diff --git a/.agents/skills/dev-guide/SKILL.md b/.agents/skills/dev-guide/SKILL.md
index e3078237d..a547cde26 100644
--- a/.agents/skills/dev-guide/SKILL.md
+++ b/.agents/skills/dev-guide/SKILL.md
@@ -16,6 +16,7 @@ description: 当前仓库开发指南。修改或排查本仓库的 Rust 网关
 | 模块职责、调用链、状态归属 | [系统架构](../../../docs/architecture.md) |
 | Rust 开发 | 加载并使用 `$rust-best-practices`，结合 [系统架构](../../../docs/architecture.md) 与 [项目约定](../../../CONTRIBUTING.md#项目约定) |
 | HTTP 路由、请求与响应、导入导出 | [API 文档](../../../docs/api.md) |
+| 开发独立网关插件 | [plugin-dev](../plugin-dev/SKILL.md)：公开 SDK、能力选择、示例、打包与验证 |
 | 前端开发、管理端组件、主题 Token、视觉验证 | 按下方「前端任务」加载设计约束，结合 [管理端主题](../../../docs/theme.md) 与 [界面验证](../../../CONTRIBUTING.md#界面验证) |
 | 常规文档更新 | [文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件)：维护当前说明，在原章节就地修订，不记录变更历史 |
 | 部署、客户端配置、备份与恢复 | [部署说明](../../../deploy/README.md) |
diff --git a/.agents/skills/plugin-dev/SKILL.md b/.agents/skills/plugin-dev/SKILL.md
new file mode 100644
index 000000000..b0534633e
--- /dev/null
+++ b/.agents/skills/plugin-dev/SKILL.md
@@ -0,0 +1,79 @@
+---
+name: plugin-dev
+description: 开发 Codex Proxy RS 网关插件，包括选择扩展能力、编写 plugin.json、实现公开 SDK 处理器、管理页面、打包与本地验证。用于新建插件、修改插件或排查插件接入；不用于 OpenAI Codex 的 .codex-plugin 插件、Vue 插件或仅修改宿主插件管理功能。
+---
+
+# Codex Proxy 插件开发
+
+面向插件作者。插件在独立项目中实现，通过公开 SDK 与宿主通信，不向宿主业务模块添加分支。
+仅修改宿主安装器、Runtime 或管理端时，使用仓库开发指南，不按本技能创建插件工程。
+
+## 先建立正确的模型
+
+```text
+选择能力 → 作者清单 + SDK 处理器 → 构建二进制／页面 → cpr-plugin package
+                                                       ↓
+实际业务验证 ← 查看权限并安装、自动准备配置 ← tar.gz + sha256
+```
+
+- `contributes` 声明提供什么，`permissions` 声明访问域；安装接受记录派生授权，`bindings` 只决定功能挂载和请求匹配
+- 安装包、运行配置和已启用功能不是同一件事；安装成功不能代替功能验证
+- `trustedProcess` 与宿主使用相同系统身份，不是操作系统沙箱
+
+## 开始工作
+
+1. 确认插件用途、已有工程／输出目录、目标宿主版本与平台。已有项目沿用其结构；没有指定工程时先确认目录，不把插件源码塞进宿主 workspace
+2. 先读 [SDK 入口](../../../backend/crates/gateway-plugin/sdk/README.md) 和[清单](../../../backend/crates/gateway-plugin/sdk/docs/manifest.md)，再按下表只选本次需要的能力章节
+3. 核对目标版本的 [SDK Cargo.toml](../../../backend/crates/gateway-plugin/sdk/Cargo.toml) 与[宿主支持清单](../../../backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json)。当前源码支持某能力，不代表较旧宿主支持；清单版本、通信版本、能力版本也不能混用
+4. 需要构建、联调或交付时读取 [构建与验证](references/development.md)，先检查实际依赖和脚本，不假设包已公开发布
+
+本技能相对链接以各文件所在目录解析；主仓根目录是本文件所在目录向上三级。插件工程或同级示例不在磁盘上时，请用户提供位置或使用选定版本的公开资料，不猜开发机绝对路径，也不自动克隆或创建远程仓库。
+
+## 按任务选择能力
+
+| 用户要做什么 | 优先使用 | 需要读取的合同 |
+| --- | --- | --- |
+| 改写请求／响应、处理流式内容、协议转换 | `middleware` | [洋葱中间件](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#洋葱中间件) |
+| 接入新的模型服务与账号 | `executor`，按需组合 `models`、`authentication`、`quota`、`account_management`、`billing`、`request_profile` | [Provider](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#provider)及 `call::provider` / `call::auth` |
+| 改变模型选择或账号排序 | `model_router` / `scheduler` | [策略类型](../../../backend/crates/gateway-plugin/sdk/src/call/policy/mod.rs)，宿主继续复验范围、资格和租约 |
+| 统计成功失败、用量或观察 WS 帧 | `request_lifecycle` / `usage` / `web_socket_observer` | [路由、调度与观察](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#路由调度与观察)，观察不改写业务结果 |
+| 接受外部客户端身份 | `frontend_authentication` | [数据面入口认证](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#数据面入口认证)，映射现有 Client Key，不接管后台登录 |
+| 增加插件页面与管理操作 | `management` | [管理页面、公开入口与 CLI](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#管理页面公开入口与-cli) |
+| 提供终端命令 | `command_line` | [管理页面、公开入口与 CLI](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#管理页面公开入口与-cli) |
+| 自动刷新凭据、额度、模型或画像资料 | `maintenance` 及对应 Provider 能力 | [Provider](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#provider)，不是任意 cron 或常驻任务入口 |
+
+只声明实现了的能力。Provider 专属能力需要注册 Provider，并具有 `executor`；普通中间件或页面不需要虚构 Provider。
+网络、账号、模型调用和私有状态属于宿主回调与授权，不重复声明为顶层能力。
+
+## 实现时的关键选择
+
+### 清单与处理器
+
+- `publisher` 与机器短名 `name` 派生插件 ID，`displayName` 用于展示；复制示例后同时调整扩展项 ID 与注册结果
+- `contributes` 每种能力最多一项，完整扩展项 ID 属于自己的插件命名空间；运行注册必须与作者清单一致
+- 作者清单用 `Manifest::from_author_slice` 规范化，不手写 `package`、固定阶段或重复注册；Provider 可用业务组简写，CLI 生成平台、协议与资源摘要，版本范围不能使用全版本通配
+- Rust 插件只依赖公开 `gateway-plugin-sdk`；需要异步会话辅助时开启 `io`，使用 `PluginSession` 管理握手、回调关联、流控、取消和关闭
+- 优先用 `PluginBuilder::from_json` 组合 `.middleware`、`.management`、`.command_line` 与 `.on(methods::..., handler)`，由构建器生成注册并检查处理器；单一中间件也可用 `MiddlewarePlugin`
+- stdout 是二进制协议通道，不能用 `println!` 输出诊断。使用基础设施 `host.log`，不输出 secret 或完整请求
+
+### 中间件与宿主服务
+
+- `request` 包裹整个逻辑请求，`attempt` 在每次选定账号的尝试中执行；根据作用范围选择，避免重试时重复副作用
+- `next` 只能消费一次。使用 SDK 的正文保留与流式映射能力，不自行拼一套 SSE／取消／流控机制；请求、响应及策略处理使用 `requests` 域
+- 持久化状态使用已声明命名空间的 `host.state.*`，账号读写使用 `host.auth.*`，不直接访问宿主数据库。见[账号与凭据](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#账号与凭据)和[状态、日志与迁移](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#状态日志与迁移)
+- 权限只声明 `network`、`models`、`accounts`、`requests`、`public_endpoints`；日志和自身状态无需授权项。安装器不配置 Key／账号白名单，资源选择属于插件业务
+- 模型、网络和亲和查询使用当前父调用的受管回调。管理／CLI 等独立入口调用模型时传明确的 Key ID；请求处理阶段继承父身份。见[Key、模型与模型调用](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#key模型与模型调用)
+- SDK 操作名不是管理员 HTTP 路由，不能据此拼接口地址；宿主身份、账单事实和调用授权也不能由插件覆盖
+
+### 只有需要页面时才创建前端
+
+- 优先参考独立示例仓库的 `examples/workbench/frontend/src/api/`：业务路由放在 `modules/`，`request.ts` 封装公开宿主桥；按需使用 `@codex-proxy/ui` 包出口，不跨仓导入宿主或 UI 的内部源码
+- Vue 页面保留 SFC，逻辑、脚本和配置使用 TypeScript；只实现业务内容，标题和副标题由 `ManagementPage` 交给宿主显示
+- 隔离页面通过 `window.codexProxyPlugin.request` 调用已注册管理路由；`models.responses` 通过普通请求链交付 JSON/SSE，支持取消且不暴露 Key 明文。不直接 `fetch` 宿主、不读取管理 Cookie 或借用宿主 Vue 实例
+- `host.model.*` 子请求跳过发起插件，不能用它证明本插件中间件／路由已参与；需要完整请求链的示例使用页面模型桥或真实客户端
+- JS、CSS、图标等资源随包构建和声明；沿用宿主桥的主题同步。Vite 本地预览不等于已安装插件的热更新，宿主验证仍需重新构建、打包和切换版本
+
+## 交付
+
+按[构建与验证](references/development.md#验证与交付)提供源码位置、能力／权限／绑定摘要、实际运行结果及验证缺口。
+开发插件不默认授权安装并启用本机进程、调用真实上游、发布依赖或推送仓库；超出当前授权时交付可安装包及操作步骤。
diff --git a/.agents/skills/plugin-dev/agents/openai.yaml b/.agents/skills/plugin-dev/agents/openai.yaml
new file mode 100644
index 000000000..44689d37b
--- /dev/null
+++ b/.agents/skills/plugin-dev/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Codex Proxy 插件开发"
+  short_description: "从能力选择到 SDK 实现、管理页面、打包与验证的插件开发指南"
+  default_prompt: "使用 $plugin-dev 为 Codex Proxy RS 开发插件，先确认需要的能力，再按公开 SDK 实现、打包并验证。"
diff --git a/.agents/skills/plugin-dev/references/development.md b/.agents/skills/plugin-dev/references/development.md
new file mode 100644
index 000000000..6a2c7dd30
--- /dev/null
+++ b/.agents/skills/plugin-dev/references/development.md
@@ -0,0 +1,98 @@
+# 构建、联调与验证
+
+仅在准备工程、构建或验证插件时读取。这里给出执行入口，不复制 SDK 协议或安装 API 的字段手册。
+
+## 工程与依赖
+
+| 位置 | 用途 |
+| --- | --- |
+| 主仓 `backend/crates/gateway-plugin/sdk/` | Rust 公开合同、会话辅助与能力文档 |
+| 主仓 `backend/apps/plugin-cli/` | `cpr-plugin package`，只校验与打包，不编译插件源码 |
+| 独立 `codex-proxy-plugins/examples/workbench/` | 基础能力体验与文本工作流示例，按需选择功能，不整体复制 |
+| 独立 `codex-proxy-ui/` | 可选的 Vue UI 库、组件文档与 playground |
+
+先检查用户给定工程，或主仓父目录下的同级仓库是否存在；读取实际仓库约定、README、`Cargo.toml`、`package.json` 与锁文件。
+只需中间件时不复制示例的管理 API、页面和相关权限；Provider、CLI 等能力从 SDK 对应合同起步，不给示例添加无关能力。
+
+本地源码联调可以使用 Cargo 路径依赖和 pnpm 的包级链接／override；路径必须真实可解析，并记录在消费方依赖配置中。
+这不等于允许从业务源码跨仓 `import .../src/...`，也不能证明第三方能独立安装。
+
+对外交付前核实 UI／SDK 的可用版本和安装来源：仅引用确实存在的发布版本，或包含所需合同的固定 Git commit；
+不要把浮动 `main` 当版本，也不要自动发布依赖以补齐条件。本地 override 尚未移除时，明确说明独立安装缺口。
+所用工具链以目标项目的配置为准，不因本机安装了更新版本而顺手升级。
+
+## 复用示例
+
+找到 `codex-proxy-plugins` 后先读根目录与 `examples/workbench/README.md`。
+该仓库使用 `bash scripts/package` 构建页面、Rust 二进制并打包；前端依赖和工具配置位于示例的 `frontend/`，根目录不维护 Node 工程。执行前核对脚本适用的插件路径和目标平台。
+
+| 任务 | 示例入口 |
+| --- | --- |
+| 身份、声明与资源 | `examples/workbench/plugin.json` |
+| 会话启动与处理器组合 | `examples/workbench/backend/src/main.rs`、`app.rs` |
+| 管理接口与 Provider | `examples/workbench/backend/src/management/`、`provider/` |
+| 页面与主题 | `examples/workbench/frontend/src/` |
+| 管理接口调用 | `examples/workbench/frontend/src/api/modules/` |
+| 包内静态资源构建 | `examples/workbench/frontend/vite.config.ts` |
+
+若派生新插件，同时修改包名、二进制名、插件身份、扩展项 ID、注册描述和构建目标，不只改展示名称。
+保留当前项目确实需要的依赖、资源和权限；不要把示例中的全请求范围直接用到共享环境。
+
+## 构建与打包
+
+先运行目标工程已有的测试和构建入口。Rust 检查示意如下，路径、工具链和 target 按实际工程替换：
+
+```bash
+cargo fmt --manifest-path /path/to/plugin/Cargo.toml -- --check
+cargo clippy --manifest-path /path/to/plugin/Cargo.toml --all-targets --all-features --locked -- -D warnings
+cargo test --manifest-path /path/to/plugin/Cargo.toml --locked
+cargo build --manifest-path /path/to/plugin/Cargo.toml --release --locked --target x86_64-unknown-linux-gnu
+```
+
+新工程尚无锁文件时先生成并检查锁文件；不要把缺少锁文件的 `--locked` 失败当作源码问题。
+有页面时另跑该前端项目的检查与生产构建，确认产物路径、资源清单和 MIME 类型相符；无页面的插件无需 Node 项目。
+
+优先使用已有 `cpr-plugin`。需要本地构建工具时，在主仓根目录运行以下命令，把 `--help` 换成实际参数即可，不必全局安装：
+
+```bash
+cargo run --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked -- package --help
+```
+
+直接打包的示意命令：
+
+```bash
+cpr-plugin package \
+  --manifest /path/to/plugin/plugin.json \
+  --binary /path/to/plugin/target/x86_64-unknown-linux-gnu/release/plugin \
+  --target x86_64-unknown-linux-gnu \
+  --resource-map web=frontend/dist \
+  --output-dir /path/to/plugin/dist
+```
+
+没有 `web` 资源时去掉 `--resource-map`。映射源相对于作者清单目录，而非命令执行目录；资源必须留在插件工程内。
+目标平台与二进制必须匹配，不能只改 target 参数伪装交叉编译。支持平台以 [CLI 文档](../../../../backend/apps/plugin-cli/README.md)及实际 `--help` 为准。
+
+输出为 `.tar.gz` 与 `.sha256`，不是源码 zip、npm 包或页面目录。归档根目录应有生成后的 `plugin.json`、可执行文件和声明资源。
+本地同版本反复试验与对外发布区分处理；发布新内容使用明确的新版本，不覆盖已发布版本。
+
+## 验证与交付
+
+按[插件使用](../../../../docs/plugins.md)验证“安装包 → 查看权限并安装 → 自动准备默认配置 → 实际使用”；只在缺少业务必填值时补配置，不添加授权或资源选择向导。
+只有获得目标环境操作授权才安装和启用；不把修改源码的授权扩展到生产实例或真实凭据操作。
+需要 API 自动化时查[插件管理 API](../../../../docs/api.md#12-插件管理)，不要依据记忆拼路由。
+
+按实际实现选择验证，不为不存在的能力增加测试任务：
+
+| 实现范围 | 应验证的行为 |
+| --- | --- |
+| 中间件 | 匹配／不匹配范围、授权不足、下游错误与取消；支持流式时检查多帧、终态和断开；若涉及续链，使用真实目标客户端检查 HTTP/SSE、WS 及后续轮次 |
+| Provider | 导入或登录、模型发现、实际执行、错误及用量；仅对声明支持的协议、资料、额度等操作验收 |
+| 管理页面 | 从宿主打开，标题／副标题、明暗主题、加载与错误状态；管理桥请求成功；停用或版本切换后旧入口失效 |
+| 入口认证／CLI／维护 | 对应身份和账号范围、缺少授权、取消与错误；不把帮助输出、注册成功或一次健康探测当完整验收 |
+| 持久状态或升级 | 读写版本冲突、升级兼容性、迁移失败与停用边界；不覆盖并发配置或把回滚版本误当恢复历史数据 |
+
+真实请求按用户选择的客户端、模型和测试预算执行；没有这些能力或授权时列为缺口，不模拟成功。
+临时账号、Key 或配置只在明确的测试范围内创建，记录并清理自己创建的对象，不输出密钥、原始请求或插件 secret。
+
+交付简述：源码与产物位置、兼容范围、所需能力／权限／绑定、执行过的命令及结果、尚未验证的场景。
+只有确实生成了产物才报告“已打包”，只有目标环境业务验证成功才报告“已生效”；提交、推送与发布按用户授权另行执行。
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 63f699982..82e184a78 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -1,8 +1,10 @@
 version: 2
 
+# 标签由维护者手动添加，各生态关闭默认打标，避免重新创建旧标签。
 updates:
   - package-ecosystem: github-actions
     directory: /
+    labels: []
     schedule:
       interval: weekly
       day: monday
@@ -16,6 +18,7 @@ updates:
 
   - package-ecosystem: cargo
     directory: /backend
+    labels: []
     schedule:
       interval: weekly
       day: monday
@@ -49,7 +52,8 @@ updates:
           - patch
 
   - package-ecosystem: npm
-    directory: /frontend
+    directory: /
+    labels: []
     schedule:
       interval: weekly
       day: monday
@@ -65,6 +69,7 @@ updates:
 
   - package-ecosystem: docker
     directory: /deploy
+    labels: []
     schedule:
       interval: weekly
       day: monday
diff --git a/.github/workflows/_quality.yml b/.github/workflows/_quality.yml
index abd4963ce..3385f89eb 100644
--- a/.github/workflows/_quality.yml
+++ b/.github/workflows/_quality.yml
@@ -161,7 +161,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
         with:
-          version: 11.7.0
+          package_json_file: frontend/package.json
 
       - name: Setup Node
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c52c38c4d..616fd73e8 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -318,6 +318,7 @@ jobs:
         env:
           VERSION: ${{ needs.release-info.outputs.version }}
           DOCKER_VERSION: ${{ needs.release-info.outputs.docker_version }}
+          GIT_SHA: ${{ needs.release-info.outputs.git_sha }}
         run: |
           set -euo pipefail
           ruby <<'RUBY' > release-platforms.json
@@ -364,6 +365,8 @@ jobs:
           compose = compose.replace(default_image, versioned_image)
           (release_dir / "compose.yaml").write_text(compose)
           assets = [release_dir / config_template.name, release_dir / "compose.yaml"]
+          shutil.rmtree(package_dir, ignore_errors=True)
+          release_packages = []
 
           for platform in platforms:
               platform_name = f"{platform['os']}-{platform['arch']}"
@@ -372,8 +375,7 @@ jobs:
               if not binary_src.is_file():
                   raise SystemExit(f"Missing binary artifact: {binary_src}")
 
-              shutil.rmtree(package_dir, ignore_errors=True)
-              package_root = package_dir / APP_NAME
+              package_root = package_dir / platform_name / APP_NAME
               web_dist = package_root / "web" / "dist"
               web_dist.mkdir(parents=True)
 
@@ -387,11 +389,37 @@ jobs:
 
               archive_name = f"{APP_NAME}_{version}_{platform['os']}_{platform['arch']}.{platform['archive']}"
               archive_path = release_dir / archive_name
-              if platform["archive"] == "tar.gz":
-                  with tarfile.open(archive_path, "w:gz") as archive:
-                      archive.add(package_root, arcname=APP_NAME)
-              else:
+              if platform["archive"] != "tar.gz":
                   raise SystemExit(f"Unsupported archive format: {platform['archive']}")
+              release_packages.append((platform, package_root, archive_path))
+
+          plugin_host_path = pathlib.Path("backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json")
+          plugin_host = json.loads(plugin_host_path.read_text())
+          if plugin_host.get("schema_version") != 1:
+              raise SystemExit(f"Invalid plugin host compatibility declaration: {plugin_host_path}")
+
+          plugin_manifest_path = release_dir / "plugin-release-manifest.json"
+          plugin_manifest_path.write_text(json.dumps({
+              "schema_version": 1,
+              "sealed": True,
+              "gateway_version": version,
+              "gateway_git_sha": os.environ["GIT_SHA"],
+              "plugin_host": plugin_host,
+              # 示例独立发版；当前不内置插件，仍保留更新与回滚所需的封口清单。
+              "plugins": [],
+          }, indent=2, sort_keys=True) + "\n")
+          assets.append(plugin_manifest_path)
+
+          # 保留运行时清单目录合同，宿主包不再携带教学示例。
+          for platform, package_root, archive_path in release_packages:
+              official_dir = package_root / "plugins" / "official"
+              official_dir.mkdir(parents=True)
+              bundled_manifest = official_dir / plugin_manifest_path.name
+              shutil.copy2(plugin_manifest_path, bundled_manifest)
+              bundled_manifest.chmod(0o444)
+              official_dir.chmod(0o555)
+              with tarfile.open(archive_path, "w:gz") as archive:
+                  archive.add(package_root, arcname=APP_NAME)
               assets.append(archive_path)
 
           checksum_path = release_dir / "checksums.txt"
@@ -415,7 +443,7 @@ jobs:
 
   build-docker-image:
     name: build-docker-image (${{ matrix.dockerPlatform }})
-    needs: [release-info, quality, build-docker-binary]
+    needs: [release-info, quality, build-docker-binary, package-assets]
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.release-info.outputs.docker_matrix) }}
@@ -448,6 +476,12 @@ jobs:
           name: codex-proxy-rs-${{ matrix.os }}-${{ matrix.arch }}
           path: dist/docker-artifacts/codex-proxy-rs-${{ matrix.os }}-${{ matrix.arch }}
 
+      - name: Download sealed release assets
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-assets
+          path: dist/release-assets
+
       - name: Prepare Docker prebuilt assets
         shell: bash
         env:
@@ -457,6 +491,7 @@ jobs:
         run: |
           set -euo pipefail
           python3 - <<'PY'
+          import json
           import shutil
           import os
           import pathlib
@@ -472,6 +507,36 @@ jobs:
           binary_dest = target_dir / app_name
           shutil.copy2(binary_src, binary_dest)
           binary_dest.chmod(0o755)
+
+          release_dir = pathlib.Path("dist/release-assets")
+          manifest_path = release_dir / "plugin-release-manifest.json"
+          manifest = json.loads(manifest_path.read_text())
+          if manifest.get("schema_version") != 1 or manifest.get("sealed") is not True:
+              raise SystemExit("Invalid sealed plugin release manifest")
+          official_dir = target_dir / "plugins" / "official"
+          official_dir.mkdir(parents=True)
+          bundled_manifest = official_dir / manifest_path.name
+          shutil.copy2(manifest_path, bundled_manifest)
+          bundled_manifest.chmod(0o444)
+          selected = 0
+          for plugin in manifest.get("plugins", []):
+              artifacts = [
+                  artifact for artifact in plugin.get("artifacts", [])
+                  if artifact.get("release_os") == os.environ["MATRIX_OS"]
+                  and artifact.get("release_architecture") == os.environ["MATRIX_ARCH"]
+              ]
+              if len(artifacts) != 1:
+                  raise SystemExit(f"Official plugin platform selection is not unique: {plugin.get('id')}")
+              archive = release_dir / artifacts[0]["archive"]
+              if not archive.is_file():
+                  raise SystemExit(f"Missing official plugin archive: {archive.name}")
+              bundled_archive = official_dir / archive.name
+              shutil.copy2(archive, bundled_archive)
+              bundled_archive.chmod(0o444)
+              selected += 1
+          if selected != len(manifest.get("plugins", [])):
+              raise SystemExit("Official plugin release bundle is incomplete")
+          official_dir.chmod(0o555)
           PY
 
       - name: Setup Docker Buildx
@@ -684,6 +749,9 @@ jobs:
             **手动下载：**
             请从下方附件中下载适合当前平台的归档包。
 
+            附件包含与当前宿主版本及提交绑定的 `plugin-release-manifest.json`，当前没有默认内置插件。
+            教学示例由独立的 `codex-proxy-plugins` 仓库维护和发布，不随宿主发行物分发。
+
             发布归档提供 GitHub 构建产物证明。Docker 镜像附带软件物料清单（SBOM）、构建来源证明和 cosign 无密钥签名。
 
             ## 📚 文档
diff --git a/.github/workflows/security-scan.yml b/.github/workflows/security-scan.yml
index 44486fc12..acc317558 100644
--- a/.github/workflows/security-scan.yml
+++ b/.github/workflows/security-scan.yml
@@ -38,9 +38,9 @@ jobs:
       - name: Install cargo-audit
         run: cargo install cargo-audit --version 0.22.2 --locked
 
-      - name: Run cargo audit
-        working-directory: backend
-        run: cargo audit
+      - name: Run Cargo audits
+        run: |
+          cargo audit --file backend/Cargo.lock
 
   frontend-security:
     runs-on: ubuntu-latest
@@ -54,7 +54,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
         with:
-          version: 11.7.0
+          package_json_file: frontend/package.json
 
       - name: Setup Node
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
diff --git a/.gitignore b/.gitignore
index ea196bb17..58d9bc8e9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,8 +7,8 @@
 /frontend/node_modules/
 /frontend/dist/
 /frontend/.vite/
-/.pnpm-store/
 /frontend/.pnpm-store/
+/frontend/.pnpm-cache/
 *.tsbuildinfo
 
 # Release artifacts
@@ -20,6 +20,9 @@
 
 # Local configuration and secrets
 /deploy/config.yaml
+.env
+.env.*
+!.env.example
 
 # Editors and operating systems
 /.idea/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8e3f77720..cddffb5ba 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -45,6 +45,7 @@ AI 开发和审查入口是根目录的 [AGENTS.md](AGENTS.md)。在仓库上下
 | 技能 | 用途 | 调用示例 |
 | --- | --- | --- |
 | [dev-guide](.agents/skills/dev-guide/SKILL.md) | 项目开发与文档导航 | `$dev-guide 修复当前问题` |
+| [plugin-dev](.agents/skills/plugin-dev/SKILL.md) | 网关插件开发、打包与验证 | `$plugin-dev 开发一个添加响应头的插件` |
 | [github-pr](.agents/skills/github-pr/SKILL.md) | 创建或审查 PR | `$github-pr 创建当前分支的 PR` / `$github-pr 审查 PR #编号` |
 | [github-issue](.agents/skills/github-issue/SKILL.md) | 整理或提交 Issue | `$github-issue 提交当前问题` |
 | [release](.agents/skills/release/SKILL.md) | 准备发布说明或正式发版 | `$release 整理本次发布说明` / `$release 发布 vX.Y.Z` |
@@ -111,7 +112,7 @@ PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或
 
 AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方案以本项目的用户任务、[管理端主题](docs/theme.md) 和已有组件为依据，在任务范围内改进布局、视觉与交互。
 
-开发前查找同类页面及 `components/base` 中的基础组件，优先使用已有主题 Token、交互和数据展示逻辑。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题。
+开发前查找同类页面及同级 `codex-proxy-ui/src/components` 中的基础组件，优先使用已有主题 Token、交互和数据展示逻辑。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题。
 
 列表列宽、序号、按钮、分页和弹窗尺寸由实际任务与数据规模决定，以同类页面为参照。新增或调整交互时说明用户需要完成什么操作，不把某个页面的取舍推广成全局禁令。
 
@@ -131,6 +132,16 @@ AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方
 | 依赖安全 | Cargo Audit、pnpm Audit | 本次变更的权限、数据与信任边界 |
 | 工作流与容器 | Actionlint、相关容器检查 | 改动涉及的运行行为 |
 
+UI 与示例源码分别在独立的 `codex-proxy-ui`、`codex-proxy-plugins` 仓库维护。前端的依赖、锁文件和 ESLint 配置均在 `frontend/` 管理，仓库根目录不维护 Node 包。UI 使用固定 GitHub 标签依赖，锁文件记录实际提交、源码归档地址及完整性摘要，常规开发和 CI 不需要检出同级仓库。安装时 pnpm 按 UI 自身锁文件准备构建依赖，再执行 `prepack` 生成 JS、CSS 和类型声明。开发服务通过 UI 包的 `development` 入口使用 Vue SFC，生产构建使用 `dist`。
+
+pnpm 版本由 `frontend/package.json` 的 `packageManager` 固定，CI 和 Docker 从该字段读取。`frontend/pnpm-workspace.yaml` 的 `allowBuilds` 按仓库放行自有 UI 包的构建脚本；升级标签时核对源码并更新锁文件，无需逐次修改构建许可，不开放全部依赖脚本。
+
+```bash
+pnpm --dir frontend install --frozen-lockfile
+```
+
+需要修改组件库时，按 [UI 源码联调指南](https://github.com/zyycn/codex-proxy-ui/blob/main/playground/guide/development.md) 建立临时本地链接；提交前恢复发布依赖并核对锁文件，不能将开发机目录写入发行依赖。独立插件的 SDK 固定到包含所需合同的 Git 提交，不依赖浮动分支。
+
 前端从仓库根目录执行：
 
 ```bash
diff --git a/README.md b/README.md
index 4d8dffeab..6ca37288a 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,16 @@
 > [!NOTE]
 > 本项目提供 Responses API，不支持 `/v1/chat/completions`，接入前请确认客户端支持 Responses 协议
 
+## 功能
+
+| 场景 | 能力 |
+| --- | --- |
+| 客户端接入 | Responses HTTP / SSE / WebSocket、Images、模型目录与 standalone Search |
+| 多账号与路由 | OpenAI、xAI 及插件 Provider，账号分组、模型范围、出站代理与安全重试 |
+| 使用与管理 | 管理端、Key 自助用量页、费用限额、请求记录与错误诊断 |
+| 插件扩展 | 制品访问域确认、自动默认配置，中间件、管理页面和其他声明能力 |
+| 运维 | 单副本部署，PostgreSQL / Redis、S3/R2 备份与同一大版本内在线更新 |
+
 ## 快速预览
 
 无需部署，打开 [快速预览服务](https://codex-proxy-rs.ainz.cc) 即可体验管理端的系统概览、账号分组、代理管理与用量统计
@@ -99,7 +109,7 @@ API Key 持有者可在同一登录页切换登录身份，进入 `/key-usage` 
 | Base URL | `http://127.0.0.1:8080/v1`；远程接入使用服务器的 HTTPS 地址 |
 | API Key | 管理端创建的客户端密钥 |
 
-可用模型以该密钥查询到的模型列表为准：
+查询该密钥可见的模型目录：
 
 ```bash
 curl http://127.0.0.1:8080/v1/models \
@@ -108,14 +118,13 @@ curl http://127.0.0.1:8080/v1/models \
 
 ## 文档
 
-- [客户端接入与生图](deploy/README.md#客户端配置)
-- [部署、备份与恢复](deploy/README.md)
-- [API 参考](docs/api.md)
-- [模型定价与手动同步](docs/api.md#模型定价)
-- [系统架构](docs/architecture.md)
-- [管理端主题](docs/theme.md)
-- [数据库迁移](backend/migrations/README.md)
-- [贡献与审查](CONTRIBUTING.md)
+| 任务 | 文档 |
+| --- | --- |
+| 部署与使用 | [部署、备份与恢复](deploy/README.md) · [客户端接入与生图](deploy/README.md#客户端配置) |
+| 接口集成 | [API 参考](docs/api.md) · [模型定价](docs/api.md#模型定价) |
+| 使用插件 | [安装、配置与使用](docs/plugins.md) |
+| 开发插件 | [SDK 与合同](backend/crates/gateway-plugin/sdk/README.md) · [打包工具](backend/apps/plugin-cli/README.md) |
+| 开发宿主 | [贡献与验证](CONTRIBUTING.md) · [系统架构](docs/architecture.md) · [管理端主题](docs/theme.md) · [数据库迁移](backend/migrations/README.md) |
 
 ## 社区
 
diff --git a/backend/Cargo.lock b/backend/Cargo.lock
index d6574065f..9ffdc73f9 100644
--- a/backend/Cargo.lock
+++ b/backend/Cargo.lock
@@ -8,6 +8,20 @@ version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
 
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "getrandom 0.3.4",
+ "once_cell",
+ "serde",
+ "version_check",
+ "zerocopy",
+]
+
 [[package]]
 name = "aho-corasick"
 version = "1.1.4"
@@ -32,6 +46,56 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "arc-swap"
 version = "1.9.2"
@@ -588,6 +652,21 @@ version = "1.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 
+[[package]]
+name = "bit-set"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3"
+dependencies = [
+ "bit-vec",
+]
+
+[[package]]
+name = "bit-vec"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7"
+
 [[package]]
 name = "bitflags"
 version = "2.13.0"
@@ -624,18 +703,42 @@ dependencies = [
  "hybrid-array",
 ]
 
+[[package]]
+name = "borrow-or-share"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc0b364ead1874514c8c2855ab558056ebfeb775653e7ae45ff72f28f8f3166c"
+
 [[package]]
 name = "bumpalo"
 version = "3.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
+[[package]]
+name = "bytecount"
+version = "0.6.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "175812e0be2bccb6abe50bb8d566126198344f707e304f45c648fd8f2cc0365e"
+
+[[package]]
+name = "bytemuck"
+version = "1.25.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
+
 [[package]]
 name = "byteorder"
 version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
 [[package]]
 name = "bytes"
 version = "1.12.1"
@@ -712,6 +815,46 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "clap"
+version = "4.6.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa8876b300ab35ba921adea3dfd70157a46249b33f95c9084ae5709785478946"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec0797fb7aeb1406c84efac526901f7ec3ead2124f946b494e72879d4b54704d"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9c751b79415d4e559e3d1fcf128e09e720eb673a06d26cf6f392d37d75b66e0"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c133bc6a41be0d194c306b5506d15e6feeea7b1d6604bd3f8310dfb2ca96486"
+
 [[package]]
 name = "cmake"
 version = "0.1.58"
@@ -727,6 +870,21 @@ version = "0.5.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a"
 
+[[package]]
+name = "codex-proxy-plugin-cli"
+version = "0.1.0"
+dependencies = [
+ "clap",
+ "flate2",
+ "gateway-plugin-sdk",
+ "hex",
+ "serde_json",
+ "sha2 0.11.0",
+ "tar",
+ "tempfile",
+ "thiserror",
+]
+
 [[package]]
 name = "codex-proxy-rs"
 version = "0.0.0"
@@ -736,6 +894,7 @@ dependencies = [
  "gateway-api",
  "gateway-core",
  "gateway-host",
+ "gateway-plugin-runtime",
  "gateway-store",
  "provider-openai",
  "provider-xai",
@@ -748,6 +907,18 @@ dependencies = [
  "tokio-rustls",
 ]
 
+[[package]]
+name = "color_quant"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
+
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
 [[package]]
 name = "combine"
 version = "4.6.8"
@@ -1181,6 +1352,15 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "email_address"
+version = "0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e079f19b08ca6239f47f8ba8509c11cf3ea30095831f7fed61441475edd8c449"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "encoding_rs"
 version = "0.8.35"
@@ -1236,12 +1416,32 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "fancy-regex"
+version = "0.19.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d301f5bf187b3c295fce6468d3875037a0bccc5f6b151c63cac2f85babf21912"
+dependencies = [
+ "bit-set",
+ "regex-automata",
+ "regex-syntax",
+]
+
 [[package]]
 name = "fastrand"
 version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
 [[package]]
 name = "ff"
 version = "0.14.0"
@@ -1275,10 +1475,21 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
 dependencies = [
  "crc32fast",
- "miniz_oxide",
+ "miniz_oxide 0.9.1",
  "zlib-rs",
 ]
 
+[[package]]
+name = "fluent-uri"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc74ac4d8359ae70623506d512209619e5cf8f347124910440dbc221714b328e"
+dependencies = [
+ "borrow-or-share",
+ "ref-cast",
+ "serde",
+]
+
 [[package]]
 name = "flume"
 version = "0.12.0"
@@ -1326,6 +1537,16 @@ dependencies = [
  "percent-encoding",
 ]
 
+[[package]]
+name = "fraction"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e246562084dde8ebbcc943b261c406ce4f68e5032ec28029a251a47d6a295500"
+dependencies = [
+ "num",
+ "num-bigint",
+]
+
 [[package]]
 name = "fs2"
 version = "0.4.3"
@@ -1464,6 +1685,7 @@ dependencies = [
  "hex",
  "rand_core 0.6.4",
  "secrecy",
+ "semver",
  "serde",
  "serde_json",
  "sha2 0.11.0",
@@ -1489,6 +1711,7 @@ dependencies = [
  "gateway-admin",
  "gateway-core",
  "gateway-protocol",
+ "headers",
  "secrecy",
  "serde",
  "serde_json",
@@ -1530,6 +1753,8 @@ version = "0.0.0"
 dependencies = [
  "async-trait",
  "axum",
+ "base64 0.23.1",
+ "bytes",
  "chrono",
  "config",
  "filetime",
@@ -1538,8 +1763,18 @@ dependencies = [
  "gateway-admin",
  "gateway-core",
  "hex",
+ "http 1.4.0",
+ "http-body-util",
+ "hyper",
+ "hyper-rustls",
+ "hyper-util",
+ "ipnet",
+ "percent-encoding",
  "reqwest",
+ "rustls",
+ "rustls-native-certs",
  "scraper",
+ "secrecy",
  "semver",
  "serde",
  "serde_ignored",
@@ -1549,12 +1784,61 @@ dependencies = [
  "tempfile",
  "thiserror",
  "tokio",
+ "tokio-rustls",
+ "tower-service",
  "tracing",
  "tracing-appender",
  "tracing-subscriber",
  "wiremock",
 ]
 
+[[package]]
+name = "gateway-plugin-runtime"
+version = "0.0.0"
+dependencies = [
+ "async-trait",
+ "base64 0.23.1",
+ "bytes",
+ "chrono",
+ "flate2",
+ "futures",
+ "gateway-admin",
+ "gateway-core",
+ "gateway-host",
+ "gateway-plugin-sdk",
+ "gateway-protocol",
+ "gateway-store",
+ "hex",
+ "image",
+ "jsonschema",
+ "roxmltree",
+ "secrecy",
+ "semver",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "sqlx",
+ "tar",
+ "tempfile",
+ "thiserror",
+ "tokio",
+ "tracing",
+ "url",
+ "uuid",
+ "wiremock",
+]
+
+[[package]]
+name = "gateway-plugin-sdk"
+version = "0.4.0"
+dependencies = [
+ "semver",
+ "serde",
+ "serde_json",
+ "thiserror",
+ "tokio",
+]
+
 [[package]]
 name = "gateway-protocol"
 version = "0.0.0"
@@ -1634,9 +1918,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
 dependencies = [
  "cfg-if",
+ "js-sys",
  "libc",
  "r-efi 5.3.0",
  "wasip2",
+ "wasm-bindgen",
 ]
 
 [[package]]
@@ -1653,6 +1939,16 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "gif"
+version = "0.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee8cfcc411d9adbbaba82fb72661cc1bcca13e8bba98b364e62b2dba8f960159"
+dependencies = [
+ "color_quant",
+ "weezl",
+]
+
 [[package]]
 name = "group"
 version = "0.14.0"
@@ -2075,6 +2371,34 @@ dependencies = [
  "icu_properties",
 ]
 
+[[package]]
+name = "image"
+version = "0.25.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "color_quant",
+ "gif",
+ "image-webp",
+ "moxcms",
+ "num-traits",
+ "png",
+ "zune-core",
+ "zune-jpeg",
+]
+
+[[package]]
+name = "image-webp"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3"
+dependencies = [
+ "byteorder-lite",
+ "quick-error",
+]
+
 [[package]]
 name = "indexmap"
 version = "2.14.0"
@@ -2091,6 +2415,12 @@ version = "2.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
 
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
 [[package]]
 name = "itoa"
 version = "1.0.18"
@@ -2118,6 +2448,59 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "jsonschema"
+version = "0.56.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6a806f80c1f5560431009ce5ec29b59d38f950e0cd7db5f1b8925e6d8104e21"
+dependencies = [
+ "ahash",
+ "bytecount",
+ "data-encoding",
+ "email_address",
+ "fancy-regex",
+ "fraction",
+ "getrandom 0.3.4",
+ "itoa",
+ "jsonschema-regex",
+ "jsonschema-value",
+ "num-cmp",
+ "num-traits",
+ "percent-encoding",
+ "referencing",
+ "regex",
+ "serde",
+ "serde_json",
+ "strum",
+ "unicode-general-category",
+ "uuid-simd",
+]
+
+[[package]]
+name = "jsonschema-regex"
+version = "0.56.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb862addfa7782108933abcf842fe25334523a9df5b89ea4d9620e3dd7b42181"
+dependencies = [
+ "regex-syntax",
+]
+
+[[package]]
+name = "jsonschema-value"
+version = "0.56.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a05cd404c5ff6e2731dbbf7e290a27417750acfb59e329560a1d0af384c93fb0"
+dependencies = [
+ "ahash",
+ "bytecount",
+ "fraction",
+ "getrandom 0.3.4",
+ "num-cmp",
+ "num-traits",
+ "serde_json",
+ "zmij",
+]
+
 [[package]]
 name = "jsonwebtoken"
 version = "11.1.0"
@@ -2257,6 +2640,12 @@ version = "2.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 
+[[package]]
+name = "micromap"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a86d3146ed3995b5913c414f6664344b9617457320782e64f0bb44afd49d74"
+
 [[package]]
 name = "mime"
 version = "0.3.17"
@@ -2273,6 +2662,16 @@ dependencies = [
  "unicase",
 ]
 
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
 [[package]]
 name = "miniz_oxide"
 version = "0.9.1"
@@ -2294,6 +2693,16 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "moxcms"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b"
+dependencies = [
+ "num-traits",
+ "pxfm",
+]
+
 [[package]]
 name = "native-tls"
 version = "0.2.14"
@@ -2326,6 +2735,45 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "num"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "35bd024e8b2ff75562e5f34e7f4905839deb4b22955ef5e73d2fea1b9813cb23"
+dependencies = [
+ "num-bigint",
+ "num-complex",
+ "num-integer",
+ "num-iter",
+ "num-rational",
+ "num-traits",
+]
+
+[[package]]
+name = "num-bigint"
+version = "0.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c89e69e7e0f03bea5ef08013795c25018e101932225a656383bd384495ecc367"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "num-cmp"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63335b2e2c34fae2fb0aa2cecfd9f0832a1e24b3b32ecec612c3426d46dc8aaa"
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "num-conv"
 version = "0.2.2"
@@ -2341,6 +2789,27 @@ dependencies = [
  "num-traits",
 ]
 
+[[package]]
+name = "num-iter"
+version = "0.1.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c92800bd69a1eac91786bcfe9da64a897eb72911b8dc3095decbd07429e8048b"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "num-rational"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824"
+dependencies = [
+ "num-bigint",
+ "num-integer",
+ "num-traits",
+]
+
 [[package]]
 name = "num-traits"
 version = "0.2.19"
@@ -2366,6 +2835,12 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
 [[package]]
 name = "openssl"
 version = "0.10.75"
@@ -2657,6 +3132,19 @@ version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
 
+[[package]]
+name = "png"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
+dependencies = [
+ "bitflags",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide 0.8.9",
+]
+
 [[package]]
 name = "potential_utf"
 version = "0.1.5"
@@ -2825,6 +3313,18 @@ dependencies = [
  "psl-types",
 ]
 
+[[package]]
+name = "pxfm"
+version = "0.1.30"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
+
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
 [[package]]
 name = "quinn"
 version = "0.11.11"
@@ -3011,6 +3511,43 @@ dependencies = [
  "bitflags",
 ]
 
+[[package]]
+name = "ref-cast"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e440fb4e4b4147295338efb76001ab9e4efc0e5839df2c47fc5ac2381d365c3"
+dependencies = [
+ "ref-cast-impl",
+]
+
+[[package]]
+name = "ref-cast-impl"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "referencing"
+version = "0.56.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3b4a92fac7e28c27de3ad26df2ecb9e652f227b258e845af034052e5b22c96c"
+dependencies = [
+ "ahash",
+ "fluent-uri",
+ "getrandom 0.3.4",
+ "hashbrown 0.17.1",
+ "itoa",
+ "micromap",
+ "parking_lot",
+ "percent-encoding",
+ "serde_json",
+]
+
 [[package]]
 name = "regex"
 version = "1.13.0"
@@ -3025,9 +3562,9 @@ dependencies = [
 
 [[package]]
 name = "regex-automata"
-version = "0.4.15"
+version = "0.4.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1f388202e4b80542a0921078cc23b6333bcf1409c1e3f86404cae4766a6131db"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -3332,6 +3869,10 @@ name = "semver"
 version = "1.0.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+dependencies = [
+ "serde",
+ "serde_core",
+]
 
 [[package]]
 name = "serde"
@@ -3632,6 +4173,7 @@ dependencies = [
  "tokio-stream",
  "tracing",
  "url",
+ "uuid",
  "webpki-roots",
 ]
 
@@ -3699,6 +4241,7 @@ dependencies = [
  "sqlx-core",
  "thiserror",
  "tracing",
+ "uuid",
 ]
 
 [[package]]
@@ -3734,6 +4277,7 @@ dependencies = [
  "stringprep",
  "thiserror",
  "tracing",
+ "uuid",
  "whoami",
 ]
 
@@ -3760,6 +4304,7 @@ dependencies = [
  "thiserror",
  "tracing",
  "url",
+ "uuid",
 ]
 
 [[package]]
@@ -3803,6 +4348,33 @@ dependencies = [
  "unicode-properties",
 ]
 
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "strum"
+version = "0.28.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9628de9b8791db39ceda2b119bbe13134770b56c138ec1d3af810d045c04f9bd"
+dependencies = [
+ "strum_macros",
+]
+
+[[package]]
+name = "strum_macros"
+version = "0.28.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab85eea0270ee17587ed4156089e10b9e6880ee688791d45a905f5b1ca36f664"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
 [[package]]
 name = "subtle"
 version = "2.6.1"
@@ -4321,6 +4893,12 @@ version = "0.3.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5c1cb5db39152898a79168971543b1cb5020dff7fe43c8dc468b0885f5e29df5"
 
+[[package]]
+name = "unicode-general-category"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b993bddc193ae5bd0d623b49ec06ac3e9312875fdae725a975c51db1cc1677f"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
@@ -4384,6 +4962,12 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
 [[package]]
 name = "uuid"
 version = "1.26.1"
@@ -4395,6 +4979,16 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "uuid-simd"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b082222b4f6619906941c17eb2297fff4c2fb96cb60164170522942a200bd8"
+dependencies = [
+ "outref",
+ "vsimd",
+]
+
 [[package]]
 name = "valuable"
 version = "0.1.1"
@@ -4552,6 +5146,12 @@ dependencies = [
  "rustls-pki-types",
 ]
 
+[[package]]
+name = "weezl"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88"
+
 [[package]]
 name = "whoami"
 version = "2.1.2"
@@ -4976,9 +5576,9 @@ checksum = "b142a20ec14a91d5bc708c1dc21b080c550113d8aa77afa29635673a65dd02c5"
 
 [[package]]
 name = "zmij"
-version = "1.0.21"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
 
 [[package]]
 name = "zstd"
@@ -5007,3 +5607,18 @@ dependencies = [
  "cc",
  "pkg-config",
 ]
+
+[[package]]
+name = "zune-core"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d56377fd46368984a170bc5aac5567e52ca5da874caa60bea39fcbca78fb658b"
+
+[[package]]
+name = "zune-jpeg"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296"
+dependencies = [
+ "zune-core",
+]
diff --git a/backend/Cargo.toml b/backend/Cargo.toml
index ce26929a5..c064e78ef 100644
--- a/backend/Cargo.toml
+++ b/backend/Cargo.toml
@@ -1,10 +1,13 @@
 [workspace]
 members = [
     "apps/gateway",
+    "apps/plugin-cli",
     "crates/gateway-admin",
     "crates/gateway-api",
     "crates/gateway-core",
     "crates/gateway-host",
+    "crates/gateway-plugin/runtime",
+    "crates/gateway-plugin/sdk",
     "crates/gateway-protocol",
     "crates/gateway-store",
     "crates/providers/openai",
diff --git a/backend/apps/gateway/Cargo.toml b/backend/apps/gateway/Cargo.toml
index fdfca651c..305e739e3 100644
--- a/backend/apps/gateway/Cargo.toml
+++ b/backend/apps/gateway/Cargo.toml
@@ -16,6 +16,7 @@ gateway-admin = { path = "../../crates/gateway-admin" }
 gateway-api = { path = "../../crates/gateway-api" }
 gateway-core = { path = "../../crates/gateway-core" }
 gateway-host = { path = "../../crates/gateway-host" }
+gateway-plugin-runtime = { path = "../../crates/gateway-plugin/runtime" }
 gateway-store = { path = "../../crates/gateway-store" }
 provider-openai = { path = "../../crates/providers/openai" }
 provider-xai = { path = "../../crates/providers/xai" }
diff --git a/backend/apps/gateway/src/bootstrap.rs b/backend/apps/gateway/src/bootstrap.rs
index 5bd39b8d4..133119cec 100644
--- a/backend/apps/gateway/src/bootstrap.rs
+++ b/backend/apps/gateway/src/bootstrap.rs
@@ -52,6 +52,47 @@ impl LoadableConfig for GatewayConfig {
 
 /// 按冻结顺序初始化全部 Bundle，并把进程阻塞权交给 Host。
 pub async fn run() -> Result<(), BootstrapError> {
+    launch(None).await.map(|_| ())
+}
+
+/// 这里只接收插件命名空间内的参数，不转交宿主配置或其他启动 secret。
+pub struct PluginCommand {
+    pub instance_id: Option<String>,
+    pub name: Option<String>,
+    pub arguments: Vec<String>,
+}
+
+impl PluginCommand {
+    fn is_help(&self) -> bool {
+        self.name.is_none()
+            || self
+                .arguments
+                .iter()
+                .any(|value| matches!(value.as_str(), "--help" | "-h"))
+    }
+}
+
+pub async fn plugin_command(
+    command: PluginCommand,
+) -> Result<gateway_plugin_runtime::PluginCommandOutput, BootstrapError> {
+    launch(Some(command)).await
+}
+
+async fn launch(
+    command: Option<PluginCommand>,
+) -> Result<gateway_plugin_runtime::PluginCommandOutput, BootstrapError> {
+    macro_rules! or_shutdown {
+        ($runtime:expr, $result:expr) => {
+            match $result {
+                Ok(value) => value,
+                Err(error) => {
+                    $runtime.shutdown().await;
+                    return Err(error.into());
+                }
+            }
+        };
+    }
+
     let config = gateway_host::load_config::<GatewayConfig>()?;
     let GatewayConfig {
         schema_version: _,
@@ -63,47 +104,234 @@ pub async fn run() -> Result<(), BootstrapError> {
         openai,
     } = config;
 
-    let host = gateway_host::initialize(host).await?;
+    let plugin_cache = host.runtime_data_dir().join("plugins");
+    let host = if command.is_some() {
+        gateway_host::initialize_command_line(host).await?
+    } else {
+        gateway_host::initialize(host).await?
+    };
     host.report_startup_ready("Host");
-    let mut store = gateway_store::initialize(store).await?;
+    let help = command.as_ref().is_some_and(PluginCommand::is_help);
+    let mut store = if help {
+        gateway_store::initialize_read_only(store).await?
+    } else if command.is_some() {
+        gateway_store::initialize_command_line(store).await?
+    } else {
+        gateway_store::initialize(store).await?
+    };
     host.report_startup_ready("Store");
+    let version = host
+        .system_operations()
+        .version()
+        .await
+        .map_err(|_| ConfigError::InvalidField("host.version"))?
+        .version;
+    let plugin_http = std::sync::Arc::new(gateway_host::outbound::HttpClient::new()?);
+    if let Some(command) = command.as_ref().filter(|_| help) {
+        // 帮助在原生 Provider 初始化前返回，避免写默认画像、发现模型或初始化管理员。
+        let runtime = prepare_plugins(
+            &store,
+            plugin_cache,
+            &version,
+            ProviderRegistry::default(),
+            gateway_admin::ports::provider::ProviderAdminRegistry::new([])
+                .map_err(|_| gateway_admin::model::AdminError::invalid("Provider 管理身份冲突"))?,
+            plugin_http.clone(),
+        )?;
+        let commands = or_shutdown!(runtime, runtime.prepare_command_line().await);
+        let stdout = commands.help(command.instance_id.as_deref(), command.name.as_deref());
+        commands.shutdown().await;
+        runtime.shutdown().await;
+        return Ok(gateway_plugin_runtime::PluginCommandOutput {
+            stdout: stdout?,
+            stderr: String::new(),
+            exit_code: 0,
+            saved_accounts: 0,
+        });
+    }
     let provider_ports = store.provider_ports();
     let mut openai = provider_openai::initialize(openai, provider_ports.clone()).await?;
     host.report_startup_ready("OpenAI Provider");
     let mut xai = provider_xai::initialize(provider_ports).await?;
     host.report_startup_ready("xAI Provider");
     let providers = ProviderRegistry::new([openai.core_provider(), xai.core_provider()])?;
-    let mut core = gateway_core::initialize(store.core_ports(), providers).await?;
+    let plugin_runtime = prepare_plugins(
+        &store,
+        plugin_cache,
+        &version,
+        providers,
+        gateway_admin::ports::provider::ProviderAdminRegistry::new([
+            openai.admin_provider(),
+            xai.admin_provider(),
+        ])
+        .map_err(|_| gateway_admin::model::AdminError::invalid("Provider 管理身份冲突"))?,
+        plugin_http.clone(),
+    )?;
+    if let Some(command) = command {
+        let instance_id = or_shutdown!(
+            plugin_runtime,
+            command
+                .instance_id
+                .as_deref()
+                .ok_or_else(|| gateway_admin::model::AdminError::invalid("插件实例 ID 缺失"))
+        );
+        let name = or_shutdown!(
+            plugin_runtime,
+            command
+                .name
+                .as_deref()
+                .ok_or_else(|| gateway_admin::model::AdminError::invalid("插件命令名缺失"))
+        );
+        let core = gateway_core::prepare_command_plane(
+            store.core_ports(),
+            plugin_runtime.provider_registry(),
+            Some(plugin_runtime.clone()),
+            Some(plugin_runtime.observer_registry()),
+            Some(plugin_runtime.policy_registry()),
+            Some(plugin_runtime.middleware_registry()),
+        );
+        let accounts = gateway_admin::initialize_plugin_accounts(
+            plugin_runtime.admin_registry(core.snapshots()),
+            store.admin_ports().accounts(),
+            core.snapshot_control(),
+        );
+        or_shutdown!(plugin_runtime, plugin_runtime.bind_account_ports(&accounts));
+        let keys = gateway_admin::initialize_plugin_client_keys(
+            plugin_runtime.admin_registry(core.snapshots()),
+            store.admin_ports().client_keys(),
+            core.snapshot_control(),
+        );
+        or_shutdown!(plugin_runtime, plugin_runtime.bind_client_key_ports(&keys));
+        let core = or_shutdown!(plugin_runtime, core.activate().await);
+        let nested_models = core.nested_model_execution_port();
+        let affinity_lookup = core.affinity_lookup_port();
+        or_shutdown!(
+            plugin_runtime,
+            plugin_runtime.bind_model_ports(&nested_models, &affinity_lookup)
+        );
+        let commands = or_shutdown!(plugin_runtime, plugin_runtime.prepare_command_line().await);
+        or_shutdown!(plugin_runtime, store.start_command_line_writes());
+        // CLI 不恢复主进程的准入状态，不构造 API、不初始化管理员或启动 Worker。
+        let result = commands
+            .execute_cancellable(instance_id, name, &command.arguments, &host.cancellation())
+            .await;
+        commands.shutdown().await;
+        plugin_runtime.shutdown().await;
+        store.shutdown_command_line_writes().await?;
+        return Ok(result?);
+    }
+    let core = gateway_core::prepare(
+        store.core_ports(),
+        plugin_runtime.provider_registry(),
+        Some(plugin_runtime.clone()),
+        Some(plugin_runtime.observer_registry()),
+        Some(plugin_runtime.policy_registry()),
+        Some(plugin_runtime.middleware_registry()),
+        Some(plugin_runtime.frontend_authentication_registry()),
+    );
+    let admin_providers = plugin_runtime.admin_registry(core.snapshots());
+    let plugin_accounts = gateway_admin::initialize_plugin_accounts(
+        admin_providers.clone(),
+        store.admin_ports().accounts(),
+        core.snapshot_control(),
+    );
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_account_ports(&plugin_accounts)
+    );
+    let plugin_keys = gateway_admin::initialize_plugin_client_keys(
+        admin_providers.clone(),
+        store.admin_ports().client_keys(),
+        core.snapshot_control(),
+    );
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_client_key_ports(&plugin_keys)
+    );
+    let mut core = or_shutdown!(plugin_runtime, core.activate().await);
+    let nested_models = core.nested_model_execution_port();
+    let affinity_lookup = core.affinity_lookup_port();
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_model_ports(&nested_models, &affinity_lookup)
+    );
     host.report_startup_ready("Core");
-    let mut admin = gateway_admin::initialize(
-        admin,
-        client,
-        store.admin_ports(),
-        gateway_admin::AdminRuntimePorts {
-            pricing_source: std::sync::Arc::new(gateway_host::pricing::ModelsDevPricing),
-            providers: vec![openai.admin_provider(), xai.admin_provider()],
-            snapshot: core.snapshot_control(),
-            account_probe: core.account_probe(),
-            proxy_probe: host.proxy_probe(provider_openai::build_reqwest_client_with_custom_ca),
-            client_distribution: host.client_distribution_resolver(),
-            system: host.system_operations(),
-            client_key_verifier: core.client_key_verifier(),
-        },
-    )
-    .await?;
+    let host_version = or_shutdown!(
+        plugin_runtime,
+        version
+            .trim_start_matches('v')
+            .parse()
+            .map_err(|_| ConfigError::InvalidField("host.version"))
+    );
+    let plugin_inspector = std::sync::Arc::new(gateway_plugin_runtime::PackageInspector::new(
+        gateway_plugin_runtime::PackageLimits::default(),
+        host_version,
+    ));
+    let plugin_distribution = std::sync::Arc::new(or_shutdown!(
+        plugin_runtime,
+        gateway_host::plugin_distribution::HttpPluginDistribution::new(plugin_http)
+    ));
+    let mut admin = or_shutdown!(
+        plugin_runtime,
+        gateway_admin::initialize_with_plugin_accounts(
+            admin,
+            client,
+            store.admin_ports(),
+            gateway_admin::AdminRuntimePorts {
+                providers: admin_providers,
+                plugin_preparation: plugin_runtime.clone(),
+                plugin_management: plugin_runtime.clone(),
+                published_snapshot: core.snapshots(),
+                plugin_inspector,
+                plugin_distribution,
+                pricing_source: std::sync::Arc::new(gateway_host::pricing::ModelsDevPricing),
+                snapshot: core.snapshot_control(),
+                account_probe: core.account_probe(),
+                proxy_probe: host.proxy_probe(provider_openai::build_reqwest_client_with_custom_ca),
+                client_distribution: host.client_distribution_resolver(),
+                system: host.system_operations(),
+                client_key_verifier: core.client_key_verifier(),
+            },
+            plugin_accounts,
+        )
+        .await
+    );
+    let official_files = host.official_plugin_release_files();
+    let official_identity = host.official_plugin_release_identity();
+    let official_import = or_shutdown!(
+        plugin_runtime,
+        admin
+            .services()
+            .plugins()
+            .import_official_release(
+                official_files.as_ref(),
+                &official_identity,
+                &gateway_admin::model::MutationContext {
+                    actor: gateway_admin::model::MutationActor::System,
+                    request_id: "startup-official-plugin-import".to_owned(),
+                },
+            )
+            .await
+    );
+    if official_import.artifacts > 0 {
+        host.report_startup_ready("Official plugins");
+    }
     host.report_startup_ready("Admin");
 
     let mut probes = store.health_probes();
     probes.extend(core.health_probes());
     probes.push(host.logging_health_probe());
-    let api = gateway_api::initialize(
-        api,
-        core.execution_service(),
-        admin.services(),
-        probes,
-        host.worker_health(),
-        host.connection_lifecycle(),
-    )?;
+    let api = or_shutdown!(
+        plugin_runtime,
+        gateway_api::initialize(
+            api,
+            core.execution_service(),
+            admin.services(),
+            probes,
+            host.worker_health(),
+            host.connection_lifecycle(),
+        )
+    );
     host.report_startup_ready("API");
 
     let mut plan = store.take_worker_contributions();
@@ -111,22 +339,76 @@ pub async fn run() -> Result<(), BootstrapError> {
     plan.extend(openai.take_worker_contributions());
     plan.extend(xai.take_worker_contributions());
     plan.extend(admin.take_worker_contributions());
-    host.start_workers(plan, store.worker_leader_lease())?;
+    plan.extend(or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.worker_contributions(core.snapshots())
+    ));
+    or_shutdown!(
+        plugin_runtime,
+        host.start_workers(plan, store.worker_leader_lease())
+    );
     host.report_startup_ready("Workers");
-    host.serve(api.router()).await?;
-    Ok(())
+    let served = host.serve(api.router()).await;
+    plugin_runtime.shutdown().await;
+    served?;
+    Ok(gateway_plugin_runtime::PluginCommandOutput {
+        stdout: String::new(),
+        stderr: String::new(),
+        exit_code: 0,
+        saved_accounts: 0,
+    })
+}
+
+fn prepare_plugins(
+    store: &gateway_store::StoreBundle,
+    plugin_cache: std::path::PathBuf,
+    version: &str,
+    providers: ProviderRegistry,
+    admin_providers: gateway_admin::ports::provider::ProviderAdminRegistry,
+    http: std::sync::Arc<gateway_host::outbound::HttpClient>,
+) -> Result<std::sync::Arc<gateway_plugin_runtime::PluginRuntime>, BootstrapError> {
+    Ok(std::sync::Arc::new(
+        gateway_plugin_runtime::PluginRuntime::new(
+            store.admin_ports().plugins(),
+            store.admin_ports().plugin_state(),
+            gateway_plugin_runtime::PluginRuntimeConfig {
+                cache_directory: plugin_cache,
+                host_version: version
+                    .trim_start_matches('v')
+                    .parse()
+                    .map_err(|_| ConfigError::InvalidField("host.version"))?,
+                package_limits: gateway_plugin_runtime::PackageLimits::default(),
+                rpc_limits: gateway_plugin_runtime::RpcLimits::default(),
+                continuation_drain: Default::default(),
+                restart_circuit: Default::default(),
+            },
+            providers,
+            admin_providers,
+            http,
+            std::sync::Arc::new(gateway_host::process::ProcessSupervisor::default()),
+        )
+        .with_provider_ports(store.provider_ports()),
+    ))
 }
 
 /// 组合根只保留包级错误分类，不展开内部实现或敏感配置。
 #[derive(Debug, thiserror::Error)]
 pub enum BootstrapError {
+    #[error(transparent)]
+    Worker(#[from] gateway_core::task::WorkerDefinitionError),
+    #[error(transparent)]
+    PluginCommand(#[from] gateway_plugin_runtime::PluginCommandError),
     #[error(transparent)]
     Config(#[from] gateway_host::ConfigError),
     #[error(transparent)]
     Host(#[from] gateway_host::HostError),
     #[error(transparent)]
+    Outbound(#[from] gateway_host::outbound::HttpError),
+    #[error(transparent)]
     Store(#[from] gateway_store::StoreError),
     #[error(transparent)]
+    CommandStoreDrain(#[from] gateway_store::CommandStoreDrainError),
+    #[error(transparent)]
     OpenAi(#[from] provider_openai::OpenAiInitializeError),
     #[error(transparent)]
     Xai(#[from] provider_xai::XaiInitializeError),
diff --git a/backend/apps/gateway/src/main.rs b/backend/apps/gateway/src/main.rs
index 2b08080d4..bc9d02859 100644
--- a/backend/apps/gateway/src/main.rs
+++ b/backend/apps/gateway/src/main.rs
@@ -1,19 +1,84 @@
-use std::{env, error::Error, io};
+use std::{
+    env,
+    error::Error,
+    io::{self, Write},
+    process::ExitCode,
+};
 
 use provider_openai::ensure_rustls_provider;
 
-fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
+fn main() -> ExitCode {
+    match run() {
+        Ok(code) => code,
+        Err(error) => {
+            eprintln!("{error}");
+            ExitCode::FAILURE
+        }
+    }
+}
+
+fn run() -> Result<ExitCode, Box<dyn Error + Send + Sync>> {
     ensure_rustls_provider();
     let mut arguments = env::args_os().skip(1);
-    match arguments.next().as_deref().and_then(|value| value.to_str()) {
+    let command = arguments
+        .next()
+        .map(|value| {
+            value
+                .into_string()
+                .map_err(|_| invalid_cli("command must be UTF-8"))
+        })
+        .transpose()?;
+    match command.as_deref() {
         None | Some("serve") => {
             reject_extra_arguments(arguments)?;
             runtime()?.block_on(codex_proxy_rs::bootstrap::run())?;
-            Ok(())
+            Ok(ExitCode::SUCCESS)
         }
-        Some(command) => {
-            Err(invalid_cli(&format!("unknown command {command:?}; expected serve")).into())
+        Some("help" | "--help" | "-h") => {
+            reject_extra_arguments(arguments)?;
+            println!(
+                "Usage: codex-proxy-rs [serve]\n       codex-proxy-rs plugin <instance-id> <command> [options]\n\n  --help     Show help without loading configuration\n  --version  Show version\n  plugin --help  List enabled plugin commands without starting HTTP"
+            );
+            Ok(ExitCode::SUCCESS)
         }
+        Some("--version" | "-V") => {
+            reject_extra_arguments(arguments)?;
+            println!(
+                "{}",
+                option_env!("CPR_VERSION").unwrap_or(env!("CARGO_PKG_VERSION"))
+            );
+            Ok(ExitCode::SUCCESS)
+        }
+        Some("plugin") => {
+            let arguments = arguments
+                .map(|value| {
+                    value
+                        .into_string()
+                        .map_err(|_| invalid_cli("plugin arguments must be UTF-8"))
+                })
+                .collect::<Result<Vec<_>, _>>()?;
+            let mut arguments = arguments.into_iter();
+            let instance_id = arguments
+                .next()
+                .filter(|value| !matches!(value.as_str(), "--help" | "-h"));
+            let name = arguments
+                .next()
+                .filter(|value| !matches!(value.as_str(), "--help" | "-h"));
+            if instance_id.is_none() && name.is_some() {
+                return Err(invalid_cli("unexpected plugin help arguments").into());
+            }
+            let output = runtime()?.block_on(codex_proxy_rs::bootstrap::plugin_command(
+                codex_proxy_rs::bootstrap::PluginCommand {
+                    instance_id,
+                    name,
+                    arguments: arguments.collect(),
+                },
+            ))?;
+            io::stdout().lock().write_all(output.stdout.as_bytes())?;
+            io::stderr().lock().write_all(output.stderr.as_bytes())?;
+            Ok(ExitCode::from(output.exit_code))
+        }
+        Some(_) => Err(invalid_cli("unknown command; expected serve, plugin, or --help").into()),
     }
 }
 
diff --git a/backend/apps/gateway/tests/architecture.rs b/backend/apps/gateway/tests/architecture.rs
index 55c70dce4..ab29c06c9 100644
--- a/backend/apps/gateway/tests/architecture.rs
+++ b/backend/apps/gateway/tests/architecture.rs
@@ -11,10 +11,13 @@ use syn::{Item, visit::Visit};
 /// workspace 成员冻结清单;新增 crate 必须同步扩展本文件的依赖规则。
 pub(super) const WORKSPACE_MEMBERS: &[&str] = &[
     "apps/gateway",
+    "apps/plugin-cli",
     "crates/gateway-admin",
     "crates/gateway-api",
     "crates/gateway-core",
     "crates/gateway-host",
+    "crates/gateway-plugin/runtime",
+    "crates/gateway-plugin/sdk",
     "crates/gateway-protocol",
     "crates/gateway-store",
     "crates/providers/openai",
@@ -149,6 +152,13 @@ fn gateway_protocol_has_no_workspace_dependencies() {
     }
 }
 
+#[test]
+fn plugin_sdk_has_no_workspace_dependencies() {
+    for name in dependency_names("crates/gateway-plugin/sdk") {
+        assert!(!name.starts_with("gateway-") && !name.starts_with("provider-"));
+    }
+}
+
 #[test]
 fn provider_crates_do_not_depend_on_each_other() {
     assert_no_dependency("crates/providers/openai", &["provider-xai"]);
@@ -166,25 +176,34 @@ fn gateway_admin_stays_free_of_infrastructure_dependencies() {
 /// workspace 包名到冻结成员路径的映射。
 const PACKAGE_TO_MEMBER: &[(&str, &str)] = &[
     ("codex-proxy-rs", "apps/gateway"),
+    ("codex-proxy-plugin-cli", "apps/plugin-cli"),
     ("gateway-admin", "crates/gateway-admin"),
     ("gateway-api", "crates/gateway-api"),
     ("gateway-core", "crates/gateway-core"),
     ("gateway-host", "crates/gateway-host"),
+    ("gateway-plugin-runtime", "crates/gateway-plugin/runtime"),
+    ("gateway-plugin-sdk", "crates/gateway-plugin/sdk"),
     ("gateway-protocol", "crates/gateway-protocol"),
     ("gateway-store", "crates/gateway-store"),
     ("provider-openai", "crates/providers/openai"),
     ("provider-xai", "crates/providers/xai"),
 ];
 
-/// Adapter/provider 根门面的稳定合同模块；任何增减都必须同步完成边界审计。
+/// SDK 与 Adapter/provider 根门面的稳定合同模块；任何增减都必须同步完成边界审计。
 const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
+    ("crates/gateway-plugin/sdk", &["call", "client"]),
+    ("crates/gateway-plugin/runtime", &[]),
     ("crates/gateway-api", &["admin", "auth", "openai"]),
     (
         "crates/gateway-host",
         &[
             "client_distribution",
             "config",
+            "outbound",
+            "official_plugins",
             "pricing",
+            "plugin_distribution",
+            "process",
             "proxy_probe",
             "serve",
             "system_update",
@@ -207,10 +226,12 @@ const ROOT_TEST_SCENARIOS: &[(&str, &[&str])] = &[
 
 /// 冻结的 workspace 内部运行时依赖边；新增/删除任何边都必须同步本表。
 const ALLOWED_INTERNAL_EDGES: &[(&str, &str)] = &[
+    ("codex-proxy-plugin-cli", "gateway-plugin-sdk"),
     ("codex-proxy-rs", "gateway-admin"),
     ("codex-proxy-rs", "gateway-api"),
     ("codex-proxy-rs", "gateway-core"),
     ("codex-proxy-rs", "gateway-host"),
+    ("codex-proxy-rs", "gateway-plugin-runtime"),
     ("codex-proxy-rs", "gateway-store"),
     ("codex-proxy-rs", "provider-openai"),
     ("codex-proxy-rs", "provider-xai"),
@@ -220,6 +241,11 @@ const ALLOWED_INTERNAL_EDGES: &[(&str, &str)] = &[
     ("gateway-api", "gateway-protocol"),
     ("gateway-host", "gateway-admin"),
     ("gateway-host", "gateway-core"),
+    ("gateway-plugin-runtime", "gateway-host"),
+    ("gateway-plugin-runtime", "gateway-core"),
+    ("gateway-plugin-runtime", "gateway-admin"),
+    ("gateway-plugin-runtime", "gateway-plugin-sdk"),
+    ("gateway-plugin-runtime", "gateway-protocol"),
     ("gateway-store", "gateway-admin"),
     ("gateway-store", "gateway-core"),
     ("provider-openai", "gateway-admin"),
@@ -349,13 +375,18 @@ fn production_sources_do_not_host_tests() {
 
 #[test]
 fn workspace_modules_follow_conventional_file_layout() {
+    let targets = test_source_roots();
     for member in WORKSPACE_MEMBERS {
         let member_root = backend_root().join(member);
         assert_module_tree(&member_root.join("src"), &["lib.rs", "main.rs"]);
 
         let tests = member_root.join("tests");
         if tests.is_dir() {
-            assert_module_tree(&tests, &["main.rs"]);
+            let roots = targets.get(&tests).expect("Cargo test source roots");
+            assert_module_tree(
+                &tests,
+                &roots.iter().map(String::as_str).collect::<Vec<_>>(),
+            );
         }
     }
 }
@@ -368,6 +399,7 @@ enum ModuleLayout {
 
 #[test]
 fn integration_tests_mirror_production_module_tree() {
+    let targets = test_source_roots();
     for member in WORKSPACE_MEMBERS {
         let member_root = backend_root().join(member);
         let tests_root = member_root.join("tests");
@@ -376,9 +408,13 @@ fn integration_tests_mirror_production_module_tree() {
         }
 
         let production = module_layouts(&member_root.join("src"), &["lib.rs", "main.rs"]);
-        let tests = module_layouts(&tests_root, &["main.rs"]);
+        let roots = targets.get(&tests_root).expect("Cargo test source roots");
+        let tests = module_layouts(
+            &tests_root,
+            &roots.iter().map(String::as_str).collect::<Vec<_>>(),
+        );
         for (module, test_layout) in tests {
-            if module == Path::new("support") {
+            if module.starts_with("support") {
                 continue;
             }
 
@@ -408,6 +444,28 @@ fn integration_tests_mirror_production_module_tree() {
     }
 }
 
+/// Rust 子进程 fixture 是 Cargo 的独立 crate 根，不能要求它由测试模块再次声明。
+fn test_source_roots() -> BTreeMap<PathBuf, Vec<String>> {
+    let metadata = cargo_metadata_json();
+    let mut roots = BTreeMap::<PathBuf, Vec<String>>::new();
+    for package in metadata["packages"].as_array().expect("Cargo packages") {
+        let root = Path::new(package["manifest_path"].as_str().expect("package manifest"))
+            .parent()
+            .expect("package directory")
+            .join("tests");
+        for target in package["targets"].as_array().expect("Cargo targets") {
+            let source = Path::new(target["src_path"].as_str().expect("target source"));
+            if let Ok(relative) = source.strip_prefix(&root) {
+                roots
+                    .entry(root.clone())
+                    .or_default()
+                    .push(relative.to_str().expect("UTF-8 source path").to_owned());
+            }
+        }
+    }
+    roots
+}
+
 fn module_layouts(root: &Path, crate_roots: &[&str]) -> BTreeMap<PathBuf, ModuleLayout> {
     super::rust_files(root)
         .into_iter()
diff --git a/backend/apps/gateway/tests/bootstrap.rs b/backend/apps/gateway/tests/bootstrap.rs
index b1cc13a70..7627a1dfd 100644
--- a/backend/apps/gateway/tests/bootstrap.rs
+++ b/backend/apps/gateway/tests/bootstrap.rs
@@ -9,6 +9,54 @@ const REDIS_PASSWORD: &str = "222222222222222222222222222222222222222222222222";
 const ADMIN_PASSWORD: &str = "test-admin-password";
 const TOPOLOGY_CHILD_ENV: &str = "CPR_TEST_TOPOLOGY_CHILD";
 
+#[test]
+fn basic_cli_options_do_not_load_configuration_and_reject_unexpected_arguments() {
+    let directory = tempfile::tempdir().unwrap();
+    fs::create_dir(directory.path().join("deploy")).unwrap();
+    fs::write(directory.path().join("deploy/config.yaml"), "invalid: [").unwrap();
+    for flag in ["--help", "-h", "help", "--version", "-V"] {
+        let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
+            .arg(flag)
+            .current_dir(directory.path())
+            .env_clear()
+            .output()
+            .unwrap();
+        assert!(output.status.success(), "{flag}");
+        assert!(!output.stdout.is_empty());
+        assert!(output.stderr.is_empty());
+    }
+    for args in [
+        vec!["unknown"],
+        vec!["--help", "extra"],
+        vec!["serve", "extra"],
+    ] {
+        let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
+            .args(args)
+            .current_dir(directory.path())
+            .env_clear()
+            .output()
+            .unwrap();
+        assert!(!output.status.success());
+        assert!(output.stdout.is_empty());
+        assert!(!String::from_utf8_lossy(&output.stderr).contains("configuration"));
+    }
+}
+
+#[cfg(unix)]
+#[test]
+fn non_utf8_command_is_not_interpreted_as_serve() {
+    use std::os::unix::ffi::OsStringExt as _;
+
+    let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
+        .arg(std::ffi::OsString::from_vec(vec![0xff]))
+        .env_clear()
+        .output()
+        .unwrap();
+    assert!(!output.status.success());
+    assert!(output.stdout.is_empty());
+    assert!(String::from_utf8_lossy(&output.stderr).contains("command must be UTF-8"));
+}
+
 #[tokio::test]
 async fn proxy_probe_should_use_provider_custom_ca_for_https_proxies() {
     use gateway_admin::ports::proxy::ProxyProbe;
diff --git a/backend/apps/plugin-cli/Cargo.toml b/backend/apps/plugin-cli/Cargo.toml
new file mode 100644
index 000000000..47c210973
--- /dev/null
+++ b/backend/apps/plugin-cli/Cargo.toml
@@ -0,0 +1,27 @@
+[package]
+name = "codex-proxy-plugin-cli"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+rust-version.workspace = true
+
+[[bin]]
+name = "cpr-plugin"
+path = "src/main.rs"
+
+[dependencies]
+clap = { version = "4.6.7", features = ["derive"] }
+flate2 = "1.1.9"
+gateway-plugin-sdk = { path = "../../crates/gateway-plugin/sdk" }
+hex = "0.4.3"
+serde_json = "1.0.150"
+sha2 = "0.11.0"
+tar = "0.4.44"
+thiserror = "2.0.18"
+
+[dev-dependencies]
+tempfile = "3.27.0"
+
+[lints]
+workspace = true
diff --git a/backend/apps/plugin-cli/README.md b/backend/apps/plugin-cli/README.md
new file mode 100644
index 000000000..546c19a47
--- /dev/null
+++ b/backend/apps/plugin-cli/README.md
@@ -0,0 +1,65 @@
+# Codex Proxy Plugin CLI
+
+`cpr-plugin` 校验并规范化作者清单、收集声明的资源，生成可安装归档及 SHA-256 校验文件。
+当前输出使用 `manifestVersion: 3`、`protocolVersion: 4` 和 SDK `0.4` 合同。
+
+## 安装
+
+从仓库根目录安装到本地工具目录：
+
+```bash
+cargo install --locked --path backend/apps/plugin-cli --root /path/to/local-tools
+```
+
+将 `/path/to/local-tools/bin` 加入 `PATH`，或使用可执行文件的完整路径。
+
+## 打包
+
+先构建目标平台的插件二进制；插件提供管理页面时，还需构建页面静态资源。打包命令传入作者清单、二进制和所需的资源目录映射，通过 `cpr-plugin package --help` 查看完整参数：
+
+```bash
+cpr-plugin package \
+  --manifest /path/to/plugin/plugin.json \
+  --binary /path/to/plugin/target/x86_64-unknown-linux-gnu/release/plugin \
+  --target x86_64-unknown-linux-gnu \
+  --resource-map web=web/dist \
+  --output-dir /path/to/output
+```
+
+资源映射相对于作者清单所在目录解析。输出包括完整插件 ID、版本和目标 triple 命名的 `.tar.gz` 及 `.sha256`；归档根目录直接包含 `plugin.json`、可执行文件和已声明资源，不包含开发依赖。
+
+作者清单可省略普通贡献项的 `id`、`version` 和固定阶段；`middleware` 的 `request`／`attempt` 仍须显式选择。
+Provider 使用一个业务组声明协议与可选功能，例如：
+
+```json
+{
+  "contributes": {
+    "provider": {
+      "capabilities": ["models", "quota", "maintenance"],
+      "inputFormats": ["openai"],
+      "outputFormats": ["openai"]
+    }
+  }
+}
+```
+
+CLI 与 SDK 的 `Manifest::from_author_slice`、`PluginBuilder::from_json` 共用规范化入口；归档中的
+`plugin.json` 会写入展开后的 `executor`、所选 Provider 子能力及完整贡献项字段，不保留另一份作者声明。
+完整规则见 [SDK 清单](../../crates/gateway-plugin/sdk/docs/manifest.md)。
+
+支持 `x86_64-unknown-linux-gnu`、`aarch64-unknown-linux-gnu` 和 `aarch64-apple-darwin`。完整开发示例在同级 `codex-proxy-plugins/examples/workbench` 仓库目录；本工具不负责源码构建、上传或启用插件。
+
+### 图标资源
+
+在作者清单的 `icon` 中指定图标，并在 `resources` 中登记对应路径与 MIME 类型，配置方式见
+[SDK 插件图标](../../crates/gateway-plugin/sdk/docs/manifest.md#插件图标)。图标与其他声明资源一样参与打包和摘要计算，
+无需额外命令参数；工具保留文件原始内容，宿主安装时验证图标内容与资源限制。
+
+## 开发
+
+Rust 包名为 `codex-proxy-plugin-cli`，位于宿主的 `backend` workspace，共享工具链、锁文件和检查规则；内部仅依赖 `gateway-plugin-sdk`。
+
+```bash
+cargo run --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli -- package --help
+RUST_MIN_STACK=16777216 cargo +1.97.0 test --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked
+```
diff --git a/backend/apps/plugin-cli/src/main.rs b/backend/apps/plugin-cli/src/main.rs
new file mode 100644
index 000000000..9ec4b1f53
--- /dev/null
+++ b/backend/apps/plugin-cli/src/main.rs
@@ -0,0 +1,562 @@
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    fs::{self, File, OpenOptions},
+    io::{self, Read as _, Write as _},
+    path::{Component, Path, PathBuf},
+};
+
+use clap::{Args, Parser, Subcommand};
+use flate2::{Compression, GzBuilder};
+use gateway_plugin_sdk::{
+    Manifest, ManifestError, PROTOCOL_VERSION, Package, PackageTarget, valid_package_path,
+};
+use sha2::{Digest as _, Sha256};
+use tar::{Builder, EntryType, Header, HeaderMode};
+use thiserror::Error;
+
+const MAXIMUM_COMPRESSED_BYTES: u64 = 32 * 1024 * 1024;
+const MAXIMUM_EXPANDED_BYTES: u64 = 128 * 1024 * 1024;
+const MAXIMUM_MANIFEST_BYTES: u64 = 64 * 1024;
+
+#[derive(Parser)]
+#[command(name = "cpr-plugin", version, about = "Codex Proxy 插件开发工具")]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    #[command(about = "校验清单并打包已编译的插件")]
+    Package(Options),
+}
+
+#[derive(Debug, Error)]
+enum PackagerError {
+    #[error("{0}")]
+    Invalid(String),
+    #[error("failed to {action} {path}: {source}")]
+    Io {
+        action: &'static str,
+        path: PathBuf,
+        #[source]
+        source: io::Error,
+    },
+    #[error("source or generated manifest is invalid: {0}")]
+    Manifest(#[from] ManifestError),
+    #[error("failed to encode generated manifest: {0}")]
+    EncodeManifest(#[source] serde_json::Error),
+}
+
+#[derive(Debug, Args)]
+struct Options {
+    #[arg(long, value_name = "FILE", help = "作者清单 plugin.json")]
+    manifest: PathBuf,
+    #[arg(long, value_name = "FILE", help = "已编译的目标平台插件二进制")]
+    binary: PathBuf,
+    #[arg(long, value_name = "TRIPLE", help = "目标平台 triple")]
+    target: String,
+    #[arg(long, value_name = "DIRECTORY", help = "归档与 SHA-256 文件的输出目录")]
+    output_dir: PathBuf,
+    #[arg(
+        long = "resource-map",
+        value_name = "PREFIX=DIRECTORY",
+        help = "包内资源前缀到项目内目录的映射，可重复传入"
+    )]
+    resource_maps: Vec<String>,
+}
+
+#[derive(Debug, Clone, Copy)]
+struct RuntimeTarget {
+    os: &'static str,
+    architecture: &'static str,
+}
+
+impl RuntimeTarget {
+    fn parse(triple: &str) -> Result<Self, PackagerError> {
+        match triple {
+            "x86_64-unknown-linux-gnu" => Ok(Self {
+                os: "linux",
+                architecture: "x86_64",
+            }),
+            "aarch64-unknown-linux-gnu" => Ok(Self {
+                os: "linux",
+                architecture: "aarch64",
+            }),
+            "aarch64-apple-darwin" => Ok(Self {
+                os: "macos",
+                architecture: "aarch64",
+            }),
+            _ => Err(PackagerError::Invalid(format!(
+                "unsupported plugin target {triple}"
+            ))),
+        }
+    }
+}
+
+#[derive(Debug)]
+struct PackageOutput {
+    archive: PathBuf,
+    checksum: PathBuf,
+}
+
+fn main() -> Result<(), PackagerError> {
+    match Cli::parse().command {
+        Commands::Package(options) => {
+            let output = package(&options)?;
+            println!("{}", output.archive.display());
+            println!("{}", output.checksum.display());
+            Ok(())
+        }
+    }
+}
+
+fn parse_resource_maps(values: &[String]) -> Result<BTreeMap<String, PathBuf>, PackagerError> {
+    let mut resource_maps = BTreeMap::new();
+    for value in values {
+        let (prefix, directory) = value.split_once('=').ok_or_else(|| {
+            PackagerError::Invalid(
+                "--resource-map must use package-prefix=source-directory".to_owned(),
+            )
+        })?;
+        if !valid_resource_prefix(prefix) {
+            return Err(PackagerError::Invalid(format!(
+                "invalid resource-map package prefix {prefix}"
+            )));
+        }
+        let directory = PathBuf::from(directory);
+        if !safe_relative_directory(&directory) {
+            return Err(PackagerError::Invalid(format!(
+                "resource-map source directory must be a non-empty project-relative path: {}",
+                directory.display()
+            )));
+        }
+        if resource_maps.insert(prefix.to_owned(), directory).is_some() {
+            return Err(PackagerError::Invalid(format!(
+                "duplicate resource-map package prefix {prefix}"
+            )));
+        }
+    }
+    Ok(resource_maps)
+}
+
+fn valid_resource_prefix(prefix: &str) -> bool {
+    valid_package_path(prefix) && !prefix.contains('/')
+}
+
+fn safe_relative_directory(path: &Path) -> bool {
+    !path.as_os_str().is_empty()
+        && !path.is_absolute()
+        && path
+            .components()
+            .all(|component| matches!(component, Component::Normal(_) | Component::CurDir))
+}
+
+fn package(options: &Options) -> Result<PackageOutput, PackagerError> {
+    let target = RuntimeTarget::parse(&options.target)?;
+    let resource_maps = parse_resource_maps(&options.resource_maps)?;
+    let manifest_bytes = read_regular_file(&options.manifest, MAXIMUM_MANIFEST_BYTES)?;
+    let mut manifest = Manifest::from_author_slice(&manifest_bytes)?;
+
+    let project_directory = options
+        .manifest
+        .parent()
+        .filter(|path| !path.as_os_str().is_empty())
+        .unwrap_or_else(|| Path::new("."));
+    let canonical_project = canonicalize(project_directory)?;
+    let mut sources = BTreeMap::from([(manifest.main.clone(), options.binary.clone())]);
+    let mut used_maps = BTreeSet::new();
+    for package_path in manifest.resources.keys() {
+        let source = resource_source(
+            project_directory,
+            package_path,
+            &resource_maps,
+            &mut used_maps,
+        )?;
+        let canonical_source = canonicalize(&source)?;
+        if !canonical_source.starts_with(&canonical_project) {
+            return Err(PackagerError::Invalid(format!(
+                "resource source escapes the plugin project: {}",
+                source.display()
+            )));
+        }
+        if sources.insert(package_path.clone(), source).is_some() {
+            return Err(PackagerError::Invalid(format!(
+                "plugin main and resource share package path {package_path}"
+            )));
+        }
+    }
+    if used_maps.len() != resource_maps.len() {
+        let unused = resource_maps
+            .keys()
+            .filter(|prefix| !used_maps.contains(*prefix))
+            .cloned()
+            .collect::<Vec<_>>();
+        return Err(PackagerError::Invalid(format!(
+            "unused resource-map package prefix: {}",
+            unused.join(", ")
+        )));
+    }
+    reject_case_folded_paths(sources.keys())?;
+
+    let mut files = BTreeMap::new();
+    let mut source_bytes = 0u64;
+    for (package_path, source) in sources {
+        let remaining = MAXIMUM_EXPANDED_BYTES
+            .checked_sub(source_bytes)
+            .ok_or_else(package_limit)?;
+        let bytes = read_regular_file(&source, remaining)?;
+        source_bytes = source_bytes
+            .checked_add(u64::try_from(bytes.len()).map_err(|_| package_limit())?)
+            .ok_or_else(package_limit)?;
+        files.insert(package_path, bytes);
+    }
+    let digests = files
+        .iter()
+        .map(|(path, bytes)| (path.clone(), hex::encode(Sha256::digest(bytes))))
+        .collect();
+    manifest.package = Some(Package {
+        protocol_version: PROTOCOL_VERSION,
+        target: PackageTarget {
+            os: target.os.to_owned(),
+            architecture: target.architecture.to_owned(),
+        },
+        files: digests,
+    });
+    manifest.validate()?;
+    let mut generated_manifest =
+        serde_json::to_vec_pretty(&manifest).map_err(PackagerError::EncodeManifest)?;
+    generated_manifest.push(b'\n');
+    if generated_manifest.len() as u64 > MAXIMUM_MANIFEST_BYTES {
+        return Err(package_limit());
+    }
+
+    create_directory(&options.output_dir)?;
+    let plugin_id = manifest.plugin_id()?;
+    let archive_name = format!("{plugin_id}-{}-{}.tar.gz", manifest.version, options.target);
+    let archive_path = options.output_dir.join(&archive_name);
+    let archive_temporary = options
+        .output_dir
+        .join(format!(".{archive_name}.{}.tmp", std::process::id()));
+    let mut temporary = TemporaryFile::create(archive_temporary)?;
+    write_archive(
+        temporary.file_mut(),
+        &generated_manifest,
+        &manifest.main,
+        &files,
+    )?;
+    temporary.sync_all()?;
+    let compressed_bytes = temporary.metadata_len()?;
+    if compressed_bytes > MAXIMUM_COMPRESSED_BYTES {
+        return Err(package_limit());
+    }
+    temporary.persist(&archive_path)?;
+
+    let archive_digest = sha256_file(&archive_path)?;
+    let checksum_path = options.output_dir.join(format!("{archive_name}.sha256"));
+    let checksum_temporary = options
+        .output_dir
+        .join(format!(".{archive_name}.sha256.{}.tmp", std::process::id()));
+    let mut checksum = TemporaryFile::create(checksum_temporary)?;
+    let checksum_temporary_path = checksum.path().to_owned();
+    writeln!(checksum.file_mut(), "{archive_digest}  {archive_name}").map_err(|source| {
+        PackagerError::Io {
+            action: "write",
+            path: checksum_temporary_path,
+            source,
+        }
+    })?;
+    checksum.sync_all()?;
+    checksum.persist(&checksum_path)?;
+
+    Ok(PackageOutput {
+        archive: archive_path,
+        checksum: checksum_path,
+    })
+}
+
+fn resource_source(
+    project_directory: &Path,
+    package_path: &str,
+    mappings: &BTreeMap<String, PathBuf>,
+    used_mappings: &mut BTreeSet<String>,
+) -> Result<PathBuf, PackagerError> {
+    let (prefix, remainder) = package_path
+        .split_once('/')
+        .map_or((package_path, None), |(prefix, remainder)| {
+            (prefix, Some(remainder))
+        });
+    if let Some(directory) = mappings.get(prefix) {
+        let remainder = remainder.ok_or_else(|| {
+            PackagerError::Invalid(format!(
+                "mapped resource {package_path} must have a path below prefix {prefix}"
+            ))
+        })?;
+        used_mappings.insert(prefix.to_owned());
+        Ok(project_directory.join(directory).join(remainder))
+    } else {
+        Ok(project_directory.join(package_path))
+    }
+}
+
+fn reject_case_folded_paths<'a>(
+    paths: impl IntoIterator<Item = &'a String>,
+) -> Result<(), PackagerError> {
+    let mut folded = BTreeSet::new();
+    for path in paths {
+        if !folded.insert(path.to_ascii_lowercase()) {
+            return Err(PackagerError::Invalid(format!(
+                "package path collides case-insensitively: {path}"
+            )));
+        }
+    }
+    Ok(())
+}
+
+fn write_archive(
+    output: &mut File,
+    manifest: &[u8],
+    main_path: &str,
+    files: &BTreeMap<String, Vec<u8>>,
+) -> Result<(), PackagerError> {
+    let encoder = GzBuilder::new().mtime(0).write(output, Compression::best());
+    let limited = LimitedWriter::new(encoder, MAXIMUM_EXPANDED_BYTES);
+    let mut archive = Builder::new(limited);
+    archive.mode(HeaderMode::Deterministic);
+    append_file(&mut archive, "plugin.json", manifest, 0o644)?;
+    for (path, bytes) in files {
+        let mode = if path == main_path { 0o755 } else { 0o644 };
+        append_file(&mut archive, path, bytes, mode)?;
+    }
+    archive.finish().map_err(|source| PackagerError::Io {
+        action: "finish archive",
+        path: PathBuf::from("<temporary archive>"),
+        source,
+    })?;
+    let limited = archive.into_inner().map_err(|source| PackagerError::Io {
+        action: "finish archive",
+        path: PathBuf::from("<temporary archive>"),
+        source,
+    })?;
+    limited
+        .into_inner()
+        .finish()
+        .map_err(|source| PackagerError::Io {
+            action: "finish compression",
+            path: PathBuf::from("<temporary archive>"),
+            source,
+        })?;
+    Ok(())
+}
+
+fn append_file<W: io::Write>(
+    archive: &mut Builder<W>,
+    path: &str,
+    bytes: &[u8],
+    mode: u32,
+) -> Result<(), PackagerError> {
+    let mut header = Header::new_gnu();
+    header.set_entry_type(EntryType::Regular);
+    header.set_mode(mode);
+    header.set_uid(0);
+    header.set_gid(0);
+    header.set_mtime(0);
+    header.set_size(bytes.len() as u64);
+    header.set_cksum();
+    archive
+        .append_data(&mut header, path, bytes)
+        .map_err(|source| PackagerError::Io {
+            action: "append archive entry",
+            path: PathBuf::from(path),
+            source,
+        })
+}
+
+struct LimitedWriter<W> {
+    inner: W,
+    written: u64,
+    maximum: u64,
+}
+
+impl<W> LimitedWriter<W> {
+    const fn new(inner: W, maximum: u64) -> Self {
+        Self {
+            inner,
+            written: 0,
+            maximum,
+        }
+    }
+
+    fn into_inner(self) -> W {
+        self.inner
+    }
+}
+
+impl<W> io::Write for LimitedWriter<W>
+where
+    W: io::Write,
+{
+    fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
+        let length = u64::try_from(bytes.len())
+            .map_err(|_| io::Error::other("plugin package exceeds expanded size limit"))?;
+        if length > self.maximum.saturating_sub(self.written) {
+            return Err(io::Error::other(
+                "plugin package exceeds expanded size limit",
+            ));
+        }
+        let written = self.inner.write(bytes)?;
+        self.written = self
+            .written
+            .checked_add(written as u64)
+            .ok_or_else(|| io::Error::other("plugin package size overflow"))?;
+        Ok(written)
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        self.inner.flush()
+    }
+}
+
+struct TemporaryFile {
+    path: PathBuf,
+    file: File,
+}
+
+impl TemporaryFile {
+    fn create(path: PathBuf) -> Result<Self, PackagerError> {
+        let file = OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .open(&path)
+            .map_err(|source| PackagerError::Io {
+                action: "create",
+                path: path.clone(),
+                source,
+            })?;
+        Ok(Self { path, file })
+    }
+
+    fn path(&self) -> &Path {
+        &self.path
+    }
+
+    fn file_mut(&mut self) -> &mut File {
+        &mut self.file
+    }
+
+    fn sync_all(&mut self) -> Result<(), PackagerError> {
+        let path = self.path.clone();
+        self.file_mut()
+            .sync_all()
+            .map_err(|source| PackagerError::Io {
+                action: "sync",
+                path,
+                source,
+            })
+    }
+
+    fn metadata_len(&self) -> Result<u64, PackagerError> {
+        self.file
+            .metadata()
+            .map(|metadata| metadata.len())
+            .map_err(|source| PackagerError::Io {
+                action: "inspect",
+                path: self.path.clone(),
+                source,
+            })
+    }
+
+    fn persist(mut self, destination: &Path) -> Result<(), PackagerError> {
+        fs::rename(&self.path, destination).map_err(|source| PackagerError::Io {
+            action: "publish",
+            path: destination.to_owned(),
+            source,
+        })?;
+        self.path.clear();
+        Ok(())
+    }
+}
+
+impl Drop for TemporaryFile {
+    fn drop(&mut self) {
+        if !self.path.as_os_str().is_empty() {
+            let _ = fs::remove_file(&self.path);
+        }
+    }
+}
+
+fn read_regular_file(path: &Path, maximum_bytes: u64) -> Result<Vec<u8>, PackagerError> {
+    let metadata = fs::symlink_metadata(path).map_err(|source| PackagerError::Io {
+        action: "inspect",
+        path: path.to_owned(),
+        source,
+    })?;
+    if !metadata.file_type().is_file() || metadata.file_type().is_symlink() {
+        return Err(PackagerError::Invalid(format!(
+            "package input must be a regular non-symlink file: {}",
+            path.display()
+        )));
+    }
+    if metadata.len() > maximum_bytes {
+        return Err(package_limit());
+    }
+    let file = File::open(path).map_err(|source| PackagerError::Io {
+        action: "open",
+        path: path.to_owned(),
+        source,
+    })?;
+    let mut bytes = Vec::with_capacity(usize::try_from(metadata.len()).unwrap_or_default());
+    file.take(maximum_bytes.saturating_add(1))
+        .read_to_end(&mut bytes)
+        .map_err(|source| PackagerError::Io {
+            action: "read",
+            path: path.to_owned(),
+            source,
+        })?;
+    if bytes.len() as u64 > maximum_bytes {
+        return Err(package_limit());
+    }
+    Ok(bytes)
+}
+
+fn canonicalize(path: &Path) -> Result<PathBuf, PackagerError> {
+    fs::canonicalize(path).map_err(|source| PackagerError::Io {
+        action: "canonicalize",
+        path: path.to_owned(),
+        source,
+    })
+}
+
+fn create_directory(path: &Path) -> Result<(), PackagerError> {
+    fs::create_dir_all(path).map_err(|source| PackagerError::Io {
+        action: "create directory",
+        path: path.to_owned(),
+        source,
+    })
+}
+
+fn sha256_file(path: &Path) -> Result<String, PackagerError> {
+    let mut file = File::open(path).map_err(|source| PackagerError::Io {
+        action: "open",
+        path: path.to_owned(),
+        source,
+    })?;
+    let mut digest = Sha256::new();
+    let mut buffer = [0u8; 64 * 1024];
+    loop {
+        let read = file.read(&mut buffer).map_err(|source| PackagerError::Io {
+            action: "hash",
+            path: path.to_owned(),
+            source,
+        })?;
+        if read == 0 {
+            break;
+        }
+        digest.update(&buffer[..read]);
+    }
+    Ok(hex::encode(digest.finalize()))
+}
+
+fn package_limit() -> PackagerError {
+    PackagerError::Invalid("plugin package exceeds installation size limits".to_owned())
+}
diff --git a/backend/apps/plugin-cli/tests/main.rs b/backend/apps/plugin-cli/tests/main.rs
new file mode 100644
index 000000000..3f7971ec6
--- /dev/null
+++ b/backend/apps/plugin-cli/tests/main.rs
@@ -0,0 +1,267 @@
+use std::{
+    collections::BTreeMap,
+    fs::{self, File},
+    io::Read as _,
+    process::{Command, Output},
+};
+
+use flate2::read::MultiGzDecoder;
+use gateway_plugin_sdk::{Capability, MANIFEST_VERSION, Manifest, PROTOCOL_VERSION, Stage};
+use sha2::{Digest as _, Sha256};
+
+fn cli(arguments: &[&str]) -> Output {
+    Command::new(env!("CARGO_BIN_EXE_cpr-plugin"))
+        .args(arguments)
+        .output()
+        .unwrap()
+}
+
+fn assert_rejected(arguments: &[&str], message: &str) {
+    let output = cli(arguments);
+    assert!(
+        !output.status.success(),
+        "{arguments:?} unexpectedly succeeded"
+    );
+    assert!(
+        String::from_utf8_lossy(&output.stderr).contains(message),
+        "{arguments:?}: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+}
+
+fn package_arguments() -> Vec<&'static str> {
+    vec![
+        "package",
+        "--manifest",
+        "plugin.json",
+        "--binary",
+        "plugin-bin",
+        "--target",
+        "x86_64-unknown-linux-gnu",
+        "--output-dir",
+        "dist",
+    ]
+}
+
+#[test]
+fn root_help_lists_package_command() {
+    let output = cli(&["--help"]);
+    assert!(output.status.success());
+    let help = String::from_utf8(output.stdout).unwrap();
+    assert!(help.contains("cpr-plugin <COMMAND>"), "{help}");
+    assert!(help.contains("package"), "{help}");
+}
+
+#[test]
+fn version_uses_the_user_command_name() {
+    let output = cli(&["--version"]);
+    assert!(output.status.success());
+    assert_eq!(
+        String::from_utf8(output.stdout).unwrap(),
+        format!("cpr-plugin {}\n", env!("CARGO_PKG_VERSION"))
+    );
+}
+
+#[test]
+fn package_help_does_not_require_inputs() {
+    let output = cli(&["package", "--help"]);
+    assert!(output.status.success());
+    let help = String::from_utf8(output.stdout).unwrap();
+    assert!(help.contains("cpr-plugin package"), "{help}");
+    assert!(help.contains("--resource-map"), "{help}");
+}
+
+#[test]
+fn rejects_missing_subcommand() {
+    assert_rejected(&[], "Usage: cpr-plugin");
+}
+
+#[test]
+fn rejects_unknown_subcommand() {
+    assert_rejected(&["publish"], "unrecognized subcommand");
+}
+
+#[test]
+fn rejects_missing_package_arguments() {
+    assert_rejected(&["package"], "--manifest");
+}
+
+#[test]
+fn rejects_duplicate_single_value_options() {
+    let mut arguments = package_arguments();
+    arguments.extend(["--manifest", "other.json"]);
+    assert_rejected(&arguments, "cannot be used multiple times");
+}
+
+#[test]
+fn rejects_unknown_targets() {
+    let mut arguments = package_arguments();
+    arguments[6] = "x86_64-pc-windows-msvc";
+    assert_rejected(&arguments, "unsupported plugin target");
+}
+
+#[test]
+fn rejects_unsafe_resource_mappings_before_reading_files() {
+    for (mapping, message) in [
+        ("web=../web/dist", "project-relative path"),
+        ("web=/web/dist", "project-relative path"),
+        ("web=", "project-relative path"),
+        ("web/assets=web/dist", "invalid resource-map package prefix"),
+        ("web", "must use package-prefix=source-directory"),
+    ] {
+        let mut arguments = package_arguments();
+        arguments.extend(["--resource-map", mapping]);
+        assert_rejected(&arguments, message);
+    }
+}
+
+#[test]
+fn rejects_duplicate_resource_prefixes() {
+    let mut arguments = package_arguments();
+    arguments.extend([
+        "--resource-map",
+        "web=web/dist",
+        "--resource-map",
+        "web=other",
+    ]);
+    assert_rejected(&arguments, "duplicate resource-map package prefix");
+}
+
+#[test]
+fn packages_only_generated_resources_with_v3_metadata() {
+    assert_packaged_resources("assets/icon.png", "image/png", b"png");
+}
+
+#[test]
+fn packages_svg_icons_with_their_declared_mime_and_digest() {
+    assert_packaged_resources(
+        "assets/icon.svg",
+        "image/svg+xml",
+        br#"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M2 2h20v20H2z"/></svg>"#,
+    );
+}
+
+fn assert_packaged_resources(icon_path: &str, icon_mime: &str, icon: &[u8]) {
+    let directory = tempfile::tempdir().unwrap();
+    let project = directory.path().join("example");
+    fs::create_dir_all(project.join("web/dist")).unwrap();
+    fs::create_dir_all(project.join("assets")).unwrap();
+    let mut source: serde_json::Value = serde_json::from_slice(source_manifest()).unwrap();
+    source["icon"] = icon_path.into();
+    let resources = source["resources"].as_object_mut().unwrap();
+    resources.remove("assets/icon.png");
+    resources.insert(icon_path.into(), icon_mime.into());
+    fs::write(
+        project.join("plugin.json"),
+        serde_json::to_vec(&source).unwrap(),
+    )
+    .unwrap();
+    fs::write(project.join("LICENSE"), b"license").unwrap();
+    fs::write(project.join(icon_path), icon).unwrap();
+    fs::write(project.join("plugin-bin"), b"binary").unwrap();
+    fs::write(project.join("web/index.html"), b"source html").unwrap();
+    fs::write(project.join("web/dist/index.html"), b"built html").unwrap();
+    fs::write(project.join("web/dist/app.js"), b"built js").unwrap();
+    fs::write(project.join("web/dist/app.css"), b"built css").unwrap();
+
+    let output = Command::new(env!("CARGO_BIN_EXE_cpr-plugin"))
+        .arg("package")
+        .arg("--manifest")
+        .arg(project.join("plugin.json"))
+        .arg("--binary")
+        .arg(project.join("plugin-bin"))
+        .args(["--target", "x86_64-unknown-linux-gnu"])
+        .arg("--output-dir")
+        .arg(project.join("dist"))
+        .args(["--resource-map", "web=web/dist"])
+        .output()
+        .unwrap();
+    assert!(
+        output.status.success(),
+        "{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+
+    let archive_name = "codex-proxy.request-workbench-0.1.0-x86_64-unknown-linux-gnu.tar.gz";
+    let archive_path = project.join("dist").join(archive_name);
+    let checksum_path = project.join("dist").join(format!("{archive_name}.sha256"));
+    assert_eq!(
+        String::from_utf8(output.stdout).unwrap(),
+        format!("{}\n{}\n", archive_path.display(), checksum_path.display())
+    );
+    let archive = File::open(&archive_path).unwrap();
+    let mut package = tar::Archive::new(MultiGzDecoder::new(archive));
+    let mut entries = BTreeMap::new();
+    for entry in package.entries().unwrap() {
+        let mut entry = entry.unwrap();
+        let path = entry.path().unwrap().to_string_lossy().into_owned();
+        let mut bytes = Vec::new();
+        entry.read_to_end(&mut bytes).unwrap();
+        entries.insert(path, bytes);
+    }
+    assert_eq!(
+        entries.keys().cloned().collect::<Vec<_>>(),
+        vec![
+            "LICENSE".to_owned(),
+            icon_path.to_owned(),
+            "bin/plugin".to_owned(),
+            "plugin.json".to_owned(),
+            "web/app.css".to_owned(),
+            "web/app.js".to_owned(),
+            "web/index.html".to_owned(),
+        ]
+    );
+    assert_eq!(entries["web/index.html"], b"built html");
+    let manifest: Manifest = serde_json::from_slice(&entries["plugin.json"]).unwrap();
+    assert_eq!(manifest.manifest_version, MANIFEST_VERSION);
+    assert_eq!(
+        manifest.contributes[&Capability::Middleware].id,
+        "codex-proxy.request-workbench.middleware"
+    );
+    assert_eq!(
+        manifest.contributes[&Capability::Management].stages,
+        [Stage::Management]
+    );
+    assert_eq!(
+        manifest.contributes[&Capability::Executor].input_formats,
+        ["openai"]
+    );
+    assert_eq!(
+        manifest.contributes[&Capability::Quota].stages,
+        [Stage::Management, Stage::Maintenance]
+    );
+    assert_eq!(manifest.resources[icon_path], icon_mime);
+    assert_eq!(entries[icon_path], icon);
+    let package = manifest.package.unwrap();
+    assert_eq!(package.files[icon_path], hex::encode(Sha256::digest(icon)));
+    assert_eq!(package.protocol_version, PROTOCOL_VERSION);
+    assert_eq!(package.target.os, "linux");
+    assert_eq!(package.target.architecture, "x86_64");
+    assert_eq!(package.files.len(), 6);
+    let checksum = fs::read_to_string(checksum_path).unwrap();
+    let digest = hex::encode(Sha256::digest(fs::read(archive_path).unwrap()));
+    assert_eq!(checksum, format!("{digest}  {archive_name}\n"));
+}
+
+fn source_manifest() -> &'static [u8] {
+    br#"{
+      "manifestVersion":3,
+      "name":"request-workbench",
+      "displayName":"Request Workbench",
+      "publisher":"codex-proxy",
+      "version":"0.1.0",
+      "description":"test package",
+      "license":"Apache-2.0",
+      "engines":{"codex-proxy-rs":">=3.12.0, <4.0.0"},
+      "main":"bin/plugin",
+      "runtime":"trustedProcess",
+      "contributes":{
+        "middleware":{"stages":["request"],"inputFormats":["openai"],"outputFormats":["openai"]},
+        "management":{},
+        "provider":{"capabilities":["quota"],"inputFormats":["openai"],"outputFormats":["openai"]}
+      },
+      "permissions":["requests","accounts"],
+      "icon":"assets/icon.png",
+      "resources":{"LICENSE":"text/plain","assets/icon.png":"image/png","web/index.html":"text/html","web/app.js":"text/javascript","web/app.css":"text/css"}
+    }"#
+}
diff --git a/backend/crates/gateway-admin/Cargo.toml b/backend/crates/gateway-admin/Cargo.toml
index 9345fea2a..43de20175 100644
--- a/backend/crates/gateway-admin/Cargo.toml
+++ b/backend/crates/gateway-admin/Cargo.toml
@@ -16,7 +16,7 @@ argon2 = "0.6.0"
 async-trait = "0.1.89"
 base64 = "0.23.0"
 bytes = "1.11.1"
-chrono = "0.4.45"
+chrono = { version = "0.4.45", features = ["serde"] }
 futures = "0.3.32"
 gateway-core = { path = "../gateway-core" }
 heck = "0.5.0"
@@ -25,6 +25,7 @@ rand_core = { version = "0.6.4", features = ["getrandom"] }
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
 secrecy = { version = "0.10.3", features = ["serde"] }
+semver = "1.0.27"
 sha2 = "0.11"
 subtle = "2.6.1"
 thiserror = "2.0.18"
diff --git a/backend/crates/gateway-admin/src/lib.rs b/backend/crates/gateway-admin/src/lib.rs
index b0ac21a79..ac6ed3830 100644
--- a/backend/crates/gateway-admin/src/lib.rs
+++ b/backend/crates/gateway-admin/src/lib.rs
@@ -7,7 +7,6 @@ use std::{fmt, path::Path, sync::Arc, time::Duration};
 use gateway_core::{
     engine::execution::ClientKeyVerifier,
     engine::probe::AccountProbe,
-    routing::ProviderKind,
     runtime::SnapshotControl,
     task::{
         DaemonRestartPolicy, WorkerContribution, WorkerId, WorkerKind, WorkerLeaseRequest,
@@ -22,34 +21,39 @@ pub mod freeze_recovery;
 pub mod model;
 pub mod ports;
 mod use_case;
+pub use use_case::plugins::{PluginDistributionPorts, PluginManagementService, PluginsService};
 
 pub use use_case::key_usage::KeyUsageService;
 
 pub use use_case::{
-    account_groups::AccountGroupService, accounts::AccountsService, auth::AuthService,
-    backup::BackupService, client_distribution::ClientDistributionService,
-    client_keys::ClientKeyService, import_tasks::ImportTasksService,
-    observability::ObservabilityService, openai::OpenAiService, proxies::ProxiesService,
-    settings::SettingsService, system::SystemService, xai::XaiService,
+    account_groups::AccountGroupService,
+    accounts::AccountsService,
+    auth::AuthService,
+    backup::BackupService,
+    client_distribution::ClientDistributionService,
+    client_keys::ClientKeyService,
+    credentials::{CredentialsService, ProviderCredentials},
+    import_tasks::ImportTasksService,
+    observability::ObservabilityService,
+    proxies::ProxiesService,
+    settings::SettingsService,
+    system::SystemService,
 };
 
-use model::{AdminError, AdminErrorKind};
+use model::AdminError;
 use ports::{
-    client_distribution::ClientDistributionResolver,
-    provider::{ProviderAdmin, ProviderAdminError, ProviderAdminErrorKind, ProviderAdminRegistry},
-    store::AdminStorePorts,
-    system::SystemOperations,
+    client_distribution::ClientDistributionResolver, plugin_accounts::PluginAccountAccess,
+    plugin_client_keys::PluginClientKeyAccess, provider::ProviderAdminRegistry,
+    store::AdminStorePorts, system::SystemOperations,
 };
 use use_case::{
     account_groups::DefaultAccountGroupService, accounts::DefaultAccountsService,
     auth::DefaultAuthService, backup::DefaultBackupService,
     client_distribution::DefaultClientDistributionService, client_keys::DefaultClientKeyService,
-    observability::DefaultObservabilityService, openai::DefaultOpenAiService,
-    settings::DefaultSettingsService, system::DefaultSystemService, xai::DefaultXaiService,
+    observability::DefaultObservabilityService, settings::DefaultSettingsService,
+    system::DefaultSystemService,
 };
 
-const OPENAI_PROVIDER_KIND: &str = "openai";
-const XAI_PROVIDER_KIND: &str = "xai";
 const MINIMUM_INITIAL_PASSWORD_BYTES: usize = 12;
 const WEAK_ADMIN_PASSWORDS: &[&str] = &[
     "",
@@ -182,6 +186,8 @@ pub enum AdminConfigError {
 /// 字段全部私有；调用方经 accessor 直接调用能力，不需要命名内部 `use_case` 模块。
 #[derive(Clone)]
 pub struct AdminServices {
+    plugins: Arc<PluginsService>,
+    plugin_management: Arc<PluginManagementService>,
     proxies: Arc<dyn ProxiesService>,
     auth: Arc<dyn AuthService>,
     key_usage: Arc<dyn KeyUsageService>,
@@ -192,13 +198,23 @@ pub struct AdminServices {
     observability: Arc<dyn ObservabilityService>,
     settings: Arc<dyn SettingsService>,
     system: Arc<dyn SystemService>,
-    openai: Arc<dyn OpenAiService>,
-    xai: Arc<dyn XaiService>,
+    credentials: Arc<CredentialsService>,
+    plugin_accounts: Arc<dyn PluginAccountAccess>,
     backups: Arc<dyn BackupService>,
     import_tasks: Arc<dyn ImportTasksService>,
 }
 
 impl AdminServices {
+    #[must_use]
+    pub fn plugin_management(&self) -> &PluginManagementService {
+        &self.plugin_management
+    }
+
+    #[must_use]
+    pub fn plugins(&self) -> &PluginsService {
+        &self.plugins
+    }
+
     #[must_use]
     pub fn import_tasks(&self) -> &dyn ImportTasksService {
         self.import_tasks.as_ref()
@@ -261,13 +277,14 @@ impl AdminServices {
     }
 
     #[must_use]
-    pub fn openai(&self) -> &dyn OpenAiService {
-        self.openai.as_ref()
+    pub fn credentials(&self) -> &CredentialsService {
+        self.credentials.as_ref()
     }
 
+    /// Runtime 只持有该窄端口的 Weak；AdminBundle 保持实际生命周期。
     #[must_use]
-    pub fn xai(&self) -> &dyn XaiService {
-        self.xai.as_ref()
+    pub fn plugin_accounts_handle(&self) -> Arc<dyn PluginAccountAccess> {
+        Arc::clone(&self.plugin_accounts)
     }
 
     #[must_use]
@@ -296,8 +313,13 @@ impl AdminBundle {
 
 /// 组合根提供给控制面的运行能力；与配置和存储端口分别传入。
 pub struct AdminRuntimePorts {
+    pub plugin_preparation: Arc<dyn ports::plugins::PluginPreparation>,
+    pub plugin_management: Arc<dyn ports::plugin_management::PluginManagement>,
+    pub published_snapshot: gateway_core::runtime::RuntimeSnapshotHandle,
+    pub plugin_distribution: Arc<dyn ports::plugins::PluginDistribution>,
+    pub plugin_inspector: Arc<dyn ports::plugins::PluginPackageInspector>,
     pub pricing_source: Arc<dyn ports::pricing::PricingSource>,
-    pub providers: Vec<Arc<dyn ProviderAdmin>>,
+    pub providers: ProviderAdminRegistry,
     pub snapshot: Arc<dyn SnapshotControl>,
     pub account_probe: Arc<dyn AccountProbe>,
     pub proxy_probe: Arc<dyn ports::proxy::ProxyProbe>,
@@ -306,18 +328,44 @@ pub struct AdminRuntimePorts {
     pub client_key_verifier: Arc<dyn ClientKeyVerifier>,
 }
 
-/// 校验配置、建立动态 Provider 注册表并完成默认管理员幂等初始化。
+/// 校验配置、接入已组装的 Provider 注册表并完成默认管理员幂等初始化。
 ///
 /// # Errors
 ///
-/// 配置非法、Provider 注册冲突/缺失或默认管理员初始化失败时返回错误。
+/// 配置非法或默认管理员初始化失败时返回错误。
 pub async fn initialize(
+    config: AdminConfig,
+    client_config: ClientConfig,
+    store: AdminStorePorts,
+    runtime: AdminRuntimePorts,
+) -> Result<AdminBundle, AdminError> {
+    initialize_inner(config, client_config, store, runtime, None).await
+}
+
+/// 使用组合根已绑定给 Runtime 的同一账号窄端口，避免为完整 Admin 重建第二实例。
+pub async fn initialize_with_plugin_accounts(
+    config: AdminConfig,
+    client_config: ClientConfig,
+    store: AdminStorePorts,
+    runtime: AdminRuntimePorts,
+    plugin_accounts: Arc<dyn PluginAccountAccess>,
+) -> Result<AdminBundle, AdminError> {
+    initialize_inner(config, client_config, store, runtime, Some(plugin_accounts)).await
+}
+
+async fn initialize_inner(
     mut config: AdminConfig,
     mut client_config: ClientConfig,
     store: AdminStorePorts,
     runtime: AdminRuntimePorts,
+    plugin_accounts: Option<Arc<dyn PluginAccountAccess>>,
 ) -> Result<AdminBundle, AdminError> {
     let AdminRuntimePorts {
+        plugin_preparation,
+        plugin_management,
+        published_snapshot,
+        plugin_distribution,
+        plugin_inspector,
         pricing_source,
         providers,
         snapshot,
@@ -333,13 +381,7 @@ pub async fn initialize(
     client_config
         .resolve_and_validate(Path::new("."))
         .map_err(|error| AdminError::invalid(error.to_string()))?;
-    let registry = ProviderAdminRegistry::new(providers).map_err(map_provider_registry_error)?;
-    let openai = registry
-        .require(&provider_kind(OPENAI_PROVIDER_KIND)?)
-        .map_err(map_provider_registry_error)?;
-    let xai = registry
-        .require(&provider_kind(XAI_PROVIDER_KIND)?)
-        .map_err(map_provider_registry_error)?;
+    let registry = providers;
 
     let auth = Arc::new(DefaultAuthService::new(
         config.default_username,
@@ -370,7 +412,11 @@ pub async fn initialize(
         backup_ports.dump(),
         backup_ports.object_store(),
     );
-    let system = Arc::new(DefaultSystemService::new(system));
+    let system_preflight = Arc::new(use_case::plugin_update::PluginSystemUpdatePreflight::new(
+        store.plugins(),
+        plugin_inspector.clone(),
+    ));
+    let system = Arc::new(DefaultSystemService::new(system, system_preflight));
     let key_usage = Arc::new(use_case::key_usage::DefaultKeyUsageService::new(
         auth.clone(),
         client_key_verifier,
@@ -378,22 +424,32 @@ pub async fn initialize(
         store.observability(),
         system.clone(),
     ));
-    let openai = Arc::new(DefaultOpenAiService::new(
-        openai,
+    let credentials = Arc::new(CredentialsService::new(
+        registry.clone(),
         store.accounts(),
         store.proxies(),
         snapshot.clone(),
     ));
-    let xai = Arc::new(DefaultXaiService::new(
-        xai,
-        store.accounts(),
-        store.proxies(),
-        snapshot.clone(),
-    ));
-    let import_tasks =
-        use_case::import_tasks::DefaultImportTasksService::new(openai.clone(), xai.clone());
+    let plugin_accounts = plugin_accounts.unwrap_or_else(|| {
+        initialize_plugin_accounts(registry.clone(), store.accounts(), snapshot.clone())
+    });
+    let import_tasks = use_case::import_tasks::DefaultImportTasksService::new(credentials.clone());
     let import_task = use_case::import_tasks::ImportTaskWorker(import_tasks.clone());
     let services = AdminServices {
+        plugin_management: Arc::new(PluginManagementService::new(
+            plugin_management,
+            store.plugins(),
+            published_snapshot.clone(),
+        )),
+        plugins: Arc::new(PluginsService::new(
+            store.plugins(),
+            plugin_inspector,
+            PluginDistributionPorts::new(plugin_distribution, store.proxies()),
+            snapshot.clone(),
+            plugin_preparation,
+            published_snapshot,
+            store.plugin_state(),
+        )),
         key_usage,
         proxies: Arc::new(use_case::proxies::DefaultProxiesService::new(
             store.proxies(),
@@ -427,8 +483,8 @@ pub async fn initialize(
             pricing_source,
         )),
         system,
-        openai,
-        xai,
+        credentials,
+        plugin_accounts,
         import_tasks,
         backups,
     };
@@ -460,6 +516,29 @@ pub async fn initialize(
     })
 }
 
+/// CLI 只组合账号用例，不初始化管理员、管理服务或后台任务；写入仍复用同一事务与审计。
+pub fn initialize_plugin_accounts(
+    providers: ports::provider::ProviderAdminRegistry,
+    accounts: Arc<dyn ports::store::AccountStore>,
+    snapshot: Arc<dyn gateway_core::runtime::SnapshotControl>,
+) -> Arc<dyn PluginAccountAccess> {
+    Arc::new(use_case::plugin_accounts::DefaultPluginAccountAccess::new(
+        providers, accounts, snapshot,
+    ))
+}
+
+/// 为 Runtime 创建只暴露非秘密 Client Key 目录的窄端口。
+#[must_use]
+pub fn initialize_plugin_client_keys(
+    providers: ports::provider::ProviderAdminRegistry,
+    store: Arc<dyn ports::store::ClientKeyStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+) -> Arc<dyn PluginClientKeyAccess> {
+    let service: Arc<dyn ClientKeyService> =
+        Arc::new(DefaultClientKeyService::new(store, snapshot, providers));
+    Arc::new(use_case::plugin_client_keys::DefaultPluginClientKeyAccess::new(service))
+}
+
 /// Backup Worker 注册：单个可取消 Daemon，owner 固定为 `backup`。
 fn backup_worker_contribution(
     task: backup::task::BackupTask,
@@ -509,24 +588,3 @@ fn freeze_recovery_worker_contribution(
     .map_err(|_| AdminError::internal("冻结恢复 Worker 注册信息不合法"))?;
     Ok(vec![WorkerContribution::Registration(registration)])
 }
-
-fn provider_kind(value: &'static str) -> Result<ProviderKind, AdminError> {
-    ProviderKind::new(value).map_err(|_| AdminError::internal("内置 Provider 类型不合法"))
-}
-
-fn map_provider_registry_error(error: ProviderAdminError) -> AdminError {
-    let kind = match error.kind() {
-        ProviderAdminErrorKind::Invalid | ProviderAdminErrorKind::Unsupported => {
-            AdminErrorKind::Invalid
-        }
-        ProviderAdminErrorKind::NotFound => AdminErrorKind::NotFound,
-        ProviderAdminErrorKind::Conflict => AdminErrorKind::Conflict,
-        ProviderAdminErrorKind::Ambiguous => AdminErrorKind::UpstreamResultUnknown,
-        ProviderAdminErrorKind::Unavailable | ProviderAdminErrorKind::CredentialRefreshRequired => {
-            AdminErrorKind::Unavailable
-        }
-        ProviderAdminErrorKind::BadGateway => AdminErrorKind::BadGateway,
-        ProviderAdminErrorKind::Internal => AdminErrorKind::Internal,
-    };
-    AdminError::new(kind, "Provider 注册表初始化失败")
-}
diff --git a/backend/crates/gateway-admin/src/model/accounts.rs b/backend/crates/gateway-admin/src/model/accounts.rs
index 29abee64d..ff78ec446 100644
--- a/backend/crates/gateway-admin/src/model/accounts.rs
+++ b/backend/crates/gateway-admin/src/model/accounts.rs
@@ -204,6 +204,8 @@ pub struct AccountPage {
     pub items: Vec<AccountPageItem>,
     pub total: u64,
     pub summary: AccountSummary,
+    /// 全部持久化账号的平台，不受筛选、分页和插件启停影响。
+    pub providers: Vec<String>,
 }
 
 /// 同一状态快照下的账号事实与唯一状态投影。
diff --git a/backend/crates/gateway-admin/src/model/auth.rs b/backend/crates/gateway-admin/src/model/auth.rs
index b99129144..0ef5af021 100644
--- a/backend/crates/gateway-admin/src/model/auth.rs
+++ b/backend/crates/gateway-admin/src/model/auth.rs
@@ -101,7 +101,8 @@ impl From<ClientAuthenticationError> for LoginError {
     fn from(error: ClientAuthenticationError) -> Self {
         match error {
             ClientAuthenticationError::InvalidKey => Self::InvalidCredentials,
-            ClientAuthenticationError::SnapshotUnavailable => Self::Unavailable,
+            ClientAuthenticationError::SnapshotUnavailable
+            | ClientAuthenticationError::ProviderUnavailable => Self::Unavailable,
         }
     }
 }
diff --git a/backend/crates/gateway-admin/src/model/client_keys.rs b/backend/crates/gateway-admin/src/model/client_keys.rs
index 36d523388..0cc99dfce 100644
--- a/backend/crates/gateway-admin/src/model/client_keys.rs
+++ b/backend/crates/gateway-admin/src/model/client_keys.rs
@@ -1,6 +1,6 @@
 //! Client API Key 的 Command、Result 与安全秘密类型。
 
-use std::{fmt, num::NonZeroU16};
+use std::{collections::BTreeMap, fmt, num::NonZeroU16};
 
 use chrono::{DateTime, Utc};
 
@@ -12,6 +12,11 @@ use gateway_core::{
 
 use super::{AdminModelError, Revision, account_groups::AccountGroupRef};
 
+pub type ProviderRequestProfileOverrides =
+    BTreeMap<ProviderKind, gateway_core::account::OpaqueProviderData>;
+pub type ProviderRequestProfileOverrideUpdates =
+    BTreeMap<ProviderKind, Option<gateway_core::account::OpaqueProviderData>>;
+
 /// Client Key 列表保持旧 HTTP 合同允许的完整非零 `u16` 页大小。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct ClientKeyPageSize(NonZeroU16);
@@ -86,8 +91,7 @@ pub struct ClientKeyListQuery {
 /// 不含完整明文 Key 的管理投影。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientKeyRecord {
-    pub openai_client_profile_override: Option<gateway_core::account::OpaqueProviderData>,
-    pub xai_client_profile_override: Option<gateway_core::account::OpaqueProviderData>,
+    pub request_profile_overrides: ProviderRequestProfileOverrides,
     pub id: ClientApiKeyId,
     pub name: String,
     pub label: Option<String>,
@@ -146,8 +150,7 @@ impl fmt::Debug for ClientKeySecret {
 /// API 提交的 Client Key 创建命令。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CreateClientKey {
-    pub openai_client_profile_override: Option<gateway_core::account::OpaqueProviderData>,
-    pub xai_client_profile_override: Option<gateway_core::account::OpaqueProviderData>,
+    pub request_profile_overrides: ProviderRequestProfileOverrides,
     pub custom_key: Option<PlaintextClientApiKey>,
     pub name: String,
     pub label: Option<String>,
@@ -159,8 +162,7 @@ pub struct CreateClientKey {
 /// 管理用例生成 ID 与明文后的持久化命令。
 #[derive(Clone, PartialEq, Eq)]
 pub struct NewClientKey {
-    pub openai_client_profile_override: Option<gateway_core::account::OpaqueProviderData>,
-    pub xai_client_profile_override: Option<gateway_core::account::OpaqueProviderData>,
+    pub request_profile_overrides: ProviderRequestProfileOverrides,
     pub id: ClientApiKeyId,
     pub name: String,
     pub label: Option<String>,
@@ -185,8 +187,7 @@ impl fmt::Debug for NewClientKey {
 /// 修改 Client Key 的公开策略字段。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UpdateClientKey {
-    pub openai_client_profile_override: Option<Option<gateway_core::account::OpaqueProviderData>>,
-    pub xai_client_profile_override: Option<Option<gateway_core::account::OpaqueProviderData>>,
+    pub request_profile_override_updates: ProviderRequestProfileOverrideUpdates,
     pub id: ClientApiKeyId,
     pub name: String,
     pub label: Option<String>,
diff --git a/backend/crates/gateway-admin/src/model/mod.rs b/backend/crates/gateway-admin/src/model/mod.rs
index ae3d474f4..9ad361505 100644
--- a/backend/crates/gateway-admin/src/model/mod.rs
+++ b/backend/crates/gateway-admin/src/model/mod.rs
@@ -11,7 +11,10 @@ pub mod client_keys;
 pub mod import_tasks;
 pub mod key_usage;
 pub mod observability;
+pub mod plugin_client_keys;
+pub mod plugins;
 pub mod pricing;
+pub mod provider_capabilities;
 pub mod provider_credentials;
 pub mod proxies;
 pub mod quota_forecast;
diff --git a/backend/crates/gateway-admin/src/model/plugin_client_keys.rs b/backend/crates/gateway-admin/src/model/plugin_client_keys.rs
new file mode 100644
index 000000000..e43c1d2e5
--- /dev/null
+++ b/backend/crates/gateway-admin/src/model/plugin_client_keys.rs
@@ -0,0 +1,31 @@
+//! 插件可见的 Client Key 非秘密资源投影。
+
+use gateway_core::policy::ClientApiKeyId;
+
+use super::PageSize;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginClientKeyCursor {
+    pub name: String,
+    pub id: ClientApiKeyId,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginClientKeyListQuery {
+    pub cursor: Option<PluginClientKeyCursor>,
+    pub limit: PageSize,
+}
+
+/// 插件只能发现调用所需的公开身份，不取得 Key 前缀、策略细节或明文。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginClientKey {
+    pub id: ClientApiKeyId,
+    pub name: String,
+    pub enabled: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginClientKeyPage {
+    pub items: Vec<PluginClientKey>,
+    pub next_cursor: Option<PluginClientKeyCursor>,
+}
diff --git a/backend/crates/gateway-admin/src/model/plugins/distribution.rs b/backend/crates/gateway-admin/src/model/plugins/distribution.rs
new file mode 100644
index 000000000..39719e279
--- /dev/null
+++ b/backend/crates/gateway-admin/src/model/plugins/distribution.rs
@@ -0,0 +1,231 @@
+use std::{fmt, sync::Arc};
+
+use chrono::{DateTime, Utc};
+use gateway_core::account::OutboundProxy;
+use secrecy::SecretString;
+use serde::{Deserialize, Serialize};
+
+use super::{PluginArtifactMetadata, PluginSource, PluginSourceEgress};
+use crate::model::Revision;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum PluginUpdateSource {
+    Builtin,
+    Upload,
+    Url { url: String },
+    Github { repository: String },
+}
+
+/// 检查策略只决定查询目标，任何策略都不会自动安装或切换运行实例。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum PluginUpdatePolicy {
+    Manual {},
+    Stable {},
+    Pinned {
+        tag: String,
+        #[serde(default)]
+        allow_prerelease: bool,
+    },
+}
+
+impl Default for PluginUpdatePolicy {
+    fn default() -> Self {
+        Self::Manual {}
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginSourceBinding {
+    pub plugin_id: String,
+    pub source: PluginUpdateSource,
+    #[serde(default)]
+    pub policy: PluginUpdatePolicy,
+    #[serde(default)]
+    pub outbound_proxy_id: Option<String>,
+}
+
+#[derive(Clone)]
+pub struct PluginDistributionEgress {
+    pub source: PluginSourceEgress,
+    pub proxy: OutboundProxy,
+}
+
+impl PluginDistributionEgress {
+    #[must_use]
+    pub fn new(id: String, revision: Revision, proxy: OutboundProxy) -> Self {
+        Self {
+            source: PluginSourceEgress {
+                id,
+                revision: revision.get(),
+            },
+            proxy,
+        }
+    }
+
+    #[must_use]
+    pub fn cache_key(&self) -> String {
+        format!("{}:{}", self.source.id, self.source.revision)
+    }
+}
+
+impl fmt::Debug for PluginDistributionEgress {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("PluginDistributionEgress")
+            .field("source", &self.source)
+            .field("proxy", &"<redacted>")
+            .finish()
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginUpdateCheck {
+    pub binding: PluginSourceBinding,
+    /// Release 元数据不是已校验的插件包，不据此声明平台或 SDK 兼容。
+    pub release: PluginRelease,
+}
+
+impl From<&PluginSource> for PluginUpdateSource {
+    fn from(source: &PluginSource) -> Self {
+        match source {
+            PluginSource::Builtin { .. } => Self::Builtin,
+            PluginSource::Upload => Self::Upload,
+            PluginSource::Url { url, .. } => Self::Url { url: url.clone() },
+            PluginSource::Github { repository, .. } => Self::Github {
+                repository: repository.to_ascii_lowercase(),
+            },
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DownloadPurpose {
+    Metadata,
+    Artifact,
+}
+
+/// 授权目标以完整 origin 和路径段边界匹配；摘要、名称和列表均不包含 secret。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct SourceCredentialInfo {
+    pub id: String,
+    pub name: String,
+    pub origin: String,
+    pub path_prefix: String,
+    pub purposes: Vec<DownloadPurpose>,
+}
+
+#[derive(Clone, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum SourceAuthentication {
+    Github {
+        token: SecretString,
+    },
+    Bearer {
+        token: SecretString,
+    },
+    Basic {
+        username: String,
+        password: SecretString,
+    },
+    Header {
+        name: String,
+        value: SecretString,
+    },
+}
+
+#[derive(Clone)]
+pub struct SourceCredential {
+    pub info: SourceCredentialInfo,
+    pub authentication: SourceAuthentication,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct GithubReleaseQuery {
+    pub repository: String,
+    pub tag: Option<String>,
+    #[serde(default)]
+    pub allow_prerelease: bool,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ReleaseAsset {
+    pub name: String,
+    pub size: u64,
+    pub sha256: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginRelease {
+    pub repository: String,
+    pub tag: String,
+    pub name: String,
+    pub prerelease: bool,
+    pub assets: Vec<ReleaseAsset>,
+    pub queried_at: DateTime<Utc>,
+    pub expires_at: DateTime<Utc>,
+}
+
+/// 下载意图不承载凭据；引用在 Admin 中解析后只交给 Host 的本次调用。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum RemotePluginLocation {
+    Url {
+        url: String,
+        sha256: Option<String>,
+    },
+    Github {
+        repository: String,
+        tag: String,
+        asset: String,
+        #[serde(default)]
+        allow_prerelease: bool,
+        sha256: Option<String>,
+    },
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct RemotePluginVerify {
+    pub location: RemotePluginLocation,
+    #[serde(default)]
+    pub credential_ids: Vec<String>,
+    #[serde(default)]
+    pub outbound_proxy_id: Option<String>,
+    /// 更新已有插件时锁定身份；首次安装从包内清单读取。
+    pub expected_plugin_id: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct RemotePluginInstall {
+    pub plugin_id: String,
+    pub version: String,
+    pub location: RemotePluginLocation,
+    #[serde(default)]
+    pub credential_ids: Vec<String>,
+    #[serde(default)]
+    pub outbound_proxy_id: Option<String>,
+}
+
+pub struct DownloadedPlugin {
+    pub archive: Arc<[u8]>,
+    pub sha256: String,
+    pub source: PluginSource,
+}
+
+/// 只读包校验结果，不代表实例配置、授权或私有状态已完成运行时准备。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct VerifiedPluginArtifact {
+    pub metadata: PluginArtifactMetadata,
+    pub source: PluginSource,
+}
diff --git a/backend/crates/gateway-admin/src/model/plugins/instances.rs b/backend/crates/gateway-admin/src/model/plugins/instances.rs
new file mode 100644
index 000000000..3aadbee27
--- /dev/null
+++ b/backend/crates/gateway-admin/src/model/plugins/instances.rs
@@ -0,0 +1,193 @@
+use std::collections::BTreeMap;
+
+use secrecy::SecretString;
+use serde::{Deserialize, Serialize};
+
+use crate::model::Revision;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginPermissionGrant {
+    pub permission: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PluginFailurePolicy {
+    Reject,
+    Delegate,
+    Observe,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginCapabilityBinding {
+    pub contribution: String,
+    pub stage: String,
+    pub order: i32,
+    pub failure_policy: PluginFailurePolicy,
+    #[serde(default)]
+    pub client_key_ids: Vec<String>,
+    #[serde(default)]
+    pub account_group_ids: Vec<String>,
+    #[serde(default)]
+    pub provider_ids: Vec<String>,
+    #[serde(default)]
+    pub models: Vec<String>,
+    #[serde(default)]
+    pub identity_bindings: Vec<PluginFrontendIdentityBinding>,
+}
+
+/// 外部 principal 到既有 Client Key 的显式宿主映射。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginFrontendIdentityBinding {
+    pub principal: String,
+    pub client_key_id: String,
+}
+
+impl std::fmt::Debug for PluginFrontendIdentityBinding {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("PluginFrontendIdentityBinding")
+            .field("principal", &"[REDACTED]")
+            .field("client_key_id", &self.client_key_id)
+            .finish()
+    }
+}
+
+/// 配置和 secret 分离；Debug 与 Serialize 不得无意展开实例配置。
+#[derive(Clone)]
+pub struct PluginInstance {
+    pub id: String,
+    pub name: String,
+    pub artifact_sha256: String,
+    pub enabled: bool,
+    pub trusted_process: bool,
+    pub configuration: serde_json::Value,
+    pub secrets: BTreeMap<String, SecretString>,
+    pub grants: Vec<PluginPermissionGrant>,
+    pub bindings: Vec<PluginCapabilityBinding>,
+    pub revision: Revision,
+}
+
+#[derive(Clone)]
+pub struct PluginInstanceSnapshot {
+    pub config_revision: Revision,
+    pub instances: Vec<PluginInstance>,
+}
+
+pub struct PluginInstanceMutation {
+    pub config_revision: Revision,
+    pub instance: PluginInstance,
+}
+
+/// 控制面展示的单实例运行状态；它描述当前进程观察到的事实，不替代持久启用配置。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PluginInstanceRuntimeStatus {
+    Disabled,
+    AwaitingPublication,
+    Preparing,
+    Running,
+    Blocked,
+    PreparationFailed,
+    Faulted,
+    Draining,
+}
+
+/// 已脱敏且可安全返回给管理员的运行失败摘要。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginInstanceRuntimeFailure {
+    pub code: String,
+    pub message: String,
+}
+
+/// 从当前发布视图、弱代次索引和 continuation retention 合成的只读诊断。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginInstanceRuntime {
+    pub status: PluginInstanceRuntimeStatus,
+    pub actual_revision: Option<u64>,
+    pub actual_artifact_sha256: Option<String>,
+    pub failure: Option<PluginInstanceRuntimeFailure>,
+    pub draining_revisions: Vec<u64>,
+    pub retained_continuations: u32,
+}
+
+pub struct PluginInstanceView {
+    pub instance: PluginInstance,
+    pub configuration_required: bool,
+    pub running: bool,
+    pub published_revision: Option<u64>,
+    pub runtime: PluginInstanceRuntime,
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct ConfigurePluginInstance {
+    /// 创建草稿固定一个 UUID，重试复用同一配置，不能作为编辑已有配置的入口。
+    pub creation_id: Option<String>,
+    /// 编辑时检查用户看到的配置版本，避免覆盖另一窗口已经保存的内容。
+    pub expected_revision: Option<u64>,
+    /// 管理员确认停用的同插件配置，与当前配置在同一事务中切换。
+    #[serde(default)]
+    pub replace_instances: Vec<PluginInstanceReplacement>,
+    pub name: String,
+    pub artifact_sha256: String,
+    pub enabled: bool,
+    pub configuration: serde_json::Value,
+    /// 缺省保留旧值；显式空对象清除全部 secret。
+    pub secrets: Option<BTreeMap<String, SecretString>>,
+    pub bindings: Vec<PluginCapabilityBinding>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginInstanceReplacement {
+    pub id: String,
+    pub expected_revision: u64,
+}
+
+/// 恢复已安装旧版本的配置快照，并重新通过目标版本校验。
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct RollbackPluginInstance {
+    pub artifact_sha256: String,
+    pub expected_revision: u64,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginRollbackTarget {
+    pub artifact_sha256: String,
+    pub version: String,
+    pub platforms: Vec<String>,
+}
+
+/// 静态候选不启动插件；实际回滚仍须复验配置、平台和私有状态兼容性。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginRollbackPlan {
+    pub instance_revision: u64,
+    pub current_version: String,
+    pub targets: Vec<PluginRollbackTarget>,
+}
+
+/// 版本配置快照只用于服务端恢复，敏感值不实现 Debug 或 Serialize。
+#[derive(Clone)]
+pub struct PluginVersionConfiguration {
+    pub configuration: serde_json::Value,
+    pub secrets: BTreeMap<String, SecretString>,
+    pub bindings: Vec<PluginCapabilityBinding>,
+}
+
+/// 切换版本的只读草稿，不包含密钥值，也不会启动插件或写入配置。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginVersionPlan {
+    pub instance_revision: u64,
+    pub artifact_sha256: String,
+    pub configuration: serde_json::Value,
+    pub secret_fields: Vec<String>,
+    pub bindings: Vec<PluginCapabilityBinding>,
+    pub restored: bool,
+}
diff --git a/backend/crates/gateway-admin/src/model/plugins/management.rs b/backend/crates/gateway-admin/src/model/plugins/management.rs
new file mode 100644
index 000000000..6bc9d155d
--- /dev/null
+++ b/backend/crates/gateway-admin/src/model/plugins/management.rs
@@ -0,0 +1,89 @@
+use std::sync::Arc;
+
+use serde::{Deserialize, Serialize};
+
+/// 页面和业务调用绑定同一实例版本；制品摘要单独作为不可变资源身份。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginManagementTarget {
+    pub instance_id: String,
+    pub artifact_sha256: String,
+    pub revision: u64,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginManagementView {
+    pub target: PluginManagementTarget,
+    pub name: String,
+    pub configuration_schema: serde_json::Value,
+    pub pages: Vec<PluginManagementPage>,
+    pub routes: Vec<PluginManagementRoute>,
+    pub resources: Vec<PluginManagementResource>,
+    pub callbacks: Vec<PluginManagementCallback>,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginManagementCallback {
+    pub path: String,
+    pub response_content_types: Vec<String>,
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct StartPluginManagementCallback {
+    pub path: String,
+    pub ttl_seconds: u32,
+}
+
+/// state 是短期一次性秘密，只交给发起登录的管理员，不进入 Debug 或日志。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginManagementCallbackTicket {
+    pub state: String,
+    pub expires_at_ms: i64,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginManagementPage {
+    pub id: String,
+    pub title: String,
+    pub description: Option<String>,
+    pub entry: String,
+    pub icon: Option<String>,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginManagementRoute {
+    pub method: String,
+    pub path: String,
+    pub request_content_types: Vec<String>,
+    pub response_content_types: Vec<String>,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginManagementResource {
+    pub path: String,
+    pub content_type: String,
+    pub public: bool,
+}
+
+/// 原始正文可能含业务数据，不能派生内容型 Debug 或写入诊断日志。
+pub struct PluginManagementRequest {
+    pub method: String,
+    pub path: String,
+    pub query: String,
+    pub content_type: Option<String>,
+    pub body: Vec<u8>,
+    pub request_id: String,
+}
+
+pub struct PluginManagementResponse {
+    pub status: u16,
+    pub content_type: String,
+    pub body: Arc<[u8]>,
+}
diff --git a/backend/crates/gateway-admin/src/model/plugins/mod.rs b/backend/crates/gateway-admin/src/model/plugins/mod.rs
new file mode 100644
index 000000000..13a0401b8
--- /dev/null
+++ b/backend/crates/gateway-admin/src/model/plugins/mod.rs
@@ -0,0 +1,273 @@
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    sync::Arc,
+};
+
+use serde::{Deserialize, Serialize};
+
+use super::Revision;
+
+pub mod distribution;
+pub mod instances;
+pub mod management;
+pub mod official;
+pub mod state;
+
+/// 一个宿主发行版明确承诺支持的插件能力版本。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PluginHostCapability {
+    pub capability: String,
+    pub versions: Vec<u32>,
+}
+
+/// 随宿主发行物封口的插件合同；Runtime 与发布清单共用这一份声明。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PluginHostCompatibility {
+    pub schema_version: u32,
+    pub manifest_schema_versions: Vec<u32>,
+    pub protocol_versions: Vec<u32>,
+    pub capabilities: Vec<PluginHostCapability>,
+    pub permissions: Vec<String>,
+}
+
+impl PluginHostCompatibility {
+    /// 拒绝空集合、重复项和不受控标识，避免发行清单把“未知”解释为通配。
+    #[must_use]
+    pub fn is_valid(&self) -> bool {
+        if self.schema_version != 1
+            || !valid_versions(&self.manifest_schema_versions)
+            || !valid_versions(&self.protocol_versions)
+            || self.capabilities.is_empty()
+            || self.capabilities.len() > 64
+            || self.permissions.len() > 64
+        {
+            return false;
+        }
+        let mut capabilities = BTreeSet::new();
+        if self.capabilities.iter().any(|entry| {
+            !valid_identifier(&entry.capability)
+                || !valid_versions(&entry.versions)
+                || !capabilities.insert(entry.capability.as_str())
+        }) {
+            return false;
+        }
+        let mut permissions = BTreeSet::new();
+        !self.permissions.iter().any(|permission| {
+            !valid_identifier(permission) || !permissions.insert(permission.as_str())
+        })
+    }
+
+    #[must_use]
+    pub fn supports_capability(&self, capability: &str, version: u32) -> bool {
+        self.capabilities
+            .iter()
+            .any(|entry| entry.capability == capability && entry.versions.contains(&version))
+    }
+
+    #[must_use]
+    pub fn supports_permission(&self, permission: &str) -> bool {
+        self.permissions.iter().any(|entry| entry == permission)
+    }
+}
+
+fn valid_versions(versions: &[u32]) -> bool {
+    !versions.is_empty()
+        && versions.len() <= 16
+        && versions.iter().all(|version| *version > 0)
+        && versions.iter().collect::<BTreeSet<_>>().len() == versions.len()
+}
+
+fn valid_identifier(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 64
+        && value.bytes().all(|byte| {
+            byte.is_ascii_lowercase() || byte.is_ascii_digit() || matches!(byte, b'_' | b'-')
+        })
+}
+
+pub(crate) fn valid_plugin_id(value: &str) -> bool {
+    if value.len() > 64 {
+        return false;
+    }
+    let Some((publisher, name)) = value.split_once('.') else {
+        return false;
+    };
+    valid_plugin_segment(publisher) && valid_plugin_segment(name)
+}
+
+fn valid_plugin_segment(value: &str) -> bool {
+    value
+        .as_bytes()
+        .first()
+        .is_some_and(u8::is_ascii_alphanumeric)
+        && value
+            .as_bytes()
+            .last()
+            .is_some_and(u8::is_ascii_alphanumeric)
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
+}
+
+/// 已安装包对目标宿主的静态要求；不包含包体、配置或 secret。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginCompatibilityRequirements {
+    pub host_version: String,
+    pub manifest_schema_version: u32,
+    pub protocol_version: u32,
+    pub capabilities: Vec<(String, u32)>,
+    pub permissions: Vec<String>,
+}
+
+/// 一次下载使用的非敏感出站代理身份；地址与认证由受管代理记录持有。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginSourceEgress {
+    pub id: String,
+    pub revision: u64,
+}
+
+/// 安装来源只保存公开定位信息，下载凭据和出站代理通过独立记录引用。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum PluginSource {
+    Builtin {
+        release: String,
+    },
+    Upload,
+    Url {
+        url: String,
+        credential_ids: Vec<String>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        outbound_proxy: Option<PluginSourceEgress>,
+    },
+    Github {
+        repository: String,
+        tag: String,
+        asset: String,
+        credential_ids: Vec<String>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        outbound_proxy: Option<PluginSourceEgress>,
+    },
+}
+
+impl PluginSource {
+    #[must_use]
+    pub fn credential_ids(&self) -> &[String] {
+        match self {
+            Self::Url { credential_ids, .. } | Self::Github { credential_ids, .. } => {
+                credential_ids
+            }
+            Self::Builtin { .. } | Self::Upload => &[],
+        }
+    }
+
+    #[must_use]
+    pub const fn outbound_proxy(&self) -> Option<&PluginSourceEgress> {
+        match self {
+            Self::Url { outbound_proxy, .. } | Self::Github { outbound_proxy, .. } => {
+                outbound_proxy.as_ref()
+            }
+            Self::Builtin { .. } | Self::Upload => None,
+        }
+    }
+}
+
+/// 管理端保留的单项贡献声明；map key 是能力标识，`id` 是实例绑定引用的扩展项身份。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginContribution {
+    pub id: String,
+    pub version: u32,
+    pub stages: Vec<String>,
+    pub input_formats: Vec<String>,
+    pub output_formats: Vec<String>,
+}
+
+/// 制品清单中的展示图标；路径只用于选择已校验的包资源。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum PluginArtifactIcon {
+    Path(String),
+    Themed(PluginArtifactIconVariants),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PluginArtifactIconVariants {
+    pub light: String,
+    pub dark: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PluginIconTheme {
+    Light,
+    Dark,
+}
+
+/// 从不可变制品中读取的已校验图标字节。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginArtifactIconResource {
+    pub content_type: String,
+    pub body: Vec<u8>,
+}
+
+/// 管理端使用的静态描述，不承载 SDK 的运行时消息或宿主实现类型。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginPermissionDescription {
+    pub permission: String,
+    pub label: String,
+    pub description: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginArtifactMetadata {
+    pub plugin_id: String,
+    pub version: String,
+    pub name: String,
+    pub display_name: String,
+    pub publisher: String,
+    pub author: Option<String>,
+    pub description: String,
+    pub license: String,
+    pub sha256: String,
+    pub platforms: Vec<String>,
+    #[serde(default)]
+    pub icon: Option<PluginArtifactIcon>,
+    pub contributes: BTreeMap<String, PluginContribution>,
+    pub requested_permissions: Vec<String>,
+    pub configuration_schema: serde_json::Value,
+    pub secret_fields: Vec<String>,
+    #[serde(default)]
+    pub state_namespaces: Vec<state::PluginStateSchema>,
+}
+
+/// 由包检查端口产生的不可变制品；不派生 Debug，包内可能含敏感用户数据。
+#[derive(Clone)]
+pub struct InspectedPluginArtifact {
+    pub metadata: PluginArtifactMetadata,
+    pub archive: Arc<[u8]>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct InstalledPluginArtifact {
+    pub metadata: PluginArtifactMetadata,
+    pub source: PluginSource,
+    pub installed_at: chrono::DateTime<chrono::Utc>,
+    pub accepted_at: Option<chrono::DateTime<chrono::Utc>>,
+}
+
+pub struct PluginArtifactMutation {
+    pub config_revision: Revision,
+    pub artifact: InstalledPluginArtifact,
+}
+
+pub struct PluginInstallResult {
+    pub mutation: PluginArtifactMutation,
+    pub default_instance_id: Option<String>,
+    pub configuration_required: bool,
+}
diff --git a/backend/crates/gateway-admin/src/model/plugins/official.rs b/backend/crates/gateway-admin/src/model/plugins/official.rs
new file mode 100644
index 000000000..ca07bc5b3
--- /dev/null
+++ b/backend/crates/gateway-admin/src/model/plugins/official.rs
@@ -0,0 +1,15 @@
+use super::super::Revision;
+
+/// 编译进宿主二进制的发行身份；不能由运行时配置或插件清单覆盖。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct OfficialPluginReleaseIdentity {
+    pub gateway_version: String,
+    pub gateway_git_sha: String,
+}
+
+/// 启动时导入官方制品的结果；导入只持久化制品，不创建或启用实例。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct OfficialPluginImport {
+    pub artifacts: usize,
+    pub config_revision: Option<Revision>,
+}
diff --git a/backend/crates/gateway-admin/src/model/plugins/state.rs b/backend/crates/gateway-admin/src/model/plugins/state.rs
new file mode 100644
index 000000000..08dcce3e6
--- /dev/null
+++ b/backend/crates/gateway-admin/src/model/plugins/state.rs
@@ -0,0 +1,205 @@
+use std::{collections::BTreeMap, fmt};
+
+use serde::{Deserialize, Serialize};
+
+use crate::model::Revision;
+
+/// 已由 Runtime 校验的命名空间 schema 与配额事实。
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginStateSchema {
+    pub namespace: String,
+    pub schema_version: u32,
+    pub schema_sha256: String,
+    pub schema: serde_json::Value,
+    pub maximum_records: u32,
+    pub maximum_bytes: u64,
+    pub maximum_value_bytes: u32,
+    #[serde(default)]
+    pub migrates_from: Vec<u32>,
+}
+
+impl fmt::Debug for PluginStateSchema {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("PluginStateSchema")
+            .field("namespace", &self.namespace)
+            .field("schema_version", &self.schema_version)
+            .field("schema_sha256", &self.schema_sha256)
+            .field("schema", &"[REDACTED]")
+            .field("maximum_records", &self.maximum_records)
+            .field("maximum_bytes", &self.maximum_bytes)
+            .field("maximum_value_bytes", &self.maximum_value_bytes)
+            .field("migrates_from", &self.migrates_from)
+            .finish()
+    }
+}
+
+#[derive(Clone, Default, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginStateConfiguration {
+    #[serde(default)]
+    pub namespaces: Vec<PluginStateSchema>,
+}
+
+/// 与实例保存同事务提交的状态配置；transition 只引用已完成的 staging 数据。
+#[derive(Clone, Default)]
+pub struct PluginStateCommit {
+    pub configuration: PluginStateConfiguration,
+    pub transition_id: Option<String>,
+}
+
+#[derive(Clone)]
+pub struct PluginStateOwnerRequest {
+    pub instance_id: String,
+    pub artifact_sha256: String,
+    pub instance_revision: Revision,
+    pub configuration: PluginStateConfiguration,
+}
+
+/// Store 签发的实例私有状态 fence。插件协议中从不传输这些字段。
+#[derive(Clone)]
+pub struct PluginStateOwner {
+    instance_id: String,
+    artifact_sha256: String,
+    instance_revision: Revision,
+    namespaces: BTreeMap<String, PluginStateNamespaceOwner>,
+}
+
+#[derive(Clone)]
+pub struct PluginStateNamespaceOwner {
+    generation_id: String,
+    fence: String,
+    schema_version: u32,
+}
+
+impl PluginStateOwner {
+    #[must_use]
+    pub fn from_store(
+        instance_id: String,
+        artifact_sha256: String,
+        instance_revision: Revision,
+        namespaces: BTreeMap<String, PluginStateNamespaceOwner>,
+    ) -> Self {
+        Self {
+            instance_id,
+            artifact_sha256,
+            instance_revision,
+            namespaces,
+        }
+    }
+
+    #[must_use]
+    pub fn instance_id(&self) -> &str {
+        &self.instance_id
+    }
+
+    #[must_use]
+    pub fn artifact_sha256(&self) -> &str {
+        &self.artifact_sha256
+    }
+
+    #[must_use]
+    pub const fn instance_revision(&self) -> Revision {
+        self.instance_revision
+    }
+
+    #[must_use]
+    pub fn namespace(&self, namespace: &str) -> Option<&PluginStateNamespaceOwner> {
+        self.namespaces.get(namespace)
+    }
+}
+
+impl PluginStateNamespaceOwner {
+    #[must_use]
+    pub fn from_store(generation_id: String, fence: String, schema_version: u32) -> Self {
+        Self {
+            generation_id,
+            fence,
+            schema_version,
+        }
+    }
+
+    #[must_use]
+    pub fn generation_id(&self) -> &str {
+        &self.generation_id
+    }
+
+    #[must_use]
+    pub fn fence(&self) -> &str {
+        &self.fence
+    }
+
+    #[must_use]
+    pub const fn schema_version(&self) -> u32 {
+        self.schema_version
+    }
+}
+
+/// 私有值可能含插件自己的敏感状态，故意不实现 `Debug`。
+#[derive(Clone)]
+pub struct PluginStateRecord {
+    pub key: String,
+    pub value: serde_json::Value,
+    pub version: u64,
+    pub schema_version: u32,
+}
+
+pub struct PutPluginState {
+    pub namespace: String,
+    pub key: String,
+    pub value: serde_json::Value,
+    /// `None` 是 create-only；已有记录必须提交精确版本。
+    pub expected_version: Option<u64>,
+}
+
+pub struct DeletePluginState {
+    pub namespace: String,
+    pub key: String,
+    pub expected_version: u64,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PluginStateWrite {
+    pub version: u64,
+}
+
+#[derive(Clone)]
+pub struct PluginStateTransition {
+    pub id: String,
+    pub instance_id: String,
+    pub artifact_sha256: String,
+    pub namespaces: Vec<PluginStateMigrationNamespace>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginStateMigrationNamespace {
+    pub namespace: String,
+    pub from_schema_version: u32,
+    pub to_schema_version: u32,
+}
+
+pub struct PluginStateMigrationBatch {
+    pub cursor: Option<String>,
+    pub records: Vec<PluginStateRecord>,
+}
+
+pub struct ApplyPluginStateMigration {
+    pub transition_id: String,
+    pub namespace: String,
+    pub cursor: Option<String>,
+    /// Runtime 刚读取的有序源键；Store 会在写入前重新读取并逐项比对。
+    pub expected_keys: Vec<String>,
+    pub changes: Vec<PluginStateMigrationChange>,
+}
+
+pub struct PluginStateMigrationChange {
+    pub key: String,
+    pub action: PluginStateMigrationAction,
+}
+
+pub enum PluginStateMigrationAction {
+    Keep,
+    Replace(serde_json::Value),
+    Delete,
+}
diff --git a/backend/crates/gateway-admin/src/model/provider_capabilities.rs b/backend/crates/gateway-admin/src/model/provider_capabilities.rs
new file mode 100644
index 000000000..7614cd262
--- /dev/null
+++ b/backend/crates/gateway-admin/src/model/provider_capabilities.rs
@@ -0,0 +1,42 @@
+//! 账号页面消费的能力描述；支持声明不代替实际操作时的账号范围与权限校验。
+
+use gateway_core::routing::ProviderKind;
+use serde_json::Value;
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct ProviderCredentialDescriptor {
+    pub provider: ProviderKind,
+    pub capabilities: ProviderCredentialCapabilities,
+}
+
+/// 当前账号可用的管理能力，由已发布 Provider 投影；不代替执行时的权限与身份校验。
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub struct ProviderAccountCapabilities {
+    pub quota: bool,
+    pub quota_refresh: bool,
+    pub profile: bool,
+    pub subscription: bool,
+    pub avatar: bool,
+    pub reset_credits: bool,
+    pub consume_reset_credit: bool,
+}
+
+#[derive(Debug, Default, Clone, PartialEq)]
+pub struct ProviderCredentialCapabilities {
+    pub import: Option<Value>,
+    pub login: Option<ProviderLoginCapability>,
+    pub refresh: bool,
+    pub export: bool,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct ProviderLoginCapability {
+    pub input_schema: Value,
+    pub completion: AuthorizationCompletion,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AuthorizationCompletion {
+    Callback,
+    Poll,
+}
diff --git a/backend/crates/gateway-admin/src/model/provider_credentials.rs b/backend/crates/gateway-admin/src/model/provider_credentials.rs
index f3cb67400..58ed381c6 100644
--- a/backend/crates/gateway-admin/src/model/provider_credentials.rs
+++ b/backend/crates/gateway-admin/src/model/provider_credentials.rs
@@ -15,7 +15,7 @@ use serde_json::{Map, Value};
 use uuid::Uuid;
 
 use super::{
-    AdminError, MutationActor, MutationContext, Revision,
+    AdminError, MutationActor, MutationContext, PageSize, Revision,
     accounts::{
         AccountImportSettings, AccountRecord, AccountSummary, AccountUsage, CredentialState,
     },
@@ -384,13 +384,19 @@ enum StoredAuthorizationOwnerV1 {
     System,
 }
 
-/// 启动 Provider OAuth Authorization Code 流程。
-#[derive(Debug, Clone, PartialEq, Eq)]
+/// 启动 Provider 登录；输入仅用于本次准备，不进入宿主的持久事务目标。
+#[derive(Debug, Clone, PartialEq)]
 pub struct StartAuthorization {
     pub context: MutationContext,
     pub name: String,
     pub reauthorization: Option<ProviderAccountId>,
     pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
+    pub input: ProviderDocument,
+}
+
+pub struct PrepareAuthorization {
+    pub pending: PendingAuthorizationMutation,
+    pub input: ProviderDocument,
 }
 
 /// OAuth 流程启动结果。
@@ -425,8 +431,8 @@ pub trait AuthorizationCommitGuard: Send + 'static {
 
 /// OAuth complete 后由 Provider 返回的准备结果；Store 仍是唯一提交者。
 pub enum PreparedAuthorizationCredential {
-    Create(PreparedCredentialCreate),
-    Reauthorize(PreparedCredentialRotation),
+    Create(Vec<PreparedCredentialCreate>),
+    Reauthorize(Box<PreparedCredentialRotation>),
 }
 
 /// Provider 从 opaque pending payload 恢复的信封与已验证 credential 必须一起返回。
@@ -449,18 +455,131 @@ impl fmt::Debug for PreparedAuthorizationCommit {
 /// Store 可持久化的 OAuth credential facts，不携带 Provider guard。
 #[derive(Debug, Clone, PartialEq)]
 pub enum AuthorizationCredentialCommit {
-    Create(PreparedCredentialCreate),
-    Reauthorize(PreparedCredentialRotationFacts),
+    Create(Vec<PreparedCredentialCreate>),
+    Reauthorize(Box<PreparedCredentialRotationFacts>),
 }
 
 /// Admin 交给 Store 的 OAuth 原子事务命令。
 #[derive(Debug, Clone, PartialEq)]
 pub struct AuthorizationCommit {
+    pub key: AuthorizationReceiptKey,
     pub settings: Option<AccountImportSettings>,
     pub pending: PendingAuthorizationMutation,
     pub credential: AuthorizationCredentialCommit,
 }
 
+/// 回执以 Provider、授权流和管理员身份绑定；不持久化原始 flow 或回调材料。
+#[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]
+pub struct AuthorizationReceiptKey {
+    provider_kind: ProviderKind,
+    flow_digest: String,
+    owner_digest: String,
+}
+
+impl AuthorizationReceiptKey {
+    pub fn new(
+        provider_kind: ProviderKind,
+        flow: &str,
+        context: &MutationContext,
+    ) -> Result<Self, AdminError> {
+        use sha2::{Digest as _, Sha256};
+        if flow.trim().is_empty() || flow.len() > 1024 || flow.chars().any(char::is_control) {
+            return Err(AdminError::invalid("授权流程标识无效"));
+        }
+        Ok(Self {
+            provider_kind,
+            flow_digest: hex::encode(Sha256::digest(flow.as_bytes())),
+            owner_digest: authorization_owner_digest(context),
+        })
+    }
+
+    #[must_use]
+    pub const fn provider_kind(&self) -> &ProviderKind {
+        &self.provider_kind
+    }
+
+    #[must_use]
+    pub fn flow_digest(&self) -> &str {
+        &self.flow_digest
+    }
+
+    #[must_use]
+    pub fn owner_digest(&self) -> &str {
+        &self.owner_digest
+    }
+
+    #[must_use]
+    pub fn matches_context(&self, context: &MutationContext) -> bool {
+        authorization_owner_digest(context) == self.owner_digest
+    }
+}
+
+fn authorization_owner_digest(context: &MutationContext) -> String {
+    use sha2::{Digest as _, Sha256};
+    let owner = match &context.actor {
+        MutationActor::AdminSession { admin_user_id } => format!("admin_session:{admin_user_id}"),
+        MutationActor::AdminApiKey => "admin_api_key".into(),
+        MutationActor::System => "system".into(),
+    };
+    hex::encode(Sha256::digest(owner.as_bytes()))
+}
+
+impl fmt::Debug for AuthorizationReceiptKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("AuthorizationReceiptKey([REDACTED])")
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthorizationCommitResult {
+    pub result: CredentialBatchMutationResult,
+    pub newly_committed: bool,
+}
+
+/// 同一授权事务产生的账号集合；重新授权的集合始终只有原账号。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CredentialBatchMutationResult {
+    pub config_revision: Revision,
+    pub accounts: Vec<AuthorizedAccount>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthorizedAccount {
+    pub account_id: ProviderAccountId,
+    pub credential_revision: Option<Revision>,
+}
+
+impl From<CredentialMutationResult> for CredentialBatchMutationResult {
+    fn from(result: CredentialMutationResult) -> Self {
+        Self {
+            config_revision: result.config_revision,
+            accounts: vec![AuthorizedAccount {
+                account_id: result.account_id,
+                credential_revision: result.credential_revision,
+            }],
+        }
+    }
+}
+
+/// 轮询可以附带浏览器返回值；敏感材料不能进入 Debug 或通用审计。
+pub struct PollAuthorization {
+    pub context: MutationContext,
+    pub flow_id: String,
+    pub callback_url: Option<String>,
+    pub settings: Option<AccountImportSettings>,
+}
+
+pub enum PreparedAuthorizationPoll {
+    Pending { retry_after: std::time::Duration },
+    Complete(Box<PreparedAuthorizationCommit>),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AuthorizationPollResult {
+    Pending { retry_after: std::time::Duration },
+    Complete(CredentialBatchMutationResult),
+}
+
 /// OAuth 准备结果拆解后的 Store 命令与两个结算 guard。
 ///
 /// Store 成功时先结束 credential guard，再消费 OAuth claim；失败时丢弃 credential guard 并
@@ -494,6 +613,7 @@ impl PreparedAuthorizationCommit {
     pub(crate) fn into_commit(
         self,
         settings: Option<AccountImportSettings>,
+        key: AuthorizationReceiptKey,
     ) -> AuthorizationCommitSettlement {
         let (credential, guard) = match self.credential {
             PreparedAuthorizationCredential::Create(credential) => {
@@ -502,13 +622,14 @@ impl PreparedAuthorizationCommit {
             PreparedAuthorizationCredential::Reauthorize(prepared) => {
                 let (facts, guard) = prepared.into_parts();
                 (
-                    AuthorizationCredentialCommit::Reauthorize(facts),
+                    AuthorizationCredentialCommit::Reauthorize(Box::new(facts)),
                     Some(guard),
                 )
             }
         };
         AuthorizationCommitSettlement {
             command: AuthorizationCommit {
+                key,
                 settings,
                 pending: self.pending,
                 credential,
@@ -519,13 +640,8 @@ impl PreparedAuthorizationCommit {
     }
 
     pub(crate) async fn abort(self) -> Result<(), AdminError> {
-        let AuthorizationCommitSettlement {
-            credential_guard,
-            authorization_guard,
-            ..
-        } = self.into_commit(None);
-        drop(credential_guard);
-        if let Some(guard) = authorization_guard {
+        drop(self.credential);
+        if let Some(guard) = self.authorization_guard {
             guard.abort().await?;
         }
         Ok(())
@@ -1060,6 +1176,62 @@ pub struct ProviderModels {
     pub observed_at: Option<DateTime<Utc>>,
 }
 
+/// 插件账号回调的服务端过滤条件；Provider 缺省时跨全部已注册类型分页。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginAccountListQuery {
+    pub provider_kind: Option<ProviderKind>,
+    pub cursor: Option<ProviderAccountId>,
+    pub limit: PageSize,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginAccountPage {
+    pub accounts: Vec<AccountRecord>,
+    pub next_cursor: Option<ProviderAccountId>,
+}
+
+/// 原始凭据与当前账号 revision 的同一读取结果。
+#[derive(Clone, PartialEq)]
+pub struct PluginAccountCredential {
+    pub account: AccountRecord,
+    pub provider_material: ProviderDocument,
+}
+
+impl fmt::Debug for PluginAccountCredential {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("PluginAccountCredential")
+            .field("account", &self.account)
+            .field("provider_material", &self.provider_material)
+            .finish()
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PluginAccountSaveReason {
+    Explicit,
+    ModelDiscovery,
+    Maintenance,
+}
+
+/// Runtime 已完成 wire 校验、Admin 仍需绑定当前账号和 revision 的 prepared facts。
+#[derive(Debug, Clone, PartialEq)]
+pub enum PreparedPluginAccountSave {
+    Create(PreparedCredentialCreate),
+    Replace {
+        facts: PreparedCredentialRotationFacts,
+        authentication_kind: String,
+        reason: PluginAccountSaveReason,
+    },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginAccountSaveResult {
+    pub config_revision: Revision,
+    pub account_id: ProviderAccountId,
+    pub credential_revision: Revision,
+}
+
 /// Provider 执行 refresh 时所需的当前公共账号事实。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PrepareCredentialRefresh {
@@ -1095,6 +1267,7 @@ impl fmt::Debug for ProviderExport {
 #[derive(Debug, Clone, PartialEq)]
 pub struct AccountDirectoryItem {
     pub account: AccountRecord,
+    pub capabilities: super::provider_capabilities::ProviderAccountCapabilities,
     /// Provider 提供的套餐展示名称；未识别到套餐时为空。
     pub plan_type_display: Option<String>,
     pub projection: gateway_core::account::AccountStatusProjection,
@@ -1109,6 +1282,7 @@ pub struct AccountDirectoryPage {
     pub items: Vec<AccountDirectoryItem>,
     pub total: u64,
     pub summary: AccountSummary,
+    pub providers: Vec<String>,
 }
 
 /// 凭据刷新提交后的完整账号结果。
diff --git a/backend/crates/gateway-admin/src/model/quota_forecast.rs b/backend/crates/gateway-admin/src/model/quota_forecast.rs
index f4ba91522..4286fe547 100644
--- a/backend/crates/gateway-admin/src/model/quota_forecast.rs
+++ b/backend/crates/gateway-admin/src/model/quota_forecast.rs
@@ -43,6 +43,19 @@ pub struct QuotaForecastSource {
     pub usd: Option<f64>,
 }
 
+/// 为目标周期选择唯一的预测源窗口；缺少同周期窗口时复用最短的可统计窗口。
+///
+/// Admin 的历史查询与最终投影必须共用这里的顺序，避免查询不会进入响应的窗口。
+pub(crate) fn quota_forecast_source_window(
+    quota: &ProviderQuota,
+    period: AccountUsagePeriod,
+) -> Option<(&ProviderQuotaWindow, AccountUsagePeriod)> {
+    quota
+        .usage_windows()
+        .find(|(_, source_period)| *source_period == period)
+        .or_else(|| quota.usage_windows().min_by_key(|(_, period)| *period))
+}
+
 /// 优先预测真实的对应窗口；缺少对应周期时只给出明确标识的 7/30 天容量折算。
 /// 本地日志不能证明站外消耗或完整留存，因此即使样本充足也不声称官方额度。
 #[must_use]
@@ -53,10 +66,7 @@ pub fn account_quota_forecasts(
     samples: &[QuotaForecastSample],
 ) -> [AccountQuotaForecast; 2] {
     [AccountUsagePeriod::Weekly, AccountUsagePeriod::Monthly].map(|period| {
-        let selected = quota
-            .usage_windows()
-            .find(|(_, source_period)| *source_period == period)
-            .or_else(|| quota.usage_windows().min_by_key(|(_, period)| *period));
+        let selected = quota_forecast_source_window(quota, period);
         let mut forecast = AccountQuotaForecast {
             period,
             target_seconds: match period {
diff --git a/backend/crates/gateway-admin/src/model/settings.rs b/backend/crates/gateway-admin/src/model/settings.rs
index e49bec263..9d38b9d03 100644
--- a/backend/crates/gateway-admin/src/model/settings.rs
+++ b/backend/crates/gateway-admin/src/model/settings.rs
@@ -4,21 +4,28 @@ use std::{collections::BTreeMap, fmt};
 
 use chrono::{DateTime, Utc};
 
-use gateway_core::routing::{PublicModelId, UpstreamModelId};
+use gateway_core::routing::{ProviderKind, PublicModelId, UpstreamModelId};
 
 use super::Revision;
 
 /// 客户端模型到上游模型的全局精确映射。
 pub type ModelMappings = BTreeMap<PublicModelId, UpstreamModelId>;
 
+/// Provider-owned 请求画像选择；Provider ID 是唯一命名空间。
+pub type ProviderRequestProfiles =
+    BTreeMap<ProviderKind, gateway_core::account::OpaqueProviderData>;
+
+/// Provider-owned 请求画像的部分更新；`None` 只表示显式删除该 Provider 的历史选择。
+pub type ProviderRequestProfileUpdates =
+    BTreeMap<ProviderKind, Option<gateway_core::account::OpaqueProviderData>>;
+
 /// 账号调度策略；由 Core 拥有稳定值与 wire 映射。
 pub use gateway_core::account::RotationStrategy;
 
 /// 完整运行设置事实。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct RuntimeSettings {
-    pub openai_client_profile: Option<gateway_core::account::OpaqueProviderData>,
-    pub xai_client_profile: Option<gateway_core::account::OpaqueProviderData>,
+    pub request_profiles: ProviderRequestProfiles,
     pub config_revision: Revision,
     pub request_location_enabled: bool,
     pub request_location: gateway_core::account::RequestLocation,
@@ -50,8 +57,8 @@ pub struct RuntimeSettings {
 /// 原子替换运行设置的命令。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ReplaceRuntimeSettings {
-    pub openai_client_profile: Option<gateway_core::account::OpaqueProviderData>,
-    pub xai_client_profile: Option<gateway_core::account::OpaqueProviderData>,
+    /// 只覆盖提交的 Provider；未提交项保留当前持久值。
+    pub request_profile_updates: ProviderRequestProfileUpdates,
     pub request_location_enabled: bool,
     pub request_location: gateway_core::account::RequestLocation,
     pub model_mappings: ModelMappings,
@@ -134,10 +141,8 @@ impl RuntimeSettings {
         &self,
         provider: &str,
     ) -> Option<&gateway_core::account::OpaqueProviderData> {
-        match provider {
-            "openai" => self.openai_client_profile.as_ref(),
-            "xai" => self.xai_client_profile.as_ref(),
-            _ => None,
-        }
+        ProviderKind::new(provider.to_owned())
+            .ok()
+            .and_then(|provider| self.request_profiles.get(&provider))
     }
 }
diff --git a/backend/crates/gateway-admin/src/ports/mod.rs b/backend/crates/gateway-admin/src/ports/mod.rs
index 0b1539fd3..8b8cd3989 100644
--- a/backend/crates/gateway-admin/src/ports/mod.rs
+++ b/backend/crates/gateway-admin/src/ports/mod.rs
@@ -2,8 +2,14 @@
 
 pub mod backup;
 pub mod client_distribution;
+pub mod plugin_accounts;
+pub mod plugin_client_keys;
+pub mod plugin_management;
+pub mod plugin_release;
+pub mod plugins;
 pub mod pricing;
 pub mod provider;
+pub mod provider_extensions;
 pub mod proxy;
 pub mod store;
 pub mod system;
diff --git a/backend/crates/gateway-admin/src/ports/plugin_accounts.rs b/backend/crates/gateway-admin/src/ports/plugin_accounts.rs
new file mode 100644
index 000000000..1c1586f36
--- /dev/null
+++ b/backend/crates/gateway-admin/src/ports/plugin_accounts.rs
@@ -0,0 +1,34 @@
+//! 插件宿主访问账号权威所需的窄端口。
+
+use async_trait::async_trait;
+use gateway_core::account::ProviderAccountId;
+
+use crate::model::{
+    AdminError, MutationContext,
+    provider_credentials::{
+        PluginAccountCredential, PluginAccountListQuery, PluginAccountPage,
+        PluginAccountSaveResult, PreparedPluginAccountSave,
+    },
+};
+
+/// Runtime 只取得账号读写用例，不接触 Store、SQL 或完整管理服务集合。
+#[async_trait]
+pub trait PluginAccountAccess: Send + Sync {
+    async fn list(&self, query: PluginAccountListQuery) -> Result<PluginAccountPage, AdminError>;
+
+    async fn get_runtime(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<crate::model::accounts::AccountRecord, AdminError>;
+
+    async fn get_credential(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<PluginAccountCredential, AdminError>;
+
+    async fn save(
+        &self,
+        command: PreparedPluginAccountSave,
+        context: &MutationContext,
+    ) -> Result<PluginAccountSaveResult, AdminError>;
+}
diff --git a/backend/crates/gateway-admin/src/ports/plugin_client_keys.rs b/backend/crates/gateway-admin/src/ports/plugin_client_keys.rs
new file mode 100644
index 000000000..96e6e0ea0
--- /dev/null
+++ b/backend/crates/gateway-admin/src/ports/plugin_client_keys.rs
@@ -0,0 +1,16 @@
+//! 插件发现 Client Key 公开身份的窄端口。
+
+use async_trait::async_trait;
+
+use crate::model::{
+    AdminError,
+    plugin_client_keys::{PluginClientKeyListQuery, PluginClientKeyPage},
+};
+
+#[async_trait]
+pub trait PluginClientKeyAccess: Send + Sync {
+    async fn list(
+        &self,
+        query: PluginClientKeyListQuery,
+    ) -> Result<PluginClientKeyPage, AdminError>;
+}
diff --git a/backend/crates/gateway-admin/src/ports/plugin_management.rs b/backend/crates/gateway-admin/src/ports/plugin_management.rs
new file mode 100644
index 000000000..7bb5d4034
--- /dev/null
+++ b/backend/crates/gateway-admin/src/ports/plugin_management.rs
@@ -0,0 +1,57 @@
+use async_trait::async_trait;
+use gateway_core::runtime::extensions::ExtensionSetReference;
+
+use crate::model::{
+    AdminError,
+    plugins::management::{
+        PluginManagementRequest, PluginManagementResponse, PluginManagementTarget,
+        PluginManagementView,
+    },
+};
+
+/// 仅按 Admin 固定的发布引用分派；Runtime 不自行选择当前代次，也不拥有管理员身份。
+#[async_trait]
+pub trait PluginManagement: Send + Sync {
+    /// 复核固定发布代次中的模型访问域；调用方已校验持久实例仍为当前目标。
+    async fn authorize_models(
+        &self,
+        published: &ExtensionSetReference,
+        target: &PluginManagementTarget,
+    ) -> Result<(), AdminError>;
+
+    async fn start_callback(
+        &self,
+        published: &ExtensionSetReference,
+        target: &PluginManagementTarget,
+        command: crate::model::plugins::management::StartPluginManagementCallback,
+        context: &crate::model::auth::AdminRequestContext,
+    ) -> Result<crate::model::plugins::management::PluginManagementCallbackTicket, AdminError>;
+
+    async fn callback(
+        &self,
+        published: &ExtensionSetReference,
+        target: &PluginManagementTarget,
+        state: &str,
+        request: PluginManagementRequest,
+    ) -> Result<PluginManagementResponse, AdminError>;
+
+    async fn views(
+        &self,
+        published: &ExtensionSetReference,
+    ) -> Result<Vec<PluginManagementView>, AdminError>;
+
+    async fn resource(
+        &self,
+        published: &ExtensionSetReference,
+        target: &PluginManagementTarget,
+        path: &str,
+        public: bool,
+    ) -> Result<PluginManagementResponse, AdminError>;
+
+    async fn handle(
+        &self,
+        published: &ExtensionSetReference,
+        target: &PluginManagementTarget,
+        request: PluginManagementRequest,
+    ) -> Result<PluginManagementResponse, AdminError>;
+}
diff --git a/backend/crates/gateway-admin/src/ports/plugin_release.rs b/backend/crates/gateway-admin/src/ports/plugin_release.rs
new file mode 100644
index 000000000..1d9b5c3c6
--- /dev/null
+++ b/backend/crates/gateway-admin/src/ports/plugin_release.rs
@@ -0,0 +1,37 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OfficialPluginReleaseReadErrorKind {
+    Invalid,
+    NotFound,
+    Unavailable,
+}
+
+/// 文件系统错误不携带部署路径，避免把宿主布局传播到管理域和日志之外。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+#[error("official plugin release files are unavailable")]
+pub struct OfficialPluginReleaseReadError {
+    kind: OfficialPluginReleaseReadErrorKind,
+}
+
+impl OfficialPluginReleaseReadError {
+    #[must_use]
+    pub const fn new(kind: OfficialPluginReleaseReadErrorKind) -> Self {
+        Self { kind }
+    }
+
+    #[must_use]
+    pub const fn kind(self) -> OfficialPluginReleaseReadErrorKind {
+        self.kind
+    }
+}
+
+/// Host 只暴露与宿主发行物同信任边界的只读文件，不解释官方身份或插件包。
+#[async_trait]
+pub trait OfficialPluginReleaseFiles: Send + Sync {
+    async fn manifest(&self) -> Result<Option<Arc<[u8]>>, OfficialPluginReleaseReadError>;
+
+    async fn artifact(&self, file_name: &str) -> Result<Arc<[u8]>, OfficialPluginReleaseReadError>;
+}
diff --git a/backend/crates/gateway-admin/src/ports/plugins.rs b/backend/crates/gateway-admin/src/ports/plugins.rs
new file mode 100644
index 000000000..c6b4ef84b
--- /dev/null
+++ b/backend/crates/gateway-admin/src/ports/plugins.rs
@@ -0,0 +1,331 @@
+use std::{collections::BTreeMap, sync::Arc};
+
+use async_trait::async_trait;
+
+use super::store::AdminStoreResult;
+use crate::model::plugins::distribution::{
+    DownloadedPlugin, GithubReleaseQuery, PluginDistributionEgress, PluginRelease,
+    PluginSourceBinding, PluginUpdateSource, RemotePluginLocation, SourceCredential,
+    SourceCredentialInfo,
+};
+use crate::model::plugins::instances::{
+    PluginInstance, PluginInstanceMutation, PluginInstanceReplacement, PluginInstanceRuntime,
+    PluginInstanceSnapshot, PluginVersionConfiguration,
+};
+use crate::model::plugins::state::{
+    ApplyPluginStateMigration, DeletePluginState, PluginStateCommit, PluginStateConfiguration,
+    PluginStateMigrationBatch, PluginStateOwner, PluginStateOwnerRequest, PluginStateRecord,
+    PluginStateTransition, PluginStateWrite, PutPluginState,
+};
+use crate::model::{
+    AdminError, MutationContext, Revision,
+    plugins::{
+        InspectedPluginArtifact, InstalledPluginArtifact, PluginArtifactMutation,
+        PluginCompatibilityRequirements, PluginSource,
+    },
+};
+use gateway_core::runtime::extensions::ExtensionSetReference;
+
+/// Admin 准备完整候选并保活到提交后的发布结束；进程状态不能代替持久启用状态。
+#[async_trait]
+pub trait PluginPreparation: Send + Sync {
+    /// 静态判断业务配置是否完整，不启动进程；不完整的安装保留为待配置。
+    async fn configuration_ready(
+        &self,
+        instance: PluginInstance,
+        metadata: &crate::model::plugins::PluginArtifactMetadata,
+    ) -> Result<bool, AdminError>;
+    async fn validate(
+        &self,
+        instance: PluginInstance,
+    ) -> Result<PluginStateConfiguration, AdminError>;
+    /// 候选可使用未来 revision；其依赖的持久化事实必须按当前 source revision 读取。
+    /// 本次修改的实例 revision 必须等于候选 config_revision，准备失败时拒绝提交；历史故障可隔离。
+    async fn prepare(
+        &self,
+        source_revision: Revision,
+        snapshot: PluginInstanceSnapshot,
+    ) -> Result<ExtensionSetReference, AdminError>;
+    /// 返回当前进程的只读运行事实；缺省实现让不托管插件进程的组合保持兼容。
+    async fn runtime_diagnostics(
+        &self,
+        _snapshot: &PluginInstanceSnapshot,
+        _published_revision: Option<u64>,
+        _published: Option<&ExtensionSetReference>,
+    ) -> Option<BTreeMap<String, PluginInstanceRuntime>> {
+        None
+    }
+    async fn activate_state(
+        &self,
+        _prepared: &ExtensionSetReference,
+        _instance: &PluginInstance,
+    ) -> Result<(), AdminError> {
+        Ok(())
+    }
+    async fn quiesce_instance(
+        &self,
+        _instance_id: &str,
+        _artifact_sha256: &str,
+        _revision: Revision,
+    ) {
+    }
+    async fn migrate_state(
+        &self,
+        _prepared: &ExtensionSetReference,
+        _transition: PluginStateTransition,
+    ) -> Result<(), AdminError> {
+        Err(AdminError::unavailable("插件状态迁移运行时不可用"))
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PluginStateStoreErrorKind {
+    Invalid,
+    NotFound,
+    Conflict,
+    Quota,
+    PermissionDenied,
+    Unavailable,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("plugin state operation failed")]
+pub struct PluginStateStoreError {
+    kind: PluginStateStoreErrorKind,
+}
+
+impl PluginStateStoreError {
+    #[must_use]
+    pub const fn new(kind: PluginStateStoreErrorKind) -> Self {
+        Self { kind }
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> PluginStateStoreErrorKind {
+        self.kind
+    }
+}
+
+pub type PluginStateStoreResult<T> = Result<T, PluginStateStoreError>;
+
+/// 私有状态的窄端口；不暴露 SQL、连接或跨命名空间事务。
+#[async_trait]
+pub trait PluginStateStore: Send + Sync {
+    async fn load_owner(
+        &self,
+        request: PluginStateOwnerRequest,
+    ) -> PluginStateStoreResult<Option<PluginStateOwner>>;
+    async fn get(
+        &self,
+        owner: &PluginStateOwner,
+        namespace: &str,
+        key: &str,
+    ) -> PluginStateStoreResult<Option<PluginStateRecord>>;
+    async fn put(
+        &self,
+        owner: &PluginStateOwner,
+        command: PutPluginState,
+    ) -> PluginStateStoreResult<PluginStateWrite>;
+    async fn delete(
+        &self,
+        owner: &PluginStateOwner,
+        command: DeletePluginState,
+    ) -> PluginStateStoreResult<bool>;
+    async fn transition_required(
+        &self,
+        instance_id: &str,
+        target: &PluginStateConfiguration,
+    ) -> PluginStateStoreResult<bool>;
+    async fn begin_transition(
+        &self,
+        instance_id: &str,
+        expected_instance_revision: Revision,
+        artifact_sha256: &str,
+        target: PluginStateConfiguration,
+    ) -> PluginStateStoreResult<PluginStateTransition>;
+    async fn migration_batch(
+        &self,
+        transition_id: &str,
+        namespace: &str,
+        maximum_records: u32,
+    ) -> PluginStateStoreResult<PluginStateMigrationBatch>;
+    async fn apply_migration_batch(
+        &self,
+        command: ApplyPluginStateMigration,
+    ) -> PluginStateStoreResult<()>;
+    async fn abort_transition(&self, transition_id: &str) -> PluginStateStoreResult<()>;
+}
+
+/// Host 拥有联网、重定向、凭据作用域、限流与有界下载，不解释插件包。
+#[async_trait]
+pub trait PluginDistribution: Send + Sync {
+    fn validate_source(&self, source: &PluginUpdateSource) -> Result<(), AdminError>;
+    fn validate_credential(&self, credential: &SourceCredential) -> Result<(), AdminError>;
+    async fn query_release(
+        &self,
+        query: GithubReleaseQuery,
+        credentials: Vec<SourceCredential>,
+        egress: Option<PluginDistributionEgress>,
+    ) -> Result<PluginRelease, AdminError>;
+    async fn download(
+        &self,
+        location: RemotePluginLocation,
+        credentials: Vec<SourceCredential>,
+        egress: Option<PluginDistributionEgress>,
+    ) -> Result<DownloadedPlugin, AdminError>;
+}
+
+/// Runtime 只解释插件包格式；安装事务与来源选择归 Admin。
+#[async_trait]
+pub trait PluginPackageInspector: Send + Sync {
+    /// 当前宿主对权限标识的说明，供展示投影使用，不属于不可变制品元数据。
+    fn permission_descriptions(
+        &self,
+        permissions: &[String],
+    ) -> Vec<crate::model::plugins::PluginPermissionDescription> {
+        permissions
+            .iter()
+            .map(
+                |permission| crate::model::plugins::PluginPermissionDescription {
+                    permission: permission.clone(),
+                    label: permission.clone(),
+                    description: String::new(),
+                },
+            )
+            .collect()
+    }
+
+    async fn inspect(
+        &self,
+        archive: Arc<[u8]>,
+        expected_sha256: Option<String>,
+    ) -> Result<InspectedPluginArtifact, AdminError>;
+
+    /// 从已安装且摘要匹配的制品中读取可展示的静态图标，不启动插件实例。
+    async fn icon(
+        &self,
+        _archive: Arc<[u8]>,
+        _expected_sha256: String,
+        _theme: crate::model::plugins::PluginIconTheme,
+    ) -> Result<Option<crate::model::plugins::PluginArtifactIconResource>, AdminError> {
+        Err(AdminError::unavailable("插件图标读取不可用"))
+    }
+
+    /// 只读取已校验包的静态宿主要求；不得准备或启动插件进程。
+    async fn compatibility(
+        &self,
+        _archive: Arc<[u8]>,
+        _expected_sha256: String,
+    ) -> Result<PluginCompatibilityRequirements, AdminError> {
+        Err(AdminError::unavailable("插件兼容性检查不可用"))
+    }
+}
+
+#[async_trait]
+pub trait PluginStore: Send + Sync {
+    /// 只复核精确管理目标的启用、接受事实和版本，不读取实例配置或密钥。
+    async fn management_target_is_current(
+        &self,
+        target: &crate::model::plugins::management::PluginManagementTarget,
+    ) -> AdminStoreResult<bool>;
+    async fn load_instances(&self) -> AdminStoreResult<PluginInstanceSnapshot>;
+    /// 读取对应制品最近一次启用时提交的配置，密钥始终留在服务端。
+    async fn load_version_configuration(
+        &self,
+        _id: &str,
+        _digest: &str,
+    ) -> AdminStoreResult<Option<PluginVersionConfiguration>> {
+        Ok(None)
+    }
+    /// 只返回有可恢复配置的制品摘要，不读取敏感值。
+    async fn configuration_versions(&self, _id: &str) -> AdminStoreResult<Vec<String>> {
+        Ok(Vec::new())
+    }
+    async fn save_instance(
+        &self,
+        instance: PluginInstance,
+        expected_revision: Revision,
+        context: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation>;
+    async fn save_instance_with_state(
+        &self,
+        instance: PluginInstance,
+        expected_revision: Revision,
+        state: PluginStateCommit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        if !state.configuration.namespaces.is_empty() || state.transition_id.is_some() {
+            return Err(super::store::AdminStoreError::new(
+                super::store::AdminStoreErrorKind::Unavailable,
+                "plugin state",
+                "plugin state store is unavailable",
+            ));
+        }
+        self.save_instance(instance, expected_revision, context)
+            .await
+    }
+    /// 保存目标并停用明确确认的配置，必须共享事务和配置版本检查。
+    async fn save_instance_replacing(
+        &self,
+        instance: PluginInstance,
+        expected_revision: Revision,
+        state: PluginStateCommit,
+        replacements: &[PluginInstanceReplacement],
+        context: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        if !replacements.is_empty() {
+            return Err(super::store::AdminStoreError::new(
+                super::store::AdminStoreErrorKind::Unavailable,
+                "plugin",
+                "atomic plugin configuration switching is unavailable",
+            ));
+        }
+        self.save_instance_with_state(instance, expected_revision, state, context)
+            .await
+    }
+
+    async fn delete_instance(
+        &self,
+        id: &str,
+        expected_revision: Revision,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn list_update_sources(&self) -> AdminStoreResult<Vec<PluginSourceBinding>>;
+    async fn change_update_source(
+        &self,
+        binding: PluginSourceBinding,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn list_source_credentials(&self) -> AdminStoreResult<Vec<SourceCredentialInfo>>;
+    async fn load_source_credential(&self, id: &str) -> AdminStoreResult<SourceCredential>;
+    async fn save_source_credential(
+        &self,
+        credential: SourceCredential,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn delete_source_credential(
+        &self,
+        id: &str,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn list_artifacts(&self) -> AdminStoreResult<Vec<InstalledPluginArtifact>>;
+    async fn load_artifact(&self, digest: &str) -> AdminStoreResult<InspectedPluginArtifact>;
+    async fn install_artifact(
+        &self,
+        artifact: InspectedPluginArtifact,
+        source: PluginSource,
+        context: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation>;
+    /// 接受不可变制品声明的全部能力域；接受事实不随实例设置变化。
+    async fn accept_artifact(
+        &self,
+        digest: &str,
+        context: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation>;
+    /// 删除制品及其无引用下载凭据，最后一个版本同时删除来源规则，清理与审计必须原子提交。
+    async fn delete_artifact(
+        &self,
+        digest: &str,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+}
diff --git a/backend/crates/gateway-admin/src/ports/provider.rs b/backend/crates/gateway-admin/src/ports/provider.rs
index a13f0de48..0bc7452aa 100644
--- a/backend/crates/gateway-admin/src/ports/provider.rs
+++ b/backend/crates/gateway-admin/src/ports/provider.rs
@@ -15,11 +15,11 @@ use crate::model::observability::{
 };
 use crate::model::provider_credentials::{
     AuthorizationStarted, CompleteAuthorization, ConsumeProviderResetCredit,
-    PendingAuthorizationMutation, PrepareCredentialImport, PrepareCredentialRefresh,
-    PrepareCredentialRotation, PreparedAuthorizationCommit, PreparedCredentialImport,
-    PreparedCredentialRotation, ProviderExport, ProviderExportCredentialInput, ProviderModels,
-    ProviderProfileAvatar, ProviderProfileStatistics, ProviderQuota, ProviderQuotaRequest,
-    ProviderResetCreditResult, ProviderResetCredits, ProviderSubscription, explicit_plan_type,
+    PrepareCredentialImport, PrepareCredentialRefresh, PrepareCredentialRotation,
+    PreparedAuthorizationCommit, PreparedCredentialImport, PreparedCredentialRotation,
+    ProviderExport, ProviderExportCredentialInput, ProviderModels, ProviderProfileAvatar,
+    ProviderProfileStatistics, ProviderQuota, ProviderQuotaRequest, ProviderResetCreditResult,
+    ProviderResetCredits, ProviderSubscription, explicit_plan_type,
 };
 use crate::model::{
     provider_credentials::{ProviderDocument, ProviderQuotaWindow},
@@ -117,6 +117,21 @@ pub trait ProviderAdmin: Send + Sync {
 
     fn provider_kind(&self) -> &ProviderKind;
 
+    fn credential_capabilities(
+        &self,
+    ) -> crate::model::provider_capabilities::ProviderCredentialCapabilities {
+        Default::default()
+    }
+
+    /// 只读取当前代次的声明及账号类型，不执行网络或数据库查询。
+    fn account_capabilities(
+        &self,
+        _account_id: &ProviderAccountId,
+        _authentication_kind: &str,
+    ) -> crate::model::provider_capabilities::ProviderAccountCapabilities {
+        Default::default()
+    }
+
     /// 提供该 Provider 的可选客户端身份；通用管理层不解释内部字段。
     fn client_profile_options(
         &self,
@@ -124,6 +139,11 @@ pub trait ProviderAdmin: Send + Sync {
         Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
     }
 
+    /// 没有持久选择时使用的 Provider 默认画像；只返回已准备的本地事实。
+    fn default_client_profile(&self) -> Option<gateway_core::account::OpaqueProviderData> {
+        None
+    }
+
     /// 校验并投影客户端身份，结果不含认证或账号材料。
     fn preview_client_profile(
         &self,
@@ -150,7 +170,7 @@ pub trait ProviderAdmin: Send + Sync {
     async fn account_facts_changed(&self, _account_ids: &[ProviderAccountId]) {}
 
     /// 生成一次连接测试所需的 Provider-owned operation；Core 负责实际执行与落账。
-    fn connection_test_operation(
+    async fn connection_test_operation(
         &self,
         upstream_model: &UpstreamModelId,
         input_text: &str,
@@ -180,7 +200,7 @@ pub trait ProviderAdmin: Send + Sync {
 
     async fn start_authorization(
         &self,
-        pending: PendingAuthorizationMutation,
+        command: crate::model::provider_credentials::PrepareAuthorization,
     ) -> Result<AuthorizationStarted, ProviderAdminError>;
 
     async fn complete_authorization(
@@ -188,6 +208,14 @@ pub trait ProviderAdmin: Send + Sync {
         command: CompleteAuthorization,
     ) -> Result<PreparedAuthorizationCommit, ProviderAdminError>;
 
+    async fn poll_authorization(
+        &self,
+        _command: crate::model::provider_credentials::PollAuthorization,
+    ) -> Result<crate::model::provider_credentials::PreparedAuthorizationPoll, ProviderAdminError>
+    {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
     async fn prepare_rotation(
         &self,
         command: PrepareCredentialRotation,
@@ -275,16 +303,69 @@ pub trait ProviderAdmin: Send + Sync {
 /// 按 ProviderKind 动态发现管理能力；不含具体 Provider 分支。
 #[derive(Clone)]
 pub struct ProviderAdminRegistry {
-    providers: Arc<BTreeMap<ProviderKind, Arc<dyn ProviderAdmin>>>,
+    pub(super) providers: Arc<BTreeMap<ProviderKind, Arc<dyn ProviderAdmin>>>,
+    pub(super) extensions: Option<(
+        super::provider_extensions::ProviderAdminExtensionIndex,
+        gateway_core::runtime::RuntimeSnapshotHandle,
+    )>,
+    pub(super) snapshot: Option<Arc<gateway_core::routing::RuntimeSnapshot>>,
 }
 
 impl ProviderAdminRegistry {
-    #[must_use]
-    pub fn pricing_catalog(&self) -> gateway_core::metering::PricingOverrides {
-        self.providers
+    /// 返回当前冻结代次中真正提供客户端画像选项的 Provider。
+    pub fn client_profile_providers(&self) -> Result<Vec<ProviderKind>, ProviderAdminError> {
+        let frozen = self.freeze()?;
+        let mut supported = Vec::new();
+        for (kind, provider) in frozen.providers.iter() {
+            match provider.client_profile_options() {
+                Ok(_) => supported.push(kind.clone()),
+                Err(error) if error.kind() == ProviderAdminErrorKind::Unsupported => {}
+                Err(error) => return Err(error),
+            }
+        }
+        Ok(supported)
+    }
+
+    /// 一次读取冻结整个目录，能力与执行器始终来自同一已发布代次。
+    pub fn credential_descriptors(
+        &self,
+    ) -> Result<
+        Vec<crate::model::provider_capabilities::ProviderCredentialDescriptor>,
+        ProviderAdminError,
+    > {
+        Ok(self
+            .freeze()?
+            .providers
+            .iter()
+            .map(|(kind, provider)| {
+                crate::model::provider_capabilities::ProviderCredentialDescriptor {
+                    provider: kind.clone(),
+                    capabilities: provider.credential_capabilities(),
+                }
+            })
+            .collect())
+    }
+
+    pub fn pricing_catalog(
+        &self,
+    ) -> Result<gateway_core::metering::PricingOverrides, ProviderAdminError> {
+        Ok(self
+            .freeze()?
+            .providers
             .iter()
             .map(|(kind, provider)| (kind.as_str().to_owned(), provider.pricing_catalog()))
-            .collect()
+            .collect())
+    }
+
+    /// 一个管理用例可显式冻结目录，批量操作不会混入下一份配置。
+    pub fn freeze(&self) -> Result<Self, ProviderAdminError> {
+        let Some((index, snapshots)) = &self.extensions else {
+            return Ok(self.clone());
+        };
+        let snapshot = snapshots
+            .acquire()
+            .map_err(|_| ProviderAdminError::new(ProviderAdminErrorKind::Unavailable))?;
+        index.resolve(snapshot)
     }
 
     /// 创建无重复 ProviderKind 的注册表。
@@ -304,17 +385,25 @@ impl ProviderAdminRegistry {
         }
         Ok(Self {
             providers: Arc::new(registered),
+            extensions: None,
+            snapshot: None,
         })
     }
 
     pub fn require(
         &self,
         provider_kind: &ProviderKind,
-    ) -> Result<Arc<dyn ProviderAdmin>, ProviderAdminError> {
-        self.providers
-            .get(provider_kind)
-            .cloned()
-            .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    ) -> Result<super::provider_extensions::ProviderAdminHandle, ProviderAdminError> {
+        if let Some(provider) = self.providers.get(provider_kind) {
+            return Ok(super::provider_extensions::ProviderAdminHandle {
+                provider: provider.clone(),
+                snapshot: self.snapshot.clone(),
+            });
+        }
+        if self.extensions.is_some() {
+            return self.freeze()?.require(provider_kind);
+        }
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
     }
 
     /// 账号目录与关联列表共用套餐补全和展示规则，已知账号套餐优先于额度快照。
@@ -339,7 +428,7 @@ impl ProviderAdminRegistry {
         let plan_type = explicit_plan_type(plan_type)?.trim();
         let provider = ProviderKind::new(provider_kind.to_owned())
             .ok()
-            .and_then(|kind| self.providers.get(&kind));
+            .and_then(|kind| self.require(&kind).ok());
         let display = provider.map_or_else(
             || plan_type.to_owned(),
             |provider| provider.plan_type_display(plan_type),
@@ -355,14 +444,16 @@ impl ProviderAdminRegistry {
             ProviderKind,
             gateway_core::account::OpaqueProviderData,
         >,
-    ) -> Vec<DashboardWireProfile> {
-        self.providers
+    ) -> Result<Vec<DashboardWireProfile>, ProviderAdminError> {
+        Ok(self
+            .freeze()?
+            .providers
             .iter()
             .filter_map(|(kind, provider)| match configurations.get(kind) {
                 Some(configuration) => provider.configured_wire_profile(configuration),
                 None => provider.dashboard_wire_profile(),
             })
-            .collect()
+            .collect())
     }
 
     /// 动态分派 Provider-owned 费用规则，不含任何具体 Provider 分支。
diff --git a/backend/crates/gateway-admin/src/ports/provider_extensions.rs b/backend/crates/gateway-admin/src/ports/provider_extensions.rs
new file mode 100644
index 000000000..1a569466d
--- /dev/null
+++ b/backend/crates/gateway-admin/src/ports/provider_extensions.rs
@@ -0,0 +1,112 @@
+//! 管理操作解析 Core 已发布的扩展集合；不持有独立的当前版本指针。
+
+use std::{
+    collections::BTreeMap,
+    sync::{Arc, RwLock, Weak},
+};
+
+use gateway_core::{
+    routing::{ProviderKind, RuntimeSnapshot},
+    runtime::{RuntimeSnapshotHandle, extensions::ExtensionSetId},
+};
+
+use super::provider::{
+    ProviderAdmin, ProviderAdminError, ProviderAdminErrorKind, ProviderAdminRegistry,
+};
+
+#[derive(Clone)]
+pub struct ProviderAdminExtensionIndex {
+    base: Arc<BTreeMap<ProviderKind, Arc<dyn ProviderAdmin>>>,
+    sets: Arc<RwLock<BTreeMap<ExtensionSetId, Weak<ProviderAdminRegistry>>>>,
+}
+
+impl ProviderAdminExtensionIndex {
+    #[must_use]
+    pub fn new(base: ProviderAdminRegistry) -> Self {
+        Self {
+            base: base.providers,
+            sets: Arc::default(),
+        }
+    }
+
+    pub fn register(
+        &self,
+        id: ExtensionSetId,
+        providers: impl IntoIterator<Item = Arc<dyn ProviderAdmin>>,
+    ) -> Result<Arc<ProviderAdminRegistry>, ProviderAdminError> {
+        let registry = Arc::new(ProviderAdminRegistry::new(
+            self.base.values().cloned().chain(providers),
+        )?);
+        let mut sets = self
+            .sets
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        sets.retain(|_, registry| registry.strong_count() != 0);
+        if sets.contains_key(&id) {
+            return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+        }
+        sets.insert(id, Arc::downgrade(&registry));
+        Ok(registry)
+    }
+
+    #[must_use]
+    pub fn registry(&self, snapshots: RuntimeSnapshotHandle) -> ProviderAdminRegistry {
+        ProviderAdminRegistry {
+            providers: self.base.clone(),
+            extensions: Some((self.clone(), snapshots)),
+            snapshot: None,
+        }
+    }
+
+    pub(super) fn resolve(
+        &self,
+        snapshot: Arc<RuntimeSnapshot>,
+    ) -> Result<ProviderAdminRegistry, ProviderAdminError> {
+        let reference = snapshot
+            .extensions()
+            .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::Unavailable))?;
+        if !reference.can_serve() {
+            return Err(ProviderAdminError::new(ProviderAdminErrorKind::Unavailable));
+        }
+        let registry = self
+            .sets
+            .read()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .get(reference.id())
+            .and_then(Weak::upgrade)
+            .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::Unavailable))?;
+        Ok(ProviderAdminRegistry {
+            providers: registry.providers.clone(),
+            extensions: None,
+            snapshot: Some(snapshot),
+        })
+    }
+}
+
+/// 管理操作及其后台观测保活同一集合，避免发布切换在 await 期间终止旧进程。
+#[derive(Clone)]
+pub struct ProviderAdminHandle {
+    pub(super) provider: Arc<dyn ProviderAdmin>,
+    pub(super) snapshot: Option<Arc<RuntimeSnapshot>>,
+}
+
+impl ProviderAdminHandle {
+    /// 管理准备与 Core 探测共享完整快照，不能在两次 await 之间重新解析插件版本。
+    #[must_use]
+    pub fn snapshot(&self) -> Option<Arc<RuntimeSnapshot>> {
+        self.snapshot.clone()
+    }
+}
+
+impl std::ops::Deref for ProviderAdminHandle {
+    type Target = dyn ProviderAdmin;
+    fn deref(&self) -> &Self::Target {
+        self.provider.as_ref()
+    }
+}
+
+impl AsRef<dyn ProviderAdmin> for ProviderAdminHandle {
+    fn as_ref(&self) -> &(dyn ProviderAdmin + 'static) {
+        self.provider.as_ref()
+    }
+}
diff --git a/backend/crates/gateway-admin/src/ports/store.rs b/backend/crates/gateway-admin/src/ports/store.rs
index 59e4b48e3..bb440881c 100644
--- a/backend/crates/gateway-admin/src/ports/store.rs
+++ b/backend/crates/gateway-admin/src/ports/store.rs
@@ -32,7 +32,8 @@ use crate::model::{
     },
     provider_credentials::{
         AuthorizationCommit, CredentialDetails, CredentialImportCommit, CredentialImportResult,
-        CredentialMutationResult, CredentialRotationCommit, ProviderExportCredentialInput,
+        CredentialMutationResult, CredentialRotationCommit, PluginAccountListQuery,
+        PluginAccountPage, ProviderExportCredentialInput,
     },
     quota_forecast_sampling::QuotaForecastHistory,
     settings::{AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RuntimeSettings},
@@ -88,6 +89,12 @@ pub type AdminStoreResult<T> = Result<T, AdminStoreError>;
 /// 账号目录与公共账号写操作。
 #[async_trait]
 pub trait AccountStore: Send + Sync {
+    /// 插件回调按授权 Provider/账号在数据库过滤后做稳定 cursor 分页。
+    async fn list_plugin_accounts(
+        &self,
+        query: PluginAccountListQuery,
+    ) -> AdminStoreResult<PluginAccountPage>;
+
     async fn list_accounts(
         &self,
         query: AccountListQuery,
@@ -123,12 +130,24 @@ pub trait AccountStore: Send + Sync {
         account_id: &gateway_core::account::ProviderAccountId,
     ) -> AdminStoreResult<Option<CredentialDetails>>;
 
+    /// 插件按全局账号 ID 读取时，由数据库记录提供权威 Provider 归属。
+    async fn credential_details_by_id(
+        &self,
+        account_id: &gateway_core::account::ProviderAccountId,
+    ) -> AdminStoreResult<Option<CredentialDetails>>;
+
     async fn load_credentials_for_export(
         &self,
         provider_kind: &gateway_core::routing::ProviderKind,
         account_ids: &[gateway_core::account::ProviderAccountId],
     ) -> AdminStoreResult<Vec<ProviderExportCredentialInput>>;
 
+    /// 插件凭据读取只接收账号 ID，不接受调用方另行声明 Provider。
+    async fn load_credential_for_plugin(
+        &self,
+        account_id: &gateway_core::account::ProviderAccountId,
+    ) -> AdminStoreResult<Option<ProviderExportCredentialInput>>;
+
     async fn commit_credential_import(
         &self,
         command: CredentialImportCommit,
@@ -139,7 +158,13 @@ pub trait AccountStore: Send + Sync {
         &self,
         command: AuthorizationCommit,
         context: &MutationContext,
-    ) -> AdminStoreResult<CredentialMutationResult>;
+    ) -> AdminStoreResult<crate::model::provider_credentials::AuthorizationCommitResult>;
+
+    /// 已提交的授权结果独立于插件进程和 Redis 临时状态；只有原管理员身份可读。
+    async fn authorization_receipt(
+        &self,
+        key: &crate::model::provider_credentials::AuthorizationReceiptKey,
+    ) -> AdminStoreResult<Option<crate::model::provider_credentials::CredentialBatchMutationResult>>;
 
     async fn commit_credential_rotation(
         &self,
@@ -396,6 +421,9 @@ pub trait ObservabilityStore: Send + Sync {
 
     async fn list_usage_records(&self, query: UsageQuery) -> AdminStoreResult<UsagePage>;
 
+    /// 区间内请求及错误事实的平台集合，不依赖当前注册或账号是否仍存在。
+    async fn usage_provider_kinds(&self, range: TimeRange) -> AdminStoreResult<Vec<String>>;
+
     async fn usage_record_detail(&self, request_id: &str) -> AdminStoreResult<UsageDetail>;
 
     async fn usage_summary(
@@ -488,9 +516,25 @@ pub struct AdminStorePorts {
     observability: Arc<dyn ObservabilityStore>,
     settings: Arc<dyn SettingsStore>,
     backup: BackupStorePorts,
+    plugins: Arc<dyn super::plugins::PluginStore>,
+    plugin_state: Arc<dyn super::plugins::PluginStateStore>,
 }
 
 impl AdminStorePorts {
+    #[must_use]
+    pub fn plugins(&self) -> Arc<dyn super::plugins::PluginStore> {
+        Arc::clone(&self.plugins)
+    }
+
+    #[must_use]
+    pub fn plugin_state(&self) -> Arc<dyn super::plugins::PluginStateStore> {
+        Arc::clone(&self.plugin_state)
+    }
+
+    #[expect(
+        clippy::too_many_arguments,
+        reason = "组合根需显式注入各领域窄端口，不能用服务定位器隐藏依赖"
+    )]
     #[must_use]
     pub fn new(
         accounts: AdminAccountStorePorts,
@@ -499,6 +543,8 @@ impl AdminStorePorts {
         observability: Arc<dyn ObservabilityStore>,
         settings: Arc<dyn SettingsStore>,
         backup: BackupStorePorts,
+        plugins: Arc<dyn super::plugins::PluginStore>,
+        plugin_state: Arc<dyn super::plugins::PluginStateStore>,
     ) -> Self {
         Self {
             accounts,
@@ -507,6 +553,8 @@ impl AdminStorePorts {
             observability,
             settings,
             backup,
+            plugins,
+            plugin_state,
         }
     }
 
diff --git a/backend/crates/gateway-admin/src/ports/system.rs b/backend/crates/gateway-admin/src/ports/system.rs
index 7196a89ce..69e274fd8 100644
--- a/backend/crates/gateway-admin/src/ports/system.rs
+++ b/backend/crates/gateway-admin/src/ports/system.rs
@@ -1,15 +1,33 @@
 //! Host 为系统管理用例提供的进程与操作系统能力。
 
-use std::pin::Pin;
+use std::{pin::Pin, sync::Arc};
 
 use async_trait::async_trait;
 use futures::Stream;
 
+use crate::model::Revision;
 use crate::model::system::{
     SystemOperationAccepted, SystemUpdateDetail, SystemUpdateEvent, SystemUpdateStatus,
     SystemVersion,
 };
 
+/// Host 已校验并解包的同一更新候选；字节只含发行清单，不含运行配置或凭据。
+#[derive(Clone)]
+pub struct SystemUpdateCandidate {
+    pub target_version: String,
+    pub release_manifest: Arc<[u8]>,
+}
+
+impl std::fmt::Debug for SystemUpdateCandidate {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("SystemUpdateCandidate")
+            .field("target_version", &self.target_version)
+            .field("release_manifest_bytes", &self.release_manifest.len())
+            .finish()
+    }
+}
+
 /// Host 系统操作失败类型。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SystemOperationErrorKind {
@@ -51,6 +69,18 @@ impl SystemOperationError {
 /// 每个订阅者独占的系统事件流。
 pub type SystemUpdateEventStream = Pin<Box<dyn Stream<Item = SystemUpdateEvent> + Send + 'static>>;
 
+/// Admin 对启用实例和制品作兼容决策；Host 只负责候选下载、校验与文件交换。
+#[async_trait]
+pub trait SystemUpdatePreflight: Send + Sync {
+    async fn validate(
+        &self,
+        candidate: SystemUpdateCandidate,
+    ) -> Result<Revision, SystemOperationError>;
+
+    /// 在文件交换临界点复核全局配置 CAS，不能用较早快照掩盖实例变更。
+    async fn confirm_revision(&self, expected: Revision) -> Result<(), SystemOperationError>;
+}
+
 /// 版本、自更新、回滚和重启能力；实现唯一归 gateway-host。
 #[async_trait]
 pub trait SystemOperations: Send + Sync {
@@ -66,11 +96,15 @@ pub trait SystemOperations: Send + Sync {
     async fn perform_update(
         &self,
         target_version: Option<String>,
+        preflight: Arc<dyn SystemUpdatePreflight>,
     ) -> Result<SystemOperationAccepted, SystemOperationError>;
 
     async fn update_status(&self) -> Result<SystemUpdateStatus, SystemOperationError>;
 
-    async fn rollback(&self) -> Result<SystemOperationAccepted, SystemOperationError>;
+    async fn rollback(
+        &self,
+        preflight: Arc<dyn SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError>;
 
     async fn restart(&self) -> Result<SystemOperationAccepted, SystemOperationError>;
 }
diff --git a/backend/crates/gateway-admin/src/use_case/accounts.rs b/backend/crates/gateway-admin/src/use_case/accounts.rs
index 5ce26298b..389a2c367 100644
--- a/backend/crates/gateway-admin/src/use_case/accounts.rs
+++ b/backend/crates/gateway-admin/src/use_case/accounts.rs
@@ -1,6 +1,9 @@
 //! 统一账号目录与跨 Provider 动态分派。
 
-use std::{collections::BTreeMap, sync::Arc};
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    sync::Arc,
+};
 
 use async_trait::async_trait;
 use chrono::{Duration, Utc};
@@ -23,12 +26,14 @@ use crate::{
         observability::TimeRange,
         provider_credentials::{
             AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountPersonalInfo,
-            AccountRefreshResult, ConsumeProviderResetCredit, PrepareCredentialRefresh,
-            ProviderModels, ProviderProfileAvatar, ProviderQuota, ProviderQuotaRequest,
-            ProviderQuotaWindow, ProviderResetCreditResult, ProviderResetCredits,
-            QuotaLocalUsageAttribution,
+            AccountRefreshResult, AccountUsagePeriod, ConsumeProviderResetCredit,
+            PrepareCredentialRefresh, ProviderModels, ProviderProfileAvatar, ProviderQuota,
+            ProviderQuotaRequest, ProviderQuotaWindow, ProviderResetCreditResult,
+            ProviderResetCredits, QuotaLocalUsageAttribution,
+        },
+        quota_forecast::{
+            AccountQuotaForecastReport, account_quota_forecasts, quota_forecast_source_window,
         },
-        quota_forecast::{AccountQuotaForecastReport, account_quota_forecasts},
         quota_forecast_sampling::{QuotaForecastPoint, select_forecast_sample},
     },
     ports::{
@@ -210,7 +215,7 @@ impl DefaultAccountsService {
     ) -> Result<
         (
             AccountPageItem,
-            Arc<dyn crate::ports::provider::ProviderAdmin>,
+            crate::ports::provider_extensions::ProviderAdminHandle,
         ),
         AdminError,
     > {
@@ -314,14 +319,25 @@ impl DefaultAccountsService {
             .await
             .map_err(|error| map_store_error(error, "rolling account usage"))?;
         let rolling_usage = rolling_usage.into_iter().next();
-        let mut quota = provider
+        let mut quota = match provider
             .quota(ProviderQuotaRequest {
                 account_id: account_id.clone(),
                 refresh: refresh_quota,
                 rolling_usage: rolling_usage.clone(),
             })
             .await
-            .map_err(|error| map_provider_error(error, "provider quota"))?;
+        {
+            Ok(quota) => quota,
+            // 凭据更新后的账号投影不要求 Provider 提供额度；显式刷新仍须支持该操作。
+            Err(error)
+                if !refresh_quota
+                    && error.kind()
+                        == crate::ports::provider::ProviderAdminErrorKind::Unsupported =>
+            {
+                empty_quota()
+            }
+            Err(error) => return Err(map_provider_error(error, "provider quota")),
+        };
         let mut stored = if refresh_quota {
             self.load_account(account_id).await?
         } else {
@@ -342,6 +358,8 @@ impl DefaultAccountsService {
                     .and_then(|(window, _)| window.local_usage.clone())
             });
         Ok(AccountDirectoryItem {
+            capabilities: provider
+                .account_capabilities(account_id, &stored.account.authentication_kind),
             plan_type_display: self.providers.resolve_account_plan(
                 stored.account.provider_kind.as_str(),
                 &mut stored.account.plan_type,
@@ -358,6 +376,10 @@ impl DefaultAccountsService {
 #[async_trait]
 impl AccountsService for DefaultAccountsService {
     async fn list(&self, query: AccountListQuery) -> Result<AccountDirectoryPage, AdminError> {
+        let providers = self
+            .providers
+            .freeze()
+            .map_err(|error| map_provider_error(error, "provider directory"))?;
         let runtime = self
             .account_runtime
             .active_rate_limits()
@@ -393,7 +415,7 @@ impl AccountsService for DefaultAccountsService {
                 .map_err(|_| AdminError::invalid("Provider 账号 ID 不合法"))?;
             // 单个账号的 quota 投影失败（Provider 未注册或 quota 读取失败）不拖垮整页：
             // 该账号降级为空额度投影，其余账号与页面状态照常返回。
-            let provider = match self.providers.require(&account.provider_kind) {
+            let provider = match providers.require(&account.provider_kind) {
                 Ok(provider) => provider,
                 Err(error) => {
                     tracing::warn!(
@@ -434,13 +456,22 @@ impl AccountsService for DefaultAccountsService {
             .into_iter()
             .zip(quotas)
             .map(|(mut item, quota)| {
+                let id = ProviderAccountId::new(item.account.id.clone())
+                    .map_err(|_| AdminError::invalid("Provider 账号 ID 不合法"))?;
+                let capabilities = providers
+                    .require(&item.account.provider_kind)
+                    .map(|provider| {
+                        provider.account_capabilities(&id, &item.account.authentication_kind)
+                    })
+                    .unwrap_or_default();
                 let usage = api_key_usage.remove(&item.account.id).or_else(|| {
                     quota
                         .usage_window()
                         .and_then(|(window, _)| window.local_usage.clone())
                 });
-                AccountDirectoryItem {
-                    plan_type_display: self.providers.resolve_account_plan(
+                Ok(AccountDirectoryItem {
+                    capabilities,
+                    plan_type_display: providers.resolve_account_plan(
                         item.account.provider_kind.as_str(),
                         &mut item.account.plan_type,
                         Some(&quota),
@@ -449,14 +480,15 @@ impl AccountsService for DefaultAccountsService {
                     account: item.account,
                     projection: item.projection,
                     quota,
-                }
+                })
             })
-            .collect();
+            .collect::<Result<Vec<_>, AdminError>>()?;
         Ok(AccountDirectoryPage {
             config_revision: page.config_revision,
             items,
             total: page.total,
             summary: page.summary,
+            providers: page.providers,
         })
     }
 
@@ -465,6 +497,10 @@ impl AccountsService for DefaultAccountsService {
         context: &MutationContext,
         account_ids: Vec<ProviderAccountId>,
     ) -> Result<AccountExportBundle, AdminError> {
+        let providers = self
+            .providers
+            .freeze()
+            .map_err(|error| map_provider_error(error, "provider export"))?;
         if account_ids.is_empty() || account_ids.len() > 200 {
             return Err(AdminError::invalid("账号导出数量必须在 1 到 200 之间"));
         }
@@ -483,12 +519,21 @@ impl AccountsService for DefaultAccountsService {
         }) {
             return Err(AdminError::invalid("账号导出列表包含重复 ID"));
         }
-        let mut documents = Vec::with_capacity(grouped.len());
-        for (provider_kind, ids) in grouped {
-            let provider = self
-                .providers
-                .require(&provider_kind)
-                .map_err(|error| map_provider_error(error, "provider account export"))?;
+        // 混选时先验证同一发布代次的全部能力，拒绝路径不读取任何一组明文凭据。
+        let export_groups = grouped
+            .into_iter()
+            .map(|(provider_kind, ids)| {
+                let provider = providers
+                    .require(&provider_kind)
+                    .map_err(|error| map_provider_error(error, "provider account export"))?;
+                if !provider.credential_capabilities().export {
+                    return Err(AdminError::invalid("所选账号包含不支持导出的平台"));
+                }
+                Ok((provider_kind, provider, ids))
+            })
+            .collect::<Result<Vec<_>, AdminError>>()?;
+        let mut documents = Vec::with_capacity(export_groups.len());
+        for (provider_kind, provider, ids) in export_groups {
             let credentials = self
                 .accounts
                 .load_credentials_for_export(&provider_kind, &ids)
@@ -646,7 +691,7 @@ impl AccountsService for DefaultAccountsService {
         let mut providers = BTreeMap::<
             ProviderKind,
             (
-                Arc<dyn crate::ports::provider::ProviderAdmin>,
+                crate::ports::provider_extensions::ProviderAdminHandle,
                 Vec<ProviderAccountId>,
             ),
         >::new();
@@ -710,7 +755,15 @@ impl AccountsService for DefaultAccountsService {
             .map_err(|error| map_provider_error(error, "forecast quota snapshot"))?;
         let now = Utc::now();
         let mut samples = Vec::new();
-        for (window, _) in quota.usage_windows() {
+        let mut selected_keys = BTreeSet::new();
+        for period in [AccountUsagePeriod::Weekly, AccountUsagePeriod::Monthly] {
+            let Some((window, _)) = quota_forecast_source_window(&quota, period) else {
+                continue;
+            };
+            // 缺少一个周期时两个结果会复用同一窗口，只查询一次历史快照。
+            if !selected_keys.insert(window.key.as_str()) {
+                continue;
+            }
             let (Some(mut query), Some(observed), Some(percent)) = (
                 quota_usage_window(account_id.as_str(), window),
                 quota.observed_at,
@@ -897,6 +950,7 @@ impl AccountsService for DefaultAccountsService {
         let model = upstream_model.as_str().to_owned();
         let operation = provider
             .connection_test_operation(&upstream_model, CONNECTION_TEST_INPUT)
+            .await
             .map_err(|error| map_provider_error(error, "provider connection test"))?;
         let initial = vec![
             AccountConnectionTestEvent::Started {
@@ -912,12 +966,15 @@ impl AccountsService for DefaultAccountsService {
         let probe = Arc::clone(&self.probe);
         let terminal = futures::stream::once(async move {
             let result = probe
-                .probe(AccountProbeRequest {
-                    account_id,
-                    provider_kind: account.provider_kind,
-                    upstream_model,
-                    operation,
-                })
+                .probe(
+                    AccountProbeRequest {
+                        account_id,
+                        provider_kind: account.provider_kind,
+                        upstream_model,
+                        operation,
+                    },
+                    provider.snapshot(),
+                )
                 .await;
             match result {
                 Ok(result) => result
diff --git a/backend/crates/gateway-admin/src/use_case/client_keys.rs b/backend/crates/gateway-admin/src/use_case/client_keys.rs
index a8d03e5c0..342838ffb 100644
--- a/backend/crates/gateway-admin/src/use_case/client_keys.rs
+++ b/backend/crates/gateway-admin/src/use_case/client_keys.rs
@@ -113,18 +113,11 @@ impl ClientKeyService for DefaultClientKeyService {
         context: &MutationContext,
         command: CreateClientKey,
     ) -> Result<CreatedClientKey, AdminError> {
-        for (provider, profile) in [
-            ("openai", &command.openai_client_profile_override),
-            ("xai", &command.xai_client_profile_override),
-        ] {
-            if let Some(profile) = profile {
-                let kind = gateway_core::routing::ProviderKind::new(provider)
-                    .map_err(|_| AdminError::invalid("Provider 不合法"))?;
-                self.providers
-                    .require(&kind)
-                    .and_then(|provider| provider.preview_client_profile(profile))
-                    .map_err(|error| super::map_provider_error(error, "client profile"))?;
-            }
+        for (provider, profile) in &command.request_profile_overrides {
+            self.providers
+                .require(provider)
+                .and_then(|provider| provider.preview_client_profile(profile))
+                .map_err(|error| super::map_provider_error(error, "client profile"))?;
         }
         let id = ClientApiKeyId::new(format!("key_{}", Uuid::now_v7().simple()))
             .map_err(|_| AdminError::internal("创建 Client API Key ID 失败"))?;
@@ -139,8 +132,7 @@ impl ClientKeyService for DefaultClientKeyService {
             .store
             .create_client_key(
                 NewClientKey {
-                    openai_client_profile_override: command.openai_client_profile_override,
-                    xai_client_profile_override: command.xai_client_profile_override,
+                    request_profile_overrides: command.request_profile_overrides,
                     id,
                     name: command.name,
                     label: command.label,
@@ -165,15 +157,10 @@ impl ClientKeyService for DefaultClientKeyService {
         context: &MutationContext,
         command: UpdateClientKey,
     ) -> Result<ClientKeyMutation, AdminError> {
-        for (provider, profile) in [
-            ("openai", &command.openai_client_profile_override),
-            ("xai", &command.xai_client_profile_override),
-        ] {
-            if let Some(Some(profile)) = profile {
-                let kind = gateway_core::routing::ProviderKind::new(provider)
-                    .map_err(|_| AdminError::invalid("Provider 不合法"))?;
+        for (provider, profile) in &command.request_profile_override_updates {
+            if let Some(profile) = profile {
                 self.providers
-                    .require(&kind)
+                    .require(provider)
                     .and_then(|provider| provider.preview_client_profile(profile))
                     .map_err(|error| super::map_provider_error(error, "client profile"))?;
             }
diff --git a/backend/crates/gateway-admin/src/use_case/credentials/flow.rs b/backend/crates/gateway-admin/src/use_case/credentials/flow.rs
new file mode 100644
index 000000000..ca6101660
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/credentials/flow.rs
@@ -0,0 +1,331 @@
+//! 已冻结 Provider 的凭据工作流；Admin 保持事务、审计与发布的唯一所有权。
+
+use std::sync::Arc;
+
+use gateway_core::runtime::SnapshotControl;
+
+use crate::{
+    model::{
+        AdminError,
+        provider_credentials::{
+            AuthorizationCommitResult, AuthorizationPollResult, AuthorizationReceiptKey,
+            AuthorizationStarted, CompleteAuthorization, CredentialBatchMutationResult,
+            CredentialDeletion, CredentialDeletionResult, CredentialImportCommit,
+            CredentialImportResult, CredentialMutationResult, ImportCredentials, PollAuthorization,
+            PrepareAuthorization, PrepareCredentialImport, PrepareCredentialRotation,
+            PreparedAuthorizationCredential, PreparedAuthorizationPoll, RotateCredential,
+            StartAuthorization,
+        },
+    },
+    ports::{provider_extensions::ProviderAdminHandle, store::AccountStore},
+};
+
+use super::super::{
+    commit_authorization, commit_credential_rotation, delete_credentials, map_provider_error,
+    map_store_error, pending_authorization, publish_committed,
+    publish_credentials_and_observe_quota, required_credential, validate_authorization_commit,
+    validate_prepared_import, validate_prepared_rotation,
+};
+
+pub struct ProviderCredentials {
+    provider: ProviderAdminHandle,
+    accounts: Arc<dyn AccountStore>,
+    proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl ProviderCredentials {
+    #[must_use]
+    pub(crate) fn new(
+        provider: ProviderAdminHandle,
+        accounts: Arc<dyn AccountStore>,
+        proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        Self {
+            provider,
+            accounts,
+            proxies,
+            snapshot,
+        }
+    }
+    pub async fn import_document(
+        &self,
+        command: ImportCredentials,
+    ) -> Result<CredentialImportResult, AdminError> {
+        let context = command.context;
+        let proxy_reservation = super::super::import_proxy_binding(
+            self.proxies.as_ref(),
+            command.outbound_proxy_id.as_deref(),
+        )
+        .await?;
+        let outbound_proxy = proxy_reservation
+            .as_ref()
+            .map(|reservation| reservation.binding.clone());
+        let prepared = self
+            .provider
+            .prepare_import(PrepareCredentialImport {
+                default_outbound_proxy: outbound_proxy
+                    .as_ref()
+                    .map(|binding| binding.proxy.clone()),
+                document: command.document,
+            })
+            .await
+            .map_err(|error| map_provider_error(error, "provider credential import"))?;
+        validate_prepared_import(
+            self.provider.provider_kind(),
+            &prepared,
+            "provider credential import",
+        )?;
+        let result = self
+            .accounts
+            .commit_credential_import(
+                CredentialImportCommit {
+                    outbound_proxy,
+                    prepared,
+                    settings: command.settings,
+                },
+                &context,
+            )
+            .await
+            .map_err(|error| map_store_error(error, "provider credential import"))?;
+        drop(proxy_reservation);
+        publish_credentials_and_observe_quota(
+            &self.provider,
+            self.snapshot.as_ref(),
+            result.config_revision,
+            &result.credential_ids,
+            &context.request_id,
+        )
+        .await?;
+        Ok(result)
+    }
+
+    pub async fn start_authorization(
+        &self,
+        command: StartAuthorization,
+    ) -> Result<AuthorizationStarted, AdminError> {
+        let pending = pending_authorization(
+            self.accounts.as_ref(),
+            self.proxies.as_ref(),
+            self.provider.provider_kind(),
+            &command,
+            "provider credential",
+        )
+        .await?;
+        self.provider
+            .start_authorization(PrepareAuthorization {
+                pending,
+                input: command.input,
+            })
+            .await
+            .map_err(|error| map_provider_error(error, "provider authorization"))
+    }
+
+    pub async fn rotate(
+        &self,
+        command: RotateCredential,
+    ) -> Result<CredentialMutationResult, AdminError> {
+        let context = command.mutation.context;
+        let account_id = command.mutation.account_id;
+        if command
+            .settings
+            .as_ref()
+            .is_some_and(|settings| settings.account_id != account_id.as_str())
+        {
+            return Err(AdminError::invalid("凭据和账号设置的目标不一致"));
+        }
+        let disable_account = command
+            .settings
+            .as_ref()
+            .is_some_and(|settings| !settings.enabled);
+        let details = required_credential(
+            self.accounts.as_ref(),
+            self.provider.provider_kind(),
+            &account_id,
+            "provider credential rotation",
+        )
+        .await?;
+        let account = details.credential;
+        let prepared = self
+            .provider
+            .prepare_rotation(PrepareCredentialRotation {
+                account: account.clone(),
+                provider_material: command.provider_material,
+            })
+            .await
+            .map_err(|error| map_provider_error(error, "provider credential rotation"))?;
+        validate_prepared_rotation(&account, &prepared, "provider credential rotation")?;
+        let result = commit_credential_rotation(
+            self.accounts.as_ref(),
+            prepared,
+            command.settings,
+            &context,
+            "provider credential rotation",
+        )
+        .await?;
+        if disable_account {
+            self.provider.account_unavailable(&account_id).await;
+        }
+        self.provider
+            .account_facts_changed(std::slice::from_ref(&result.account_id))
+            .await;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+
+    pub async fn delete(
+        &self,
+        command: CredentialDeletion,
+    ) -> Result<CredentialDeletionResult, AdminError> {
+        let result = delete_credentials(
+            self.accounts.as_ref(),
+            self.provider.as_ref(),
+            command,
+            "provider credential",
+        )
+        .await?;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+}
+
+impl super::CredentialsService {
+    pub async fn complete_authorization(
+        &self,
+        kind: &gateway_core::routing::ProviderKind,
+        mut command: CompleteAuthorization,
+    ) -> Result<CredentialMutationResult, AdminError> {
+        let context = command.context.clone();
+        let key = AuthorizationReceiptKey::new(kind.clone(), &command.flow_id, &context)?;
+        if let Some(result) = self
+            .accounts
+            .authorization_receipt(&key)
+            .await
+            .map_err(|error| map_store_error(error, "authorization receipt"))?
+        {
+            publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+            return single_authorization_result(result);
+        }
+        let scope = self.for_provider(kind)?;
+        let provider = &scope.provider;
+        let settings = command.settings.take();
+        let prepared = provider
+            .complete_authorization(command)
+            .await
+            .map_err(|error| map_provider_error(error, "provider authorization"))?;
+        let prepared =
+            validate_authorization_commit(kind, &context, prepared, "provider authorization")
+                .await?;
+        // 回调完成入口保留单账号合同；多账号授权通过显式轮询结果交付，不能提交后再截断。
+        if matches!(&prepared.credential, PreparedAuthorizationCredential::Create(accounts) if accounts.len() != 1)
+        {
+            prepared.abort().await?;
+            return Err(AdminError::invalid("多账号授权需要使用轮询入口"));
+        }
+        let result = commit_authorization(
+            self.accounts.as_ref(),
+            prepared,
+            key,
+            settings,
+            &context,
+            "provider authorization",
+        )
+        .await?;
+        let result = self
+            .publish_authorization(provider, result, &context.request_id)
+            .await?;
+        single_authorization_result(result)
+    }
+
+    pub async fn poll_authorization(
+        &self,
+        kind: &gateway_core::routing::ProviderKind,
+        mut command: PollAuthorization,
+    ) -> Result<AuthorizationPollResult, AdminError> {
+        let context = command.context.clone();
+        let key = AuthorizationReceiptKey::new(kind.clone(), &command.flow_id, &context)?;
+        if let Some(result) = self
+            .accounts
+            .authorization_receipt(&key)
+            .await
+            .map_err(|error| map_store_error(error, "authorization receipt"))?
+        {
+            publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+            return Ok(AuthorizationPollResult::Complete(result));
+        }
+        let scope = self.for_provider(kind)?;
+        let provider = &scope.provider;
+        let settings = command.settings.take();
+        let prepared = provider
+            .poll_authorization(command)
+            .await
+            .map_err(|error| map_provider_error(error, "provider authorization poll"))?;
+        let prepared = match prepared {
+            PreparedAuthorizationPoll::Pending { retry_after } => {
+                if retry_after.is_zero() || retry_after > std::time::Duration::from_secs(300) {
+                    return Err(AdminError::internal("Provider 授权轮询间隔无效"));
+                }
+                return Ok(AuthorizationPollResult::Pending { retry_after });
+            }
+            PreparedAuthorizationPoll::Complete(prepared) => *prepared,
+        };
+        let prepared =
+            validate_authorization_commit(kind, &context, prepared, "provider authorization poll")
+                .await?;
+        let result = commit_authorization(
+            self.accounts.as_ref(),
+            prepared,
+            key,
+            settings,
+            &context,
+            "provider authorization poll",
+        )
+        .await?;
+        let result = self
+            .publish_authorization(provider, result, &context.request_id)
+            .await?;
+        Ok(AuthorizationPollResult::Complete(result))
+    }
+
+    async fn publish_authorization(
+        &self,
+        provider: &ProviderAdminHandle,
+        outcome: AuthorizationCommitResult,
+        request_id: &str,
+    ) -> Result<CredentialBatchMutationResult, AdminError> {
+        let result = outcome.result;
+        if outcome.newly_committed {
+            let ids = result
+                .accounts
+                .iter()
+                .map(|account| account.account_id.clone())
+                .collect::<Vec<_>>();
+            publish_credentials_and_observe_quota(
+                provider,
+                self.snapshot.as_ref(),
+                result.config_revision,
+                &ids,
+                request_id,
+            )
+            .await?;
+        } else {
+            publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        }
+        Ok(result)
+    }
+}
+
+fn single_authorization_result(
+    result: CredentialBatchMutationResult,
+) -> Result<CredentialMutationResult, AdminError> {
+    let [account] = result
+        .accounts
+        .try_into()
+        .map_err(|_| AdminError::invalid("多账号授权需要使用轮询入口"))?;
+    Ok(CredentialMutationResult {
+        config_revision: result.config_revision,
+        account_id: account.account_id,
+        credential_revision: account.credential_revision,
+    })
+}
diff --git a/backend/crates/gateway-admin/src/use_case/credentials/mod.rs b/backend/crates/gateway-admin/src/use_case/credentials/mod.rs
new file mode 100644
index 000000000..b972452d2
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/credentials/mod.rs
@@ -0,0 +1,59 @@
+mod flow;
+
+use std::sync::Arc;
+
+use gateway_core::{routing::ProviderKind, runtime::SnapshotControl};
+
+use crate::{
+    model::AdminError,
+    ports::{provider::ProviderAdminRegistry, proxy::ProxyStore, store::AccountStore},
+};
+
+pub use flow::ProviderCredentials;
+
+/// 所有 Provider 共用凭据用例；每次操作从已发布目录冻结自己的管理实现。
+pub struct CredentialsService {
+    providers: ProviderAdminRegistry,
+    accounts: Arc<dyn AccountStore>,
+    proxies: Arc<dyn ProxyStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl CredentialsService {
+    pub fn providers(
+        &self,
+    ) -> Result<Vec<crate::model::provider_capabilities::ProviderCredentialDescriptor>, AdminError>
+    {
+        self.providers
+            .credential_descriptors()
+            .map_err(|error| super::map_provider_error(error, "provider capabilities"))
+    }
+
+    #[must_use]
+    pub fn new(
+        providers: ProviderAdminRegistry,
+        accounts: Arc<dyn AccountStore>,
+        proxies: Arc<dyn ProxyStore>,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        Self {
+            providers,
+            accounts,
+            proxies,
+            snapshot,
+        }
+    }
+
+    pub fn for_provider(&self, kind: &ProviderKind) -> Result<ProviderCredentials, AdminError> {
+        let provider = self
+            .providers
+            .require(kind)
+            .map_err(|error| super::map_provider_error(error, "provider credentials"))?;
+        Ok(ProviderCredentials::new(
+            provider,
+            self.accounts.clone(),
+            self.proxies.clone(),
+            self.snapshot.clone(),
+        ))
+    }
+}
diff --git a/backend/crates/gateway-admin/src/use_case/import_tasks.rs b/backend/crates/gateway-admin/src/use_case/import_tasks.rs
index 68703c593..e23ae10cb 100644
--- a/backend/crates/gateway-admin/src/use_case/import_tasks.rs
+++ b/backend/crates/gateway-admin/src/use_case/import_tasks.rs
@@ -16,7 +16,7 @@ use gateway_core::{
 use tokio::{sync::Notify, time::Instant};
 use uuid::Uuid;
 
-use super::{openai::OpenAiService, xai::XaiService};
+use super::credentials::CredentialsService;
 use crate::model::{
     AdminError, AdminErrorKind, MutationActor, MutationContext,
     import_tasks::{
@@ -129,17 +129,15 @@ struct Registry {
 pub(crate) struct DefaultImportTasksService {
     registry: Mutex<Registry>,
     notify: Notify,
-    openai: Arc<dyn OpenAiService>,
-    xai: Arc<dyn XaiService>,
+    credentials: Arc<CredentialsService>,
 }
 
 impl DefaultImportTasksService {
-    pub(crate) fn new(openai: Arc<dyn OpenAiService>, xai: Arc<dyn XaiService>) -> Arc<Self> {
+    pub(crate) fn new(credentials: Arc<CredentialsService>) -> Arc<Self> {
         Arc::new(Self {
             registry: Mutex::default(),
             notify: Notify::new(),
-            openai,
-            xai,
+            credentials,
         })
     }
 
@@ -177,11 +175,10 @@ impl DefaultImportTasksService {
 
     async fn execute(&self, id: Uuid, index: usize, input: ImportTaskInput) {
         let operation = async {
-            match input.provider.as_str() {
-                "openai" => self.openai.import_document(input.command).await,
-                "xai" => self.xai.import_document(input.command).await,
-                _ => Err(AdminError::invalid("不支持的导入平台")),
-            }
+            self.credentials
+                .for_provider(&input.provider)?
+                .import_document(input.command)
+                .await
         };
         let result = AssertUnwindSafe(operation).catch_unwind().await;
         let mut registry = self.registry();
@@ -222,7 +219,7 @@ impl ImportTasksService for DefaultImportTasksService {
         if command.items.is_empty()
             || command.items.len() > MAX_IMPORT_TASK_ITEMS
             || command.items.iter().any(|item| {
-                !matches!(item.provider.as_str(), "openai" | "xai")
+                self.credentials.for_provider(&item.provider).is_err()
                     || item.command.context.actor != command.context.actor
             })
         {
diff --git a/backend/crates/gateway-admin/src/use_case/key_usage.rs b/backend/crates/gateway-admin/src/use_case/key_usage.rs
index 0aa53668d..c7253683b 100644
--- a/backend/crates/gateway-admin/src/use_case/key_usage.rs
+++ b/backend/crates/gateway-admin/src/use_case/key_usage.rs
@@ -37,6 +37,12 @@ pub trait KeyUsageService: Send + Sync {
     /// 验证 Key 并只读查询当前额度，不记录 Key 使用或执行推理准入。
     async fn budget(&self, plaintext: &str) -> Result<Option<ClientBudgetStatus>, AdminError>;
 
+    /// 使用 Core 已认证的宿主身份查询额度，不接收插件自报的 Key ID。
+    async fn budget_for_client(
+        &self,
+        id: &ClientApiKeyId,
+    ) -> Result<Option<ClientBudgetStatus>, AdminError>;
+
     async fn version(&self, session_id: Option<&str>) -> Result<Option<SystemVersion>, AdminError>;
 
     async fn config(&self, session_id: Option<&str>)
@@ -111,15 +117,25 @@ impl KeyUsageService for DefaultKeyUsageService {
         let id = match self.verifier.verify_client_key(plaintext) {
             Ok(id) => id,
             Err(ClientAuthenticationError::InvalidKey) => return Ok(None),
-            Err(ClientAuthenticationError::SnapshotUnavailable) => {
+            Err(
+                ClientAuthenticationError::SnapshotUnavailable
+                | ClientAuthenticationError::ProviderUnavailable,
+            ) => {
                 return Err(AdminError::new(
                     AdminErrorKind::Unavailable,
                     "密钥验证暂时不可用",
                 ));
             }
         };
+        self.budget_for_client(&id).await
+    }
+
+    async fn budget_for_client(
+        &self,
+        id: &ClientApiKeyId,
+    ) -> Result<Option<ClientBudgetStatus>, AdminError> {
         self.keys
-            .get_client_key(&id)
+            .get_client_key(id)
             .await
             .map(|key| key.filter(|key| key.enabled).map(|key| key.budget))
             .map_err(|error| map_store_error(error, "key usage budget"))
diff --git a/backend/crates/gateway-admin/src/use_case/mod.rs b/backend/crates/gateway-admin/src/use_case/mod.rs
index 3733e70ee..fee5c163f 100644
--- a/backend/crates/gateway-admin/src/use_case/mod.rs
+++ b/backend/crates/gateway-admin/src/use_case/mod.rs
@@ -6,16 +6,17 @@ pub mod auth;
 pub mod backup;
 pub mod client_distribution;
 pub mod client_keys;
+pub mod credentials;
 pub mod import_tasks;
 pub mod key_usage;
 pub mod observability;
-pub mod openai;
+pub mod plugin_accounts;
+pub mod plugin_client_keys;
+pub(crate) mod plugin_update;
+pub mod plugins;
 pub mod proxies;
 pub mod settings;
 pub mod system;
-pub mod xai;
-
-use std::sync::Arc;
 
 use crate::{
     model::{
@@ -101,8 +102,18 @@ async fn publish_committed(
     Ok(())
 }
 
+async fn publish_committed_deferred(
+    snapshot: &dyn SnapshotControl,
+    revision: crate::model::Revision,
+) -> Result<(), AdminError> {
+    let revision = ConfigRevision::new(revision.get())
+        .map_err(|_| AdminError::internal("已提交的配置版本不合法"))?;
+    snapshot.publish_committed_deferred(revision).await;
+    Ok(())
+}
+
 async fn publish_credentials_and_observe_quota(
-    provider: &Arc<dyn ProviderAdmin>,
+    provider: &crate::ports::provider_extensions::ProviderAdminHandle,
     snapshot: &dyn SnapshotControl,
     revision: crate::model::Revision,
     account_ids: &[ProviderAccountId],
@@ -112,7 +123,7 @@ async fn publish_credentials_and_observe_quota(
     publish_committed(snapshot, revision).await?;
 
     // 凭据已经提交；额度只是可重建的观察，不能拖住管理请求或回滚提交结果。
-    let provider = Arc::clone(provider);
+    let provider = provider.clone();
     let account_ids = account_ids.to_vec();
     let request_id = request_id.to_owned();
     tokio::spawn(async move {
@@ -151,6 +162,18 @@ async fn required_credential(
         .ok_or_else(|| AdminError::not_found("Provider 凭据不存在"))
 }
 
+async fn required_plugin_credential(
+    accounts: &dyn AccountStore,
+    account_id: &ProviderAccountId,
+    resource: &'static str,
+) -> Result<CredentialDetails, AdminError> {
+    accounts
+        .credential_details_by_id(account_id)
+        .await
+        .map_err(|error| map_store_error(error, resource))?
+        .ok_or_else(|| AdminError::not_found("Provider 凭据不存在"))
+}
+
 async fn import_proxy_binding(
     proxies: &dyn crate::ports::proxy::ProxyStore,
     id: Option<&str>,
@@ -233,7 +256,13 @@ fn validate_prepared_rotation(
     prepared: &PreparedCredentialRotation,
     _resource: &'static str,
 ) -> Result<(), AdminError> {
-    let facts = prepared.facts();
+    validate_prepared_rotation_facts(account, prepared.facts())
+}
+
+fn validate_prepared_rotation_facts(
+    account: &crate::model::accounts::AccountRecord,
+    facts: &crate::model::provider_credentials::PreparedCredentialRotationFacts,
+) -> Result<(), AdminError> {
     if facts.account_id.as_str() != account.id.as_str()
         || facts.provider_kind != account.provider_kind
     {
@@ -265,8 +294,16 @@ async fn validate_authorization_commit(
     let matches_target = match (prepared.pending.target(), &prepared.credential) {
         (
             AuthorizationMutationTarget::Create { .. },
-            PreparedAuthorizationCredential::Create(credential),
-        ) => credential.provider_kind == *provider_kind,
+            PreparedAuthorizationCredential::Create(credentials),
+        ) => {
+            let mut identities = std::collections::BTreeSet::new();
+            !credentials.is_empty()
+                && credentials.len() <= 200
+                && credentials.iter().all(|credential| {
+                    credential.provider_kind == *provider_kind
+                        && identities.insert(&credential.account_id)
+                })
+        }
         (
             AuthorizationMutationTarget::Reauthorize { account_id },
             PreparedAuthorizationCredential::Reauthorize(credential),
@@ -294,10 +331,11 @@ async fn validate_authorization_commit(
 async fn commit_authorization(
     accounts: &dyn AccountStore,
     prepared: PreparedAuthorizationCommit,
+    key: crate::model::provider_credentials::AuthorizationReceiptKey,
     settings: Option<crate::model::accounts::AccountImportSettings>,
     context: &MutationContext,
     resource: &'static str,
-) -> Result<CredentialMutationResult, AdminError> {
+) -> Result<crate::model::provider_credentials::AuthorizationCommitResult, AdminError> {
     if settings.is_some()
         && matches!(
             &prepared.credential,
@@ -311,14 +349,19 @@ async fn commit_authorization(
         command,
         credential_guard,
         authorization_guard,
-    } = prepared.into_commit(settings);
+    } = prepared.into_commit(settings, key);
     match accounts.commit_authorization(command, context).await {
         Ok(result) => {
-            if let Some(guard) = credential_guard {
+            if let Some(guard) = credential_guard
+                && result.newly_committed
+            {
                 guard.finish();
             }
-            if let Some(guard) = authorization_guard {
-                guard.commit().await?;
+            if let Some(guard) = authorization_guard
+                && let Err(error) = guard.commit().await
+            {
+                // 账号与回执已经原子提交，Redis 清理失败不能把确定的成功改写为失败。
+                tracing::warn!(resource, settlement_error = %error, "authorization committed but pending cleanup failed");
             }
             Ok(result)
         }
diff --git a/backend/crates/gateway-admin/src/use_case/observability.rs b/backend/crates/gateway-admin/src/use_case/observability.rs
index 6535331dc..4a98ea833 100644
--- a/backend/crates/gateway-admin/src/use_case/observability.rs
+++ b/backend/crates/gateway-admin/src/use_case/observability.rs
@@ -105,6 +105,7 @@ pub trait ObservabilityService: Send + Sync {
     async fn dashboard_trend(&self, range: TimeRange, kind: TrendKind)
     -> Result<Trend, AdminError>;
     async fn usage_records(&self, query: UsageQuery) -> Result<UsagePage, AdminError>;
+    async fn usage_provider_kinds(&self, range: TimeRange) -> Result<Vec<String>, AdminError>;
     async fn usage_record_detail(&self, request_id: &str) -> Result<UsageDetail, AdminError>;
     async fn usage_summary(
         &self,
@@ -192,20 +193,10 @@ impl DefaultObservabilityService {
             average(first_token_latency_sum_ms, first_token_latency_count);
         let trend = trend(TrendKind::Usage, observation.trend.clone())?;
         let health_timeline = health_timeline_at(&observation.trend, Utc::now());
-        let mut configurations = std::collections::BTreeMap::new();
-        if let Some(configuration) = &settings.openai_client_profile {
-            configurations.insert(
-                gateway_core::routing::ProviderKind::new("openai").expect("static provider kind"),
-                configuration.clone(),
-            );
-        }
-        if let Some(configuration) = &settings.xai_client_profile {
-            configurations.insert(
-                gateway_core::routing::ProviderKind::new("xai").expect("static provider kind"),
-                configuration.clone(),
-            );
-        }
-        let wire_profiles = self.providers.dashboard_wire_profiles(&configurations);
+        let wire_profiles = self
+            .providers
+            .dashboard_wire_profiles(&settings.request_profiles)
+            .map_err(|error| super::map_provider_error(error, "provider profiles"))?;
         let max_concurrent_per_account = u64::from(settings.max_concurrent_per_account);
         let (inherited_accounts, overridden_slots) = runtime_slots
             .as_ref()
@@ -283,6 +274,13 @@ impl ObservabilityService for DefaultObservabilityService {
         Ok(page)
     }
 
+    async fn usage_provider_kinds(&self, range: TimeRange) -> Result<Vec<String>, AdminError> {
+        self.store
+            .usage_provider_kinds(range)
+            .await
+            .map_err(|error| map_store_error(error, "usage providers"))
+    }
+
     async fn usage_record_detail(&self, request_id: &str) -> Result<UsageDetail, AdminError> {
         if request_id.trim().is_empty() {
             return Err(AdminError::invalid("用量记录 ID 不能为空"));
diff --git a/backend/crates/gateway-admin/src/use_case/openai.rs b/backend/crates/gateway-admin/src/use_case/openai.rs
deleted file mode 100644
index bf2fd36c8..000000000
--- a/backend/crates/gateway-admin/src/use_case/openai.rs
+++ /dev/null
@@ -1,252 +0,0 @@
-//! OpenAI 管理资源的中立 ProviderAdmin 委托。
-
-use std::sync::Arc;
-
-use async_trait::async_trait;
-use gateway_core::runtime::SnapshotControl;
-
-use crate::{
-    model::{
-        AdminError,
-        provider_credentials::{
-            AuthorizationStarted, CompleteAuthorization, CredentialDeletion,
-            CredentialDeletionResult, CredentialImportCommit, CredentialImportResult,
-            CredentialMutationResult, ImportCredentials, PrepareCredentialImport,
-            PrepareCredentialRotation, RotateCredential, StartAuthorization,
-        },
-    },
-    ports::{provider::ProviderAdmin, store::AccountStore},
-};
-
-use super::{
-    commit_authorization, commit_credential_rotation, delete_credentials, map_provider_error,
-    map_store_error, pending_authorization, publish_committed,
-    publish_credentials_and_observe_quota, required_credential, validate_authorization_commit,
-    validate_prepared_import, validate_prepared_rotation,
-};
-
-/// OpenAI 固定管理路由消费的服务。
-#[async_trait]
-pub trait OpenAiService: Send + Sync {
-    async fn import_document(
-        &self,
-        command: ImportCredentials,
-    ) -> Result<CredentialImportResult, AdminError>;
-    async fn start_authorization(
-        &self,
-        command: StartAuthorization,
-    ) -> Result<AuthorizationStarted, AdminError>;
-    async fn complete_authorization(
-        &self,
-        command: CompleteAuthorization,
-    ) -> Result<CredentialMutationResult, AdminError>;
-    async fn rotate(
-        &self,
-        command: RotateCredential,
-    ) -> Result<CredentialMutationResult, AdminError>;
-    async fn delete(
-        &self,
-        command: CredentialDeletion,
-    ) -> Result<CredentialDeletionResult, AdminError>;
-}
-
-pub(crate) struct DefaultOpenAiService {
-    provider: Arc<dyn ProviderAdmin>,
-    accounts: Arc<dyn AccountStore>,
-    proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
-    snapshot: Arc<dyn SnapshotControl>,
-}
-
-impl DefaultOpenAiService {
-    #[must_use]
-    pub(crate) fn new(
-        provider: Arc<dyn ProviderAdmin>,
-        accounts: Arc<dyn AccountStore>,
-        proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
-        snapshot: Arc<dyn SnapshotControl>,
-    ) -> Self {
-        Self {
-            provider,
-            accounts,
-            proxies,
-            snapshot,
-        }
-    }
-}
-
-#[async_trait]
-impl OpenAiService for DefaultOpenAiService {
-    async fn import_document(
-        &self,
-        command: ImportCredentials,
-    ) -> Result<CredentialImportResult, AdminError> {
-        let context = command.context;
-        let proxy_reservation = super::import_proxy_binding(
-            self.proxies.as_ref(),
-            command.outbound_proxy_id.as_deref(),
-        )
-        .await?;
-        let outbound_proxy = proxy_reservation
-            .as_ref()
-            .map(|reservation| reservation.binding.clone());
-        let prepared = self
-            .provider
-            .prepare_import(PrepareCredentialImport {
-                default_outbound_proxy: outbound_proxy
-                    .as_ref()
-                    .map(|binding| binding.proxy.clone()),
-                document: command.document,
-            })
-            .await
-            .map_err(|error| map_provider_error(error, "OpenAI credential import"))?;
-        validate_prepared_import(
-            self.provider.provider_kind(),
-            &prepared,
-            "OpenAI credential import",
-        )?;
-        let result = self
-            .accounts
-            .commit_credential_import(
-                CredentialImportCommit {
-                    outbound_proxy,
-                    prepared,
-                    settings: command.settings,
-                },
-                &context,
-            )
-            .await
-            .map_err(|error| map_store_error(error, "OpenAI credential import"))?;
-        drop(proxy_reservation);
-        publish_credentials_and_observe_quota(
-            &self.provider,
-            self.snapshot.as_ref(),
-            result.config_revision,
-            &result.credential_ids,
-            &context.request_id,
-        )
-        .await?;
-        Ok(result)
-    }
-
-    async fn start_authorization(
-        &self,
-        command: StartAuthorization,
-    ) -> Result<AuthorizationStarted, AdminError> {
-        let pending = pending_authorization(
-            self.accounts.as_ref(),
-            self.proxies.as_ref(),
-            self.provider.provider_kind(),
-            &command,
-            "OpenAI credential",
-        )
-        .await?;
-        self.provider
-            .start_authorization(pending)
-            .await
-            .map_err(|error| map_provider_error(error, "OpenAI authorization"))
-    }
-
-    async fn complete_authorization(
-        &self,
-        mut command: CompleteAuthorization,
-    ) -> Result<CredentialMutationResult, AdminError> {
-        let context = command.context.clone();
-        let settings = command.settings.take();
-        let prepared = self
-            .provider
-            .complete_authorization(command)
-            .await
-            .map_err(|error| map_provider_error(error, "OpenAI authorization"))?;
-        let prepared = validate_authorization_commit(
-            self.provider.provider_kind(),
-            &context,
-            prepared,
-            "OpenAI authorization",
-        )
-        .await?;
-        let result = commit_authorization(
-            self.accounts.as_ref(),
-            prepared,
-            settings,
-            &context,
-            "OpenAI authorization",
-        )
-        .await?;
-        publish_credentials_and_observe_quota(
-            &self.provider,
-            self.snapshot.as_ref(),
-            result.config_revision,
-            std::slice::from_ref(&result.account_id),
-            &context.request_id,
-        )
-        .await?;
-        Ok(result)
-    }
-
-    async fn rotate(
-        &self,
-        command: RotateCredential,
-    ) -> Result<CredentialMutationResult, AdminError> {
-        let context = command.mutation.context;
-        let account_id = command.mutation.account_id;
-        if command
-            .settings
-            .as_ref()
-            .is_some_and(|settings| settings.account_id != account_id.as_str())
-        {
-            return Err(AdminError::invalid("凭据和账号设置的目标不一致"));
-        }
-        let disable_account = command
-            .settings
-            .as_ref()
-            .is_some_and(|settings| !settings.enabled);
-        let details = required_credential(
-            self.accounts.as_ref(),
-            self.provider.provider_kind(),
-            &account_id,
-            "OpenAI credential rotation",
-        )
-        .await?;
-        let account = details.credential;
-        let prepared = self
-            .provider
-            .prepare_rotation(PrepareCredentialRotation {
-                account: account.clone(),
-                provider_material: command.provider_material,
-            })
-            .await
-            .map_err(|error| map_provider_error(error, "OpenAI credential rotation"))?;
-        validate_prepared_rotation(&account, &prepared, "OpenAI credential rotation")?;
-        let result = commit_credential_rotation(
-            self.accounts.as_ref(),
-            prepared,
-            command.settings,
-            &context,
-            "OpenAI credential rotation",
-        )
-        .await?;
-        if disable_account {
-            self.provider.account_unavailable(&account_id).await;
-        }
-        self.provider
-            .account_facts_changed(std::slice::from_ref(&result.account_id))
-            .await;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        Ok(result)
-    }
-
-    async fn delete(
-        &self,
-        command: CredentialDeletion,
-    ) -> Result<CredentialDeletionResult, AdminError> {
-        let result = delete_credentials(
-            self.accounts.as_ref(),
-            self.provider.as_ref(),
-            command,
-            "OpenAI credential",
-        )
-        .await?;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        Ok(result)
-    }
-}
diff --git a/backend/crates/gateway-admin/src/use_case/plugin_accounts.rs b/backend/crates/gateway-admin/src/use_case/plugin_accounts.rs
new file mode 100644
index 000000000..fcc88057b
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/plugin_accounts.rs
@@ -0,0 +1,217 @@
+//! 插件宿主账号回调；复用凭据事务，不建立第二套账号权威。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use gateway_core::{account::ProviderAccountId, routing::ProviderKind, runtime::SnapshotControl};
+
+use crate::{
+    model::{
+        AdminError, MutationContext,
+        provider_credentials::{
+            CredentialImportCommit, CredentialRotationCommit, PluginAccountCredential,
+            PluginAccountListQuery, PluginAccountPage, PluginAccountSaveReason,
+            PluginAccountSaveResult, PreparedCredentialImport, PreparedPluginAccountSave,
+        },
+    },
+    ports::{
+        plugin_accounts::PluginAccountAccess, provider::ProviderAdminRegistry, store::AccountStore,
+    },
+};
+
+use super::{
+    map_provider_error, map_store_error, publish_committed_deferred,
+    publish_credentials_and_observe_quota, required_credential, required_plugin_credential,
+    validate_prepared_import, validate_prepared_rotation_facts,
+};
+
+pub(crate) struct DefaultPluginAccountAccess {
+    providers: ProviderAdminRegistry,
+    accounts: Arc<dyn AccountStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl DefaultPluginAccountAccess {
+    #[must_use]
+    pub(crate) fn new(
+        providers: ProviderAdminRegistry,
+        accounts: Arc<dyn AccountStore>,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        Self {
+            providers,
+            accounts,
+            snapshot,
+        }
+    }
+
+    fn provider(
+        &self,
+        provider_kind: &ProviderKind,
+    ) -> Result<crate::ports::provider_extensions::ProviderAdminHandle, AdminError> {
+        self.providers
+            .require(provider_kind)
+            .map_err(|error| map_provider_error(error, "plugin account access"))
+    }
+}
+
+#[async_trait]
+impl PluginAccountAccess for DefaultPluginAccountAccess {
+    async fn list(&self, query: PluginAccountListQuery) -> Result<PluginAccountPage, AdminError> {
+        self.accounts
+            .list_plugin_accounts(query)
+            .await
+            .map_err(|error| map_store_error(error, "plugin account list"))
+    }
+
+    async fn get_runtime(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<crate::model::accounts::AccountRecord, AdminError> {
+        Ok(
+            required_plugin_credential(
+                self.accounts.as_ref(),
+                account_id,
+                "plugin account runtime",
+            )
+            .await?
+            .credential,
+        )
+    }
+
+    async fn get_credential(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<PluginAccountCredential, AdminError> {
+        let credential = self
+            .accounts
+            .load_credential_for_plugin(account_id)
+            .await
+            .map_err(|error| map_store_error(error, "plugin credential"))?
+            .ok_or_else(|| AdminError::not_found("Provider 凭据不存在"))?;
+        Ok(PluginAccountCredential {
+            account: credential.account,
+            provider_material: credential.provider_material,
+        })
+    }
+
+    async fn save(
+        &self,
+        command: PreparedPluginAccountSave,
+        context: &MutationContext,
+    ) -> Result<PluginAccountSaveResult, AdminError> {
+        match command {
+            PreparedPluginAccountSave::Create(prepared) => {
+                let provider_kind = prepared.provider_kind.clone();
+                let account_id = prepared.account_id.clone();
+                let provider = self.provider(&provider_kind)?;
+                let prepared = PreparedCredentialImport {
+                    provider_kind: provider_kind.clone(),
+                    credentials: vec![prepared],
+                };
+                validate_prepared_import(&provider_kind, &prepared, "plugin account save")?;
+                let result = self
+                    .accounts
+                    .commit_credential_import(
+                        CredentialImportCommit {
+                            outbound_proxy: None,
+                            settings: None,
+                            prepared,
+                        },
+                        context,
+                    )
+                    .await
+                    .map_err(|error| map_store_error(error, "plugin account save"))?;
+                if result.credential_ids.as_slice() != std::slice::from_ref(&account_id) {
+                    return Err(AdminError::internal("账号保存结果与准备目标不一致"));
+                }
+                let credential_revision = required_credential(
+                    self.accounts.as_ref(),
+                    &provider_kind,
+                    &account_id,
+                    "plugin account save",
+                )
+                .await?
+                .credential
+                .credential_revision;
+                publish_credentials_and_observe_quota(
+                    &provider,
+                    self.snapshot.as_ref(),
+                    result.config_revision,
+                    std::slice::from_ref(&account_id),
+                    &context.request_id,
+                )
+                .await?;
+                Ok(PluginAccountSaveResult {
+                    config_revision: result.config_revision,
+                    account_id,
+                    credential_revision,
+                })
+            }
+            PreparedPluginAccountSave::Replace {
+                facts,
+                authentication_kind,
+                reason,
+            } => {
+                let account = required_credential(
+                    self.accounts.as_ref(),
+                    &facts.provider_kind,
+                    &facts.account_id,
+                    "plugin account save",
+                )
+                .await?
+                .credential;
+                validate_prepared_rotation_facts(&account, &facts)?;
+                if account.authentication_kind != authentication_kind {
+                    return Err(AdminError::conflict("插件准备结果与当前认证类型不一致"));
+                }
+                let provider = if reason == PluginAccountSaveReason::Explicit {
+                    Some(self.provider(&facts.provider_kind)?)
+                } else {
+                    None
+                };
+                let command = CredentialRotationCommit {
+                    prepared: facts,
+                    settings: None,
+                };
+                let result = match reason {
+                    PluginAccountSaveReason::Explicit => {
+                        self.accounts
+                            .commit_credential_rotation(command, context)
+                            .await
+                    }
+                    PluginAccountSaveReason::ModelDiscovery
+                    | PluginAccountSaveReason::Maintenance => {
+                        self.accounts
+                            .commit_credential_refresh(command, context)
+                            .await
+                    }
+                }
+                .map_err(|error| map_store_error(error, "plugin account save"))?;
+                let credential_revision = result
+                    .credential_revision
+                    .ok_or_else(|| AdminError::internal("账号保存未返回凭据版本"))?;
+                if let Some(provider) = provider {
+                    publish_credentials_and_observe_quota(
+                        &provider,
+                        self.snapshot.as_ref(),
+                        result.config_revision,
+                        std::slice::from_ref(&result.account_id),
+                        &context.request_id,
+                    )
+                    .await?;
+                } else {
+                    // 模型发现可能位于快照编译内，后台维护还持有刷新租约；
+                    // 只合并发布，由 Runtime 当前调用失效目录，避免重入准备或刷新锁。
+                    publish_committed_deferred(self.snapshot.as_ref(), result.config_revision)
+                        .await?;
+                }
+                Ok(PluginAccountSaveResult {
+                    config_revision: result.config_revision,
+                    account_id: result.account_id,
+                    credential_revision,
+                })
+            }
+        }
+    }
+}
diff --git a/backend/crates/gateway-admin/src/use_case/plugin_client_keys.rs b/backend/crates/gateway-admin/src/use_case/plugin_client_keys.rs
new file mode 100644
index 000000000..df7a72545
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/plugin_client_keys.rs
@@ -0,0 +1,87 @@
+//! 插件 Client Key 目录；复用管理服务并收窄为非秘密投影。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+
+use crate::{
+    model::{
+        AdminError,
+        client_keys::{
+            ClientKeyCursor, ClientKeyCursorValue, ClientKeyListQuery, ClientKeyPageSize,
+            ClientKeySort, ClientKeySortField, SortDirection,
+        },
+        plugin_client_keys::{
+            PluginClientKey, PluginClientKeyCursor, PluginClientKeyListQuery, PluginClientKeyPage,
+        },
+    },
+    ports::plugin_client_keys::PluginClientKeyAccess,
+    use_case::client_keys::ClientKeyService,
+};
+
+pub(crate) struct DefaultPluginClientKeyAccess {
+    service: Arc<dyn ClientKeyService>,
+}
+
+impl DefaultPluginClientKeyAccess {
+    pub(crate) fn new(service: Arc<dyn ClientKeyService>) -> Self {
+        Self { service }
+    }
+}
+
+#[async_trait]
+impl PluginClientKeyAccess for DefaultPluginClientKeyAccess {
+    async fn list(
+        &self,
+        query: PluginClientKeyListQuery,
+    ) -> Result<PluginClientKeyPage, AdminError> {
+        let sort = ClientKeySort {
+            field: ClientKeySortField::Name,
+            direction: SortDirection::Asc,
+        };
+        let page_size = ClientKeyPageSize::new(query.limit.get())
+            .map_err(|_| AdminError::internal("插件 Client Key 页大小不合法"))?;
+        let page = self
+            .service
+            .list(ClientKeyListQuery {
+                cursor: query.cursor.map(|cursor| ClientKeyCursor {
+                    sort,
+                    value: ClientKeyCursorValue::Name(cursor.name),
+                    id: cursor.id,
+                }),
+                page_size,
+                search: None,
+                sort,
+            })
+            .await?;
+        let next_cursor = page
+            .next_cursor
+            .map(|cursor| match cursor.value {
+                ClientKeyCursorValue::Name(name)
+                    if cursor.sort.field == ClientKeySortField::Name
+                        && cursor.sort.direction == SortDirection::Asc =>
+                {
+                    Ok(PluginClientKeyCursor {
+                        name,
+                        id: cursor.id,
+                    })
+                }
+                _ => Err(AdminError::internal(
+                    "Client Key 服务返回了不匹配的插件分页游标",
+                )),
+            })
+            .transpose()?;
+        Ok(PluginClientKeyPage {
+            items: page
+                .items
+                .into_iter()
+                .map(|item| PluginClientKey {
+                    id: item.id,
+                    name: item.name,
+                    enabled: item.enabled,
+                })
+                .collect(),
+            next_cursor,
+        })
+    }
+}
diff --git a/backend/crates/gateway-admin/src/use_case/plugin_update.rs b/backend/crates/gateway-admin/src/use_case/plugin_update.rs
new file mode 100644
index 000000000..648a7305a
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/plugin_update.rs
@@ -0,0 +1,148 @@
+use std::{collections::BTreeMap, sync::Arc};
+
+use async_trait::async_trait;
+
+use crate::{
+    model::{AdminErrorKind, Revision},
+    ports::{
+        plugins::{PluginPackageInspector, PluginStore},
+        store::AdminStoreErrorKind,
+        system::{
+            SystemOperationError, SystemOperationErrorKind, SystemUpdateCandidate,
+            SystemUpdatePreflight,
+        },
+    },
+};
+
+use super::plugins::official::update_compatibility;
+
+/// 只读取启用实例及其固定包体，检查目标宿主合同；不准备或执行插件。
+pub(crate) struct PluginSystemUpdatePreflight {
+    store: Arc<dyn PluginStore>,
+    inspector: Arc<dyn PluginPackageInspector>,
+}
+
+impl PluginSystemUpdatePreflight {
+    pub(crate) fn new(
+        store: Arc<dyn PluginStore>,
+        inspector: Arc<dyn PluginPackageInspector>,
+    ) -> Self {
+        Self { store, inspector }
+    }
+}
+
+#[async_trait]
+impl SystemUpdatePreflight for PluginSystemUpdatePreflight {
+    async fn validate(
+        &self,
+        candidate: SystemUpdateCandidate,
+    ) -> Result<Revision, SystemOperationError> {
+        let target = semver::Version::parse(candidate.target_version.trim_start_matches('v'))
+            .map_err(|_| invalid("目标网关版本不合法"))?;
+        let compatibility = update_compatibility(
+            candidate.release_manifest.as_ref(),
+            candidate.target_version.trim_start_matches('v'),
+        )
+        .map_err(|_| invalid("目标发行物缺少有效的插件兼容声明"))?;
+        let snapshot = self.store.load_instances().await.map_err(map_store_error)?;
+        let mut inspected = BTreeMap::new();
+        for instance in snapshot
+            .instances
+            .iter()
+            .filter(|instance| instance.enabled)
+        {
+            let requirements = if let Some(requirements) = inspected.get(&instance.artifact_sha256)
+            {
+                requirements
+            } else {
+                let artifact = self
+                    .store
+                    .load_artifact(&instance.artifact_sha256)
+                    .await
+                    .map_err(map_store_error)?;
+                let requirements = self
+                    .inspector
+                    .compatibility(artifact.archive, instance.artifact_sha256.clone())
+                    .await
+                    .map_err(map_inspection_error)?;
+                inspected.insert(instance.artifact_sha256.clone(), requirements);
+                inspected
+                    .get(&instance.artifact_sha256)
+                    .ok_or_else(|| internal("插件兼容性检查结果不可用"))?
+            };
+            let host_versions = semver::VersionReq::parse(&requirements.host_version)
+                .map_err(|_| incompatible(&instance.id))?;
+            if !host_versions.matches(&target)
+                || !compatibility
+                    .manifest_schema_versions
+                    .contains(&requirements.manifest_schema_version)
+                || !compatibility
+                    .protocol_versions
+                    .contains(&requirements.protocol_version)
+                || requirements
+                    .capabilities
+                    .iter()
+                    .any(|(capability, version)| {
+                        !compatibility.supports_capability(capability, *version)
+                    })
+                || requirements
+                    .permissions
+                    .iter()
+                    .any(|permission| !compatibility.supports_permission(permission))
+            {
+                return Err(incompatible(&instance.id));
+            }
+        }
+        Ok(snapshot.config_revision)
+    }
+
+    async fn confirm_revision(&self, expected: Revision) -> Result<(), SystemOperationError> {
+        let current = self
+            .store
+            .load_instances()
+            .await
+            .map_err(map_store_error)?
+            .config_revision;
+        if current != expected {
+            return Err(conflict("插件配置已变化，请重新执行系统更新"));
+        }
+        Ok(())
+    }
+}
+
+fn map_store_error(error: crate::ports::store::AdminStoreError) -> SystemOperationError {
+    match error.kind() {
+        AdminStoreErrorKind::StaleRevision
+        | AdminStoreErrorKind::DuplicateName
+        | AdminStoreErrorKind::Conflict => conflict("插件配置已变化，请重新执行系统更新"),
+        AdminStoreErrorKind::Invalid | AdminStoreErrorKind::NotFound => {
+            conflict("启用插件的制品不完整，无法执行系统更新")
+        }
+        AdminStoreErrorKind::Unavailable => internal("插件配置暂不可读取"),
+    }
+}
+
+fn map_inspection_error(error: crate::model::AdminError) -> SystemOperationError {
+    match error.kind() {
+        AdminErrorKind::Invalid | AdminErrorKind::Conflict | AdminErrorKind::NotFound => {
+            conflict("启用插件的制品无法通过兼容性检查")
+        }
+        _ => internal("插件兼容性检查暂不可用"),
+    }
+}
+
+fn incompatible(instance_id: &str) -> SystemOperationError {
+    conflict(format!("启用插件实例 {instance_id} 与目标网关版本不兼容"))
+}
+
+fn invalid(message: impl Into<String>) -> SystemOperationError {
+    SystemOperationError::new(SystemOperationErrorKind::Invalid, message)
+}
+
+fn conflict(message: impl Into<String>) -> SystemOperationError {
+    SystemOperationError::new(SystemOperationErrorKind::Conflict, message)
+}
+
+fn internal(message: impl Into<String>) -> SystemOperationError {
+    SystemOperationError::new(SystemOperationErrorKind::Internal, message)
+}
diff --git a/backend/crates/gateway-admin/src/use_case/plugins/artifacts.rs b/backend/crates/gateway-admin/src/use_case/plugins/artifacts.rs
new file mode 100644
index 000000000..c12d09baf
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/plugins/artifacts.rs
@@ -0,0 +1,431 @@
+use std::{collections::BTreeSet, sync::Arc};
+
+use gateway_core::runtime::SnapshotControl;
+use sha2::{Digest as _, Sha256};
+
+use super::super::{map_store_error, publish_committed};
+use crate::{
+    model::{
+        AdminError, MutationContext, Revision,
+        plugins::{
+            InspectedPluginArtifact, InstalledPluginArtifact, PluginArtifactIconResource,
+            PluginArtifactMetadata, PluginArtifactMutation, PluginIconTheme, PluginInstallResult,
+            PluginSource,
+            distribution::VerifiedPluginArtifact,
+            instances::{
+                ConfigurePluginInstance, PluginCapabilityBinding, PluginFailurePolicy,
+                PluginInstance, PluginPermissionGrant,
+            },
+        },
+    },
+    ports::plugins::{
+        PluginDistribution, PluginPackageInspector, PluginPreparation, PluginStateStore,
+        PluginStore,
+    },
+    ports::proxy::ProxyStore,
+};
+
+use super::state::PluginStateService;
+
+/// 远程插件来源访问所需的传输与受管出站代理目录。
+pub struct PluginDistributionPorts {
+    pub(super) transport: Arc<dyn PluginDistribution>,
+    pub(super) proxies: Arc<dyn ProxyStore>,
+}
+
+impl PluginDistributionPorts {
+    #[must_use]
+    pub fn new(transport: Arc<dyn PluginDistribution>, proxies: Arc<dyn ProxyStore>) -> Self {
+        Self { transport, proxies }
+    }
+}
+
+/// 所有安装入口在取得完整包后进入同一校验与事务流程。
+pub struct PluginsService {
+    pub(super) store: Arc<dyn PluginStore>,
+    pub(super) inspector: Arc<dyn PluginPackageInspector>,
+    pub(super) distribution: PluginDistributionPorts,
+    pub(super) snapshots: Arc<dyn SnapshotControl>,
+    pub(super) preparation: Arc<dyn PluginPreparation>,
+    pub(super) published: gateway_core::runtime::RuntimeSnapshotHandle,
+    pub(super) state: PluginStateService,
+}
+
+impl PluginsService {
+    pub fn permission_descriptions(
+        &self,
+        permissions: &[String],
+    ) -> Vec<crate::model::plugins::PluginPermissionDescription> {
+        self.inspector.permission_descriptions(permissions)
+    }
+
+    #[must_use]
+    pub fn new(
+        store: Arc<dyn PluginStore>,
+        inspector: Arc<dyn PluginPackageInspector>,
+        distribution: PluginDistributionPorts,
+        snapshots: Arc<dyn SnapshotControl>,
+        preparation: Arc<dyn PluginPreparation>,
+        published: gateway_core::runtime::RuntimeSnapshotHandle,
+        state: Arc<dyn PluginStateStore>,
+    ) -> Self {
+        Self {
+            store,
+            inspector,
+            distribution,
+            snapshots,
+            preparation,
+            published,
+            state: PluginStateService::new(state),
+        }
+    }
+
+    pub async fn list(&self) -> Result<Vec<InstalledPluginArtifact>, AdminError> {
+        self.store
+            .list_artifacts()
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))
+    }
+
+    pub async fn icon(
+        &self,
+        digest: &str,
+        theme: PluginIconTheme,
+    ) -> Result<PluginArtifactIconResource, AdminError> {
+        if !valid_digest(digest) {
+            return Err(AdminError::invalid("插件制品摘要不合法"));
+        }
+        let artifact = self
+            .store
+            .load_artifact(digest)
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        if artifact.metadata.icon.is_none() {
+            return Err(AdminError::not_found("插件制品未提供图标"));
+        }
+        self.inspector
+            .icon(artifact.archive, digest.to_owned(), theme)
+            .await?
+            .ok_or_else(|| AdminError::not_found("插件制品未提供图标"))
+    }
+
+    pub async fn verify_upload(
+        &self,
+        archive: Arc<[u8]>,
+    ) -> Result<VerifiedPluginArtifact, AdminError> {
+        let artifact = self.inspector.inspect(archive, None).await?;
+        Ok(VerifiedPluginArtifact {
+            metadata: artifact.metadata,
+            source: PluginSource::Upload,
+        })
+    }
+
+    /// 管理上传固定为自定义来源；调用方不能借通用参数声明官方身份。
+    pub async fn install_upload(
+        &self,
+        archive: Arc<[u8]>,
+        expected_sha256: Option<String>,
+        context: &MutationContext,
+    ) -> Result<PluginInstallResult, AdminError> {
+        if expected_sha256.is_none() {
+            return Err(AdminError::invalid("安装需要已校验的插件包摘要"));
+        }
+        let artifact = self.inspector.inspect(archive, expected_sha256).await?;
+        let mutation = self
+            .persist(artifact, PluginSource::Upload, context)
+            .await?;
+        self.complete_install(mutation, context).await
+    }
+
+    /// 接受已导入但尚未安装的制品；官方发行导入也必须经过管理员的这一步。
+    pub async fn accept_artifact(
+        &self,
+        digest: &str,
+        context: &MutationContext,
+    ) -> Result<PluginInstallResult, AdminError> {
+        if !valid_digest(digest) {
+            return Err(AdminError::invalid("插件制品摘要不合法"));
+        }
+        let mutation = self
+            .store
+            .accept_artifact(digest, context)
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        publish_committed(self.snapshots.as_ref(), mutation.config_revision).await?;
+        self.finish_install(mutation, context).await
+    }
+
+    pub(super) async fn complete_install(
+        &self,
+        mutation: PluginArtifactMutation,
+        context: &MutationContext,
+    ) -> Result<PluginInstallResult, AdminError> {
+        let digest = mutation.artifact.metadata.sha256.clone();
+        self.accept_artifact(&digest, context).await
+    }
+
+    async fn finish_install(
+        &self,
+        mut mutation: PluginArtifactMutation,
+        context: &MutationContext,
+    ) -> Result<PluginInstallResult, AdminError> {
+        let metadata = mutation.artifact.metadata.clone();
+        let creation_id = default_instance_id(&metadata.plugin_id);
+        let configuration = configuration_defaults(&metadata);
+        let bindings = default_bindings(&metadata);
+        let probe = default_instance(
+            &metadata,
+            &creation_id,
+            configuration.clone(),
+            bindings.clone(),
+            false,
+            mutation.config_revision,
+        );
+        let configuration_required = !self
+            .preparation
+            .configuration_ready(probe, &metadata)
+            .await?;
+
+        // 其它管理员写入或同插件的并发安装可能推进全局 revision；稳定 creation ID
+        // 配合每轮重新读取，既不会复制默认实例，也不会覆盖先完成的另一个版本。
+        for _ in 0..3 {
+            let snapshot = self
+                .store
+                .load_instances()
+                .await
+                .map_err(|error| map_store_error(error, "plugin"))?;
+            if let Some((default_instance_id, required)) = self
+                .existing_plugin_instance(&snapshot, &metadata, &creation_id)
+                .await?
+            {
+                mutation.config_revision = snapshot.config_revision;
+                return Ok(PluginInstallResult {
+                    mutation,
+                    default_instance_id,
+                    configuration_required: required,
+                });
+            }
+
+            let input = ConfigurePluginInstance {
+                replace_instances: Vec::new(),
+                creation_id: Some(creation_id.clone()),
+                expected_revision: None,
+                name: metadata.display_name.clone(),
+                artifact_sha256: metadata.sha256.clone(),
+                enabled: !configuration_required,
+                configuration: configuration.clone(),
+                secrets: None,
+                bindings: bindings.clone(),
+            };
+            match self.configure_instance(None, input, context).await {
+                Ok(configured) => {
+                    mutation.config_revision = configured.config_revision;
+                    return Ok(PluginInstallResult {
+                        mutation,
+                        default_instance_id: Some(configured.instance.id),
+                        configuration_required,
+                    });
+                }
+                Err(error) if error.kind() == crate::model::AdminErrorKind::Conflict => {}
+                Err(error) => return Err(error),
+            }
+        }
+        Err(AdminError::conflict(
+            "插件安装期间配置持续变化，请刷新后重试",
+        ))
+    }
+
+    async fn existing_plugin_instance(
+        &self,
+        snapshot: &crate::model::plugins::instances::PluginInstanceSnapshot,
+        metadata: &PluginArtifactMetadata,
+        default_id: &str,
+    ) -> Result<Option<(Option<String>, bool)>, AdminError> {
+        let artifacts = self
+            .store
+            .list_artifacts()
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        let matching_digests = artifacts
+            .into_iter()
+            .filter(|artifact| artifact.metadata.plugin_id == metadata.plugin_id)
+            .map(|artifact| artifact.metadata.sha256)
+            .collect::<BTreeSet<_>>();
+        let Some(instance) = snapshot
+            .instances
+            .iter()
+            .find(|instance| matching_digests.contains(&instance.artifact_sha256))
+        else {
+            return Ok(None);
+        };
+        if instance.id == default_id && instance.artifact_sha256 == metadata.sha256 {
+            let required = !self
+                .preparation
+                .configuration_ready(instance.clone(), metadata)
+                .await?;
+            Ok(Some((Some(instance.id.clone()), required)))
+        } else {
+            Ok(Some((None, false)))
+        }
+    }
+
+    pub(super) async fn persist(
+        &self,
+        artifact: InspectedPluginArtifact,
+        source: PluginSource,
+        context: &MutationContext,
+    ) -> Result<PluginArtifactMutation, AdminError> {
+        let mutation = self
+            .store
+            .install_artifact(artifact, source, context)
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        publish_committed(self.snapshots.as_ref(), mutation.config_revision).await?;
+        Ok(mutation)
+    }
+
+    pub async fn delete(
+        &self,
+        digest: &str,
+        context: &MutationContext,
+    ) -> Result<Revision, AdminError> {
+        let revision = self
+            .store
+            .delete_artifact(digest, context)
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        publish_committed(self.snapshots.as_ref(), revision).await?;
+        Ok(revision)
+    }
+}
+
+fn valid_digest(digest: &str) -> bool {
+    digest.len() == 64
+        && digest
+            .bytes()
+            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+}
+
+fn default_instance_id(plugin_id: &str) -> String {
+    let mut hash = Sha256::new();
+    hash.update(b"codex-proxy-rs/plugin-default-instance/v1\0");
+    hash.update(plugin_id.as_bytes());
+    let digest = hash.finalize();
+    let mut bytes = [0_u8; 16];
+    bytes.copy_from_slice(&digest[..16]);
+    // RFC 9562 UUIDv8 保留给应用自定义派生；variant 固定为 RFC 4122。
+    bytes[6] = (bytes[6] & 0x0f) | 0x80;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    uuid::Uuid::from_bytes(bytes).to_string()
+}
+
+pub(super) fn configuration_defaults(metadata: &PluginArtifactMetadata) -> serde_json::Value {
+    let mut configuration = schema_default(&metadata.configuration_schema)
+        .filter(serde_json::Value::is_object)
+        .unwrap_or_else(|| serde_json::Value::Object(serde_json::Map::new()));
+    merge_property_defaults(&mut configuration, &metadata.configuration_schema);
+    if let Some(configuration) = configuration.as_object_mut() {
+        for secret in &metadata.secret_fields {
+            configuration.remove(secret);
+        }
+    }
+    configuration
+}
+
+fn schema_default(schema: &serde_json::Value) -> Option<serde_json::Value> {
+    let mut value = if let Some(value) = schema.get("default") {
+        value.clone()
+    } else {
+        let properties = schema.get("properties")?.as_object()?;
+        let mut object = serde_json::Map::new();
+        for (name, property) in properties {
+            if let Some(value) = schema_default(property) {
+                object.insert(name.clone(), value);
+            }
+        }
+        if object.is_empty() {
+            return None;
+        }
+        serde_json::Value::Object(object)
+    };
+    merge_property_defaults(&mut value, schema);
+    Some(value)
+}
+
+fn merge_property_defaults(value: &mut serde_json::Value, schema: &serde_json::Value) {
+    let (Some(value), Some(properties)) = (
+        value.as_object_mut(),
+        schema
+            .get("properties")
+            .and_then(serde_json::Value::as_object),
+    ) else {
+        return;
+    };
+    for (name, property) in properties {
+        if let Some(current) = value.get_mut(name) {
+            merge_property_defaults(current, property);
+        } else if let Some(default) = schema_default(property) {
+            value.insert(name.clone(), default);
+        }
+    }
+}
+
+pub(super) fn default_bindings(metadata: &PluginArtifactMetadata) -> Vec<PluginCapabilityBinding> {
+    metadata
+        .contributes
+        .iter()
+        .filter(|(capability, _)| {
+            !matches!(
+                capability.as_str(),
+                "frontend_authentication" | "management" | "command_line"
+            )
+        })
+        .flat_map(|(_, contribution)| {
+            contribution
+                .stages
+                .iter()
+                .map(|stage| PluginCapabilityBinding {
+                    contribution: contribution.id.clone(),
+                    stage: stage.clone(),
+                    order: 0,
+                    failure_policy: if stage == "observation" {
+                        PluginFailurePolicy::Observe
+                    } else {
+                        PluginFailurePolicy::Reject
+                    },
+                    client_key_ids: Vec::new(),
+                    account_group_ids: Vec::new(),
+                    provider_ids: Vec::new(),
+                    models: Vec::new(),
+                    identity_bindings: Vec::new(),
+                })
+        })
+        .collect()
+}
+
+fn default_instance(
+    metadata: &PluginArtifactMetadata,
+    id: &str,
+    configuration: serde_json::Value,
+    bindings: Vec<PluginCapabilityBinding>,
+    enabled: bool,
+    revision: Revision,
+) -> PluginInstance {
+    PluginInstance {
+        id: id.to_owned(),
+        name: metadata.display_name.clone(),
+        artifact_sha256: metadata.sha256.clone(),
+        enabled,
+        trusted_process: true,
+        configuration,
+        secrets: Default::default(),
+        grants: metadata
+            .requested_permissions
+            .iter()
+            .cloned()
+            .map(|permission| PluginPermissionGrant { permission })
+            .collect(),
+        bindings,
+        revision,
+    }
+}
diff --git a/backend/crates/gateway-admin/src/use_case/plugins/distribution.rs b/backend/crates/gateway-admin/src/use_case/plugins/distribution.rs
new file mode 100644
index 000000000..2ea751d91
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/plugins/distribution.rs
@@ -0,0 +1,379 @@
+use std::collections::BTreeSet;
+
+use super::PluginsService;
+use crate::{
+    model::{
+        AdminError, MutationContext, Revision,
+        plugins::{
+            InspectedPluginArtifact, PluginInstallResult, PluginSource,
+            distribution::{
+                GithubReleaseQuery, PluginDistributionEgress, PluginRelease, PluginSourceBinding,
+                PluginUpdateCheck, PluginUpdatePolicy, PluginUpdateSource, RemotePluginInstall,
+                RemotePluginLocation, RemotePluginVerify, SourceAuthentication, SourceCredential,
+                SourceCredentialInfo, VerifiedPluginArtifact,
+            },
+        },
+    },
+    ports::store::AdminStoreErrorKind,
+    use_case::{map_store_error, publish_committed},
+};
+
+impl PluginsService {
+    pub async fn update_sources(
+        &self,
+    ) -> Result<Vec<crate::model::plugins::distribution::PluginSourceBinding>, AdminError> {
+        self.store
+            .list_update_sources()
+            .await
+            .map_err(|e| map_store_error(e, "plugin"))
+    }
+
+    pub async fn change_update_source(
+        &self,
+        mut binding: crate::model::plugins::distribution::PluginSourceBinding,
+        context: &MutationContext,
+    ) -> Result<Revision, AdminError> {
+        if matches!(binding.source, PluginUpdateSource::Builtin) {
+            return Err(AdminError::invalid("官方来源只由发行清单确认"));
+        }
+        if let PluginUpdateSource::Github { repository } = &mut binding.source {
+            repository.make_ascii_lowercase();
+        }
+        self.distribution
+            .transport
+            .validate_source(&binding.source)?;
+        validate_update_policy(&binding)?;
+        validate_source_egress(&binding)?;
+        self.resolve_egress(binding.outbound_proxy_id.as_deref())
+            .await?;
+        let revision = self
+            .store
+            .change_update_source(binding, context)
+            .await
+            .map_err(|e| map_store_error(e, "plugin"))?;
+        publish_committed(self.snapshots.as_ref(), revision).await?;
+        Ok(revision)
+    }
+
+    pub async fn check_update(
+        &self,
+        plugin_id: &str,
+        credential_ids: &[String],
+    ) -> Result<PluginUpdateCheck, AdminError> {
+        let binding = self
+            .update_sources()
+            .await?
+            .into_iter()
+            .find(|binding| binding.plugin_id == plugin_id)
+            .ok_or_else(|| AdminError::not_found("插件更新来源不存在"))?;
+        validate_update_policy(&binding)?;
+        let PluginUpdateSource::Github { repository } = &binding.source else {
+            return Err(AdminError::invalid(
+                "该来源不提供 Release 更新查询，请显式选择并安装插件包",
+            ));
+        };
+        let (tag, allow_prerelease) = match &binding.policy {
+            PluginUpdatePolicy::Manual {} => {
+                return Err(AdminError::invalid("请先为该来源设置更新检查策略"));
+            }
+            PluginUpdatePolicy::Stable {} => (None, false),
+            PluginUpdatePolicy::Pinned {
+                tag,
+                allow_prerelease,
+            } => (Some(tag.clone()), *allow_prerelease),
+        };
+        let release = self
+            .query_release(
+                GithubReleaseQuery {
+                    repository: repository.clone(),
+                    tag,
+                    allow_prerelease,
+                },
+                credential_ids,
+                binding.outbound_proxy_id.as_deref(),
+            )
+            .await?;
+        // 查询期间来源或策略被修改时返回冲突，不把旧来源的候选交给下一步安装。
+        if !self.update_sources().await?.contains(&binding) {
+            return Err(AdminError::conflict("插件更新来源已变更，请重新检查"));
+        }
+        Ok(PluginUpdateCheck { binding, release })
+    }
+    pub async fn source_credentials(&self) -> Result<Vec<SourceCredentialInfo>, AdminError> {
+        self.store
+            .list_source_credentials()
+            .await
+            .map_err(|e| map_store_error(e, "plugin"))
+    }
+
+    pub async fn create_source_credential(
+        &self,
+        mut info: SourceCredentialInfo,
+        authentication: SourceAuthentication,
+        context: &MutationContext,
+    ) -> Result<SourceCredentialInfo, AdminError> {
+        info.id = uuid::Uuid::now_v7().to_string();
+        let credential = SourceCredential {
+            info: info.clone(),
+            authentication,
+        };
+        self.distribution
+            .transport
+            .validate_credential(&credential)?;
+        let revision = self
+            .store
+            .save_source_credential(credential, context)
+            .await
+            .map_err(|e| map_store_error(e, "plugin"))?;
+        publish_committed(self.snapshots.as_ref(), revision).await?;
+        Ok(info)
+    }
+
+    pub async fn delete_source_credential(
+        &self,
+        id: &str,
+        context: &MutationContext,
+    ) -> Result<Revision, AdminError> {
+        let revision = self
+            .store
+            .delete_source_credential(id, context)
+            .await
+            .map_err(|e| map_store_error(e, "plugin"))?;
+        publish_committed(self.snapshots.as_ref(), revision).await?;
+        Ok(revision)
+    }
+
+    pub async fn query_release(
+        &self,
+        query: GithubReleaseQuery,
+        credential_ids: &[String],
+        outbound_proxy_id: Option<&str>,
+    ) -> Result<PluginRelease, AdminError> {
+        let egress = self.resolve_egress(outbound_proxy_id).await?;
+        let release = self
+            .distribution
+            .transport
+            .query_release(
+                query,
+                self.credentials(credential_ids).await?,
+                egress.clone(),
+            )
+            .await?;
+        self.ensure_egress_current(egress.as_ref()).await?;
+        Ok(release)
+    }
+
+    pub async fn install_remote(
+        &self,
+        input: RemotePluginInstall,
+        context: &MutationContext,
+    ) -> Result<PluginInstallResult, AdminError> {
+        if !crate::model::plugins::valid_plugin_id(&input.plugin_id)
+            || input.version.is_empty()
+            || input.version.len() > 128
+        {
+            return Err(AdminError::invalid("安装需要已解析的插件 ID 与版本"));
+        }
+        let digest = match &input.location {
+            RemotePluginLocation::Url { sha256, .. }
+            | RemotePluginLocation::Github { sha256, .. } => sha256,
+        };
+        if digest.is_none() {
+            return Err(AdminError::invalid("安装需要已校验的插件包摘要"));
+        }
+        let (artifact, source) = self
+            .inspect_remote(RemotePluginVerify {
+                location: input.location,
+                credential_ids: input.credential_ids,
+                outbound_proxy_id: input.outbound_proxy_id,
+                expected_plugin_id: Some(input.plugin_id),
+            })
+            .await?;
+        if artifact.metadata.version != input.version {
+            return Err(AdminError::invalid("插件清单版本与安装选择不符"));
+        }
+        let mutation = self.persist(artifact, source, context).await?;
+        self.complete_install(mutation, context).await
+    }
+
+    pub async fn verify_remote(
+        &self,
+        input: RemotePluginVerify,
+    ) -> Result<VerifiedPluginArtifact, AdminError> {
+        let (artifact, source) = self.inspect_remote(input).await?;
+        Ok(VerifiedPluginArtifact {
+            metadata: artifact.metadata,
+            source,
+        })
+    }
+
+    async fn inspect_remote(
+        &self,
+        input: RemotePluginVerify,
+    ) -> Result<(InspectedPluginArtifact, PluginSource), AdminError> {
+        if input
+            .expected_plugin_id
+            .as_deref()
+            .is_some_and(|id| !crate::model::plugins::valid_plugin_id(id))
+        {
+            return Err(AdminError::invalid("预期插件 ID 不合法"));
+        }
+        let source = match &input.location {
+            RemotePluginLocation::Url { url, .. } => PluginUpdateSource::Url { url: url.clone() },
+            RemotePluginLocation::Github { repository, .. } => PluginUpdateSource::Github {
+                repository: repository.to_ascii_lowercase(),
+            },
+        };
+        let outbound_proxy_id = input.outbound_proxy_id.clone();
+        self.distribution.transport.validate_source(&source)?;
+        let bindings = self.update_sources().await?;
+        let expected_binding = bindings
+            .iter()
+            .find(|binding| Some(&binding.plugin_id) == input.expected_plugin_id.as_ref());
+        if expected_binding.is_some_and(|binding| {
+            binding.source != source || binding.outbound_proxy_id != outbound_proxy_id
+        }) {
+            return Err(AdminError::conflict(
+                "插件来源与已保存配置不符，请先显式修改来源",
+            ));
+        }
+        let egress = self.resolve_egress(outbound_proxy_id.as_deref()).await?;
+        let download = self
+            .distribution
+            .transport
+            .download(
+                input.location,
+                self.credentials(&input.credential_ids).await?,
+                egress.clone(),
+            )
+            .await?;
+        self.ensure_egress_current(egress.as_ref()).await?;
+        let artifact = self
+            .inspector
+            .inspect(download.archive, Some(download.sha256))
+            .await?;
+        if input
+            .expected_plugin_id
+            .as_ref()
+            .is_some_and(|id| *id != artifact.metadata.plugin_id)
+        {
+            return Err(AdminError::invalid("插件清单身份与安装选择不符"));
+        }
+        // 首次解析前身份未知，按包内身份复核下载前的来源绑定。
+        let binding = bindings
+            .iter()
+            .find(|binding| binding.plugin_id == artifact.metadata.plugin_id);
+        if binding.is_some_and(|binding| {
+            binding.source != source || binding.outbound_proxy_id != outbound_proxy_id
+        }) {
+            return Err(AdminError::conflict(
+                "插件来源与已保存配置不符，请先显式修改来源",
+            ));
+        }
+        if PluginUpdateSource::from(&download.source) != source {
+            return Err(AdminError::invalid("下载来源与校验选择不符"));
+        }
+        if download.source.outbound_proxy() != egress.as_ref().map(|egress| &egress.source) {
+            return Err(AdminError::invalid("下载出站身份与安装选择不符"));
+        }
+        let current_binding = self
+            .update_sources()
+            .await?
+            .into_iter()
+            .find(|binding| binding.plugin_id == artifact.metadata.plugin_id);
+        if current_binding.as_ref() != binding {
+            return Err(AdminError::conflict("插件更新来源已变更，请重新校验"));
+        }
+        Ok((artifact, download.source))
+    }
+
+    async fn resolve_egress(
+        &self,
+        outbound_proxy_id: Option<&str>,
+    ) -> Result<Option<PluginDistributionEgress>, AdminError> {
+        let Some(id) = outbound_proxy_id else {
+            return Ok(None);
+        };
+        if id.is_empty() || id.len() > 128 || id.chars().any(char::is_control) {
+            return Err(AdminError::invalid("插件来源出站代理不合法"));
+        }
+        let record = self
+            .distribution
+            .proxies
+            .get(id)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))?;
+        Ok(Some(PluginDistributionEgress::new(
+            record.id,
+            record.revision,
+            record.proxy,
+        )))
+    }
+
+    async fn ensure_egress_current(
+        &self,
+        egress: Option<&PluginDistributionEgress>,
+    ) -> Result<(), AdminError> {
+        let Some(egress) = egress else {
+            return Ok(());
+        };
+        let current = match self.distribution.proxies.get(&egress.source.id).await {
+            Ok(current) => current,
+            Err(error) if error.kind() == AdminStoreErrorKind::NotFound => {
+                return Err(AdminError::conflict("插件来源出站代理已变更，请重新校验"));
+            }
+            Err(error) => return Err(map_store_error(error, "proxy")),
+        };
+        if current.revision.get() != egress.source.revision || current.proxy != egress.proxy {
+            return Err(AdminError::conflict("插件来源出站代理已变更，请重新校验"));
+        }
+        Ok(())
+    }
+
+    async fn credentials(&self, ids: &[String]) -> Result<Vec<SourceCredential>, AdminError> {
+        if ids.len() > 8 || ids.iter().collect::<BTreeSet<_>>().len() != ids.len() {
+            return Err(AdminError::invalid("下载凭据不能重复，且最多选择 8 个"));
+        }
+        let mut credentials = Vec::with_capacity(ids.len());
+        for id in ids {
+            credentials.push(
+                self.store
+                    .load_source_credential(id)
+                    .await
+                    .map_err(|e| map_store_error(e, "plugin"))?,
+            );
+        }
+        Ok(credentials)
+    }
+}
+
+fn validate_update_policy(binding: &PluginSourceBinding) -> Result<(), AdminError> {
+    if !matches!(binding.source, PluginUpdateSource::Github { .. })
+        && !matches!(binding.policy, PluginUpdatePolicy::Manual {})
+    {
+        return Err(AdminError::invalid(
+            "只有 GitHub 来源支持 Release 更新检查策略",
+        ));
+    }
+    if let PluginUpdatePolicy::Pinned { tag, .. } = &binding.policy
+        && (tag.is_empty()
+            || tag.len() > 128
+            || tag.chars().any(char::is_control)
+            || tag.trim() != tag)
+    {
+        return Err(AdminError::invalid("固定 Release tag 不合法"));
+    }
+    Ok(())
+}
+
+fn validate_source_egress(binding: &PluginSourceBinding) -> Result<(), AdminError> {
+    if binding.outbound_proxy_id.is_some()
+        && matches!(
+            binding.source,
+            PluginUpdateSource::Builtin | PluginUpdateSource::Upload
+        )
+    {
+        return Err(AdminError::invalid("本地或官方来源不能配置出站代理"));
+    }
+    Ok(())
+}
diff --git a/backend/crates/gateway-admin/src/use_case/plugins/instances.rs b/backend/crates/gateway-admin/src/use_case/plugins/instances.rs
new file mode 100644
index 000000000..3c983c896
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/plugins/instances.rs
@@ -0,0 +1,786 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use gateway_core::{policy::ClientApiKeyId, routing::AccountGroupId};
+use secrecy::ExposeSecret;
+
+use super::PluginsService;
+use crate::{
+    model::{
+        AdminError, MutationContext, Revision,
+        plugins::instances::{
+            ConfigurePluginInstance, PluginInstance, PluginInstanceMutation,
+            PluginInstanceReplacement, PluginInstanceRuntime, PluginInstanceRuntimeStatus,
+            PluginInstanceSnapshot, PluginInstanceView, PluginPermissionGrant,
+        },
+        plugins::state::{PluginStateCommit, PluginStateConfiguration},
+    },
+    use_case::{map_store_error, publish_committed},
+};
+
+impl PluginsService {
+    pub async fn instances(&self) -> Result<Vec<PluginInstanceView>, AdminError> {
+        let snapshot = self
+            .store
+            .load_instances()
+            .await
+            .map_err(|e| map_store_error(e, "plugin"))?;
+        let published = self.published.snapshot_for_diagnostics();
+        let published_revision = published.as_ref().map(|snapshot| snapshot.revision().get());
+        let published_ready = published
+            .as_ref()
+            .is_some_and(|snapshot| snapshot.extensions().is_none_or(|set| set.can_serve()));
+        let mut diagnostics = self
+            .preparation
+            .runtime_diagnostics(
+                &snapshot,
+                published_revision,
+                published
+                    .as_ref()
+                    .and_then(|snapshot| snapshot.extensions()),
+            )
+            .await
+            .unwrap_or_default();
+        let target_revision = snapshot.config_revision.get();
+        let artifacts = self
+            .list()
+            .await?
+            .into_iter()
+            .map(|artifact| (artifact.metadata.sha256.clone(), artifact.metadata))
+            .collect::<BTreeMap<_, _>>();
+        let mut views = Vec::with_capacity(snapshot.instances.len());
+        for instance in snapshot.instances {
+            let metadata = artifacts
+                .get(&instance.artifact_sha256)
+                .ok_or_else(|| AdminError::not_found("插件制品不存在"))?;
+            let configuration_required = !self
+                .preparation
+                .configuration_ready(instance.clone(), metadata)
+                .await?;
+            let runtime = diagnostics.remove(&instance.id).unwrap_or_else(|| {
+                let running = instance.enabled
+                    && published_ready
+                    && published_revision == Some(target_revision);
+                PluginInstanceRuntime {
+                    status: if !instance.enabled {
+                        PluginInstanceRuntimeStatus::Disabled
+                    } else if running {
+                        PluginInstanceRuntimeStatus::Running
+                    } else {
+                        PluginInstanceRuntimeStatus::AwaitingPublication
+                    },
+                    actual_revision: running.then_some(instance.revision.get()),
+                    actual_artifact_sha256: running.then(|| instance.artifact_sha256.clone()),
+                    failure: None,
+                    draining_revisions: Vec::new(),
+                    retained_continuations: 0,
+                }
+            });
+            views.push(PluginInstanceView {
+                configuration_required,
+                running: runtime.status == PluginInstanceRuntimeStatus::Running,
+                published_revision,
+                runtime,
+                instance,
+            });
+        }
+        Ok(views)
+    }
+
+    pub async fn configure_instance(
+        &self,
+        id: Option<&str>,
+        input: ConfigurePluginInstance,
+        context: &MutationContext,
+    ) -> Result<PluginInstanceMutation, AdminError> {
+        if id.is_some() && input.creation_id.is_some() {
+            return Err(AdminError::invalid("编辑配置不能使用创建标识"));
+        }
+        if id.is_none() && input.expected_revision.is_some() {
+            return Err(AdminError::invalid("创建配置不能指定已有配置版本"));
+        }
+        if let Some(creation_id) = &input.creation_id {
+            let parsed = uuid::Uuid::parse_str(creation_id)
+                .map_err(|_| AdminError::invalid("配置创建标识必须是 UUID"))?;
+            if parsed.to_string() != *creation_id {
+                return Err(AdminError::invalid("配置创建标识必须使用标准 UUID 格式"));
+            }
+        }
+        let snapshot = self
+            .store
+            .load_instances()
+            .await
+            .map_err(|e| map_store_error(e, "plugin"))?;
+        let existing = match id {
+            Some(id) => Some(
+                snapshot
+                    .instances
+                    .iter()
+                    .find(|instance| instance.id == id)
+                    .cloned()
+                    .ok_or_else(|| AdminError::not_found("插件实例不存在"))?,
+            ),
+            None => input.creation_id.as_ref().and_then(|creation_id| {
+                snapshot
+                    .instances
+                    .iter()
+                    .find(|instance| instance.id == *creation_id)
+                    .cloned()
+            }),
+        };
+        if let Some(existing) = &existing {
+            if id.is_none() && !same_creation_request(existing, &input) {
+                return Err(AdminError::conflict("此配置已创建，请加载最新配置后编辑"));
+            }
+            if input
+                .expected_revision
+                .is_some_and(|revision| revision != existing.revision.get())
+            {
+                return Err(AdminError::conflict("插件配置已变更，请加载最新配置后重试"));
+            }
+        }
+        self.configure_from_snapshot(snapshot, existing, input, context)
+            .await
+    }
+
+    pub(super) async fn configure_from_snapshot(
+        &self,
+        mut snapshot: PluginInstanceSnapshot,
+        existing: Option<PluginInstance>,
+        input: ConfigurePluginInstance,
+        context: &MutationContext,
+    ) -> Result<PluginInstanceMutation, AdminError> {
+        let expected_revision = snapshot.config_revision;
+        let candidate_revision = next_revision(expected_revision)?;
+        let artifacts = self
+            .store
+            .list_artifacts()
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        let artifact = artifacts
+            .iter()
+            .find(|artifact| artifact.metadata.sha256 == input.artifact_sha256)
+            .ok_or_else(|| AdminError::not_found("插件制品不存在"))?;
+        if artifact.accepted_at.is_none() {
+            return Err(AdminError::invalid("请先安装并接受该版本声明的权限"));
+        }
+        let same_plugin = |digest: &str| {
+            artifacts.iter().any(|item| {
+                item.metadata.sha256 == digest
+                    && item.metadata.plugin_id == artifact.metadata.plugin_id
+            })
+        };
+        if existing
+            .as_ref()
+            .is_some_and(|previous| !same_plugin(&previous.artifact_sha256))
+        {
+            return Err(AdminError::invalid("不能将已有配置切换为另一个插件"));
+        }
+        if input.enabled
+            && snapshot.instances.iter().any(|other| {
+                other.enabled
+                    && existing
+                        .as_ref()
+                        .is_none_or(|current| current.id != other.id)
+                    && same_plugin(&other.artifact_sha256)
+                    && !input
+                        .replace_instances
+                        .iter()
+                        .any(|replacement| replacement.id == other.id)
+            })
+        {
+            return Err(AdminError::conflict(
+                "此插件已有启用配置，请先切换或停用旧配置",
+            ));
+        }
+        let saved = if let Some(previous) = &existing
+            && previous.artifact_sha256 != input.artifact_sha256
+            && input.secrets.is_none()
+        {
+            self.store
+                .load_version_configuration(&previous.id, &input.artifact_sha256)
+                .await
+                .map_err(|error| map_store_error(error, "plugin"))?
+        } else {
+            None
+        };
+        let instance = PluginInstance {
+            id: existing.as_ref().map_or_else(
+                || {
+                    input
+                        .creation_id
+                        .clone()
+                        .unwrap_or_else(|| uuid::Uuid::now_v7().to_string())
+                },
+                |instance| instance.id.clone(),
+            ),
+            name: input.name.trim().to_owned(),
+            artifact_sha256: input.artifact_sha256,
+            enabled: input.enabled,
+            trusted_process: true,
+            configuration: input.configuration,
+            secrets: input
+                .secrets
+                .or_else(|| saved.map(|saved| saved.secrets))
+                .unwrap_or_else(|| {
+                    existing
+                        .as_ref()
+                        .map_or_else(Default::default, |instance| instance.secrets.clone())
+                }),
+            grants: artifact
+                .metadata
+                .requested_permissions
+                .iter()
+                .cloned()
+                .map(|permission| PluginPermissionGrant { permission })
+                .collect(),
+            bindings: input.bindings,
+            revision: candidate_revision,
+        };
+        validate_input(&instance)?;
+        if existing
+            .as_ref()
+            .is_some_and(|previous| previous.artifact_sha256 != instance.artifact_sha256)
+            && !self
+                .preparation
+                .configuration_ready(instance.clone(), &artifact.metadata)
+                .await?
+        {
+            return Err(AdminError::invalid(
+                "目标版本仍缺少必填设置，请补充后再切换",
+            ));
+        }
+
+        let replacements = input.replace_instances;
+        if !replacements.is_empty() {
+            if !instance.enabled || replacements.len() > 256 {
+                return Err(AdminError::invalid(
+                    "仅启用配置时可以切换其他配置，单次最多 256 项",
+                ));
+            }
+            let mut ids = BTreeSet::new();
+            for replacement in &replacements {
+                if replacement.id == instance.id || !ids.insert(&replacement.id) {
+                    return Err(AdminError::invalid("停用列表不能重复或包含当前配置"));
+                }
+                let previous = snapshot
+                    .instances
+                    .iter()
+                    .find(|item| item.id == replacement.id)
+                    .ok_or_else(|| AdminError::conflict("待停用配置已变更，请重新确认"))?;
+                if !previous.enabled || previous.revision.get() != replacement.expected_revision {
+                    return Err(AdminError::conflict("待停用配置已变更，请重新确认"));
+                }
+                if !artifacts.iter().any(|item| {
+                    item.metadata.sha256 == previous.artifact_sha256
+                        && item.metadata.plugin_id == artifact.metadata.plugin_id
+                }) {
+                    return Err(AdminError::invalid("只能切换同一插件的配置"));
+                }
+            }
+        }
+        let state = self.preparation.validate(instance.clone()).await?;
+        if let Some(existing) = &existing
+            && self.state.transition_required(&existing.id, &state).await?
+        {
+            return self
+                .configure_instance_with_state_transition(
+                    snapshot,
+                    existing.clone(),
+                    instance,
+                    state,
+                    &replacements,
+                    context,
+                )
+                .await;
+        }
+        snapshot.instances.retain(|item| item.id != instance.id);
+        snapshot.instances.push(instance.clone());
+        snapshot.config_revision = candidate_revision;
+        apply_replacements(&mut snapshot, &replacements);
+        let prepared = self
+            .preparation
+            .prepare(expected_revision, snapshot.clone())
+            .await?;
+        let result = self
+            .store
+            .save_instance_replacing(
+                instance,
+                expected_revision,
+                PluginStateCommit {
+                    configuration: state,
+                    transition_id: None,
+                },
+                &replacements,
+                context,
+            )
+            .await
+            .map_err(|e| map_store_error(e, "plugin"))?;
+        let prepared = if result.config_revision == candidate_revision
+            && result.instance.revision == candidate_revision
+        {
+            prepared
+        } else {
+            snapshot.config_revision = result.config_revision;
+            snapshot
+                .instances
+                .retain(|item| item.id != result.instance.id);
+            snapshot.instances.push(result.instance.clone());
+            apply_replacements(&mut snapshot, &replacements);
+            self.preparation
+                .prepare(result.config_revision, snapshot)
+                .await?
+        };
+        self.preparation
+            .activate_state(&prepared, &result.instance)
+            .await?;
+        // prepared 的强引用跨过提交与唯一发布入口，防止候选在被读取之前回收。
+        publish_committed(self.snapshots.as_ref(), result.config_revision).await?;
+        drop(prepared);
+        Ok(result)
+    }
+
+    async fn configure_instance_with_state_transition(
+        &self,
+        mut snapshot: PluginInstanceSnapshot,
+        previous: PluginInstance,
+        mut target: PluginInstance,
+        target_state: PluginStateConfiguration,
+        replacements: &[PluginInstanceReplacement],
+        context: &MutationContext,
+    ) -> Result<PluginInstanceMutation, AdminError> {
+        let previous_state = self.preparation.validate(previous.clone()).await?;
+        let original_revision = snapshot.config_revision;
+        // 即使最终保持停用，迁移也必须由目标制品的受控候选执行。
+        let mut migration_instance = target.clone();
+        migration_instance.enabled = true;
+        snapshot.config_revision = migration_instance.revision;
+        snapshot
+            .instances
+            .retain(|instance| instance.id != migration_instance.id);
+        snapshot.instances.push(migration_instance);
+        apply_replacements(&mut snapshot, replacements);
+        let migration_prepared = self
+            .preparation
+            .prepare(original_revision, snapshot)
+            .await?;
+
+        let mut disabled_revision = None;
+        let disabled = if previous.enabled {
+            let mut disabled = previous.clone();
+            disabled.enabled = false;
+            let mutation = self
+                .store
+                .save_instance_with_state(
+                    disabled,
+                    original_revision,
+                    PluginStateCommit {
+                        configuration: previous_state.clone(),
+                        transition_id: None,
+                    },
+                    context,
+                )
+                .await
+                .map_err(|error| map_store_error(error, "plugin"))?;
+            publish_committed(self.snapshots.as_ref(), mutation.config_revision).await?;
+            self.preparation
+                .quiesce_instance(&previous.id, &previous.artifact_sha256, previous.revision)
+                .await;
+            disabled_revision = Some(mutation.config_revision);
+            mutation.instance
+        } else {
+            previous.clone()
+        };
+        let expected_revision = disabled_revision.unwrap_or(original_revision);
+        let transition = match self
+            .state
+            .begin_transition(
+                &disabled.id,
+                disabled.revision,
+                &target.artifact_sha256,
+                target_state.clone(),
+            )
+            .await
+        {
+            Ok(transition) => transition,
+            Err(error) => {
+                return Err(self
+                    .recover_failed_state_transition(
+                        None,
+                        &previous,
+                        &previous_state,
+                        disabled_revision,
+                        context,
+                        error,
+                    )
+                    .await);
+            }
+        };
+        if let Err(error) = self
+            .preparation
+            .migrate_state(&migration_prepared, transition.clone())
+            .await
+        {
+            return Err(self
+                .recover_failed_state_transition(
+                    Some(&transition.id),
+                    &previous,
+                    &previous_state,
+                    disabled_revision,
+                    context,
+                    error,
+                )
+                .await);
+        }
+
+        let mut current = self
+            .store
+            .load_instances()
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        if current.config_revision != expected_revision {
+            return Err(self
+                .recover_failed_state_transition(
+                    Some(&transition.id),
+                    &previous,
+                    &previous_state,
+                    disabled_revision,
+                    context,
+                    AdminError::conflict("迁移期间插件配置已发生变化"),
+                )
+                .await);
+        }
+        let candidate_revision = next_revision(expected_revision)?;
+        target.revision = candidate_revision;
+        current.instances.retain(|item| item.id != target.id);
+        current.instances.push(target.clone());
+        current.config_revision = candidate_revision;
+        apply_replacements(&mut current, replacements);
+        let prepared = match self
+            .preparation
+            .prepare(expected_revision, current.clone())
+            .await
+        {
+            Ok(prepared) => prepared,
+            Err(error) => {
+                return Err(self
+                    .recover_failed_state_transition(
+                        Some(&transition.id),
+                        &previous,
+                        &previous_state,
+                        disabled_revision,
+                        context,
+                        error,
+                    )
+                    .await);
+            }
+        };
+        let result = match self
+            .store
+            .save_instance_replacing(
+                target,
+                expected_revision,
+                PluginStateCommit {
+                    configuration: target_state,
+                    transition_id: Some(transition.id.clone()),
+                },
+                replacements,
+                context,
+            )
+            .await
+        {
+            Ok(result) => result,
+            Err(error) => {
+                return Err(self
+                    .recover_failed_state_transition(
+                        Some(&transition.id),
+                        &previous,
+                        &previous_state,
+                        disabled_revision,
+                        context,
+                        map_store_error(error, "plugin"),
+                    )
+                    .await);
+            }
+        };
+        let prepared = if result.config_revision == candidate_revision
+            && result.instance.revision == candidate_revision
+        {
+            prepared
+        } else {
+            current.config_revision = result.config_revision;
+            current
+                .instances
+                .retain(|item| item.id != result.instance.id);
+            current.instances.push(result.instance.clone());
+            apply_replacements(&mut current, replacements);
+            self.preparation
+                .prepare(result.config_revision, current)
+                .await?
+        };
+        self.preparation
+            .activate_state(&prepared, &result.instance)
+            .await?;
+        publish_committed(self.snapshots.as_ref(), result.config_revision).await?;
+        drop(migration_prepared);
+        drop(prepared);
+        Ok(result)
+    }
+
+    async fn recover_failed_state_transition(
+        &self,
+        transition_id: Option<&str>,
+        previous: &PluginInstance,
+        previous_state: &PluginStateConfiguration,
+        disabled_revision: Option<Revision>,
+        context: &MutationContext,
+        original_error: AdminError,
+    ) -> AdminError {
+        if let Some(transition_id) = transition_id {
+            self.state.abort_transition(transition_id).await;
+        }
+        let Some(disabled_revision) = disabled_revision else {
+            return original_error;
+        };
+        let restored = async {
+            let mut snapshot = self
+                .store
+                .load_instances()
+                .await
+                .map_err(|error| map_store_error(error, "plugin"))?;
+            if snapshot.config_revision != disabled_revision {
+                return Err(AdminError::conflict(
+                    "状态迁移失败；实例已保持停用，且配置已被其他操作修改",
+                ));
+            }
+            let candidate_revision = next_revision(disabled_revision)?;
+            let mut restore = previous.clone();
+            restore.enabled = true;
+            restore.revision = candidate_revision;
+            snapshot.instances.retain(|item| item.id != restore.id);
+            snapshot.instances.push(restore.clone());
+            snapshot.config_revision = candidate_revision;
+            let prepared = self
+                .preparation
+                .prepare(disabled_revision, snapshot.clone())
+                .await?;
+            let mutation = self
+                .store
+                .save_instance_with_state(
+                    restore,
+                    disabled_revision,
+                    PluginStateCommit {
+                        configuration: previous_state.clone(),
+                        transition_id: None,
+                    },
+                    context,
+                )
+                .await
+                .map_err(|error| map_store_error(error, "plugin"))?;
+            let prepared = if mutation.config_revision == candidate_revision
+                && mutation.instance.revision == candidate_revision
+            {
+                prepared
+            } else {
+                snapshot.config_revision = mutation.config_revision;
+                snapshot
+                    .instances
+                    .retain(|item| item.id != mutation.instance.id);
+                snapshot.instances.push(mutation.instance.clone());
+                self.preparation
+                    .prepare(mutation.config_revision, snapshot)
+                    .await?
+            };
+            self.preparation
+                .activate_state(&prepared, &mutation.instance)
+                .await?;
+            publish_committed(self.snapshots.as_ref(), mutation.config_revision).await?;
+            Ok::<(), AdminError>(())
+        }
+        .await;
+        match restored {
+            Ok(()) => original_error,
+            Err(error) => {
+                tracing::warn!(
+                    error_kind = ?error.kind(),
+                    "plugin state migration failed and the previous instance could not be restored"
+                );
+                AdminError::conflict("状态迁移失败；为避免覆盖并发配置，插件实例已保持停用")
+            }
+        }
+    }
+
+    pub async fn delete_instance(
+        &self,
+        id: &str,
+        context: &MutationContext,
+    ) -> Result<Revision, AdminError> {
+        let snapshot = self
+            .store
+            .load_instances()
+            .await
+            .map_err(|e| map_store_error(e, "plugin"))?;
+        let instance = snapshot
+            .instances
+            .iter()
+            .find(|instance| instance.id == id)
+            .ok_or_else(|| AdminError::not_found("插件实例不存在"))?;
+        if instance.enabled {
+            return Err(AdminError::conflict("请先停用插件实例"));
+        }
+        let revision = self
+            .store
+            .delete_instance(id, snapshot.config_revision, context)
+            .await
+            .map_err(|e| map_store_error(e, "plugin"))?;
+        publish_committed(self.snapshots.as_ref(), revision).await?;
+        Ok(revision)
+    }
+
+    /// 紧急管理修复不要求损坏插件成功准备；提交后沿用现有发布与暂停合同。
+    pub async fn disable_instance(
+        &self,
+        id: &str,
+        context: &MutationContext,
+    ) -> Result<PluginInstanceMutation, AdminError> {
+        let PluginInstanceSnapshot {
+            config_revision,
+            instances,
+        } = self
+            .store
+            .load_instances()
+            .await
+            .map_err(|e| map_store_error(e, "plugin"))?;
+        let mut instance = instances
+            .into_iter()
+            .find(|instance| instance.id == id)
+            .ok_or_else(|| AdminError::not_found("插件实例不存在"))?;
+        instance.enabled = false;
+        let result = self
+            .store
+            .save_instance(instance, config_revision, context)
+            .await
+            .map_err(|e| map_store_error(e, "plugin"))?;
+        publish_committed(self.snapshots.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+}
+
+fn apply_replacements(
+    snapshot: &mut PluginInstanceSnapshot,
+    replacements: &[PluginInstanceReplacement],
+) {
+    for instance in &mut snapshot.instances {
+        if replacements.iter().any(|item| item.id == instance.id) {
+            instance.enabled = false;
+            instance.revision = snapshot.config_revision;
+        }
+    }
+}
+
+fn same_creation_request(existing: &PluginInstance, input: &ConfigurePluginInstance) -> bool {
+    let same_secrets = input
+        .secrets
+        .as_ref()
+        .map_or(existing.secrets.is_empty(), |secrets| {
+            secrets.len() == existing.secrets.len()
+                && secrets.iter().all(|(key, value)| {
+                    existing
+                        .secrets
+                        .get(key)
+                        .is_some_and(|current| current.expose_secret() == value.expose_secret())
+                })
+        });
+    existing.name == input.name.trim()
+        && existing.artifact_sha256 == input.artifact_sha256
+        && existing.enabled == input.enabled
+        && existing.configuration == input.configuration
+        && existing.bindings == input.bindings
+        && same_secrets
+}
+
+fn validate_input(instance: &PluginInstance) -> Result<(), AdminError> {
+    if instance.name.is_empty()
+        || instance.name.len() > 128
+        || instance.name.chars().any(char::is_control)
+        || instance.artifact_sha256.len() != 64
+        || !instance
+            .artifact_sha256
+            .bytes()
+            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+        || !instance.configuration.is_object()
+        || serde_json::to_vec(&instance.configuration).map_or(true, |bytes| bytes.len() > 48 * 1024)
+        || instance.secrets.len() > 64
+        || instance.grants.len() > 32
+        || instance.bindings.len() > 64
+    {
+        return Err(AdminError::invalid("插件实例配置不合法或超过大小限制"));
+    }
+    use secrecy::ExposeSecret as _;
+    if instance
+        .secrets
+        .iter()
+        .any(|(key, value)| key.len() > 64 || value.expose_secret().len() > 8192)
+        || instance
+            .secrets
+            .values()
+            .map(|value| value.expose_secret().len())
+            .sum::<usize>()
+            > 48 * 1024
+    {
+        return Err(AdminError::invalid("插件敏感配置超过大小限制"));
+    }
+    if instance.bindings.iter().any(|binding| {
+        binding.contribution.is_empty()
+            || binding.contribution.len() > 128
+            || !binding
+                .contribution
+                .bytes()
+                .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-'))
+            || binding.client_key_ids.len() > 256
+            || binding.account_group_ids.len() > 256
+            || binding.client_key_ids.iter().collect::<BTreeSet<_>>().len()
+                != binding.client_key_ids.len()
+            || binding
+                .account_group_ids
+                .iter()
+                .collect::<BTreeSet<_>>()
+                .len()
+                != binding.account_group_ids.len()
+            || binding
+                .client_key_ids
+                .iter()
+                .any(|id| ClientApiKeyId::new(id.clone()).is_err())
+            || binding
+                .account_group_ids
+                .iter()
+                .any(|id| AccountGroupId::new(id.clone()).is_err())
+            || binding.identity_bindings.len() > 256
+            || binding
+                .identity_bindings
+                .iter()
+                .map(|identity| &identity.principal)
+                .collect::<BTreeSet<_>>()
+                .len()
+                != binding.identity_bindings.len()
+            || binding.identity_bindings.iter().any(|identity| {
+                identity.principal.trim() != identity.principal
+                    || identity.principal.is_empty()
+                    || identity.principal.len() > 256
+                    || identity.principal.chars().any(char::is_control)
+                    || ClientApiKeyId::new(identity.client_key_id.clone()).is_err()
+            })
+    }) {
+        return Err(AdminError::invalid("插件绑定的范围或入口认证身份不合法"));
+    }
+    Ok(())
+}
+
+fn next_revision(revision: Revision) -> Result<Revision, AdminError> {
+    Revision::new(
+        revision
+            .get()
+            .checked_add(1)
+            .ok_or_else(|| AdminError::internal("配置版本已耗尽"))?,
+    )
+    .map_err(|_| AdminError::internal("配置版本不合法"))
+}
diff --git a/backend/crates/gateway-admin/src/use_case/plugins/management.rs b/backend/crates/gateway-admin/src/use_case/plugins/management.rs
new file mode 100644
index 000000000..d49efeded
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/plugins/management.rs
@@ -0,0 +1,145 @@
+use std::sync::Arc;
+
+use gateway_core::runtime::{RuntimeSnapshotHandle, extensions::ExtensionSetReference};
+
+use crate::{
+    model::{
+        AdminError,
+        plugins::{
+            instances::PluginInstance,
+            management::{
+                PluginManagementRequest, PluginManagementResponse, PluginManagementTarget,
+                PluginManagementView,
+            },
+        },
+    },
+    ports::{plugin_management::PluginManagement, plugins::PluginStore},
+};
+
+/// 菜单是发布视图的投影；每次业务动作仍复核持久实例，旧页面不能保留已撤销权限。
+pub struct PluginManagementService {
+    runtime: Arc<dyn PluginManagement>,
+    store: Arc<dyn PluginStore>,
+    published: RuntimeSnapshotHandle,
+}
+
+impl PluginManagementService {
+    /// 页面发起模型请求前复核持久目标与当前发布代次；长响应可重复调用以收敛撤销。
+    pub async fn authorize_models(
+        &self,
+        target: &PluginManagementTarget,
+    ) -> Result<(), AdminError> {
+        let reference = self.authorize(target).await?;
+        self.runtime.authorize_models(&reference, target).await
+    }
+
+    pub async fn start_callback(
+        &self,
+        target: &PluginManagementTarget,
+        command: crate::model::plugins::management::StartPluginManagementCallback,
+        context: &crate::model::auth::AdminRequestContext,
+    ) -> Result<crate::model::plugins::management::PluginManagementCallbackTicket, AdminError> {
+        let reference = self.authorize(target).await?;
+        self.runtime
+            .start_callback(&reference, target, command, context)
+            .await
+    }
+
+    pub async fn callback(
+        &self,
+        target: &PluginManagementTarget,
+        state: &str,
+        request: PluginManagementRequest,
+    ) -> Result<PluginManagementResponse, AdminError> {
+        let reference = self.authorize(target).await?;
+        self.runtime
+            .callback(&reference, target, state, request)
+            .await
+    }
+
+    #[must_use]
+    pub fn new(
+        runtime: Arc<dyn PluginManagement>,
+        store: Arc<dyn PluginStore>,
+        published: RuntimeSnapshotHandle,
+    ) -> Self {
+        Self {
+            runtime,
+            store,
+            published,
+        }
+    }
+
+    pub async fn views(&self) -> Result<Vec<PluginManagementView>, AdminError> {
+        let Some(reference) = self.reference()? else {
+            return Ok(Vec::new());
+        };
+        let mut views = self.runtime.views(&reference).await?;
+        let snapshot = self
+            .store
+            .load_instances()
+            .await
+            .map_err(|_| AdminError::unavailable("无法复核插件页面授权"))?;
+        views.retain(|view| {
+            snapshot
+                .instances
+                .iter()
+                .any(|instance| matches(instance, &view.target))
+        });
+        Ok(views)
+    }
+
+    pub async fn resource(
+        &self,
+        target: &PluginManagementTarget,
+        path: &str,
+        public: bool,
+    ) -> Result<PluginManagementResponse, AdminError> {
+        let reference = self.authorize(target).await?;
+        self.runtime
+            .resource(&reference, target, path, public)
+            .await
+    }
+
+    pub async fn handle(
+        &self,
+        target: &PluginManagementTarget,
+        request: PluginManagementRequest,
+    ) -> Result<PluginManagementResponse, AdminError> {
+        let reference = self.authorize(target).await?;
+        self.runtime.handle(&reference, target, request).await
+    }
+
+    fn reference(&self) -> Result<Option<ExtensionSetReference>, AdminError> {
+        self.published
+            .acquire()
+            .map(|snapshot| snapshot.extensions().cloned())
+            .map_err(|_| AdminError::unavailable("插件发布视图暂不可用"))
+    }
+
+    async fn authorize(
+        &self,
+        target: &PluginManagementTarget,
+    ) -> Result<ExtensionSetReference, AdminError> {
+        let reference = self
+            .reference()?
+            .ok_or_else(|| AdminError::not_found("插件管理扩展不存在"))?;
+        let current = self
+            .store
+            .management_target_is_current(target)
+            .await
+            .map_err(|_| AdminError::unavailable("无法复核插件管理授权"))?;
+        if !current {
+            return Err(AdminError::conflict("插件版本或授权已变化，请刷新页面"));
+        }
+        Ok(reference)
+    }
+}
+
+fn matches(instance: &PluginInstance, target: &PluginManagementTarget) -> bool {
+    instance.enabled
+        && instance.trusted_process
+        && instance.id == target.instance_id
+        && instance.artifact_sha256 == target.artifact_sha256
+        && instance.revision.get() == target.revision
+}
diff --git a/backend/crates/gateway-admin/src/use_case/plugins/mod.rs b/backend/crates/gateway-admin/src/use_case/plugins/mod.rs
new file mode 100644
index 000000000..06ef142d1
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/plugins/mod.rs
@@ -0,0 +1,10 @@
+mod artifacts;
+mod distribution;
+mod instances;
+mod management;
+pub(crate) mod official;
+mod state;
+mod versions;
+
+pub use artifacts::{PluginDistributionPorts, PluginsService};
+pub use management::PluginManagementService;
diff --git a/backend/crates/gateway-admin/src/use_case/plugins/official.rs b/backend/crates/gateway-admin/src/use_case/plugins/official.rs
new file mode 100644
index 000000000..1af450186
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/plugins/official.rs
@@ -0,0 +1,362 @@
+use std::{collections::BTreeSet, path::Path};
+
+use serde::Deserialize;
+
+use crate::{
+    model::{
+        AdminError, AdminErrorKind, MutationActor, MutationContext,
+        plugins::{
+            InspectedPluginArtifact, PluginHostCompatibility, PluginSource,
+            official::{OfficialPluginImport, OfficialPluginReleaseIdentity},
+        },
+    },
+    ports::plugin_release::{
+        OfficialPluginReleaseFiles, OfficialPluginReleaseReadError,
+        OfficialPluginReleaseReadErrorKind,
+    },
+};
+
+use super::PluginsService;
+
+const MANIFEST_SCHEMA_VERSION: u32 = 1;
+const MAXIMUM_MANIFEST_BYTES: usize = 256 * 1024;
+const MAXIMUM_PLUGINS: usize = 64;
+const MAXIMUM_ARTIFACTS_PER_PLUGIN: usize = 8;
+const MAXIMUM_VERSION_BYTES: usize = 128;
+const MAXIMUM_PUBLISHER_BYTES: usize = 256;
+const MAXIMUM_STABILITY_BYTES: usize = 32;
+const MAXIMUM_ARCHIVE_NAME_BYTES: usize = 255;
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct SealedReleaseManifest {
+    schema_version: u32,
+    sealed: bool,
+    gateway_version: String,
+    gateway_git_sha: String,
+    plugin_host: PluginHostCompatibility,
+    plugins: Vec<OfficialPlugin>,
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct OfficialPlugin {
+    id: String,
+    version: String,
+    publisher: String,
+    stability: String,
+    artifacts: Vec<OfficialArtifact>,
+}
+
+#[derive(Clone, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct OfficialArtifact {
+    release_os: String,
+    release_architecture: String,
+    target: String,
+    os: String,
+    architecture: String,
+    archive: String,
+    sha256: String,
+}
+
+struct ValidatedOfficialArtifact {
+    inspected: InspectedPluginArtifact,
+}
+
+#[derive(Clone, Copy)]
+struct Platform {
+    release_os: &'static str,
+    release_architecture: &'static str,
+    target: &'static str,
+    runtime_os: &'static str,
+    runtime_architecture: &'static str,
+}
+
+impl PluginsService {
+    /// 从与宿主发行物同信任边界的封口清单导入官方包。
+    ///
+    /// 所有清单项和包体会先完成静态校验，再进入与上传/远程安装相同的持久化用例。
+    pub async fn import_official_release(
+        &self,
+        files: &dyn OfficialPluginReleaseFiles,
+        identity: &OfficialPluginReleaseIdentity,
+        context: &MutationContext,
+    ) -> Result<OfficialPluginImport, AdminError> {
+        if !matches!(context.actor, MutationActor::System) {
+            return Err(AdminError::new(
+                AdminErrorKind::Forbidden,
+                "官方插件只能由宿主发行导入",
+            ));
+        }
+        let Some(bytes) = files.manifest().await.map_err(map_read_error)? else {
+            return Ok(OfficialPluginImport {
+                artifacts: 0,
+                config_revision: None,
+            });
+        };
+        let ValidatedManifest {
+            gateway_version,
+            plugins,
+            plugins_len,
+        } = validate_manifest(&bytes, identity)?;
+        let platform = current_platform()
+            .ok_or_else(|| AdminError::invalid("当前平台不支持官方插件发行物"))?;
+        let mut validated = Vec::with_capacity(plugins.len());
+
+        // 先完成整份清单的静态检查；持久化故障后的已提交前缀由下次启动幂等补齐。
+        for plugin in plugins {
+            let artifact = select_artifact(&plugin, platform)?;
+            let archive = files
+                .artifact(&artifact.archive)
+                .await
+                .map_err(map_read_error)?;
+            let inspected = self
+                .inspector
+                .inspect(archive, Some(artifact.sha256.clone()))
+                .await?;
+            validate_inspected(&plugin, &artifact, &inspected)?;
+            validated.push(ValidatedOfficialArtifact { inspected });
+        }
+
+        let mut revision = None;
+        for artifact in validated {
+            let mutation = self
+                .persist(
+                    artifact.inspected,
+                    PluginSource::Builtin {
+                        release: gateway_version.clone(),
+                    },
+                    context,
+                )
+                .await?;
+            revision = Some(mutation.config_revision);
+        }
+        Ok(OfficialPluginImport {
+            artifacts: plugins_len,
+            config_revision: revision,
+        })
+    }
+}
+
+struct ValidatedManifest {
+    gateway_version: String,
+    plugins: Vec<OfficialPlugin>,
+    plugins_len: usize,
+}
+
+fn validate_manifest(
+    bytes: &[u8],
+    identity: &OfficialPluginReleaseIdentity,
+) -> Result<ValidatedManifest, AdminError> {
+    let manifest = parse_manifest(bytes)?;
+    if manifest.gateway_version != identity.gateway_version
+        || manifest.gateway_git_sha != identity.gateway_git_sha
+    {
+        return Err(invalid_manifest());
+    }
+    let plugins_len = manifest.plugins.len();
+    Ok(ValidatedManifest {
+        gateway_version: manifest.gateway_version,
+        plugins: manifest.plugins,
+        plugins_len,
+    })
+}
+
+pub(crate) fn update_compatibility(
+    bytes: &[u8],
+    target_version: &str,
+) -> Result<PluginHostCompatibility, AdminError> {
+    let manifest = parse_manifest(bytes)?;
+    (manifest.gateway_version == target_version)
+        .then_some(manifest.plugin_host)
+        .ok_or_else(invalid_manifest)
+}
+
+fn parse_manifest(bytes: &[u8]) -> Result<SealedReleaseManifest, AdminError> {
+    if bytes.len() > MAXIMUM_MANIFEST_BYTES {
+        return Err(invalid_manifest());
+    }
+    let manifest: SealedReleaseManifest =
+        serde_json::from_slice(bytes).map_err(|_| invalid_manifest())?;
+    if manifest.schema_version != MANIFEST_SCHEMA_VERSION
+        || !manifest.sealed
+        || !valid_text(&manifest.gateway_version, MAXIMUM_VERSION_BYTES)
+        || !valid_git_sha(&manifest.gateway_git_sha)
+        || !manifest.plugin_host.is_valid()
+        || manifest.plugins.len() > MAXIMUM_PLUGINS
+    {
+        return Err(invalid_manifest());
+    }
+    let mut plugin_ids = BTreeSet::new();
+    let mut archives = BTreeSet::new();
+    for plugin in &manifest.plugins {
+        if !crate::model::plugins::valid_plugin_id(&plugin.id)
+            || !valid_text(&plugin.version, MAXIMUM_VERSION_BYTES)
+            || !valid_text(&plugin.publisher, MAXIMUM_PUBLISHER_BYTES)
+            || plugin.id.split_once('.').map(|(publisher, _)| publisher)
+                != Some(plugin.publisher.as_str())
+            || !valid_text(&plugin.stability, MAXIMUM_STABILITY_BYTES)
+            || !plugin_ids.insert(plugin.id.as_str())
+            || plugin.artifacts.is_empty()
+            || plugin.artifacts.len() > MAXIMUM_ARTIFACTS_PER_PLUGIN
+        {
+            return Err(invalid_manifest());
+        }
+        let mut platforms = BTreeSet::new();
+        for artifact in &plugin.artifacts {
+            if !valid_artifact(plugin, artifact)
+                || !platforms.insert((
+                    artifact.release_os.as_str(),
+                    artifact.release_architecture.as_str(),
+                ))
+                || !archives.insert(artifact.archive.as_str())
+            {
+                return Err(invalid_manifest());
+            }
+        }
+    }
+    Ok(manifest)
+}
+
+fn valid_artifact(plugin: &OfficialPlugin, artifact: &OfficialArtifact) -> bool {
+    supported_platform(artifact).is_some()
+        && valid_archive_name(&artifact.archive)
+        && valid_sha256(&artifact.sha256)
+        && artifact.archive
+            == format!(
+                "{}-{}-{}-{}.tar.gz",
+                plugin.id, plugin.version, artifact.os, artifact.architecture
+            )
+}
+
+fn supported_platform(artifact: &OfficialArtifact) -> Option<Platform> {
+    SUPPORTED_PLATFORMS.iter().copied().find(|platform| {
+        artifact.release_os == platform.release_os
+            && artifact.release_architecture == platform.release_architecture
+            && artifact.target == platform.target
+            && artifact.os == platform.runtime_os
+            && artifact.architecture == platform.runtime_architecture
+    })
+}
+
+fn select_artifact(
+    plugin: &OfficialPlugin,
+    current: Platform,
+) -> Result<OfficialArtifact, AdminError> {
+    let mut matching = plugin.artifacts.iter().filter(|artifact| {
+        artifact.release_os == current.release_os
+            && artifact.release_architecture == current.release_architecture
+            && artifact.target == current.target
+            && artifact.os == current.runtime_os
+            && artifact.architecture == current.runtime_architecture
+    });
+    let selected = matching.next().cloned().ok_or_else(invalid_manifest)?;
+    if matching.next().is_some() {
+        return Err(invalid_manifest());
+    }
+    Ok(selected)
+}
+
+fn validate_inspected(
+    plugin: &OfficialPlugin,
+    artifact: &OfficialArtifact,
+    inspected: &InspectedPluginArtifact,
+) -> Result<(), AdminError> {
+    if inspected.metadata.plugin_id != plugin.id
+        || inspected.metadata.publisher != plugin.publisher
+        || inspected.metadata.version != plugin.version
+        || inspected.metadata.sha256 != artifact.sha256
+        || !inspected
+            .metadata
+            .platforms
+            .iter()
+            .any(|value| value == &format!("{}-{}", artifact.os, artifact.architecture))
+    {
+        return Err(AdminError::invalid("官方插件包身份与发行清单不一致"));
+    }
+    Ok(())
+}
+
+fn valid_text(value: &str, maximum: usize) -> bool {
+    !value.is_empty()
+        && value.len() <= maximum
+        && value.trim() == value
+        && !value.chars().any(char::is_control)
+}
+
+fn valid_git_sha(value: &str) -> bool {
+    value.len() == 40
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_digit() || matches!(byte, b'a'..=b'f'))
+}
+
+fn valid_sha256(value: &str) -> bool {
+    value.len() == 64
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_digit() || matches!(byte, b'a'..=b'f'))
+}
+
+fn valid_archive_name(value: &str) -> bool {
+    value.len() <= MAXIMUM_ARCHIVE_NAME_BYTES
+        && value.ends_with(".tar.gz")
+        && Path::new(value).file_name().and_then(|name| name.to_str()) == Some(value)
+        && Path::new(value).components().count() == 1
+        && !value.chars().any(char::is_control)
+}
+
+fn map_read_error(error: OfficialPluginReleaseReadError) -> AdminError {
+    match error.kind() {
+        OfficialPluginReleaseReadErrorKind::Invalid
+        | OfficialPluginReleaseReadErrorKind::NotFound => invalid_manifest(),
+        OfficialPluginReleaseReadErrorKind::Unavailable => {
+            AdminError::unavailable("官方插件发行物暂不可读取")
+        }
+    }
+}
+
+fn invalid_manifest() -> AdminError {
+    AdminError::invalid("官方插件发行清单不合法或不属于当前宿主发行物")
+}
+
+fn current_platform() -> Option<Platform> {
+    SUPPORTED_PLATFORMS.iter().copied().find(|platform| {
+        platform.runtime_os == std::env::consts::OS
+            && platform.runtime_architecture == std::env::consts::ARCH
+            && target_environment_matches(platform.target)
+    })
+}
+
+fn target_environment_matches(target: &str) -> bool {
+    match target {
+        "x86_64-unknown-linux-gnu" | "aarch64-unknown-linux-gnu" => cfg!(target_env = "gnu"),
+        "aarch64-apple-darwin" => cfg!(target_os = "macos"),
+        _ => false,
+    }
+}
+
+const SUPPORTED_PLATFORMS: &[Platform] = &[
+    Platform {
+        release_os: "linux",
+        release_architecture: "amd64",
+        target: "x86_64-unknown-linux-gnu",
+        runtime_os: "linux",
+        runtime_architecture: "x86_64",
+    },
+    Platform {
+        release_os: "linux",
+        release_architecture: "arm64",
+        target: "aarch64-unknown-linux-gnu",
+        runtime_os: "linux",
+        runtime_architecture: "aarch64",
+    },
+    Platform {
+        release_os: "darwin",
+        release_architecture: "arm64",
+        target: "aarch64-apple-darwin",
+        runtime_os: "macos",
+        runtime_architecture: "aarch64",
+    },
+];
diff --git a/backend/crates/gateway-admin/src/use_case/plugins/state.rs b/backend/crates/gateway-admin/src/use_case/plugins/state.rs
new file mode 100644
index 000000000..37672f332
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/plugins/state.rs
@@ -0,0 +1,73 @@
+use std::sync::Arc;
+
+use crate::{
+    model::{
+        AdminError, Revision,
+        plugins::state::{PluginStateConfiguration, PluginStateTransition},
+    },
+    ports::plugins::{PluginStateStore, PluginStateStoreError, PluginStateStoreErrorKind},
+};
+
+pub(super) struct PluginStateService {
+    store: Arc<dyn PluginStateStore>,
+}
+
+impl PluginStateService {
+    #[must_use]
+    pub(super) fn new(store: Arc<dyn PluginStateStore>) -> Self {
+        Self { store }
+    }
+
+    pub(super) async fn transition_required(
+        &self,
+        instance_id: &str,
+        target: &PluginStateConfiguration,
+    ) -> Result<bool, AdminError> {
+        self.store
+            .transition_required(instance_id, target)
+            .await
+            .map_err(map_state_error)
+    }
+
+    pub(super) async fn begin_transition(
+        &self,
+        instance_id: &str,
+        expected_instance_revision: Revision,
+        artifact_sha256: &str,
+        target: PluginStateConfiguration,
+    ) -> Result<PluginStateTransition, AdminError> {
+        self.store
+            .begin_transition(
+                instance_id,
+                expected_instance_revision,
+                artifact_sha256,
+                target,
+            )
+            .await
+            .map_err(map_state_error)
+    }
+
+    pub(super) async fn abort_transition(&self, transition_id: &str) {
+        if let Err(error) = self.store.abort_transition(transition_id).await {
+            tracing::warn!(
+                error_kind = ?error.kind(),
+                "failed to discard plugin state staging generation"
+            );
+        }
+    }
+}
+
+fn map_state_error(error: PluginStateStoreError) -> AdminError {
+    match error.kind() {
+        PluginStateStoreErrorKind::Invalid => AdminError::invalid("插件状态声明不合法"),
+        PluginStateStoreErrorKind::NotFound => AdminError::not_found("插件状态实例不存在"),
+        PluginStateStoreErrorKind::Conflict => {
+            AdminError::conflict("插件状态版本不兼容或已发生并发变更")
+        }
+        PluginStateStoreErrorKind::Quota => AdminError::conflict("插件状态迁移超过声明配额"),
+        PluginStateStoreErrorKind::PermissionDenied => {
+            AdminError::conflict("插件状态 fence 已失效")
+        }
+        PluginStateStoreErrorKind::Unavailable => AdminError::unavailable("插件状态存储暂不可用"),
+    }
+}
diff --git a/backend/crates/gateway-admin/src/use_case/plugins/versions.rs b/backend/crates/gateway-admin/src/use_case/plugins/versions.rs
new file mode 100644
index 000000000..28be61efa
--- /dev/null
+++ b/backend/crates/gateway-admin/src/use_case/plugins/versions.rs
@@ -0,0 +1,318 @@
+use super::{
+    PluginsService,
+    artifacts::{configuration_defaults, default_bindings},
+};
+use crate::{
+    model::{
+        AdminError, MutationContext,
+        plugins::{
+            PluginArtifactMetadata,
+            instances::{
+                ConfigurePluginInstance, PluginInstance, PluginInstanceMutation,
+                PluginRollbackPlan, PluginRollbackTarget, PluginVersionConfiguration,
+                PluginVersionPlan, RollbackPluginInstance,
+            },
+        },
+    },
+    use_case::map_store_error,
+};
+
+impl PluginsService {
+    pub async fn rollback_instance(
+        &self,
+        id: &str,
+        input: RollbackPluginInstance,
+        context: &MutationContext,
+    ) -> Result<PluginInstanceMutation, AdminError> {
+        let snapshot = self
+            .store
+            .load_instances()
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        let existing = snapshot
+            .instances
+            .iter()
+            .find(|instance| instance.id == id)
+            .cloned()
+            .ok_or_else(|| AdminError::not_found("插件实例不存在"))?;
+        if existing.revision.get() != input.expected_revision {
+            return Err(AdminError::conflict("插件实例已变更，请重新确认回滚目标"));
+        }
+        let artifacts = self.list().await?;
+        let current = artifacts
+            .iter()
+            .find(|artifact| artifact.metadata.sha256 == existing.artifact_sha256)
+            .ok_or_else(|| AdminError::not_found("当前插件制品不存在"))?;
+        let target = artifacts
+            .iter()
+            .find(|artifact| artifact.metadata.sha256 == input.artifact_sha256)
+            .ok_or_else(|| AdminError::not_found("回滚目标制品尚未安装"))?;
+        if rollback_version(&current.metadata, &target.metadata)?.is_none() {
+            return Err(AdminError::invalid("回滚目标必须是同一插件的较早版本"));
+        }
+        let saved = self
+            .store
+            .load_version_configuration(id, &input.artifact_sha256)
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?
+            .ok_or_else(|| {
+                AdminError::invalid("该版本没有可恢复的配置，请通过版本切换检查当前设置")
+            })?;
+        let configuration = ConfigurePluginInstance {
+            creation_id: None,
+            expected_revision: None,
+            replace_instances: Vec::new(),
+            name: existing.name.clone(),
+            artifact_sha256: input.artifact_sha256,
+            enabled: existing.enabled,
+            configuration: saved.configuration,
+            secrets: Some(saved.secrets),
+            bindings: saved.bindings,
+        };
+        // 沿用同一份快照的 CAS 和状态迁移流程，不能在检查目标后重新读取并覆盖并发配置。
+        self.configure_from_snapshot(snapshot, Some(existing), configuration, context)
+            .await
+    }
+
+    pub async fn rollback_plan(&self, id: &str) -> Result<PluginRollbackPlan, AdminError> {
+        let snapshot = self
+            .store
+            .load_instances()
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        let instance = snapshot
+            .instances
+            .iter()
+            .find(|instance| instance.id == id)
+            .ok_or_else(|| AdminError::not_found("插件实例不存在"))?;
+        let artifacts = self.list().await?;
+        let current = artifacts
+            .iter()
+            .find(|artifact| artifact.metadata.sha256 == instance.artifact_sha256)
+            .ok_or_else(|| AdminError::not_found("当前插件制品不存在"))?;
+        let saved_versions = self
+            .store
+            .configuration_versions(id)
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        let mut targets = Vec::new();
+        for artifact in artifacts.iter().filter(|artifact| {
+            artifact.accepted_at.is_some() && saved_versions.contains(&artifact.metadata.sha256)
+        }) {
+            if let Some(version) = rollback_version(&current.metadata, &artifact.metadata)? {
+                targets.push((
+                    version,
+                    PluginRollbackTarget {
+                        artifact_sha256: artifact.metadata.sha256.clone(),
+                        version: artifact.metadata.version.clone(),
+                        platforms: artifact.metadata.platforms.clone(),
+                    },
+                ));
+            }
+        }
+        targets.sort_by(|(left, left_target), (right, right_target)| {
+            right.cmp_precedence(left).then_with(|| {
+                left_target
+                    .artifact_sha256
+                    .cmp(&right_target.artifact_sha256)
+            })
+        });
+        Ok(PluginRollbackPlan {
+            instance_revision: instance.revision.get(),
+            current_version: current.metadata.version.clone(),
+            targets: targets.into_iter().map(|(_, target)| target).collect(),
+        })
+    }
+
+    pub async fn version_plan(
+        &self,
+        id: &str,
+        digest: &str,
+    ) -> Result<PluginVersionPlan, AdminError> {
+        let snapshot = self
+            .store
+            .load_instances()
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        let instance = snapshot
+            .instances
+            .iter()
+            .find(|instance| instance.id == id)
+            .ok_or_else(|| AdminError::not_found("插件实例不存在"))?;
+        let (configuration, restored) = self.version_configuration(instance, digest).await?;
+        Ok(PluginVersionPlan {
+            instance_revision: instance.revision.get(),
+            artifact_sha256: digest.to_owned(),
+            configuration: configuration.configuration,
+            secret_fields: configuration.secrets.into_keys().collect(),
+            bindings: configuration.bindings,
+            restored,
+        })
+    }
+
+    pub async fn switch_instance_version(
+        &self,
+        id: &str,
+        input: RollbackPluginInstance,
+        context: &MutationContext,
+    ) -> Result<PluginInstanceMutation, AdminError> {
+        let snapshot = self
+            .store
+            .load_instances()
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        let existing = snapshot
+            .instances
+            .iter()
+            .find(|instance| instance.id == id)
+            .cloned()
+            .ok_or_else(|| AdminError::not_found("插件实例不存在"))?;
+        if existing.revision.get() != input.expected_revision {
+            return Err(AdminError::conflict("插件设置已变更，请刷新后重试"));
+        }
+        if existing.artifact_sha256 == input.artifact_sha256 {
+            return Err(AdminError::invalid("已在使用此版本"));
+        }
+        let (configuration, _) = self
+            .version_configuration(&existing, &input.artifact_sha256)
+            .await?;
+        let request = ConfigurePluginInstance {
+            creation_id: None,
+            expected_revision: Some(existing.revision.get()),
+            replace_instances: Vec::new(),
+            name: existing.name.clone(),
+            artifact_sha256: input.artifact_sha256,
+            enabled: existing.enabled,
+            configuration: configuration.configuration,
+            secrets: Some(configuration.secrets),
+            bindings: configuration.bindings,
+        };
+        // 同一次读取的 CAS 覆盖草稿计算、准备与提交，不能覆盖并发设置。
+        self.configure_from_snapshot(snapshot, Some(existing), request, context)
+            .await
+    }
+
+    async fn version_configuration(
+        &self,
+        instance: &PluginInstance,
+        digest: &str,
+    ) -> Result<(PluginVersionConfiguration, bool), AdminError> {
+        let artifacts = self
+            .store
+            .list_artifacts()
+            .await
+            .map_err(|error| map_store_error(error, "plugin"))?;
+        let current = artifacts
+            .iter()
+            .find(|artifact| artifact.metadata.sha256 == instance.artifact_sha256)
+            .ok_or_else(|| AdminError::not_found("当前插件版本不存在"))?;
+        let target = artifacts
+            .iter()
+            .find(|artifact| artifact.metadata.sha256 == digest && artifact.accepted_at.is_some())
+            .ok_or_else(|| AdminError::not_found("目标插件版本尚未安装"))?;
+        if current.metadata.plugin_id != target.metadata.plugin_id {
+            return Err(AdminError::invalid("只能切换同一插件的版本"));
+        }
+        if digest != instance.artifact_sha256
+            && let Some(saved) = self
+                .store
+                .load_version_configuration(&instance.id, digest)
+                .await
+                .map_err(|error| map_store_error(error, "plugin"))?
+        {
+            return Ok((saved, true));
+        }
+        let mut configuration = instance.configuration.clone();
+        // 只补充缺失的默认值，保留显式值及未知字段，让不兼容项由校验反馈给用户。
+        merge_missing_defaults(&mut configuration, configuration_defaults(&target.metadata));
+        Ok((
+            PluginVersionConfiguration {
+                configuration,
+                secrets: instance.secrets.clone(),
+                bindings: version_bindings(instance, &current.metadata, &target.metadata),
+            },
+            false,
+        ))
+    }
+}
+
+fn version_bindings(
+    instance: &PluginInstance,
+    current: &PluginArtifactMetadata,
+    target: &PluginArtifactMetadata,
+) -> Vec<crate::model::plugins::instances::PluginCapabilityBinding> {
+    let mut bindings = default_bindings(target);
+    // 已关闭的既有能力继续关闭，新声明能力才采用包默认值。
+    bindings.retain(|binding| {
+        let capability = target
+            .contributes
+            .iter()
+            .find(|(_, contribution)| contribution.id == binding.contribution)
+            .map(|(capability, _)| capability);
+        let previous = capability.and_then(|capability| current.contributes.get(capability));
+        previous.is_none_or(|contribution| {
+            !contribution.stages.contains(&binding.stage)
+                || instance
+                    .bindings
+                    .iter()
+                    .any(|old| old.contribution == contribution.id && old.stage == binding.stage)
+        })
+    });
+    for previous in &instance.bindings {
+        let Some((capability, _)) = current
+            .contributes
+            .iter()
+            .find(|(_, contribution)| contribution.id == previous.contribution)
+        else {
+            continue;
+        };
+        let Some(contribution) = target
+            .contributes
+            .get(capability)
+            .filter(|contribution| contribution.stages.contains(&previous.stage))
+        else {
+            continue;
+        };
+        let mut binding = previous.clone();
+        binding.contribution.clone_from(&contribution.id);
+        if let Some(default) = bindings.iter_mut().find(|default| {
+            default.contribution == binding.contribution && default.stage == binding.stage
+        }) {
+            *default = binding;
+        } else {
+            bindings.push(binding);
+        }
+    }
+    bindings
+}
+
+fn rollback_version(
+    current: &PluginArtifactMetadata,
+    target: &PluginArtifactMetadata,
+) -> Result<Option<semver::Version>, AdminError> {
+    if current.plugin_id != target.plugin_id {
+        return Ok(None);
+    }
+    let current_version = semver::Version::parse(&current.version)
+        .map_err(|_| AdminError::invalid("当前插件版本无效"))?;
+    let target_version = semver::Version::parse(&target.version)
+        .map_err(|_| AdminError::invalid("回滚目标版本无效"))?;
+    Ok(target_version
+        .cmp_precedence(&current_version)
+        .is_lt()
+        .then_some(target_version))
+}
+
+fn merge_missing_defaults(current: &mut serde_json::Value, defaults: serde_json::Value) {
+    let (Some(current), serde_json::Value::Object(defaults)) = (current.as_object_mut(), defaults)
+    else {
+        return;
+    };
+    for (key, default) in defaults {
+        if let Some(value) = current.get_mut(&key) {
+            merge_missing_defaults(value, default);
+        } else {
+            current.insert(key, default);
+        }
+    }
+}
diff --git a/backend/crates/gateway-admin/src/use_case/settings.rs b/backend/crates/gateway-admin/src/use_case/settings.rs
index c0cf52588..a670d1671 100644
--- a/backend/crates/gateway-admin/src/use_case/settings.rs
+++ b/backend/crates/gateway-admin/src/use_case/settings.rs
@@ -37,6 +37,11 @@ pub trait SettingsService: Send + Sync {
         context: &MutationContext,
         command: crate::model::pricing::UpdatePricing,
     ) -> Result<(), AdminError>;
+    async fn client_profile_providers(
+        &self,
+    ) -> Result<Vec<gateway_core::routing::ProviderKind>, AdminError> {
+        Ok(Vec::new())
+    }
     async fn client_profile_options(
         &self,
         _provider: &str,
@@ -78,7 +83,7 @@ impl DefaultSettingsService {
     fn profile_provider(
         &self,
         provider: &str,
-    ) -> Result<Arc<dyn crate::ports::provider::ProviderAdmin>, AdminError> {
+    ) -> Result<crate::ports::provider_extensions::ProviderAdminHandle, AdminError> {
         let kind = gateway_core::routing::ProviderKind::new(provider)
             .map_err(|_| AdminError::invalid("Provider 不合法"))?;
         self.providers
@@ -129,6 +134,17 @@ impl SettingsService for DefaultSettingsService {
         {
             return Err(AdminError::invalid("请选择 1 至 10000 个模型"));
         }
+        let providers = self
+            .providers
+            .pricing_catalog()
+            .map_err(|error| super::map_provider_error(error, "provider pricing"))?;
+        if command
+            .models
+            .keys()
+            .any(|provider| !providers.contains_key(provider))
+        {
+            return Err(AdminError::invalid("Provider 不支持价目管理"));
+        }
         let mut current = self.pricing_source.fetch().await?;
         if current != command.preview {
             return Err(AdminError::invalid(
@@ -174,7 +190,10 @@ impl SettingsService for DefaultSettingsService {
             .await
             .map_err(|error| map_store_error(error, "model pricing"))?;
         Ok(crate::model::pricing::PricingCatalog {
-            defaults: self.providers.pricing_catalog(),
+            defaults: self
+                .providers
+                .pricing_catalog()
+                .map_err(|error| super::map_provider_error(error, "provider pricing"))?,
             overrides: stored.overrides,
             synced: stored.synced,
             synced_at: stored.synced_at,
@@ -258,12 +277,20 @@ impl SettingsService for DefaultSettingsService {
         publish_committed(self.snapshot.as_ref(), revision).await
     }
 
+    async fn client_profile_providers(
+        &self,
+    ) -> Result<Vec<gateway_core::routing::ProviderKind>, AdminError> {
+        self.providers
+            .client_profile_providers()
+            .map_err(|error| super::map_provider_error(error, "client profile"))
+    }
+
     async fn client_profile_options(
         &self,
         provider: &str,
     ) -> Result<gateway_core::account::OpaqueProviderData, AdminError> {
-        let mut options = self
-            .profile_provider(provider)?
+        let profile_provider = self.profile_provider(provider)?;
+        let mut options = profile_provider
             .client_profile_options()
             .map_err(|error| super::map_provider_error(error, "client profile"))?
             .into_inner();
@@ -272,6 +299,7 @@ impl SettingsService for DefaultSettingsService {
             .await?
             .client_profile(provider)
             .cloned()
+            .or_else(|| profile_provider.default_client_profile())
             .ok_or_else(|| AdminError::internal("通用客户端身份尚未初始化"))?;
         options.insert(
             "globalConfiguration".to_owned(),
@@ -295,6 +323,7 @@ impl SettingsService for DefaultSettingsService {
                 .await?
                 .client_profile(provider)
                 .cloned()
+                .or_else(|| profile_provider.default_client_profile())
                 .ok_or_else(|| AdminError::internal("通用客户端身份尚未初始化"))?;
             (&global, "global")
         };
@@ -316,16 +345,41 @@ impl SettingsService for DefaultSettingsService {
     async fn replace(
         &self,
         context: &MutationContext,
-        command: ReplaceRuntimeSettings,
+        mut command: ReplaceRuntimeSettings,
     ) -> Result<RuntimeSettings, AdminError> {
         validate_settings(&command)?;
-        for (provider, profile) in [
-            ("openai", &command.openai_client_profile),
-            ("xai", &command.xai_client_profile),
-        ] {
-            if let Some(profile) = profile {
-                self.profile_provider(provider)?
-                    .preview_client_profile(profile)
+        if command
+            .request_profile_updates
+            .values()
+            .any(Option::is_some)
+        {
+            let current = self
+                .store
+                .load_runtime_settings()
+                .await
+                .map_err(|error| map_store_error(error, "runtime settings"))?;
+            command.request_profile_updates.retain(|provider, update| {
+                !update
+                    .as_ref()
+                    .is_some_and(|profile| current.request_profiles.get(provider) == Some(profile))
+            });
+        }
+        if command
+            .request_profile_updates
+            .values()
+            .any(Option::is_some)
+        {
+            let providers = self
+                .providers
+                .freeze()
+                .map_err(|error| super::map_provider_error(error, "client profile"))?;
+            for (provider, profile) in &command.request_profile_updates {
+                let Some(profile) = profile else {
+                    continue;
+                };
+                providers
+                    .require(provider)
+                    .and_then(|provider| provider.preview_client_profile(profile))
                     .map_err(|error| super::map_provider_error(error, "client profile"))?;
             }
         }
diff --git a/backend/crates/gateway-admin/src/use_case/system.rs b/backend/crates/gateway-admin/src/use_case/system.rs
index 0fcc4c69d..27dffce97 100644
--- a/backend/crates/gateway-admin/src/use_case/system.rs
+++ b/backend/crates/gateway-admin/src/use_case/system.rs
@@ -11,6 +11,7 @@ use crate::{
     },
     ports::system::{
         SystemOperationError, SystemOperationErrorKind, SystemOperations, SystemUpdateEventStream,
+        SystemUpdatePreflight,
     },
 };
 
@@ -32,12 +33,19 @@ pub trait SystemService: Send + Sync {
 /// 保持 Host 能力窄边界的默认系统用例。
 pub(crate) struct DefaultSystemService {
     operations: Arc<dyn SystemOperations>,
+    preflight: Arc<dyn SystemUpdatePreflight>,
 }
 
 impl DefaultSystemService {
     #[must_use]
-    pub(crate) const fn new(operations: Arc<dyn SystemOperations>) -> Self {
-        Self { operations }
+    pub(crate) fn new(
+        operations: Arc<dyn SystemOperations>,
+        preflight: Arc<dyn SystemUpdatePreflight>,
+    ) -> Self {
+        Self {
+            operations,
+            preflight,
+        }
     }
 }
 
@@ -66,7 +74,7 @@ impl SystemService for DefaultSystemService {
             .map(|version| version.trim().to_owned())
             .filter(|version| !version.is_empty());
         self.operations
-            .perform_update(target_version)
+            .perform_update(target_version, Arc::clone(&self.preflight))
             .await
             .map_err(map_system_error)
     }
@@ -79,7 +87,10 @@ impl SystemService for DefaultSystemService {
     }
 
     async fn rollback(&self) -> Result<SystemOperationAccepted, AdminError> {
-        self.operations.rollback().await.map_err(map_system_error)
+        self.operations
+            .rollback(Arc::clone(&self.preflight))
+            .await
+            .map_err(map_system_error)
     }
 
     async fn restart(&self) -> Result<SystemOperationAccepted, AdminError> {
diff --git a/backend/crates/gateway-admin/src/use_case/xai.rs b/backend/crates/gateway-admin/src/use_case/xai.rs
deleted file mode 100644
index babfae0cf..000000000
--- a/backend/crates/gateway-admin/src/use_case/xai.rs
+++ /dev/null
@@ -1,195 +0,0 @@
-//! xAI 管理资源的中立 ProviderAdmin 委托。
-
-use std::sync::Arc;
-
-use async_trait::async_trait;
-use gateway_core::runtime::SnapshotControl;
-
-use crate::{
-    model::{
-        AdminError,
-        provider_credentials::{
-            AuthorizationStarted, CompleteAuthorization, CredentialDeletion,
-            CredentialDeletionResult, CredentialImportCommit, CredentialImportResult,
-            CredentialMutationResult, ImportCredentials, PrepareCredentialImport,
-            StartAuthorization,
-        },
-    },
-    ports::{provider::ProviderAdmin, store::AccountStore},
-};
-
-use super::{
-    commit_authorization, delete_credentials, map_provider_error, map_store_error,
-    pending_authorization, publish_committed, publish_credentials_and_observe_quota,
-    validate_authorization_commit, validate_prepared_import,
-};
-
-/// xAI 固定管理路由消费的服务。
-#[async_trait]
-pub trait XaiService: Send + Sync {
-    async fn import_document(
-        &self,
-        command: ImportCredentials,
-    ) -> Result<CredentialImportResult, AdminError>;
-    async fn start_authorization(
-        &self,
-        command: StartAuthorization,
-    ) -> Result<AuthorizationStarted, AdminError>;
-    async fn complete_authorization(
-        &self,
-        command: CompleteAuthorization,
-    ) -> Result<CredentialMutationResult, AdminError>;
-    async fn delete(
-        &self,
-        command: CredentialDeletion,
-    ) -> Result<CredentialDeletionResult, AdminError>;
-}
-
-pub(crate) struct DefaultXaiService {
-    provider: Arc<dyn ProviderAdmin>,
-    accounts: Arc<dyn AccountStore>,
-    proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
-    snapshot: Arc<dyn SnapshotControl>,
-}
-
-impl DefaultXaiService {
-    #[must_use]
-    pub(crate) fn new(
-        provider: Arc<dyn ProviderAdmin>,
-        accounts: Arc<dyn AccountStore>,
-        proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
-        snapshot: Arc<dyn SnapshotControl>,
-    ) -> Self {
-        Self {
-            provider,
-            accounts,
-            proxies,
-            snapshot,
-        }
-    }
-}
-
-#[async_trait]
-impl XaiService for DefaultXaiService {
-    async fn import_document(
-        &self,
-        command: ImportCredentials,
-    ) -> Result<CredentialImportResult, AdminError> {
-        let context = command.context;
-        let proxy_reservation = super::import_proxy_binding(
-            self.proxies.as_ref(),
-            command.outbound_proxy_id.as_deref(),
-        )
-        .await?;
-        let outbound_proxy = proxy_reservation
-            .as_ref()
-            .map(|reservation| reservation.binding.clone());
-        let prepared = self
-            .provider
-            .prepare_import(PrepareCredentialImport {
-                default_outbound_proxy: outbound_proxy
-                    .as_ref()
-                    .map(|binding| binding.proxy.clone()),
-                document: command.document,
-            })
-            .await
-            .map_err(|error| map_provider_error(error, "xAI credential import"))?;
-        validate_prepared_import(
-            self.provider.provider_kind(),
-            &prepared,
-            "xAI credential import",
-        )?;
-        let result = self
-            .accounts
-            .commit_credential_import(
-                CredentialImportCommit {
-                    outbound_proxy,
-                    prepared,
-                    settings: command.settings,
-                },
-                &context,
-            )
-            .await
-            .map_err(|error| map_store_error(error, "xAI credential import"))?;
-        drop(proxy_reservation);
-        publish_credentials_and_observe_quota(
-            &self.provider,
-            self.snapshot.as_ref(),
-            result.config_revision,
-            &result.credential_ids,
-            &context.request_id,
-        )
-        .await?;
-        Ok(result)
-    }
-
-    async fn start_authorization(
-        &self,
-        command: StartAuthorization,
-    ) -> Result<AuthorizationStarted, AdminError> {
-        let pending = pending_authorization(
-            self.accounts.as_ref(),
-            self.proxies.as_ref(),
-            self.provider.provider_kind(),
-            &command,
-            "xAI credential",
-        )
-        .await?;
-        self.provider
-            .start_authorization(pending)
-            .await
-            .map_err(|error| map_provider_error(error, "xAI authorization"))
-    }
-
-    async fn complete_authorization(
-        &self,
-        mut command: CompleteAuthorization,
-    ) -> Result<CredentialMutationResult, AdminError> {
-        let context = command.context.clone();
-        let settings = command.settings.take();
-        let prepared = self
-            .provider
-            .complete_authorization(command)
-            .await
-            .map_err(|error| map_provider_error(error, "xAI authorization"))?;
-        let prepared = validate_authorization_commit(
-            self.provider.provider_kind(),
-            &context,
-            prepared,
-            "xAI authorization",
-        )
-        .await?;
-        let result = commit_authorization(
-            self.accounts.as_ref(),
-            prepared,
-            settings,
-            &context,
-            "xAI authorization",
-        )
-        .await?;
-        publish_credentials_and_observe_quota(
-            &self.provider,
-            self.snapshot.as_ref(),
-            result.config_revision,
-            std::slice::from_ref(&result.account_id),
-            &context.request_id,
-        )
-        .await?;
-        Ok(result)
-    }
-
-    async fn delete(
-        &self,
-        command: CredentialDeletion,
-    ) -> Result<CredentialDeletionResult, AdminError> {
-        let result = delete_credentials(
-            self.accounts.as_ref(),
-            self.provider.as_ref(),
-            command,
-            "xAI credential",
-        )
-        .await?;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        Ok(result)
-    }
-}
diff --git a/backend/crates/gateway-admin/tests/model/quota_forecast.rs b/backend/crates/gateway-admin/tests/model/quota_forecast.rs
index 3740fcb87..32207ee98 100644
--- a/backend/crates/gateway-admin/tests/model/quota_forecast.rs
+++ b/backend/crates/gateway-admin/tests/model/quota_forecast.rs
@@ -141,6 +141,22 @@ fn corresponding_actual_window_takes_priority_and_retains_its_duration() {
     assert_eq!(week.estimated_tokens, Some(1_129));
 }
 
+#[test]
+fn source_selection_keeps_provider_order_with_the_maximum_window_count() {
+    let windows = (0..64)
+        .map(|index| {
+            if index % 2 == 0 {
+                window(&format!("week-{index}"), 7)
+            } else {
+                window(&format!("month-{index}"), 30)
+            }
+        })
+        .collect();
+    let [week, month] = forecast(&quota(windows));
+    assert_eq!(week.source.unwrap().label, "week-0");
+    assert_eq!(month.source.unwrap().label, "month-1");
+}
+
 #[test]
 fn short_or_model_specific_windows_are_not_account_capacity() {
     let mut model = window("model", 7);
diff --git a/backend/crates/gateway-admin/tests/use_case/accounts.rs b/backend/crates/gateway-admin/tests/use_case/accounts.rs
index 55cde2459..5207e33f4 100644
--- a/backend/crates/gateway-admin/tests/use_case/accounts.rs
+++ b/backend/crates/gateway-admin/tests/use_case/accounts.rs
@@ -29,20 +29,21 @@ use gateway_admin::{
             BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
         },
         observability::TimeRange,
+        provider_capabilities::ProviderCredentialCapabilities,
         provider_credentials::{
             AuthorizationCommit, AuthorizationCommitGuard, AuthorizationCredentialCommit,
             AuthorizationMutationTarget, AuthorizationStarted, CompleteAuthorization,
             ConsumeProviderResetCredit, CredentialCommitGuard, CredentialDetails,
             CredentialImportCommit, CredentialImportResult, CredentialMutationResult,
-            CredentialRotationCommit, PendingAuthorizationMutation, PrepareCredentialImport,
-            PrepareCredentialRefresh, PrepareCredentialRotation, PreparedAuthorizationCommit,
-            PreparedAuthorizationCredential, PreparedCredentialCreate, PreparedCredentialImport,
-            PreparedCredentialRotation, PreparedCredentialRotationFacts, ProviderDocument,
-            ProviderExport, ProviderExportCredentialInput, ProviderModels,
-            ProviderProfileActivityInsights, ProviderProfileStatistics,
-            ProviderProfileStatisticsSummary, ProviderQuota, ProviderQuotaRequest,
-            ProviderQuotaWindow, ProviderResetCreditResult, ProviderSubscription,
-            QuotaLocalUsageAttribution,
+            CredentialRotationCommit, PendingAuthorizationMutation, PluginAccountSaveReason,
+            PrepareCredentialImport, PrepareCredentialRefresh, PrepareCredentialRotation,
+            PreparedAuthorizationCommit, PreparedAuthorizationCredential, PreparedCredentialCreate,
+            PreparedCredentialImport, PreparedCredentialRotation, PreparedCredentialRotationFacts,
+            PreparedPluginAccountSave, ProviderDocument, ProviderExport,
+            ProviderExportCredentialInput, ProviderModels, ProviderProfileActivityInsights,
+            ProviderProfileStatistics, ProviderProfileStatisticsSummary, ProviderQuota,
+            ProviderQuotaRequest, ProviderQuotaWindow, ProviderResetCreditResult,
+            ProviderSubscription, QuotaLocalUsageAttribution,
         },
         quota_forecast_sampling::{QuotaForecastHistory, QuotaForecastUsage},
         settings::{
@@ -65,12 +66,20 @@ pub(super) type EventLog = Arc<Mutex<Vec<&'static str>>>;
 
 pub(super) struct FakeProviderAdmin {
     kind: ProviderKind,
+    credential_capabilities: Mutex<ProviderCredentialCapabilities>,
+    capabilities: Mutex<gateway_admin::model::provider_capabilities::ProviderAccountCapabilities>,
     events: EventLog,
     failure: Mutex<Option<ProviderAdminError>>,
     import_gate: Mutex<Option<Arc<tokio::sync::Semaphore>>>,
     quota_failure: Mutex<Option<ProviderAdminErrorKind>>,
     pending: Arc<Mutex<Option<PendingAuthorizationMutation>>>,
     retry_authorization_after_abort: Mutex<bool>,
+    authorization_accounts: Mutex<Option<Vec<PreparedCredentialCreate>>>,
+    authorization_polls: Mutex<
+        std::collections::VecDeque<
+            gateway_admin::model::provider_credentials::PreparedAuthorizationPoll,
+        >,
+    >,
     export_inputs: Mutex<Vec<ProviderExportCredentialInput>>,
     import_account_ids: Mutex<Vec<String>>,
     quota_requests: Mutex<Vec<ProviderQuotaRequest>>,
@@ -86,15 +95,33 @@ pub(super) struct FakeProviderAdmin {
 }
 
 impl FakeProviderAdmin {
+    pub(super) fn set_authorization_accounts(&self, accounts: Vec<PreparedCredentialCreate>) {
+        *self.authorization_accounts.lock().unwrap() = Some(accounts);
+    }
+
+    pub(super) fn queue_authorization_poll(
+        &self,
+        result: gateway_admin::model::provider_credentials::PreparedAuthorizationPoll,
+    ) {
+        self.authorization_polls.lock().unwrap().push_back(result);
+    }
+
     pub(super) fn new(kind: &str, events: EventLog) -> Arc<Self> {
         Arc::new(Self {
             kind: ProviderKind::new(kind).expect("provider kind"),
+            credential_capabilities: Mutex::new(ProviderCredentialCapabilities {
+                export: true,
+                ..Default::default()
+            }),
+            capabilities: Mutex::default(),
             events,
             failure: Mutex::new(None),
             import_gate: Mutex::new(None),
             quota_failure: Mutex::new(None),
             pending: Arc::new(Mutex::new(None)),
             retry_authorization_after_abort: Mutex::new(false),
+            authorization_accounts: Mutex::new(None),
+            authorization_polls: Mutex::default(),
             export_inputs: Mutex::new(Vec::new()),
             import_account_ids: Mutex::new(vec!["acct_prepared".to_owned()]),
             quota_requests: Mutex::new(Vec::new()),
@@ -258,6 +285,17 @@ impl FakeProviderAdmin {
 
 #[async_trait]
 impl ProviderAdmin for FakeProviderAdmin {
+    fn credential_capabilities(&self) -> ProviderCredentialCapabilities {
+        self.credential_capabilities.lock().unwrap().clone()
+    }
+
+    fn account_capabilities(
+        &self,
+        _account_id: &ProviderAccountId,
+        _authentication_kind: &str,
+    ) -> gateway_admin::model::provider_capabilities::ProviderAccountCapabilities {
+        *self.capabilities.lock().unwrap()
+    }
     fn provider_kind(&self) -> &ProviderKind {
         &self.kind
     }
@@ -300,7 +338,7 @@ impl ProviderAdmin for FakeProviderAdmin {
         self.record("provider.account_facts_changed");
     }
 
-    fn connection_test_operation(
+    async fn connection_test_operation(
         &self,
         model: &gateway_core::routing::UpstreamModelId,
         input: &str,
@@ -364,8 +402,9 @@ impl ProviderAdmin for FakeProviderAdmin {
 
     async fn start_authorization(
         &self,
-        pending: PendingAuthorizationMutation,
+        command: gateway_admin::model::provider_credentials::PrepareAuthorization,
     ) -> Result<AuthorizationStarted, ProviderAdminError> {
+        let pending = command.pending;
         self.record("provider.start_authorization");
         self.require_available()?;
         *self.pending.lock().expect("pending authorization") = Some(pending);
@@ -398,12 +437,20 @@ impl ProviderAdmin for FakeProviderAdmin {
         .then(|| pending.clone());
         let credential = match pending.target() {
             AuthorizationMutationTarget::Create { name } => {
-                PreparedAuthorizationCredential::Create(prepared_create(self.kind.clone(), name))
+                PreparedAuthorizationCredential::Create(
+                    self.authorization_accounts
+                        .lock()
+                        .unwrap()
+                        .take()
+                        .unwrap_or_else(|| vec![prepared_create(self.kind.clone(), name)]),
+                )
             }
             AuthorizationMutationTarget::Reauthorize { account_id } => {
                 let mut account = account_record(self.kind.as_str());
                 account.id = account_id.as_str().to_owned();
-                PreparedAuthorizationCredential::Reauthorize(self.prepared_rotation(&account))
+                PreparedAuthorizationCredential::Reauthorize(Box::new(
+                    self.prepared_rotation(&account),
+                ))
             }
         };
         let prepared = PreparedAuthorizationCommit::new(pending, credential);
@@ -419,6 +466,22 @@ impl ProviderAdmin for FakeProviderAdmin {
         })
     }
 
+    async fn poll_authorization(
+        &self,
+        _command: gateway_admin::model::provider_credentials::PollAuthorization,
+    ) -> Result<
+        gateway_admin::model::provider_credentials::PreparedAuthorizationPoll,
+        ProviderAdminError,
+    > {
+        self.record("provider.poll_authorization");
+        self.require_available()?;
+        self.authorization_polls
+            .lock()
+            .unwrap()
+            .pop_front()
+            .ok_or_else(unsupported)
+    }
+
     async fn prepare_rotation(
         &self,
         command: PrepareCredentialRotation,
@@ -539,6 +602,12 @@ pub(super) struct FakeAccountStore {
     accounts: Mutex<Vec<AccountRecord>>,
     account_after_probe: Mutex<Option<AccountRecord>>,
     fail_commit: Mutex<bool>,
+    receipts: Mutex<
+        std::collections::BTreeMap<
+            gateway_admin::model::provider_credentials::AuthorizationReceiptKey,
+            gateway_admin::model::provider_credentials::CredentialBatchMutationResult,
+        >,
+    >,
     audit_requests: Mutex<Vec<String>>,
     import_settings: Mutex<Vec<Option<gateway_admin::model::accounts::AccountImportSettings>>>,
     quota_window_usage: Mutex<Vec<AccountUsageWindowResult>>,
@@ -559,6 +628,7 @@ impl FakeAccountStore {
             accounts: Mutex::new(vec![account]),
             account_after_probe: Mutex::new(None),
             fail_commit: Mutex::new(false),
+            receipts: Mutex::new(Default::default()),
             audit_requests: Mutex::new(Vec::new()),
             import_settings: Mutex::new(Vec::new()),
             quota_window_usage: Mutex::new(Vec::new()),
@@ -654,6 +724,17 @@ impl FakeAccountStore {
 
 #[async_trait]
 impl AccountStore for FakeAccountStore {
+    async fn list_plugin_accounts(
+        &self,
+        _: gateway_admin::model::provider_credentials::PluginAccountListQuery,
+    ) -> AdminStoreResult<gateway_admin::model::provider_credentials::PluginAccountPage> {
+        Err(AdminStoreError::new(
+            AdminStoreErrorKind::Unavailable,
+            "plugin accounts",
+            "unavailable",
+        ))
+    }
+
     async fn list_accounts(
         &self,
         _: AccountListQuery,
@@ -664,6 +745,12 @@ impl AccountStore for FakeAccountStore {
         let total = accounts.len() as u64;
         Ok(AccountPage {
             config_revision: revision(1),
+            providers: accounts
+                .iter()
+                .map(|account| account.provider_kind.to_string())
+                .collect::<std::collections::BTreeSet<_>>()
+                .into_iter()
+                .collect(),
             items: accounts.into_iter().map(Self::page_item).collect(),
             total,
             summary: AccountSummary {
@@ -756,6 +843,24 @@ impl AccountStore for FakeAccountStore {
         }))
     }
 
+    async fn credential_details_by_id(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> AdminStoreResult<Option<CredentialDetails>> {
+        self.record("store.credential_details_by_id");
+        let account = self
+            .accounts
+            .lock()
+            .expect("accounts")
+            .iter()
+            .find(|account| account.id == account_id.as_str())
+            .cloned();
+        Ok(account.map(|credential| CredentialDetails {
+            config_revision: revision(1),
+            credential,
+        }))
+    }
+
     async fn load_credentials_for_export(
         &self,
         provider_kind: &ProviderKind,
@@ -784,6 +889,24 @@ impl AccountStore for FakeAccountStore {
             .collect())
     }
 
+    async fn load_credential_for_plugin(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> AdminStoreResult<Option<ProviderExportCredentialInput>> {
+        self.record("store.load_credential_for_plugin");
+        Ok(self
+            .accounts
+            .lock()
+            .expect("accounts")
+            .iter()
+            .find(|account| account.id == account_id.as_str())
+            .cloned()
+            .map(|account| ProviderExportCredentialInput {
+                account,
+                provider_material: document(),
+            }))
+    }
+
     async fn commit_credential_import(
         &self,
         command: CredentialImportCommit,
@@ -811,26 +934,65 @@ impl AccountStore for FakeAccountStore {
         &self,
         command: AuthorizationCommit,
         context: &MutationContext,
-    ) -> AdminStoreResult<CredentialMutationResult> {
+    ) -> AdminStoreResult<gateway_admin::model::provider_credentials::AuthorizationCommitResult>
+    {
         self.import_settings
             .lock()
             .expect("import settings")
             .push(command.settings);
+        if let Some(result) = self.receipts.lock().unwrap().get(&command.key).cloned() {
+            return Ok(
+                gateway_admin::model::provider_credentials::AuthorizationCommitResult {
+                    result,
+                    newly_committed: false,
+                },
+            );
+        }
         self.record("store.commit_authorization");
         self.record_context(context);
         self.require_commit()?;
-        let (account_id, credential_revision) = match command.credential {
-            AuthorizationCredentialCommit::Create(credential) => (credential.account_id, None),
-            AuthorizationCredentialCommit::Reauthorize(credential) => (
-                credential.account_id,
-                Some(revision(credential.expected_credential_revision.get() + 1)),
-            ),
+        let accounts = match command.credential {
+            AuthorizationCredentialCommit::Create(credentials) => credentials
+                .into_iter()
+                .map(
+                    |credential| gateway_admin::model::provider_credentials::AuthorizedAccount {
+                        account_id: credential.account_id,
+                        credential_revision: None,
+                    },
+                )
+                .collect(),
+            AuthorizationCredentialCommit::Reauthorize(credential) => vec![
+                gateway_admin::model::provider_credentials::AuthorizedAccount {
+                    account_id: credential.account_id,
+                    credential_revision: Some(revision(
+                        credential.expected_credential_revision.get() + 1,
+                    )),
+                },
+            ],
         };
-        Ok(CredentialMutationResult {
+        let result = gateway_admin::model::provider_credentials::CredentialBatchMutationResult {
             config_revision: revision(2),
-            account_id,
-            credential_revision,
-        })
+            accounts,
+        };
+        self.receipts
+            .lock()
+            .unwrap()
+            .insert(command.key, result.clone());
+        Ok(
+            gateway_admin::model::provider_credentials::AuthorizationCommitResult {
+                result,
+                newly_committed: true,
+            },
+        )
+    }
+
+    async fn authorization_receipt(
+        &self,
+        key: &gateway_admin::model::provider_credentials::AuthorizationReceiptKey,
+    ) -> AdminStoreResult<
+        Option<gateway_admin::model::provider_credentials::CredentialBatchMutationResult>,
+    > {
+        Ok(self.receipts.lock().unwrap().get(key).cloned())
     }
 
     async fn commit_credential_rotation(
@@ -997,8 +1159,7 @@ impl SettingsStore for StaticSettingsStore {
     }
     async fn load_runtime_settings(&self) -> AdminStoreResult<RuntimeSettings> {
         Ok(RuntimeSettings {
-            openai_client_profile: None,
-            xai_client_profile: None,
+            request_profiles: Default::default(),
             request_location_enabled: false,
             request_location: Default::default(),
             config_revision: revision(1),
@@ -1258,6 +1419,66 @@ async fn connection_test_should_preserve_disabled_account_status() {
     ));
 }
 
+#[tokio::test]
+async fn accounts_export_should_reject_unsupported_before_loading_secrets() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("local-echo", events.clone());
+    provider.credential_capabilities.lock().unwrap().export = false;
+    let store = FakeAccountStore::new("local-echo", events.clone());
+    let error = accounts_service(provider, store)
+        .await
+        .accounts()
+        .export(
+            &context("unsupported-export"),
+            vec![ProviderAccountId::new("acct_test").unwrap()],
+        )
+        .await
+        .unwrap_err();
+
+    assert_eq!(error.kind(), gateway_admin::model::AdminErrorKind::Invalid);
+    assert_eq!(recorded(&events), ["store.load_account"]);
+}
+
+#[tokio::test]
+async fn accounts_export_should_validate_all_providers_before_loading_any_secret() {
+    for registered in [true, false] {
+        let events = events();
+        let native = FakeProviderAdmin::new("openai", events.clone());
+        let plugin = FakeProviderAdmin::new("z-plugin", events.clone());
+        plugin.credential_capabilities.lock().unwrap().export = false;
+        let store = FakeAccountStore::new("openai", events.clone());
+        let mut other = account_record("z-plugin");
+        other.id = "acct_plugin".to_owned();
+        store.accounts.lock().unwrap().push(other);
+        let mut harness = super::AdminHarness::new()
+            .accounts(store)
+            .settings(Arc::new(StaticSettingsStore))
+            .provider(native);
+        if registered {
+            harness = harness.provider(plugin);
+        }
+        let error = harness
+            .build()
+            .await
+            .accounts()
+            .export(
+                &context("mixed-provider-export"),
+                vec![
+                    ProviderAccountId::new("acct_test").unwrap(),
+                    ProviderAccountId::new("acct_plugin").unwrap(),
+                ],
+            )
+            .await
+            .unwrap_err();
+
+        assert_eq!(error.kind(), gateway_admin::model::AdminErrorKind::Invalid);
+        assert_eq!(
+            recorded(&events),
+            ["store.load_account", "store.load_account"]
+        );
+    }
+}
+
 #[tokio::test]
 async fn accounts_export_should_pass_store_loaded_timestamps_and_material_to_provider() {
     let provider = FakeProviderAdmin::new("openai", events());
@@ -1321,6 +1542,162 @@ async fn accounts_refresh_should_keep_guard_through_store_commit() {
     assert_eq!(store.audit_requests(), ["refresh-request"]);
 }
 
+#[tokio::test]
+async fn plugin_account_saves_reuse_commits_and_defer_publication_inside_runtime_calls() {
+    for (reason, commit_event, request_id) in [
+        (
+            PluginAccountSaveReason::ModelDiscovery,
+            "store.commit_refresh",
+            "plugin-model-discovery",
+        ),
+        (
+            PluginAccountSaveReason::Maintenance,
+            "store.commit_refresh",
+            "plugin-maintenance",
+        ),
+        (
+            PluginAccountSaveReason::Explicit,
+            "store.commit_rotation",
+            "plugin-explicit-save",
+        ),
+    ] {
+        let events = events();
+        let provider = FakeProviderAdmin::new("openai", events.clone());
+        let store = FakeAccountStore::new("openai", events.clone());
+        let snapshot = Arc::new(RecordingPluginAccountPublication(events.clone()));
+        let access = gateway_admin::initialize_plugin_accounts(
+            ProviderAdminRegistry::new([provider.clone() as Arc<dyn ProviderAdmin>]).unwrap(),
+            store.clone(),
+            snapshot,
+        );
+
+        let result = access
+            .save(
+                PreparedPluginAccountSave::Replace {
+                    facts: plugin_rotation_facts(&account_record("openai")),
+                    authentication_kind: "oauth".to_owned(),
+                    reason,
+                },
+                &context(request_id),
+            )
+            .await
+            .expect("save prepared plugin account facts");
+        if reason == PluginAccountSaveReason::Explicit {
+            tokio::time::timeout(
+                std::time::Duration::from_secs(1),
+                provider.quota_started.notified(),
+            )
+            .await
+            .expect("start post-commit quota observation");
+        } else {
+            // Runtime 内保存时仍持有编译或刷新资源，不能重入 Provider/额度查询。
+            tokio::task::yield_now().await;
+        }
+
+        assert_eq!(result.account_id.as_str(), "acct_test");
+        assert_eq!(result.credential_revision, revision(2));
+        assert_eq!(store.audit_requests(), [request_id]);
+        let mut expected = vec!["store.credential_details", commit_event];
+        if reason == PluginAccountSaveReason::Explicit {
+            expected.extend([
+                "provider.account_facts_changed",
+                "snapshot.publish_committed",
+                "provider.quota",
+            ]);
+        } else {
+            expected.push("snapshot.publish_committed_deferred");
+        }
+        assert_eq!(recorded(&events), expected);
+    }
+}
+
+#[tokio::test]
+async fn plugin_account_reads_resolve_the_authoritative_provider_from_the_account_id() {
+    let events = events();
+    let store = FakeAccountStore::new("xai", events.clone());
+    // 读取端口不能让调用方提供或伪造 Provider；注册表中即使只有另一 Provider，
+    // 也必须按 Store 中该 account ID 的权威事实返回。
+    let registered_provider = FakeProviderAdmin::new("openai", events.clone());
+    let access = gateway_admin::initialize_plugin_accounts(
+        ProviderAdminRegistry::new([registered_provider as Arc<dyn ProviderAdmin>]).unwrap(),
+        store,
+        Arc::new(RecordingPluginAccountPublication(events.clone())),
+    );
+    let account_id = ProviderAccountId::new("acct_test").expect("account ID");
+
+    let runtime = access
+        .get_runtime(&account_id)
+        .await
+        .expect("load plugin account runtime");
+    let credential = access
+        .get_credential(&account_id)
+        .await
+        .expect("load plugin account credential");
+
+    assert_eq!(runtime.provider_kind.as_str(), "xai");
+    assert_eq!(credential.account.provider_kind.as_str(), "xai");
+    assert_eq!(credential.account.id, account_id.as_str());
+    assert_eq!(
+        recorded(&events),
+        [
+            "store.credential_details_by_id",
+            "store.load_credential_for_plugin",
+        ]
+    );
+}
+
+struct RecordingPluginAccountPublication(EventLog);
+
+impl gateway_core::runtime::SnapshotControl for RecordingPluginAccountPublication {
+    fn publish_committed(
+        &self,
+        revision: gateway_core::routing::ConfigRevision,
+    ) -> BoxFuture<'_, ()> {
+        Box::pin(async move {
+            assert_eq!(revision.get(), 2);
+            self.0.lock().unwrap().push("snapshot.publish_committed");
+        })
+    }
+
+    fn publish_committed_deferred(
+        &self,
+        revision: gateway_core::routing::ConfigRevision,
+    ) -> BoxFuture<'_, ()> {
+        Box::pin(async move {
+            assert_eq!(revision.get(), 2);
+            self.0
+                .lock()
+                .unwrap()
+                .push("snapshot.publish_committed_deferred");
+        })
+    }
+}
+
+#[tokio::test]
+async fn plugin_account_save_rejects_stale_authentication_kind_before_commit() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    let store = FakeAccountStore::new("openai", events.clone());
+    let services = accounts_service(provider, store.clone()).await;
+
+    let error = services
+        .plugin_accounts_handle()
+        .save(
+            PreparedPluginAccountSave::Replace {
+                facts: plugin_rotation_facts(&account_record("openai")),
+                authentication_kind: "api_key".to_owned(),
+                reason: PluginAccountSaveReason::Explicit,
+            },
+            &context("plugin-stale-auth-kind"),
+        )
+        .await
+        .expect_err("authentication kind change must be rejected");
+
+    assert_eq!(error.kind(), gateway_admin::model::AdminErrorKind::Conflict);
+    assert_eq!(recorded(&events), ["store.credential_details"]);
+    assert!(store.audit_requests().is_empty());
+}
+
 #[tokio::test]
 async fn accounts_quota_refresh_should_return_the_updated_account_status() {
     let events = events();
@@ -1644,6 +2021,12 @@ async fn accounts_batch_update_should_commit_once_and_notify_each_provider() {
 #[tokio::test]
 async fn accounts_list_should_return_complete_directory_semantics() {
     let provider = FakeProviderAdmin::new("openai", events());
+    let capabilities = gateway_admin::model::provider_capabilities::ProviderAccountCapabilities {
+        quota: true,
+        profile: true,
+        ..Default::default()
+    };
+    *provider.capabilities.lock().unwrap() = capabilities;
     let mut stored = account_record("openai");
     stored.plan_type = Some("  self_serve_business_prolite  ".to_owned());
     let store = FakeAccountStore::with_account(stored, events());
@@ -1665,6 +2048,7 @@ async fn accounts_list_should_return_complete_directory_semantics() {
     assert_eq!(page.summary.total, 1);
     assert_eq!(page.summary.normal, 1);
     let account = page.items.first().expect("account item");
+    assert_eq!(account.capabilities, capabilities);
     assert_eq!(account.account.provider_kind.as_str(), "openai");
     assert_eq!(
         account.projection.status,
@@ -1690,6 +2074,7 @@ async fn accounts_list_should_return_complete_directory_semantics() {
         .await
         .expect("account detail");
     assert_eq!(detail.plan_type_display, account.plan_type_display);
+    assert_eq!(detail.capabilities, account.capabilities);
     assert_eq!(detail.account.plan_type, account.account.plan_type);
 }
 
@@ -2039,6 +2424,11 @@ async fn quota_forecast_reads_raw_snapshot_and_limits_usage_to_observation_time(
         report.forecasts[0].source.as_ref().unwrap().observed_at,
         Some(observed)
     );
+    assert_eq!(
+        report.forecasts[1].source.as_ref().unwrap().label,
+        report.forecasts[0].source.as_ref().unwrap().label,
+        "缺少月窗口时两个展示周期复用同一周窗口"
+    );
     let queries = store.quota_window_queries();
     assert_eq!(queries.len(), 1);
     assert_eq!(queries[0].range.start, reset - TimeDelta::days(7));
@@ -2069,6 +2459,70 @@ async fn quota_forecast_does_not_query_usage_without_a_current_snapshot() {
     assert!(!provider.quota_requests.lock().unwrap()[0].refresh);
 }
 
+#[tokio::test]
+async fn quota_forecast_only_queries_the_two_selected_source_windows() {
+    let provider = FakeProviderAdmin::new("openai", events());
+    let now = Utc::now();
+    let observed = now - TimeDelta::minutes(1);
+    let reset = now + TimeDelta::days(1);
+    let windows = (0..64)
+        .map(|index| {
+            let monthly = index % 2 == 1;
+            ProviderQuotaWindow {
+                key: if monthly {
+                    format!("month-{index}")
+                } else {
+                    format!("week-{index}")
+                },
+                group: if monthly { "monthly" } else { "shortTerm" }.to_owned(),
+                label: format!("window-{index}"),
+                limit_id: None,
+                limit_name: None,
+                role: None,
+                local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+                window_seconds: Some(if monthly { 30 } else { 7 } * 86_400),
+                used_percent: Some(20.0),
+                reset_at: Some(reset),
+                limit_reached: false,
+                local_usage: None,
+                provider_data: None,
+            }
+        })
+        .collect();
+    provider.set_quota(ProviderQuota {
+        plan_type: Some("pro".to_owned()),
+        observed_at: Some(observed),
+        windows,
+        ..empty_quota()
+    });
+    let mut account = account_record("openai");
+    account.created_at = now - TimeDelta::days(60);
+    let store = FakeAccountStore::with_account(account, events());
+    let report = accounts_service(provider, store.clone())
+        .await
+        .accounts()
+        .quota_forecast(&ProviderAccountId::new("acct_test").unwrap())
+        .await
+        .expect("quota forecast");
+
+    let queries = store.quota_window_queries();
+    assert_eq!(
+        queries
+            .iter()
+            .map(|query| query.key.as_str())
+            .collect::<Vec<_>>(),
+        ["week-0", "month-1"]
+    );
+    assert_eq!(
+        report.forecasts[0].source.as_ref().unwrap().label,
+        "window-0"
+    );
+    assert_eq!(
+        report.forecasts[1].source.as_ref().unwrap().label,
+        "window-1"
+    );
+}
+
 #[tokio::test]
 async fn quota_forecast_mid_cycle_sampling_accepts_small_reset_jitter_but_not_a_changed_bucket() {
     use gateway_admin::model::quota_forecast_sampling::QuotaForecastHistoryPoint;
@@ -2530,6 +2984,52 @@ async fn reset_credit_oauth_refresh_should_reuse_the_exact_consume_command() {
     assert!(recorded(&events).contains(&"store.commit_refresh"));
 }
 
+#[tokio::test]
+async fn reset_credit_refresh_without_quota_should_complete_with_the_same_command() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("example", events.clone());
+    provider.fail_next(ProviderAdminErrorKind::CredentialRefreshRequired);
+    *provider.quota_failure.lock().unwrap() = Some(ProviderAdminErrorKind::Unsupported);
+    let store = FakeAccountStore::new("example", events.clone());
+    let services = accounts_service(provider.clone(), store).await;
+    let command = ConsumeProviderResetCredit {
+        account_id: ProviderAccountId::new("acct_test").unwrap(),
+        credit_id: Some("credit_1".into()),
+        redeem_request_id: uuid::Uuid::parse_str("dbabeb20-040e-4e9f-8615-0b7c81e79987").unwrap(),
+    };
+
+    let result = services
+        .accounts()
+        .consume_reset_credit(&context("reset-without-quota"), command.clone())
+        .await
+        .expect("缺少可选额度能力不能中断凭据刷新后的消费重试");
+
+    assert_eq!(result.code, "reset");
+    assert_eq!(provider.reset_credit_commands(), [command.clone(), command]);
+    assert_eq!(
+        recorded(&events)
+            .iter()
+            .filter(|event| **event == "store.commit_refresh")
+            .count(),
+        1
+    );
+}
+
+#[tokio::test]
+async fn accounts_quota_refresh_should_still_reject_an_unsupported_operation() {
+    let provider = FakeProviderAdmin::new("example", events());
+    *provider.quota_failure.lock().unwrap() = Some(ProviderAdminErrorKind::Unsupported);
+    let services = accounts_service(provider, FakeAccountStore::new("example", events())).await;
+
+    let error = services
+        .accounts()
+        .quota(&ProviderAccountId::new("acct_test").unwrap(), true)
+        .await
+        .expect_err("显式刷新不能被解释为空额度投影");
+
+    assert_eq!(error.kind(), gateway_admin::model::AdminErrorKind::Invalid);
+}
+
 #[tokio::test]
 async fn reset_credit_unknown_result_should_keep_a_stable_admin_kind() {
     let events = events();
@@ -2710,7 +3210,7 @@ fn prepared_create(provider_kind: ProviderKind, name: &str) -> PreparedCredentia
     prepared_create_with_id(provider_kind, "acct_prepared", name)
 }
 
-fn prepared_create_with_id(
+pub(super) fn prepared_create_with_id(
     provider_kind: ProviderKind,
     account_id: &str,
     name: &str,
@@ -2747,6 +3247,23 @@ fn rotation_result(command: CredentialRotationCommit) -> CredentialMutationResul
     }
 }
 
+fn plugin_rotation_facts(account: &AccountRecord) -> PreparedCredentialRotationFacts {
+    PreparedCredentialRotationFacts {
+        account_id: ProviderAccountId::new(account.id.clone()).expect("account ID"),
+        provider_kind: account.provider_kind.clone(),
+        expected_credential_revision: account.credential_revision,
+        replacement_identity: None,
+        name: "plugin refreshed account".to_owned(),
+        email: account.email.clone(),
+        plan_type: account.plan_type.clone(),
+        preserve_profile: true,
+        provider_material: document(),
+        has_refresh_token: account.has_refresh_token,
+        access_token_expires_at: account.access_token_expires_at,
+        next_refresh_at: account.next_refresh_at,
+    }
+}
+
 fn empty_profile_statistics() -> ProviderProfileStatistics {
     ProviderProfileStatistics {
         display_name: Some("Preview user".to_owned()),
@@ -2935,6 +3452,7 @@ impl AccountProbe for SuccessfulAccountProbe {
     fn probe(
         &self,
         _: AccountProbeRequest,
+        _: Option<Arc<gateway_core::routing::RuntimeSnapshot>>,
     ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
         Box::pin(async {
             Ok(AccountProbeResult {
@@ -2950,6 +3468,7 @@ impl AccountProbe for FailingAccountProbe {
     fn probe(
         &self,
         _: AccountProbeRequest,
+        _: Option<Arc<gateway_core::routing::RuntimeSnapshot>>,
     ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
         Box::pin(async {
             let detail = ClientVisibleUpstreamError::new(
@@ -2979,6 +3498,7 @@ impl AccountProbe for FreeModelQuotaProbe {
     fn probe(
         &self,
         _: AccountProbeRequest,
+        _: Option<Arc<gateway_core::routing::RuntimeSnapshot>>,
     ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
         Box::pin(async move {
             self.store.set_account_after_probe(account_record("xai"));
@@ -3022,3 +3542,29 @@ pub(super) fn import_settings() -> gateway_admin::model::accounts::AccountImport
         ],
     }
 }
+
+#[tokio::test]
+async fn unregistered_provider_accounts_have_no_live_management_capabilities() {
+    let provider = FakeProviderAdmin::new("openai", events());
+    let store = FakeAccountStore::with_account(account_record("retired-provider"), events());
+    let services = accounts_service(provider, store).await;
+    let page = services
+        .accounts()
+        .list(AccountListQuery {
+            page: 1,
+            page_size: gateway_admin::model::PageSize::new(20).unwrap(),
+            provider_kind: None,
+            group_filter: None,
+            search: None,
+            status: None,
+            sort: None,
+        })
+        .await
+        .unwrap();
+    assert_eq!(page.items.len(), 1);
+    assert_eq!(
+        page.items[0].account.provider_kind.as_str(),
+        "retired-provider"
+    );
+    assert_eq!(page.items[0].capabilities, Default::default());
+}
diff --git a/backend/crates/gateway-admin/tests/use_case/client_keys.rs b/backend/crates/gateway-admin/tests/use_case/client_keys.rs
index 166c6f7c4..f26fad5dd 100644
--- a/backend/crates/gateway-admin/tests/use_case/client_keys.rs
+++ b/backend/crates/gateway-admin/tests/use_case/client_keys.rs
@@ -6,20 +6,26 @@ use gateway_core::policy::{ClientApiKeyId, PlaintextClientApiKey, RateLimits};
 
 use gateway_admin::{
     model::{
-        AdminErrorKind, MutationActor, MutationContext, Revision,
+        AdminErrorKind, MutationActor, MutationContext, PageSize, Revision,
         client_keys::{
             ClientKeyCursor, ClientKeyCursorValue, ClientKeyListQuery, ClientKeyPage,
             ClientKeyPageSize, ClientKeyRecord, ClientKeySecret, ClientKeySort, ClientKeySortField,
             CreateClientKey, DeleteClientKey, NewClientKey, SetClientKeyEnabled, SortDirection,
             UpdateClientKey,
         },
+        plugin_client_keys::{
+            PluginClientKey, PluginClientKeyCursor, PluginClientKeyListQuery, PluginClientKeyPage,
+        },
     },
+    ports::provider::{ProviderAdmin, ProviderAdminRegistry},
     ports::store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult, ClientKeyStore},
 };
 
 #[derive(Default)]
 struct TestClientKeyStore {
     plaintexts: Mutex<Vec<String>>,
+    list_queries: Mutex<Vec<ClientKeyListQuery>>,
+    list_response: Mutex<Option<ClientKeyPage>>,
     create_error: Option<AdminStoreErrorKind>,
     update_error: Option<AdminStoreErrorKind>,
     resets: Mutex<Vec<gateway_admin::model::client_keys::ResetClientKeyBudget>>,
@@ -44,6 +50,10 @@ impl ClientKeyStore for TestClientKeyStore {
     }
 
     async fn list_client_keys(&self, query: ClientKeyListQuery) -> AdminStoreResult<ClientKeyPage> {
+        self.list_queries.lock().unwrap().push(query.clone());
+        if let Some(page) = self.list_response.lock().unwrap().clone() {
+            return Ok(page);
+        }
         assert_eq!(query.page_size.get(), u16::MAX);
         Ok(ClientKeyPage {
             config_revision: Revision::new(1).expect("revision"),
@@ -74,8 +84,7 @@ impl ClientKeyStore for TestClientKeyStore {
         }
         self.plaintexts.lock().unwrap().push(key.plaintext);
         let record = ClientKeyRecord {
-            openai_client_profile_override: None,
-            xai_client_profile_override: None,
+            request_profile_overrides: Default::default(),
             id: key.id,
             name: key.name,
             label: key.label,
@@ -196,6 +205,91 @@ async fn client_key_list_should_forward_the_full_nonzero_u16_page_size() {
     assert_eq!(page.total, 0);
 }
 
+#[tokio::test]
+async fn plugin_client_key_list_projects_only_public_identity_and_uses_stable_name_cursor() {
+    let now = Utc::now();
+    let key_id = ClientApiKeyId::new("key_public").expect("key ID");
+    let next_id = ClientApiKeyId::new("key_next").expect("next key ID");
+    let sort = ClientKeySort {
+        field: ClientKeySortField::Name,
+        direction: SortDirection::Asc,
+    };
+    let store = Arc::new(TestClientKeyStore {
+        list_response: Mutex::new(Some(ClientKeyPage {
+            config_revision: Revision::new(7).expect("revision"),
+            items: vec![ClientKeyRecord {
+                request_profile_overrides: Default::default(),
+                id: key_id.clone(),
+                name: "Public identity".to_owned(),
+                label: Some("private management label".to_owned()),
+                groups: Vec::new(),
+                provider_kinds: Vec::new(),
+                prefix: "sk_must_not_escape".to_owned(),
+                enabled: true,
+                limits: RateLimits::unlimited(),
+                budget: Default::default(),
+                last_used_at: Some(now),
+                created_at: now,
+                updated_at: now,
+            }],
+            total: 1,
+            next_cursor: Some(ClientKeyCursor {
+                sort,
+                value: ClientKeyCursorValue::Name("Public identity".to_owned()),
+                id: next_id.clone(),
+            }),
+        })),
+        ..Default::default()
+    });
+    let providers = ProviderAdminRegistry::new(Vec::<Arc<dyn ProviderAdmin>>::new())
+        .expect("empty provider registry");
+    let access = gateway_admin::initialize_plugin_client_keys(
+        providers,
+        store.clone(),
+        Arc::new(super::NoopSnapshot),
+    );
+    let input_cursor = PluginClientKeyCursor {
+        name: "Before".to_owned(),
+        id: ClientApiKeyId::new("key_before").expect("cursor key ID"),
+    };
+
+    let page = access
+        .list(PluginClientKeyListQuery {
+            cursor: Some(input_cursor.clone()),
+            limit: PageSize::new(25).expect("page size"),
+        })
+        .await
+        .expect("list plugin client keys");
+
+    assert_eq!(
+        page,
+        PluginClientKeyPage {
+            items: vec![PluginClientKey {
+                id: key_id,
+                name: "Public identity".to_owned(),
+                enabled: true,
+            }],
+            next_cursor: Some(PluginClientKeyCursor {
+                name: "Public identity".to_owned(),
+                id: next_id,
+            }),
+        }
+    );
+    assert_eq!(
+        *store.list_queries.lock().unwrap(),
+        vec![ClientKeyListQuery {
+            cursor: Some(ClientKeyCursor {
+                sort,
+                value: ClientKeyCursorValue::Name(input_cursor.name),
+                id: input_cursor.id,
+            }),
+            page_size: ClientKeyPageSize::new(25).expect("page size"),
+            search: None,
+            sort,
+        }]
+    );
+}
+
 #[tokio::test]
 async fn create_preserves_migrated_keys_and_keeps_default_generation() {
     let store = Arc::new(TestClientKeyStore::default());
@@ -260,8 +354,7 @@ async fn duplicate_names_report_the_same_actionable_conflict_on_create_and_updat
         .update(
             &mutation_context(),
             UpdateClientKey {
-                openai_client_profile_override: None,
-                xai_client_profile_override: None,
+                request_profile_override_updates: Default::default(),
                 id: ClientApiKeyId::new("key_existing").unwrap(),
                 name: "Migration".to_owned(),
                 label: None,
@@ -281,8 +374,7 @@ async fn duplicate_names_report_the_same_actionable_conflict_on_create_and_updat
 
 fn create_command(key: Option<&str>) -> CreateClientKey {
     CreateClientKey {
-        openai_client_profile_override: None,
-        xai_client_profile_override: None,
+        request_profile_overrides: Default::default(),
         custom_key: key.map(|value| PlaintextClientApiKey::new(value).unwrap()),
         name: "Migration".to_owned(),
         label: None,
diff --git a/backend/crates/gateway-admin/tests/use_case/credentials/flow.rs b/backend/crates/gateway-admin/tests/use_case/credentials/flow.rs
new file mode 100644
index 000000000..62bd050ea
--- /dev/null
+++ b/backend/crates/gateway-admin/tests/use_case/credentials/flow.rs
@@ -0,0 +1,388 @@
+use std::time::Duration;
+
+use async_trait::async_trait;
+use gateway_admin::model::{
+    AdminError, AdminErrorKind,
+    provider_credentials::{
+        AuthorizationCommitGuard, AuthorizationMutationTarget, AuthorizationOwnerBinding,
+        AuthorizationPollResult, PendingAuthorizationMutation, PollAuthorization,
+        PreparedAuthorizationCommit, PreparedAuthorizationCredential, PreparedAuthorizationPoll,
+    },
+};
+use gateway_core::routing::ProviderKind;
+
+use super::super::{
+    AdminHarness,
+    accounts::{
+        EventLog, FakeAccountStore, FakeProviderAdmin, context, events, prepared_create_with_id,
+        recorded,
+    },
+};
+
+struct Claim(EventLog);
+
+struct FailedConsumptionClaim(EventLog);
+
+#[tokio::test]
+async fn unavailable_receipts_prevent_replaying_upstream_authorization() {
+    let log = events();
+    let kind = ProviderKind::new("example").unwrap();
+    let services = AdminHarness::new()
+        .provider(FakeProviderAdmin::new("example", log.clone()))
+        .build()
+        .await;
+    let error = services
+        .credentials()
+        .poll_authorization(&kind, poll())
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), AdminErrorKind::Unavailable);
+    assert!(recorded(&log).is_empty());
+}
+
+#[async_trait]
+impl AuthorizationCommitGuard for FailedConsumptionClaim {
+    async fn commit(self: Box<Self>) -> Result<(), AdminError> {
+        self.0.lock().unwrap().push("claim.consume_failed");
+        Err(AdminError::unavailable("injected pending store failure"))
+    }
+
+    async fn abort(self: Box<Self>) -> Result<(), AdminError> {
+        panic!("a committed authorization must not be aborted")
+    }
+}
+
+#[tokio::test]
+async fn committed_authorization_survives_cleanup_failure_and_does_not_require_a_provider_on_retry()
+{
+    let log = events();
+    let kind = ProviderKind::new("example").unwrap();
+    let provider = FakeProviderAdmin::new("example", log.clone());
+    let PreparedAuthorizationPoll::Complete(prepared) = completed(&log, &["acct_receipt"]) else {
+        unreachable!()
+    };
+    provider.queue_authorization_poll(PreparedAuthorizationPoll::Complete(Box::new(
+        prepared.with_authorization_guard(Box::new(FailedConsumptionClaim(log.clone()))),
+    )));
+    let store = FakeAccountStore::new("example", log.clone());
+    let services = AdminHarness::new()
+        .provider(provider)
+        .accounts(store.clone())
+        .build()
+        .await;
+    let original = services
+        .credentials()
+        .poll_authorization(&kind, poll())
+        .await
+        .unwrap();
+    // 只挂载同一个持久化端口，不再注册 Provider，证明恢复不重放任何插件操作。
+    let restarted = AdminHarness::new().accounts(store.clone()).build().await;
+    assert_eq!(
+        restarted
+            .credentials()
+            .poll_authorization(&kind, poll())
+            .await
+            .unwrap(),
+        original
+    );
+    assert_eq!(store.audit_requests().len(), 1);
+    assert_eq!(
+        recorded(&log)
+            .iter()
+            .filter(|event| **event == "provider.poll_authorization")
+            .count(),
+        1
+    );
+    assert!(recorded(&log).contains(&"claim.consume_failed"));
+}
+
+#[async_trait]
+impl AuthorizationCommitGuard for Claim {
+    async fn commit(self: Box<Self>) -> Result<(), AdminError> {
+        self.0.lock().unwrap().push("claim.commit");
+        Ok(())
+    }
+
+    async fn abort(self: Box<Self>) -> Result<(), AdminError> {
+        self.0.lock().unwrap().push("claim.abort");
+        Ok(())
+    }
+}
+
+fn poll() -> PollAuthorization {
+    PollAuthorization {
+        context: context("poll"),
+        flow_id: "flow-test".into(),
+        callback_url: None,
+        settings: None,
+    }
+}
+
+fn completed(log: &EventLog, ids: &[&str]) -> PreparedAuthorizationPoll {
+    let kind = ProviderKind::new("example").unwrap();
+    PreparedAuthorizationPoll::Complete(Box::new(
+        PreparedAuthorizationCommit::new(
+            PendingAuthorizationMutation::new(
+                kind.clone(),
+                AuthorizationMutationTarget::Create {
+                    name: "login".into(),
+                },
+                AuthorizationOwnerBinding::from_context(&context("start")),
+            ),
+            PreparedAuthorizationCredential::Create(
+                ids.iter()
+                    .map(|id| prepared_create_with_id(kind.clone(), id, "account"))
+                    .collect(),
+            ),
+        )
+        .with_authorization_guard(Box::new(Claim(log.clone()))),
+    ))
+}
+
+#[tokio::test]
+async fn pending_poll_never_commits_or_observes_accounts() {
+    let log = events();
+    let provider = FakeProviderAdmin::new("example", log.clone());
+    provider.queue_authorization_poll(PreparedAuthorizationPoll::Pending {
+        retry_after: Duration::from_secs(5),
+    });
+    let store = FakeAccountStore::new("example", log.clone());
+    let services = AdminHarness::new()
+        .provider(provider)
+        .accounts(store.clone())
+        .build()
+        .await;
+    let result = services
+        .credentials()
+        .poll_authorization(&ProviderKind::new("example").unwrap(), poll())
+        .await
+        .unwrap();
+    assert_eq!(
+        result,
+        AuthorizationPollResult::Pending {
+            retry_after: Duration::from_secs(5)
+        }
+    );
+    assert_eq!(recorded(&log), ["provider.poll_authorization"]);
+    assert!(store.audit_requests().is_empty());
+}
+
+#[tokio::test]
+async fn multi_account_poll_commits_once_then_consumes_claim_and_publishes_all_accounts() {
+    let log = events();
+    let provider = FakeProviderAdmin::new("example", log.clone());
+    provider.queue_authorization_poll(completed(&log, &["acct_one", "acct_two"]));
+    let store = FakeAccountStore::new("example", log.clone());
+    let services = AdminHarness::new()
+        .provider(provider.clone())
+        .accounts(store.clone())
+        .build()
+        .await;
+    let result = services
+        .credentials()
+        .poll_authorization(&ProviderKind::new("example").unwrap(), poll())
+        .await
+        .unwrap();
+    let AuthorizationPollResult::Complete(result) = result else {
+        panic!("expected completed login")
+    };
+    assert_eq!(
+        result
+            .accounts
+            .iter()
+            .map(|account| account.account_id.as_str())
+            .collect::<Vec<_>>(),
+        ["acct_one", "acct_two"]
+    );
+    provider.wait_for_quota_requests(2).await;
+    assert_eq!(
+        &recorded(&log)[..4],
+        [
+            "provider.poll_authorization",
+            "store.commit_authorization",
+            "claim.commit",
+            "provider.account_facts_changed"
+        ]
+    );
+    assert_eq!(store.audit_requests(), ["poll"]);
+    assert_eq!(provider.quota_requests().len(), 2);
+}
+
+#[tokio::test]
+async fn failed_batch_commit_releases_claim_without_publishing_partial_success() {
+    let log = events();
+    let provider = FakeProviderAdmin::new("example", log.clone());
+    provider.queue_authorization_poll(completed(&log, &["acct_one", "acct_two"]));
+    let store = FakeAccountStore::new("example", log.clone());
+    store.fail_next_commit();
+    let services = AdminHarness::new()
+        .provider(provider)
+        .accounts(store)
+        .build()
+        .await;
+    assert!(
+        services
+            .credentials()
+            .poll_authorization(&ProviderKind::new("example").unwrap(), poll())
+            .await
+            .is_err()
+    );
+    assert_eq!(
+        recorded(&log),
+        [
+            "provider.poll_authorization",
+            "store.commit_authorization",
+            "claim.abort"
+        ]
+    );
+}
+
+#[tokio::test]
+async fn invalid_account_collections_release_claim_before_store() {
+    for ids in [vec![], vec!["acct_one", "acct_one"], vec!["acct_one"; 201]] {
+        let log = events();
+        let provider = FakeProviderAdmin::new("example", log.clone());
+        provider.queue_authorization_poll(completed(&log, &ids));
+        let store = FakeAccountStore::new("example", log.clone());
+        let services = AdminHarness::new()
+            .provider(provider)
+            .accounts(store)
+            .build()
+            .await;
+        let error = services
+            .credentials()
+            .poll_authorization(&ProviderKind::new("example").unwrap(), poll())
+            .await
+            .unwrap_err();
+        assert_eq!(error.kind(), AdminErrorKind::Conflict);
+        assert_eq!(
+            recorded(&log),
+            ["provider.poll_authorization", "claim.abort"]
+        );
+    }
+}
+
+#[tokio::test]
+async fn forged_poll_owner_or_provider_cannot_commit_accounts() {
+    for wrong_owner in [true, false] {
+        let log = events();
+        let provider = FakeProviderAdmin::new("example", log.clone());
+        let PreparedAuthorizationPoll::Complete(mut prepared) = completed(&log, &["acct_one"])
+        else {
+            unreachable!()
+        };
+        if wrong_owner {
+            let mut foreign = context("foreign-start");
+            foreign.actor = gateway_admin::model::MutationActor::AdminSession {
+                admin_user_id: "different-admin".into(),
+            };
+            prepared.pending = PendingAuthorizationMutation::new(
+                ProviderKind::new("example").unwrap(),
+                AuthorizationMutationTarget::Create {
+                    name: "login".into(),
+                },
+                AuthorizationOwnerBinding::from_context(&foreign),
+            );
+        } else {
+            let PreparedAuthorizationCredential::Create(accounts) = &mut prepared.credential else {
+                unreachable!()
+            };
+            accounts[0].provider_kind = ProviderKind::new("another").unwrap();
+        }
+        provider.queue_authorization_poll(PreparedAuthorizationPoll::Complete(prepared));
+        let store = FakeAccountStore::new("example", log.clone());
+        let services = AdminHarness::new()
+            .provider(provider)
+            .accounts(store)
+            .build()
+            .await;
+        let error = services
+            .credentials()
+            .poll_authorization(&ProviderKind::new("example").unwrap(), poll())
+            .await
+            .unwrap_err();
+        assert_eq!(error.kind(), AdminErrorKind::Conflict);
+        assert_eq!(
+            recorded(&log),
+            ["provider.poll_authorization", "claim.abort"]
+        );
+    }
+}
+
+#[tokio::test]
+async fn pending_poll_requires_a_bounded_positive_interval() {
+    for retry_after in [Duration::ZERO, Duration::from_secs(301)] {
+        let log = events();
+        let provider = FakeProviderAdmin::new("example", log.clone());
+        provider.queue_authorization_poll(PreparedAuthorizationPoll::Pending { retry_after });
+        let store = FakeAccountStore::new("example", log.clone());
+        let services = AdminHarness::new()
+            .provider(provider)
+            .accounts(store)
+            .build()
+            .await;
+        let error = services
+            .credentials()
+            .poll_authorization(&ProviderKind::new("example").unwrap(), poll())
+            .await
+            .unwrap_err();
+        assert_eq!(error.kind(), AdminErrorKind::Internal);
+        assert_eq!(recorded(&log), ["provider.poll_authorization"]);
+    }
+}
+
+#[tokio::test]
+async fn single_account_completion_rejects_multiple_accounts_before_commit() {
+    let log = events();
+    let kind = ProviderKind::new("example").unwrap();
+    let provider = FakeProviderAdmin::new("example", log.clone());
+    provider.retry_authorization_after_abort();
+    provider.set_authorization_accounts(vec![
+        prepared_create_with_id(kind.clone(), "acct_one", "one"),
+        prepared_create_with_id(kind.clone(), "acct_two", "two"),
+    ]);
+    let store = FakeAccountStore::new("example", log.clone());
+    let services = AdminHarness::new()
+        .provider(provider)
+        .accounts(store.clone())
+        .build()
+        .await;
+    let credentials = services.credentials().for_provider(&kind).unwrap();
+    credentials
+        .start_authorization(
+            gateway_admin::model::provider_credentials::StartAuthorization {
+                input: gateway_admin::model::provider_credentials::ProviderDocument::new(
+                    gateway_core::account::OpaqueProviderData::new(serde_json::Map::new()),
+                ),
+                context: context("start"),
+                name: "login".into(),
+                reauthorization: None,
+                outbound_proxy: None,
+            },
+        )
+        .await
+        .unwrap();
+    let error = services
+        .credentials()
+        .complete_authorization(
+            &kind,
+            gateway_admin::model::provider_credentials::CompleteAuthorization {
+                context: context("complete"),
+                flow_id: "flow-test".into(),
+                callback_url: "https://example.invalid/callback".into(),
+                settings: None,
+            },
+        )
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+    assert_eq!(
+        recorded(&log),
+        [
+            "provider.start_authorization",
+            "provider.complete_authorization",
+            "authorization_guard.abort"
+        ]
+    );
+    assert!(store.audit_requests().is_empty());
+}
diff --git a/backend/crates/gateway-admin/tests/use_case/credentials/mod.rs b/backend/crates/gateway-admin/tests/use_case/credentials/mod.rs
new file mode 100644
index 000000000..20e1f0eca
--- /dev/null
+++ b/backend/crates/gateway-admin/tests/use_case/credentials/mod.rs
@@ -0,0 +1,3 @@
+mod flow;
+mod openai;
+mod xai;
diff --git a/backend/crates/gateway-admin/tests/use_case/openai.rs b/backend/crates/gateway-admin/tests/use_case/credentials/openai.rs
similarity index 75%
rename from backend/crates/gateway-admin/tests/use_case/openai.rs
rename to backend/crates/gateway-admin/tests/use_case/credentials/openai.rs
index 45b19d51a..5cf3d9a61 100644
--- a/backend/crates/gateway-admin/tests/use_case/openai.rs
+++ b/backend/crates/gateway-admin/tests/use_case/credentials/openai.rs
@@ -11,7 +11,7 @@ use gateway_admin::{
     ports::provider::ProviderAdminErrorKind,
 };
 
-use super::accounts::{
+use super::super::accounts::{
     FakeAccountStore, FakeProviderAdmin, context, document, events, recorded, revision,
 };
 
@@ -23,7 +23,9 @@ async fn openai_delete_should_commit_then_release_provider_resources() {
     let services = service(provider, store.clone()).await;
 
     services
-        .openai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+        .unwrap()
         .delete(deletion("acct_test"))
         .await
         .expect("delete credential");
@@ -48,10 +50,12 @@ async fn openai_import_should_prepare_before_atomic_store_commit() {
     let services = service(provider.clone(), store.clone()).await;
 
     services
-        .openai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+        .unwrap()
         .import_document(ImportCredentials {
             outbound_proxy_id: None,
-            settings: Some(super::accounts::import_settings()),
+            settings: Some(super::super::accounts::import_settings()),
             context: context("import-openai"),
             document: document(),
         })
@@ -79,7 +83,7 @@ async fn openai_import_should_prepare_before_atomic_store_commit() {
     );
     assert_eq!(
         store.import_settings(),
-        [Some(super::accounts::import_settings())]
+        [Some(super::super::accounts::import_settings())]
     );
     assert_eq!(store.audit_requests(), ["import-openai"]);
 }
@@ -106,7 +110,9 @@ async fn openai_import_should_expose_only_explicit_public_errors_without_committ
         let store = FakeAccountStore::new("openai", events.clone());
         let services = service(provider, store.clone()).await;
         let error = services
-            .openai()
+            .credentials()
+            .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+            .unwrap()
             .import_document(ImportCredentials {
                 outbound_proxy_id: None,
                 settings: None,
@@ -132,7 +138,9 @@ async fn openai_import_should_refresh_quota_for_every_imported_account() {
     let services = service(provider.clone(), store).await;
 
     let result = services
-        .openai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+        .unwrap()
         .import_document(ImportCredentials {
             outbound_proxy_id: None,
             settings: None,
@@ -177,7 +185,9 @@ async fn openai_import_should_remain_successful_when_quota_refresh_fails() {
     let services = service(provider.clone(), store).await;
 
     let result = services
-        .openai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+        .unwrap()
         .import_document(ImportCredentials {
             outbound_proxy_id: None,
             settings: None,
@@ -204,8 +214,13 @@ async fn openai_authorization_create_should_observe_initial_quota() {
     let services = service(provider.clone(), store.clone()).await;
 
     services
-        .openai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+        .unwrap()
         .start_authorization(StartAuthorization {
+            input: gateway_admin::model::provider_credentials::ProviderDocument::new(
+                gateway_core::account::OpaqueProviderData::new(serde_json::Map::new()),
+            ),
             outbound_proxy: None,
             context: context("oauth-start-openai-create"),
             name: "new OpenAI credential".to_owned(),
@@ -214,13 +229,16 @@ async fn openai_authorization_create_should_observe_initial_quota() {
         .await
         .expect("start authorization");
     services
-        .openai()
-        .complete_authorization(CompleteAuthorization {
-            settings: Some(super::accounts::import_settings()),
-            context: context("oauth-start-openai-create"),
-            flow_id: "flow-test".to_owned(),
-            callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
-        })
+        .credentials()
+        .complete_authorization(
+            &gateway_core::routing::ProviderKind::new("openai").unwrap(),
+            CompleteAuthorization {
+                settings: Some(super::super::accounts::import_settings()),
+                context: context("oauth-start-openai-create"),
+                flow_id: "flow-test".to_owned(),
+                callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
+            },
+        )
         .await
         .expect("complete authorization");
 
@@ -246,7 +264,7 @@ async fn openai_authorization_create_should_observe_initial_quota() {
     );
     assert_eq!(
         store.import_settings(),
-        [Some(super::accounts::import_settings())]
+        [Some(super::super::accounts::import_settings())]
     );
     assert_eq!(store.audit_requests(), ["oauth-start-openai-create"]);
 }
@@ -260,8 +278,13 @@ async fn openai_authorization_create_should_remain_successful_when_initial_quota
     let services = service(provider.clone(), store).await;
 
     services
-        .openai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+        .unwrap()
         .start_authorization(StartAuthorization {
+            input: gateway_admin::model::provider_credentials::ProviderDocument::new(
+                gateway_core::account::OpaqueProviderData::new(serde_json::Map::new()),
+            ),
             outbound_proxy: None,
             context: context("oauth-start-openai-quota-failure"),
             name: "new OpenAI credential".to_owned(),
@@ -270,13 +293,16 @@ async fn openai_authorization_create_should_remain_successful_when_initial_quota
         .await
         .expect("start authorization");
     let result = services
-        .openai()
-        .complete_authorization(CompleteAuthorization {
-            settings: None,
-            context: context("oauth-start-openai-quota-failure"),
-            flow_id: "flow-test".to_owned(),
-            callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
-        })
+        .credentials()
+        .complete_authorization(
+            &gateway_core::routing::ProviderKind::new("openai").unwrap(),
+            CompleteAuthorization {
+                settings: None,
+                context: context("oauth-start-openai-quota-failure"),
+                flow_id: "flow-test".to_owned(),
+                callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
+            },
+        )
         .await
         .expect("quota observation must not fail authorization");
 
@@ -302,8 +328,13 @@ async fn openai_authorization_store_failure_should_release_claim_for_retry() {
     };
 
     services
-        .openai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+        .unwrap()
         .start_authorization(StartAuthorization {
+            input: gateway_admin::model::provider_credentials::ProviderDocument::new(
+                gateway_core::account::OpaqueProviderData::new(serde_json::Map::new()),
+            ),
             outbound_proxy: None,
             context: context("oauth-store-retry"),
             name: "new OpenAI credential".to_owned(),
@@ -312,13 +343,19 @@ async fn openai_authorization_store_failure_should_release_claim_for_retry() {
         .await
         .expect("start authorization");
     services
-        .openai()
-        .complete_authorization(command())
+        .credentials()
+        .complete_authorization(
+            &gateway_core::routing::ProviderKind::new("openai").unwrap(),
+            command(),
+        )
         .await
         .expect_err("Store commit must fail");
     services
-        .openai()
-        .complete_authorization(command())
+        .credentials()
+        .complete_authorization(
+            &gateway_core::routing::ProviderKind::new("openai").unwrap(),
+            command(),
+        )
         .await
         .expect("released claim must permit retry");
 
@@ -350,7 +387,9 @@ async fn openai_import_provider_error_should_not_touch_store_transaction() {
     let services = service(provider, store).await;
 
     services
-        .openai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+        .unwrap()
         .import_document(ImportCredentials {
             outbound_proxy_id: None,
             settings: None,
@@ -370,8 +409,13 @@ async fn openai_reauthorization_should_commit_after_credential_revision_advances
     let store = FakeAccountStore::new("openai", events.clone());
     let services = service(provider.clone(), store.clone()).await;
     services
-        .openai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+        .unwrap()
         .start_authorization(StartAuthorization {
+            input: gateway_admin::model::provider_credentials::ProviderDocument::new(
+                gateway_core::account::OpaqueProviderData::new(serde_json::Map::new()),
+            ),
             outbound_proxy: None,
             context: context("oauth-start-openai"),
             name: "reauthorize".to_owned(),
@@ -396,13 +440,16 @@ async fn openai_reauthorization_should_commit_after_credential_revision_advances
     provider.set_current_credential_revision(revision(2));
 
     let result = services
-        .openai()
-        .complete_authorization(CompleteAuthorization {
-            settings: None,
-            context: context("oauth-complete-openai"),
-            flow_id: "flow-test".to_owned(),
-            callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
-        })
+        .credentials()
+        .complete_authorization(
+            &gateway_core::routing::ProviderKind::new("openai").unwrap(),
+            CompleteAuthorization {
+                settings: None,
+                context: context("oauth-complete-openai"),
+                flow_id: "flow-test".to_owned(),
+                callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
+            },
+        )
         .await
         .expect("complete reauthorization");
 
@@ -427,7 +474,7 @@ async fn openai_reauthorization_should_commit_after_credential_revision_advances
 }
 
 async fn service(provider: Arc<FakeProviderAdmin>, store: Arc<FakeAccountStore>) -> AdminServices {
-    super::AdminHarness::new()
+    super::super::AdminHarness::new()
         .provider(provider)
         .accounts(store)
         .build()
@@ -448,8 +495,13 @@ async fn reauthorization_with_import_settings_releases_claim_without_committing(
     let store = FakeAccountStore::new("openai", events.clone());
     let services = service(provider, store.clone()).await;
     services
-        .openai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+        .unwrap()
         .start_authorization(StartAuthorization {
+            input: gateway_admin::model::provider_credentials::ProviderDocument::new(
+                gateway_core::account::OpaqueProviderData::new(serde_json::Map::new()),
+            ),
             outbound_proxy: None,
             context: context("reauthorization-settings"),
             name: "existing account".to_owned(),
@@ -458,13 +510,16 @@ async fn reauthorization_with_import_settings_releases_claim_without_committing(
         .await
         .expect("start reauthorization");
     let error = services
-        .openai()
-        .complete_authorization(CompleteAuthorization {
-            settings: Some(super::accounts::import_settings()),
-            context: context("reauthorization-settings"),
-            flow_id: "flow-test".to_owned(),
-            callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
-        })
+        .credentials()
+        .complete_authorization(
+            &gateway_core::routing::ProviderKind::new("openai").unwrap(),
+            CompleteAuthorization {
+                settings: Some(super::super::accounts::import_settings()),
+                context: context("reauthorization-settings"),
+                flow_id: "flow-test".to_owned(),
+                callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
+            },
+        )
         .await
         .expect_err("reauthorization must preserve settings");
     assert_eq!(error.kind(), gateway_admin::model::AdminErrorKind::Invalid);
diff --git a/backend/crates/gateway-admin/tests/use_case/xai.rs b/backend/crates/gateway-admin/tests/use_case/credentials/xai.rs
similarity index 76%
rename from backend/crates/gateway-admin/tests/use_case/xai.rs
rename to backend/crates/gateway-admin/tests/use_case/credentials/xai.rs
index 12f5bc01f..24b764710 100644
--- a/backend/crates/gateway-admin/tests/use_case/xai.rs
+++ b/backend/crates/gateway-admin/tests/use_case/credentials/xai.rs
@@ -10,7 +10,9 @@ use gateway_admin::{
     ports::provider::ProviderAdminErrorKind,
 };
 
-use super::accounts::{FakeAccountStore, FakeProviderAdmin, context, document, events, recorded};
+use super::super::accounts::{
+    FakeAccountStore, FakeProviderAdmin, context, document, events, recorded,
+};
 
 #[tokio::test]
 async fn xai_import_should_prepare_before_atomic_store_commit() {
@@ -20,10 +22,12 @@ async fn xai_import_should_prepare_before_atomic_store_commit() {
     let services = service(provider.clone(), store.clone()).await;
 
     services
-        .xai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("xai").unwrap())
+        .unwrap()
         .import_document(ImportCredentials {
             outbound_proxy_id: None,
-            settings: Some(super::accounts::import_settings()),
+            settings: Some(super::super::accounts::import_settings()),
             context: context("import-xai"),
             document: document(),
         })
@@ -50,7 +54,7 @@ async fn xai_import_should_prepare_before_atomic_store_commit() {
     );
     assert_eq!(
         store.import_settings(),
-        [Some(super::accounts::import_settings())]
+        [Some(super::super::accounts::import_settings())]
     );
     assert_eq!(store.audit_requests(), ["import-xai"]);
 }
@@ -64,7 +68,9 @@ async fn xai_import_should_refresh_quota_for_every_imported_account() {
     let services = service(provider.clone(), store).await;
 
     services
-        .xai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("xai").unwrap())
+        .unwrap()
         .import_document(ImportCredentials {
             outbound_proxy_id: None,
             settings: None,
@@ -101,7 +107,9 @@ async fn xai_import_should_remain_successful_when_quota_refresh_fails() {
     let services = service(provider.clone(), store).await;
 
     let result = services
-        .xai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("xai").unwrap())
+        .unwrap()
         .import_document(ImportCredentials {
             outbound_proxy_id: None,
             settings: None,
@@ -127,8 +135,13 @@ async fn xai_authorization_should_observe_quota_without_affecting_commit() {
         let store = FakeAccountStore::new("xai", events.clone());
         let services = service(provider.clone(), store.clone()).await;
         services
-            .xai()
+            .credentials()
+            .for_provider(&gateway_core::routing::ProviderKind::new("xai").unwrap())
+            .unwrap()
             .start_authorization(StartAuthorization {
+                input: gateway_admin::model::provider_credentials::ProviderDocument::new(
+                    gateway_core::account::OpaqueProviderData::new(serde_json::Map::new()),
+                ),
                 outbound_proxy: None,
                 context: context("oauth-xai-create"),
                 name: "new xAI credential".to_owned(),
@@ -137,13 +150,16 @@ async fn xai_authorization_should_observe_quota_without_affecting_commit() {
             .await
             .expect("start authorization");
         let result = services
-            .xai()
-            .complete_authorization(CompleteAuthorization {
-                settings: None,
-                context: context("oauth-xai-create"),
-                flow_id: "flow-test".to_owned(),
-                callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
-            })
+            .credentials()
+            .complete_authorization(
+                &gateway_core::routing::ProviderKind::new("xai").unwrap(),
+                CompleteAuthorization {
+                    settings: None,
+                    context: context("oauth-xai-create"),
+                    flow_id: "flow-test".to_owned(),
+                    callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
+                },
+            )
             .await
             .expect("quota observation must not fail authorization");
 
@@ -186,8 +202,22 @@ async fn credential_import_should_return_while_initial_quota_is_pending() {
         };
         let result = tokio::time::timeout(std::time::Duration::from_secs(5), async {
             match kind {
-                "openai" => services.openai().import_document(command).await,
-                _ => services.xai().import_document(command).await,
+                "openai" => {
+                    services
+                        .credentials()
+                        .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+                        .unwrap()
+                        .import_document(command)
+                        .await
+                }
+                _ => {
+                    services
+                        .credentials()
+                        .for_provider(&gateway_core::routing::ProviderKind::new("xai").unwrap())
+                        .unwrap()
+                        .import_document(command)
+                        .await
+                }
             }
         })
         .await
@@ -208,7 +238,9 @@ async fn xai_import_store_failure_should_not_observe_quota_or_invalidate_provide
     let services = service(provider.clone(), store).await;
 
     services
-        .xai()
+        .credentials()
+        .for_provider(&gateway_core::routing::ProviderKind::new("xai").unwrap())
+        .unwrap()
         .import_document(ImportCredentials {
             outbound_proxy_id: None,
             settings: None,
@@ -226,7 +258,7 @@ async fn xai_import_store_failure_should_not_observe_quota_or_invalidate_provide
 }
 
 async fn service(provider: Arc<FakeProviderAdmin>, store: Arc<FakeAccountStore>) -> AdminServices {
-    super::AdminHarness::new()
+    super::super::AdminHarness::new()
         .provider(provider)
         .accounts(store)
         .build()
diff --git a/backend/crates/gateway-admin/tests/use_case/freeze_recovery.rs b/backend/crates/gateway-admin/tests/use_case/freeze_recovery.rs
index 7cafdc72a..46b75b3ad 100644
--- a/backend/crates/gateway-admin/tests/use_case/freeze_recovery.rs
+++ b/backend/crates/gateway-admin/tests/use_case/freeze_recovery.rs
@@ -25,8 +25,7 @@ use super::accounts::{FakeAccountStore, FakeProviderAdmin, account_record, event
 
 fn runtime_settings(enabled: bool, probe_enabled: bool, adaptive: bool) -> RuntimeSettings {
     RuntimeSettings {
-        openai_client_profile: None,
-        xai_client_profile: None,
+        request_profiles: Default::default(),
         request_location_enabled: false,
         request_location: Default::default(),
         config_revision: revision(1),
@@ -201,6 +200,7 @@ impl AccountProbe for SuccessfulProbe {
     fn probe(
         &self,
         _: AccountProbeRequest,
+        _: Option<Arc<gateway_core::routing::RuntimeSnapshot>>,
     ) -> futures::future::BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
         Box::pin(async {
             Ok(AccountProbeResult {
@@ -216,6 +216,7 @@ impl AccountProbe for FailingProbe {
     fn probe(
         &self,
         _: AccountProbeRequest,
+        _: Option<Arc<gateway_core::routing::RuntimeSnapshot>>,
     ) -> futures::future::BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
         Box::pin(async {
             Err(AccountProbeError::new(
diff --git a/backend/crates/gateway-admin/tests/use_case/mod.rs b/backend/crates/gateway-admin/tests/use_case/mod.rs
index b9dea9e50..d01958718 100644
--- a/backend/crates/gateway-admin/tests/use_case/mod.rs
+++ b/backend/crates/gateway-admin/tests/use_case/mod.rs
@@ -4,14 +4,15 @@ mod auth;
 mod auth_key;
 mod backup;
 mod client_keys;
+mod credentials;
 mod freeze_recovery;
 mod import_tasks;
 mod observability;
-mod openai;
+mod plugin_update;
+mod plugins;
 mod proxies;
 mod settings;
 mod system;
-mod xai;
 
 use std::{
     str::FromStr,
@@ -49,10 +50,10 @@ use gateway_admin::{
         provider_credentials::{
             AuthorizationCommit, AuthorizationStarted, CompleteAuthorization, CredentialDetails,
             CredentialImportCommit, CredentialImportResult, CredentialMutationResult,
-            CredentialRotationCommit, PendingAuthorizationMutation, PrepareCredentialImport,
-            PrepareCredentialRefresh, PrepareCredentialRotation, PreparedAuthorizationCommit,
-            PreparedCredentialImport, PreparedCredentialRotation, ProviderExport,
-            ProviderExportCredentialInput, ProviderModels, ProviderQuota,
+            CredentialRotationCommit, PrepareCredentialImport, PrepareCredentialRefresh,
+            PrepareCredentialRotation, PreparedAuthorizationCommit, PreparedCredentialImport,
+            PreparedCredentialRotation, ProviderExport, ProviderExportCredentialInput,
+            ProviderModels, ProviderQuota,
         },
         settings::{AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RuntimeSettings},
         system::{SystemOperationAccepted, SystemUpdateDetail, SystemUpdateStatus, SystemVersion},
@@ -101,6 +102,8 @@ pub(super) struct AdminHarness {
     providers: Vec<Arc<dyn ProviderAdmin>>,
     probe: Arc<dyn AccountProbe>,
     system: Arc<dyn SystemOperations>,
+    plugin_store: Arc<dyn gateway_admin::ports::plugins::PluginStore>,
+    plugin_inspector: Arc<dyn gateway_admin::ports::plugins::PluginPackageInspector>,
     client_key_verifier: Arc<dyn ClientKeyVerifier>,
 }
 
@@ -126,6 +129,8 @@ impl AdminHarness {
             ],
             probe: Arc::new(UnavailableProbe),
             system: Arc::new(UnavailableSystem),
+            plugin_store: Arc::new(plugins::TestPluginPorts),
+            plugin_inspector: Arc::new(plugins::TestPluginPorts),
             client_key_verifier: Arc::new(UnavailableClientKeyVerifier),
         }
     }
@@ -215,6 +220,16 @@ impl AdminHarness {
         self
     }
 
+    pub(super) fn plugins(
+        mut self,
+        store: Arc<dyn gateway_admin::ports::plugins::PluginStore>,
+        inspector: Arc<dyn gateway_admin::ports::plugins::PluginPackageInspector>,
+    ) -> Self {
+        self.plugin_store = store;
+        self.plugin_inspector = inspector;
+        self
+    }
+
     pub(super) async fn build(self) -> AdminServices {
         self.build_bundle().await.services()
     }
@@ -241,10 +256,20 @@ impl AdminHarness {
                 self.observability,
                 self.settings,
                 self.backup,
+                self.plugin_store,
+                Arc::new(plugins::TestPluginPorts),
             ),
             gateway_admin::AdminRuntimePorts {
+                plugin_preparation: Arc::new(plugins::TestPluginPorts),
+                plugin_management: Arc::new(plugins::TestPluginPorts),
+                published_snapshot: gateway_core::runtime::RuntimeSnapshotHandle::default(),
+                plugin_inspector: self.plugin_inspector,
+                plugin_distribution: Arc::new(plugins::TestPluginPorts),
                 pricing_source: Arc::new(UnavailablePricingSource),
-                providers: self.providers,
+                providers: gateway_admin::ports::provider::ProviderAdminRegistry::new(
+                    self.providers,
+                )
+                .unwrap(),
                 snapshot: Arc::new(NoopSnapshot),
                 account_probe: self.probe,
                 proxy_probe: Arc::new(proxies::TestProxies::default()),
@@ -416,6 +441,13 @@ impl AccountGroupStore for UnavailableAccountGroupStore {
 
 #[async_trait]
 impl AccountStore for UnavailableStore {
+    async fn list_plugin_accounts(
+        &self,
+        _: gateway_admin::model::provider_credentials::PluginAccountListQuery,
+    ) -> AdminStoreResult<gateway_admin::model::provider_credentials::PluginAccountPage> {
+        Err(unavailable("plugin accounts"))
+    }
+
     async fn list_accounts(
         &self,
         _: AccountListQuery,
@@ -462,6 +494,13 @@ impl AccountStore for UnavailableStore {
         Err(unavailable("credential"))
     }
 
+    async fn credential_details_by_id(
+        &self,
+        _: &ProviderAccountId,
+    ) -> AdminStoreResult<Option<CredentialDetails>> {
+        Err(unavailable("credential"))
+    }
+
     async fn load_credentials_for_export(
         &self,
         _: &ProviderKind,
@@ -470,6 +509,13 @@ impl AccountStore for UnavailableStore {
         Err(unavailable("credential export"))
     }
 
+    async fn load_credential_for_plugin(
+        &self,
+        _: &ProviderAccountId,
+    ) -> AdminStoreResult<Option<ProviderExportCredentialInput>> {
+        Err(unavailable("credential export"))
+    }
+
     async fn commit_credential_import(
         &self,
         _: CredentialImportCommit,
@@ -478,11 +524,21 @@ impl AccountStore for UnavailableStore {
         Err(unavailable("credential import"))
     }
 
+    async fn authorization_receipt(
+        &self,
+        _: &gateway_admin::model::provider_credentials::AuthorizationReceiptKey,
+    ) -> AdminStoreResult<
+        Option<gateway_admin::model::provider_credentials::CredentialBatchMutationResult>,
+    > {
+        Err(unavailable("authorization receipt"))
+    }
+
     async fn commit_authorization(
         &self,
         _: AuthorizationCommit,
         _: &MutationContext,
-    ) -> AdminStoreResult<CredentialMutationResult> {
+    ) -> AdminStoreResult<gateway_admin::model::provider_credentials::AuthorizationCommitResult>
+    {
         Err(unavailable("authorization"))
     }
 
@@ -682,6 +738,10 @@ impl ObservabilityStore for UnavailableStore {
         Err(unavailable("usage records"))
     }
 
+    async fn usage_provider_kinds(&self, _: TimeRange) -> AdminStoreResult<Vec<String>> {
+        Err(unavailable("usage providers"))
+    }
+
     async fn usage_record_detail(&self, _: &str) -> AdminStoreResult<UsageDetail> {
         Err(unavailable("usage detail"))
     }
@@ -784,6 +844,10 @@ impl UnavailableProvider {
     }
 }
 
+pub(super) fn test_provider(kind: &str) -> Arc<dyn ProviderAdmin> {
+    Arc::new(UnavailableProvider::new(kind))
+}
+
 #[async_trait]
 impl ProviderAdmin for UnavailableProvider {
     fn provider_kind(&self) -> &ProviderKind {
@@ -792,7 +856,7 @@ impl ProviderAdmin for UnavailableProvider {
 
     async fn account_unavailable(&self, _: &ProviderAccountId) {}
 
-    fn connection_test_operation(
+    async fn connection_test_operation(
         &self,
         _: &gateway_core::routing::UpstreamModelId,
         _: &str,
@@ -823,7 +887,7 @@ impl ProviderAdmin for UnavailableProvider {
 
     async fn start_authorization(
         &self,
-        _: PendingAuthorizationMutation,
+        _: gateway_admin::model::provider_credentials::PrepareAuthorization,
     ) -> Result<AuthorizationStarted, ProviderAdminError> {
         Err(unsupported_provider())
     }
@@ -955,6 +1019,7 @@ impl AccountProbe for UnavailableProbe {
     fn probe(
         &self,
         _: AccountProbeRequest,
+        _: Option<Arc<gateway_core::routing::RuntimeSnapshot>>,
     ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
         Box::pin(async {
             Err(GatewayError::new(
@@ -985,6 +1050,7 @@ impl SystemOperations for UnavailableSystem {
     async fn perform_update(
         &self,
         _: Option<String>,
+        _: Arc<dyn gateway_admin::ports::system::SystemUpdatePreflight>,
     ) -> Result<SystemOperationAccepted, SystemOperationError> {
         Err(unavailable_system())
     }
@@ -993,7 +1059,10 @@ impl SystemOperations for UnavailableSystem {
         Err(unavailable_system())
     }
 
-    async fn rollback(&self) -> Result<SystemOperationAccepted, SystemOperationError> {
+    async fn rollback(
+        &self,
+        _: Arc<dyn gateway_admin::ports::system::SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError> {
         Err(unavailable_system())
     }
 
diff --git a/backend/crates/gateway-admin/tests/use_case/observability.rs b/backend/crates/gateway-admin/tests/use_case/observability.rs
index 37a3fe4d7..1dba81a03 100644
--- a/backend/crates/gateway-admin/tests/use_case/observability.rs
+++ b/backend/crates/gateway-admin/tests/use_case/observability.rs
@@ -750,6 +750,10 @@ impl ObservabilityStore for FixtureObservabilityStore {
         ))
     }
 
+    async fn usage_provider_kinds(&self, _: TimeRange) -> AdminStoreResult<Vec<String>> {
+        Ok(vec!["retired-provider".into()])
+    }
+
     async fn list_usage_records(&self, query: UsageQuery) -> AdminStoreResult<UsagePage> {
         let items = self.usage_records.lock().expect("usage records").clone();
         let total = u64::try_from(items.len()).unwrap_or(u64::MAX);
@@ -808,8 +812,7 @@ impl SettingsStore for FixtureSettingsStore {
     }
     async fn load_runtime_settings(&self) -> AdminStoreResult<RuntimeSettings> {
         Ok(RuntimeSettings {
-            openai_client_profile: None,
-            xai_client_profile: None,
+            request_profiles: Default::default(),
             request_location_enabled: false,
             request_location: Default::default(),
             config_revision: Revision::new(1).expect("revision"),
diff --git a/backend/crates/gateway-admin/tests/use_case/plugin_update.rs b/backend/crates/gateway-admin/tests/use_case/plugin_update.rs
new file mode 100644
index 000000000..4824e769a
--- /dev/null
+++ b/backend/crates/gateway-admin/tests/use_case/plugin_update.rs
@@ -0,0 +1,368 @@
+use std::{collections::BTreeMap, sync::Arc};
+
+use async_trait::async_trait;
+use gateway_admin::{
+    model::{
+        AdminError, MutationContext, Revision,
+        plugins::{
+            InspectedPluginArtifact, InstalledPluginArtifact, PluginArtifactMetadata,
+            PluginArtifactMutation, PluginCompatibilityRequirements, PluginSource,
+            distribution::{PluginSourceBinding, SourceCredential, SourceCredentialInfo},
+            instances::{PluginInstance, PluginInstanceMutation, PluginInstanceSnapshot},
+        },
+        system::{
+            SystemOperationAccepted, SystemOperationState, SystemOperationStatus,
+            SystemUpdateDetail, SystemUpdateStatus, SystemVersion,
+        },
+    },
+    ports::{
+        plugins::{PluginPackageInspector, PluginStore},
+        store::AdminStoreResult,
+        system::{
+            SystemOperationError, SystemOperations, SystemUpdateCandidate, SystemUpdateEventStream,
+            SystemUpdatePreflight,
+        },
+    },
+};
+
+struct Fixture {
+    revisions: std::sync::Mutex<Vec<Revision>>,
+    requirements: PluginCompatibilityRequirements,
+}
+
+impl Fixture {
+    fn new(requirements: PluginCompatibilityRequirements, revisions: &[u64]) -> Arc<Self> {
+        Arc::new(Self {
+            revisions: std::sync::Mutex::new(
+                revisions
+                    .iter()
+                    .map(|revision| Revision::new(*revision).expect("revision"))
+                    .collect(),
+            ),
+            requirements,
+        })
+    }
+
+    fn next_revision(&self) -> Revision {
+        let mut revisions = self.revisions.lock().expect("revisions");
+        if revisions.len() > 1 {
+            revisions.remove(0)
+        } else {
+            *revisions.first().expect("fixture revision")
+        }
+    }
+}
+
+#[async_trait]
+impl PluginPackageInspector for Fixture {
+    async fn inspect(
+        &self,
+        _: Arc<[u8]>,
+        _: Option<String>,
+    ) -> Result<InspectedPluginArtifact, AdminError> {
+        unreachable!()
+    }
+
+    async fn compatibility(
+        &self,
+        _: Arc<[u8]>,
+        expected_sha256: String,
+    ) -> Result<PluginCompatibilityRequirements, AdminError> {
+        assert_eq!(expected_sha256, "a".repeat(64));
+        Ok(self.requirements.clone())
+    }
+}
+
+#[async_trait]
+impl PluginStore for Fixture {
+    async fn management_target_is_current(
+        &self,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+    ) -> AdminStoreResult<bool> {
+        Ok(self
+            .load_instances()
+            .await?
+            .instances
+            .iter()
+            .any(|instance| {
+                instance.enabled
+                    && instance.trusted_process
+                    && instance.id == target.instance_id
+                    && instance.artifact_sha256 == target.artifact_sha256
+                    && instance.revision.get() == target.revision
+            }))
+    }
+    async fn load_instances(&self) -> AdminStoreResult<PluginInstanceSnapshot> {
+        Ok(PluginInstanceSnapshot {
+            config_revision: self.next_revision(),
+            instances: vec![PluginInstance {
+                id: "enabled-fixture".into(),
+                name: "Enabled fixture".into(),
+                artifact_sha256: "a".repeat(64),
+                enabled: true,
+                trusted_process: true,
+                configuration: serde_json::json!({}),
+                secrets: BTreeMap::new(),
+                grants: Vec::new(),
+                bindings: Vec::new(),
+                revision: Revision::new(1).expect("revision"),
+            }],
+        })
+    }
+
+    async fn load_artifact(&self, digest: &str) -> AdminStoreResult<InspectedPluginArtifact> {
+        assert_eq!(digest, "a".repeat(64));
+        Ok(InspectedPluginArtifact {
+            metadata: PluginArtifactMetadata {
+                plugin_id: "test.fixture".into(),
+                version: "1.0.0".into(),
+                name: "fixture".into(),
+                display_name: "Fixture".into(),
+                publisher: "test".into(),
+                author: Some("project".into()),
+                description: "fixture".into(),
+                license: "MIT".into(),
+                sha256: digest.into(),
+                platforms: Vec::new(),
+                icon: None,
+                contributes: BTreeMap::new(),
+                requested_permissions: Vec::new(),
+                configuration_schema: serde_json::json!({}),
+                secret_fields: Vec::new(),
+                state_namespaces: Vec::new(),
+            },
+            archive: Arc::from([1_u8]),
+        })
+    }
+
+    async fn save_instance(
+        &self,
+        _: PluginInstance,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        unreachable!()
+    }
+
+    async fn delete_instance(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+
+    async fn list_update_sources(&self) -> AdminStoreResult<Vec<PluginSourceBinding>> {
+        unreachable!()
+    }
+
+    async fn change_update_source(
+        &self,
+        _: PluginSourceBinding,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+
+    async fn list_source_credentials(&self) -> AdminStoreResult<Vec<SourceCredentialInfo>> {
+        unreachable!()
+    }
+
+    async fn load_source_credential(&self, _: &str) -> AdminStoreResult<SourceCredential> {
+        unreachable!()
+    }
+
+    async fn save_source_credential(
+        &self,
+        _: SourceCredential,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+
+    async fn delete_source_credential(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+
+    async fn list_artifacts(&self) -> AdminStoreResult<Vec<InstalledPluginArtifact>> {
+        unreachable!()
+    }
+
+    async fn install_artifact(
+        &self,
+        _: InspectedPluginArtifact,
+        _: PluginSource,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        unreachable!()
+    }
+
+    async fn accept_artifact(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        unreachable!()
+    }
+
+    async fn delete_artifact(&self, _: &str, _: &MutationContext) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+}
+
+struct PreflightingSystem {
+    candidate: SystemUpdateCandidate,
+}
+
+#[async_trait]
+impl SystemOperations for PreflightingSystem {
+    async fn version(&self) -> Result<SystemVersion, SystemOperationError> {
+        unreachable!()
+    }
+
+    async fn update_detail(&self, _: bool) -> Result<SystemUpdateDetail, SystemOperationError> {
+        unreachable!()
+    }
+
+    fn update_events(&self) -> SystemUpdateEventStream {
+        Box::pin(futures::stream::empty())
+    }
+
+    async fn perform_update(
+        &self,
+        _: Option<String>,
+        preflight: Arc<dyn SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError> {
+        let revision = preflight.validate(self.candidate.clone()).await?;
+        preflight.confirm_revision(revision).await?;
+        Ok(SystemOperationAccepted::Update {
+            operation_id: "fixture".into(),
+            deployment_mode: "fixture".into(),
+            message: "accepted".into(),
+            target_version: self.candidate.target_version.clone(),
+        })
+    }
+
+    async fn update_status(&self) -> Result<SystemUpdateStatus, SystemOperationError> {
+        Ok(SystemUpdateStatus {
+            previous_version: None,
+            current_version: None,
+            need_restart: false,
+            operation: SystemOperationState {
+                operation_id: None,
+                kind: None,
+                status: SystemOperationStatus::Idle,
+                target_version: None,
+                message: None,
+                error: None,
+                started_at: None,
+                finished_at: None,
+            },
+        })
+    }
+
+    async fn rollback(
+        &self,
+        _: Arc<dyn SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError> {
+        unreachable!()
+    }
+
+    async fn restart(&self) -> Result<SystemOperationAccepted, SystemOperationError> {
+        unreachable!()
+    }
+}
+
+#[tokio::test]
+async fn system_update_accepts_compatible_enabled_plugins_at_the_same_revision() {
+    let fixture = Fixture::new(requirements("^1.0", "executor", "log"), &[7]);
+    let services = super::AdminHarness::new()
+        .plugins(fixture.clone(), fixture)
+        .system(Arc::new(PreflightingSystem {
+            candidate: candidate("executor", "log"),
+        }))
+        .build()
+        .await;
+
+    services
+        .system()
+        .perform_update(Some("1.2.0".into()))
+        .await
+        .expect("compatible update");
+}
+
+#[tokio::test]
+async fn system_update_rejects_missing_target_capability_and_revision_changes() {
+    let incompatible = Fixture::new(requirements("^1.0", "executor", "log"), &[7]);
+    let services = super::AdminHarness::new()
+        .plugins(incompatible.clone(), incompatible)
+        .system(Arc::new(PreflightingSystem {
+            candidate: candidate("models", "log"),
+        }))
+        .build()
+        .await;
+    assert!(
+        services
+            .system()
+            .perform_update(Some("1.2.0".into()))
+            .await
+            .is_err()
+    );
+
+    let stale = Fixture::new(requirements("^1.0", "executor", "log"), &[7, 8]);
+    let services = super::AdminHarness::new()
+        .plugins(stale.clone(), stale)
+        .system(Arc::new(PreflightingSystem {
+            candidate: candidate("executor", "log"),
+        }))
+        .build()
+        .await;
+    assert!(
+        services
+            .system()
+            .perform_update(Some("1.2.0".into()))
+            .await
+            .is_err()
+    );
+}
+
+fn requirements(
+    host_version: &str,
+    capability: &str,
+    permission: &str,
+) -> PluginCompatibilityRequirements {
+    PluginCompatibilityRequirements {
+        host_version: host_version.into(),
+        manifest_schema_version: 2,
+        protocol_version: 3,
+        capabilities: vec![(capability.into(), 1)],
+        permissions: vec![permission.into()],
+    }
+}
+
+fn candidate(capability: &str, permission: &str) -> SystemUpdateCandidate {
+    let manifest = serde_json::to_vec(&serde_json::json!({
+        "schema_version": 1,
+        "sealed": true,
+        "gateway_version": "1.2.0",
+        "gateway_git_sha": "a".repeat(40),
+        "plugin_host": {
+            "schema_version": 1,
+            "manifest_schema_versions": [2],
+            "protocol_versions": [3],
+            "capabilities": [{ "capability": capability, "versions": [1] }],
+            "permissions": [permission],
+        },
+        "plugins": [],
+    }))
+    .expect("manifest");
+    SystemUpdateCandidate {
+        target_version: "1.2.0".into(),
+        release_manifest: manifest.into(),
+    }
+}
diff --git a/backend/crates/gateway-admin/tests/use_case/plugins/artifacts.rs b/backend/crates/gateway-admin/tests/use_case/plugins/artifacts.rs
new file mode 100644
index 000000000..462a1928f
--- /dev/null
+++ b/backend/crates/gateway-admin/tests/use_case/plugins/artifacts.rs
@@ -0,0 +1,439 @@
+use std::{
+    collections::BTreeMap,
+    sync::{Arc, Mutex},
+};
+
+use async_trait::async_trait;
+use futures::future::BoxFuture;
+use gateway_admin::{
+    PluginDistributionPorts, PluginsService,
+    model::{
+        AdminError, MutationActor, MutationContext, Revision,
+        plugins::{
+            InspectedPluginArtifact, InstalledPluginArtifact, PluginArtifactMetadata,
+            PluginArtifactMutation, PluginContribution, PluginSource,
+            distribution::{PluginSourceBinding, SourceCredential, SourceCredentialInfo},
+            instances::{PluginInstance, PluginInstanceMutation, PluginInstanceSnapshot},
+            state::PluginStateConfiguration,
+        },
+    },
+    ports::{
+        plugins::{PluginPreparation, PluginStore},
+        store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult},
+    },
+};
+use gateway_core::{
+    routing::ConfigRevision,
+    runtime::{
+        RuntimeSnapshotHandle, SnapshotControl,
+        extensions::{ExtensionSetId, ExtensionSetLease, ExtensionSetReference},
+    },
+};
+use serde_json::json;
+
+use super::TestPluginPorts;
+
+const DIGEST: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+
+struct FixtureData {
+    artifact: InstalledPluginArtifact,
+    snapshot: PluginInstanceSnapshot,
+    saves: usize,
+    publications: Vec<u64>,
+}
+
+struct Fixture {
+    data: Mutex<FixtureData>,
+}
+
+impl Fixture {
+    fn new(metadata: PluginArtifactMetadata, existing: Option<PluginInstance>) -> Arc<Self> {
+        Arc::new(Self {
+            data: Mutex::new(FixtureData {
+                artifact: InstalledPluginArtifact {
+                    metadata,
+                    source: PluginSource::Upload,
+                    installed_at: chrono::Utc::now(),
+                    accepted_at: None,
+                },
+                snapshot: PluginInstanceSnapshot {
+                    config_revision: revision(1),
+                    instances: existing.into_iter().collect(),
+                },
+                saves: 0,
+                publications: Vec::new(),
+            }),
+        })
+    }
+
+    fn service(self: &Arc<Self>) -> PluginsService {
+        let unused = Arc::new(TestPluginPorts);
+        PluginsService::new(
+            self.clone(),
+            unused.clone(),
+            PluginDistributionPorts::new(unused.clone(), unused.clone()),
+            self.clone(),
+            self.clone(),
+            RuntimeSnapshotHandle::default(),
+            unused,
+        )
+    }
+}
+
+impl SnapshotControl for Fixture {
+    fn publish_committed(&self, revision: ConfigRevision) -> BoxFuture<'_, ()> {
+        self.data.lock().unwrap().publications.push(revision.get());
+        Box::pin(async {})
+    }
+}
+
+struct Lease;
+
+impl ExtensionSetLease for Lease {
+    fn is_ready(&self) -> bool {
+        true
+    }
+}
+
+#[async_trait]
+impl PluginPreparation for Fixture {
+    async fn configuration_ready(
+        &self,
+        instance: PluginInstance,
+        _: &gateway_admin::model::plugins::PluginArtifactMetadata,
+    ) -> Result<bool, AdminError> {
+        Ok(instance
+            .configuration
+            .get("requiredName")
+            .is_some_and(serde_json::Value::is_string))
+    }
+
+    async fn validate(&self, _: PluginInstance) -> Result<PluginStateConfiguration, AdminError> {
+        Ok(PluginStateConfiguration {
+            namespaces: Vec::new(),
+        })
+    }
+
+    async fn prepare(
+        &self,
+        source_revision: Revision,
+        _: PluginInstanceSnapshot,
+    ) -> Result<ExtensionSetReference, AdminError> {
+        if source_revision != self.data.lock().unwrap().snapshot.config_revision {
+            return Err(AdminError::conflict("fixture configuration changed"));
+        }
+        Ok(ExtensionSetReference::new(
+            ExtensionSetId::new("install-fixture".into()).unwrap(),
+            Arc::new(Lease),
+        ))
+    }
+}
+
+#[async_trait]
+impl PluginStore for Fixture {
+    async fn management_target_is_current(
+        &self,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+    ) -> AdminStoreResult<bool> {
+        Ok(self
+            .load_instances()
+            .await?
+            .instances
+            .iter()
+            .any(|instance| {
+                instance.enabled
+                    && instance.trusted_process
+                    && instance.id == target.instance_id
+                    && instance.artifact_sha256 == target.artifact_sha256
+                    && instance.revision.get() == target.revision
+            }))
+    }
+    async fn load_instances(&self) -> AdminStoreResult<PluginInstanceSnapshot> {
+        Ok(self.data.lock().unwrap().snapshot.clone())
+    }
+
+    async fn save_instance(
+        &self,
+        mut instance: PluginInstance,
+        expected_revision: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        let mut data = self.data.lock().unwrap();
+        if data.snapshot.config_revision != expected_revision {
+            return Err(store_error(AdminStoreErrorKind::Conflict));
+        }
+        let next = revision(expected_revision.get() + 1);
+        instance.revision = next;
+        data.snapshot.config_revision = next;
+        data.snapshot
+            .instances
+            .retain(|current| current.id != instance.id);
+        data.snapshot.instances.push(instance.clone());
+        data.saves += 1;
+        Ok(PluginInstanceMutation {
+            config_revision: next,
+            instance,
+        })
+    }
+
+    async fn delete_instance(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(store_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn list_update_sources(&self) -> AdminStoreResult<Vec<PluginSourceBinding>> {
+        Ok(Vec::new())
+    }
+
+    async fn change_update_source(
+        &self,
+        _: PluginSourceBinding,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(store_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn list_source_credentials(&self) -> AdminStoreResult<Vec<SourceCredentialInfo>> {
+        Ok(Vec::new())
+    }
+
+    async fn load_source_credential(&self, _: &str) -> AdminStoreResult<SourceCredential> {
+        Err(store_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn save_source_credential(
+        &self,
+        _: SourceCredential,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(store_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn delete_source_credential(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(store_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn list_artifacts(&self) -> AdminStoreResult<Vec<InstalledPluginArtifact>> {
+        Ok(vec![self.data.lock().unwrap().artifact.clone()])
+    }
+
+    async fn load_artifact(&self, _: &str) -> AdminStoreResult<InspectedPluginArtifact> {
+        Err(store_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn install_artifact(
+        &self,
+        _: InspectedPluginArtifact,
+        _: PluginSource,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        Err(store_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn accept_artifact(
+        &self,
+        digest: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        let mut data = self.data.lock().unwrap();
+        if data.artifact.metadata.sha256 != digest {
+            return Err(store_error(AdminStoreErrorKind::NotFound));
+        }
+        if data.artifact.accepted_at.is_none() {
+            data.artifact.accepted_at = Some(chrono::Utc::now());
+            data.snapshot.config_revision = revision(data.snapshot.config_revision.get() + 1);
+        }
+        Ok(PluginArtifactMutation {
+            config_revision: data.snapshot.config_revision,
+            artifact: data.artifact.clone(),
+        })
+    }
+
+    async fn delete_artifact(&self, _: &str, _: &MutationContext) -> AdminStoreResult<Revision> {
+        Err(store_error(AdminStoreErrorKind::Unavailable))
+    }
+}
+
+#[tokio::test]
+async fn acceptance_creates_one_stable_default_instance_with_defaults_and_bindings() {
+    let fixture = Fixture::new(metadata(true), None);
+    let service = fixture.service();
+
+    let first = service.accept_artifact(DIGEST, &context()).await.unwrap();
+    let repeated = service.accept_artifact(DIGEST, &context()).await.unwrap();
+    assert_eq!(first.default_instance_id, repeated.default_instance_id);
+    assert!(!first.configuration_required);
+    assert!(!repeated.configuration_required);
+
+    let data = fixture.data.lock().unwrap();
+    assert_eq!(data.saves, 1, "同一摘要重试不能复制默认实例");
+    assert_eq!(data.snapshot.instances.len(), 1);
+    let instance = &data.snapshot.instances[0];
+    assert_eq!(
+        Some(instance.id.as_str()),
+        first.default_instance_id.as_deref()
+    );
+    assert!(instance.enabled);
+    assert_eq!(instance.configuration["mode"], "safe");
+    assert_eq!(instance.configuration["nested"]["limit"], 3);
+    assert_eq!(instance.configuration["requiredName"], "ready");
+    assert!(instance.configuration.get("token").is_none());
+    assert_eq!(
+        instance
+            .bindings
+            .iter()
+            .map(|binding| (
+                binding.contribution.as_str(),
+                binding.stage.as_str(),
+                &binding.failure_policy,
+            ))
+            .collect::<Vec<_>>(),
+        [
+            (
+                "test.example.middleware",
+                "observation",
+                &gateway_admin::model::plugins::instances::PluginFailurePolicy::Observe,
+            ),
+            (
+                "test.example.middleware",
+                "request",
+                &gateway_admin::model::plugins::instances::PluginFailurePolicy::Reject,
+            ),
+        ]
+    );
+    assert!(instance.bindings.iter().all(|binding| !matches!(
+        binding.contribution.as_str(),
+        "test.example.auth" | "test.example.cli" | "test.example.management"
+    )));
+}
+
+#[tokio::test]
+async fn missing_required_configuration_creates_a_disabled_pending_instance() {
+    let fixture = Fixture::new(metadata(false), None);
+    let result = fixture
+        .service()
+        .accept_artifact(DIGEST, &context())
+        .await
+        .unwrap();
+    assert!(result.configuration_required);
+    assert!(result.default_instance_id.is_some());
+    let data = fixture.data.lock().unwrap();
+    assert_eq!(data.snapshot.instances.len(), 1);
+    assert!(!data.snapshot.instances[0].enabled);
+}
+
+#[tokio::test]
+async fn existing_plugin_instance_prevents_an_extra_default_instance() {
+    let metadata = metadata(true);
+    let existing = PluginInstance {
+        id: uuid::Uuid::now_v7().to_string(),
+        name: "Existing".into(),
+        artifact_sha256: metadata.sha256.clone(),
+        enabled: false,
+        trusted_process: false,
+        configuration: json!({}),
+        secrets: BTreeMap::new(),
+        grants: Vec::new(),
+        bindings: Vec::new(),
+        revision: revision(1),
+    };
+    let fixture = Fixture::new(metadata, Some(existing));
+    let result = fixture
+        .service()
+        .accept_artifact(DIGEST, &context())
+        .await
+        .unwrap();
+    assert_eq!(result.default_instance_id, None);
+    let data = fixture.data.lock().unwrap();
+    assert_eq!(data.saves, 0);
+    assert_eq!(data.snapshot.instances.len(), 1);
+}
+
+fn metadata(with_required_default: bool) -> PluginArtifactMetadata {
+    let required_name = if with_required_default {
+        json!({"type":"string","default":"ready"})
+    } else {
+        json!({"type":"string"})
+    };
+    PluginArtifactMetadata {
+        plugin_id: "test.example".into(),
+        version: "1.0.0".into(),
+        name: "example".into(),
+        display_name: "Example".into(),
+        publisher: "test".into(),
+        author: None,
+        description: "fixture".into(),
+        license: "MIT".into(),
+        sha256: DIGEST.into(),
+        platforms: vec!["linux-x86_64".into()],
+        icon: None,
+        contributes: BTreeMap::from([
+            (
+                "command_line".into(),
+                contribution("test.example.cli", &["command"]),
+            ),
+            (
+                "frontend_authentication".into(),
+                contribution("test.example.auth", &["authentication"]),
+            ),
+            (
+                "management".into(),
+                contribution("test.example.management", &["management"]),
+            ),
+            (
+                "middleware".into(),
+                contribution("test.example.middleware", &["observation", "request"]),
+            ),
+        ]),
+        requested_permissions: vec!["network".into()],
+        configuration_schema: json!({
+            "type":"object",
+            "properties": {
+                "mode": {"type":"string","default":"safe"},
+                "nested": {
+                    "type":"object",
+                    "default": {},
+                    "properties": {"limit":{"type":"integer","default":3}}
+                },
+                "requiredName": required_name,
+                "token": {"type":"string","default":"never-copy-secret"}
+            },
+            "required":["requiredName"]
+        }),
+        secret_fields: vec!["token".into()],
+        state_namespaces: Vec::new(),
+    }
+}
+
+fn contribution(id: &str, stages: &[&str]) -> PluginContribution {
+    PluginContribution {
+        id: id.into(),
+        version: 1,
+        stages: stages.iter().map(|stage| (*stage).into()).collect(),
+        input_formats: Vec::new(),
+        output_formats: Vec::new(),
+    }
+}
+
+fn revision(value: u64) -> Revision {
+    Revision::new(value).unwrap()
+}
+
+fn context() -> MutationContext {
+    MutationContext {
+        actor: MutationActor::System,
+        request_id: "install-fixture".into(),
+    }
+}
+
+fn store_error(kind: AdminStoreErrorKind) -> AdminStoreError {
+    AdminStoreError::new(kind, "plugin", "install fixture")
+}
diff --git a/backend/crates/gateway-admin/tests/use_case/plugins/distribution.rs b/backend/crates/gateway-admin/tests/use_case/plugins/distribution.rs
new file mode 100644
index 000000000..4aca3a2eb
--- /dev/null
+++ b/backend/crates/gateway-admin/tests/use_case/plugins/distribution.rs
@@ -0,0 +1,766 @@
+use std::sync::{Arc, Mutex};
+
+use async_trait::async_trait;
+use futures::future::BoxFuture;
+use gateway_admin::{
+    PluginDistributionPorts, PluginsService,
+    model::{
+        AdminError, AdminErrorKind, MutationActor, MutationContext, Revision,
+        plugins::{
+            InspectedPluginArtifact, InstalledPluginArtifact, PluginArtifactMetadata,
+            PluginArtifactMutation, PluginSource, PluginSourceEgress,
+            distribution::{
+                DownloadedPlugin, GithubReleaseQuery, PluginDistributionEgress, PluginRelease,
+                PluginSourceBinding, PluginUpdatePolicy, PluginUpdateSource, RemotePluginInstall,
+                RemotePluginLocation, RemotePluginVerify, SourceCredential, SourceCredentialInfo,
+            },
+            instances::{PluginInstance, PluginInstanceMutation, PluginInstanceSnapshot},
+        },
+        proxies::{
+            NewProxy, ProxyAccountListQuery, ProxyAccountPage, ProxyListQuery, ProxyMutation,
+            ProxyPage, ProxyRecord, ProxyTestResult, UpdateProxy,
+        },
+    },
+    ports::{
+        plugins::{PluginDistribution, PluginPackageInspector, PluginStore},
+        proxy::{ProxyImportReservation, ProxyStore},
+        store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult},
+    },
+};
+use gateway_core::{
+    account::{OutboundProxy, ProviderAccountId},
+    routing::ConfigRevision,
+    runtime::{RuntimeSnapshotHandle, SnapshotControl},
+};
+
+use super::TestPluginPorts;
+
+struct Fixture {
+    binding: Mutex<PluginSourceBinding>,
+    queries: Mutex<Vec<GithubReleaseQuery>>,
+    publications: Mutex<Vec<u64>>,
+    changes: Mutex<usize>,
+    query_fails: bool,
+    change_during_query: bool,
+    package: Option<InspectedPluginArtifact>,
+    downloads: Mutex<usize>,
+    change_during_download: bool,
+    proxy: Mutex<Option<ProxyRecord>>,
+    egresses: Mutex<Vec<Option<PluginSourceEgress>>>,
+    change_proxy_during_download: bool,
+}
+
+impl Fixture {
+    fn new(policy: PluginUpdatePolicy) -> Self {
+        Self {
+            binding: Mutex::new(PluginSourceBinding {
+                plugin_id: "test.example".into(),
+                source: PluginUpdateSource::Github {
+                    repository: "owner/plugin".into(),
+                },
+                policy,
+                outbound_proxy_id: None,
+            }),
+            queries: Mutex::new(vec![]),
+            publications: Mutex::new(vec![]),
+            changes: Mutex::new(0),
+            query_fails: false,
+            change_during_query: false,
+            package: None,
+            downloads: Mutex::new(0),
+            change_during_download: false,
+            proxy: Mutex::new(None),
+            egresses: Mutex::new(vec![]),
+            change_proxy_during_download: false,
+        }
+    }
+
+    fn service(self: &Arc<Self>) -> PluginsService {
+        let unused = Arc::new(TestPluginPorts);
+        PluginsService::new(
+            self.clone(),
+            self.clone(),
+            PluginDistributionPorts::new(self.clone(), self.clone()),
+            self.clone(),
+            unused.clone(),
+            RuntimeSnapshotHandle::default(),
+            unused,
+        )
+    }
+}
+
+impl SnapshotControl for Fixture {
+    fn publish_committed(&self, revision: ConfigRevision) -> BoxFuture<'_, ()> {
+        self.publications.lock().unwrap().push(revision.get());
+        Box::pin(async {})
+    }
+}
+
+#[async_trait]
+impl ProxyStore for Fixture {
+    async fn reserve_import(&self, _: &str) -> AdminStoreResult<ProxyImportReservation> {
+        unreachable!()
+    }
+
+    async fn list(&self, _: ProxyListQuery) -> AdminStoreResult<ProxyPage> {
+        unreachable!()
+    }
+
+    async fn list_accounts(&self, _: ProxyAccountListQuery) -> AdminStoreResult<ProxyAccountPage> {
+        unreachable!()
+    }
+
+    async fn get(&self, id: &str) -> AdminStoreResult<ProxyRecord> {
+        self.proxy
+            .lock()
+            .unwrap()
+            .as_ref()
+            .filter(|record| record.id == id)
+            .cloned()
+            .ok_or_else(|| {
+                AdminStoreError::new(AdminStoreErrorKind::NotFound, "proxy", "fixture not found")
+            })
+    }
+
+    async fn remove_account(
+        &self,
+        _: &str,
+        _: &ProviderAccountId,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+
+    async fn create(&self, _: NewProxy, _: &MutationContext) -> AdminStoreResult<ProxyMutation> {
+        unreachable!()
+    }
+
+    async fn update(&self, _: UpdateProxy, _: &MutationContext) -> AdminStoreResult<ProxyMutation> {
+        unreachable!()
+    }
+
+    async fn delete(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+
+    async fn record_test(
+        &self,
+        _: &str,
+        _: Revision,
+        _: ProxyTestResult,
+        _: &MutationContext,
+    ) -> AdminStoreResult<ProxyRecord> {
+        unreachable!()
+    }
+}
+
+#[async_trait]
+impl PluginDistribution for Fixture {
+    fn validate_source(&self, _: &PluginUpdateSource) -> Result<(), AdminError> {
+        Ok(())
+    }
+    fn validate_credential(&self, _: &SourceCredential) -> Result<(), AdminError> {
+        unreachable!()
+    }
+    async fn query_release(
+        &self,
+        query: GithubReleaseQuery,
+        credentials: Vec<SourceCredential>,
+        egress: Option<PluginDistributionEgress>,
+    ) -> Result<PluginRelease, AdminError> {
+        assert!(credentials.is_empty());
+        self.egresses
+            .lock()
+            .unwrap()
+            .push(egress.map(|egress| egress.source));
+        self.queries.lock().unwrap().push(query.clone());
+        if self.query_fails {
+            return Err(AdminError::unavailable("fixture rate limited"));
+        }
+        if self.change_during_query {
+            self.binding.lock().unwrap().policy = PluginUpdatePolicy::Manual {};
+        }
+        Ok(PluginRelease {
+            repository: query.repository,
+            tag: query.tag.unwrap_or_else(|| "v2.0.0".into()),
+            name: "fixture".into(),
+            prerelease: query.allow_prerelease,
+            assets: vec![],
+            queried_at: chrono::Utc::now(),
+            expires_at: chrono::Utc::now(),
+        })
+    }
+    async fn download(
+        &self,
+        location: RemotePluginLocation,
+        _: Vec<SourceCredential>,
+        egress: Option<PluginDistributionEgress>,
+    ) -> Result<DownloadedPlugin, AdminError> {
+        let outbound_proxy = egress.as_ref().map(|egress| egress.source.clone());
+        self.egresses.lock().unwrap().push(outbound_proxy.clone());
+        let package = self.package.as_ref().expect("检查更新不能下载产物");
+        *self.downloads.lock().unwrap() += 1;
+        if self.change_during_download {
+            self.binding.lock().unwrap().policy = PluginUpdatePolicy::Manual {};
+        }
+        if self.change_proxy_during_download {
+            self.proxy.lock().unwrap().as_mut().unwrap().revision = Revision::new(2).unwrap();
+        }
+        let RemotePluginLocation::Github {
+            repository,
+            tag,
+            asset,
+            ..
+        } = location
+        else {
+            unreachable!()
+        };
+        Ok(DownloadedPlugin {
+            archive: package.archive.clone(),
+            sha256: package.metadata.sha256.clone(),
+            source: PluginSource::Github {
+                repository: repository.to_ascii_lowercase(),
+                tag,
+                asset,
+                credential_ids: vec![],
+                outbound_proxy,
+            },
+        })
+    }
+}
+
+#[async_trait]
+impl PluginPackageInspector for Fixture {
+    async fn inspect(
+        &self,
+        archive: Arc<[u8]>,
+        expected_sha256: Option<String>,
+    ) -> Result<InspectedPluginArtifact, AdminError> {
+        let package = self.package.as_ref().expect("检查 Release 不能校验插件包");
+        assert_eq!(archive, package.archive);
+        if let Some(digest) = expected_sha256 {
+            assert_eq!(digest, package.metadata.sha256);
+        }
+        Ok(package.clone())
+    }
+}
+
+#[async_trait]
+impl PluginStore for Fixture {
+    async fn management_target_is_current(
+        &self,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+    ) -> AdminStoreResult<bool> {
+        Ok(self
+            .load_instances()
+            .await?
+            .instances
+            .iter()
+            .any(|instance| {
+                instance.enabled
+                    && instance.trusted_process
+                    && instance.id == target.instance_id
+                    && instance.artifact_sha256 == target.artifact_sha256
+                    && instance.revision.get() == target.revision
+            }))
+    }
+    async fn list_update_sources(&self) -> AdminStoreResult<Vec<PluginSourceBinding>> {
+        Ok(vec![self.binding.lock().unwrap().clone()])
+    }
+    async fn change_update_source(
+        &self,
+        binding: PluginSourceBinding,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        *self.binding.lock().unwrap() = binding;
+        *self.changes.lock().unwrap() += 1;
+        Ok(Revision::new(2).unwrap())
+    }
+    async fn load_instances(&self) -> AdminStoreResult<PluginInstanceSnapshot> {
+        unreachable!()
+    }
+    async fn save_instance(
+        &self,
+        _: PluginInstance,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        unreachable!()
+    }
+    async fn delete_instance(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+    async fn list_source_credentials(&self) -> AdminStoreResult<Vec<SourceCredentialInfo>> {
+        unreachable!()
+    }
+    async fn load_source_credential(&self, _: &str) -> AdminStoreResult<SourceCredential> {
+        Err(super::unavailable())
+    }
+    async fn save_source_credential(
+        &self,
+        _: SourceCredential,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+    async fn delete_source_credential(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+    async fn list_artifacts(&self) -> AdminStoreResult<Vec<InstalledPluginArtifact>> {
+        unreachable!()
+    }
+    async fn load_artifact(&self, _: &str) -> AdminStoreResult<InspectedPluginArtifact> {
+        unreachable!()
+    }
+    async fn install_artifact(
+        &self,
+        _: InspectedPluginArtifact,
+        _: PluginSource,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        panic!("检查更新不能安装产物")
+    }
+    async fn accept_artifact(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        unreachable!()
+    }
+    async fn delete_artifact(&self, _: &str, _: &MutationContext) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+}
+
+fn context() -> MutationContext {
+    MutationContext {
+        actor: MutationActor::System,
+        request_id: "plugin-update-test".into(),
+    }
+}
+
+#[tokio::test]
+async fn update_check_uses_persisted_policy_without_downloading_writing_or_publishing() {
+    for (policy, tag, prerelease) in [
+        (PluginUpdatePolicy::Stable {}, None, false),
+        (
+            PluginUpdatePolicy::Pinned {
+                tag: "v2.0.0-rc.1".into(),
+                allow_prerelease: true,
+            },
+            Some("v2.0.0-rc.1"),
+            true,
+        ),
+    ] {
+        let fixture = Arc::new(Fixture::new(policy.clone()));
+        let check = fixture
+            .service()
+            .check_update("test.example", &[])
+            .await
+            .unwrap();
+        assert_eq!(check.binding.policy, policy);
+        assert_eq!(
+            fixture.queries.lock().unwrap().as_slice(),
+            &[GithubReleaseQuery {
+                repository: "owner/plugin".into(),
+                tag: tag.map(str::to_owned),
+                allow_prerelease: prerelease,
+            }]
+        );
+        assert_eq!(*fixture.changes.lock().unwrap(), 0);
+        assert!(fixture.publications.lock().unwrap().is_empty());
+    }
+}
+
+#[tokio::test]
+async fn update_check_never_turns_query_failure_or_changed_source_into_no_updates() {
+    for changed in [false, true] {
+        let mut fixture = Fixture::new(PluginUpdatePolicy::Stable {});
+        fixture.query_fails = !changed;
+        fixture.change_during_query = changed;
+        let fixture = Arc::new(fixture);
+        let error = fixture
+            .service()
+            .check_update("test.example", &[])
+            .await
+            .unwrap_err();
+        assert_eq!(
+            error.kind(),
+            if changed {
+                AdminErrorKind::Conflict
+            } else {
+                AdminErrorKind::Unavailable
+            }
+        );
+        assert!(fixture.publications.lock().unwrap().is_empty());
+    }
+}
+
+#[tokio::test]
+async fn update_check_rejects_manual_missing_and_duplicate_credential_selections_before_query() {
+    let fixture = Arc::new(Fixture::new(PluginUpdatePolicy::Manual {}));
+    assert_eq!(
+        fixture
+            .service()
+            .check_update("test.example", &[])
+            .await
+            .unwrap_err()
+            .kind(),
+        AdminErrorKind::Invalid
+    );
+    assert_eq!(
+        fixture
+            .service()
+            .check_update("missing", &[])
+            .await
+            .unwrap_err()
+            .kind(),
+        AdminErrorKind::NotFound
+    );
+    fixture.binding.lock().unwrap().policy = PluginUpdatePolicy::Stable {};
+    assert_eq!(
+        fixture
+            .service()
+            .check_update("test.example", &["same".into(), "same".into()])
+            .await
+            .unwrap_err()
+            .kind(),
+        AdminErrorKind::Invalid
+    );
+    assert!(fixture.queries.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn changing_source_validates_policy_and_publishes_only_explicit_valid_changes() {
+    let fixture = Arc::new(Fixture::new(PluginUpdatePolicy::Manual {}));
+    let original = fixture.binding.lock().unwrap().clone();
+    for (source, policy) in [
+        (PluginUpdateSource::Upload, PluginUpdatePolicy::Stable {}),
+        (PluginUpdateSource::Builtin, PluginUpdatePolicy::Manual {}),
+        (
+            original.source.clone(),
+            PluginUpdatePolicy::Pinned {
+                tag: " ".into(),
+                allow_prerelease: false,
+            },
+        ),
+    ] {
+        let error = fixture
+            .service()
+            .change_update_source(
+                PluginSourceBinding {
+                    plugin_id: "test.example".into(),
+                    source,
+                    policy,
+                    outbound_proxy_id: None,
+                },
+                &context(),
+            )
+            .await
+            .unwrap_err();
+        assert_eq!(error.kind(), AdminErrorKind::Invalid);
+    }
+    assert_eq!(*fixture.changes.lock().unwrap(), 0);
+    let binding = PluginSourceBinding {
+        plugin_id: "test.example".into(),
+        source: PluginUpdateSource::Github {
+            repository: "Owner/Plugin".into(),
+        },
+        policy: PluginUpdatePolicy::Stable {},
+        outbound_proxy_id: None,
+    };
+    fixture
+        .service()
+        .change_update_source(binding, &context())
+        .await
+        .unwrap();
+    assert_eq!(fixture.binding.lock().unwrap().source, original.source);
+    assert_eq!(*fixture.changes.lock().unwrap(), 1);
+    assert_eq!(fixture.publications.lock().unwrap().as_slice(), &[2]);
+}
+
+#[test]
+fn existing_source_payload_defaults_to_manual_and_rejects_unknown_policy_fields() {
+    let binding: PluginSourceBinding = serde_json::from_value(
+        serde_json::json!({"pluginId":"test.example","source":{"kind":"upload"}}),
+    )
+    .unwrap();
+    assert_eq!(binding.policy, PluginUpdatePolicy::Manual {});
+    assert!(serde_json::from_value::<PluginSourceBinding>(serde_json::json!({"pluginId":"test.example","source":{"kind":"github","repository":"owner/plugin"},"policy":{"kind":"stable","autoInstall":true}})).is_err());
+}
+
+fn preview_fixture() -> Fixture {
+    let mut fixture = Fixture::new(PluginUpdatePolicy::Stable {});
+    fixture.package = Some(InspectedPluginArtifact {
+        metadata: PluginArtifactMetadata {
+            plugin_id: "test.example".into(),
+            version: "2.0.0".into(),
+            name: "example".into(),
+            display_name: "Example".into(),
+            publisher: "test".into(),
+            author: Some("Tests".into()),
+            description: String::new(),
+            license: "MIT".into(),
+            sha256: "a".repeat(64),
+            platforms: vec!["linux-x86_64".into()],
+            icon: None,
+            contributes: Default::default(),
+            requested_permissions: vec!["log".into()],
+            configuration_schema: serde_json::json!({"type":"object"}),
+            secret_fields: vec![],
+            state_namespaces: vec![],
+        },
+        archive: b"bounded archive fixture".as_slice().into(),
+    });
+    fixture
+}
+
+fn source_proxy() -> ProxyRecord {
+    let now = chrono::Utc::now();
+    ProxyRecord {
+        location: None,
+        id: "source-proxy".into(),
+        name: "Source proxy".into(),
+        proxy: OutboundProxy::parse("http://user:secret@127.0.0.1:18080").unwrap(),
+        revision: Revision::new(1).unwrap(),
+        account_count: 0,
+        last_test_at: None,
+        last_test: None,
+        created_at: now,
+        updated_at: now,
+    }
+}
+
+fn preview_request() -> RemotePluginVerify {
+    RemotePluginVerify {
+        expected_plugin_id: Some("test.example".into()),
+        credential_ids: vec![],
+        outbound_proxy_id: None,
+        location: RemotePluginLocation::Github {
+            repository: "Owner/Plugin".into(),
+            tag: "v2.0.0".into(),
+            asset: "plugin.tar.gz".into(),
+            allow_prerelease: false,
+            sha256: Some("a".repeat(64)),
+        },
+    }
+}
+
+fn install_request() -> RemotePluginInstall {
+    let preview = preview_request();
+    RemotePluginInstall {
+        plugin_id: "test.example".into(),
+        version: "2.0.0".into(),
+        credential_ids: preview.credential_ids,
+        outbound_proxy_id: preview.outbound_proxy_id,
+        location: preview.location,
+    }
+}
+
+#[tokio::test]
+async fn saved_source_proxy_is_resolved_for_queries_and_frozen_into_verified_source() {
+    let mut fixture = preview_fixture();
+    fixture.binding.get_mut().unwrap().outbound_proxy_id = Some("source-proxy".into());
+    *fixture.proxy.get_mut().unwrap() = Some(source_proxy());
+    let fixture = Arc::new(fixture);
+    fixture
+        .service()
+        .check_update("test.example", &[])
+        .await
+        .unwrap();
+    let mut request = preview_request();
+    request.outbound_proxy_id = Some("source-proxy".into());
+    let verified = fixture.service().verify_remote(request).await.unwrap();
+    assert!(matches!(
+        verified.source.outbound_proxy(),
+        Some(PluginSourceEgress { id, revision: 1 }) if id == "source-proxy"
+    ));
+    assert_eq!(
+        fixture.egresses.lock().unwrap().as_slice(),
+        &[
+            Some(PluginSourceEgress {
+                id: "source-proxy".into(),
+                revision: 1,
+            }),
+            Some(PluginSourceEgress {
+                id: "source-proxy".into(),
+                revision: 1,
+            }),
+        ]
+    );
+}
+
+#[tokio::test]
+async fn proxy_revision_change_during_download_rejects_the_verified_candidate() {
+    let mut fixture = preview_fixture();
+    fixture.binding.get_mut().unwrap().outbound_proxy_id = Some("source-proxy".into());
+    *fixture.proxy.get_mut().unwrap() = Some(source_proxy());
+    fixture.change_proxy_during_download = true;
+    let fixture = Arc::new(fixture);
+    let mut request = preview_request();
+    request.outbound_proxy_id = Some("source-proxy".into());
+    assert_eq!(
+        fixture
+            .service()
+            .verify_remote(request)
+            .await
+            .unwrap_err()
+            .kind(),
+        AdminErrorKind::Conflict
+    );
+}
+
+#[tokio::test]
+async fn verifying_remote_package_uses_inspector_and_returns_fixed_facts_without_installing() {
+    let fixture = Arc::new(preview_fixture());
+    let verified = fixture
+        .service()
+        .verify_remote(preview_request())
+        .await
+        .unwrap();
+    assert_eq!(verified.metadata.sha256, "a".repeat(64));
+    assert_eq!(verified.metadata.requested_permissions, vec!["log"]);
+    assert!(
+        matches!(verified.source, PluginSource::Github { ref repository, ref tag, ref asset, .. }
+        if repository == "owner/plugin" && tag == "v2.0.0" && asset == "plugin.tar.gz")
+    );
+    assert_eq!(*fixture.downloads.lock().unwrap(), 1);
+    assert_eq!(*fixture.changes.lock().unwrap(), 0);
+    assert!(fixture.publications.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn remote_install_rejects_non_namespaced_plugin_ids_before_download() {
+    for plugin_id in [
+        "example",
+        "Test.example",
+        "test.-example",
+        "test.example_legacy",
+        "test.example.extra",
+    ] {
+        let fixture = Arc::new(preview_fixture());
+        let mut request = preview_request();
+        request.expected_plugin_id = Some(plugin_id.into());
+        let error = fixture.service().verify_remote(request).await.unwrap_err();
+        assert_eq!(error.kind(), AdminErrorKind::Invalid, "{plugin_id}");
+        assert_eq!(*fixture.downloads.lock().unwrap(), 0, "{plugin_id}");
+    }
+}
+
+#[tokio::test]
+async fn installation_rejects_identity_version_and_source_changes_without_persisting() {
+    for change in 0..4 {
+        let mut fixture = preview_fixture();
+        match change {
+            0 => fixture.package.as_mut().unwrap().metadata.plugin_id = "foreign".into(),
+            1 => fixture.package.as_mut().unwrap().metadata.version = "3.0.0".into(),
+            2 => fixture.binding.lock().unwrap().source = PluginUpdateSource::Upload,
+            _ => fixture.change_during_download = true,
+        }
+        let fixture = Arc::new(fixture);
+        let error = fixture
+            .service()
+            .install_remote(install_request(), &context())
+            .await
+            .err()
+            .unwrap();
+        assert_eq!(
+            error.kind(),
+            if change < 2 {
+                AdminErrorKind::Invalid
+            } else {
+                AdminErrorKind::Conflict
+            }
+        );
+        assert_eq!(*fixture.downloads.lock().unwrap(), usize::from(change != 2));
+        assert!(fixture.publications.lock().unwrap().is_empty());
+    }
+}
+
+#[tokio::test]
+async fn preview_discovers_identity_and_version_from_manifest_without_installing() {
+    let fixture = Arc::new(preview_fixture());
+    let mut request = preview_request();
+    request.expected_plugin_id = None;
+    let RemotePluginLocation::Github { sha256, .. } = &mut request.location else {
+        unreachable!()
+    };
+    *sha256 = None;
+    let verified = fixture.service().verify_remote(request).await.unwrap();
+    assert_eq!(verified.metadata.plugin_id, "test.example");
+    assert_eq!(verified.metadata.version, "2.0.0");
+    assert!(fixture.publications.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn discovered_identity_cannot_bypass_saved_source_or_concurrent_changes() {
+    for changed_during_download in [false, true] {
+        let mut fixture = preview_fixture();
+        if changed_during_download {
+            fixture.change_during_download = true;
+        } else {
+            fixture.binding.get_mut().unwrap().source = PluginUpdateSource::Upload;
+        }
+        let fixture = Arc::new(fixture);
+        let mut request = preview_request();
+        request.expected_plugin_id = None;
+        let error = fixture.service().verify_remote(request).await.unwrap_err();
+        assert_eq!(error.kind(), AdminErrorKind::Conflict);
+        assert!(fixture.publications.lock().unwrap().is_empty());
+    }
+}
+
+#[tokio::test]
+async fn installation_requires_pinned_digest_before_downloading() {
+    let fixture = Arc::new(preview_fixture());
+    let mut request = install_request();
+    let RemotePluginLocation::Github { sha256, .. } = &mut request.location else {
+        unreachable!()
+    };
+    *sha256 = None;
+    let error = fixture
+        .service()
+        .install_remote(request, &context())
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+    assert_eq!(*fixture.downloads.lock().unwrap(), 0);
+}
+
+#[tokio::test]
+async fn upload_preview_inspects_without_persisting_or_publishing() {
+    let fixture = Arc::new(preview_fixture());
+    let archive = fixture.package.as_ref().unwrap().archive.clone();
+    let verified = fixture.service().verify_upload(archive).await.unwrap();
+    assert_eq!(verified.metadata.plugin_id, "test.example");
+    assert_eq!(verified.source, PluginSource::Upload);
+    assert!(fixture.publications.lock().unwrap().is_empty());
+}
+
+#[test]
+fn url_preview_accepts_only_a_location_without_identity_or_digest() {
+    let input: RemotePluginVerify = serde_json::from_value(serde_json::json!({
+        "location": {"kind": "url", "url": "https://example.org/plugin.tar.gz"}
+    }))
+    .unwrap();
+    assert!(input.expected_plugin_id.is_none());
+    assert!(matches!(
+        input.location,
+        RemotePluginLocation::Url { sha256: None, .. }
+    ));
+}
diff --git a/backend/crates/gateway-admin/tests/use_case/plugins/instances.rs b/backend/crates/gateway-admin/tests/use_case/plugins/instances.rs
new file mode 100644
index 000000000..6ec60da7f
--- /dev/null
+++ b/backend/crates/gateway-admin/tests/use_case/plugins/instances.rs
@@ -0,0 +1,1408 @@
+use std::{
+    collections::BTreeMap,
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicU64, Ordering},
+    },
+};
+
+use async_trait::async_trait;
+use futures::future::BoxFuture;
+use gateway_admin::{
+    PluginDistributionPorts, PluginsService,
+    model::{
+        AdminError, AdminErrorKind, MutationActor, MutationContext, Revision,
+        plugins::{
+            InspectedPluginArtifact, InstalledPluginArtifact, PluginArtifactMetadata,
+            PluginArtifactMutation, PluginContribution, PluginSource,
+            distribution::{PluginSourceBinding, SourceCredential, SourceCredentialInfo},
+            instances::{
+                ConfigurePluginInstance, PluginCapabilityBinding, PluginFailurePolicy,
+                PluginInstance, PluginInstanceMutation, PluginInstanceReplacement,
+                PluginInstanceRuntime, PluginInstanceRuntimeFailure, PluginInstanceRuntimeStatus,
+                PluginInstanceSnapshot, PluginPermissionGrant, PluginVersionConfiguration,
+                RollbackPluginInstance,
+            },
+            state::{
+                ApplyPluginStateMigration, DeletePluginState, PluginStateCommit,
+                PluginStateConfiguration, PluginStateMigrationBatch, PluginStateMigrationNamespace,
+                PluginStateOwner, PluginStateOwnerRequest, PluginStateRecord, PluginStateSchema,
+                PluginStateTransition, PluginStateWrite, PutPluginState,
+            },
+        },
+    },
+    ports::{
+        plugins::{
+            PluginPreparation, PluginStateStore, PluginStateStoreError, PluginStateStoreErrorKind,
+            PluginStateStoreResult, PluginStore,
+        },
+        store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult},
+    },
+};
+use gateway_core::{
+    routing::ConfigRevision,
+    runtime::{
+        RuntimeSnapshotHandle, SnapshotControl,
+        extensions::{ExtensionSetId, ExtensionSetLease, ExtensionSetReference},
+    },
+};
+use serde_json::json;
+
+use super::TestPluginPorts;
+
+const OLD_ARTIFACT: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+const NEW_ARTIFACT: &str = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+
+#[derive(Clone, Copy)]
+enum MigrationBehavior {
+    Succeed,
+    Fail,
+    ConcurrentChangeThenFail,
+}
+
+struct SavedInstance {
+    artifact_sha256: String,
+    enabled: bool,
+    transition_id: Option<String>,
+}
+
+struct FixtureData {
+    snapshot: PluginInstanceSnapshot,
+    artifacts: Vec<InstalledPluginArtifact>,
+    artifact_reads: usize,
+    change_during_artifact_read: bool,
+    fail_preparation: bool,
+    configuration_ready: bool,
+    prepared_snapshots: Vec<PluginInstanceSnapshot>,
+    saves: Vec<SavedInstance>,
+    history: BTreeMap<String, PluginVersionConfiguration>,
+    aborted: usize,
+    activated: usize,
+    quiesced: usize,
+    diagnostics: Option<BTreeMap<String, PluginInstanceRuntime>>,
+}
+
+struct LifecycleFixture {
+    behavior: MigrationBehavior,
+    data: Mutex<FixtureData>,
+    next_prepared: AtomicU64,
+}
+
+impl LifecycleFixture {
+    fn new(behavior: MigrationBehavior) -> Arc<Self> {
+        Arc::new(Self {
+            behavior,
+            data: Mutex::new(FixtureData {
+                snapshot: PluginInstanceSnapshot {
+                    config_revision: revision(10),
+                    instances: vec![PluginInstance {
+                        id: "00000000-0000-7000-8000-000000000001".into(),
+                        name: "previous".into(),
+                        artifact_sha256: OLD_ARTIFACT.into(),
+                        enabled: true,
+                        trusted_process: true,
+                        configuration: json!({}),
+                        secrets: Default::default(),
+                        grants: vec![],
+                        bindings: vec![],
+                        revision: revision(10),
+                    }],
+                },
+                artifacts: vec![
+                    artifact(OLD_ARTIFACT, "test.lifecycle", "2.0.0"),
+                    artifact(NEW_ARTIFACT, "test.lifecycle", "1.0.0"),
+                ],
+                artifact_reads: 0,
+                change_during_artifact_read: false,
+                fail_preparation: false,
+                configuration_ready: true,
+                prepared_snapshots: vec![],
+                saves: vec![],
+                history: BTreeMap::from([(
+                    NEW_ARTIFACT.into(),
+                    PluginVersionConfiguration {
+                        configuration: json!({"oldVersion": true}),
+                        secrets: BTreeMap::from([("token".into(), "old-version-secret".into())]),
+                        bindings: vec![],
+                    },
+                )]),
+                aborted: 0,
+                activated: 0,
+                quiesced: 0,
+                diagnostics: None,
+            }),
+            next_prepared: AtomicU64::new(1),
+        })
+    }
+
+    fn snapshot(&self) -> PluginInstanceSnapshot {
+        self.data.lock().unwrap().snapshot.clone()
+    }
+
+    fn save(
+        &self,
+        mut instance: PluginInstance,
+        expected: Revision,
+        transition_id: Option<String>,
+        replacements: &[PluginInstanceReplacement],
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        let mut data = self.data.lock().unwrap();
+        if data.snapshot.config_revision != expected {
+            return Err(admin_error(AdminStoreErrorKind::Conflict));
+        }
+        let next = revision(expected.get() + 1);
+        for replacement in replacements {
+            let current = data
+                .snapshot
+                .instances
+                .iter_mut()
+                .find(|item| item.id == replacement.id)
+                .unwrap();
+            assert!(current.enabled);
+            assert_eq!(current.revision.get(), replacement.expected_revision);
+            current.enabled = false;
+            current.revision = next;
+        }
+        if instance.enabled {
+            data.history.insert(
+                instance.artifact_sha256.clone(),
+                PluginVersionConfiguration {
+                    configuration: instance.configuration.clone(),
+                    secrets: instance.secrets.clone(),
+                    bindings: instance.bindings.clone(),
+                },
+            );
+        }
+        instance.revision = next;
+        data.snapshot.config_revision = next;
+        data.snapshot
+            .instances
+            .retain(|current| current.id != instance.id);
+        data.snapshot.instances.push(instance.clone());
+        data.saves.push(SavedInstance {
+            artifact_sha256: instance.artifact_sha256.clone(),
+            enabled: instance.enabled,
+            transition_id,
+        });
+        Ok(PluginInstanceMutation {
+            config_revision: next,
+            instance,
+        })
+    }
+}
+
+struct Lease;
+
+impl ExtensionSetLease for Lease {
+    fn is_ready(&self) -> bool {
+        true
+    }
+}
+
+#[async_trait]
+impl PluginPreparation for LifecycleFixture {
+    async fn configuration_ready(
+        &self,
+        instance: PluginInstance,
+        metadata: &gateway_admin::model::plugins::PluginArtifactMetadata,
+    ) -> Result<bool, AdminError> {
+        assert_eq!(instance.artifact_sha256, metadata.sha256);
+        Ok(self.data.lock().unwrap().configuration_ready)
+    }
+
+    async fn validate(
+        &self,
+        instance: PluginInstance,
+    ) -> Result<PluginStateConfiguration, AdminError> {
+        Ok(state(if instance.artifact_sha256 == OLD_ARTIFACT {
+            1
+        } else {
+            2
+        }))
+    }
+
+    async fn prepare(
+        &self,
+        source_revision: Revision,
+        snapshot: PluginInstanceSnapshot,
+    ) -> Result<ExtensionSetReference, AdminError> {
+        let mut data = self.data.lock().unwrap();
+        if source_revision != data.snapshot.config_revision {
+            return Err(AdminError::conflict(
+                "configuration changed during preparation",
+            ));
+        }
+        if data.fail_preparation {
+            return Err(AdminError::invalid("候选配置准备失败"));
+        }
+        assert!(
+            snapshot
+                .instances
+                .iter()
+                .all(|instance| instance.revision <= snapshot.config_revision),
+            "候选集合必须包含本次实例变更的 revision，才能严格拒绝目标插件启动失败"
+        );
+        data.prepared_snapshots.push(snapshot);
+        let id = self.next_prepared.fetch_add(1, Ordering::Relaxed);
+        Ok(ExtensionSetReference::new(
+            ExtensionSetId::new(format!("state-candidate-{id}")).unwrap(),
+            Arc::new(Lease),
+        ))
+    }
+
+    async fn runtime_diagnostics(
+        &self,
+        _: &PluginInstanceSnapshot,
+        _: Option<u64>,
+        _: Option<&ExtensionSetReference>,
+    ) -> Option<BTreeMap<String, PluginInstanceRuntime>> {
+        self.data.lock().unwrap().diagnostics.clone()
+    }
+
+    async fn activate_state(
+        &self,
+        _: &ExtensionSetReference,
+        _: &PluginInstance,
+    ) -> Result<(), AdminError> {
+        self.data.lock().unwrap().activated += 1;
+        Ok(())
+    }
+
+    async fn quiesce_instance(&self, _: &str, _: &str, _: Revision) {
+        self.data.lock().unwrap().quiesced += 1;
+    }
+
+    async fn migrate_state(
+        &self,
+        _: &ExtensionSetReference,
+        _: PluginStateTransition,
+    ) -> Result<(), AdminError> {
+        match self.behavior {
+            MigrationBehavior::Succeed => Ok(()),
+            MigrationBehavior::Fail => Err(AdminError::invalid("migration fixture failed")),
+            MigrationBehavior::ConcurrentChangeThenFail => {
+                let mut data = self.data.lock().unwrap();
+                let next = revision(data.snapshot.config_revision.get() + 1);
+                data.snapshot.config_revision = next;
+                let instance = &mut data.snapshot.instances[0];
+                instance.name = "concurrent edit".into();
+                instance.revision = next;
+                Err(AdminError::invalid("migration fixture failed"))
+            }
+        }
+    }
+}
+
+#[async_trait]
+impl PluginStateStore for LifecycleFixture {
+    async fn load_owner(
+        &self,
+        _: PluginStateOwnerRequest,
+    ) -> PluginStateStoreResult<Option<PluginStateOwner>> {
+        state_unavailable()
+    }
+
+    async fn get(
+        &self,
+        _: &PluginStateOwner,
+        _: &str,
+        _: &str,
+    ) -> PluginStateStoreResult<Option<PluginStateRecord>> {
+        state_unavailable()
+    }
+
+    async fn put(
+        &self,
+        _: &PluginStateOwner,
+        _: PutPluginState,
+    ) -> PluginStateStoreResult<PluginStateWrite> {
+        state_unavailable()
+    }
+
+    async fn delete(
+        &self,
+        _: &PluginStateOwner,
+        _: DeletePluginState,
+    ) -> PluginStateStoreResult<bool> {
+        state_unavailable()
+    }
+
+    async fn transition_required(
+        &self,
+        _: &str,
+        target: &PluginStateConfiguration,
+    ) -> PluginStateStoreResult<bool> {
+        Ok(target.namespaces[0].schema_version == 2)
+    }
+
+    async fn begin_transition(
+        &self,
+        instance_id: &str,
+        expected_instance_revision: Revision,
+        artifact_sha256: &str,
+        _: PluginStateConfiguration,
+    ) -> PluginStateStoreResult<PluginStateTransition> {
+        let data = self.data.lock().unwrap();
+        let current = &data.snapshot.instances[0];
+        if current.enabled
+            || current.id != instance_id
+            || current.revision != expected_instance_revision
+            || artifact_sha256 != NEW_ARTIFACT
+        {
+            return Err(PluginStateStoreError::new(
+                PluginStateStoreErrorKind::Conflict,
+            ));
+        }
+        Ok(PluginStateTransition {
+            id: "00000000-0000-7000-8000-000000000002".into(),
+            instance_id: instance_id.into(),
+            artifact_sha256: artifact_sha256.into(),
+            namespaces: vec![PluginStateMigrationNamespace {
+                namespace: "cache".into(),
+                from_schema_version: 1,
+                to_schema_version: 2,
+            }],
+        })
+    }
+
+    async fn migration_batch(
+        &self,
+        _: &str,
+        _: &str,
+        _: u32,
+    ) -> PluginStateStoreResult<PluginStateMigrationBatch> {
+        state_unavailable()
+    }
+
+    async fn apply_migration_batch(
+        &self,
+        _: ApplyPluginStateMigration,
+    ) -> PluginStateStoreResult<()> {
+        state_unavailable()
+    }
+
+    async fn abort_transition(&self, _: &str) -> PluginStateStoreResult<()> {
+        self.data.lock().unwrap().aborted += 1;
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl PluginStore for LifecycleFixture {
+    async fn management_target_is_current(
+        &self,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+    ) -> AdminStoreResult<bool> {
+        Ok(self
+            .load_instances()
+            .await?
+            .instances
+            .iter()
+            .any(|instance| {
+                instance.enabled
+                    && instance.trusted_process
+                    && instance.id == target.instance_id
+                    && instance.artifact_sha256 == target.artifact_sha256
+                    && instance.revision.get() == target.revision
+            }))
+    }
+    async fn load_instances(&self) -> AdminStoreResult<PluginInstanceSnapshot> {
+        Ok(self.snapshot())
+    }
+
+    async fn load_version_configuration(
+        &self,
+        _: &str,
+        digest: &str,
+    ) -> AdminStoreResult<Option<PluginVersionConfiguration>> {
+        Ok(self.data.lock().unwrap().history.get(digest).cloned())
+    }
+    async fn configuration_versions(&self, _: &str) -> AdminStoreResult<Vec<String>> {
+        Ok(self.data.lock().unwrap().history.keys().cloned().collect())
+    }
+
+    async fn save_instance(
+        &self,
+        instance: PluginInstance,
+        expected_revision: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        self.save(instance, expected_revision, None, &[])
+    }
+
+    async fn save_instance_with_state(
+        &self,
+        instance: PluginInstance,
+        expected_revision: Revision,
+        state: PluginStateCommit,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        self.save(instance, expected_revision, state.transition_id, &[])
+    }
+
+    async fn save_instance_replacing(
+        &self,
+        instance: PluginInstance,
+        expected_revision: Revision,
+        state: PluginStateCommit,
+        replacements: &[PluginInstanceReplacement],
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        self.save(
+            instance,
+            expected_revision,
+            state.transition_id,
+            replacements,
+        )
+    }
+
+    async fn delete_instance(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(admin_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn list_update_sources(&self) -> AdminStoreResult<Vec<PluginSourceBinding>> {
+        Err(admin_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn change_update_source(
+        &self,
+        _: PluginSourceBinding,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(admin_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn list_source_credentials(&self) -> AdminStoreResult<Vec<SourceCredentialInfo>> {
+        Err(admin_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn load_source_credential(&self, _: &str) -> AdminStoreResult<SourceCredential> {
+        Err(admin_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn save_source_credential(
+        &self,
+        _: SourceCredential,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(admin_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn delete_source_credential(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(admin_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn list_artifacts(&self) -> AdminStoreResult<Vec<InstalledPluginArtifact>> {
+        let mut data = self.data.lock().unwrap();
+        data.artifact_reads += 1;
+        if data.change_during_artifact_read {
+            let next = revision(data.snapshot.config_revision.get() + 1);
+            data.snapshot.config_revision = next;
+            data.snapshot.instances[0].revision = next;
+            data.snapshot.instances[0].name = "concurrent edit".into();
+        }
+        Ok(data.artifacts.clone())
+    }
+
+    async fn load_artifact(&self, _: &str) -> AdminStoreResult<InspectedPluginArtifact> {
+        Err(admin_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn install_artifact(
+        &self,
+        _: InspectedPluginArtifact,
+        _: PluginSource,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        Err(admin_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn accept_artifact(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        Err(admin_error(AdminStoreErrorKind::Unavailable))
+    }
+
+    async fn delete_artifact(&self, _: &str, _: &MutationContext) -> AdminStoreResult<Revision> {
+        Err(admin_error(AdminStoreErrorKind::Unavailable))
+    }
+}
+
+#[derive(Default)]
+struct Published {
+    revisions: Mutex<Vec<u64>>,
+}
+
+impl SnapshotControl for Published {
+    fn publish_committed(&self, revision: ConfigRevision) -> BoxFuture<'_, ()> {
+        self.revisions.lock().unwrap().push(revision.get());
+        Box::pin(async {})
+    }
+}
+
+fn service(fixture: Arc<LifecycleFixture>, published: Arc<Published>) -> PluginsService {
+    PluginsService::new(
+        fixture.clone(),
+        Arc::new(TestPluginPorts),
+        PluginDistributionPorts::new(Arc::new(TestPluginPorts), Arc::new(TestPluginPorts)),
+        published,
+        fixture.clone(),
+        RuntimeSnapshotHandle::default(),
+        fixture,
+    )
+}
+
+fn state(version: u32) -> PluginStateConfiguration {
+    PluginStateConfiguration {
+        namespaces: vec![PluginStateSchema {
+            namespace: "cache".into(),
+            schema_version: version,
+            schema_sha256: char::from_digit(version, 16)
+                .unwrap()
+                .to_string()
+                .repeat(64),
+            schema: json!({"type":"object"}),
+            maximum_records: 16,
+            maximum_bytes: 1024,
+            maximum_value_bytes: 128,
+            migrates_from: (version == 2).then_some(1).into_iter().collect(),
+        }],
+    }
+}
+
+fn artifact(digest: &str, plugin_id: &str, version: &str) -> InstalledPluginArtifact {
+    InstalledPluginArtifact {
+        metadata: PluginArtifactMetadata {
+            plugin_id: plugin_id.into(),
+            version: version.into(),
+            name: plugin_id.strip_prefix("test.").unwrap_or(plugin_id).into(),
+            display_name: "Lifecycle fixture".into(),
+            publisher: "test".into(),
+            author: None,
+            description: String::new(),
+            license: "MIT".into(),
+            sha256: digest.into(),
+            platforms: vec!["linux/x86_64".into()],
+            icon: None,
+            contributes: BTreeMap::from([(
+                "middleware".into(),
+                PluginContribution {
+                    id: format!("{plugin_id}.middleware"),
+                    version: 1,
+                    stages: vec!["request".into()],
+                    input_formats: Vec::new(),
+                    output_formats: Vec::new(),
+                },
+            )]),
+            requested_permissions: vec![],
+            configuration_schema: json!({"type":"object"}),
+            secret_fields: vec![],
+            state_namespaces: vec![],
+        },
+        source: PluginSource::Upload,
+        installed_at: chrono::Utc::now(),
+        accepted_at: Some(chrono::Utc::now()),
+    }
+}
+
+fn rollback_input() -> RollbackPluginInstance {
+    RollbackPluginInstance {
+        artifact_sha256: NEW_ARTIFACT.into(),
+        expected_revision: 10,
+    }
+}
+
+fn input() -> ConfigurePluginInstance {
+    ConfigurePluginInstance {
+        replace_instances: Vec::new(),
+        creation_id: None,
+        expected_revision: None,
+        name: "upgraded".into(),
+        artifact_sha256: NEW_ARTIFACT.into(),
+        enabled: true,
+        configuration: json!({}),
+        secrets: None,
+        bindings: vec![],
+    }
+}
+
+#[tokio::test]
+async fn instance_list_loads_metadata_once_for_shared_artifacts_without_loading_archives() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    let mut second = fixture.snapshot().instances[0].clone();
+    second.id = "00000000-0000-7000-8000-000000000002".into();
+    second.enabled = false;
+    fixture.data.lock().unwrap().snapshot.instances.push(second);
+    let views = service(fixture.clone(), Arc::new(Published::default()))
+        .instances()
+        .await
+        .unwrap();
+    assert_eq!(views.len(), 2);
+    assert!(views.iter().all(|view| !view.configuration_required));
+    assert_eq!(fixture.data.lock().unwrap().artifact_reads, 1);
+}
+
+#[tokio::test]
+async fn enable_replacement_prepares_and_publishes_one_atomic_switch() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    let published = Arc::new(Published::default());
+    let service = service(fixture.clone(), published.clone());
+    let previous = fixture.snapshot().instances[0].clone();
+    let mut request = input();
+    request.replace_instances = vec![PluginInstanceReplacement {
+        id: previous.id.clone(),
+        expected_revision: 10,
+    }];
+    let result = service
+        .configure_instance(None, request, &context())
+        .await
+        .unwrap();
+    let data = fixture.data.lock().unwrap();
+    assert_eq!(data.saves.len(), 1);
+    assert_eq!(*published.revisions.lock().unwrap(), vec![11]);
+    for snapshot in data.prepared_snapshots.iter().chain([&data.snapshot]) {
+        let old = snapshot
+            .instances
+            .iter()
+            .find(|item| item.id == previous.id)
+            .unwrap();
+        let current = snapshot
+            .instances
+            .iter()
+            .find(|item| item.id == result.instance.id)
+            .unwrap();
+        assert!(!old.enabled);
+        assert!(current.enabled);
+        assert_eq!(old.revision, current.revision);
+        assert_eq!(old.configuration, previous.configuration);
+        assert_eq!(old.artifact_sha256, previous.artifact_sha256);
+    }
+}
+
+#[tokio::test]
+async fn enable_replacement_rejects_stale_or_invalid_confirmation_without_writing() {
+    for scenario in [
+        "stale",
+        "missing",
+        "disabled",
+        "foreign",
+        "duplicate",
+        "self",
+        "save_disabled",
+    ] {
+        let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+        let published = Arc::new(Published::default());
+        let service = service(fixture.clone(), published.clone());
+        let previous = fixture.snapshot().instances[0].clone();
+        let mut request = input();
+        request.replace_instances = vec![PluginInstanceReplacement {
+            id: previous.id.clone(),
+            expected_revision: 10,
+        }];
+        let mut target_id = None;
+        match scenario {
+            "stale" => request.replace_instances[0].expected_revision = 9,
+            "missing" => request.replace_instances[0].id = uuid::Uuid::now_v7().to_string(),
+            "disabled" => fixture.data.lock().unwrap().snapshot.instances[0].enabled = false,
+            "foreign" => {
+                fixture.data.lock().unwrap().artifacts[0].metadata.plugin_id =
+                    "another.plugin".into()
+            }
+            "duplicate" => request
+                .replace_instances
+                .push(request.replace_instances[0].clone()),
+            "self" => target_id = Some(previous.id.as_str()),
+            "save_disabled" => request.enabled = false,
+            _ => unreachable!(),
+        }
+        assert!(
+            service
+                .configure_instance(target_id, request, &context())
+                .await
+                .is_err(),
+            "{scenario}"
+        );
+        assert!(fixture.data.lock().unwrap().saves.is_empty(), "{scenario}");
+        assert!(published.revisions.lock().unwrap().is_empty(), "{scenario}");
+    }
+}
+
+#[tokio::test]
+async fn enable_replacement_preparation_failure_preserves_the_enabled_configuration() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    fixture.data.lock().unwrap().fail_preparation = true;
+    let service = service(fixture.clone(), Arc::new(Published::default()));
+    let previous = fixture.snapshot().instances[0].clone();
+    let mut request = input();
+    request.replace_instances = vec![PluginInstanceReplacement {
+        id: previous.id.clone(),
+        expected_revision: 10,
+    }];
+    assert!(
+        service
+            .configure_instance(None, request, &context())
+            .await
+            .is_err()
+    );
+    assert!(fixture.data.lock().unwrap().saves.is_empty());
+    assert!(fixture.snapshot().instances[0].enabled);
+}
+
+#[tokio::test]
+async fn enable_replacement_state_migration_only_switches_old_configuration_after_success() {
+    for behavior in [MigrationBehavior::Succeed, MigrationBehavior::Fail] {
+        let fixture = LifecycleFixture::new(behavior);
+        let target_id = fixture.snapshot().instances[0].id.clone();
+        let mut old = fixture.snapshot().instances[0].clone();
+        old.id = uuid::Uuid::now_v7().to_string();
+        {
+            let mut data = fixture.data.lock().unwrap();
+            data.snapshot.instances[0].enabled = false;
+            data.snapshot.instances.push(old.clone());
+        }
+        let service = service(fixture.clone(), Arc::new(Published::default()));
+        let mut request = input();
+        request.replace_instances = vec![PluginInstanceReplacement {
+            id: old.id.clone(),
+            expected_revision: 10,
+        }];
+        let result = service
+            .configure_instance(Some(&target_id), request, &context())
+            .await;
+        let succeeded = matches!(behavior, MigrationBehavior::Succeed);
+        assert_eq!(result.is_ok(), succeeded);
+        let snapshot = fixture.snapshot();
+        assert_eq!(
+            snapshot
+                .instances
+                .iter()
+                .find(|item| item.id == old.id)
+                .unwrap()
+                .enabled,
+            !succeeded
+        );
+        assert_eq!(
+            snapshot
+                .instances
+                .iter()
+                .find(|item| item.id == target_id)
+                .unwrap()
+                .enabled,
+            succeeded
+        );
+    }
+}
+
+#[tokio::test]
+async fn configuration_retry_reuses_creation_id_and_rejects_changed_draft() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    let service = service(fixture.clone(), Arc::new(Published::default()));
+    let creation_id = "00000000-0000-7000-8000-000000000002";
+    let request = || {
+        let mut value = input();
+        value.creation_id = Some(creation_id.into());
+        // 此用例验证创建重试，使用不需要私有状态迁移的固定版本。
+        value.artifact_sha256 = OLD_ARTIFACT.into();
+        value.enabled = false;
+        value
+    };
+    let created = service
+        .configure_instance(None, request(), &context())
+        .await
+        .unwrap();
+    let retried = service
+        .configure_instance(None, request(), &context())
+        .await
+        .unwrap();
+    assert_eq!(created.instance.id, creation_id);
+    assert_eq!(retried.instance.id, creation_id);
+    assert_eq!(fixture.snapshot().instances.len(), 2);
+    let before = fixture.snapshot().config_revision;
+    let mut changed = request();
+    changed.name = "changed draft".into();
+    let error = service
+        .configure_instance(None, changed, &context())
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminErrorKind::Conflict);
+    assert_eq!(fixture.snapshot().config_revision, before);
+}
+
+#[tokio::test]
+async fn configuration_update_rejects_stale_revision_without_writing() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    let mut request = input();
+    request.expected_revision = Some(9);
+    let error = service(fixture.clone(), Arc::new(Published::default()))
+        .configure_instance(
+            Some("00000000-0000-7000-8000-000000000001"),
+            request,
+            &context(),
+        )
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminErrorKind::Conflict);
+    assert!(fixture.data.lock().unwrap().saves.is_empty());
+}
+
+fn context() -> MutationContext {
+    MutationContext {
+        actor: MutationActor::System,
+        request_id: "state-lifecycle-test".into(),
+    }
+}
+
+fn revision(value: u64) -> Revision {
+    Revision::new(value).unwrap()
+}
+
+fn admin_error(kind: AdminStoreErrorKind) -> AdminStoreError {
+    AdminStoreError::new(kind, "plugin", "state lifecycle fixture")
+}
+
+fn state_unavailable<T>() -> PluginStateStoreResult<T> {
+    Err(PluginStateStoreError::new(
+        PluginStateStoreErrorKind::Unavailable,
+    ))
+}
+
+#[tokio::test]
+async fn instance_list_uses_runtime_diagnostics_and_keeps_running_compatibility_derived() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    let expected = PluginInstanceRuntime {
+        status: PluginInstanceRuntimeStatus::PreparationFailed,
+        actual_revision: Some(9),
+        actual_artifact_sha256: Some(OLD_ARTIFACT.into()),
+        failure: Some(PluginInstanceRuntimeFailure {
+            code: "unavailable".into(),
+            message: "插件候选准备失败".into(),
+        }),
+        draining_revisions: vec![8],
+        retained_continuations: 1,
+    };
+    fixture.data.lock().unwrap().diagnostics = Some(BTreeMap::from([(
+        "00000000-0000-7000-8000-000000000001".into(),
+        expected.clone(),
+    )]));
+
+    let views = service(fixture, Arc::new(Published::default()))
+        .instances()
+        .await
+        .unwrap();
+    assert_eq!(views.len(), 1);
+    assert!(!views[0].running);
+    assert_eq!(views[0].runtime, expected);
+}
+
+#[tokio::test]
+async fn instance_list_falls_back_without_inventing_runtime_failures() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    let views = service(fixture, Arc::new(Published::default()))
+        .instances()
+        .await
+        .unwrap();
+    assert_eq!(views.len(), 1);
+    assert_eq!(
+        views[0].runtime.status,
+        PluginInstanceRuntimeStatus::AwaitingPublication
+    );
+    assert!(!views[0].running);
+    assert!(views[0].runtime.failure.is_none());
+}
+
+#[tokio::test]
+async fn incompatible_state_upgrade_quiesces_migrates_and_promotes_the_target() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    let published = Arc::new(Published::default());
+    let result = service(fixture.clone(), published.clone())
+        .configure_instance(
+            Some("00000000-0000-7000-8000-000000000001"),
+            input(),
+            &context(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(result.config_revision, revision(12));
+    assert_eq!(result.instance.artifact_sha256, NEW_ARTIFACT);
+    assert!(result.instance.enabled);
+    let data = fixture.data.lock().unwrap();
+    assert_eq!(data.quiesced, 1);
+    assert_eq!(data.activated, 1);
+    assert_eq!(data.aborted, 0);
+    assert_eq!(data.saves.len(), 2);
+    assert_eq!(data.saves[0].artifact_sha256, OLD_ARTIFACT);
+    assert!(!data.saves[0].enabled);
+    assert!(data.saves[0].transition_id.is_none());
+    assert_eq!(data.saves[1].artifact_sha256, NEW_ARTIFACT);
+    assert!(data.saves[1].enabled);
+    assert!(data.saves[1].transition_id.is_some());
+    assert_eq!(published.revisions.lock().unwrap().as_slice(), [11, 12]);
+}
+
+#[tokio::test]
+async fn failed_state_migration_restores_the_previous_enabled_version_with_cas() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Fail);
+    let published = Arc::new(Published::default());
+    let error = service(fixture.clone(), published.clone())
+        .configure_instance(
+            Some("00000000-0000-7000-8000-000000000001"),
+            input(),
+            &context(),
+        )
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+    let data = fixture.data.lock().unwrap();
+    assert_eq!(data.snapshot.config_revision, revision(12));
+    assert_eq!(data.snapshot.instances[0].artifact_sha256, OLD_ARTIFACT);
+    assert!(data.snapshot.instances[0].enabled);
+    assert_eq!(data.quiesced, 1);
+    assert_eq!(data.activated, 1);
+    assert_eq!(data.aborted, 1);
+    assert_eq!(data.saves.len(), 2);
+    assert!(!data.saves[0].enabled);
+    assert!(data.saves[1].enabled);
+    assert_eq!(published.revisions.lock().unwrap().as_slice(), [11, 12]);
+}
+
+#[tokio::test]
+async fn failed_state_migration_never_overwrites_a_concurrent_configuration_change() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::ConcurrentChangeThenFail);
+    let published = Arc::new(Published::default());
+    let error = service(fixture.clone(), published.clone())
+        .configure_instance(
+            Some("00000000-0000-7000-8000-000000000001"),
+            input(),
+            &context(),
+        )
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminErrorKind::Conflict);
+    let data = fixture.data.lock().unwrap();
+    assert_eq!(data.snapshot.config_revision, revision(12));
+    assert_eq!(data.snapshot.instances[0].name, "concurrent edit");
+    assert_eq!(data.snapshot.instances[0].artifact_sha256, OLD_ARTIFACT);
+    assert!(!data.snapshot.instances[0].enabled);
+    assert_eq!(data.aborted, 1);
+    assert_eq!(data.activated, 0);
+    assert_eq!(data.saves.len(), 1, "恢复不能覆盖迁移期间的新配置");
+    assert_eq!(published.revisions.lock().unwrap().as_slice(), [11]);
+}
+
+#[tokio::test]
+async fn rollback_restores_target_configuration_secrets_and_bindings_and_derives_permissions() {
+    use secrecy::ExposeSecret as _;
+
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    {
+        let mut data = fixture.data.lock().unwrap();
+        data.artifacts[1].metadata.requested_permissions = vec!["network".into()];
+        let instance = &mut data.snapshot.instances[0];
+        instance.configuration = json!({"label":"retained"});
+        instance
+            .secrets
+            .insert("token".into(), "fixture-secret".into());
+        instance.bindings.push(PluginCapabilityBinding {
+            contribution: "test.lifecycle.middleware".into(),
+            stage: "request".into(),
+            order: 7,
+            failure_policy: PluginFailurePolicy::Reject,
+            client_key_ids: Vec::new(),
+            account_group_ids: Vec::new(),
+            provider_ids: Vec::new(),
+            models: Vec::new(),
+            identity_bindings: Vec::new(),
+        });
+    }
+    let before = fixture.snapshot().instances.remove(0);
+    let result = service(fixture.clone(), Arc::new(Published::default()))
+        .rollback_instance(&before.id, rollback_input(), &context())
+        .await
+        .unwrap();
+    assert_eq!(result.instance.artifact_sha256, NEW_ARTIFACT);
+    assert_eq!(result.instance.name, before.name);
+    assert_eq!(result.instance.enabled, before.enabled);
+    assert_eq!(result.instance.configuration, json!({"oldVersion": true}));
+    assert_eq!(
+        result.instance.grants,
+        [PluginPermissionGrant {
+            permission: "network".into()
+        }]
+    );
+    assert!(result.instance.bindings.is_empty());
+    assert_eq!(
+        result.instance.secrets["token"].expose_secret(),
+        "old-version-secret"
+    );
+    let data = fixture.data.lock().unwrap();
+    assert_eq!(data.quiesced, 1);
+    assert_eq!(data.activated, 1);
+    assert!(data.saves.last().unwrap().transition_id.is_some());
+}
+
+#[tokio::test]
+async fn rollback_rejects_stale_confirmation_without_preparing_or_writing() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    let mut input = rollback_input();
+    input.expected_revision = 9;
+    let error = service(fixture.clone(), Arc::new(Published::default()))
+        .rollback_instance(&fixture.snapshot().instances[0].id, input, &context())
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminErrorKind::Conflict);
+    assert!(fixture.data.lock().unwrap().saves.is_empty());
+    assert_eq!(fixture.next_prepared.load(Ordering::Relaxed), 1);
+}
+
+#[tokio::test]
+async fn rollback_rejects_foreign_newer_equal_or_uninstalled_artifacts() {
+    for (plugin_id, version, installed, expected) in [
+        ("test.other-plugin", "1.0.0", true, AdminErrorKind::Invalid),
+        ("test.lifecycle", "2.0.1", true, AdminErrorKind::Invalid),
+        ("test.lifecycle", "2.0.0", true, AdminErrorKind::Invalid),
+        (
+            "test.lifecycle",
+            "2.0.0+older-build",
+            true,
+            AdminErrorKind::Invalid,
+        ),
+        ("test.lifecycle", "1.0.0", false, AdminErrorKind::NotFound),
+    ] {
+        let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+        {
+            let mut data = fixture.data.lock().unwrap();
+            data.artifacts.truncate(1);
+            if installed {
+                data.artifacts
+                    .push(artifact(NEW_ARTIFACT, plugin_id, version));
+            }
+        }
+        let error = service(fixture.clone(), Arc::new(Published::default()))
+            .rollback_instance(
+                &fixture.snapshot().instances[0].id,
+                rollback_input(),
+                &context(),
+            )
+            .await
+            .err()
+            .unwrap();
+        assert_eq!(error.kind(), expected, "{plugin_id}/{version}/{installed}");
+        assert!(fixture.data.lock().unwrap().saves.is_empty());
+        assert_eq!(fixture.next_prepared.load(Ordering::Relaxed), 1);
+    }
+}
+
+#[tokio::test]
+async fn rollback_keeps_the_original_snapshot_fence_during_artifact_lookup() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    fixture.data.lock().unwrap().change_during_artifact_read = true;
+    let error = service(fixture.clone(), Arc::new(Published::default()))
+        .rollback_instance(
+            &fixture.snapshot().instances[0].id,
+            rollback_input(),
+            &context(),
+        )
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminErrorKind::Conflict);
+    let data = fixture.data.lock().unwrap();
+    assert_eq!(data.snapshot.instances[0].name, "concurrent edit");
+    assert_eq!(data.snapshot.instances[0].artifact_sha256, OLD_ARTIFACT);
+    assert!(data.saves.is_empty());
+}
+
+#[tokio::test]
+async fn rollback_migration_failure_restores_the_previous_version_without_replaying() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Fail);
+    let error = service(fixture.clone(), Arc::new(Published::default()))
+        .rollback_instance(
+            &fixture.snapshot().instances[0].id,
+            rollback_input(),
+            &context(),
+        )
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+    let data = fixture.data.lock().unwrap();
+    assert_eq!(data.snapshot.instances[0].artifact_sha256, OLD_ARTIFACT);
+    assert!(data.snapshot.instances[0].enabled);
+    assert_eq!(data.aborted, 1);
+    assert!(
+        data.saves
+            .iter()
+            .all(|saved| saved.artifact_sha256 == OLD_ARTIFACT)
+    );
+}
+
+#[tokio::test]
+async fn rollback_of_a_disabled_instance_never_enables_it() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    fixture.data.lock().unwrap().snapshot.instances[0].enabled = false;
+    let result = service(fixture.clone(), Arc::new(Published::default()))
+        .rollback_instance(
+            &fixture.snapshot().instances[0].id,
+            rollback_input(),
+            &context(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(result.instance.artifact_sha256, NEW_ARTIFACT);
+    assert!(!result.instance.enabled);
+    assert!(
+        fixture
+            .data
+            .lock()
+            .unwrap()
+            .saves
+            .iter()
+            .all(|saved| !saved.enabled)
+    );
+}
+
+#[tokio::test]
+async fn rollback_plan_is_read_only_and_orders_only_earlier_versions_of_the_same_plugin() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    {
+        let mut data = fixture.data.lock().unwrap();
+        data.artifacts.extend([
+            artifact(&"c".repeat(64), "test.lifecycle", "2.0.0-rc.2"),
+            artifact(&"d".repeat(64), "test.lifecycle", "2.0.0-rc.10"),
+            artifact(&"e".repeat(64), "test.lifecycle", "2.0.0+another-build"),
+            artifact(&"f".repeat(64), "test.other-plugin", "0.1.0"),
+        ]);
+        let saved = data.history[NEW_ARTIFACT].clone();
+        data.history.insert("c".repeat(64), saved.clone());
+        data.history.insert("d".repeat(64), saved);
+        data.snapshot.instances[0]
+            .secrets
+            .insert("token".into(), "fixture-secret".into());
+    }
+    let plan = service(fixture.clone(), Arc::new(Published::default()))
+        .rollback_plan(&fixture.snapshot().instances[0].id)
+        .await
+        .unwrap();
+    assert_eq!(plan.instance_revision, 10);
+    assert_eq!(plan.current_version, "2.0.0");
+    assert_eq!(
+        plan.targets
+            .iter()
+            .map(|target| target.version.as_str())
+            .collect::<Vec<_>>(),
+        ["2.0.0-rc.10", "2.0.0-rc.2", "1.0.0"],
+    );
+    let public = serde_json::to_string(&plan).unwrap();
+    assert!(!public.contains("fixture-secret"));
+    assert!(!public.contains("token"));
+    assert!(fixture.data.lock().unwrap().saves.is_empty());
+    assert_eq!(fixture.next_prepared.load(Ordering::Relaxed), 1);
+}
+
+#[tokio::test]
+async fn rollback_plan_excludes_unaccepted_older_artifacts() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    let digest = "c".repeat(64);
+    let mut pending = artifact(&digest, "test.lifecycle", "1.5.0");
+    pending.accepted_at = None;
+    fixture.data.lock().unwrap().artifacts.push(pending);
+
+    let plan = service(fixture.clone(), Arc::new(Published::default()))
+        .rollback_plan(&fixture.snapshot().instances[0].id)
+        .await
+        .unwrap();
+
+    assert!(
+        plan.targets
+            .iter()
+            .all(|target| target.artifact_sha256 != digest)
+    );
+}
+
+#[tokio::test]
+async fn enabling_another_instance_requires_an_explicit_replacement() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    let error = service(fixture.clone(), Arc::new(Published::default()))
+        .configure_instance(None, input(), &context())
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminErrorKind::Conflict);
+    assert!(fixture.data.lock().unwrap().saves.is_empty());
+    assert!(fixture.snapshot().instances[0].enabled);
+}
+
+#[tokio::test]
+async fn version_plan_keeps_explicit_values_adds_defaults_and_remaps_bindings_without_writing() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    {
+        let mut data = fixture.data.lock().unwrap();
+        data.history.clear();
+        data.artifacts[1].metadata.configuration_schema = json!({
+            "type":"object", "default":{"fromRoot":42}, "properties": {
+                "label":{"type":"string","default":"default"},
+                "nested":{"type":"object","properties":{"added":{"default":true},"kept":{"default":100}}},
+                "token":{"type":"string","default":"never-copy-secret"}
+            }
+        });
+        data.artifacts[1].metadata.secret_fields = vec!["token".into()];
+        data.artifacts[1]
+            .metadata
+            .contributes
+            .get_mut("middleware")
+            .unwrap()
+            .id = "renamed.middleware".into();
+        data.snapshot.instances[0].configuration =
+            json!({"label":"mine","nested":{"kept":0},"obsolete":"keep-for-validation"});
+        data.snapshot.instances[0]
+            .secrets
+            .insert("token".into(), "private-value".into());
+        data.snapshot.instances[0].bindings = vec![PluginCapabilityBinding {
+            contribution: "test.lifecycle.middleware".into(),
+            stage: "request".into(),
+            order: 3,
+            failure_policy: PluginFailurePolicy::Reject,
+            client_key_ids: vec![],
+            account_group_ids: vec![],
+            provider_ids: vec![],
+            models: vec!["test-model".into()],
+            identity_bindings: vec![],
+        }];
+    }
+    let before = fixture.snapshot();
+    let plan = service(fixture.clone(), Arc::new(Published::default()))
+        .version_plan(&before.instances[0].id, NEW_ARTIFACT)
+        .await
+        .unwrap();
+    assert!(!plan.restored);
+    assert_eq!(
+        plan.configuration,
+        json!({"label":"mine","nested":{"kept":0,"added":true},"obsolete":"keep-for-validation","fromRoot":42})
+    );
+    assert_eq!(plan.bindings[0].contribution, "renamed.middleware");
+    assert_eq!(plan.bindings[0].models, ["test-model"]);
+    assert_eq!(plan.secret_fields, ["token"]);
+    let public = serde_json::to_string(&plan).unwrap();
+    assert!(!public.contains("private-value"));
+    assert!(!public.contains("never-copy-secret"));
+    assert_eq!(fixture.snapshot().config_revision, before.config_revision);
+    assert!(fixture.data.lock().unwrap().saves.is_empty());
+}
+
+#[tokio::test]
+async fn version_switch_preparation_failure_preserves_current_and_saved_settings() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    fixture.data.lock().unwrap().fail_preparation = true;
+    let before = fixture.snapshot();
+    let result = service(fixture.clone(), Arc::new(Published::default()))
+        .switch_instance_version(&before.instances[0].id, rollback_input(), &context())
+        .await;
+    assert!(result.is_err());
+    assert_eq!(fixture.snapshot().config_revision, before.config_revision);
+    assert_eq!(
+        fixture.snapshot().instances[0].artifact_sha256,
+        OLD_ARTIFACT
+    );
+    let data = fixture.data.lock().unwrap();
+    assert!(data.saves.is_empty());
+    assert_eq!(
+        data.history[NEW_ARTIFACT].configuration,
+        json!({"oldVersion":true})
+    );
+}
+
+#[tokio::test]
+async fn version_edit_preserves_the_target_versions_secrets_when_omitted() {
+    use secrecy::ExposeSecret as _;
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    let before = fixture.snapshot();
+    let mut request = input();
+    request.secrets = None;
+    let result = service(fixture, Arc::new(Published::default()))
+        .configure_instance(Some(&before.instances[0].id), request, &context())
+        .await
+        .unwrap();
+    assert_eq!(
+        result.instance.secrets["token"].expose_secret(),
+        "old-version-secret"
+    );
+}
+
+#[tokio::test]
+async fn rollback_requires_a_saved_configuration_instead_of_reusing_incompatible_current_settings()
+{
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    fixture.data.lock().unwrap().history.clear();
+    let service = service(fixture.clone(), Arc::new(Published::default()));
+    let id = fixture.snapshot().instances[0].id.clone();
+    assert!(service.rollback_plan(&id).await.unwrap().targets.is_empty());
+    let error = service
+        .rollback_instance(&id, rollback_input(), &context())
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+    assert!(fixture.data.lock().unwrap().saves.is_empty());
+}
+
+#[tokio::test]
+async fn switching_a_disabled_plugin_also_requires_complete_target_settings() {
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    {
+        let mut data = fixture.data.lock().unwrap();
+        data.configuration_ready = false;
+        data.snapshot.instances[0].enabled = false;
+    }
+    let before = fixture.snapshot();
+    let error = service(fixture.clone(), Arc::new(Published::default()))
+        .switch_instance_version(&before.instances[0].id, rollback_input(), &context())
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+    assert_eq!(fixture.snapshot().config_revision, before.config_revision);
+    assert!(fixture.data.lock().unwrap().saves.is_empty());
+}
+
+#[tokio::test]
+async fn switching_versions_uses_saved_settings_and_rejects_stale_retry() {
+    use secrecy::ExposeSecret as _;
+    let fixture = LifecycleFixture::new(MigrationBehavior::Succeed);
+    let service = service(fixture.clone(), Arc::new(Published::default()));
+    let id = fixture.snapshot().instances[0].id.clone();
+    let result = service
+        .switch_instance_version(&id, rollback_input(), &context())
+        .await
+        .unwrap();
+    assert_eq!(result.instance.artifact_sha256, NEW_ARTIFACT);
+    assert_eq!(result.instance.configuration, json!({"oldVersion":true}));
+    assert_eq!(
+        result.instance.secrets["token"].expose_secret(),
+        "old-version-secret"
+    );
+    assert!(result.instance.enabled);
+    let revision = fixture.snapshot().config_revision;
+    let error = service
+        .switch_instance_version(&id, rollback_input(), &context())
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminErrorKind::Conflict);
+    assert_eq!(fixture.snapshot().config_revision, revision);
+}
diff --git a/backend/crates/gateway-admin/tests/use_case/plugins/mod.rs b/backend/crates/gateway-admin/tests/use_case/plugins/mod.rs
new file mode 100644
index 000000000..924af2951
--- /dev/null
+++ b/backend/crates/gateway-admin/tests/use_case/plugins/mod.rs
@@ -0,0 +1,404 @@
+use async_trait::async_trait;
+use gateway_admin::model::plugins::distribution::{
+    DownloadedPlugin, GithubReleaseQuery, PluginRelease, RemotePluginLocation, SourceCredential,
+    SourceCredentialInfo,
+};
+use gateway_admin::model::plugins::distribution::{PluginSourceBinding, PluginUpdateSource};
+use gateway_admin::{
+    model::{
+        AdminError, MutationContext, Revision,
+        plugins::{
+            InspectedPluginArtifact, InstalledPluginArtifact, PluginArtifactMutation, PluginSource,
+            state::{
+                ApplyPluginStateMigration, DeletePluginState, PluginStateConfiguration,
+                PluginStateMigrationBatch, PluginStateOwner, PluginStateOwnerRequest,
+                PluginStateRecord, PluginStateTransition, PluginStateWrite, PutPluginState,
+            },
+        },
+    },
+    ports::{
+        plugins::{
+            PluginPackageInspector, PluginStateStore, PluginStateStoreError,
+            PluginStateStoreErrorKind, PluginStateStoreResult, PluginStore,
+        },
+        store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult},
+    },
+};
+use std::sync::Arc;
+
+mod artifacts;
+mod distribution;
+mod instances;
+mod official;
+
+pub(super) struct TestPluginPorts;
+
+#[async_trait]
+impl gateway_admin::ports::proxy::ProxyStore for TestPluginPorts {
+    async fn reserve_import(
+        &self,
+        _: &str,
+    ) -> AdminStoreResult<gateway_admin::ports::proxy::ProxyImportReservation> {
+        Err(unavailable())
+    }
+
+    async fn list(
+        &self,
+        _: gateway_admin::model::proxies::ProxyListQuery,
+    ) -> AdminStoreResult<gateway_admin::model::proxies::ProxyPage> {
+        Err(unavailable())
+    }
+
+    async fn list_accounts(
+        &self,
+        _: gateway_admin::model::proxies::ProxyAccountListQuery,
+    ) -> AdminStoreResult<gateway_admin::model::proxies::ProxyAccountPage> {
+        Err(unavailable())
+    }
+
+    async fn get(&self, _: &str) -> AdminStoreResult<gateway_admin::model::proxies::ProxyRecord> {
+        Err(unavailable())
+    }
+
+    async fn remove_account(
+        &self,
+        _: &str,
+        _: &gateway_core::account::ProviderAccountId,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unavailable())
+    }
+
+    async fn create(
+        &self,
+        _: gateway_admin::model::proxies::NewProxy,
+        _: &MutationContext,
+    ) -> AdminStoreResult<gateway_admin::model::proxies::ProxyMutation> {
+        Err(unavailable())
+    }
+
+    async fn update(
+        &self,
+        _: gateway_admin::model::proxies::UpdateProxy,
+        _: &MutationContext,
+    ) -> AdminStoreResult<gateway_admin::model::proxies::ProxyMutation> {
+        Err(unavailable())
+    }
+
+    async fn delete(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unavailable())
+    }
+
+    async fn record_test(
+        &self,
+        _: &str,
+        _: Revision,
+        _: gateway_admin::model::proxies::ProxyTestResult,
+        _: &MutationContext,
+    ) -> AdminStoreResult<gateway_admin::model::proxies::ProxyRecord> {
+        Err(unavailable())
+    }
+}
+
+#[async_trait]
+impl gateway_admin::ports::plugin_management::PluginManagement for TestPluginPorts {
+    async fn authorize_models(
+        &self,
+        _: &gateway_core::runtime::extensions::ExtensionSetReference,
+        _: &gateway_admin::model::plugins::management::PluginManagementTarget,
+    ) -> Result<(), AdminError> {
+        Err(AdminError::not_found("unused plugin fixture"))
+    }
+
+    async fn start_callback(
+        &self,
+        _: &gateway_core::runtime::extensions::ExtensionSetReference,
+        _: &gateway_admin::model::plugins::management::PluginManagementTarget,
+        _: gateway_admin::model::plugins::management::StartPluginManagementCallback,
+        _: &gateway_admin::model::auth::AdminRequestContext,
+    ) -> Result<gateway_admin::model::plugins::management::PluginManagementCallbackTicket, AdminError>
+    {
+        Err(AdminError::not_found("unused plugin fixture"))
+    }
+    async fn callback(
+        &self,
+        _: &gateway_core::runtime::extensions::ExtensionSetReference,
+        _: &gateway_admin::model::plugins::management::PluginManagementTarget,
+        _: &str,
+        _: gateway_admin::model::plugins::management::PluginManagementRequest,
+    ) -> Result<gateway_admin::model::plugins::management::PluginManagementResponse, AdminError>
+    {
+        Err(AdminError::not_found("unused plugin fixture"))
+    }
+    async fn views(
+        &self,
+        _: &gateway_core::runtime::extensions::ExtensionSetReference,
+    ) -> Result<Vec<gateway_admin::model::plugins::management::PluginManagementView>, AdminError>
+    {
+        Ok(Vec::new())
+    }
+    async fn resource(
+        &self,
+        _: &gateway_core::runtime::extensions::ExtensionSetReference,
+        _: &gateway_admin::model::plugins::management::PluginManagementTarget,
+        _: &str,
+        _: bool,
+    ) -> Result<gateway_admin::model::plugins::management::PluginManagementResponse, AdminError>
+    {
+        Err(AdminError::not_found("unused plugin fixture"))
+    }
+    async fn handle(
+        &self,
+        _: &gateway_core::runtime::extensions::ExtensionSetReference,
+        _: &gateway_admin::model::plugins::management::PluginManagementTarget,
+        _: gateway_admin::model::plugins::management::PluginManagementRequest,
+    ) -> Result<gateway_admin::model::plugins::management::PluginManagementResponse, AdminError>
+    {
+        Err(AdminError::not_found("unused plugin fixture"))
+    }
+}
+
+#[async_trait]
+impl gateway_admin::ports::plugins::PluginPreparation for TestPluginPorts {
+    async fn configuration_ready(
+        &self,
+        _: gateway_admin::model::plugins::instances::PluginInstance,
+        _: &gateway_admin::model::plugins::PluginArtifactMetadata,
+    ) -> Result<bool, AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+
+    async fn validate(
+        &self,
+        _: gateway_admin::model::plugins::instances::PluginInstance,
+    ) -> Result<gateway_admin::model::plugins::state::PluginStateConfiguration, AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+    async fn prepare(
+        &self,
+        _: Revision,
+        _: gateway_admin::model::plugins::instances::PluginInstanceSnapshot,
+    ) -> Result<gateway_core::runtime::extensions::ExtensionSetReference, AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+}
+
+fn unavailable() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Unavailable,
+        "plugin",
+        "unused plugin fixture",
+    )
+}
+
+fn state_unavailable<T>() -> PluginStateStoreResult<T> {
+    Err(PluginStateStoreError::new(
+        PluginStateStoreErrorKind::Unavailable,
+    ))
+}
+
+#[async_trait]
+impl PluginStateStore for TestPluginPorts {
+    async fn load_owner(
+        &self,
+        _: PluginStateOwnerRequest,
+    ) -> PluginStateStoreResult<Option<PluginStateOwner>> {
+        state_unavailable()
+    }
+    async fn get(
+        &self,
+        _: &PluginStateOwner,
+        _: &str,
+        _: &str,
+    ) -> PluginStateStoreResult<Option<PluginStateRecord>> {
+        state_unavailable()
+    }
+    async fn put(
+        &self,
+        _: &PluginStateOwner,
+        _: PutPluginState,
+    ) -> PluginStateStoreResult<PluginStateWrite> {
+        state_unavailable()
+    }
+    async fn delete(
+        &self,
+        _: &PluginStateOwner,
+        _: DeletePluginState,
+    ) -> PluginStateStoreResult<bool> {
+        state_unavailable()
+    }
+    async fn transition_required(
+        &self,
+        _: &str,
+        _: &PluginStateConfiguration,
+    ) -> PluginStateStoreResult<bool> {
+        state_unavailable()
+    }
+    async fn begin_transition(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &str,
+        _: PluginStateConfiguration,
+    ) -> PluginStateStoreResult<PluginStateTransition> {
+        state_unavailable()
+    }
+    async fn migration_batch(
+        &self,
+        _: &str,
+        _: &str,
+        _: u32,
+    ) -> PluginStateStoreResult<PluginStateMigrationBatch> {
+        state_unavailable()
+    }
+    async fn apply_migration_batch(
+        &self,
+        _: ApplyPluginStateMigration,
+    ) -> PluginStateStoreResult<()> {
+        state_unavailable()
+    }
+    async fn abort_transition(&self, _: &str) -> PluginStateStoreResult<()> {
+        state_unavailable()
+    }
+}
+
+#[async_trait]
+impl PluginStore for TestPluginPorts {
+    async fn management_target_is_current(
+        &self,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+    ) -> AdminStoreResult<bool> {
+        Ok(self
+            .load_instances()
+            .await?
+            .instances
+            .iter()
+            .any(|instance| {
+                instance.enabled
+                    && instance.trusted_process
+                    && instance.id == target.instance_id
+                    && instance.artifact_sha256 == target.artifact_sha256
+                    && instance.revision.get() == target.revision
+            }))
+    }
+    async fn load_instances(
+        &self,
+    ) -> AdminStoreResult<gateway_admin::model::plugins::instances::PluginInstanceSnapshot> {
+        Err(unavailable())
+    }
+    async fn save_instance(
+        &self,
+        _: gateway_admin::model::plugins::instances::PluginInstance,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<gateway_admin::model::plugins::instances::PluginInstanceMutation> {
+        Err(unavailable())
+    }
+    async fn delete_instance(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unavailable())
+    }
+    async fn list_update_sources(&self) -> AdminStoreResult<Vec<PluginSourceBinding>> {
+        Ok(Vec::new())
+    }
+    async fn change_update_source(
+        &self,
+        _: PluginSourceBinding,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unavailable())
+    }
+
+    async fn list_source_credentials(&self) -> AdminStoreResult<Vec<SourceCredentialInfo>> {
+        Ok(Vec::new())
+    }
+    async fn load_source_credential(&self, _: &str) -> AdminStoreResult<SourceCredential> {
+        Err(unavailable())
+    }
+    async fn save_source_credential(
+        &self,
+        _: SourceCredential,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unavailable())
+    }
+    async fn delete_source_credential(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unavailable())
+    }
+
+    async fn list_artifacts(&self) -> AdminStoreResult<Vec<InstalledPluginArtifact>> {
+        Ok(Vec::new())
+    }
+    async fn load_artifact(&self, _: &str) -> AdminStoreResult<InspectedPluginArtifact> {
+        Err(unavailable())
+    }
+    async fn install_artifact(
+        &self,
+        _: InspectedPluginArtifact,
+        _: PluginSource,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        Err(unavailable())
+    }
+    async fn accept_artifact(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        Err(unavailable())
+    }
+    async fn delete_artifact(&self, _: &str, _: &MutationContext) -> AdminStoreResult<Revision> {
+        Err(unavailable())
+    }
+}
+
+#[async_trait]
+impl PluginPackageInspector for TestPluginPorts {
+    async fn inspect(
+        &self,
+        _: Arc<[u8]>,
+        _: Option<String>,
+    ) -> Result<InspectedPluginArtifact, AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+}
+
+#[async_trait]
+impl gateway_admin::ports::plugins::PluginDistribution for TestPluginPorts {
+    fn validate_source(&self, _: &PluginUpdateSource) -> Result<(), AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+
+    fn validate_credential(&self, _: &SourceCredential) -> Result<(), AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+    async fn query_release(
+        &self,
+        _: GithubReleaseQuery,
+        _: Vec<SourceCredential>,
+        _: Option<gateway_admin::model::plugins::distribution::PluginDistributionEgress>,
+    ) -> Result<PluginRelease, AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+    async fn download(
+        &self,
+        _: RemotePluginLocation,
+        _: Vec<SourceCredential>,
+        _: Option<gateway_admin::model::plugins::distribution::PluginDistributionEgress>,
+    ) -> Result<DownloadedPlugin, AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+}
diff --git a/backend/crates/gateway-admin/tests/use_case/plugins/official.rs b/backend/crates/gateway-admin/tests/use_case/plugins/official.rs
new file mode 100644
index 000000000..bb37f0d6d
--- /dev/null
+++ b/backend/crates/gateway-admin/tests/use_case/plugins/official.rs
@@ -0,0 +1,416 @@
+use std::{collections::BTreeMap, sync::Arc};
+
+use async_trait::async_trait;
+use futures::future::BoxFuture;
+use gateway_admin::{
+    PluginDistributionPorts, PluginsService,
+    model::{
+        AdminError, AdminErrorKind, MutationActor, MutationContext, Revision,
+        plugins::{
+            InspectedPluginArtifact, InstalledPluginArtifact, PluginArtifactMetadata,
+            PluginArtifactMutation, PluginSource,
+            distribution::{PluginSourceBinding, SourceCredential, SourceCredentialInfo},
+            instances::{PluginInstance, PluginInstanceMutation, PluginInstanceSnapshot},
+            official::OfficialPluginReleaseIdentity,
+        },
+    },
+    ports::{
+        plugin_release::{
+            OfficialPluginReleaseFiles, OfficialPluginReleaseReadError,
+            OfficialPluginReleaseReadErrorKind,
+        },
+        plugins::{PluginPackageInspector, PluginStore},
+        store::AdminStoreResult,
+    },
+};
+use gateway_core::{
+    routing::ConfigRevision,
+    runtime::{RuntimeSnapshotHandle, SnapshotControl},
+};
+
+use super::TestPluginPorts;
+
+const VERSION: &str = "3.13.0";
+const GIT_SHA: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+
+struct Fixture {
+    manifest: Option<Arc<[u8]>>,
+    archives: BTreeMap<String, Arc<[u8]>>,
+    inspected_publisher: String,
+    installs: std::sync::Mutex<Vec<(String, PluginSource)>>,
+    publications: std::sync::Mutex<Vec<u64>>,
+    fail_archive: Option<Vec<u8>>,
+}
+
+impl Fixture {
+    fn new(plugins: &[(&str, u8)]) -> Arc<Self> {
+        let artifacts = plugins
+            .iter()
+            .map(|(id, marker)| plugin_entry(id, *marker))
+            .collect::<Vec<_>>();
+        let manifest = serde_json::to_vec(&serde_json::json!({
+            "schema_version": 1,
+            "sealed": true,
+            "gateway_version": VERSION,
+            "gateway_git_sha": GIT_SHA,
+            "plugin_host": plugin_host(),
+            "plugins": artifacts,
+        }))
+        .expect("manifest");
+        let archives = plugins
+            .iter()
+            .map(|(id, marker)| {
+                (
+                    format!(
+                        "{id}-1.0.0-{}-{}.tar.gz",
+                        std::env::consts::OS,
+                        std::env::consts::ARCH
+                    ),
+                    Arc::<[u8]>::from(vec![*marker]),
+                )
+            })
+            .collect();
+        Arc::new(Self {
+            manifest: Some(manifest.into()),
+            archives,
+            inspected_publisher: "test".into(),
+            installs: std::sync::Mutex::new(Vec::new()),
+            publications: std::sync::Mutex::new(Vec::new()),
+            fail_archive: None,
+        })
+    }
+
+    fn service(self: &Arc<Self>) -> PluginsService {
+        let unused = Arc::new(TestPluginPorts);
+        PluginsService::new(
+            self.clone(),
+            self.clone(),
+            PluginDistributionPorts::new(unused.clone(), unused.clone()),
+            self.clone(),
+            unused.clone(),
+            RuntimeSnapshotHandle::default(),
+            unused,
+        )
+    }
+}
+
+#[async_trait]
+impl OfficialPluginReleaseFiles for Fixture {
+    async fn manifest(&self) -> Result<Option<Arc<[u8]>>, OfficialPluginReleaseReadError> {
+        Ok(self.manifest.clone())
+    }
+
+    async fn artifact(&self, file_name: &str) -> Result<Arc<[u8]>, OfficialPluginReleaseReadError> {
+        self.archives.get(file_name).cloned().ok_or_else(|| {
+            OfficialPluginReleaseReadError::new(OfficialPluginReleaseReadErrorKind::NotFound)
+        })
+    }
+}
+
+#[async_trait]
+impl PluginPackageInspector for Fixture {
+    async fn inspect(
+        &self,
+        archive: Arc<[u8]>,
+        expected_sha256: Option<String>,
+    ) -> Result<InspectedPluginArtifact, AdminError> {
+        if self
+            .fail_archive
+            .as_ref()
+            .is_some_and(|expected| archive.as_ref() == expected)
+        {
+            return Err(AdminError::invalid("fixture rejected package"));
+        }
+        let marker = archive.first().copied().expect("marker");
+        let name = format!("official-{marker}");
+        let id = format!("test.{name}");
+        Ok(InspectedPluginArtifact {
+            metadata: PluginArtifactMetadata {
+                plugin_id: id,
+                version: "1.0.0".into(),
+                name,
+                display_name: "Official fixture".into(),
+                publisher: self.inspected_publisher.clone(),
+                author: Some("project".into()),
+                description: String::new(),
+                license: "MIT".into(),
+                sha256: expected_sha256.expect("expected digest"),
+                platforms: vec![format!(
+                    "{}-{}",
+                    std::env::consts::OS,
+                    std::env::consts::ARCH
+                )],
+                icon: None,
+                contributes: Default::default(),
+                requested_permissions: Vec::new(),
+                configuration_schema: serde_json::json!({}),
+                secret_fields: Vec::new(),
+                state_namespaces: Vec::new(),
+            },
+            archive,
+        })
+    }
+}
+
+impl SnapshotControl for Fixture {
+    fn publish_committed(&self, revision: ConfigRevision) -> BoxFuture<'_, ()> {
+        self.publications.lock().unwrap().push(revision.get());
+        Box::pin(async {})
+    }
+}
+
+#[async_trait]
+impl PluginStore for Fixture {
+    async fn management_target_is_current(
+        &self,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+    ) -> AdminStoreResult<bool> {
+        Ok(self
+            .load_instances()
+            .await?
+            .instances
+            .iter()
+            .any(|instance| {
+                instance.enabled
+                    && instance.trusted_process
+                    && instance.id == target.instance_id
+                    && instance.artifact_sha256 == target.artifact_sha256
+                    && instance.revision.get() == target.revision
+            }))
+    }
+    async fn load_instances(&self) -> AdminStoreResult<PluginInstanceSnapshot> {
+        unreachable!()
+    }
+    async fn save_instance(
+        &self,
+        _: PluginInstance,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        unreachable!()
+    }
+    async fn delete_instance(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+    async fn list_update_sources(&self) -> AdminStoreResult<Vec<PluginSourceBinding>> {
+        unreachable!()
+    }
+    async fn change_update_source(
+        &self,
+        _: PluginSourceBinding,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+    async fn list_source_credentials(&self) -> AdminStoreResult<Vec<SourceCredentialInfo>> {
+        unreachable!()
+    }
+    async fn load_source_credential(&self, _: &str) -> AdminStoreResult<SourceCredential> {
+        unreachable!()
+    }
+    async fn save_source_credential(
+        &self,
+        _: SourceCredential,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+    async fn delete_source_credential(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+    async fn list_artifacts(&self) -> AdminStoreResult<Vec<InstalledPluginArtifact>> {
+        unreachable!()
+    }
+    async fn load_artifact(&self, _: &str) -> AdminStoreResult<InspectedPluginArtifact> {
+        unreachable!()
+    }
+    async fn install_artifact(
+        &self,
+        artifact: InspectedPluginArtifact,
+        source: PluginSource,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        self.installs
+            .lock()
+            .unwrap()
+            .push((artifact.metadata.plugin_id.clone(), source.clone()));
+        Ok(PluginArtifactMutation {
+            config_revision: Revision::new(2).unwrap(),
+            artifact: InstalledPluginArtifact {
+                metadata: artifact.metadata,
+                source,
+                installed_at: chrono::Utc::now(),
+                accepted_at: None,
+            },
+        })
+    }
+    async fn accept_artifact(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        unreachable!()
+    }
+    async fn delete_artifact(&self, _: &str, _: &MutationContext) -> AdminStoreResult<Revision> {
+        unreachable!()
+    }
+}
+
+#[tokio::test]
+async fn official_release_validates_all_packages_then_uses_builtin_install_path() {
+    let fixture = Fixture::new(&[("test.official-1", 1)]);
+    let result = fixture
+        .service()
+        .import_official_release(fixture.as_ref(), &identity(), &system_context())
+        .await
+        .expect("official import");
+
+    assert_eq!(result.artifacts, 1);
+    assert_eq!(result.config_revision.map(Revision::get), Some(2));
+    assert_eq!(
+        fixture.installs.lock().unwrap().as_slice(),
+        &[(
+            "test.official-1".into(),
+            PluginSource::Builtin {
+                release: VERSION.into()
+            }
+        )]
+    );
+    assert_eq!(fixture.publications.lock().unwrap().as_slice(), &[2]);
+}
+
+#[tokio::test]
+async fn official_release_never_persists_a_valid_prefix_when_later_validation_fails() {
+    let mut fixture = Fixture::new(&[("test.official-1", 1), ("test.official-2", 2)]);
+    Arc::get_mut(&mut fixture).unwrap().fail_archive = Some(vec![2]);
+    let error = fixture
+        .service()
+        .import_official_release(fixture.as_ref(), &identity(), &system_context())
+        .await
+        .expect_err("second package must fail");
+
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+    assert!(fixture.installs.lock().unwrap().is_empty());
+    assert!(fixture.publications.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn official_release_rejects_publisher_identity_mismatches() {
+    let fixture = Fixture::new(&[("other.official-1", 1)]);
+    assert_eq!(
+        fixture
+            .service()
+            .import_official_release(fixture.as_ref(), &identity(), &system_context())
+            .await
+            .expect_err("publisher must match the plugin ID namespace")
+            .kind(),
+        AdminErrorKind::Invalid
+    );
+    assert!(fixture.installs.lock().unwrap().is_empty());
+
+    let mut fixture = Fixture::new(&[("test.official-1", 1)]);
+    Arc::get_mut(&mut fixture).unwrap().inspected_publisher = "other".into();
+    assert_eq!(
+        fixture
+            .service()
+            .import_official_release(fixture.as_ref(), &identity(), &system_context())
+            .await
+            .expect_err("inspected publisher must match the sealed release")
+            .kind(),
+        AdminErrorKind::Invalid
+    );
+    assert!(fixture.installs.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn official_release_rejects_non_system_callers_and_mismatched_build_identity() {
+    let fixture = Fixture::new(&[("test.official-1", 1)]);
+    let admin = MutationContext {
+        actor: MutationActor::AdminApiKey,
+        request_id: "fixture".into(),
+    };
+    assert_eq!(
+        fixture
+            .service()
+            .import_official_release(fixture.as_ref(), &identity(), &admin)
+            .await
+            .expect_err("admin caller")
+            .kind(),
+        AdminErrorKind::Forbidden
+    );
+    let wrong = OfficialPluginReleaseIdentity {
+        gateway_version: "9.9.9".into(),
+        gateway_git_sha: GIT_SHA.into(),
+    };
+    assert_eq!(
+        fixture
+            .service()
+            .import_official_release(fixture.as_ref(), &wrong, &system_context())
+            .await
+            .expect_err("mismatched identity")
+            .kind(),
+        AdminErrorKind::Invalid
+    );
+    assert!(fixture.installs.lock().unwrap().is_empty());
+}
+
+fn identity() -> OfficialPluginReleaseIdentity {
+    OfficialPluginReleaseIdentity {
+        gateway_version: VERSION.into(),
+        gateway_git_sha: GIT_SHA.into(),
+    }
+}
+
+fn plugin_host() -> serde_json::Value {
+    serde_json::json!({
+        "schema_version": 1,
+        "manifest_schema_versions": [2],
+        "protocol_versions": [3],
+        "capabilities": [{ "capability": "executor", "versions": [1] }],
+        "permissions": ["log"],
+    })
+}
+
+fn system_context() -> MutationContext {
+    MutationContext {
+        actor: MutationActor::System,
+        request_id: "official-import-fixture".into(),
+    }
+}
+
+fn plugin_entry(id: &str, marker: u8) -> serde_json::Value {
+    let (release_os, release_architecture, target) = release_platform();
+    serde_json::json!({
+        "id": id,
+        "version": "1.0.0",
+        "publisher": "test",
+        "stability": "experimental",
+        "artifacts": [{
+            "release_os": release_os,
+            "release_architecture": release_architecture,
+            "target": target,
+            "os": std::env::consts::OS,
+            "architecture": std::env::consts::ARCH,
+            "archive": format!("{id}-1.0.0-{}-{}.tar.gz", std::env::consts::OS, std::env::consts::ARCH),
+            "sha256": format!("{marker:01x}").repeat(64),
+        }]
+    })
+}
+
+fn release_platform() -> (&'static str, &'static str, &'static str) {
+    match (std::env::consts::OS, std::env::consts::ARCH) {
+        ("linux", "x86_64") => ("linux", "amd64", "x86_64-unknown-linux-gnu"),
+        ("linux", "aarch64") => ("linux", "arm64", "aarch64-unknown-linux-gnu"),
+        ("macos", "aarch64") => ("darwin", "arm64", "aarch64-apple-darwin"),
+        platform => panic!("unsupported test platform: {platform:?}"),
+    }
+}
diff --git a/backend/crates/gateway-admin/tests/use_case/proxies.rs b/backend/crates/gateway-admin/tests/use_case/proxies.rs
index e170a364f..e329ceacc 100644
--- a/backend/crates/gateway-admin/tests/use_case/proxies.rs
+++ b/backend/crates/gateway-admin/tests/use_case/proxies.rs
@@ -147,15 +147,28 @@ async fn authorization_uses_selected_proxy_regardless_of_probe_status() {
                 .build()
                 .await;
             let command = StartAuthorization {
+                input: gateway_admin::model::provider_credentials::ProviderDocument::new(
+                    gateway_core::account::OpaqueProviderData::new(serde_json::Map::new()),
+                ),
                 outbound_proxy: Some(AccountProxySelection::Saved("proxy_oauth".to_owned())),
                 context: context("oauth-proxy-status"),
                 name: "授权账号".to_owned(),
                 reauthorization: None,
             };
             let result = if kind == "openai" {
-                services.openai().start_authorization(command).await
+                services
+                    .credentials()
+                    .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+                    .unwrap()
+                    .start_authorization(command)
+                    .await
             } else {
-                services.xai().start_authorization(command).await
+                services
+                    .credentials()
+                    .for_provider(&gateway_core::routing::ProviderKind::new("xai").unwrap())
+                    .unwrap()
+                    .start_authorization(command)
+                    .await
             };
             assert!(result.is_ok(), "{kind}, {probe_success:?}: {result:?}");
             assert_eq!(recorded(&events), ["provider.start_authorization"]);
@@ -263,9 +276,19 @@ async fn credential_import_keeps_proxy_reserved_until_commit_and_releases_on_err
                 document: document(),
             };
             let result = if kind == "openai" {
-                services.openai().import_document(command).await
+                services
+                    .credentials()
+                    .for_provider(&gateway_core::routing::ProviderKind::new("openai").unwrap())
+                    .unwrap()
+                    .import_document(command)
+                    .await
             } else {
-                services.xai().import_document(command).await
+                services
+                    .credentials()
+                    .for_provider(&gateway_core::routing::ProviderKind::new("xai").unwrap())
+                    .unwrap()
+                    .import_document(command)
+                    .await
             };
             assert_eq!(result.is_err(), failure.is_some());
             let events = recorded(&events);
diff --git a/backend/crates/gateway-admin/tests/use_case/settings.rs b/backend/crates/gateway-admin/tests/use_case/settings.rs
index 3a0b17581..e74e5ac19 100644
--- a/backend/crates/gateway-admin/tests/use_case/settings.rs
+++ b/backend/crates/gateway-admin/tests/use_case/settings.rs
@@ -1,8 +1,14 @@
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    sync::{Arc, Mutex},
+};
+
 use async_trait::async_trait;
 
 use gateway_admin::{
     model::{
-        AdminErrorKind, MutationContext,
+        AdminErrorKind, MutationContext, Revision,
+        pricing::{PricingChange, PricingSyncPreview, StoredPricing, SyncPricing, UpdatePricing},
         settings::{
             AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RotationStrategy,
             RuntimeSettings,
@@ -13,10 +19,15 @@ use gateway_admin::{
 
 struct UnusedSettingsStore;
 
+#[derive(Default)]
+struct PricingSettingsStore {
+    updated: Mutex<Option<UpdatePricing>>,
+}
+
 #[tokio::test]
 async fn client_profile_preview_rejects_unknown_provider_before_loading_settings() {
     let services = super::AdminHarness::new()
-        .settings(std::sync::Arc::new(UnusedSettingsStore))
+        .settings(Arc::new(UnusedSettingsStore))
         .build()
         .await;
     let error = services
@@ -27,6 +38,61 @@ async fn client_profile_preview_rejects_unknown_provider_before_loading_settings
     assert_eq!(error.kind(), AdminErrorKind::Invalid);
 }
 
+#[tokio::test]
+async fn pricing_accepts_registered_plugin_provider_and_rejects_unknown_sync_provider() {
+    let store = Arc::new(PricingSettingsStore::default());
+    let services = super::AdminHarness::new()
+        .settings(store.clone())
+        .provider(super::test_provider("example-plugin"))
+        .build()
+        .await;
+    let context = MutationContext {
+        actor: gateway_admin::model::MutationActor::System,
+        request_id: "request-plugin-pricing".to_owned(),
+    };
+    let pricing = serde_json::from_value(serde_json::json!({
+        "multiplierBps": 10000,
+        "bands": {"standard": {
+            "input": "1", "output": "2", "cacheRead": "0", "cacheWrite": "0"
+        }}
+    }))
+    .expect("plugin pricing");
+    let update = UpdatePricing {
+        provider: "example-plugin".to_owned(),
+        models: vec!["example-model".to_owned()],
+        change: PricingChange::Replace(pricing),
+    };
+
+    services
+        .settings()
+        .update_pricing(&context, update.clone())
+        .await
+        .expect("registered plugin provider pricing");
+    assert_eq!(
+        store.updated.lock().expect("updated pricing").as_ref(),
+        Some(&update)
+    );
+
+    let error = services
+        .settings()
+        .sync_pricing(
+            &context,
+            SyncPricing {
+                preview: PricingSyncPreview {
+                    prices: BTreeMap::new(),
+                    skipped: Vec::new(),
+                },
+                models: BTreeMap::from([(
+                    "unregistered-provider".to_owned(),
+                    BTreeSet::from(["example-model".to_owned()]),
+                )]),
+            },
+        )
+        .await
+        .expect_err("unknown provider cannot enter pricing sync");
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+}
+
 #[async_trait]
 impl SettingsStore for UnusedSettingsStore {
     async fn load_pricing(&self) -> AdminStoreResult<gateway_admin::model::pricing::StoredPricing> {
@@ -78,10 +144,65 @@ impl SettingsStore for UnusedSettingsStore {
     }
 }
 
+#[async_trait]
+impl SettingsStore for PricingSettingsStore {
+    async fn load_pricing(&self) -> AdminStoreResult<StoredPricing> {
+        Ok(StoredPricing::default())
+    }
+
+    async fn sync_pricing(
+        &self,
+        _: gateway_admin::model::pricing::PricingSyncChanges,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        panic!("unexpected pricing sync")
+    }
+
+    async fn update_pricing(
+        &self,
+        command: UpdatePricing,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        *self.updated.lock().expect("updated pricing") = Some(command);
+        Ok(Revision::new(2).expect("revision"))
+    }
+
+    async fn load_runtime_settings(&self) -> AdminStoreResult<RuntimeSettings> {
+        Err(unused())
+    }
+
+    async fn admin_api_key_exists(&self) -> AdminStoreResult<bool> {
+        Err(unused())
+    }
+
+    async fn replace_runtime_settings(
+        &self,
+        _: ReplaceRuntimeSettings,
+        _: &MutationContext,
+    ) -> AdminStoreResult<RuntimeSettings> {
+        Err(unused())
+    }
+
+    async fn replace_admin_api_key(
+        &self,
+        _: AdminApiKey,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AdminApiKeyMutation> {
+        Err(unused())
+    }
+
+    async fn delete_admin_api_key(
+        &self,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AdminApiKeyMutation> {
+        Err(unused())
+    }
+}
+
 #[tokio::test]
 async fn settings_should_reject_zero_refresh_margin_before_store_call() {
     let services = super::AdminHarness::new()
-        .settings(std::sync::Arc::new(UnusedSettingsStore))
+        .settings(Arc::new(UnusedSettingsStore))
         .build()
         .await;
     let error = services
@@ -92,8 +213,7 @@ async fn settings_should_reject_zero_refresh_margin_before_store_call() {
                 request_id: "request-settings".to_owned(),
             },
             ReplaceRuntimeSettings {
-                openai_client_profile: None,
-                xai_client_profile: None,
+                request_profile_updates: Default::default(),
                 request_location_enabled: false,
                 request_location: Default::default(),
                 model_mappings: Default::default(),
diff --git a/backend/crates/gateway-admin/tests/use_case/system.rs b/backend/crates/gateway-admin/tests/use_case/system.rs
index 8cf1f412b..633d2a843 100644
--- a/backend/crates/gateway-admin/tests/use_case/system.rs
+++ b/backend/crates/gateway-admin/tests/use_case/system.rs
@@ -54,6 +54,7 @@ impl SystemOperations for RecordingSystemOperations {
     async fn perform_update(
         &self,
         target_version: Option<String>,
+        _: std::sync::Arc<dyn gateway_admin::ports::system::SystemUpdatePreflight>,
     ) -> Result<SystemOperationAccepted, SystemOperationError> {
         *self.target.lock().expect("target") = Some(target_version.clone());
         Ok(SystemOperationAccepted::Update {
@@ -82,7 +83,10 @@ impl SystemOperations for RecordingSystemOperations {
         })
     }
 
-    async fn rollback(&self) -> Result<SystemOperationAccepted, SystemOperationError> {
+    async fn rollback(
+        &self,
+        _: std::sync::Arc<dyn gateway_admin::ports::system::SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError> {
         Ok(SystemOperationAccepted::Rollback {
             operation_id: "operation-rollback".to_owned(),
             message: "accepted".to_owned(),
diff --git a/backend/crates/gateway-api/Cargo.toml b/backend/crates/gateway-api/Cargo.toml
index ac13c5b55..e76e0c8fa 100644
--- a/backend/crates/gateway-api/Cargo.toml
+++ b/backend/crates/gateway-api/Cargo.toml
@@ -21,6 +21,7 @@ futures = "0.3.32"
 gateway-admin = { path = "../gateway-admin" }
 gateway-core = { path = "../gateway-core" }
 gateway-protocol = { path = "../gateway-protocol" }
+headers = "0.4.1"
 secrecy = "0.10"
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
diff --git a/backend/crates/gateway-api/src/admin/accounts/capabilities.rs b/backend/crates/gateway-api/src/admin/accounts/capabilities.rs
new file mode 100644
index 000000000..29fd97864
--- /dev/null
+++ b/backend/crates/gateway-api/src/admin/accounts/capabilities.rs
@@ -0,0 +1,79 @@
+//! 已发布 Provider 的账号能力；响应只包含静态 schema，不包含配置或凭据。
+
+use gateway_admin::model::provider_capabilities::{
+    AuthorizationCompletion, ProviderCredentialDescriptor,
+};
+
+use super::*;
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProviderData {
+    pub provider: String,
+    pub credentials: AccountCredentialCapabilitiesData,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountCredentialCapabilitiesData {
+    pub import: Option<Value>,
+    pub login: Option<AccountLoginCapabilityData>,
+    pub refresh: bool,
+    pub export: bool,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountLoginCapabilityData {
+    pub input_schema: Value,
+    pub completion: AccountAuthorizationCompletion,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AccountAuthorizationCompletion {
+    Callback,
+    Poll,
+}
+
+impl From<ProviderCredentialDescriptor> for AccountProviderData {
+    fn from(value: ProviderCredentialDescriptor) -> Self {
+        let capabilities = value.capabilities;
+        Self {
+            provider: value.provider.as_str().to_owned(),
+            credentials: AccountCredentialCapabilitiesData {
+                import: capabilities.import,
+                login: capabilities.login.map(|login| AccountLoginCapabilityData {
+                    input_schema: login.input_schema,
+                    completion: match login.completion {
+                        AuthorizationCompletion::Callback => {
+                            AccountAuthorizationCompletion::Callback
+                        }
+                        AuthorizationCompletion::Poll => AccountAuthorizationCompletion::Poll,
+                    },
+                }),
+                refresh: capabilities.refresh,
+                export: capabilities.export,
+            },
+        }
+    }
+}
+
+pub(super) async fn providers<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: crate::auth::SessionState + Send + Sync,
+{
+    let descriptors = state
+        .admin_services()
+        .credentials()
+        .providers()
+        .map_err(map_service_error)?;
+    let data: Vec<_> = descriptors
+        .into_iter()
+        .map(AccountProviderData::from)
+        .collect();
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
diff --git a/backend/crates/gateway-api/src/admin/accounts/credentials.rs b/backend/crates/gateway-api/src/admin/accounts/credentials.rs
index f65a1a526..cd700163f 100644
--- a/backend/crates/gateway-api/src/admin/accounts/credentials.rs
+++ b/backend/crates/gateway-api/src/admin/accounts/credentials.rs
@@ -14,20 +14,8 @@ fn validate_account_notes(notes: Option<&str>) -> Result<(), WireValidationError
     Ok(())
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub(super) enum AccountProvider {
-    OpenAi,
-    Xai,
-}
-
-impl AccountProvider {
-    fn parse(value: &str) -> Result<Self, WireValidationError> {
-        match value.trim() {
-            "openai" => Ok(Self::OpenAi),
-            "xai" => Ok(Self::Xai),
-            _ => Err(WireValidationError::new("provider")),
-        }
-    }
+fn parse_provider(value: &str) -> Result<ProviderKind, WireValidationError> {
+    ProviderKind::new(value.trim().to_owned()).map_err(|_| WireValidationError::new("provider"))
 }
 
 /// 导入统一设置，复用编辑账号的备注、调度和分组约束。
@@ -84,7 +72,7 @@ impl AccountImportRequest {
         if let Some(settings) = &self.settings {
             settings.validate()?;
         }
-        AccountProvider::parse(&self.provider)?;
+        parse_provider(&self.provider)?;
         if !self.data.is_object()
             || serde_json::to_vec(&self.data)
                 .map_or(true, |encoded| encoded.len() > MAX_IMPORT_DATA_BYTES)
@@ -97,9 +85,9 @@ impl AccountImportRequest {
     pub(super) fn into_command(
         self,
         context: gateway_admin::model::MutationContext,
-    ) -> Result<(AccountProvider, ImportCredentials), WireValidationError> {
+    ) -> Result<(ProviderKind, ImportCredentials), WireValidationError> {
         self.validate()?;
-        let provider = AccountProvider::parse(&self.provider)?;
+        let provider = parse_provider(&self.provider)?;
         Ok((
             provider,
             ImportCredentials {
@@ -115,7 +103,7 @@ impl AccountImportRequest {
     }
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Clone, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct StartAccountAuthorizationRequest {
     pub outbound_proxy_id: Option<String>,
@@ -123,12 +111,17 @@ pub struct StartAccountAuthorizationRequest {
     pub name: String,
     pub account_id: Option<String>,
     pub outbound_proxy_url: Option<super::wire::AccountProxyUpdate>,
+    #[serde(default)]
+    pub input: Map<String, Value>,
 }
 
 impl StartAccountAuthorizationRequest {
     pub fn validate(&self) -> Result<(), WireValidationError> {
-        AccountProvider::parse(&self.provider)?;
+        parse_provider(&self.provider)?;
         require_text(&self.name, MAX_NAME_BYTES, "name")?;
+        if serde_json::to_vec(&self.input).map_or(true, |data| data.len() > 64 * 1024) {
+            return Err(WireValidationError::new("input"));
+        }
         if let Some(account_id) = self.account_id.as_deref() {
             require_account_id(account_id, "accountId")?;
         }
@@ -138,9 +131,9 @@ impl StartAccountAuthorizationRequest {
     pub(super) fn into_command(
         self,
         context: gateway_admin::model::MutationContext,
-    ) -> Result<(AccountProvider, StartAuthorization), WireValidationError> {
+    ) -> Result<(ProviderKind, StartAuthorization), WireValidationError> {
         self.validate()?;
-        let provider = AccountProvider::parse(&self.provider)?;
+        let provider = parse_provider(&self.provider)?;
         let reauthorization = self
             .account_id
             .map(ProviderAccountId::new)
@@ -150,6 +143,7 @@ impl StartAccountAuthorizationRequest {
             provider,
             StartAuthorization {
                 context,
+                input: ProviderDocument::new(OpaqueProviderData::new(self.input)),
                 name: self.name,
                 reauthorization,
                 outbound_proxy: super::wire::proxy_selection(
@@ -175,27 +169,17 @@ impl CompleteAccountAuthorizationRequest {
         if let Some(settings) = &self.settings {
             settings.validate()?;
         }
-        let provider = AccountProvider::parse(&self.provider)?;
-        match provider {
-            AccountProvider::OpenAi => {
-                if !URL_SAFE_NO_PAD
-                    .decode(&self.flow_id)
-                    .is_ok_and(|decoded| decoded.len() == 32)
-                {
-                    return Err(WireValidationError::new("flowId"));
-                }
-            }
-            AccountProvider::Xai => require_wire_id(&self.flow_id, "flowId")?,
-        }
+        let provider = parse_provider(&self.provider)?;
+        validate_authorization_flow(&provider, &self.flow_id)?;
         require_text(&self.callback_url, MAX_CALLBACK_URL_BYTES, "callbackUrl")
     }
 
     pub(super) fn into_command(
         self,
         context: gateway_admin::model::MutationContext,
-    ) -> Result<(AccountProvider, CompleteAuthorization), WireValidationError> {
+    ) -> Result<(ProviderKind, CompleteAuthorization), WireValidationError> {
         self.validate()?;
-        let provider = AccountProvider::parse(&self.provider)?;
+        let provider = parse_provider(&self.provider)?;
         Ok((
             provider,
             CompleteAuthorization {
@@ -211,9 +195,97 @@ impl CompleteAccountAuthorizationRequest {
     }
 }
 
-#[derive(Debug, Clone, Deserialize)]
+fn validate_authorization_flow(
+    provider: &ProviderKind,
+    flow_id: &str,
+) -> Result<(), WireValidationError> {
+    if provider.as_str() == "openai" {
+        if !URL_SAFE_NO_PAD
+            .decode(flow_id)
+            .is_ok_and(|decoded| decoded.len() == 32)
+        {
+            return Err(WireValidationError::new("flowId"));
+        }
+        Ok(())
+    } else {
+        require_wire_id(flow_id, "flowId")
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PollAccountAuthorizationRequest {
+    pub provider: String,
+    pub flow_id: String,
+    pub callback_url: Option<String>,
+    pub settings: Option<AccountImportSettingsRequest>,
+}
+
+impl PollAccountAuthorizationRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        validate_authorization_flow(&parse_provider(&self.provider)?, &self.flow_id)?;
+        if let Some(callback) = &self.callback_url {
+            require_text(callback, MAX_CALLBACK_URL_BYTES, "callbackUrl")?;
+        }
+        if let Some(settings) = &self.settings {
+            settings.validate()?;
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(ProviderKind, PollAuthorization), WireValidationError> {
+        self.validate()?;
+        Ok((
+            parse_provider(&self.provider)?,
+            PollAuthorization {
+                context,
+                flow_id: self.flow_id,
+                callback_url: self.callback_url,
+                settings: self
+                    .settings
+                    .map(AccountImportSettingsRequest::into_settings)
+                    .transpose()?,
+            },
+        ))
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(
+    tag = "status",
+    rename_all = "camelCase",
+    rename_all_fields = "camelCase"
+)]
+pub enum AccountAuthorizationPollData {
+    Pending { retry_after_ms: u64 },
+    Complete { account_ids: Vec<String> },
+}
+
+impl From<AuthorizationPollResult> for AccountAuthorizationPollData {
+    fn from(result: AuthorizationPollResult) -> Self {
+        match result {
+            AuthorizationPollResult::Pending { retry_after } => Self::Pending {
+                retry_after_ms: retry_after.as_secs() * 1000
+                    + u64::from(retry_after.subsec_millis()),
+            },
+            AuthorizationPollResult::Complete(result) => Self::Complete {
+                account_ids: result
+                    .accounts
+                    .into_iter()
+                    .map(|account| account.account_id.to_string())
+                    .collect(),
+            },
+        }
+    }
+}
+
+#[derive(Clone, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct UpdateAccountRequest {
+    pub connection: Option<AccountConnectionUpdateRequest>,
     pub outbound_proxy_id: Option<String>,
     pub outbound_proxy_url: Option<super::wire::AccountProxyUpdate>,
     pub account_id: String,
@@ -229,6 +301,9 @@ pub struct UpdateAccountRequest {
 impl UpdateAccountRequest {
     pub fn validate(&self) -> Result<(), WireValidationError> {
         require_account_id(&self.account_id, "accountId")?;
+        if let Some(connection) = &self.connection {
+            connection.validate()?;
+        }
         validate_account_notes(self.notes.as_deref())?;
         parse_concurrency_limit(self.concurrency_limit)?;
         parse_account_weight(self.weight)?;
@@ -236,9 +311,14 @@ impl UpdateAccountRequest {
         Ok(())
     }
 
-    pub(super) fn into_command(self) -> Result<UpdateAccount, WireValidationError> {
+    pub(super) fn into_command(
+        self,
+    ) -> Result<(UpdateAccount, Option<ProviderDocument>), WireValidationError> {
         self.validate()?;
-        Ok(UpdateAccount {
+        let connection = self
+            .connection
+            .map(AccountConnectionUpdateRequest::into_document);
+        let settings = UpdateAccount {
             outbound_proxy: super::wire::proxy_selection(
                 self.outbound_proxy_id,
                 self.outbound_proxy_url,
@@ -250,7 +330,45 @@ impl UpdateAccountRequest {
             weight: parse_account_weight(self.weight)?,
             model_access: self.model_access,
             group_ids: validate_wire_group_ids(&self.group_ids)?,
-        })
+        };
+        Ok((settings, connection))
+    }
+}
+
+/// 编辑 OpenAI API Key 账号的连接设置；省略密钥时保留已保存的值。
+#[derive(Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountConnectionUpdateRequest {
+    pub base_url: String,
+    pub transport: String,
+    pub api_key: Option<String>,
+}
+
+impl AccountConnectionUpdateRequest {
+    fn validate(&self) -> Result<(), WireValidationError> {
+        require_text(&self.base_url, 2048, "connection.baseUrl")?;
+        if !matches!(self.transport.as_str(), "http" | "prefer_websocket") {
+            return Err(WireValidationError::new("connection.transport"));
+        }
+        if self.api_key.as_ref().is_some_and(|key| {
+            key.is_empty()
+                || key.len() > 16 * 1024
+                || !key.bytes().all(|byte| byte.is_ascii_graphic())
+        }) {
+            return Err(WireValidationError::new("connection.apiKey"));
+        }
+        Ok(())
+    }
+
+    fn into_document(self) -> ProviderDocument {
+        let mut material = Map::from_iter([
+            ("base_url".to_owned(), Value::String(self.base_url)),
+            ("transport".to_owned(), Value::String(self.transport)),
+        ]);
+        if let Some(key) = self.api_key {
+            material.insert("api_key".to_owned(), Value::String(key));
+        }
+        ProviderDocument::new(OpaqueProviderData::new(material))
     }
 }
 
@@ -279,7 +397,7 @@ pub struct AccountDeletionRequest {
 
 impl AccountDeletionRequest {
     pub fn validate(&self) -> Result<(), WireValidationError> {
-        AccountProvider::parse(&self.provider)?;
+        parse_provider(&self.provider)?;
         if self.account_ids.is_empty() || self.account_ids.len() > MAX_ACCOUNT_DELETE_BATCH {
             return Err(WireValidationError::new("accountIds"));
         }
@@ -296,9 +414,9 @@ impl AccountDeletionRequest {
     pub(super) fn into_command(
         self,
         context: gateway_admin::model::MutationContext,
-    ) -> Result<(AccountProvider, CredentialDeletion), WireValidationError> {
+    ) -> Result<(ProviderKind, CredentialDeletion), WireValidationError> {
         self.validate()?;
-        let provider = AccountProvider::parse(&self.provider)?;
+        let provider = parse_provider(&self.provider)?;
         Ok((
             provider,
             CredentialDeletion {
@@ -314,106 +432,6 @@ impl AccountDeletionRequest {
     }
 }
 
-#[derive(Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
-pub struct RotateAccountRequest {
-    pub provider: String,
-    pub account_id: String,
-    pub access_token: Option<String>,
-    pub refresh_token: Option<String>,
-    pub id_token: Option<String>,
-    pub base_url: Option<String>,
-    pub api_key: Option<String>,
-    pub transport: Option<String>,
-    pub settings: Option<UpdateAccountRequest>,
-}
-
-impl RotateAccountRequest {
-    pub fn validate(&self) -> Result<(), WireValidationError> {
-        if AccountProvider::parse(&self.provider)? != AccountProvider::OpenAi {
-            return Err(WireValidationError::new("provider"));
-        }
-        require_account_id(&self.account_id, "accountId")?;
-        if let Some(settings) = &self.settings {
-            settings.validate()?;
-            if settings.account_id != self.account_id {
-                return Err(WireValidationError::new("settings.accountId"));
-            }
-        }
-        if let Some(base_url) = &self.base_url {
-            if self.access_token.is_some()
-                || self.refresh_token.is_some()
-                || self.id_token.is_some()
-                || base_url.is_empty()
-                || base_url.len() > 2048
-                || !matches!(self.transport.as_deref(), Some("http" | "prefer_websocket"))
-                || self.api_key.as_ref().is_some_and(|key| {
-                    key.is_empty()
-                        || key.len() > 16 * 1024
-                        || !key.bytes().all(|byte| byte.is_ascii_graphic())
-                })
-            {
-                return Err(WireValidationError::new("credential"));
-            }
-            Ok(())
-        } else {
-            if self.api_key.is_some() || self.transport.is_some() {
-                return Err(WireValidationError::new("credential"));
-            }
-            validate_oauth_material(
-                self.access_token
-                    .as_deref()
-                    .ok_or_else(|| WireValidationError::new("accessToken"))?,
-                self.refresh_token.as_deref(),
-                self.id_token.as_deref(),
-            )
-        }
-    }
-
-    pub(super) fn into_command(
-        self,
-        context: gateway_admin::model::MutationContext,
-    ) -> Result<RotateCredential, WireValidationError> {
-        self.validate()?;
-        let mut material = Map::new();
-        if let Some(base_url) = self.base_url {
-            material.insert("base_url".to_owned(), Value::String(base_url));
-            material.insert(
-                "transport".to_owned(),
-                self.transport.map_or(Value::Null, Value::String),
-            );
-            if let Some(key) = self.api_key {
-                material.insert("api_key".to_owned(), Value::String(key));
-            }
-        } else {
-            material.insert(
-                "access_token".to_owned(),
-                self.access_token.map_or(Value::Null, Value::String),
-            );
-            material.insert(
-                "refresh_token".to_owned(),
-                self.refresh_token.map_or(Value::Null, Value::String),
-            );
-            material.insert(
-                "id_token".to_owned(),
-                self.id_token.map_or(Value::Null, Value::String),
-            );
-        }
-        Ok(RotateCredential {
-            settings: self
-                .settings
-                .map(UpdateAccountRequest::into_command)
-                .transpose()?,
-            mutation: CredentialMutation {
-                context,
-                account_id: ProviderAccountId::new(self.account_id)
-                    .map_err(|_| WireValidationError::new("accountId"))?,
-            },
-            provider_material: ProviderDocument::new(OpaqueProviderData::new(material)),
-        })
-    }
-}
-
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AccountImportData {
@@ -579,47 +597,6 @@ fn require_text(
     Ok(())
 }
 
-fn validate_oauth_material(
-    access_token: &str,
-    refresh_token: Option<&str>,
-    id_token: Option<&str>,
-) -> Result<(), WireValidationError> {
-    if access_token.len() > MAX_ACCESS_TOKEN_BYTES
-        || !valid_visible_ascii(access_token)
-        || !valid_compact_jwt_shape(access_token)
-    {
-        return Err(WireValidationError::new("accessToken"));
-    }
-    if refresh_token.is_some_and(|token| {
-        token.len() > MAX_REFRESH_TOKEN_BYTES
-            || !valid_visible_ascii(token)
-            || token == access_token
-    }) {
-        return Err(WireValidationError::new("refreshToken"));
-    }
-    if id_token.is_some_and(|token| {
-        token.len() > MAX_ID_TOKEN_BYTES
-            || !valid_visible_ascii(token)
-            || !valid_compact_jwt_shape(token)
-    }) {
-        return Err(WireValidationError::new("idToken"));
-    }
-    Ok(())
-}
-
-fn valid_compact_jwt_shape(value: &str) -> bool {
-    let mut segments = value.split('.');
-    matches!(
-        (segments.next(), segments.next(), segments.next(), segments.next()),
-        (Some(header), Some(payload), Some(signature), None)
-            if !header.is_empty() && !payload.is_empty() && !signature.is_empty()
-    )
-}
-
-fn valid_visible_ascii(value: &str) -> bool {
-    !value.is_empty() && value.bytes().all(|byte| (0x21..=0x7e).contains(&byte))
-}
-
 pub(super) fn provider_document_value(document: ProviderDocument) -> Value {
     Value::Object(document.into_provider_data().into_inner())
 }
diff --git a/backend/crates/gateway-api/src/admin/accounts/handlers.rs b/backend/crates/gateway-api/src/admin/accounts/handlers.rs
index 9440d2318..0e952e3f2 100644
--- a/backend/crates/gateway-api/src/admin/accounts/handlers.rs
+++ b/backend/crates/gateway-api/src/admin/accounts/handlers.rs
@@ -12,12 +12,15 @@ where
     Router::new()
         .merge(super::import_tasks::router::<S>())
         .route("/api/admin/accounts", get(list_accounts::<S>))
+        .route(
+            "/api/admin/accounts/providers",
+            get(super::capabilities::providers::<S>),
+        )
         .route("/api/admin/accounts/detail", get(account_detail::<S>))
         .route("/api/admin/accounts/export", get(export_accounts::<S>))
         .route("/api/admin/accounts/import", post(import_accounts::<S>))
         .route("/api/admin/accounts/refresh", post(refresh_account::<S>))
         .route("/api/admin/accounts/recover", post(recover_account::<S>))
-        .route("/api/admin/accounts/rotate", post(rotate_account::<S>))
         .route("/api/admin/accounts/update", post(update_account::<S>))
         .route("/api/admin/accounts/delete", post(delete_accounts::<S>))
         .route(
@@ -62,6 +65,10 @@ where
             "/api/admin/accounts/oauth/complete",
             post(complete_account_authorization::<S>),
         )
+        .route(
+            "/api/admin/accounts/oauth/poll",
+            post(poll_account_authorization::<S>),
+        )
 }
 
 async fn batch_update_accounts<S>(
@@ -168,17 +175,14 @@ where
     let (provider, command) = request
         .into_command(auth.context().mutation_context())
         .map_err(map_wire_error)?;
-    let result = match provider {
-        AccountProvider::OpenAi => {
-            state
-                .admin_services()
-                .openai()
-                .import_document(command)
-                .await
-        }
-        AccountProvider::Xai => state.admin_services().xai().import_document(command).await,
-    }
-    .map_err(map_service_error)?;
+    let result = state
+        .admin_services()
+        .credentials()
+        .for_provider(&provider)
+        .map_err(map_service_error)?
+        .import_document(command)
+        .await
+        .map_err(map_service_error)?;
     Ok(AdminResponse::new(
         StatusCode::CREATED,
         AdminEnvelope::ok(AccountImportData::from_result(result)),
@@ -196,23 +200,14 @@ where
     let (provider, command) = request
         .into_command(auth.context().mutation_context())
         .map_err(map_wire_error)?;
-    let result = match provider {
-        AccountProvider::OpenAi => {
-            state
-                .admin_services()
-                .openai()
-                .start_authorization(command)
-                .await
-        }
-        AccountProvider::Xai => {
-            state
-                .admin_services()
-                .xai()
-                .start_authorization(command)
-                .await
-        }
-    }
-    .map_err(map_service_error)?;
+    let result = state
+        .admin_services()
+        .credentials()
+        .for_provider(&provider)
+        .map_err(map_service_error)?
+        .start_authorization(command)
+        .await
+        .map_err(map_service_error)?;
     Ok(AdminResponse::new(
         StatusCode::CREATED,
         AdminEnvelope::ok(AccountAuthorizationData::from(result)),
@@ -230,49 +225,38 @@ where
     let (provider, command) = request
         .into_command(auth.context().mutation_context())
         .map_err(map_wire_error)?;
-    let result = match provider {
-        AccountProvider::OpenAi => {
-            state
-                .admin_services()
-                .openai()
-                .complete_authorization(command)
-                .await
-        }
-        AccountProvider::Xai => {
-            state
-                .admin_services()
-                .xai()
-                .complete_authorization(command)
-                .await
-        }
-    }
-    .map_err(map_service_error)?;
+    let result = state
+        .admin_services()
+        .credentials()
+        .complete_authorization(&provider, command)
+        .await
+        .map_err(map_service_error)?;
     Ok(AdminResponse::new(
         StatusCode::CREATED,
         AdminEnvelope::ok(AccountMutationData::from(result)),
     ))
 }
 
-async fn rotate_account<S>(
+async fn poll_account_authorization<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    AdminJson(request): AdminJson<RotateAccountRequest>,
+    AdminJson(request): AdminJson<PollAccountAuthorizationRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: SessionState + Send + Sync,
 {
-    let command = request
+    let (provider, command) = request
         .into_command(auth.context().mutation_context())
         .map_err(map_wire_error)?;
     let result = state
         .admin_services()
-        .openai()
-        .rotate(command)
+        .credentials()
+        .poll_authorization(&provider, command)
         .await
         .map_err(map_service_error)?;
     Ok(AdminResponse::new(
         StatusCode::OK,
-        AdminEnvelope::ok(AccountMutationData::from(result)),
+        AdminEnvelope::ok(AccountAuthorizationPollData::from(result)),
     ))
 }
 
@@ -284,13 +268,39 @@ async fn update_account<S>(
 where
     S: SessionState + Send + Sync,
 {
-    let command = request.into_command().map_err(map_wire_error)?;
-    let result = state
-        .admin_services()
-        .accounts()
-        .update(&auth.context().mutation_context(), command)
-        .await
-        .map_err(map_service_error)?;
+    let (command, connection) = request.into_command().map_err(map_wire_error)?;
+    let context = auth.context().mutation_context();
+    let result = if let Some(provider_material) = connection {
+        let provider = ProviderKind::new("openai").map_err(|_| AdminError::internal())?;
+        let account_id = ProviderAccountId::new(command.account_id.clone())
+            .map_err(|_| AdminError::internal())?;
+        let result = state
+            .admin_services()
+            .credentials()
+            .for_provider(&provider)
+            .map_err(map_service_error)?
+            .rotate(RotateCredential {
+                mutation: CredentialMutation {
+                    context,
+                    account_id,
+                },
+                settings: Some(command),
+                provider_material,
+            })
+            .await
+            .map_err(map_service_error)?;
+        AccountUpdateResult {
+            account_id: result.account_id,
+            config_revision: result.config_revision,
+        }
+    } else {
+        state
+            .admin_services()
+            .accounts()
+            .update(&context, command)
+            .await
+            .map_err(map_service_error)?
+    };
     Ok(AdminResponse::new(
         StatusCode::OK,
         AdminEnvelope::ok(UpdatedAccountData::from(result)),
@@ -308,11 +318,14 @@ where
     let (provider, command) = request
         .into_command(auth.context().mutation_context())
         .map_err(map_wire_error)?;
-    let result = match provider {
-        AccountProvider::OpenAi => state.admin_services().openai().delete(command).await,
-        AccountProvider::Xai => state.admin_services().xai().delete(command).await,
-    }
-    .map_err(map_service_error)?;
+    let result = state
+        .admin_services()
+        .credentials()
+        .for_provider(&provider)
+        .map_err(map_service_error)?
+        .delete(command)
+        .await
+        .map_err(map_service_error)?;
     Ok(AdminResponse::new(
         StatusCode::OK,
         AdminEnvelope::ok(AccountDeletionData::from(result)),
diff --git a/backend/crates/gateway-api/src/admin/accounts/import_tasks.rs b/backend/crates/gateway-api/src/admin/accounts/import_tasks.rs
index c81894960..8a8257b76 100644
--- a/backend/crates/gateway-api/src/admin/accounts/import_tasks.rs
+++ b/backend/crates/gateway-api/src/admin/accounts/import_tasks.rs
@@ -152,11 +152,6 @@ where
         .into_iter()
         .map(|item| {
             let (provider, command) = item.into_command(context.clone())?;
-            let provider = ProviderKind::new(match provider {
-                AccountProvider::OpenAi => "openai",
-                AccountProvider::Xai => "xai",
-            })
-            .map_err(|_| WireValidationError::new("provider"))?;
             Ok(ImportTaskInput { provider, command })
         })
         .collect::<Result<Vec<_>, WireValidationError>>()
diff --git a/backend/crates/gateway-api/src/admin/accounts/mod.rs b/backend/crates/gateway-api/src/admin/accounts/mod.rs
index 5681138f0..ade2207b5 100644
--- a/backend/crates/gateway-api/src/admin/accounts/mod.rs
+++ b/backend/crates/gateway-api/src/admin/accounts/mod.rs
@@ -26,10 +26,11 @@ use gateway_admin::model::{
     },
     provider_credentials::{
         AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountPersonalInfo,
-        AccountRefreshResult, AccountUsagePeriod, AuthorizationStarted, CompleteAuthorization,
-        ConsumeProviderResetCredit, CredentialDeletion, CredentialDeletionResult,
-        CredentialImportResult, CredentialMutation, CredentialMutationResult, ImportCredentials,
-        ProviderDocument, ProviderModels, ProviderProfileActivityInsights, ProviderProfileAvatar,
+        AccountRefreshResult, AccountUsagePeriod, AuthorizationPollResult, AuthorizationStarted,
+        CompleteAuthorization, ConsumeProviderResetCredit, CredentialDeletion,
+        CredentialDeletionResult, CredentialImportResult, CredentialMutation,
+        CredentialMutationResult, ImportCredentials, PollAuthorization, ProviderDocument,
+        ProviderModels, ProviderProfileActivityInsights, ProviderProfileAvatar,
         ProviderProfileDailyUsage, ProviderProfileInvocation, ProviderProfileStatistics,
         ProviderProfileStatisticsSummary, ProviderQuota, ProviderQuotaWindow, ProviderResetCredit,
         ProviderResetCreditResult, ProviderResetCredits, ProviderSubscription, RotateCredential,
@@ -56,28 +57,27 @@ const MAX_SEARCH_BYTES: usize = 256;
 const MAX_ID_BYTES: usize = 256;
 const MAX_NAME_BYTES: usize = 512;
 const MAX_IMPORT_DATA_BYTES: usize = 64 * 1024 * 1024;
-const MAX_ACCESS_TOKEN_BYTES: usize = 16 * 1024;
-const MAX_REFRESH_TOKEN_BYTES: usize = 64 * 1024;
-const MAX_ID_TOKEN_BYTES: usize = 16 * 1024;
 const MAX_CALLBACK_URL_BYTES: usize = 64 * 1024;
 const MAX_ACCOUNT_DELETE_BATCH: usize = 200;
 const MAX_ACCOUNT_GROUP_BATCH: usize = 1000;
 const MAX_AVATAR_VERSION_BYTES: usize = 32;
 
+mod capabilities;
 mod credentials;
 mod handlers;
 mod import_tasks;
 mod presenter;
 mod wire;
 
+pub use capabilities::*;
 pub use credentials::*;
 pub use handlers::{profile_avatar_response, router};
 pub(super) use presenter::quota_window_view;
 pub use wire::*;
 
 use credentials::{
-    AccountProvider, parse_account_weight, parse_concurrency_limit, provider_document_value,
-    require_account_id, validate_wire_group_ids,
+    parse_account_weight, parse_concurrency_limit, provider_document_value, require_account_id,
+    validate_wire_group_ids,
 };
 use presenter::*;
 use wire::BatchUpdatedAccountsData;
diff --git a/backend/crates/gateway-api/src/admin/accounts/presenter.rs b/backend/crates/gateway-api/src/admin/accounts/presenter.rs
index 2f2980f1b..1c1e7f167 100644
--- a/backend/crates/gateway-api/src/admin/accounts/presenter.rs
+++ b/backend/crates/gateway-api/src/admin/accounts/presenter.rs
@@ -15,6 +15,7 @@ pub(super) fn account_page_data(
         u32::try_from(result.total.div_ceil(u64::from(page_size))).unwrap_or(u32::MAX)
     };
     AccountPageData {
+        providers: result.providers,
         items: result
             .items
             .into_iter()
@@ -60,6 +61,7 @@ pub(super) fn account_models_data(result: ProviderModels) -> AccountModelsData {
 pub(super) fn account_view(item: AccountDirectoryItem, now: DateTime<Utc>) -> AccountView {
     let AccountDirectoryItem {
         account,
+        capabilities,
         plan_type_display,
         projection,
         usage,
@@ -77,6 +79,7 @@ pub(super) fn account_view(item: AccountDirectoryItem, now: DateTime<Utc>) -> Ac
     }
     let (quota, refresh_token_expires_at) = account_quota_view(quota, cooldown, now);
     AccountView {
+        capabilities: capabilities.into(),
         id: account.id.clone(),
         name: account.name,
         notes: account.notes,
diff --git a/backend/crates/gateway-api/src/admin/accounts/wire.rs b/backend/crates/gateway-api/src/admin/accounts/wire.rs
index cee3b5eab..cdcfcdd86 100644
--- a/backend/crates/gateway-api/src/admin/accounts/wire.rs
+++ b/backend/crates/gateway-api/src/admin/accounts/wire.rs
@@ -162,7 +162,7 @@ impl ListQuery {
         if page_size == 0 || page_size > MAX_PAGE_SIZE {
             return Err(WireValidationError::new("pageSize"));
         }
-        let provider_kind = parse_provider(self.provider.as_deref().unwrap_or("all"))?;
+        let provider_kind = parse_provider(self.provider.as_deref().unwrap_or_default())?;
         let group_filter = match self.group_id.as_deref().map(str::trim) {
             None | Some("") => None,
             Some("ungrouped") => Some(AccountGroupFilter::Ungrouped),
@@ -213,7 +213,7 @@ impl ListQuery {
 
 fn parse_provider(value: &str) -> Result<Option<ProviderKind>, WireValidationError> {
     let value = value.trim();
-    if value.is_empty() || value.eq_ignore_ascii_case("all") {
+    if value.is_empty() {
         return Ok(None);
     }
     ProviderKind::new(value.to_owned())
@@ -248,6 +248,7 @@ pub struct AccountPageData {
     pub items: Vec<AccountView>,
     pub page: PageMeta,
     pub summary: AccountSummaryView,
+    pub providers: Vec<String>,
 }
 
 /// 账号概览计数。
@@ -266,6 +267,7 @@ pub struct AccountSummaryView {
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AccountView {
+    pub capabilities: AccountCapabilitiesView,
     pub outbound_proxy_endpoint: Option<String>,
     pub id: String,
     pub name: String,
@@ -303,6 +305,36 @@ pub struct AccountView {
     pub usage: AccountUsageView,
 }
 
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountCapabilitiesView {
+    pub quota: bool,
+    pub quota_refresh: bool,
+    pub profile: bool,
+    pub subscription: bool,
+    pub avatar: bool,
+    pub reset_credits: bool,
+    pub consume_reset_credit: bool,
+}
+
+impl From<gateway_admin::model::provider_capabilities::ProviderAccountCapabilities>
+    for AccountCapabilitiesView
+{
+    fn from(
+        value: gateway_admin::model::provider_capabilities::ProviderAccountCapabilities,
+    ) -> Self {
+        Self {
+            quota: value.quota,
+            quota_refresh: value.quota_refresh,
+            profile: value.profile,
+            subscription: value.subscription,
+            avatar: value.avatar,
+            reset_credits: value.reset_credits,
+            consume_reset_credit: value.consume_reset_credit,
+        }
+    }
+}
+
 /// 容量估算仅供管理端展示；金额不是订阅账单或可消费余额。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
diff --git a/backend/crates/gateway-api/src/admin/client_keys.rs b/backend/crates/gateway-api/src/admin/client_keys.rs
index 941a131ef..2b7e610ee 100644
--- a/backend/crates/gateway-api/src/admin/client_keys.rs
+++ b/backend/crates/gateway-api/src/admin/client_keys.rs
@@ -2,7 +2,7 @@
 
 use crate::auth::SessionState;
 
-use std::fmt;
+use std::{collections::BTreeMap, fmt};
 
 use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
 use chrono::{DateTime, Utc};
@@ -17,7 +17,7 @@ use gateway_core::{
     engine::budget::ClientBudgetLimits,
     metering::Decimal,
     policy::{ClientApiKeyId, PlaintextClientApiKey, RateLimits},
-    routing::AccountGroupId,
+    routing::{AccountGroupId, ProviderKind},
 };
 use serde::{Deserialize, Serialize};
 
@@ -38,6 +38,10 @@ const MAX_CURSOR_BYTES: usize = 512;
 const MAX_SEARCH_BYTES: usize = 256;
 const DEFAULT_PAGE_SIZE: u16 = 50;
 
+type ProviderRequestProfileOverrides = BTreeMap<String, serde_json::Map<String, serde_json::Value>>;
+type ProviderRequestProfileOverrideUpdates =
+    BTreeMap<String, Option<serde_json::Map<String, serde_json::Value>>>;
+
 fn parse_budget(
     value: Option<String>,
     field: &'static str,
@@ -147,6 +151,8 @@ impl ClientKeySort {
 #[derive(Clone, PartialEq, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct CreateClientKeyRequest {
+    #[serde(default)]
+    provider_request_profile_overrides: ProviderRequestProfileOverrides,
     openai_client_profile_override: Option<serde_json::Map<String, serde_json::Value>>,
     xai_client_profile_override: Option<serde_json::Map<String, serde_json::Value>>,
     custom_key: Option<String>,
@@ -177,13 +183,13 @@ impl CreateClientKeyRequest {
         let group_ids = validate_group_ids(self.group_ids)?;
         validate_limit(self.max_concurrency, "maxConcurrency")?;
         validate_limit(self.requests_per_minute, "requestsPerMinute")?;
+        let request_profile_overrides = normalize_request_profile_overrides(
+            self.provider_request_profile_overrides,
+            self.openai_client_profile_override,
+            self.xai_client_profile_override,
+        )?;
         Ok(CreateClientKey {
-            openai_client_profile_override: self
-                .openai_client_profile_override
-                .map(gateway_core::account::OpaqueProviderData::new),
-            xai_client_profile_override: self
-                .xai_client_profile_override
-                .map(gateway_core::account::OpaqueProviderData::new),
+            request_profile_overrides,
             custom_key: self
                 .custom_key
                 .filter(|key| !key.is_empty())
@@ -210,6 +216,8 @@ impl CreateClientKeyRequest {
 #[derive(Debug, Clone, PartialEq, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct UpdateClientKeyRequest {
+    #[serde(default)]
+    provider_request_profile_overrides: ProviderRequestProfileOverrideUpdates,
     #[serde(default, deserialize_with = "deserialize_profile_override")]
     openai_client_profile_override: Option<Option<serde_json::Map<String, serde_json::Value>>>,
     #[serde(default, deserialize_with = "deserialize_profile_override")]
@@ -233,13 +241,13 @@ impl UpdateClientKeyRequest {
         let group_ids = validate_group_ids(self.group_ids)?;
         validate_limit(self.max_concurrency, "maxConcurrency")?;
         validate_limit(self.requests_per_minute, "requestsPerMinute")?;
+        let request_profile_override_updates = normalize_request_profile_override_updates(
+            self.provider_request_profile_overrides,
+            self.openai_client_profile_override,
+            self.xai_client_profile_override,
+        )?;
         Ok(UpdateClientKey {
-            openai_client_profile_override: self
-                .openai_client_profile_override
-                .map(|value| value.map(gateway_core::account::OpaqueProviderData::new)),
-            xai_client_profile_override: self
-                .xai_client_profile_override
-                .map(|value| value.map(gateway_core::account::OpaqueProviderData::new)),
+            request_profile_override_updates,
             id: client_key_id(self.id, "clientKeyMutationNotFound")?,
             name: self.name,
             label: self.label,
@@ -325,7 +333,10 @@ impl ClientKeyMutationRequest {
 #[derive(Debug, Clone, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ClientKeyView {
+    provider_request_profile_overrides: ProviderRequestProfileOverrides,
+    /// 固定兼容字段；值始终从 provider_request_profile_overrides 派生。
     openai_client_profile_override: Option<serde_json::Map<String, serde_json::Value>>,
+    /// 固定兼容字段；值始终从 provider_request_profile_overrides 派生。
     xai_client_profile_override: Option<serde_json::Map<String, serde_json::Value>>,
     id: String,
     name: String,
@@ -364,13 +375,17 @@ impl From<ClientKeyRecord> for ClientKeyView {
         } else {
             "groups"
         };
+        let provider_request_profile_overrides = record
+            .request_profile_overrides
+            .into_iter()
+            .map(|(provider, profile)| (provider.as_str().to_owned(), profile.into_inner()))
+            .collect::<ProviderRequestProfileOverrides>();
         Self {
-            openai_client_profile_override: record
-                .openai_client_profile_override
-                .map(gateway_core::account::OpaqueProviderData::into_inner),
-            xai_client_profile_override: record
-                .xai_client_profile_override
-                .map(gateway_core::account::OpaqueProviderData::into_inner),
+            openai_client_profile_override: provider_request_profile_overrides
+                .get("openai")
+                .cloned(),
+            xai_client_profile_override: provider_request_profile_overrides.get("xai").cloned(),
+            provider_request_profile_overrides,
             id: record.id.to_string(),
             name: record.name,
             label: record.label,
@@ -702,6 +717,102 @@ fn validate_limit(value: u64, field: &'static str) -> Result<(), WireValidationE
     Ok(())
 }
 
+fn normalize_request_profile_overrides(
+    profiles: ProviderRequestProfileOverrides,
+    openai: Option<serde_json::Map<String, serde_json::Value>>,
+    xai: Option<serde_json::Map<String, serde_json::Value>>,
+) -> Result<gateway_admin::model::client_keys::ProviderRequestProfileOverrides, WireValidationError>
+{
+    if profiles.len() > 256 {
+        return Err(WireValidationError::new("providerRequestProfileOverrides"));
+    }
+    let mut normalized = profiles
+        .into_iter()
+        .map(|(provider, profile)| {
+            validate_request_profile_size(&profile)?;
+            Ok((
+                ProviderKind::new(provider)
+                    .map_err(|_| WireValidationError::new("providerRequestProfileOverrides"))?,
+                gateway_core::account::OpaqueProviderData::new(profile),
+            ))
+        })
+        .collect::<Result<gateway_admin::model::client_keys::ProviderRequestProfileOverrides, _>>(
+        )?;
+    for (provider, profile) in [("openai", openai), ("xai", xai)] {
+        let Some(profile) = profile else {
+            continue;
+        };
+        validate_request_profile_size(&profile)?;
+        let provider = ProviderKind::new(provider).expect("static Provider kind is valid");
+        let profile = gateway_core::account::OpaqueProviderData::new(profile);
+        if normalized
+            .get(&provider)
+            .is_some_and(|current| current != &profile)
+        {
+            return Err(WireValidationError::new("providerRequestProfileOverrides"));
+        }
+        normalized.insert(provider, profile);
+    }
+    Ok(normalized)
+}
+
+fn normalize_request_profile_override_updates(
+    profiles: ProviderRequestProfileOverrideUpdates,
+    openai: Option<Option<serde_json::Map<String, serde_json::Value>>>,
+    xai: Option<Option<serde_json::Map<String, serde_json::Value>>>,
+) -> Result<
+    gateway_admin::model::client_keys::ProviderRequestProfileOverrideUpdates,
+    WireValidationError,
+> {
+    if profiles.len() > 256 {
+        return Err(WireValidationError::new("providerRequestProfileOverrides"));
+    }
+    let mut normalized = profiles
+        .into_iter()
+        .map(|(provider, profile)| {
+            if let Some(profile) = profile.as_ref() {
+                validate_request_profile_size(profile)?;
+            }
+            Ok((
+                ProviderKind::new(provider).map_err(|_| {
+                    WireValidationError::new("providerRequestProfileOverrides")
+                })?,
+                profile.map(gateway_core::account::OpaqueProviderData::new),
+            ))
+        })
+        .collect::<Result<
+            gateway_admin::model::client_keys::ProviderRequestProfileOverrideUpdates,
+            _,
+        >>()?;
+    for (provider, profile) in [("openai", openai), ("xai", xai)] {
+        let Some(profile) = profile else {
+            continue;
+        };
+        if let Some(profile) = profile.as_ref() {
+            validate_request_profile_size(profile)?;
+        }
+        let provider = ProviderKind::new(provider).expect("static Provider kind is valid");
+        let profile = profile.map(gateway_core::account::OpaqueProviderData::new);
+        if normalized
+            .get(&provider)
+            .is_some_and(|current| current != &profile)
+        {
+            return Err(WireValidationError::new("providerRequestProfileOverrides"));
+        }
+        normalized.insert(provider, profile);
+    }
+    Ok(normalized)
+}
+
+fn validate_request_profile_size(
+    profile: &serde_json::Map<String, serde_json::Value>,
+) -> Result<(), WireValidationError> {
+    if serde_json::to_vec(profile).map_or(true, |encoded| encoded.len() > 64 * 1024) {
+        return Err(WireValidationError::new("providerRequestProfileOverrides"));
+    }
+    Ok(())
+}
+
 fn validate_required_text(value: &str, field: &'static str) -> Result<(), WireValidationError> {
     if value.trim().is_empty() {
         return Err(WireValidationError::new(field));
diff --git a/backend/crates/gateway-api/src/admin/mod.rs b/backend/crates/gateway-api/src/admin/mod.rs
index e5061e5ed..230f2f7b6 100644
--- a/backend/crates/gateway-api/src/admin/mod.rs
+++ b/backend/crates/gateway-api/src/admin/mod.rs
@@ -17,6 +17,7 @@ pub mod backups;
 pub mod client_keys;
 mod extract;
 pub mod observability;
+mod plugins;
 pub mod presenter;
 pub mod proxies;
 pub mod settings;
@@ -30,7 +31,11 @@ pub use wire::{
     AdminPageData, AdminResponse, PageMeta, WireValidationError,
 };
 
-/// 构造完整且固定的 `/api/admin` 路由。
+pub(crate) fn model_router() -> Router<crate::ApiState> {
+    plugins::model_router().layer(middleware::map_response(no_store))
+}
+
+/// 构造管理用例路由；模型执行桥由完整 API 组合单独装配。
 pub fn router<S>() -> Router<S>
 where
     S: SessionState + Clone + Send + Sync + 'static,
@@ -38,6 +43,7 @@ where
     Router::new()
         .merge(account_groups::router::<S>())
         .merge(proxies::router::<S>())
+        .merge(plugins::router::<S>())
         .merge(accounts::router::<S>())
         .merge(backups::router::<S>())
         .merge(client_keys::router::<S>())
diff --git a/backend/crates/gateway-api/src/admin/observability/query.rs b/backend/crates/gateway-api/src/admin/observability/query.rs
index 3b0acc118..6171e81ec 100644
--- a/backend/crates/gateway-api/src/admin/observability/query.rs
+++ b/backend/crates/gateway-api/src/admin/observability/query.rs
@@ -23,6 +23,14 @@ impl DashboardQuery {
     }
 }
 
+/// 用量页面的平台筛选范围，与分页及当前平台选择无关。
+#[derive(Clone, Default, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct UsageProvidersQuery {
+    pub start_time: Option<String>,
+    pub end_time: Option<String>,
+}
+
 /// 逻辑请求列表、汇总和洞察查询参数。
 #[derive(Clone, Default, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
diff --git a/backend/crates/gateway-api/src/admin/observability/routes.rs b/backend/crates/gateway-api/src/admin/observability/routes.rs
index e0f147eb0..182841c0d 100644
--- a/backend/crates/gateway-api/src/admin/observability/routes.rs
+++ b/backend/crates/gateway-api/src/admin/observability/routes.rs
@@ -12,6 +12,7 @@ where
         .route("/api/admin/dashboard/summary", get(dashboard_summary::<S>))
         .route("/api/admin/dashboard/trend", get(dashboard_trend::<S>))
         .route("/api/admin/usage/records", get(usage_records::<S>))
+        .route("/api/admin/usage/providers", get(usage_providers::<S>))
         .route(
             "/api/admin/usage/records/detail",
             get(usage_record_detail::<S>),
@@ -118,6 +119,28 @@ where
     ))
 }
 
+pub(crate) async fn usage_providers<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<UsageProvidersQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: SessionState + Send + Sync,
+{
+    let range = usage_range(query.start_time.as_deref(), query.end_time.as_deref())
+        .map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .observability()
+        .usage_provider_kinds(range)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(result),
+    ))
+}
+
 pub(crate) async fn usage_records_summary<S>(
     _auth: AdminAuth,
     State(state): State<S>,
diff --git a/backend/crates/gateway-api/src/admin/plugins/artifacts.rs b/backend/crates/gateway-api/src/admin/plugins/artifacts.rs
new file mode 100644
index 000000000..41a3afbdb
--- /dev/null
+++ b/backend/crates/gateway-api/src/admin/plugins/artifacts.rs
@@ -0,0 +1,282 @@
+use axum::{
+    Router,
+    body::{Body, Bytes},
+    extract::{DefaultBodyLimit, Path, State, rejection::BytesRejection},
+    http::{HeaderValue, StatusCode, header},
+    response::{IntoResponse, Response},
+    routing::{get, post},
+};
+use gateway_admin::model::plugins::{
+    InstalledPluginArtifact, PluginArtifactMetadata, PluginIconTheme, PluginInstallResult,
+    PluginPermissionDescription, PluginSource, distribution::VerifiedPluginArtifact,
+};
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    admin::{
+        AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse,
+        wire::map_admin_service_error,
+    },
+    auth::SessionState,
+};
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(super) struct ArtifactView {
+    metadata: MetadataView,
+    source: PluginSource,
+    installed_at: String,
+    accepted_at: Option<String>,
+}
+
+impl ArtifactView {
+    fn new(value: InstalledPluginArtifact, service: &gateway_admin::PluginsService) -> Self {
+        Self {
+            metadata: MetadataView::new(value.metadata, service),
+            source: value.source,
+            installed_at: value.installed_at.to_rfc3339(),
+            accepted_at: value.accepted_at.map(|value| value.to_rfc3339()),
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct MetadataView {
+    #[serde(flatten)]
+    metadata: PluginArtifactMetadata,
+    permission_descriptions: Vec<PluginPermissionDescription>,
+}
+
+impl MetadataView {
+    fn new(metadata: PluginArtifactMetadata, service: &gateway_admin::PluginsService) -> Self {
+        Self {
+            permission_descriptions: service
+                .permission_descriptions(&metadata.requested_permissions),
+            metadata,
+        }
+    }
+}
+
+#[derive(Serialize)]
+pub(super) struct VerifiedArtifactView {
+    metadata: MetadataView,
+    source: PluginSource,
+}
+
+impl VerifiedArtifactView {
+    pub(super) fn new(
+        value: VerifiedPluginArtifact,
+        service: &gateway_admin::PluginsService,
+    ) -> Self {
+        Self {
+            metadata: MetadataView::new(value.metadata, service),
+            source: value.source,
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(super) struct InstallResultView {
+    artifact: ArtifactView,
+    config_revision: u64,
+    default_instance_id: Option<String>,
+    configuration_required: bool,
+}
+
+impl InstallResultView {
+    pub(super) fn new(value: PluginInstallResult, service: &gateway_admin::PluginsService) -> Self {
+        Self {
+            artifact: ArtifactView::new(value.mutation.artifact, service),
+            config_revision: value.mutation.config_revision.get(),
+            default_instance_id: value.default_instance_id,
+            configuration_required: value.configuration_required,
+        }
+    }
+}
+
+pub(in crate::admin) fn router<S: SessionState + Clone + Send + Sync + 'static>() -> Router<S> {
+    Router::new()
+        .route("/api/admin/plugins/artifacts", get(list::<S>))
+        .route("/api/admin/plugins/artifacts/{sha256}/icon", get(icon::<S>))
+        .route(
+            "/api/admin/plugins/artifacts/upload",
+            post(upload::<S>).layer(DefaultBodyLimit::max(32 * 1024 * 1024)),
+        )
+        .route(
+            "/api/admin/plugins/artifacts/upload/verify",
+            post(verify_upload::<S>).layer(DefaultBodyLimit::max(32 * 1024 * 1024)),
+        )
+        .route("/api/admin/plugins/artifacts/accept", post(accept::<S>))
+        .route("/api/admin/plugins/artifacts/delete", post(remove::<S>))
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "lowercase", deny_unknown_fields)]
+enum IconTheme {
+    Light,
+    Dark,
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct IconQuery {
+    theme: IconTheme,
+}
+
+async fn icon<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+    Path(sha256): Path<String>,
+    AdminQuery(query): AdminQuery<IconQuery>,
+) -> Result<Response, AdminError> {
+    let theme = match query.theme {
+        IconTheme::Light => PluginIconTheme::Light,
+        IconTheme::Dark => PluginIconTheme::Dark,
+    };
+    let icon = state
+        .admin_services()
+        .plugins()
+        .icon(&sha256, theme)
+        .await
+        .map_err(map_admin_service_error)?;
+    let content_type =
+        HeaderValue::from_str(&icon.content_type).map_err(|_| AdminError::internal())?;
+    let mut response = Response::new(Body::from(icon.body));
+    let headers = response.headers_mut();
+    headers.insert(header::CONTENT_TYPE, content_type);
+    headers.insert(
+        header::CONTENT_SECURITY_POLICY,
+        // 图标只作为图片加载；SVG 可用内联样式与内嵌图片，但不能执行脚本或请求外部资源。
+        HeaderValue::from_static("sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data:; base-uri 'none'; form-action 'none'"),
+    );
+    headers.insert(
+        header::X_CONTENT_TYPE_OPTIONS,
+        HeaderValue::from_static("nosniff"),
+    );
+    headers.insert(
+        header::CACHE_CONTROL,
+        HeaderValue::from_static("private, max-age=31536000, immutable"),
+    );
+    Ok(response)
+}
+
+async fn list<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError> {
+    let items: Vec<ArtifactView> = state
+        .admin_services()
+        .plugins()
+        .list()
+        .await
+        .map_err(map_admin_service_error)?
+        .into_iter()
+        .map(|artifact| ArtifactView::new(artifact, state.admin_services().plugins()))
+        .collect();
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(items)))
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct UploadQuery {
+    sha256: Option<String>,
+}
+
+async fn verify_upload<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+    bytes: Result<Bytes, BytesRejection>,
+) -> Result<impl IntoResponse, AdminError> {
+    let bytes = bytes.map_err(|error| {
+        AdminError::invalid_request(error.status(), "插件包读取失败或超过大小限制")
+    })?;
+    let result = state
+        .admin_services()
+        .plugins()
+        .verify_upload(bytes.to_vec().into())
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(VerifiedArtifactView::new(
+            result,
+            state.admin_services().plugins(),
+        )),
+    ))
+}
+
+async fn upload<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<UploadQuery>,
+    bytes: Result<Bytes, BytesRejection>,
+) -> Result<impl IntoResponse, AdminError> {
+    let bytes = bytes.map_err(|error| {
+        AdminError::invalid_request(error.status(), "插件包读取失败或超过大小限制")
+    })?;
+    let result = state
+        .admin_services()
+        .plugins()
+        .install_upload(
+            bytes.to_vec().into(),
+            query.sha256,
+            &auth.context().mutation_context(),
+        )
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(InstallResultView::new(
+            result,
+            state.admin_services().plugins(),
+        )),
+    ))
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct AcceptArtifact {
+    sha256: String,
+}
+
+async fn accept<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AcceptArtifact>,
+) -> Result<impl IntoResponse, AdminError> {
+    let result = state
+        .admin_services()
+        .plugins()
+        .accept_artifact(&request.sha256, &auth.context().mutation_context())
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(InstallResultView::new(
+            result,
+            state.admin_services().plugins(),
+        )),
+    ))
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct DeleteArtifact {
+    sha256: String,
+}
+
+async fn remove<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<DeleteArtifact>,
+) -> Result<impl IntoResponse, AdminError> {
+    state
+        .admin_services()
+        .plugins()
+        .delete(&request.sha256, &auth.context().mutation_context())
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(())))
+}
diff --git a/backend/crates/gateway-api/src/admin/plugins/distribution.rs b/backend/crates/gateway-api/src/admin/plugins/distribution.rs
new file mode 100644
index 000000000..2473318ba
--- /dev/null
+++ b/backend/crates/gateway-api/src/admin/plugins/distribution.rs
@@ -0,0 +1,238 @@
+use axum::{
+    Router,
+    extract::State,
+    http::StatusCode,
+    response::IntoResponse,
+    routing::{get, post},
+};
+use gateway_admin::model::plugins::distribution::{
+    DownloadPurpose, GithubReleaseQuery, RemotePluginInstall, RemotePluginVerify,
+    SourceAuthentication, SourceCredentialInfo,
+};
+use serde::Deserialize;
+
+use super::artifacts::{InstallResultView, VerifiedArtifactView};
+use crate::{
+    admin::{
+        AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminResponse,
+        wire::map_admin_service_error,
+    },
+    auth::SessionState,
+};
+
+pub(super) fn router<S: SessionState + Clone + Send + Sync + 'static>() -> Router<S> {
+    Router::new()
+        .route(
+            "/api/admin/plugins/update-sources",
+            get(update_sources::<S>).post(change_update_source::<S>),
+        )
+        .route("/api/admin/plugins/releases/query", post(query::<S>))
+        .route("/api/admin/plugins/updates/check", post(check_update::<S>))
+        .route("/api/admin/plugins/artifacts/install", post(install::<S>))
+        .route("/api/admin/plugins/artifacts/verify", post(verify::<S>))
+        .route(
+            "/api/admin/plugins/source-credentials",
+            get(credentials::<S>).post(create_credential::<S>),
+        )
+        .route(
+            "/api/admin/plugins/source-credentials/delete",
+            post(remove_credential::<S>),
+        )
+}
+
+async fn update_sources<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError> {
+    let sources = state
+        .admin_services()
+        .plugins()
+        .update_sources()
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(sources),
+    ))
+}
+
+async fn change_update_source<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(binding): AdminJson<gateway_admin::model::plugins::distribution::PluginSourceBinding>,
+) -> Result<impl IntoResponse, AdminError> {
+    let revision = state
+        .admin_services()
+        .plugins()
+        .change_update_source(binding, &auth.context().mutation_context())
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(serde_json::json!({"configRevision":revision.get()})),
+    ))
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct ReleaseQueryRequest {
+    query: GithubReleaseQuery,
+    #[serde(default)]
+    credential_ids: Vec<String>,
+    #[serde(default)]
+    outbound_proxy_id: Option<String>,
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct UpdateCheckRequest {
+    plugin_id: String,
+    #[serde(default)]
+    credential_ids: Vec<String>,
+}
+
+async fn check_update<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<UpdateCheckRequest>,
+) -> Result<impl IntoResponse, AdminError> {
+    let check = state
+        .admin_services()
+        .plugins()
+        .check_update(&request.plugin_id, &request.credential_ids)
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(check)))
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct CredentialRequest {
+    name: String,
+    origin: String,
+    path_prefix: String,
+    purposes: Vec<DownloadPurpose>,
+    authentication: SourceAuthentication,
+}
+
+async fn query<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<ReleaseQueryRequest>,
+) -> Result<impl IntoResponse, AdminError> {
+    let release = state
+        .admin_services()
+        .plugins()
+        .query_release(
+            request.query,
+            &request.credential_ids,
+            request.outbound_proxy_id.as_deref(),
+        )
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(release),
+    ))
+}
+
+async fn verify<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<RemotePluginVerify>,
+) -> Result<impl IntoResponse, AdminError> {
+    let result = state
+        .admin_services()
+        .plugins()
+        .verify_remote(request)
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(VerifiedArtifactView::new(
+            result,
+            state.admin_services().plugins(),
+        )),
+    ))
+}
+
+async fn install<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<RemotePluginInstall>,
+) -> Result<impl IntoResponse, AdminError> {
+    let result = state
+        .admin_services()
+        .plugins()
+        .install_remote(request, &auth.context().mutation_context())
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(InstallResultView::new(
+            result,
+            state.admin_services().plugins(),
+        )),
+    ))
+}
+
+async fn credentials<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError> {
+    let credentials = state
+        .admin_services()
+        .plugins()
+        .source_credentials()
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(credentials),
+    ))
+}
+
+async fn create_credential<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<CredentialRequest>,
+) -> Result<impl IntoResponse, AdminError> {
+    let info = SourceCredentialInfo {
+        id: String::new(),
+        name: request.name,
+        origin: request.origin,
+        path_prefix: request.path_prefix,
+        purposes: request.purposes,
+    };
+    let info = state
+        .admin_services()
+        .plugins()
+        .create_source_credential(
+            info,
+            request.authentication,
+            &auth.context().mutation_context(),
+        )
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(info),
+    ))
+}
+
+async fn remove_credential<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<super::IdRequest>,
+) -> Result<impl IntoResponse, AdminError> {
+    let revision = state
+        .admin_services()
+        .plugins()
+        .delete_source_credential(&request.id, &auth.context().mutation_context())
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(serde_json::json!({"configRevision":revision.get()})),
+    ))
+}
diff --git a/backend/crates/gateway-api/src/admin/plugins/instances.rs b/backend/crates/gateway-api/src/admin/plugins/instances.rs
new file mode 100644
index 000000000..abece7523
--- /dev/null
+++ b/backend/crates/gateway-api/src/admin/plugins/instances.rs
@@ -0,0 +1,351 @@
+use axum::{
+    Router,
+    extract::{Query, State},
+    http::StatusCode,
+    response::IntoResponse,
+    routing::{get, post},
+};
+use gateway_admin::model::plugins::instances::{
+    ConfigurePluginInstance, PluginCapabilityBinding, PluginInstance, PluginInstanceRuntime,
+    PluginInstanceRuntimeFailure, PluginInstanceRuntimeStatus, PluginInstanceView,
+    RollbackPluginInstance,
+};
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    admin::{
+        AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminResponse,
+        wire::map_admin_service_error,
+    },
+    auth::SessionState,
+};
+
+pub(super) fn router<S: SessionState + Clone + Send + Sync + 'static>() -> Router<S> {
+    Router::new()
+        .route(
+            "/api/admin/plugins/instances",
+            get(list::<S>).post(create::<S>),
+        )
+        .route("/api/admin/plugins/instances/update", post(configure::<S>))
+        .route("/api/admin/plugins/instances/rollback", post(rollback::<S>))
+        .route(
+            "/api/admin/plugins/instances/switch-version",
+            post(switch_version::<S>),
+        )
+        .route(
+            "/api/admin/plugins/instances/version-plan",
+            get(version_plan::<S>),
+        )
+        .route(
+            "/api/admin/plugins/instances/rollback-plan",
+            get(rollback_plan::<S>),
+        )
+        .route("/api/admin/plugins/instances/disable", post(disable::<S>))
+        .route("/api/admin/plugins/instances/delete", post(remove::<S>))
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct InstanceView {
+    id: String,
+    name: String,
+    artifact_sha256: String,
+    enabled: bool,
+    configuration_required: bool,
+    configuration: serde_json::Value,
+    secret_fields: Vec<String>,
+    bindings: Vec<PluginCapabilityBinding>,
+    revision: u64,
+    running: bool,
+    published_revision: Option<u64>,
+    runtime: InstanceRuntimeView,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "snake_case")]
+enum InstanceRuntimeStatus {
+    Disabled,
+    AwaitingPublication,
+    Preparing,
+    Running,
+    Blocked,
+    PreparationFailed,
+    Faulted,
+    Draining,
+}
+
+impl From<PluginInstanceRuntimeStatus> for InstanceRuntimeStatus {
+    fn from(value: PluginInstanceRuntimeStatus) -> Self {
+        match value {
+            PluginInstanceRuntimeStatus::Disabled => Self::Disabled,
+            PluginInstanceRuntimeStatus::AwaitingPublication => Self::AwaitingPublication,
+            PluginInstanceRuntimeStatus::Preparing => Self::Preparing,
+            PluginInstanceRuntimeStatus::Running => Self::Running,
+            PluginInstanceRuntimeStatus::Blocked => Self::Blocked,
+            PluginInstanceRuntimeStatus::PreparationFailed => Self::PreparationFailed,
+            PluginInstanceRuntimeStatus::Faulted => Self::Faulted,
+            PluginInstanceRuntimeStatus::Draining => Self::Draining,
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct InstanceRuntimeFailure {
+    code: String,
+    message: String,
+}
+
+impl From<PluginInstanceRuntimeFailure> for InstanceRuntimeFailure {
+    fn from(value: PluginInstanceRuntimeFailure) -> Self {
+        Self {
+            code: value.code,
+            message: value.message,
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct InstanceRuntimeView {
+    status: InstanceRuntimeStatus,
+    actual_revision: Option<u64>,
+    actual_artifact_sha256: Option<String>,
+    failure: Option<InstanceRuntimeFailure>,
+    draining_revisions: Vec<u64>,
+    retained_continuations: u32,
+}
+
+impl From<PluginInstanceRuntime> for InstanceRuntimeView {
+    fn from(value: PluginInstanceRuntime) -> Self {
+        Self {
+            status: value.status.into(),
+            actual_revision: value.actual_revision,
+            actual_artifact_sha256: value.actual_artifact_sha256,
+            failure: value.failure.map(Into::into),
+            draining_revisions: value.draining_revisions,
+            retained_continuations: value.retained_continuations,
+        }
+    }
+}
+
+impl From<PluginInstanceView> for InstanceView {
+    fn from(value: PluginInstanceView) -> Self {
+        let PluginInstance {
+            id,
+            name,
+            artifact_sha256,
+            enabled,
+            trusted_process: _,
+            configuration,
+            secrets,
+            grants: _,
+            bindings,
+            revision,
+        } = value.instance;
+        Self {
+            id,
+            name,
+            artifact_sha256,
+            enabled,
+            configuration_required: value.configuration_required,
+            configuration,
+            secret_fields: secrets.into_keys().collect(),
+            bindings,
+            revision: revision.get(),
+            running: value.running,
+            published_revision: value.published_revision,
+            runtime: value.runtime.into(),
+        }
+    }
+}
+
+async fn list<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError> {
+    let instances: Vec<InstanceView> = state
+        .admin_services()
+        .plugins()
+        .instances()
+        .await
+        .map_err(map_admin_service_error)?
+        .into_iter()
+        .map(Into::into)
+        .collect();
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(instances),
+    ))
+}
+
+async fn create<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(input): AdminJson<ConfigurePluginInstance>,
+) -> Result<impl IntoResponse, AdminError> {
+    let result = state
+        .admin_services()
+        .plugins()
+        .configure_instance(None, input, &auth.context().mutation_context())
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(
+            serde_json::json!({"id":result.instance.id,"configRevision":result.config_revision.get()}),
+        ),
+    ))
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct ConfigureRequest {
+    id: String,
+    instance: ConfigurePluginInstance,
+}
+
+async fn configure<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<ConfigureRequest>,
+) -> Result<impl IntoResponse, AdminError> {
+    let result = state
+        .admin_services()
+        .plugins()
+        .configure_instance(
+            Some(&request.id),
+            request.instance,
+            &auth.context().mutation_context(),
+        )
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(
+            serde_json::json!({"id":result.instance.id,"configRevision":result.config_revision.get()}),
+        ),
+    ))
+}
+
+async fn disable<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<super::IdRequest>,
+) -> Result<impl IntoResponse, AdminError> {
+    let result = state
+        .admin_services()
+        .plugins()
+        .disable_instance(&request.id, &auth.context().mutation_context())
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(serde_json::json!({"configRevision":result.config_revision.get()})),
+    ))
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RollbackRequest {
+    id: String,
+    target: RollbackPluginInstance,
+}
+
+async fn rollback_plan<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+    Query(request): Query<super::IdRequest>,
+) -> Result<impl IntoResponse, AdminError> {
+    let plan = state
+        .admin_services()
+        .plugins()
+        .rollback_plan(&request.id)
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(plan)))
+}
+
+async fn rollback<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<RollbackRequest>,
+) -> Result<impl IntoResponse, AdminError> {
+    let result = state
+        .admin_services()
+        .plugins()
+        .rollback_instance(
+            &request.id,
+            request.target,
+            &auth.context().mutation_context(),
+        )
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(
+            serde_json::json!({"id":result.instance.id,"configRevision":result.config_revision.get()}),
+        ),
+    ))
+}
+
+async fn remove<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<super::IdRequest>,
+) -> Result<impl IntoResponse, AdminError> {
+    let revision = state
+        .admin_services()
+        .plugins()
+        .delete_instance(&request.id, &auth.context().mutation_context())
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(serde_json::json!({"configRevision":revision.get()})),
+    ))
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct VersionPlanQuery {
+    id: String,
+    artifact_sha256: String,
+}
+
+async fn version_plan<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+    Query(request): Query<VersionPlanQuery>,
+) -> Result<impl IntoResponse, AdminError> {
+    let plan = state
+        .admin_services()
+        .plugins()
+        .version_plan(&request.id, &request.artifact_sha256)
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(plan)))
+}
+
+async fn switch_version<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<RollbackRequest>,
+) -> Result<impl IntoResponse, AdminError> {
+    let result = state
+        .admin_services()
+        .plugins()
+        .switch_instance_version(
+            &request.id,
+            request.target,
+            &auth.context().mutation_context(),
+        )
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(
+            serde_json::json!({"id":result.instance.id,"configRevision":result.config_revision.get()}),
+        ),
+    ))
+}
diff --git a/backend/crates/gateway-api/src/admin/plugins/management.rs b/backend/crates/gateway-api/src/admin/plugins/management.rs
new file mode 100644
index 000000000..e165e28a2
--- /dev/null
+++ b/backend/crates/gateway-api/src/admin/plugins/management.rs
@@ -0,0 +1,456 @@
+use std::{net::SocketAddr, sync::Arc};
+
+use axum::{
+    Router,
+    body::{Body, Bytes, to_bytes},
+    extract::{
+        ConnectInfo, DefaultBodyLimit, Extension, Path, Request, State, rejection::BytesRejection,
+    },
+    http::{HeaderMap, HeaderName, HeaderValue, StatusCode, header},
+    response::{IntoResponse, Response},
+    routing::{any, get, post},
+};
+use base64::Engine as _;
+use futures::future::BoxFuture;
+use gateway_admin::model::plugins::management::{
+    PluginManagementRequest, PluginManagementResponse, PluginManagementTarget,
+    StartPluginManagementCallback,
+};
+use gateway_core::{
+    error::{GatewayError, GatewayErrorKind},
+    policy::ClientApiKeyId,
+};
+use headers::{ETag, HeaderMapExt as _, IfNoneMatch};
+use serde::Deserialize;
+use sha2::{Digest as _, Sha256};
+
+use crate::{
+    admin::{
+        AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse,
+        wire::map_admin_service_error,
+    },
+    auth::SessionState,
+    openai::{
+        error::{gateway_error_response, protocol_error_response},
+        responses::{
+            ResponseAuthorization, ResponsesHttpRequest, decode_request_with_body,
+            execute_prepared_responses,
+        },
+    },
+};
+
+const MAXIMUM_BODY_BYTES: usize = 1024 * 1024;
+const MAXIMUM_MODEL_BODY_BYTES: usize = 8 * 1024 * 1024;
+// HTML/SVG 即使被直接导航打开也不能获得管理端 origin；执行入口由隔离 iframe 的消息桥承载。
+const RESOURCE_CSP: &str = "sandbox allow-scripts; default-src 'none'; script-src 'unsafe-inline' blob:; style-src 'unsafe-inline' blob:; img-src data: blob:; font-src data: blob:; connect-src 'none'; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'self'";
+
+pub(super) fn router<S: SessionState + Clone + Send + Sync + 'static>() -> Router<S> {
+    Router::new()
+        .route("/api/admin/plugins/extensions", get(views::<S>))
+        .route("/api/admin/plugins/extensions/{instance_id}/{artifact_sha256}/{revision}/callback-tickets", post(start_callback::<S>))
+        .route("/api/admin/plugins/extensions/{instance_id}/{artifact_sha256}/{revision}/api/{*path}", any(handle::<S>))
+        .route("/api/admin/plugins/extensions/{instance_id}/{artifact_sha256}/{revision}/resources/{*path}", get(resource::<S>))
+        .route("/plugins/resources/{instance_id}/{artifact_sha256}/{revision}/{*path}", get(public_resource::<S>))
+        .route("/plugins/callbacks/{instance_id}/{artifact_sha256}/{revision}/{*path}", get(callback::<S>))
+}
+
+pub(in crate::admin) fn model_router() -> Router<crate::ApiState> {
+    Router::new().route(
+        "/api/admin/plugins/extensions/{instance_id}/{artifact_sha256}/{revision}/models/responses",
+        post(model_responses).layer(DefaultBodyLimit::max(MAXIMUM_MODEL_BODY_BYTES)),
+    )
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct ModelResponsesQuery {
+    client_key_id: String,
+}
+
+#[derive(Deserialize)]
+struct TargetPath {
+    instance_id: String,
+    artifact_sha256: String,
+    revision: u64,
+}
+
+impl TargetPath {
+    fn target(&self) -> PluginManagementTarget {
+        PluginManagementTarget {
+            instance_id: self.instance_id.clone(),
+            artifact_sha256: self.artifact_sha256.clone(),
+            revision: self.revision,
+        }
+    }
+}
+
+async fn model_responses(
+    _: AdminAuth,
+    State(state): State<crate::ApiState>,
+    Path(path): Path<TargetPath>,
+    AdminQuery(query): AdminQuery<ModelResponsesQuery>,
+    parts: axum::http::request::Parts,
+    body: Result<Bytes, BytesRejection>,
+) -> Result<Response, AdminError> {
+    let body = body.map_err(|error| {
+        AdminError::invalid_request(error.status(), "插件模型请求正文过大或无法读取")
+    })?;
+    let target = path.target();
+    state
+        .admin_services()
+        .plugin_management()
+        .authorize_models(&target)
+        .await
+        .map_err(map_admin_service_error)?;
+    let client_key_id = ClientApiKeyId::new(query.client_key_id)
+        .map_err(|_| AdminError::bad_request("Client Key 标识不合法"))?;
+    let headers = model_request_headers(&parts.headers);
+    let (decoded, middleware_body) =
+        match decode_request_with_body(&body, &headers, MAXIMUM_MODEL_BODY_BYTES) {
+            Ok(decoded) => decoded,
+            Err(error) => {
+                return Ok(harden_model_response(protocol_error_response(
+                    StatusCode::BAD_REQUEST,
+                    error.protocol_body(),
+                )));
+            }
+        };
+    let service = state.openai().clone();
+    let execution = service.execution();
+    let prepared = match execution.prepare_plugin_execution(&client_key_id).await {
+        Ok(prepared) => prepared,
+        Err(error) => return Ok(harden_model_response(gateway_error_response(&error))),
+    };
+    let authorization: Arc<dyn ResponseAuthorization> =
+        Arc::new(PluginModelsAuthorization { state, target });
+    let response = execute_prepared_responses(
+        service,
+        prepared,
+        ResponsesHttpRequest {
+            peer_address: parts
+                .extensions
+                .get::<ConnectInfo<SocketAddr>>()
+                .map(|info| info.0),
+            ingress_id: parts
+                .extensions
+                .get::<tower_http::request_id::RequestId>()
+                .cloned()
+                .map(Extension),
+            headers,
+            decoded,
+            middleware_body,
+            maximum_body_bytes: MAXIMUM_MODEL_BODY_BYTES,
+        },
+        Some(authorization),
+    )
+    .await;
+    Ok(harden_model_response(response))
+}
+
+struct PluginModelsAuthorization {
+    state: crate::ApiState,
+    target: PluginManagementTarget,
+}
+
+impl ResponseAuthorization for PluginModelsAuthorization {
+    fn authorize(&self) -> BoxFuture<'_, Result<(), GatewayError>> {
+        Box::pin(async move {
+            self.state
+                .admin_services()
+                .plugin_management()
+                .authorize_models(&self.target)
+                .await
+                .map_err(plugin_model_authorization_error)
+        })
+    }
+}
+
+fn plugin_model_authorization_error(error: gateway_admin::model::AdminError) -> GatewayError {
+    let (kind, message) = match error.kind() {
+        gateway_admin::model::AdminErrorKind::Unavailable
+        | gateway_admin::model::AdminErrorKind::Internal => (
+            GatewayErrorKind::ProviderInfrastructureUnavailable,
+            "plugin model authorization is unavailable",
+        ),
+        _ => (
+            GatewayErrorKind::PolicyDenied,
+            "plugin model authorization was revoked",
+        ),
+    };
+    GatewayError::new(kind, message)
+}
+
+fn model_request_headers(headers: &HeaderMap) -> HeaderMap {
+    let mut sanitized = HeaderMap::new();
+    for name in [
+        header::ACCEPT,
+        header::CONTENT_ENCODING,
+        header::CONTENT_TYPE,
+        header::USER_AGENT,
+        HeaderName::from_static("cf-connecting-ip"),
+        HeaderName::from_static("x-forwarded-for"),
+        HeaderName::from_static("x-real-ip"),
+    ] {
+        for value in headers.get_all(&name) {
+            sanitized.append(name.clone(), value.clone());
+        }
+    }
+    sanitized
+}
+
+fn harden_model_response(mut response: Response) -> Response {
+    for name in [
+        header::SET_COOKIE,
+        HeaderName::from_static("set-cookie2"),
+        header::WWW_AUTHENTICATE,
+        header::PROXY_AUTHENTICATE,
+        header::AUTHORIZATION,
+        header::PROXY_AUTHORIZATION,
+    ] {
+        response.headers_mut().remove(name);
+    }
+    let headers = response.headers_mut();
+    headers.insert(
+        header::CONTENT_SECURITY_POLICY,
+        HeaderValue::from_static("default-src 'none'; frame-ancestors 'none'; sandbox"),
+    );
+    headers.insert(
+        header::X_CONTENT_TYPE_OPTIONS,
+        HeaderValue::from_static("nosniff"),
+    );
+    headers.insert(
+        header::REFERRER_POLICY,
+        HeaderValue::from_static("no-referrer"),
+    );
+    response
+}
+
+async fn start_callback<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    Path((instance_id, artifact_sha256, revision)): Path<(String, String, u64)>,
+    AdminJson(command): AdminJson<StartPluginManagementCallback>,
+) -> Result<impl IntoResponse, AdminError> {
+    let target = PluginManagementTarget {
+        instance_id,
+        artifact_sha256,
+        revision,
+    };
+    let ticket = state
+        .admin_services()
+        .plugin_management()
+        .start_callback(&target, command, auth.context())
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(ticket),
+    ))
+}
+
+async fn callback<S: SessionState + Send + Sync>(
+    State(state): State<S>,
+    Path(path): Path<ResourcePath>,
+    request: Request,
+) -> Result<Response, AdminError> {
+    // Axum 为 GET 路由自动提供 HEAD；预取或探测不能消耗一次性登录票据。
+    if request.method() != axum::http::Method::GET {
+        return Err(AdminError::invalid_request(
+            StatusCode::METHOD_NOT_ALLOWED,
+            "插件登录回调仅允许 GET",
+        ));
+    }
+    let query = request.uri().query().unwrap_or_default().to_owned();
+    if query.len() > 8192 {
+        return Err(AdminError::bad_request("插件登录回调查询过大"));
+    }
+    let mut values =
+        url::form_urlencoded::parse(query.as_bytes()).filter(|(name, _)| name == "state");
+    let nonce = values
+        .next()
+        .map(|(_, value)| value.into_owned())
+        .filter(|value| !value.is_empty())
+        .ok_or_else(|| AdminError::bad_request("插件登录回调缺少 state"))?;
+    if values.next().is_some() || to_bytes(request.into_body(), 0).await.is_err() {
+        return Err(AdminError::bad_request("插件登录回调 state 重复或包含正文"));
+    }
+    let result = state
+        .admin_services()
+        .plugin_management()
+        .callback(
+            &path.target(),
+            &nonce,
+            PluginManagementRequest {
+                method: "GET".into(),
+                path: path.path,
+                query,
+                content_type: None,
+                body: Vec::new(),
+                request_id: uuid::Uuid::now_v7().to_string(),
+            },
+        )
+        .await
+        .map_err(map_admin_service_error)?;
+    raw_response(result)
+}
+
+#[derive(Deserialize)]
+struct ResourcePath {
+    instance_id: String,
+    artifact_sha256: String,
+    revision: u64,
+    path: String,
+}
+
+impl ResourcePath {
+    fn target(&self) -> PluginManagementTarget {
+        PluginManagementTarget {
+            instance_id: self.instance_id.clone(),
+            artifact_sha256: self.artifact_sha256.clone(),
+            revision: self.revision,
+        }
+    }
+}
+
+async fn views<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError> {
+    let views = state
+        .admin_services()
+        .plugin_management()
+        .views()
+        .await
+        .map_err(map_admin_service_error)?;
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(views)))
+}
+
+async fn handle<S: SessionState + Send + Sync>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    Path(path): Path<ResourcePath>,
+    request: Request,
+) -> Result<Response, AdminError> {
+    let content_type = request
+        .headers()
+        .get(header::CONTENT_TYPE)
+        .map(|value| value.to_str().map(str::to_owned))
+        .transpose()
+        .map_err(|_| AdminError::bad_request("Content-Type 无效"))?;
+    let target = path.target();
+    let method = request.method().as_str().to_owned();
+    let query = request.uri().query().unwrap_or_default().to_owned();
+    let body = to_bytes(request.into_body(), MAXIMUM_BODY_BYTES)
+        .await
+        .map_err(|_| {
+            AdminError::invalid_request(StatusCode::PAYLOAD_TOO_LARGE, "插件管理正文过大或无法读取")
+        })?;
+    let result = state
+        .admin_services()
+        .plugin_management()
+        .handle(
+            &target,
+            PluginManagementRequest {
+                method,
+                path: path.path,
+                query,
+                content_type,
+                body: body.to_vec(),
+                request_id: auth.context().request_id.clone(),
+            },
+        )
+        .await
+        .map_err(map_admin_service_error)?;
+    raw_response(result)
+}
+
+async fn resource<S: SessionState + Send + Sync>(
+    _: AdminAuth,
+    State(state): State<S>,
+    Path(path): Path<ResourcePath>,
+    headers: HeaderMap,
+) -> Result<Response, AdminError> {
+    load_resource(&state, path, false, &headers).await
+}
+
+async fn public_resource<S: SessionState + Send + Sync>(
+    State(state): State<S>,
+    Path(path): Path<ResourcePath>,
+    headers: HeaderMap,
+) -> Result<Response, AdminError> {
+    // 只分派已授予 public_resource 的不可变静态字节，不启动 handler 或继承 Cookie 权限。
+    load_resource(&state, path, true, &headers).await
+}
+
+async fn load_resource<S: SessionState + Send + Sync>(
+    state: &S,
+    path: ResourcePath,
+    public: bool,
+    headers: &HeaderMap,
+) -> Result<Response, AdminError> {
+    let result = state
+        .admin_services()
+        .plugin_management()
+        .resource(&path.target(), &path.path, public)
+        .await
+        .map_err(map_admin_service_error)?;
+    // 先复核会话、实例版本和资源授权；条件请求不能绕过撤销检查。
+    if result.status != 200 || result.body.len() > MAXIMUM_BODY_BYTES {
+        return raw_response(result);
+    }
+    let mut digest = Sha256::new();
+    digest.update(result.content_type.as_bytes());
+    digest.update([0]);
+    digest.update(&result.body);
+    let etag: ETag = format!(
+        "\"{}\"",
+        base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(digest.finalize())
+    )
+    .parse()
+    .map_err(|_| AdminError::bad_gateway())?;
+    let not_modified = headers
+        .typed_get::<IfNoneMatch>()
+        .is_some_and(|condition| !condition.precondition_passes(&etag));
+    let mut response = raw_response(result)?;
+    response.headers_mut().insert(
+        header::CACHE_CONTROL,
+        HeaderValue::from_static("private, no-cache"),
+    );
+    response.headers_mut().typed_insert(etag);
+    if not_modified {
+        *response.status_mut() = StatusCode::NOT_MODIFIED;
+        *response.body_mut() = Body::empty();
+    }
+    Ok(response)
+}
+
+fn raw_response(result: PluginManagementResponse) -> Result<Response, AdminError> {
+    if result.body.len() > MAXIMUM_BODY_BYTES || !(200..=599).contains(&result.status) {
+        return Err(AdminError::bad_gateway());
+    }
+    let content_type =
+        HeaderValue::from_str(&result.content_type).map_err(|_| AdminError::bad_gateway())?;
+    let mut response = Response::new(Body::from(Bytes::from_owner(result.body)));
+    *response.status_mut() =
+        StatusCode::from_u16(result.status).map_err(|_| AdminError::bad_gateway())?;
+    let headers = response.headers_mut();
+    headers.insert(header::CONTENT_TYPE, content_type);
+    headers.insert(
+        header::CONTENT_SECURITY_POLICY,
+        HeaderValue::from_static(RESOURCE_CSP),
+    );
+    headers.insert(
+        header::X_CONTENT_TYPE_OPTIONS,
+        HeaderValue::from_static("nosniff"),
+    );
+    headers.insert(
+        header::REFERRER_POLICY,
+        HeaderValue::from_static("no-referrer"),
+    );
+    headers.insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
+    headers.insert(
+        "permissions-policy",
+        HeaderValue::from_static("camera=(), microphone=(), geolocation=(), payment=()"),
+    );
+    Ok(response)
+}
diff --git a/backend/crates/gateway-api/src/admin/plugins/mod.rs b/backend/crates/gateway-api/src/admin/plugins/mod.rs
new file mode 100644
index 000000000..9abf98de1
--- /dev/null
+++ b/backend/crates/gateway-api/src/admin/plugins/mod.rs
@@ -0,0 +1,20 @@
+mod artifacts;
+mod distribution;
+mod instances;
+mod management;
+
+pub(super) use management::model_router;
+
+#[derive(serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+struct IdRequest {
+    id: String,
+}
+
+pub(super) fn router<S: crate::auth::SessionState + Clone + Send + Sync + 'static>()
+-> axum::Router<S> {
+    artifacts::router()
+        .merge(distribution::router())
+        .merge(instances::router())
+        .merge(management::router())
+}
diff --git a/backend/crates/gateway-api/src/admin/settings.rs b/backend/crates/gateway-api/src/admin/settings.rs
index abd8c734d..ebd32e487 100644
--- a/backend/crates/gateway-api/src/admin/settings.rs
+++ b/backend/crates/gateway-api/src/admin/settings.rs
@@ -29,12 +29,18 @@ use super::{
 
 /// 客户端模型到上游模型的全局精确映射。
 pub type ModelMappings = BTreeMap<String, String>;
+pub type ProviderRequestProfiles = BTreeMap<String, serde_json::Map<String, serde_json::Value>>;
+pub type ProviderRequestProfileUpdates =
+    BTreeMap<String, Option<serde_json::Map<String, serde_json::Value>>>;
 
 /// 运行配置投影与设置页字段的聚合响应。
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct RuntimeSettingsView {
+    pub provider_request_profiles: ProviderRequestProfiles,
+    /// 固定兼容字段；值始终从 provider_request_profiles 派生。
     pub openai_client_profile: Option<serde_json::Map<String, serde_json::Value>>,
+    /// 固定兼容字段；值始终从 provider_request_profiles 派生。
     pub xai_client_profile: Option<serde_json::Map<String, serde_json::Value>>,
     pub request_location_enabled: bool,
     pub request_location: gateway_core::account::RequestLocation,
@@ -67,8 +73,12 @@ pub struct RuntimeSettingsView {
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct UpdateRuntimeSettingsRequest {
+    #[serde(default)]
+    pub provider_request_profiles: ProviderRequestProfileUpdates,
+    /// 兼容既有 wire；与泛化字段冲突时拒绝整个请求。
     #[serde(default, deserialize_with = "deserialize_profile_update")]
     pub openai_client_profile: Option<serde_json::Map<String, serde_json::Value>>,
+    /// 兼容既有 wire；与泛化字段冲突时拒绝整个请求。
     #[serde(default, deserialize_with = "deserialize_profile_update")]
     pub xai_client_profile: Option<serde_json::Map<String, serde_json::Value>>,
     pub request_location_enabled: bool,
@@ -179,13 +189,13 @@ impl UpdateRuntimeSettingsRequest {
 
     fn into_command(self) -> Result<ReplaceRuntimeSettings, WireValidationError> {
         self.validate()?;
+        let request_profile_updates = normalize_request_profile_updates(
+            self.provider_request_profiles,
+            self.openai_client_profile,
+            self.xai_client_profile,
+        )?;
         Ok(ReplaceRuntimeSettings {
-            openai_client_profile: self
-                .openai_client_profile
-                .map(gateway_core::account::OpaqueProviderData::new),
-            xai_client_profile: self
-                .xai_client_profile
-                .map(gateway_core::account::OpaqueProviderData::new),
+            request_profile_updates,
             request_location_enabled: self.request_location_enabled,
             request_location: self
                 .request_location
@@ -226,13 +236,15 @@ impl UpdateRuntimeSettingsRequest {
 
 impl From<RuntimeSettings> for RuntimeSettingsView {
     fn from(settings: RuntimeSettings) -> Self {
+        let provider_request_profiles = settings
+            .request_profiles
+            .into_iter()
+            .map(|(provider, profile)| (provider.as_str().to_owned(), profile.into_inner()))
+            .collect::<ProviderRequestProfiles>();
         Self {
-            openai_client_profile: settings
-                .openai_client_profile
-                .map(gateway_core::account::OpaqueProviderData::into_inner),
-            xai_client_profile: settings
-                .xai_client_profile
-                .map(gateway_core::account::OpaqueProviderData::into_inner),
+            openai_client_profile: provider_request_profiles.get("openai").cloned(),
+            xai_client_profile: provider_request_profiles.get("xai").cloned(),
+            provider_request_profiles,
             request_location_enabled: settings.request_location_enabled,
             request_location: settings.request_location,
             model_mappings: wire_model_mappings(settings.model_mappings),
@@ -291,6 +303,12 @@ pub struct DeletedAdminApiKey {
     pub message: &'static str,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ClientProfileProvidersView {
+    providers: Vec<String>,
+}
+
 #[derive(Debug, Clone, Copy, Default, Deserialize)]
 #[serde(default, deny_unknown_fields)]
 struct ClientDownloadsQuery {
@@ -368,6 +386,10 @@ where
         )
         .route("/api/admin/settings/pricing/sync", post(sync_pricing::<S>))
         .route("/api/admin/settings", get(settings::<S>))
+        .route(
+            "/api/admin/settings/client-profiles",
+            get(client_profile_providers::<S>),
+        )
         .route(
             "/api/admin/settings/client-profiles/{provider}",
             get(client_profile_options::<S>),
@@ -719,6 +741,7 @@ fn map_wire_error(error: WireValidationError) -> AdminError {
         "accountAutoFreezeWindowSeconds" => "账号自动冻结统计窗口应为 60～3600 秒".to_owned(),
         "accountAutoFreezeDurationSeconds" => "账号自动冻结时长应为 300～604800 秒".to_owned(),
         "accountAutoFreezeProbeModel" => "探测模型格式不合法".to_owned(),
+        "providerRequestProfiles" => "Provider 请求画像格式不合法或字段冲突".to_owned(),
         "minCodexDesktopVersion" => "Codex Desktop 最低版本格式不合法".to_owned(),
         "minCodexCliVersion" => "Codex CLI 最低版本格式不合法".to_owned(),
         field => format!("{field} 字段不合法"),
@@ -730,6 +753,43 @@ fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
     map_admin_service_error(error)
 }
 
+fn normalize_request_profile_updates(
+    profiles: ProviderRequestProfileUpdates,
+    openai: Option<serde_json::Map<String, serde_json::Value>>,
+    xai: Option<serde_json::Map<String, serde_json::Value>>,
+) -> Result<gateway_admin::model::settings::ProviderRequestProfileUpdates, WireValidationError> {
+    if profiles.len() > 256 {
+        return Err(WireValidationError::new("providerRequestProfiles"));
+    }
+    let mut normalized = profiles
+        .into_iter()
+        .map(|(provider, profile)| {
+            let provider = gateway_core::routing::ProviderKind::new(provider)
+                .map_err(|_| WireValidationError::new("providerRequestProfiles"))?;
+            Ok((
+                provider,
+                profile.map(gateway_core::account::OpaqueProviderData::new),
+            ))
+        })
+        .collect::<Result<gateway_admin::model::settings::ProviderRequestProfileUpdates, _>>()?;
+    for (provider, profile) in [("openai", openai), ("xai", xai)] {
+        let Some(profile) = profile else {
+            continue;
+        };
+        let provider = gateway_core::routing::ProviderKind::new(provider)
+            .expect("static Provider kind is valid");
+        let profile = gateway_core::account::OpaqueProviderData::new(profile);
+        if normalized
+            .get(&provider)
+            .is_some_and(|current| current.as_ref() != Some(&profile))
+        {
+            return Err(WireValidationError::new("providerRequestProfiles"));
+        }
+        normalized.insert(provider, Some(profile));
+    }
+    Ok(normalized)
+}
+
 // 字段省略时保留已有配置；显式 null 不能清空唯一的通用默认。
 fn deserialize_profile_update<'de, D: serde::Deserializer<'de>>(
     deserializer: D,
@@ -737,6 +797,28 @@ fn deserialize_profile_update<'de, D: serde::Deserializer<'de>>(
     serde_json::Map::<String, serde_json::Value>::deserialize(deserializer).map(Some)
 }
 
+async fn client_profile_providers<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: SessionState + Send + Sync,
+{
+    let providers = state
+        .admin_services()
+        .settings()
+        .client_profile_providers()
+        .await
+        .map_err(map_service_error)?
+        .into_iter()
+        .map(|provider| provider.as_str().to_owned())
+        .collect();
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(ClientProfileProvidersView { providers }),
+    ))
+}
+
 async fn client_profile_options<S>(
     _auth: AdminAuth,
     Path(provider): Path<String>,
diff --git a/backend/crates/gateway-api/src/admin/wire.rs b/backend/crates/gateway-api/src/admin/wire.rs
index 25d7ac6ba..b72e2f27d 100644
--- a/backend/crates/gateway-api/src/admin/wire.rs
+++ b/backend/crates/gateway-api/src/admin/wire.rs
@@ -110,6 +110,8 @@ impl AdminErrorCode {
     pub const CONFLICT: Self = Self(40901);
     /// 登录尝试过多。
     pub const TOO_MANY_LOGIN_ATTEMPTS: Self = Self(42901);
+    /// 管理操作请求过于频繁。
+    pub const RATE_LIMITED: Self = Self(42902);
     /// 设置持久化失败。
     pub const SETTINGS_PERSIST: Self = Self(50000);
     /// 未分类内部错误。
@@ -232,6 +234,11 @@ const TOO_MANY_LOGIN_ATTEMPTS: AdminErrorSpec = AdminErrorSpec::new(
     AdminErrorCode::TOO_MANY_LOGIN_ATTEMPTS,
     "登录尝试过多，请稍后重试",
 );
+const RATE_LIMITED: AdminErrorSpec = AdminErrorSpec::new(
+    StatusCode::TOO_MANY_REQUESTS,
+    AdminErrorCode::RATE_LIMITED,
+    "请求过于频繁，请稍后重试",
+);
 const INTERNAL: AdminErrorSpec = AdminErrorSpec::new(
     StatusCode::INTERNAL_SERVER_ERROR,
     AdminErrorCode::INTERNAL,
@@ -306,6 +313,10 @@ impl AdminError {
         Self::from_spec(TOO_MANY_LOGIN_ATTEMPTS)
     }
 
+    pub fn rate_limited() -> Self {
+        Self::from_spec(RATE_LIMITED)
+    }
+
     pub fn forbidden() -> Self {
         Self::new(StatusCode::FORBIDDEN, AdminErrorCode::FORBIDDEN, "无权访问")
     }
@@ -351,7 +362,7 @@ pub(crate) fn map_admin_service_error(error: gateway_admin::model::AdminError) -
         AdminErrorKind::Unauthorized => AdminError::session_required(),
         AdminErrorKind::NotFound => AdminError::not_found(error.message()),
         AdminErrorKind::Conflict => AdminError::conflict(error.message()),
-        AdminErrorKind::RateLimited => AdminError::too_many_login_attempts(),
+        AdminErrorKind::RateLimited => AdminError::rate_limited(),
         AdminErrorKind::BadGateway => AdminError::bad_gateway(),
         AdminErrorKind::UpstreamResultUnknown => AdminError::upstream_result_unknown(),
         AdminErrorKind::Unavailable => AdminError::service_unavailable(),
@@ -361,7 +372,8 @@ pub(crate) fn map_admin_service_error(error: gateway_admin::model::AdminError) -
     // 认证与未知内部异常仍使用固定提示，不放行底层诊断或任意 500 消息。
     if matches!(
         error.kind(),
-        AdminErrorKind::BadGateway
+        AdminErrorKind::RateLimited
+            | AdminErrorKind::BadGateway
             | AdminErrorKind::UpstreamResultUnknown
             | AdminErrorKind::Unavailable
     ) && !error.message().trim().is_empty()
diff --git a/backend/crates/gateway-api/src/lib.rs b/backend/crates/gateway-api/src/lib.rs
index dc9d9c66d..587ea52dd 100644
--- a/backend/crates/gateway-api/src/lib.rs
+++ b/backend/crates/gateway-api/src/lib.rs
@@ -33,6 +33,7 @@ pub mod auth;
 mod health;
 mod key_usage;
 pub mod openai;
+mod provider;
 mod session_cookie;
 
 /// API-owned HTTP 与静态资源配置。
@@ -141,10 +142,18 @@ pub fn initialize(
     let mut router = Router::new()
         .route("/healthz", get(health::healthz))
         .merge(openai::router::router())
+        .merge(provider::router())
         .merge(admin::router::<ApiState>())
+        .merge(admin::model_router())
         .merge(auth::router::<ApiState>())
         .merge(key_usage::router::<ApiState>())
-        .fallback_service(ServeDir::new(config.asset_directory).fallback(ServeFile::new(index)));
+        .fallback_service(
+            Router::new()
+                .fallback_service(
+                    ServeDir::new(config.asset_directory).fallback(ServeFile::new(index)),
+                )
+                .layer(axum::middleware::map_response(static_cache_control)),
+        );
     if !config.cors_allowed_origins.is_empty() {
         let origins = config
             .cors_allowed_origins
@@ -207,6 +216,14 @@ pub fn initialize(
     Ok(ApiBundle { router })
 }
 
+async fn static_cache_control(mut response: axum::response::Response) -> axum::response::Response {
+    response.headers_mut().insert(
+        axum::http::header::CACHE_CONTROL,
+        HeaderValue::from_static("no-cache"),
+    );
+    response
+}
+
 /// API 初始化失败的脱敏分类。
 #[derive(Debug, thiserror::Error)]
 pub enum ApiError {
diff --git a/backend/crates/gateway-api/src/openai/auth.rs b/backend/crates/gateway-api/src/openai/auth.rs
index 7bbe2bc6e..b3d465c15 100644
--- a/backend/crates/gateway-api/src/openai/auth.rs
+++ b/backend/crates/gateway-api/src/openai/auth.rs
@@ -4,7 +4,9 @@ use axum::{
     http::{HeaderMap, header::AUTHORIZATION},
     response::{IntoResponse, Response},
 };
-use gateway_core::engine::execution::AuthenticatedClient;
+use gateway_core::engine::{
+    authentication::ClientAuthenticationRequest, execution::AuthenticatedClient,
+};
 use gateway_core::policy::{ClientVersionRejection, CodexClientKind, CodexClientVersion};
 
 use super::{
@@ -106,12 +108,12 @@ pub fn bearer_client_api_key(headers: &HeaderMap) -> Result<&str, ClientApiKeyAu
     Ok(token)
 }
 
-pub(crate) fn authenticate_client(
+pub(crate) async fn authenticate_client(
     service: &OpenAiService,
     headers: &HeaderMap,
 ) -> Result<AuthenticatedClient, ClientAccessError> {
-    let key = bearer_client_api_key(headers)?;
-    let client = service.authenticate(key)?;
+    let request = client_authentication_request(headers)?;
+    let client = service.authenticate(request).await?;
     if let Some(identified) = identify_codex_client(headers) {
         client
             .snapshot()
@@ -121,6 +123,27 @@ pub(crate) fn authenticate_client(
     Ok(client)
 }
 
+/// 复用数据面入口认证计划，但不记录 Key 使用事实或执行推理准入。
+pub(crate) async fn verify_client(
+    service: &OpenAiService,
+    headers: &HeaderMap,
+) -> Result<AuthenticatedClient, ClientApiKeyAuthError> {
+    let request = client_authentication_request(headers)?;
+    service.verify(request).await
+}
+
+fn client_authentication_request(
+    headers: &HeaderMap,
+) -> Result<ClientAuthenticationRequest, ClientApiKeyAuthError> {
+    let raw = headers
+        .get(AUTHORIZATION)
+        .ok_or(ClientApiKeyAuthError::MissingAuthorization)?
+        .to_str()
+        .map_err(|_| ClientApiKeyAuthError::MalformedAuthorization)?;
+    ClientAuthenticationRequest::new(raw.to_owned())
+        .map_err(|_| ClientApiKeyAuthError::MalformedAuthorization)
+}
+
 pub(crate) fn client_access_error_response(error: ClientAccessError) -> Response {
     match error {
         ClientAccessError::Authentication(error) => {
diff --git a/backend/crates/gateway-api/src/openai/endpoint.rs b/backend/crates/gateway-api/src/openai/endpoint.rs
index 81390c5fb..4bf232c73 100644
--- a/backend/crates/gateway-api/src/openai/endpoint.rs
+++ b/backend/crates/gateway-api/src/openai/endpoint.rs
@@ -1,66 +1,134 @@
 //! OpenAI Provider 原生非流式 JSON 端点的公共交付边界。
 
+use std::net::IpAddr;
+
 use axum::{
     body::{Body, Bytes},
-    http::{HeaderName, HeaderValue, StatusCode, header::CONTENT_TYPE},
+    http::{HeaderMap, HeaderName, HeaderValue, StatusCode, header::CONTENT_TYPE},
     response::{IntoResponse, Response},
 };
-use gateway_core::engine::execution::{ExecutionSession, StartedExecution};
+use gateway_core::{
+    engine::{
+        execution::{AuthenticatedClient, StartedExecution},
+        middleware::{MiddlewareError, MiddlewareFrame, MiddlewareFraming, MiddlewareResponse},
+    },
+    error::GatewayError,
+    operation::Operation,
+};
+
+use crate::openai::middleware::{
+    ExpectedBody, HttpMiddlewareInput, PendingExecution, buffered_response, error_response,
+    into_http_response, invoke_http_middleware, pending_execution_response, request_headers,
+    request_parts,
+};
 use gateway_core::event::{ProviderEvent, ProviderResponseHeader};
 
 use super::{
-    error::{engine_error_response, protocol_error_response},
-    responses::{PendingExecution, ProtocolError, ProtocolErrorBody},
+    error::{engine_error_response, gateway_error_response, protocol_error_response},
+    responses::{ProtocolError, ProtocolErrorBody},
+    service::OpenAiService,
 };
 
-/// 收集一个 Provider 原生 JSON 响应，并在 Core commit 后按原始 bytes 交付。
-pub(super) async fn collect_raw_json_response(started: StartedExecution) -> Response {
-    let response = collect_raw_json_session(started.session).await;
-    super::with_model_request_id(response, &started.request_id)
+/// Provider 自有端点也先冻结身份，再通过统一请求链进入原有执行与结算路径。
+pub(super) async fn provider_endpoint_response<F>(
+    service: OpenAiService,
+    client: AuthenticatedClient,
+    input: HttpMiddlewareInput,
+    client_ip: Option<IpAddr>,
+    user_agent: Option<String>,
+    decode: F,
+) -> Response
+where
+    F: FnOnce(Bytes, &HeaderMap) -> Result<Operation, GatewayError> + Send + 'static,
+{
+    let execution = service.execution();
+    let prepared = match execution.prepare_execution(client).await {
+        Ok(prepared) => prepared,
+        Err(error) => return gateway_error_response(&error),
+    };
+    let request_id = prepared.request_id().clone();
+    let endpoint = input.endpoint.clone();
+    let result = invoke_http_middleware(
+        execution,
+        prepared,
+        input,
+        Box::new(move |prepared, request| {
+            Box::pin(async move {
+                let (protocol, headers, body) = request_parts(request)?;
+                if protocol != "openai" {
+                    return Err(MiddlewareError::Rejected);
+                }
+                let operation = decode(body, &headers)?;
+                let started = match service
+                    .start_prepared_provider_endpoint(
+                        prepared, operation, client_ip, user_agent, endpoint,
+                    )
+                    .await
+                {
+                    Ok(started) => started,
+                    Err(error) => {
+                        return buffered_response("openai", gateway_error_response(&error)).await;
+                    }
+                };
+                collect_raw_json_response(started).await
+            })
+        }),
+    )
+    .await;
+    let response = match result {
+        Ok(response) => into_http_response(response, ExpectedBody::SingleJson).await,
+        Err(error) => error_response(error),
+    };
+    if response.headers().contains_key("x-gateway-request-id") {
+        response
+    } else {
+        super::with_model_request_id(response, &request_id)
+    }
 }
 
-async fn collect_raw_json_session(session: Box<dyn ExecutionSession>) -> Response {
-    let mut execution = PendingExecution::new(session);
-    let Some(session) = execution.session_mut() else {
-        return invalid_upstream_response();
+/// 只收集正文，不提前 commit；外层完成响应变换与校验后才提交 Core。
+async fn collect_raw_json_response(
+    started: StartedExecution,
+) -> Result<MiddlewareResponse, MiddlewareError> {
+    let mut execution = PendingExecution::new(started.session);
+    let session = execution
+        .session_mut()
+        .ok_or(MiddlewareError::InvalidState)?;
+    let events = session.collect_uncommitted().await;
+    let transformed = events
+        .as_ref()
+        .is_ok_and(|events| events.iter().any(ProviderEvent::middleware_transformed));
+    let response = match events {
+        Ok(events) => match raw_json_body(events) {
+            Some(body) => {
+                let status = session
+                    .response_status_code()
+                    .and_then(|status| StatusCode::from_u16(status).ok())
+                    .filter(StatusCode::is_success)
+                    .unwrap_or(StatusCode::OK);
+                json_body_response(body, status, session.response_headers())
+            }
+            None => invalid_upstream_response(),
+        },
+        Err(error) => engine_error_response(&error),
     };
-    let events = match session.collect_uncommitted().await {
-        Ok(events) => events,
-        Err(error) => {
-            let response = engine_error_response(&error);
-            return execution.record_response_status(response).await;
-        }
+    let response = super::with_model_request_id(response, &started.request_id);
+    let (parts, body) = response.into_parts();
+    let framing = if parts.status.is_success() {
+        MiddlewareFraming::JsonDocument
+    } else {
+        MiddlewareFraming::RawBytes
     };
-    let body = match raw_json_body(events) {
-        Some(body) => body,
-        None => {
-            let response = invalid_upstream_response();
-            let response = execution.record_response_status(response).await;
-            execution.cancel_and_finalize().await;
-            return response;
-        }
-    };
-    let status = session
-        .response_status_code()
-        .and_then(|status| StatusCode::from_u16(status).ok())
-        .filter(StatusCode::is_success)
-        .unwrap_or(StatusCode::OK);
-    let response_headers = session.response_headers().to_vec();
-    let response = json_body_response(body, status, &response_headers);
-    let Some(session) = execution.session_mut() else {
-        return invalid_upstream_response();
-    };
-    if let Err(error) = session.commit_downstream(Some(status.as_u16())).await {
-        execution.cancel_and_finalize().await;
-        let response = engine_error_response(&error);
-        return execution.record_response_status(response).await;
-    }
-    if !session.is_finalized() {
-        execution.cancel_and_finalize().await;
-        return invalid_upstream_response();
-    }
-    execution.disarm();
-    response
+    let bytes = axum::body::to_bytes(body, usize::MAX)
+        .await
+        .map_err(|_| MiddlewareError::Fault)?;
+    Ok(pending_execution_response(
+        "openai".to_owned(),
+        parts.status.as_u16(),
+        request_headers(&parts.headers),
+        MiddlewareFrame::new(bytes, framing, true).with_transformed(transformed),
+        execution,
+    ))
 }
 
 fn raw_json_body(events: Vec<ProviderEvent>) -> Option<Bytes> {
diff --git a/backend/crates/gateway-api/src/openai/images/http.rs b/backend/crates/gateway-api/src/openai/images/http.rs
index 1e93ca349..919257034 100644
--- a/backend/crates/gateway-api/src/openai/images/http.rs
+++ b/backend/crates/gateway-api/src/openai/images/http.rs
@@ -8,16 +8,20 @@ use axum::{
     http::HeaderMap,
     response::Response,
 };
+use gateway_core::engine::execution::ClientTransport;
 use gateway_core::error::{GatewayError, GatewayErrorKind};
-use gateway_core::operation::{ImageRequest, ImageRequestKind, Operation, RawJsonPayload};
+use gateway_core::operation::{
+    ImageRequest, ImageRequestKind, Operation, OperationKind, RawJsonPayload,
+};
 use serde_json::Value;
 
 use crate::ApiState;
+use crate::openai::middleware::{HttpMiddlewareInput, request_headers};
 use crate::openai::{
     auth::{authenticate_client, client_access_error_response},
-    endpoint::collect_raw_json_response,
-    error::gateway_error_response,
+    endpoint::provider_endpoint_response,
     responses::{OpenAiRequestHeaders, request_client_context},
+    router::{IMAGE_EDITS_PATH, IMAGE_GENERATIONS_PATH},
 };
 
 const OPENAI_PROTOCOL: &str = "openai";
@@ -36,7 +40,7 @@ pub(crate) async fn image_generations(
         headers,
         body,
         ImageRequestKind::Generation,
-        "/v1/images/generations",
+        IMAGE_GENERATIONS_PATH,
     )
     .await
 }
@@ -54,7 +58,7 @@ pub(crate) async fn image_edits(
         headers,
         body,
         ImageRequestKind::Edit,
-        "/v1/images/edits",
+        IMAGE_EDITS_PATH,
     )
     .await
 }
@@ -68,7 +72,7 @@ async fn handle_image_request(
     endpoint: &'static str,
 ) -> Response {
     let service = state.openai();
-    let client = match authenticate_client(service, &headers) {
+    let client = match authenticate_client(service, &headers).await {
         Ok(client) => client,
         Err(error) => return client_access_error_response(error),
     };
@@ -76,18 +80,23 @@ async fn handle_image_request(
         &headers,
         connect_info.map(|Extension(ConnectInfo(address))| address),
     );
-    let operation = match image_operation(body, &headers, kind) {
-        Ok(operation) => operation,
-        Err(error) => return gateway_error_response(&error),
-    };
-    let started = match service
-        .start_provider_endpoint(client, operation, client_ip, user_agent, endpoint)
-        .await
-    {
-        Ok(started) => started,
-        Err(error) => return gateway_error_response(&error),
-    };
-    collect_raw_json_response(started).await
+    provider_endpoint_response(
+        service.clone(),
+        client,
+        HttpMiddlewareInput {
+            endpoint: endpoint.to_owned(),
+            protocol: OPENAI_PROTOCOL.to_owned(),
+            operation: Some(OperationKind::GenerateImage),
+            transport: ClientTransport::HttpJson,
+            model_hint: None,
+            headers: request_headers(&headers),
+            body,
+        },
+        client_ip,
+        user_agent,
+        move |body, headers| image_operation(body, headers, kind),
+    )
+    .await
 }
 
 fn image_operation(
diff --git a/backend/crates/gateway-api/src/openai/middleware/http.rs b/backend/crates/gateway-api/src/openai/middleware/http.rs
new file mode 100644
index 000000000..01d6ed057
--- /dev/null
+++ b/backend/crates/gateway-api/src/openai/middleware/http.rs
@@ -0,0 +1,280 @@
+//! 未提交响应的 HTTP 交付；只验证协议边界，不解释或重算 Core 的业务事实。
+
+use super::request::{decode_headers, request_headers};
+use crate::openai::error::{
+    gateway_error_from_engine, gateway_error_response, openai_error_response,
+};
+use axum::{
+    body::Body,
+    http::{HeaderMap, HeaderValue, StatusCode, header},
+    response::{IntoResponse as _, Response},
+};
+use bytes::Bytes;
+use futures::{StreamExt as _, future::BoxFuture};
+use gateway_core::{
+    engine::middleware::{
+        MiddlewareBody, MiddlewareError, MiddlewareFrame, MiddlewareFraming, MiddlewareHeader,
+        MiddlewareResponse,
+    },
+    error::GatewayError,
+};
+use gateway_protocol::openai::response_header_is_forwardable;
+
+/// 只读目录/用量与协议错误共用的单帧响应；没有 Provider attempt 或计量副作用。
+pub(crate) async fn buffered_response(
+    protocol: &str,
+    response: Response,
+) -> Result<MiddlewareResponse, MiddlewareError> {
+    let (parts, body) = response.into_parts();
+    let bytes = axum::body::to_bytes(body, usize::MAX)
+        .await
+        .map_err(|_| MiddlewareError::Fault)?;
+    let framing = if parts.status.is_success() {
+        MiddlewareFraming::JsonDocument
+    } else {
+        MiddlewareFraming::RawBytes
+    };
+    Ok(MiddlewareResponse::new(
+        protocol.to_owned(),
+        parts.status.as_u16(),
+        request_headers(&parts.headers),
+        Box::new(BufferedBody(Some(MiddlewareFrame::new(
+            bytes, framing, true,
+        )))),
+    ))
+}
+
+struct BufferedBody(Option<MiddlewareFrame>);
+
+impl MiddlewareBody for BufferedBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async { Ok(self.0.take()) })
+    }
+
+    fn close(self: Box<Self>) -> BoxFuture<'static, ()> {
+        Box::pin(async move { drop(self) })
+    }
+}
+
+#[derive(Clone, Copy)]
+pub(crate) enum ExpectedBody {
+    SingleJson,
+    SinglePayload,
+    Sse,
+}
+
+impl ExpectedBody {
+    fn validate(self, frame: &MiddlewareFrame) -> Result<(), MiddlewareError> {
+        let valid = match self {
+            Self::SingleJson => {
+                frame.framing() == MiddlewareFraming::JsonDocument
+                    && frame.terminal()
+                    && serde_json::from_slice::<serde::de::IgnoredAny>(frame.bytes()).is_ok()
+            }
+            // 上游错误正文可能不是 JSON；只限定单文档交付，不改写原始错误字节。
+            Self::SinglePayload => {
+                frame.terminal()
+                    && (frame.framing() == MiddlewareFraming::RawBytes
+                        || Self::SingleJson.validate(frame).is_ok())
+            }
+            // 原生超大 SSE 帧允许按原字节片段交付；插件写入边界由 Runtime 校验。
+            Self::Sse => frame.framing() == MiddlewareFraming::SseEvent,
+        };
+        if valid {
+            Ok(())
+        } else {
+            Err(MiddlewareError::InvalidState)
+        }
+    }
+}
+
+/// 全部返回包装完成、首帧可读取后才提交原有 Core delivery barrier。
+pub(crate) async fn into_http_response(
+    response: MiddlewareResponse,
+    expected: ExpectedBody,
+) -> Response {
+    let (protocol, status, headers, mut body, _) = response.into_parts();
+    if protocol != "openai" {
+        return fail_before_commit(body, MiddlewareError::InvalidState).await;
+    }
+    let head = response_head(status, headers);
+    let (status, mut headers) = match head {
+        Ok(head) => head,
+        Err(error) => return fail_before_commit(body, error).await,
+    };
+    let first = match body.next_frame().await {
+        Ok(first) => first,
+        Err(error) => return fail_before_commit(body, error).await,
+    };
+    let empty = matches!(status, StatusCode::NO_CONTENT | StatusCode::NOT_MODIFIED);
+    let expected = if status.is_success() {
+        expected
+    } else {
+        ExpectedBody::SinglePayload
+    };
+    let validation = match (&first, empty) {
+        (None, true) => Ok(()),
+        (Some(frame), false) => expected.validate(frame),
+        _ => Err(MiddlewareError::InvalidState),
+    };
+    if let Err(error) = validation {
+        return fail_before_commit(body, error).await;
+    }
+    if let Some(frame) = &first {
+        // 短路响应没有下游 adapter 生成的头，传输类型仍由宿主按帧合同补齐。
+        headers.entry(header::CONTENT_TYPE).or_insert_with(|| {
+            HeaderValue::from_static(match frame.framing() {
+                MiddlewareFraming::JsonDocument => "application/json",
+                MiddlewareFraming::SseEvent => "text/event-stream",
+                MiddlewareFraming::RawBytes => "application/octet-stream",
+            })
+        });
+    }
+    if matches!(expected, ExpectedBody::Sse) {
+        headers.insert(
+            header::CACHE_CONTROL,
+            HeaderValue::from_static("no-cache, no-transform"),
+        );
+        headers.insert("x-accel-buffering", HeaderValue::from_static("no"));
+    }
+    let exhausted = empty || !matches!(expected, ExpectedBody::Sse);
+    if !empty && exhausted {
+        match body.next_frame().await {
+            Ok(None) => {}
+            Ok(Some(_)) => return fail_before_commit(body, MiddlewareError::InvalidState).await,
+            Err(error) => return fail_before_commit(body, error).await,
+        }
+    }
+    if let Err(error) = body.commit_downstream(Some(status.as_u16())).await {
+        return fail_before_commit(body, error).await;
+    }
+    let delivery = HttpDelivery {
+        first,
+        body,
+        expected,
+        exhausted,
+        terminal_seen: empty,
+    };
+    let keep_alive = matches!(expected, ExpectedBody::Sse);
+    let stream = Box::pin(futures::stream::try_unfold(delivery, HttpDelivery::next));
+    // 固定同一条输出流；心跳不能取消并重建正在等待的 next_frame 或结算 future。
+    let stream = futures::stream::unfold(stream, move |mut stream| async move {
+        let chunk = tokio::select! {
+            biased;
+            chunk = stream.next() => chunk?,
+            () = tokio::time::sleep(std::time::Duration::from_secs(15)), if keep_alive => {
+                Ok(Bytes::from_static(b": keep-alive\n\n"))
+            }
+        };
+        Some((chunk, stream))
+    });
+    let mut response = Response::new(Body::from_stream(stream));
+    *response.status_mut() = status;
+    *response.headers_mut() = headers;
+    response
+}
+
+struct HttpDelivery {
+    first: Option<MiddlewareFrame>,
+    body: Box<dyn MiddlewareBody>,
+    expected: ExpectedBody,
+    exhausted: bool,
+    terminal_seen: bool,
+}
+
+impl HttpDelivery {
+    async fn next(mut self) -> Result<Option<(Bytes, Self)>, MiddlewareError> {
+        let frame = match self.first.take() {
+            Some(frame) => Some(frame),
+            None if self.exhausted => None,
+            None => match self.body.next_frame().await {
+                Ok(frame) => frame,
+                Err(error) => {
+                    self.body.close().await;
+                    return Err(error);
+                }
+            },
+        };
+        if let Some(frame) = frame {
+            if self.terminal_seen || self.expected.validate(&frame).is_err() {
+                self.body.close().await;
+                return Err(MiddlewareError::InvalidState);
+            }
+            self.terminal_seen = frame.terminal();
+            Ok(Some((frame.into_bytes(), self)))
+        } else {
+            self.body.close().await;
+            if self.terminal_seen {
+                Ok(None)
+            } else {
+                Err(MiddlewareError::InvalidState)
+            }
+        }
+    }
+}
+
+fn response_head(
+    status: u16,
+    headers: Vec<MiddlewareHeader>,
+) -> Result<(StatusCode, HeaderMap), MiddlewareError> {
+    let status = StatusCode::from_u16(status).map_err(|_| MiddlewareError::InvalidState)?;
+    if status.is_informational() {
+        return Err(MiddlewareError::InvalidState);
+    }
+    let mut result = decode_headers(headers)?;
+    let connection_options = result
+        .get_all(header::CONNECTION)
+        .iter()
+        .filter_map(|value| value.to_str().ok())
+        .flat_map(|value| value.split(','))
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+        .map(str::to_ascii_lowercase)
+        .collect::<Vec<_>>();
+    // Content-Type 由协议 adapter 生成；其余字段在最终交付边界统一剥离认证与传输信息。
+    let blocked = result
+        .keys()
+        .filter(|name| {
+            *name != header::CONTENT_TYPE
+                && !response_header_is_forwardable(name.as_str(), &connection_options)
+        })
+        .cloned()
+        .collect::<Vec<_>>();
+    for name in blocked {
+        result.remove(name);
+    }
+    Ok((status, result))
+}
+
+async fn fail_before_commit(mut body: Box<dyn MiddlewareBody>, error: MiddlewareError) -> Response {
+    let response = error_response(error);
+    let _ = body.record_client_status(response.status().as_u16()).await;
+    body.close().await;
+    response
+}
+
+pub(crate) fn error_response(error: MiddlewareError) -> Response {
+    match error {
+        MiddlewareError::Gateway(error) => gateway_error_response(&error),
+        MiddlewareError::Engine(error) => {
+            gateway_error_response(&gateway_error_from_engine(&error))
+        }
+        MiddlewareError::Provider(error) => {
+            gateway_error_response(&GatewayError::from_provider(&error))
+        }
+        MiddlewareError::Rejected => openai_error_response(
+            StatusCode::FORBIDDEN,
+            "Request rejected by middleware",
+            "invalid_request_error",
+            "middleware_rejected",
+        )
+        .into_response(),
+        MiddlewareError::Fault | MiddlewareError::InvalidState => openai_error_response(
+            StatusCode::BAD_GATEWAY,
+            "Request middleware failed",
+            "server_error",
+            "middleware_failed",
+        )
+        .into_response(),
+    }
+}
diff --git a/backend/crates/gateway-api/src/openai/middleware/mod.rs b/backend/crates/gateway-api/src/openai/middleware/mod.rs
new file mode 100644
index 000000000..bfc2efef2
--- /dev/null
+++ b/backend/crates/gateway-api/src/openai/middleware/mod.rs
@@ -0,0 +1,11 @@
+//! OpenAI 请求洋葱链与最终传输交付；不拥有 Provider 选择或计量事实。
+
+mod http;
+mod request;
+mod session;
+
+pub(crate) use http::{ExpectedBody, buffered_response, error_response, into_http_response};
+pub(crate) use request::{
+    HttpMiddlewareInput, invoke_http_middleware, query_response, request_headers, request_parts,
+};
+pub(crate) use session::{PendingExecution, finalize_session, pending_execution_response};
diff --git a/backend/crates/gateway-api/src/openai/middleware/request.rs b/backend/crates/gateway-api/src/openai/middleware/request.rs
new file mode 100644
index 000000000..3be33c99c
--- /dev/null
+++ b/backend/crates/gateway-api/src/openai/middleware/request.rs
@@ -0,0 +1,229 @@
+//! 请求身份冻结、单次 next 与调用代次保活；HTTP 编码在 http 子模块中完成。
+
+use crate::openai::error::gateway_error_response;
+use axum::{
+    http::{HeaderMap, HeaderName, HeaderValue},
+    response::Response,
+};
+use bytes::Bytes;
+use futures::future::BoxFuture;
+use gateway_core::{
+    engine::{
+        execution::{
+            AuthenticatedClient, ClientTransport, ExecutionService, PreparedRootExecution,
+        },
+        extensions::ExtensionCallScope,
+        middleware::{
+            FrozenMiddlewarePlan, MiddlewareBody, MiddlewareError, MiddlewareFrame,
+            MiddlewareHeader, MiddlewareMount, MiddlewareNext, MiddlewareRequest,
+            MiddlewareResponse, MiddlewareTarget,
+        },
+    },
+    lifecycle::CancellationToken,
+    operation::OperationKind,
+};
+use std::{future::Future, sync::Arc};
+
+use super::http::{ExpectedBody, buffered_response, error_response, into_http_response};
+
+pub(crate) struct HttpMiddlewareInput {
+    pub endpoint: String,
+    pub protocol: String,
+    pub operation: Option<OperationKind>,
+    pub transport: ClientTransport,
+    pub model_hint: Option<String>,
+    pub headers: Vec<MiddlewareHeader>,
+    pub body: Bytes,
+}
+
+impl HttpMiddlewareInput {
+    pub(crate) fn query(endpoint: String, model_hint: Option<String>, headers: &HeaderMap) -> Self {
+        Self {
+            endpoint,
+            protocol: "openai".to_owned(),
+            operation: None,
+            transport: ClientTransport::HttpJson,
+            model_hint,
+            headers: request_headers(headers),
+            body: Bytes::new(),
+        }
+    }
+}
+
+/// 已鉴权只读查询共用入口；不重新鉴权、计量或创建 Provider attempt。
+pub(crate) async fn query_response<F, Fut>(
+    execution: Arc<dyn ExecutionService>,
+    client: AuthenticatedClient,
+    input: HttpMiddlewareInput,
+    terminal: F,
+) -> Response
+where
+    F: FnOnce(AuthenticatedClient) -> Fut + Send + 'static,
+    Fut: Future<Output = Response> + Send + 'static,
+{
+    let prepared = match execution.prepare_verified_execution(client) {
+        Ok(prepared) => prepared,
+        Err(error) => return gateway_error_response(&error),
+    };
+    let protocol = input.protocol.clone();
+    let result = invoke_http_middleware(
+        execution,
+        prepared,
+        input,
+        Box::new(move |prepared, request| {
+            Box::pin(async move {
+                if request.protocol() != protocol || !request.body().is_empty() {
+                    return Err(MiddlewareError::Rejected);
+                }
+                buffered_response(&protocol, terminal(prepared.client().clone()).await).await
+            })
+        }),
+    )
+    .await;
+    match result {
+        Ok(response) => into_http_response(response, ExpectedBody::SingleJson).await,
+        Err(error) => error_response(error),
+    }
+}
+
+pub(crate) type HttpMiddlewareTerminal = Box<
+    dyn FnOnce(
+            PreparedRootExecution,
+            MiddlewareRequest,
+        ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>>
+        + Send,
+>;
+
+pub(crate) async fn invoke_http_middleware(
+    execution: Arc<dyn ExecutionService>,
+    prepared: PreparedRootExecution,
+    input: HttpMiddlewareInput,
+    terminal: HttpMiddlewareTerminal,
+) -> Result<MiddlewareResponse, MiddlewareError> {
+    let plan = execution.middleware_plan(&prepared);
+    let lifetime = RequestLifetime {
+        cancellation: prepared.cancellation(),
+        _plan: plan.clone(),
+    };
+    let context = prepared.middleware_context(
+        MiddlewareTarget {
+            request_id: prepared.request_id().clone(),
+            mount: MiddlewareMount::Request,
+            attempt_index: None,
+            operation: input.operation,
+            endpoint: input.endpoint,
+            transport: input.transport,
+            provider: None,
+            model: input.model_hint,
+            account_id: None,
+        },
+        ExtensionCallScope::default(),
+    );
+    let request = MiddlewareRequest::new(input.protocol, input.headers, input.body);
+    let next = Box::new(HttpNext { prepared, terminal });
+    let response = match plan {
+        Some(plan) => plan.handle(context, request, next).await?,
+        None => next.run(request).await?,
+    };
+    let (protocol, status, headers, body, envelope) = response.into_parts();
+    let mut response = MiddlewareResponse::new(
+        protocol,
+        status,
+        headers,
+        Box::new(RequestBody { body, lifetime }),
+    );
+    if let Some(envelope) = envelope {
+        response = response.with_envelope(envelope);
+    }
+    Ok(response)
+}
+
+struct HttpNext {
+    prepared: PreparedRootExecution,
+    terminal: HttpMiddlewareTerminal,
+}
+
+impl MiddlewareNext for HttpNext {
+    fn run(
+        self: Box<Self>,
+        request: MiddlewareRequest,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        (self.terminal)(self.prepared, request)
+    }
+}
+
+struct RequestLifetime {
+    cancellation: CancellationToken,
+    _plan: Option<FrozenMiddlewarePlan>,
+}
+
+impl Drop for RequestLifetime {
+    fn drop(&mut self) {
+        // 包括还在 next 中等待、客户端断开和提前关流；不启动第二份账本终结逻辑。
+        self.cancellation.cancel();
+    }
+}
+
+struct RequestBody {
+    body: Box<dyn MiddlewareBody>,
+    lifetime: RequestLifetime,
+}
+
+impl MiddlewareBody for RequestBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        self.body.next_frame()
+    }
+
+    fn commit_downstream(
+        &mut self,
+        status: Option<u16>,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        self.body.commit_downstream(status)
+    }
+
+    fn record_client_status(&mut self, status: u16) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        self.body.record_client_status(status)
+    }
+
+    fn is_finalized(&self) -> bool {
+        self.body.is_finalized()
+    }
+
+    fn close(self: Box<Self>) -> BoxFuture<'static, ()> {
+        Box::pin(async move {
+            let Self { body, lifetime } = *self;
+            body.close().await;
+            drop(lifetime);
+        })
+    }
+}
+
+/// 保留多值与非 UTF-8 header；是否向插件公开由 Runtime 按授权投影。
+pub(crate) fn request_headers(headers: &HeaderMap) -> Vec<MiddlewareHeader> {
+    headers
+        .iter()
+        .map(|(name, value)| {
+            MiddlewareHeader::new(name.as_str(), Bytes::copy_from_slice(value.as_bytes()))
+        })
+        .collect()
+}
+
+/// 终点重新解码插件改写的请求；冻结认证身份不从这些 header 再次取得。
+pub(crate) fn request_parts(
+    request: MiddlewareRequest,
+) -> Result<(String, HeaderMap, Bytes), MiddlewareError> {
+    let (protocol, headers, body) = request.into_parts();
+    Ok((protocol, decode_headers(headers)?, body))
+}
+
+pub(super) fn decode_headers(headers: Vec<MiddlewareHeader>) -> Result<HeaderMap, MiddlewareError> {
+    let mut result = HeaderMap::new();
+    for header in headers {
+        let name = HeaderName::from_bytes(header.name().as_bytes())
+            .map_err(|_| MiddlewareError::InvalidState)?;
+        let value =
+            HeaderValue::from_bytes(header.value()).map_err(|_| MiddlewareError::InvalidState)?;
+        result.append(name, value);
+    }
+    Ok(result)
+}
diff --git a/backend/crates/gateway-api/src/openai/middleware/session.rs b/backend/crates/gateway-api/src/openai/middleware/session.rs
new file mode 100644
index 000000000..7d1ea484b
--- /dev/null
+++ b/backend/crates/gateway-api/src/openai/middleware/session.rs
@@ -0,0 +1,159 @@
+//! 非流式响应在洋葱链返回后才提交；既有执行守卫保管唯一终结责任。
+
+use futures::future::BoxFuture;
+use gateway_core::engine::middleware::{
+    MiddlewareBody, MiddlewareError, MiddlewareFrame, MiddlewareHeader, MiddlewareResponse,
+};
+
+use gateway_core::engine::execution::ExecutionSession;
+
+pub(crate) fn pending_execution_response(
+    protocol: String,
+    status: u16,
+    headers: Vec<MiddlewareHeader>,
+    frame: MiddlewareFrame,
+    execution: PendingExecution,
+) -> MiddlewareResponse {
+    MiddlewareResponse::new(
+        protocol,
+        status,
+        headers,
+        Box::new(BufferedExecutionBody {
+            frame: Some(frame),
+            execution,
+            commit_execution: (200..300).contains(&status),
+        }),
+    )
+}
+
+struct BufferedExecutionBody {
+    frame: Option<MiddlewareFrame>,
+    execution: PendingExecution,
+    // 原生结果决定是否提交执行；外层改写状态不能把失败转成 Core 成功。
+    commit_execution: bool,
+}
+
+impl MiddlewareBody for BufferedExecutionBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        // EOF 只表示单文档已读完；外层仍须验证正文并调用 commit，不能在此取消会话。
+        Box::pin(async { Ok(self.frame.take()) })
+    }
+
+    fn commit_downstream(
+        &mut self,
+        status: Option<u16>,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        Box::pin(async move {
+            if !self.commit_execution {
+                if let (Some(status), Some(session)) = (status, self.execution.session_mut()) {
+                    session.record_client_status(status).await?;
+                }
+                self.execution.cancel_and_finalize().await;
+                return Ok(());
+            }
+            let Some(session) = self.execution.session_mut() else {
+                return Ok(());
+            };
+            if session.is_finalized() {
+                if let Some(status) = status {
+                    session.record_client_status(status).await?;
+                }
+            } else {
+                session.commit_downstream(status).await?;
+                if !session.is_finalized() {
+                    return Err(MiddlewareError::InvalidState);
+                }
+            }
+            self.execution.disarm();
+            Ok(())
+        })
+    }
+
+    fn record_client_status(&mut self, status: u16) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        Box::pin(async move {
+            if let Some(session) = self.execution.session_mut() {
+                session.record_client_status(status).await?;
+            }
+            Ok(())
+        })
+    }
+
+    fn is_finalized(&self) -> bool {
+        self.execution.is_finalized()
+    }
+
+    fn close(mut self: Box<Self>) -> BoxFuture<'static, ()> {
+        Box::pin(async move {
+            self.execution.cancel_and_finalize().await;
+        })
+    }
+}
+
+pub(crate) async fn finalize_session(session: Box<dyn ExecutionSession>) {
+    if session.is_finalized() {
+        return;
+    }
+    session.cancel();
+    session.detach_finalize().await;
+}
+
+pub(crate) struct PendingExecution {
+    session: Option<Box<dyn ExecutionSession>>,
+}
+
+impl PendingExecution {
+    pub(crate) fn new(session: Box<dyn ExecutionSession>) -> Self {
+        Self {
+            session: Some(session),
+        }
+    }
+
+    pub(crate) fn session_mut(&mut self) -> Option<&mut (dyn ExecutionSession + 'static)> {
+        self.session.as_deref_mut()
+    }
+
+    pub(crate) fn is_finalized(&self) -> bool {
+        self.session
+            .as_ref()
+            .is_none_or(|session| session.is_finalized())
+    }
+
+    pub(crate) async fn cancel_and_finalize(&mut self) {
+        if let Some(session) = self.session.take() {
+            finalize_session(session).await;
+        }
+    }
+
+    pub(crate) async fn record_response_status(
+        &mut self,
+        response: axum::response::Response,
+    ) -> axum::response::Response {
+        if let Some(session) = self.session.as_mut() {
+            let _ = session
+                .record_client_status(response.status().as_u16())
+                .await;
+        }
+        response
+    }
+
+    pub(crate) fn disarm(&mut self) {
+        self.session = None;
+    }
+}
+
+impl Drop for PendingExecution {
+    fn drop(&mut self) {
+        let Some(session) = self.session.take() else {
+            return;
+        };
+        session.trace().record(
+            "downstream.cancelled",
+            serde_json::json!({"reason": "response_guard_dropped"}),
+        );
+        session.cancel();
+        let finalize = session.detach_finalize();
+        if let Ok(runtime) = tokio::runtime::Handle::try_current() {
+            drop(runtime.spawn(finalize));
+        }
+    }
+}
diff --git a/backend/crates/gateway-api/src/openai/mod.rs b/backend/crates/gateway-api/src/openai/mod.rs
index 8e529a56f..f50ca8146 100644
--- a/backend/crates/gateway-api/src/openai/mod.rs
+++ b/backend/crates/gateway-api/src/openai/mod.rs
@@ -4,6 +4,7 @@ pub mod auth;
 mod endpoint;
 pub mod error;
 pub mod images;
+pub(crate) mod middleware;
 pub mod models;
 pub mod responses;
 pub mod router;
@@ -12,7 +13,7 @@ pub(crate) mod service;
 mod usage;
 
 /// 客户端可读的 ID 必须能按现有请求记录检索；不以无关入口 ID 补位。
-fn with_model_request_id(
+pub(crate) fn with_model_request_id(
     mut response: axum::response::Response,
     request_id: &gateway_core::engine::ModelRequestId,
 ) -> axum::response::Response {
diff --git a/backend/crates/gateway-api/src/openai/models.rs b/backend/crates/gateway-api/src/openai/models.rs
index 300f4d0be..f8c9c41c0 100644
--- a/backend/crates/gateway-api/src/openai/models.rs
+++ b/backend/crates/gateway-api/src/openai/models.rs
@@ -6,11 +6,17 @@ use axum::{
     http::{HeaderMap, StatusCode},
     response::{IntoResponse, Response},
 };
-use gateway_core::routing::{PublicModelDescriptor, PublicModelId, PublicModelProfile};
+use gateway_core::{
+    engine::execution::AuthenticatedClient,
+    routing::{PublicModelDescriptor, PublicModelId, PublicModelProfile},
+};
 use serde::Deserialize;
 use serde_json::{Value, json};
 
-use crate::ApiState;
+use crate::{
+    ApiState,
+    openai::middleware::{self, HttpMiddlewareInput},
+};
 
 use super::{
     auth::{authenticate_client, client_access_error_response},
@@ -32,11 +38,27 @@ pub(crate) async fn models(
     headers: HeaderMap,
 ) -> Response {
     let service = state.openai();
-    let client = match authenticate_client(service, &headers) {
+    let client = match authenticate_client(service, &headers).await {
         Ok(client) => client,
         Err(error) => return client_access_error_response(error),
     };
 
+    middleware::query_response(
+        service.execution(),
+        client,
+        HttpMiddlewareInput::query(super::router::MODELS_PATH.to_owned(), None, &headers),
+        move |client| models_response(state, client, query),
+    )
+    .await
+}
+
+async fn models_response(
+    state: ApiState,
+    client: AuthenticatedClient,
+    query: ModelsQuery,
+) -> Response {
+    let service = state.openai();
+
     if let Some(version) = query
         .client_version
         .as_deref()
@@ -123,14 +145,33 @@ pub(crate) async fn model_detail(
     Path(model_id): Path<String>,
 ) -> Response {
     let service = state.openai();
-    let client = match authenticate_client(service, &headers) {
+    let client = match authenticate_client(service, &headers).await {
         Ok(client) => client,
         Err(error) => return client_access_error_response(error),
     };
+    middleware::query_response(
+        service.execution(),
+        client,
+        HttpMiddlewareInput::query(
+            format!("{}/{model_id}", super::router::MODELS_PATH),
+            Some(model_id.clone()),
+            &headers,
+        ),
+        move |client| async move { model_detail_response(&state, &client, model_id) },
+    )
+    .await
+}
+
+fn model_detail_response(
+    state: &ApiState,
+    client: &AuthenticatedClient,
+    model_id: String,
+) -> Response {
+    let service = state.openai();
     let Ok(public_model) = PublicModelId::new(model_id) else {
         return model_not_found_response().into_response();
     };
-    if !service.contains_public_model(&client, &public_model) {
+    if !service.contains_public_model(client, &public_model) {
         return model_not_found_response().into_response();
     }
 
diff --git a/backend/crates/gateway-api/src/openai/responses/error.rs b/backend/crates/gateway-api/src/openai/responses/error.rs
index 6a0d899d8..6bd8ea6ed 100644
--- a/backend/crates/gateway-api/src/openai/responses/error.rs
+++ b/backend/crates/gateway-api/src/openai/responses/error.rs
@@ -176,6 +176,9 @@ pub enum ResponseEncodeError {
     /// 协议原生流缺少可返回的终态 response object。
     #[error("responses wire stream has no terminal response")]
     MissingWireTerminal,
+    /// 缺少完整终态输出，已交付的完成项也存在缺项或冲突，不能伪造完整结果。
+    #[error("responses wire stream has inconsistent output items")]
+    InvalidOutputItems,
     /// 终态 response object 无法序列化为完整 HTTP JSON 响应。
     #[error("responses wire terminal serialization failed")]
     Serialization,
diff --git a/backend/crates/gateway-api/src/openai/responses/http.rs b/backend/crates/gateway-api/src/openai/responses/http.rs
index 4bf2cfa6f..ca966ba90 100644
--- a/backend/crates/gateway-api/src/openai/responses/http.rs
+++ b/backend/crates/gateway-api/src/openai/responses/http.rs
@@ -1,43 +1,64 @@
 //! OpenAI Responses HTTP 与 SSE adapter。
 
 use std::collections::VecDeque;
-use std::convert::Infallible;
+use std::future::Future;
 use std::net::{IpAddr, SocketAddr};
+use std::sync::{Arc, OnceLock};
 use std::time::Duration;
 
 use axum::{
-    body::{Body, Bytes},
+    body::Bytes,
     extract::{Extension, State, connect_info::ConnectInfo},
     http::{
         HeaderMap, HeaderName, HeaderValue, StatusCode,
-        header::{CACHE_CONTROL, CONTENT_TYPE, USER_AGENT},
+        header::{CONTENT_ENCODING, CONTENT_LENGTH, CONTENT_TYPE, USER_AGENT},
+    },
+    response::Response,
+};
+use futures::future::BoxFuture;
+use gateway_core::engine::{
+    CommitRequirement, EngineError,
+    execution::{ClientTransport, ExecutionSession, PreparedRootExecution, StartedExecution},
+    middleware::{
+        MiddlewareBody, MiddlewareError, MiddlewareFrame, MiddlewareFraming, MiddlewareHeader,
+        MiddlewareResponse,
     },
-    response::{IntoResponse, Response},
 };
-use futures::{StreamExt, stream};
-use gateway_core::diagnostics::TraceContext;
-use gateway_core::engine::execution::{ClientTransport, ExecutionSession, StartedExecution};
-use gateway_core::engine::{CommitRequirement, EngineError};
 use gateway_core::error::{GatewayError, GatewayErrorKind};
 use gateway_core::event::{ProviderEvent, ProviderResponseHeader};
-use gateway_core::lifecycle::ConnectionGuard;
+use gateway_core::lifecycle::{CancellationToken, ConnectionGuard};
+use gateway_core::operation::OperationKind;
 use gateway_protocol::openai::sse::{DONE_SSE_FRAME, response_failed_sse_event_with_id};
+use tokio::time::Instant;
 
 use crate::ApiState;
+use crate::openai::middleware::{
+    ExpectedBody, HttpMiddlewareInput, PendingExecution, error_response, finalize_session,
+    into_http_response, invoke_http_middleware, pending_execution_response, request_headers,
+    request_parts,
+};
+use crate::openai::service::OpenAiService;
 use crate::openai::{
     auth::{authenticate_client, client_access_error_response},
     error::{
         engine_error_response, gateway_error_contract, gateway_error_from_engine,
-        gateway_error_response, protocol_error_response, runtime_unavailable_response,
+        gateway_error_response, protocol_error_response,
     },
 };
 
 use super::{
-    OpenAiResponsesEncoder, ProtocolErrorBody, ResponseEncodeError,
-    request::decode_request_with_headers,
+    OpenAiResponsesEncoder, ResponseEncodeError,
+    request::{DecodedResponsesRequest, decode_request_with_body, decode_request_with_headers},
+    validation::{ResponseValidationFacts, ResponsesDeliveryValidator, validate_buffered_response},
 };
 
-const SSE_KEEPALIVE_INTERVAL: Duration = Duration::from_secs(15);
+const OPENAI_PROTOCOL: &str = "openai";
+const AUTHORIZATION_RECHECK_INTERVAL: Duration = Duration::from_secs(1);
+
+/// 管理页面模型桥在等待首帧和交付响应期间复核不可变插件目标。
+pub(crate) trait ResponseAuthorization: Send + Sync {
+    fn authorize(&self) -> BoxFuture<'_, Result<(), GatewayError>>;
+}
 
 /// `POST /v1/responses`。
 pub(crate) async fn responses(
@@ -47,71 +68,302 @@ pub(crate) async fn responses(
     headers: HeaderMap,
     body: Bytes,
 ) -> Response {
-    let service = state.openai();
-    let client = match authenticate_client(service, &headers) {
+    let service = state.openai().clone();
+    let client = match authenticate_client(&service, &headers).await {
         Ok(client) => client,
         Err(error) => return client_access_error_response(error),
     };
-    let decoded = match decode_request_with_headers(
-        &body,
-        &headers,
-        client.snapshot().responses_max_decompressed_body_bytes(),
-    ) {
-        Ok(decoded) => decoded,
-        Err(error) => {
-            return protocol_error_response(StatusCode::BAD_REQUEST, error.protocol_body());
-        }
-    };
-    let (client_ip, user_agent) = request_client_context(
-        &headers,
-        connect_info.map(|Extension(ConnectInfo(address))| address),
-    );
-    let decoded = decoded.with_client_context(client_ip, user_agent);
-    let streaming = decoded.metadata().stream();
-    let connection_guard = if streaming {
-        match service.try_register_connection() {
-            Ok(guard) => Some(guard),
-            Err(_) => return runtime_unavailable_response().into_response(),
-        }
-    } else {
-        None
-    };
-    let started = match service
-        .start_response(
-            client,
-            decoded,
-            if streaming {
-                ClientTransport::HttpSse
-            } else {
-                ClientTransport::HttpJson
-            },
-            "/v1/responses",
-        )
-        .await
-    {
-        Ok(started) => started,
+    let maximum_body_bytes = client.snapshot().responses_max_decompressed_body_bytes();
+    let (decoded, middleware_body) =
+        match decode_request_with_body(&body, &headers, maximum_body_bytes) {
+            Ok(decoded) => decoded,
+            Err(error) => {
+                return super::super::error::protocol_error_response(
+                    StatusCode::BAD_REQUEST,
+                    error.protocol_body(),
+                );
+            }
+        };
+    let execution = service.execution();
+    let prepared = match execution.prepare_execution(client).await {
+        Ok(prepared) => prepared,
         Err(error) => return gateway_error_response(&error),
     };
-    let trace = started.session.trace();
-    trace.headers("client.request", serde_json::json!({
-        "ingressRequestId": ingress_id.as_ref().and_then(|Extension(id)| id.header_value().to_str().ok()),
-    }), headers.iter().map(|(name, value)| (name.as_str(), value.as_bytes())));
-    trace.capture("client.request.body", &body);
-    let request_id = started.request_id;
-    let StartedExecution {
-        stream, session, ..
-    } = started;
-    let response = if stream {
-        stream_execution_response(session, connection_guard).await
+    execute_prepared_responses(
+        service,
+        prepared,
+        ResponsesHttpRequest {
+            peer_address: connect_info.map(|Extension(ConnectInfo(address))| address),
+            ingress_id,
+            headers,
+            decoded,
+            middleware_body,
+            maximum_body_bytes,
+        },
+        None,
+    )
+    .await
+}
+
+/// 两个 Responses 入口共享解码后的 HTTP 交付上下文，不携带认证策略。
+pub(crate) struct ResponsesHttpRequest {
+    pub peer_address: Option<SocketAddr>,
+    pub ingress_id: Option<Extension<tower_http::request_id::RequestId>>,
+    pub headers: HeaderMap,
+    pub decoded: DecodedResponsesRequest,
+    pub middleware_body: Bytes,
+    pub maximum_body_bytes: usize,
+}
+
+pub(crate) async fn execute_prepared_responses(
+    service: OpenAiService,
+    prepared: PreparedRootExecution,
+    request: ResponsesHttpRequest,
+    authorization: Option<Arc<dyn ResponseAuthorization>>,
+) -> Response {
+    let ResponsesHttpRequest {
+        peer_address,
+        ingress_id,
+        headers,
+        decoded,
+        middleware_body,
+        maximum_body_bytes,
+    } = request;
+    let (client_ip, user_agent) = request_client_context(&headers, peer_address);
+    let stream = decoded.metadata().stream();
+    let transport = if stream {
+        ClientTransport::HttpSse
     } else {
-        drop(connection_guard);
-        collect_execution_response(session).await
+        ClientTransport::HttpJson
     };
-    crate::openai::with_model_request_id(response, &request_id)
+    let model_hint = Some(decoded.metadata().requested_model().to_owned());
+    let execution = service.execution();
+    let request_id = prepared.request_id().clone();
+    let cancellation = prepared.cancellation();
+    let started_request_id = Arc::new(OnceLock::new());
+    let terminal_request_id = Arc::clone(&started_request_id);
+    let mut middleware_headers = headers.clone();
+    // 中间件正文已经由入口按上限解压；传输编码和旧长度不能与改写后的正文混用。
+    middleware_headers.remove(CONTENT_ENCODING);
+    middleware_headers.remove(CONTENT_LENGTH);
+    let input = HttpMiddlewareInput {
+        endpoint: crate::openai::router::RESPONSES_PATH.to_owned(),
+        protocol: OPENAI_PROTOCOL.to_owned(),
+        operation: Some(OperationKind::Generate),
+        transport,
+        model_hint,
+        headers: request_headers(&middleware_headers),
+        body: middleware_body,
+    };
+    let terminal_service = service.clone();
+    let validation = ResponseValidationFacts::default();
+    let terminal_validation = validation.clone();
+    let middleware = invoke_http_middleware(
+        execution,
+        prepared,
+        input,
+        Box::new(move |prepared, request| {
+            Box::pin(async move {
+                let (protocol, request_headers, request_body) = request_parts(request)?;
+                if protocol != OPENAI_PROTOCOL {
+                    return Err(MiddlewareError::Rejected);
+                }
+                let decoded = decode_request_with_headers(
+                    &request_body,
+                    &request_headers,
+                    maximum_body_bytes,
+                )
+                .map_err(|_| MiddlewareError::Rejected)?
+                .with_client_context(client_ip, user_agent);
+                if decoded.metadata().stream() != stream {
+                    return Err(MiddlewareError::Rejected);
+                }
+                let connection_guard = if stream {
+                    Some(
+                        terminal_service
+                            .try_register_connection()
+                            .map_err(|_| MiddlewareError::Fault)?,
+                    )
+                } else {
+                    None
+                };
+                let started = terminal_service
+                    .start_prepared_response(
+                        prepared,
+                        decoded,
+                        transport,
+                        crate::openai::router::RESPONSES_PATH,
+                    )
+                    .await
+                    .map_err(MiddlewareError::Gateway)?;
+                let _ = terminal_request_id.set(started.request_id.clone());
+                started.session.trace().headers(
+                    "client.request",
+                    serde_json::json!({
+                        "ingressRequestId": ingress_id.as_ref().and_then(|Extension(id)| id.header_value().to_str().ok()),
+                    }),
+                    request_headers
+                        .iter()
+                        .map(|(name, value)| (name.as_str(), value.as_bytes())),
+                );
+                started
+                    .session
+                    .trace()
+                    .capture("client.request.body", &request_body);
+                execution_middleware_response(started, connection_guard, terminal_validation).await
+            })
+        }),
+    );
+    let middleware = if let Some(authorization) = authorization.as_ref() {
+        match await_with_authorization(middleware, authorization, &cancellation).await {
+            Ok(result) => result,
+            Err(error) => Err(MiddlewareError::Gateway(error)),
+        }
+    } else {
+        middleware.await
+    };
+    let expected = if stream {
+        ExpectedBody::Sse
+    } else {
+        ExpectedBody::SingleJson
+    };
+    let response = match middleware {
+        Ok(response) => {
+            let response = if let Some(authorization) = authorization {
+                authorized_middleware_response(response, authorization, cancellation)
+            } else {
+                response
+            };
+            into_http_response(
+                validated_middleware_response(response, validation, stream),
+                expected,
+            )
+            .await
+        }
+        Err(error) => error_response(error),
+    };
+    super::super::with_model_request_id(response, started_request_id.get().unwrap_or(&request_id))
+}
+
+async fn await_with_authorization<T>(
+    future: impl Future<Output = T>,
+    authorization: &Arc<dyn ResponseAuthorization>,
+    cancellation: &CancellationToken,
+) -> Result<T, GatewayError> {
+    tokio::pin!(future);
+    loop {
+        tokio::select! {
+            output = &mut future => return Ok(output),
+            () = tokio::time::sleep(AUTHORIZATION_RECHECK_INTERVAL) => {
+                if let Err(error) = authorization.authorize().await {
+                    cancellation.cancel();
+                    return Err(error);
+                }
+            }
+        }
+    }
+}
+
+fn authorized_middleware_response(
+    response: MiddlewareResponse,
+    authorization: Arc<dyn ResponseAuthorization>,
+    cancellation: CancellationToken,
+) -> MiddlewareResponse {
+    let (protocol, status, headers, body, envelope) = response.into_parts();
+    let mut response = MiddlewareResponse::new(
+        protocol,
+        status,
+        headers,
+        Box::new(AuthorizedResponseBody {
+            inner: Some(body),
+            authorization,
+            cancellation,
+            last_authorized_at: Instant::now(),
+        }),
+    );
+    if let Some(envelope) = envelope {
+        response = response.with_envelope(envelope);
+    }
+    response
+}
+
+struct AuthorizedResponseBody {
+    inner: Option<Box<dyn MiddlewareBody>>,
+    authorization: Arc<dyn ResponseAuthorization>,
+    cancellation: CancellationToken,
+    last_authorized_at: Instant,
+}
+
+impl AuthorizedResponseBody {
+    async fn revoke(&mut self, error: GatewayError) -> MiddlewareError {
+        self.cancellation.cancel();
+        if let Some(inner) = self.inner.take() {
+            inner.close().await;
+        }
+        MiddlewareError::Gateway(error)
+    }
+}
+
+impl MiddlewareBody for AuthorizedResponseBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async move {
+            loop {
+                let elapsed = self.last_authorized_at.elapsed();
+                if elapsed >= AUTHORIZATION_RECHECK_INTERVAL {
+                    if let Err(error) = self.authorization.authorize().await {
+                        return Err(self.revoke(error).await);
+                    }
+                    self.last_authorized_at = Instant::now();
+                    continue;
+                }
+                let Some(inner) = self.inner.as_mut() else {
+                    return Ok(None);
+                };
+                let wait = AUTHORIZATION_RECHECK_INTERVAL - elapsed;
+                tokio::select! {
+                    frame = inner.next_frame() => return frame,
+                    () = tokio::time::sleep(wait) => {}
+                }
+            }
+        })
+    }
+
+    fn commit_downstream(
+        &mut self,
+        client_status_code: Option<u16>,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        let Some(inner) = self.inner.as_mut() else {
+            return Box::pin(async { Err(MiddlewareError::InvalidState) });
+        };
+        inner.commit_downstream(client_status_code)
+    }
+
+    fn record_client_status(
+        &mut self,
+        client_status_code: u16,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        let Some(inner) = self.inner.as_mut() else {
+            return Box::pin(async { Ok(()) });
+        };
+        inner.record_client_status(client_status_code)
+    }
+
+    fn is_finalized(&self) -> bool {
+        self.inner.as_ref().is_none_or(|inner| inner.is_finalized())
+    }
+
+    fn close(mut self: Box<Self>) -> BoxFuture<'static, ()> {
+        let inner = self.inner.take();
+        Box::pin(async move {
+            if let Some(inner) = inner {
+                inner.close().await;
+            }
+        })
+    }
 }
 
 /// 从 socket 与标准转发头提取旧 Usage 页面使用的诊断事实。
-pub(in crate::openai) fn request_client_context(
+pub(crate) fn request_client_context(
     headers: &HeaderMap,
     peer_address: Option<SocketAddr>,
 ) -> (Option<IpAddr>, Option<String>) {
@@ -159,96 +411,331 @@ const fn is_private_or_loopback(address: IpAddr) -> bool {
     }
 }
 
-/// 编码完整 canonical event 集合，并在完整 JSON 成功后提交下游。
-pub async fn collect_execution_response(session: Box<dyn ExecutionSession>) -> Response {
+async fn execution_middleware_response(
+    started: StartedExecution,
+    connection_guard: Option<Box<dyn ConnectionGuard>>,
+    validation: ResponseValidationFacts,
+) -> Result<MiddlewareResponse, MiddlewareError> {
+    let StartedExecution {
+        stream, session, ..
+    } = started;
+    if stream {
+        streaming_execution_middleware_response(session, connection_guard, validation).await
+    } else {
+        drop(connection_guard);
+        buffered_execution_middleware_response(session, validation).await
+    }
+}
+
+async fn buffered_execution_middleware_response(
+    session: Box<dyn ExecutionSession>,
+    validation: ResponseValidationFacts,
+) -> Result<MiddlewareResponse, MiddlewareError> {
     let mut execution = PendingExecution::new(session);
-    let Some(session) = execution.session_mut() else {
-        return internal_gateway_response("gateway response session is unavailable");
-    };
-    let events = match session.collect_uncommitted().await {
+    let collected = execution
+        .session_mut()
+        .ok_or(MiddlewareError::InvalidState)?
+        .collect_uncommitted()
+        .await;
+    let events = match collected {
         Ok(events) => events,
         Err(error) => {
-            let response_headers = session.response_headers().to_vec();
-            let response = engine_error_response_with_headers(&error, &response_headers);
-            return execution.record_response_status(response).await;
+            let headers = execution
+                .session_mut()
+                .ok_or(MiddlewareError::InvalidState)?
+                .response_headers()
+                .to_vec();
+            return guarded_engine_error_response(execution, &error, &headers).await;
         }
     };
-
+    let transformed = events.iter().any(ProviderEvent::middleware_transformed);
     let encoded = match encode_collected_events(&events) {
-        Ok(encoded) => encoded,
+        Ok(encoded) => Bytes::from(encoded),
         Err(error) => {
             let response =
                 protocol_error_response(StatusCode::INTERNAL_SERVER_ERROR, error.protocol_body());
-            let response = execution.record_response_status(response).await;
-            execution.cancel_and_finalize().await;
-            return response;
+            return guarded_http_response(execution, response).await;
         }
     };
-    let response_headers = session.response_headers().to_vec();
+    validation.observe_buffered(&events, &encoded);
+    let session = execution
+        .session_mut()
+        .ok_or(MiddlewareError::InvalidState)?;
     session.trace().record(
         "downstream.encoded",
         serde_json::json!({"transport": "http_json", "bytes": encoded.len()}),
     );
     session.trace().dump("downstream.body", &encoded);
-    let response = json_body_response(encoded, &response_headers);
+    let headers = response_headers(session.response_headers(), false);
+    Ok(pending_execution_response(
+        OPENAI_PROTOCOL.to_owned(),
+        StatusCode::OK.as_u16(),
+        headers,
+        MiddlewareFrame::new(encoded, MiddlewareFraming::JsonDocument, true)
+            .with_transformed(transformed),
+        execution,
+    ))
+}
 
-    let Some(session) = execution.session_mut() else {
-        return internal_gateway_response("gateway response session is unavailable");
-    };
-    if let Err(error) = session
-        .commit_downstream(Some(StatusCode::OK.as_u16()))
-        .await
+async fn streaming_execution_middleware_response(
+    session: Box<dyn ExecutionSession>,
+    connection_guard: Option<Box<dyn ConnectionGuard>>,
+    validation: ResponseValidationFacts,
+) -> Result<MiddlewareResponse, MiddlewareError> {
+    let mut body = StreamingExecutionBody::new(session, connection_guard, validation);
+    if let Err(error) = body.prime().await {
+        let headers = body.response_headers().to_vec();
+        let execution = body.take_pending_execution()?;
+        return match error {
+            MiddlewareError::Engine(error) => {
+                guarded_engine_error_response(execution, &error, &headers).await
+            }
+            error => guarded_http_response(execution, error_response(error)).await,
+        };
+    }
+    let headers = response_headers(body.response_headers(), true);
+    Ok(MiddlewareResponse::new(
+        OPENAI_PROTOCOL.to_owned(),
+        StatusCode::OK.as_u16(),
+        headers,
+        Box::new(body),
+    ))
+}
+
+/// 直接驱动测试 session 的非流式交付；生产入口通过同一 MiddlewareResponse 路径。
+pub async fn collect_execution_response(session: Box<dyn ExecutionSession>) -> Response {
+    match buffered_execution_middleware_response(session, ResponseValidationFacts::default()).await
     {
-        execution.cancel_and_finalize().await;
-        let response = engine_error_response_with_headers(&error, &response_headers);
-        return execution.record_response_status(response).await;
+        Ok(response) => into_http_response(response, ExpectedBody::SingleJson).await,
+        Err(error) => error_response(error),
     }
-    if !session.is_finalized() {
-        execution.cancel_and_finalize().await;
-        return internal_gateway_response("gateway response was not finalized after commit");
+}
+
+/// 直接驱动测试 session 的 SSE 交付；生产入口通过同一 MiddlewareResponse 路径。
+pub async fn stream_execution_response(
+    session: Box<dyn ExecutionSession>,
+    connection_guard: Option<Box<dyn ConnectionGuard>>,
+) -> Response {
+    match streaming_execution_middleware_response(
+        session,
+        connection_guard,
+        ResponseValidationFacts::default(),
+    )
+    .await
+    {
+        Ok(response) => into_http_response(response, ExpectedBody::Sse).await,
+        Err(error) => error_response(error),
+    }
+}
+
+fn validated_middleware_response(
+    response: MiddlewareResponse,
+    facts: ResponseValidationFacts,
+    streaming: bool,
+) -> MiddlewareResponse {
+    if !(200..300).contains(&response.status_code()) {
+        // 非成功响应沿用通用 SinglePayload 边界，不能套用成功 Responses 终态状态机。
+        return response;
+    }
+    let (protocol, status, headers, body, envelope) = response.into_parts();
+    let mut response = MiddlewareResponse::new(
+        protocol,
+        status,
+        headers,
+        Box::new(ValidatedResponsesBody {
+            inner: Some(body),
+            facts,
+            streaming,
+            validator: ResponsesDeliveryValidator::default(),
+            pending: VecDeque::new(),
+            committed: false,
+        }),
+    );
+    if let Some(envelope) = envelope {
+        response = response.with_envelope(envelope);
     }
-    execution.disarm();
     response
 }
 
-#[derive(Debug)]
-enum BufferedResponseEncodeError {
-    Canonical(ResponseEncodeError),
-    Json,
+struct ValidatedResponsesBody {
+    inner: Option<Box<dyn MiddlewareBody>>,
+    facts: ResponseValidationFacts,
+    streaming: bool,
+    validator: ResponsesDeliveryValidator,
+    pending: VecDeque<MiddlewareFrame>,
+    committed: bool,
 }
 
-impl BufferedResponseEncodeError {
-    fn protocol_body(&self) -> ProtocolErrorBody {
-        match self {
-            Self::Canonical(error) => error.protocol_body(),
-            Self::Json => ResponseEncodeError::Serialization.protocol_body(),
+impl ValidatedResponsesBody {
+    async fn fail_stream(&mut self) -> Option<MiddlewareFrame> {
+        if let Some(inner) = self.inner.take() {
+            inner.close().await;
         }
+        let response_id = self
+            .validator
+            .response_id()
+            .map(str::to_owned)
+            .or_else(|| self.facts.response_id());
+        self.pending.push_back(MiddlewareFrame::new(
+            Bytes::from(response_failed_sse_event_with_id(
+                response_id.as_deref(),
+                "server_error",
+                "middleware_failed",
+                "Response middleware returned an invalid stream.",
+            )),
+            MiddlewareFraming::SseEvent,
+            false,
+        ));
+        self.pending.push_back(done_frame());
+        self.pending.pop_front()
     }
 }
 
-fn encode_collected_events(
-    events: &[ProviderEvent],
-) -> Result<Vec<u8>, BufferedResponseEncodeError> {
-    let mut encoder = OpenAiResponsesEncoder::new();
-    for event in events {
-        encoder.push_sse(event);
+impl MiddlewareBody for ValidatedResponsesBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async move {
+            if let Some(frame) = self.pending.pop_front() {
+                return Ok(Some(frame));
+            }
+            let Some(inner) = self.inner.as_mut() else {
+                return Ok(None);
+            };
+            let frame = match inner.next_frame().await {
+                Ok(frame) => frame,
+                Err(error) if self.streaming && self.committed => {
+                    let _ = error;
+                    return Ok(self.fail_stream().await);
+                }
+                Err(error) => return Err(error),
+            };
+            let Some(frame) = frame else {
+                if self.streaming && self.validator.finish_delivery().is_err() {
+                    if self.committed {
+                        return Ok(self.fail_stream().await);
+                    }
+                    return Err(MiddlewareError::InvalidState);
+                }
+                return Ok(None);
+            };
+            let valid = if self.streaming {
+                self.validator
+                    .validate_frame(frame.bytes(), frame.transformed(), &self.facts)
+            } else if frame.transformed() {
+                validate_buffered_response(&self.facts, frame.bytes())
+            } else {
+                Ok(())
+            };
+            if valid.is_err() {
+                if self.streaming && self.committed {
+                    return Ok(self.fail_stream().await);
+                }
+                return Err(MiddlewareError::InvalidState);
+            }
+            Ok(Some(frame))
+        })
+    }
+
+    fn commit_downstream(
+        &mut self,
+        client_status_code: Option<u16>,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        Box::pin(async move {
+            let Some(inner) = self.inner.as_mut() else {
+                return Err(MiddlewareError::InvalidState);
+            };
+            inner.commit_downstream(client_status_code).await?;
+            self.committed = true;
+            Ok(())
+        })
+    }
+
+    fn record_client_status(
+        &mut self,
+        client_status_code: u16,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        Box::pin(async move {
+            match self.inner.as_mut() {
+                Some(inner) => inner.record_client_status(client_status_code).await,
+                None => Ok(()),
+            }
+        })
+    }
+
+    fn is_finalized(&self) -> bool {
+        self.inner.as_ref().is_none_or(|inner| inner.is_finalized())
+    }
+
+    fn close(mut self: Box<Self>) -> BoxFuture<'static, ()> {
+        let inner = self.inner.take();
+        Box::pin(async move {
+            if let Some(inner) = inner {
+                inner.close().await;
+            }
+        })
     }
-    let response = encoder
-        .finish()
-        .map_err(BufferedResponseEncodeError::Canonical)?;
-    serde_json::to_vec(&response).map_err(|_| BufferedResponseEncodeError::Json)
 }
 
-fn json_body_response(encoded: Vec<u8>, response_headers: &[ProviderResponseHeader]) -> Response {
-    let mut response = Response::new(Body::from(encoded));
-    *response.status_mut() = StatusCode::OK;
+fn encode_collected_events(events: &[ProviderEvent]) -> Result<Vec<u8>, ResponseEncodeError> {
+    let response = super::response::collect_response(events)?;
+    serde_json::to_vec(&response).map_err(|_| ResponseEncodeError::Serialization)
+}
+
+async fn guarded_engine_error_response(
+    execution: PendingExecution,
+    error: &EngineError,
+    response_headers: &[ProviderResponseHeader],
+) -> Result<MiddlewareResponse, MiddlewareError> {
+    guarded_http_response(
+        execution,
+        engine_error_response_with_headers(error, response_headers),
+    )
+    .await
+}
+
+async fn guarded_http_response(
+    execution: PendingExecution,
+    response: Response,
+) -> Result<MiddlewareResponse, MiddlewareError> {
+    let (parts, body) = response.into_parts();
+    let bytes = axum::body::to_bytes(body, usize::MAX)
+        .await
+        .map_err(|_| MiddlewareError::Fault)?;
+    Ok(pending_execution_response(
+        OPENAI_PROTOCOL.to_owned(),
+        parts.status.as_u16(),
+        request_headers(&parts.headers),
+        MiddlewareFrame::new(bytes, MiddlewareFraming::RawBytes, true),
+        execution,
+    ))
+}
+
+fn engine_error_response_with_headers(
+    error: &EngineError,
+    response_headers: &[ProviderResponseHeader],
+) -> Response {
+    let response = engine_error_response(error);
+    let failure_request_ids = ["x-request-id", "x-oai-request-id"]
+        .into_iter()
+        .flat_map(|name| {
+            response
+                .headers()
+                .get_all(name)
+                .iter()
+                .cloned()
+                .map(move |value| (name, value))
+        })
+        .collect::<Vec<_>>();
+    // 失败后仍须交付已采集的 turn state；只隔离 opening 身份，不丢弃会话状态。
+    let mut response = apply_provider_response_headers(response, response_headers);
+    response.headers_mut().remove("x-request-id");
+    response.headers_mut().remove("x-oai-request-id");
+    for (name, value) in failure_request_ids {
+        response.headers_mut().append(name, value);
+    }
     response
-        .headers_mut()
-        .insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
-    apply_response_headers(response, response_headers)
 }
 
-fn apply_response_headers(
+fn apply_provider_response_headers(
     mut response: Response,
     response_headers: &[ProviderResponseHeader],
 ) -> Response {
@@ -268,406 +755,314 @@ fn apply_response_headers(
     response
 }
 
-fn engine_error_response_with_headers(
-    error: &EngineError,
-    response_headers: &[ProviderResponseHeader],
-) -> Response {
-    let response = engine_error_response(error);
-    let failure_request_ids: Vec<_> = ["x-request-id", "x-oai-request-id"]
-        .into_iter()
-        .flat_map(|name| {
-            response
-                .headers()
-                .get_all(name)
-                .iter()
-                .cloned()
-                .map(move |value| (name, value))
-        })
-        .collect();
-    // 失败后仍须交付已采集的 turn state；只隔离 opening 身份，不丢弃会话状态。
-    let mut response = apply_response_headers(response, response_headers);
-    response.headers_mut().remove("x-request-id");
-    response.headers_mut().remove("x-oai-request-id");
-    for (name, value) in failure_request_ids {
-        response.headers_mut().append(name, value);
+fn response_headers(
+    provider_headers: &[ProviderResponseHeader],
+    streaming: bool,
+) -> Vec<MiddlewareHeader> {
+    let connection_options = super::response_connection_options(provider_headers);
+    let mut headers = Vec::new();
+    headers.push(MiddlewareHeader::new(
+        CONTENT_TYPE.as_str(),
+        Bytes::from_static(if streaming {
+            b"text/event-stream"
+        } else {
+            b"application/json"
+        }),
+    ));
+    for header in provider_headers {
+        if !super::response_header_is_forwardable(header.name(), &connection_options)
+            || header.name().eq_ignore_ascii_case(CONTENT_TYPE.as_str())
+            || HeaderName::from_bytes(header.name().as_bytes()).is_err()
+            || HeaderValue::from_bytes(header.value()).is_err()
+        {
+            continue;
+        }
+        headers.push(MiddlewareHeader::new(
+            header.name(),
+            Bytes::copy_from_slice(header.value()),
+        ));
     }
-    response
+    headers
 }
 
-/// 编码首个 SSE frame 后提交下游，再持续驱动同一执行会话。
-pub async fn stream_execution_response(
-    session: Box<dyn ExecutionSession>,
-    connection_guard: Option<Box<dyn ConnectionGuard>>,
-) -> Response {
-    let mut execution = PendingExecution::new(session);
-    let Some(session) = execution.session_mut() else {
-        return internal_gateway_response("gateway response session is unavailable");
-    };
-    let first = match session.next_event().await {
-        Ok(Some(event)) => event,
-        Ok(None) => {
-            let response = gateway_error_response(&GatewayError::new(
-                GatewayErrorKind::Internal,
-                "gateway response ended before its first event",
-            ));
-            let response = execution.record_response_status(response).await;
-            execution.cancel_and_finalize().await;
-            return response;
-        }
-        Err(error) => {
-            let response_headers = session.response_headers().to_vec();
-            let response = engine_error_response_with_headers(&error, &response_headers);
-            return execution.record_response_status(response).await;
-        }
-    };
-    let first_requirement = first.commit_requirement();
-    let first_events = first.into_provider_events();
-    if first_requirement != CommitRequirement::CommitBeforeDelivery {
-        let response = internal_gateway_response("gateway first event did not require commit");
-        let response = execution.record_response_status(response).await;
-        execution.cancel_and_finalize().await;
-        return response;
-    }
-    let mut encoder = OpenAiResponsesEncoder::new();
-    let mut frames = Vec::new();
-    for event in &first_events {
-        frames.extend(encoder.push_sse(event));
-    }
-    if frames.is_empty() {
-        let response = internal_gateway_response("gateway commit batch encoded no output");
-        let response = execution.record_response_status(response).await;
-        execution.cancel_and_finalize().await;
-        return response;
-    }
-    let Some(session) = execution.session_mut() else {
-        return internal_gateway_response("gateway response session is unavailable");
-    };
-    let response_headers = session.response_headers().to_vec();
-    if let Err(error) = session
-        .commit_downstream(Some(StatusCode::OK.as_u16()))
-        .await
-    {
-        execution.cancel_and_finalize().await;
-        let response = engine_error_response_with_headers(&error, &response_headers);
-        return execution.record_response_status(response).await;
-    }
-    let Some(session) = execution.into_session() else {
-        return internal_gateway_response("gateway response session is unavailable");
-    };
-    let mut state = ResponsesStreamState::new(session, encoder, frames, connection_guard);
-    if state.encoder.is_completed() {
-        state.finish_completed(Vec::new()).await;
-    }
-    let output = Box::pin(stream::unfold(state, |mut state| async move {
-        loop {
-            if let Some(chunk) = state.pending.pop_front() {
-                state.trace.dump("downstream.chunk", &chunk);
-                state.handed_off_bytes += chunk.len() as u64;
-                return Some((Ok::<Bytes, Infallible>(chunk), state));
-            }
-            if state.output_finished {
-                return None;
-            }
-            state.advance().await;
-        }
-    }));
-    // 保活只轮询已固定的输出 stream；不能取消并重建 advance/next_event future，
-    // 否则一次心跳就可能丢失正在等待的上游事件或执行终态清理。
-    let body = Body::from_stream(stream::unfold(output, |mut output| async move {
-        let chunk = tokio::select! {
-            biased;
-            chunk = output.next() => chunk?,
-            () = tokio::time::sleep(SSE_KEEPALIVE_INTERVAL) => {
-                Ok(Bytes::from_static(b": keep-alive\n\n"))
-            }
-        };
-        Some((chunk, output))
-    }));
-    event_stream_response(body, &response_headers)
-}
-
-fn event_stream_response(body: Body, response_headers: &[ProviderResponseHeader]) -> Response {
-    let mut response = apply_response_headers(Response::new(body), response_headers);
-    *response.status_mut() = StatusCode::OK;
-    response
-        .headers_mut()
-        .insert(CONTENT_TYPE, HeaderValue::from_static("text/event-stream"));
-    response.headers_mut().insert(
-        CACHE_CONTROL,
-        HeaderValue::from_static("no-cache, no-transform"),
-    );
-    response
-        .headers_mut()
-        .insert("x-accel-buffering", HeaderValue::from_static("no"));
-    response
-}
-
-fn internal_gateway_response(message: &'static str) -> Response {
-    gateway_error_response(&GatewayError::new(GatewayErrorKind::Internal, message))
-}
-
-pub(in crate::openai) struct PendingExecution {
-    session: Option<Box<dyn ExecutionSession>>,
-}
-
-impl PendingExecution {
-    pub(in crate::openai) fn new(session: Box<dyn ExecutionSession>) -> Self {
-        Self {
-            session: Some(session),
-        }
-    }
-
-    pub(in crate::openai) fn session_mut(
-        &mut self,
-    ) -> Option<&mut (dyn ExecutionSession + 'static)> {
-        self.session.as_deref_mut()
-    }
-
-    pub(in crate::openai) async fn cancel_and_finalize(&mut self) {
-        if let Some(session) = self.session.as_mut() {
-            session.cancel();
-            if !session.is_finalized() {
-                let _ = session.next_event().await;
-            }
-        }
-    }
-
-    pub(in crate::openai) async fn record_response_status(
-        &mut self,
-        response: Response,
-    ) -> Response {
-        if let Some(session) = self.session.as_mut() {
-            let _ = session
-                .record_client_status(response.status().as_u16())
-                .await;
-        }
-        response
-    }
-
-    pub(in crate::openai) fn disarm(&mut self) {
-        self.session = None;
-    }
-
-    fn into_session(mut self) -> Option<Box<dyn ExecutionSession>> {
-        self.session.take()
-    }
-}
-
-impl Drop for PendingExecution {
-    fn drop(&mut self) {
-        let Some(session) = self.session.take() else {
-            return;
-        };
-        if session.is_finalized() {
-            return;
-        }
-        session.trace().record(
-            "downstream.cancelled",
-            serde_json::json!({"reason": "response_guard_dropped"}),
-        );
-        session.cancel();
-        detach_finalize(session);
-    }
-}
-
-struct ResponsesStreamState {
-    trace: TraceContext,
-    handed_off_bytes: u64,
+struct StreamingExecutionBody {
     session: Option<Box<dyn ExecutionSession>>,
     encoder: OpenAiResponsesEncoder,
-    pending: VecDeque<Bytes>,
+    validation: ResponseValidationFacts,
+    pending: VecDeque<MiddlewareFrame>,
+    awaiting_terminal_eof: bool,
     output_finished: bool,
-    execution_terminal: bool,
+    batch_pending: bool,
+    transformed_pending: bool,
+    committed: bool,
     _connection_guard: Option<Box<dyn ConnectionGuard>>,
 }
 
-impl ResponsesStreamState {
+impl StreamingExecutionBody {
     fn new(
         session: Box<dyn ExecutionSession>,
-        encoder: OpenAiResponsesEncoder,
-        initial_frames: Vec<Bytes>,
         connection_guard: Option<Box<dyn ConnectionGuard>>,
+        validation: ResponseValidationFacts,
     ) -> Self {
         Self {
-            trace: session.trace(),
-            handed_off_bytes: 0,
             session: Some(session),
-            encoder,
-            pending: initial_frames.into_iter().collect(),
+            encoder: OpenAiResponsesEncoder::new(),
+            validation,
+            pending: VecDeque::new(),
+            awaiting_terminal_eof: false,
             output_finished: false,
-            execution_terminal: false,
+            batch_pending: false,
+            transformed_pending: false,
+            committed: false,
             _connection_guard: connection_guard,
         }
     }
 
-    async fn advance(&mut self) {
-        let next = match self.session.as_mut() {
-            Some(session) => session.next_event().await,
-            None => {
-                self.finish_with_gateway_error(GatewayError::new(
-                    GatewayErrorKind::Internal,
-                    "gateway response session is unavailable",
-                ));
-                return;
-            }
-        };
-        match next {
-            Ok(Some(event)) => {
-                let requirement = event.commit_requirement();
-                let events = event.into_provider_events();
-                if requirement != CommitRequirement::AlreadyCommitted {
-                    self.cancel_execution().await;
-                    self.finish_with_gateway_error(GatewayError::new(
-                        GatewayErrorKind::Internal,
-                        "gateway requested another downstream commit",
-                    ));
-                } else {
-                    for event in events {
-                        self.push_event(event).await;
-                        if self.output_finished {
-                            break;
-                        }
-                    }
-                }
-            }
-            Ok(None) => {
-                self.execution_terminal = self
-                    .session
-                    .as_ref()
-                    .is_some_and(|session| session.is_finalized());
-                if self.execution_terminal {
-                    self.pending
-                        .push_back(Bytes::from_static(DONE_SSE_FRAME.as_bytes()));
-                    self.output_finished = true;
-                } else {
-                    self.finish_with_gateway_error(GatewayError::new(
-                        GatewayErrorKind::Internal,
-                        "gateway response ended without finalizing the execution",
-                    ));
-                }
-            }
-            Err(error) => {
-                self.execution_terminal = self
-                    .session
-                    .as_ref()
-                    .is_some_and(|session| session.is_finalized());
-                if self.encoder.has_wire_failure() {
-                    self.pending
-                        .push_back(Bytes::from_static(DONE_SSE_FRAME.as_bytes()));
-                    self.output_finished = true;
-                } else {
-                    self.finish_with_gateway_error(gateway_error_from_engine(&error));
-                }
-            }
+    async fn prime(&mut self) -> Result<(), MiddlewareError> {
+        self.fill_pending().await?;
+        if self.pending.is_empty() {
+            return Err(MiddlewareError::InvalidState);
         }
+        Ok(())
     }
 
-    async fn push_event(&mut self, event: ProviderEvent) {
-        let frames = self.encoder.push_sse(&event);
-        if self.encoder.is_completed() {
-            self.finish_completed(frames).await;
-        } else {
-            self.pending.extend(frames);
-        }
+    fn response_headers(&self) -> &[ProviderResponseHeader] {
+        self.session
+            .as_ref()
+            .map_or(&[], |session| session.response_headers())
     }
 
-    async fn finish_completed(&mut self, frames: Vec<Bytes>) {
-        let next = match self.session.as_mut() {
-            Some(session) => session.next_event().await,
-            None => {
-                self.finish_with_gateway_error(GatewayError::new(
-                    GatewayErrorKind::Internal,
-                    "gateway response session is unavailable",
-                ));
-                return;
+    async fn fill_pending(&mut self) -> Result<(), MiddlewareError> {
+        while self.pending.is_empty() && !self.output_finished {
+            if self.awaiting_terminal_eof {
+                if !self.committed {
+                    // 终态 wire 不能在首字节前被中间件整批移除。
+                    return Err(MiddlewareError::InvalidState);
+                }
+                self.verify_terminal_eof().await?;
+                self.pending.push_back(done_frame());
+                self.output_finished = true;
+                continue;
             }
-        };
-        match next {
-            Ok(None)
-                if self
-                    .session
-                    .as_ref()
-                    .is_some_and(|session| session.is_finalized()) =>
-            {
-                self.pending.extend(frames);
-                self.execution_terminal = true;
-                self.pending
-                    .push_back(Bytes::from_static(DONE_SSE_FRAME.as_bytes()));
+            if self.batch_pending {
+                if !self.committed {
+                    self.session
+                        .as_mut()
+                        .ok_or(MiddlewareError::InvalidState)?
+                        .discard_pending_delivery()
+                        .map_err(MiddlewareError::Engine)?;
+                }
+                self.batch_pending = false;
+            }
+            let result = self
+                .session
+                .as_mut()
+                .ok_or(MiddlewareError::InvalidState)?
+                .next_event()
+                .await;
+            let coordinated = match result {
+                Ok(Some(event)) => event,
+                Ok(None) if self.committed && self.is_finalized() => {
+                    self.pending.push_back(done_frame());
+                    self.output_finished = true;
+                    continue;
+                }
+                Ok(None) => return Err(invalid_execution_stream()),
+                Err(error) if self.committed => {
+                    self.push_stream_error(gateway_error_from_engine(&error));
+                    continue;
+                }
+                Err(error) => return Err(MiddlewareError::Engine(error)),
+            };
+            let expected = if self.committed {
+                CommitRequirement::AlreadyCommitted
+            } else {
+                CommitRequirement::CommitBeforeDelivery
+            };
+            if coordinated.commit_requirement() != expected {
+                return Err(invalid_execution_stream());
+            }
+            let mut encoded = VecDeque::new();
+            for event in coordinated.into_provider_events() {
+                self.validation.observe_event(&event);
+                let transformed = self.transformed_pending || event.middleware_transformed();
+                let frames = self.encoder.push_sse(&event);
+                if frames.is_empty() {
+                    self.transformed_pending = transformed;
+                    continue;
+                }
+                encoded.extend(frames.into_iter().map(|bytes| {
+                    MiddlewareFrame::new(bytes, MiddlewareFraming::SseEvent, false)
+                        .with_transformed(transformed)
+                }));
+                self.transformed_pending = false;
+            }
+            self.awaiting_terminal_eof =
+                self.encoder.is_completed() || self.encoder.has_wire_failure();
+            self.batch_pending = !self.committed;
+            if encoded.is_empty() {
+                if !self.committed || self.awaiting_terminal_eof {
+                    return Err(invalid_execution_stream());
+                }
+                continue;
+            }
+            // 已提交的流在确认 Core 终结后才交付成功终态，不能先输出 completed 再报结算失败。
+            if self.awaiting_terminal_eof && self.committed {
+                self.verify_terminal_eof().await?;
+                encoded.push_back(done_frame());
                 self.output_finished = true;
             }
-            Ok(None) => {
-                self.cancel_execution().await;
-                self.finish_with_gateway_error(GatewayError::new(
-                    GatewayErrorKind::Internal,
-                    "gateway response was not finalized after its terminal event",
-                ));
-            }
-            Ok(Some(_)) => {
-                self.cancel_execution().await;
-                self.finish_with_gateway_error(GatewayError::new(
-                    GatewayErrorKind::Internal,
-                    "gateway response continued after its terminal event",
-                ));
-            }
-            Err(error) => {
-                self.execution_terminal = self
-                    .session
-                    .as_ref()
-                    .is_some_and(|session| session.is_finalized());
-                self.finish_with_gateway_error(gateway_error_from_engine(&error));
-            }
+            self.pending = encoded;
+        }
+        Ok(())
+    }
+
+    async fn verify_terminal_eof(&mut self) -> Result<(), MiddlewareError> {
+        let result = self
+            .session
+            .as_mut()
+            .ok_or(MiddlewareError::InvalidState)?
+            .next_event()
+            .await;
+        match result {
+            Ok(None) if self.is_finalized() => Ok(()),
+            Err(_) if self.encoder.has_wire_failure() && self.is_finalized() => Ok(()),
+            Ok(_) => Err(invalid_execution_stream()),
+            Err(error) => Err(MiddlewareError::Engine(error)),
         }
     }
 
-    async fn cancel_execution(&mut self) {
-        if let Some(session) = self.session.as_mut() {
-            session.cancel();
-            if !session.is_finalized() {
-                let _ = session.next_event().await;
-            }
-            self.execution_terminal = session.is_finalized();
-        }
-    }
-
-    fn finish_with_gateway_error(&mut self, error: GatewayError) {
+    fn push_stream_error(&mut self, error: GatewayError) {
         let (_, default_type, default_code) = gateway_error_contract(error.kind());
-        self.pending
-            .push_back(Bytes::from(response_failed_sse_event_with_id(
+        self.pending.push_back(MiddlewareFrame::new(
+            Bytes::from(response_failed_sse_event_with_id(
                 self.encoder.response_id(),
                 error.client_error_type().unwrap_or(default_type),
                 super::super::error::client_error_code(
                     error.client_error_code().unwrap_or(default_code),
                 ),
                 error.client_message(),
-            )));
-        self.pending
-            .push_back(Bytes::from_static(DONE_SSE_FRAME.as_bytes()));
+            )),
+            MiddlewareFraming::SseEvent,
+            false,
+        ));
+        self.pending.push_back(done_frame());
         self.output_finished = true;
     }
+
+    fn take_session_for_close(&mut self) -> Option<Box<dyn ExecutionSession>> {
+        self.session.take()
+    }
+
+    fn take_pending_execution(&mut self) -> Result<PendingExecution, MiddlewareError> {
+        self.take_session_for_close()
+            .map(PendingExecution::new)
+            .ok_or(MiddlewareError::InvalidState)
+    }
 }
 
-impl Drop for ResponsesStreamState {
+impl MiddlewareBody for StreamingExecutionBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async move {
+            if let Some(frame) = self.pending.pop_front() {
+                return Ok(Some(frame));
+            }
+            if self.output_finished {
+                return Ok(None);
+            }
+            if let Err(error) = self.fill_pending().await {
+                if !self.committed {
+                    return Err(error);
+                }
+                let error = match error {
+                    MiddlewareError::Gateway(error) => error,
+                    MiddlewareError::Engine(error) => gateway_error_from_engine(&error),
+                    _ => GatewayError::new(
+                        GatewayErrorKind::Internal,
+                        "gateway response stream could not be delivered",
+                    ),
+                };
+                self.push_stream_error(error);
+            }
+            Ok(self.pending.pop_front())
+        })
+    }
+
+    fn commit_downstream(
+        &mut self,
+        client_status_code: Option<u16>,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        Box::pin(async move {
+            if self.committed {
+                return Ok(());
+            }
+            self.session
+                .as_mut()
+                .ok_or(MiddlewareError::InvalidState)?
+                .commit_downstream(client_status_code)
+                .await
+                .map_err(MiddlewareError::Engine)?;
+            self.committed = true;
+            self.batch_pending = false;
+            Ok(())
+        })
+    }
+
+    fn record_client_status(
+        &mut self,
+        client_status_code: u16,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        Box::pin(async move {
+            let Some(session) = self.session.as_mut() else {
+                return Ok(());
+            };
+            session
+                .record_client_status(client_status_code)
+                .await
+                .map_err(MiddlewareError::Engine)
+        })
+    }
+
+    fn is_finalized(&self) -> bool {
+        self.session
+            .as_ref()
+            .is_none_or(|session| session.is_finalized())
+    }
+
+    fn close(mut self: Box<Self>) -> BoxFuture<'static, ()> {
+        let session = self.take_session_for_close();
+        Box::pin(async move {
+            if let Some(session) = session {
+                finalize_session(session).await;
+            }
+        })
+    }
+}
+
+impl Drop for StreamingExecutionBody {
     fn drop(&mut self) {
-        self.trace.record("downstream.body.closed", serde_json::json!({
-            "handedOffBytes": self.handed_off_bytes,
-            "pendingChunks": self.pending.len(),
-            "outputFinished": self.output_finished, "executionTerminal": self.execution_terminal,
-        }));
-        if self.execution_terminal {
-            return;
-        }
-        let Some(session) = self.session.take() else {
+        let Some(session) = self.take_session_for_close() else {
             return;
         };
         session.cancel();
-        // Body drop 后由 Core 继续状态机清理，HTTP body 生命周期不等待它。
-        detach_finalize(session);
+        let finalize = session.detach_finalize();
+        if let Ok(runtime) = tokio::runtime::Handle::try_current() {
+            drop(runtime.spawn(finalize));
+        }
     }
 }
 
-fn detach_finalize(session: Box<dyn ExecutionSession>) {
-    let finalize = session.detach_finalize();
-    if let Ok(runtime) = tokio::runtime::Handle::try_current() {
-        drop(runtime.spawn(finalize));
-    }
+fn done_frame() -> MiddlewareFrame {
+    MiddlewareFrame::new(
+        Bytes::from_static(DONE_SSE_FRAME.as_bytes()),
+        MiddlewareFraming::SseEvent,
+        true,
+    )
+}
+
+fn invalid_execution_stream() -> MiddlewareError {
+    MiddlewareError::Gateway(GatewayError::new(
+        GatewayErrorKind::Internal,
+        "gateway response stream violated its execution lifecycle",
+    ))
 }
diff --git a/backend/crates/gateway-api/src/openai/responses/mod.rs b/backend/crates/gateway-api/src/openai/responses/mod.rs
index daa0aa2de..c04ca9e85 100644
--- a/backend/crates/gateway-api/src/openai/responses/mod.rs
+++ b/backend/crates/gateway-api/src/openai/responses/mod.rs
@@ -4,12 +4,16 @@ mod error;
 mod http;
 mod request;
 mod response;
+mod validation;
 pub mod websocket;
 
 pub use error::{ProtocolError, ProtocolErrorBody, RequestDecodeError, ResponseEncodeError};
-pub(crate) use http::responses;
-pub(super) use http::{PendingExecution, request_client_context};
+pub(crate) use http::{
+    ResponseAuthorization, ResponsesHttpRequest, execute_prepared_responses,
+    request_client_context, responses,
+};
 pub use http::{collect_execution_response, stream_execution_response};
+pub(crate) use request::decode_request_with_body;
 pub use request::{
     ContinuationIntent, DecodedResponsesRequest, OpenAiRequestHeaders, ResponsesRequestMetadata,
     decode_request_with_headers,
@@ -19,6 +23,7 @@ pub(crate) use websocket::responses_websocket;
 pub use websocket::{ResponseCreateFrameError, decode_response_create_with_context};
 
 use gateway_core::event::ProviderResponseHeader;
+pub(super) use gateway_protocol::openai::response_header_is_forwardable;
 
 pub(super) fn response_connection_options(headers: &[ProviderResponseHeader]) -> Vec<String> {
     headers
@@ -31,49 +36,3 @@ pub(super) fn response_connection_options(headers: &[ProviderResponseHeader]) ->
         .map(str::to_ascii_lowercase)
         .collect()
 }
-
-pub(super) fn response_header_is_forwardable(name: &str, connection_options: &[String]) -> bool {
-    let name = name.trim().to_ascii_lowercase();
-    if connection_options
-        .iter()
-        .any(|option| option.eq_ignore_ascii_case(&name))
-        || name.starts_with("sec-websocket-")
-    {
-        return false;
-    }
-
-    !matches!(
-        name.as_str(),
-        "connection"
-            | "keep-alive"
-            | "proxy-connection"
-            | "te"
-            | "trailer"
-            | "transfer-encoding"
-            | "upgrade"
-            | "content-length"
-            | "content-type"
-            | "content-encoding"
-            | "authorization"
-            | "x-api-key"
-            | "www-authenticate"
-            | "authentication-info"
-            | "proxy-authenticate"
-            | "proxy-authorization"
-            | "proxy-authentication-info"
-            | "cookie"
-            | "cookie2"
-            | "set-cookie"
-            | "set-cookie2"
-            | "chatgpt-account-id"
-            | "chatgpt-organization-id"
-            | "chatgpt-org-id"
-            | "chatgpt-project-id"
-            | "openai-organization"
-            | "openai-project"
-            | "x-openai-organization"
-            | "x-openai-project"
-            | "x-codex-installation-id"
-            | "x-codex-turn-metadata"
-    )
-}
diff --git a/backend/crates/gateway-api/src/openai/responses/request.rs b/backend/crates/gateway-api/src/openai/responses/request.rs
index 55f18aafa..fda633309 100644
--- a/backend/crates/gateway-api/src/openai/responses/request.rs
+++ b/backend/crates/gateway-api/src/openai/responses/request.rs
@@ -4,6 +4,7 @@ use std::{borrow::Cow, fmt, net::IpAddr};
 
 use axum::http::HeaderMap;
 use base64::{Engine as _, engine::general_purpose::STANDARD};
+use bytes::Bytes;
 use gateway_core::operation::{GenerateRequest, Operation, ProtocolPayload, ProviderSessionState};
 use gateway_protocol::openai::{
     X_OPENAI_INTERNAL_CODEX_RESPONSES_LITE_HEADER, X_OPENAI_MEMGEN_REQUEST_HEADER,
@@ -333,6 +334,20 @@ pub fn decode_request_with_headers(
     decode_request_inner(&body, &OpenAiRequestHeaders::from_headers(headers))
 }
 
+/// 解码请求并返回已经解除 HTTP content encoding 的中间件正文。
+///
+/// 外层中间件只接收有界的协议正文；terminal 会用中间件返回的正文重新解码，
+/// 因而不能把压缩字节与已经移除的传输编码语义混用。
+pub(crate) fn decode_request_with_body(
+    body: &[u8],
+    headers: &HeaderMap,
+    max_decompressed_bytes: usize,
+) -> Result<(DecodedResponsesRequest, Bytes), RequestDecodeError> {
+    let body = decompress_request_body(body, headers, max_decompressed_bytes)?;
+    let decoded = decode_request_inner(&body, &OpenAiRequestHeaders::from_headers(headers))?;
+    Ok((decoded, Bytes::copy_from_slice(&body)))
+}
+
 /// zstd 回溯窗口独立于输出上限，调整设置不能放大解码器内部窗口分配。
 const MAX_ZSTD_WINDOW_LOG: u32 = 26;
 
diff --git a/backend/crates/gateway-api/src/openai/responses/response.rs b/backend/crates/gateway-api/src/openai/responses/response.rs
index fcfdad733..c0b93b451 100644
--- a/backend/crates/gateway-api/src/openai/responses/response.rs
+++ b/backend/crates/gateway-api/src/openai/responses/response.rs
@@ -1,5 +1,7 @@
 //! Provider OpenAI Responses wire 到客户端 transport 的透明转发边界。
 
+use std::collections::BTreeMap;
+
 use bytes::Bytes;
 use gateway_core::event::{GatewayEvent, ProtocolWireEvent, ProviderEvent};
 use gateway_protocol::openai::sse::{
@@ -141,12 +143,7 @@ impl OpenAiResponsesEncoder {
     }
 
     fn observe_wire(&mut self, wire: &ProtocolWireEvent) {
-        if let Some(response_id) = wire
-            .data()
-            .pointer("/response/id")
-            .or_else(|| wire.data().get("response_id"))
-            .and_then(Value::as_str)
-        {
+        if let Some(response_id) = wire_response_id(wire) {
             self.response_id = Some(response_id.to_owned());
         }
         let effective_type = effective_event_type(wire);
@@ -171,6 +168,72 @@ impl OpenAiResponsesEncoder {
     }
 }
 
+/// 仅在非流式出口聚合同一响应的完成项，不让流式转发常驻保存输出内容。
+pub(super) fn collect_response(events: &[ProviderEvent]) -> Result<Value, ResponseEncodeError> {
+    let mut encoder = OpenAiResponsesEncoder::new();
+    let mut response_id = None;
+    let mut items = BTreeMap::new();
+    let mut invalid_items = false;
+    for wire in events.iter().filter_map(openai_wire) {
+        if let Some(id) = wire_response_id(wire) {
+            if response_id.is_some_and(|previous| previous != id) {
+                items.clear();
+                invalid_items = false;
+            }
+            response_id = Some(id);
+        }
+        if !encoder.is_completed()
+            && effective_event_type(wire) == Some("response.output_item.done")
+        {
+            match (
+                wire.data().get("output_index").and_then(Value::as_u64),
+                wire.data().get("item").filter(|item| item.is_object()),
+            ) {
+                (Some(index), Some(item)) => {
+                    if let Some(previous) = items.insert(index, item) {
+                        invalid_items |= previous != item;
+                    }
+                }
+                _ => invalid_items = true,
+            }
+        }
+        encoder.observe_wire(wire);
+    }
+    let mut response = encoder.finish()?;
+    let Some(object) = response.as_object_mut() else {
+        return Ok(response);
+    };
+    // Codex 可只在 output_item.done 交付内容，终态仅保留身份和 usage。
+    // 有内容的终态仍是完整快照，不与 earlier done 或 canonical 增量拼接。
+    if object
+        .get("output")
+        .is_some_and(|output| !output.as_array().is_some_and(Vec::is_empty))
+        || (items.is_empty() && !invalid_items)
+    {
+        return Ok(response);
+    }
+    if invalid_items
+        || items
+            .keys()
+            .enumerate()
+            .any(|(expected, actual)| expected as u64 != *actual)
+    {
+        return Err(ResponseEncodeError::InvalidOutputItems);
+    }
+    object.insert(
+        "output".to_owned(),
+        Value::Array(items.into_values().cloned().collect()),
+    );
+    Ok(response)
+}
+
+fn wire_response_id(wire: &ProtocolWireEvent) -> Option<&str> {
+    wire.data()
+        .pointer("/response/id")
+        .or_else(|| wire.data().get("response_id"))
+        .and_then(Value::as_str)
+}
+
 fn openai_wire(event: &ProviderEvent) -> Option<&ProtocolWireEvent> {
     event
         .wire_event()
diff --git a/backend/crates/gateway-api/src/openai/responses/validation.rs b/backend/crates/gateway-api/src/openai/responses/validation.rs
new file mode 100644
index 000000000..6c7f4aca4
--- /dev/null
+++ b/backend/crates/gateway-api/src/openai/responses/validation.rs
@@ -0,0 +1,698 @@
+//! 插件改写后的 OpenAI Responses 投递协议复核。
+
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    sync::{Arc, Mutex},
+};
+
+use gateway_core::event::{GatewayEvent, ProtocolWireEvent, ProviderEvent};
+use gateway_protocol::openai::sse::{parse_sse_events, sse_frame_is_done};
+use serde_json::{Map, Value};
+
+const MAX_TRACKED_OUTPUT_ITEMS: usize = 4_096;
+const MAX_IDENTIFIER_BYTES: usize = 1_024;
+
+/// 插件输出不能安全投递为 OpenAI Responses 协议。
+#[derive(Debug, Clone, Copy)]
+pub(super) struct ResponseValidationError;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum TerminalKind {
+    Completed,
+    Incomplete,
+    Failed,
+    Done,
+}
+
+#[derive(Debug, Clone, Default)]
+struct ExpectedResponseFacts {
+    response_id: Option<String>,
+    terminal: Option<TerminalKind>,
+    invalid: bool,
+}
+
+/// 仅保存最终协议复核所需的响应 ID 与终态类别，不缓存流正文。
+#[derive(Clone, Default)]
+pub(super) struct ResponseValidationFacts(Arc<Mutex<ExpectedResponseFacts>>);
+
+impl ResponseValidationFacts {
+    pub(super) fn observe_event(&self, event: &ProviderEvent) {
+        let mut facts = self
+            .0
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if let Some(wire) = event
+            .middleware_origin_wire()
+            .or_else(|| event.wire_event())
+            .filter(|wire| wire.protocol() == "openai")
+        {
+            facts.observe_wire(wire);
+        }
+        for fact in event.canonical_facts() {
+            if let GatewayEvent::Started(metadata) = fact {
+                facts.observe_response_id(metadata.response_id());
+            }
+        }
+    }
+
+    pub(super) fn observe_buffered(&self, events: &[ProviderEvent], original: &[u8]) {
+        for event in events {
+            self.observe_event(event);
+        }
+        let Ok(value) = serde_json::from_slice::<Value>(original) else {
+            return;
+        };
+        let mut facts = self
+            .0
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if let Ok(response_id) = required_identifier(value.get("id")) {
+            facts.observe_response_id(response_id);
+        }
+        if let Some(terminal) = response_terminal(&value) {
+            facts.observe_terminal(terminal);
+        }
+    }
+
+    fn snapshot(&self) -> ExpectedResponseFacts {
+        self.0
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .clone()
+    }
+
+    pub(super) fn response_id(&self) -> Option<String> {
+        self.snapshot().response_id
+    }
+}
+
+impl ExpectedResponseFacts {
+    fn observe_wire(&mut self, wire: &ProtocolWireEvent) {
+        let event_type = wire
+            .event_type()
+            .or_else(|| wire.data().get("type").and_then(Value::as_str));
+        self.observe_wire_value(event_type, wire.data());
+        if !wire.has_json_data()
+            && let Some(raw) = wire.raw_sse_frame()
+            && let Ok(ParsedFrame::Event { event_type, value }) = ParsedFrame::parse(raw)
+        {
+            self.observe_wire_value(Some(&event_type), &value);
+        }
+    }
+
+    fn observe_wire_value(&mut self, event_type: Option<&str>, value: &Value) {
+        if event_type == Some("response.created")
+            && let Some(response_id) = value
+                .get("response")
+                .and_then(|response| response.get("id"))
+                .and_then(Value::as_str)
+        {
+            self.observe_response_id(response_id);
+        }
+        if let Some(terminal) = terminal_kind(event_type) {
+            self.observe_terminal(terminal);
+            let response = value.get("response").unwrap_or(value);
+            if let Some(response_id) = response.get("id").and_then(Value::as_str) {
+                self.observe_response_id(response_id);
+            }
+        }
+    }
+
+    fn observe_response_id(&mut self, response_id: &str) {
+        if response_id.is_empty()
+            || response_id.len() > MAX_IDENTIFIER_BYTES
+            || self
+                .response_id
+                .as_deref()
+                .is_some_and(|expected| expected != response_id)
+        {
+            self.invalid = true;
+        } else {
+            self.response_id
+                .get_or_insert_with(|| response_id.to_owned());
+        }
+    }
+
+    fn observe_terminal(&mut self, terminal: TerminalKind) {
+        if terminal == TerminalKind::Done {
+            return;
+        }
+        if self.terminal.is_some_and(|expected| expected != terminal) {
+            self.invalid = true;
+        } else {
+            self.terminal.get_or_insert(terminal);
+        }
+    }
+}
+
+/// 只复核中间件确实改写过的完整 JSON；未经改写的原生快路保持原行为。
+pub(super) fn validate_buffered_response(
+    facts: &ResponseValidationFacts,
+    modified: &[u8],
+) -> Result<(), ResponseValidationError> {
+    let expected = facts.snapshot();
+    if expected.invalid {
+        return Err(ResponseValidationError);
+    }
+    let modified =
+        serde_json::from_slice::<Value>(modified).map_err(|_| ResponseValidationError)?;
+    let response_id = required_identifier(modified.get("id"))?;
+    let terminal = response_terminal(&modified).ok_or(ResponseValidationError)?;
+    if expected
+        .response_id
+        .as_deref()
+        .is_some_and(|expected| expected != response_id)
+        || expected
+            .terminal
+            .is_some_and(|expected| expected != terminal)
+    {
+        return Err(ResponseValidationError);
+    }
+    validate_terminal_response(&modified, response_id, terminal)
+}
+
+/// 持有实际已交付给客户端的 Responses 流状态。
+///
+/// 原始前缀只旁路构建状态；直到插件首次改写或丢弃正文才启用严格拒绝，避免给
+/// 无策略原生热路增加新的兼容性条件。
+#[derive(Debug, Default)]
+pub(super) struct ResponsesDeliveryValidator {
+    active: bool,
+    invalid_prefix: bool,
+    state: DeliveryState,
+}
+
+impl ResponsesDeliveryValidator {
+    /// 复核实际交付帧；只有宿主标记为已改写时才激活严格模式。
+    pub(super) fn validate_frame(
+        &mut self,
+        delivered: &[u8],
+        transformed: bool,
+        facts: &ResponseValidationFacts,
+    ) -> Result<(), ResponseValidationError> {
+        self.validate_parsed(ParsedFrame::parse(delivered), transformed, facts)
+    }
+
+    /// WebSocket JSON message 与 SSE 共用同一响应顺序和关联校验。
+    pub(super) fn validate_websocket_frame(
+        &mut self,
+        delivered: &[u8],
+        transformed: bool,
+        facts: &ResponseValidationFacts,
+    ) -> Result<(), ResponseValidationError> {
+        self.validate_parsed(ParsedFrame::parse_json(delivered), transformed, facts)
+    }
+
+    fn validate_parsed(
+        &mut self,
+        parsed: Result<ParsedFrame, ResponseValidationError>,
+        transformed: bool,
+        facts: &ResponseValidationFacts,
+    ) -> Result<(), ResponseValidationError> {
+        if !self.active && !transformed {
+            if parsed.and_then(|frame| self.state.apply(frame)).is_err() {
+                self.invalid_prefix = true;
+            }
+            return Ok(());
+        }
+        self.activate()?;
+        let parsed = parsed?;
+        let expected = facts.snapshot();
+        if expected.invalid {
+            return Err(ResponseValidationError);
+        }
+        match &parsed {
+            ParsedFrame::Event { event_type, value } if event_type == "response.created" => {
+                let response_id = required_identifier(
+                    value
+                        .get("response")
+                        .and_then(|response| response.get("id")),
+                )?;
+                if expected
+                    .response_id
+                    .as_deref()
+                    .is_some_and(|expected| expected != response_id)
+                {
+                    return Err(ResponseValidationError);
+                }
+            }
+            ParsedFrame::Event { event_type, value }
+                if terminal_kind(Some(event_type)).is_some() =>
+            {
+                let terminal = terminal_kind(Some(event_type)).ok_or(ResponseValidationError)?;
+                let response = value.get("response").unwrap_or(value);
+                let response_id = required_identifier(response.get("id"))?;
+                if expected
+                    .response_id
+                    .as_deref()
+                    .is_some_and(|expected| expected != response_id)
+                    || expected
+                        .terminal
+                        .is_some_and(|expected| expected != terminal)
+                {
+                    return Err(ResponseValidationError);
+                }
+            }
+            ParsedFrame::Event { .. } | ParsedFrame::Done => {}
+        }
+        self.state.apply(parsed)
+    }
+
+    pub(super) fn response_id(&self) -> Option<&str> {
+        self.state.response_id.as_deref()
+    }
+
+    pub(super) fn finish_delivery(&self) -> Result<(), ResponseValidationError> {
+        if !self.active || self.state.done {
+            Ok(())
+        } else {
+            Err(ResponseValidationError)
+        }
+    }
+
+    pub(super) fn finish_websocket_delivery(&self) -> Result<(), ResponseValidationError> {
+        if !self.active || self.state.terminal.is_some() {
+            Ok(())
+        } else {
+            Err(ResponseValidationError)
+        }
+    }
+
+    fn activate(&mut self) -> Result<(), ResponseValidationError> {
+        self.active = true;
+        if self.invalid_prefix {
+            Err(ResponseValidationError)
+        } else {
+            Ok(())
+        }
+    }
+}
+
+#[derive(Debug)]
+enum ParsedFrame {
+    Event { event_type: String, value: Value },
+    Done,
+}
+
+impl ParsedFrame {
+    fn parse(bytes: &[u8]) -> Result<Self, ResponseValidationError> {
+        let frame = std::str::from_utf8(bytes).map_err(|_| ResponseValidationError)?;
+        if sse_frame_is_done(frame) {
+            return Ok(Self::Done);
+        }
+        let mut events = parse_sse_events(frame).map_err(|_| ResponseValidationError)?;
+        if events.len() != 1 {
+            return Err(ResponseValidationError);
+        }
+        let event = events.pop().ok_or(ResponseValidationError)?;
+        let value =
+            serde_json::from_str::<Value>(&event.data).map_err(|_| ResponseValidationError)?;
+        let json_type = value.get("type").and_then(Value::as_str);
+        if let (Some(sse_type), Some(json_type)) = (event.event.as_deref(), json_type)
+            && sse_type != json_type
+        {
+            return Err(ResponseValidationError);
+        }
+        let event_type = event
+            .event
+            .or_else(|| json_type.map(ToOwned::to_owned))
+            .filter(|value| !value.is_empty() && value.len() <= MAX_IDENTIFIER_BYTES)
+            .ok_or(ResponseValidationError)?;
+        if !value.is_object() {
+            return Err(ResponseValidationError);
+        }
+        Ok(Self::Event { event_type, value })
+    }
+
+    fn parse_json(bytes: &[u8]) -> Result<Self, ResponseValidationError> {
+        let value = serde_json::from_slice::<Value>(bytes).map_err(|_| ResponseValidationError)?;
+        let event_type = required_identifier(value.get("type"))?.to_owned();
+        if !value.is_object() {
+            return Err(ResponseValidationError);
+        }
+        Ok(Self::Event { event_type, value })
+    }
+}
+
+fn terminal_kind(event_type: Option<&str>) -> Option<TerminalKind> {
+    match event_type {
+        Some("response.completed") => Some(TerminalKind::Completed),
+        Some("response.incomplete") => Some(TerminalKind::Incomplete),
+        Some("response.failed" | "error") => Some(TerminalKind::Failed),
+        _ => None,
+    }
+}
+
+fn response_terminal(response: &Value) -> Option<TerminalKind> {
+    match response.get("status").and_then(Value::as_str) {
+        Some("completed") => Some(TerminalKind::Completed),
+        Some("incomplete") => Some(TerminalKind::Incomplete),
+        Some("failed") => Some(TerminalKind::Failed),
+        _ => None,
+    }
+}
+
+#[derive(Debug, Default)]
+struct DeliveryState {
+    response_id: Option<String>,
+    terminal: Option<TerminalKind>,
+    done: bool,
+    output_items: BTreeMap<u32, OutputItem>,
+    content_parts: BTreeSet<(u32, u32)>,
+}
+
+impl DeliveryState {
+    fn apply(&mut self, frame: ParsedFrame) -> Result<(), ResponseValidationError> {
+        if self.done {
+            return Err(ResponseValidationError);
+        }
+        let ParsedFrame::Event { event_type, value } = frame else {
+            if self.terminal.is_none() {
+                return Err(ResponseValidationError);
+            }
+            self.done = true;
+            return Ok(());
+        };
+        match event_type.as_str() {
+            "response.created" => self.start(&value),
+            "response.in_progress" | "response.queued" => self.progress(&value),
+            "response.output_item.added" => self.output_item(&value, false),
+            "response.output_item.done" => self.output_item(&value, true),
+            "response.content_part.added"
+            | "response.reasoning_summary_part.added"
+            | "response.reasoning_part.added" => self.content_part(&value, false),
+            "response.content_part.done"
+            | "response.reasoning_summary_part.done"
+            | "response.reasoning_part.done" => self.content_part(&value, true),
+            "response.output_text.delta"
+            | "response.output_text.done"
+            | "response.refusal.delta"
+            | "response.refusal.done"
+            | "response.reasoning_summary_text.delta"
+            | "response.reasoning_summary_text.done"
+            | "response.reasoning_text.delta"
+            | "response.reasoning_text.done" => self.content_event(&value),
+            "response.function_call_arguments.delta" | "response.custom_tool_call_input.delta" => {
+                self.tool_arguments(&event_type, &value, false)
+            }
+            "response.function_call_arguments.done" | "response.custom_tool_call_input.done" => {
+                self.tool_arguments(&event_type, &value, true)
+            }
+            "response.completed" | "response.incomplete" | "response.failed" | "error" => {
+                self.finish_response(&event_type, &value)
+            }
+            _ => Ok(()),
+        }
+    }
+
+    fn start(&mut self, value: &Value) -> Result<(), ResponseValidationError> {
+        if self.response_id.is_some() || self.terminal.is_some() {
+            return Err(ResponseValidationError);
+        }
+        let response = required_object(value.get("response"))?;
+        let response_id = required_identifier(response.get("id"))?;
+        if let Some(status) = response.get("status") {
+            let status = required_identifier(Some(status))?;
+            if !matches!(status, "queued" | "in_progress") {
+                return Err(ResponseValidationError);
+            }
+        }
+        self.response_id = Some(response_id.to_owned());
+        Ok(())
+    }
+
+    fn progress(&self, value: &Value) -> Result<(), ResponseValidationError> {
+        self.require_active()?;
+        if let Some(response) = value.get("response") {
+            let response = required_object(Some(response))?;
+            self.validate_response_id(response.get("id"))?;
+        }
+        Ok(())
+    }
+
+    fn output_item(&mut self, value: &Value, done: bool) -> Result<(), ResponseValidationError> {
+        self.require_active()?;
+        self.validate_optional_event_response_id(value)?;
+        let index = required_index(value, "output_index")?;
+        let identity = OutputItemIdentity::parse(required_object(value.get("item"))?)?;
+        if let Some(existing) = self.output_items.get_mut(&index) {
+            if !done || existing.done || existing.identity != identity {
+                return Err(ResponseValidationError);
+            }
+            existing.done = true;
+            return Ok(());
+        }
+        if self.output_items.len() >= MAX_TRACKED_OUTPUT_ITEMS
+            || self.output_items.values().any(|existing| {
+                !identity.id.is_empty() && existing.identity.id == identity.id
+                    || existing.identity.call_id.is_some()
+                        && existing.identity.call_id == identity.call_id
+            })
+        {
+            return Err(ResponseValidationError);
+        }
+        self.output_items.insert(
+            index,
+            OutputItem {
+                identity,
+                done,
+                arguments_done: false,
+            },
+        );
+        Ok(())
+    }
+
+    fn content_part(&mut self, value: &Value, done: bool) -> Result<(), ResponseValidationError> {
+        self.require_active()?;
+        self.validate_optional_event_response_id(value)?;
+        let output_index = required_index(value, "output_index")?;
+        if !self.output_items.contains_key(&output_index) {
+            return Err(ResponseValidationError);
+        }
+        let content_index = required_index(value, "content_index")?;
+        let key = (output_index, content_index);
+        if done {
+            if !self.content_parts.remove(&key) {
+                return Err(ResponseValidationError);
+            }
+        } else if self.content_parts.len() >= MAX_TRACKED_OUTPUT_ITEMS
+            || !self.content_parts.insert(key)
+        {
+            return Err(ResponseValidationError);
+        }
+        Ok(())
+    }
+
+    fn content_event(&self, value: &Value) -> Result<(), ResponseValidationError> {
+        self.require_active()?;
+        self.validate_optional_event_response_id(value)?;
+        let key = (
+            required_index(value, "output_index")?,
+            required_index(value, "content_index")?,
+        );
+        if !self.content_parts.contains(&key) {
+            return Err(ResponseValidationError);
+        }
+        Ok(())
+    }
+
+    fn tool_arguments(
+        &mut self,
+        event_type: &str,
+        value: &Value,
+        done: bool,
+    ) -> Result<(), ResponseValidationError> {
+        self.require_active()?;
+        self.validate_optional_event_response_id(value)?;
+        let output_index = required_index(value, "output_index")?;
+        let item = self
+            .output_items
+            .get_mut(&output_index)
+            .ok_or(ResponseValidationError)?;
+        let expected_type = if event_type.starts_with("response.function_call") {
+            "function_call"
+        } else {
+            "custom_tool_call"
+        };
+        if item.identity.kind != expected_type
+            || value.get("item_id").is_some_and(|id| {
+                required_identifier(Some(id)).ok() != Some(item.identity.id.as_str())
+            })
+            || value.get("call_id").is_some_and(|call_id| {
+                required_identifier(Some(call_id)).ok() != item.identity.call_id.as_deref()
+            })
+            || done && item.arguments_done
+        {
+            return Err(ResponseValidationError);
+        }
+        item.arguments_done |= done;
+        Ok(())
+    }
+
+    fn finish_response(
+        &mut self,
+        event_type: &str,
+        value: &Value,
+    ) -> Result<(), ResponseValidationError> {
+        self.require_active()?;
+        if self.terminal.is_some() {
+            return Err(ResponseValidationError);
+        }
+        let terminal = terminal_kind(Some(event_type)).ok_or(ResponseValidationError)?;
+        let response = value
+            .get("response")
+            .or_else(|| (event_type == "error").then_some(value))
+            .ok_or(ResponseValidationError)?;
+        let expected_id = self.response_id.as_deref().ok_or(ResponseValidationError)?;
+        validate_terminal_response(response, expected_id, terminal)?;
+        self.terminal = Some(terminal);
+        Ok(())
+    }
+
+    fn require_active(&self) -> Result<(), ResponseValidationError> {
+        if self.response_id.is_some() && self.terminal.is_none() {
+            Ok(())
+        } else {
+            Err(ResponseValidationError)
+        }
+    }
+
+    fn validate_response_id(&self, value: Option<&Value>) -> Result<(), ResponseValidationError> {
+        if required_identifier(value)?
+            == self.response_id.as_deref().ok_or(ResponseValidationError)?
+        {
+            Ok(())
+        } else {
+            Err(ResponseValidationError)
+        }
+    }
+
+    fn validate_optional_event_response_id(
+        &self,
+        value: &Value,
+    ) -> Result<(), ResponseValidationError> {
+        if let Some(response_id) = value.get("response_id") {
+            self.validate_response_id(Some(response_id))?;
+        }
+        Ok(())
+    }
+}
+
+#[derive(Debug)]
+struct OutputItem {
+    identity: OutputItemIdentity,
+    done: bool,
+    arguments_done: bool,
+}
+
+#[derive(Debug, PartialEq, Eq)]
+struct OutputItemIdentity {
+    id: String,
+    kind: String,
+    call_id: Option<String>,
+}
+
+impl OutputItemIdentity {
+    fn parse(item: &Map<String, Value>) -> Result<Self, ResponseValidationError> {
+        let kind = required_identifier(item.get("type"))?;
+        let known_item = matches!(
+            kind,
+            "message"
+                | "reasoning"
+                | "function_call"
+                | "custom_tool_call"
+                | "image_generation_call"
+                | "computer_call"
+                | "web_search_call"
+        );
+        let id = item
+            .get("id")
+            .map(|value| required_identifier(Some(value)))
+            .transpose()?
+            .unwrap_or("");
+        if known_item && id.is_empty() {
+            return Err(ResponseValidationError);
+        }
+        let call_id = item
+            .get("call_id")
+            .map(|value| required_identifier(Some(value)).map(ToOwned::to_owned))
+            .transpose()?;
+        if matches!(kind, "function_call" | "custom_tool_call")
+            && (call_id.is_none() || required_identifier(item.get("name")).is_err())
+        {
+            return Err(ResponseValidationError);
+        }
+        Ok(Self {
+            id: id.to_owned(),
+            kind: kind.to_owned(),
+            call_id,
+        })
+    }
+}
+
+fn validate_terminal_response(
+    response: &Value,
+    expected_id: &str,
+    terminal: TerminalKind,
+) -> Result<(), ResponseValidationError> {
+    let response = required_object(Some(response))?;
+    if required_identifier(response.get("id"))? != expected_id {
+        return Err(ResponseValidationError);
+    }
+    let expected_status = match terminal {
+        TerminalKind::Completed => "completed",
+        TerminalKind::Incomplete => "incomplete",
+        TerminalKind::Failed => "failed",
+        TerminalKind::Done => return Err(ResponseValidationError),
+    };
+    if required_identifier(response.get("status"))? != expected_status {
+        return Err(ResponseValidationError);
+    }
+    if terminal == TerminalKind::Failed {
+        if !response.get("error").is_some_and(Value::is_object) {
+            return Err(ResponseValidationError);
+        }
+        return Ok(());
+    }
+    let output = response
+        .get("output")
+        .and_then(Value::as_array)
+        .ok_or(ResponseValidationError)?;
+    if output.len() > MAX_TRACKED_OUTPUT_ITEMS {
+        return Err(ResponseValidationError);
+    }
+    let mut ids = BTreeSet::new();
+    let mut call_ids = BTreeSet::new();
+    for item in output {
+        let identity = OutputItemIdentity::parse(required_object(Some(item))?)?;
+        if (!identity.id.is_empty() && !ids.insert(identity.id))
+            || identity
+                .call_id
+                .is_some_and(|call_id| !call_ids.insert(call_id))
+        {
+            return Err(ResponseValidationError);
+        }
+    }
+    Ok(())
+}
+
+fn required_object(value: Option<&Value>) -> Result<&Map<String, Value>, ResponseValidationError> {
+    value
+        .and_then(Value::as_object)
+        .ok_or(ResponseValidationError)
+}
+
+fn required_identifier(value: Option<&Value>) -> Result<&str, ResponseValidationError> {
+    value
+        .and_then(Value::as_str)
+        .filter(|value| !value.is_empty() && value.len() <= MAX_IDENTIFIER_BYTES)
+        .ok_or(ResponseValidationError)
+}
+
+fn required_index(value: &Value, name: &str) -> Result<u32, ResponseValidationError> {
+    value
+        .get(name)
+        .and_then(Value::as_u64)
+        .and_then(|value| u32::try_from(value).ok())
+        .ok_or(ResponseValidationError)
+}
diff --git a/backend/crates/gateway-api/src/openai/responses/websocket/forward.rs b/backend/crates/gateway-api/src/openai/responses/websocket/forward.rs
index f472cafc7..c1f14fd3c 100644
--- a/backend/crates/gateway-api/src/openai/responses/websocket/forward.rs
+++ b/backend/crates/gateway-api/src/openai/responses/websocket/forward.rs
@@ -1,18 +1,27 @@
-//! 已启动 Responses execution 到客户端 WebSocket wire event 的串行转发。
+//! Responses WebSocket 洋葱响应体与串行 transport 交付。
 
-use std::sync::Arc;
+use std::collections::VecDeque;
+use std::sync::{Arc, Mutex};
 
 use axum::http::StatusCode;
-use gateway_core::engine::execution::StartedExecution;
-use gateway_core::engine::{CommitRequirement, CoordinatedEvent, EngineError};
+use bytes::Bytes;
+use futures::future::BoxFuture;
+use gateway_core::engine::CommitRequirement;
+use gateway_core::engine::execution::{ExecutionSession, StartedExecution};
+use gateway_core::engine::middleware::{
+    MiddlewareBody, MiddlewareError, MiddlewareFrame, MiddlewareFraming, MiddlewareHeader,
+    MiddlewareResponse,
+};
 use gateway_core::error::{GatewayError, GatewayErrorKind};
+use gateway_core::event::ProviderResponseHeader;
 use gateway_core::operation::ProviderSessionState;
-use tokio::time::Instant;
 
 use crate::openai::error::{gateway_error_contract, gateway_error_from_engine};
+use crate::openai::middleware::PendingExecution;
+use crate::openai::responses::validation::{ResponseValidationFacts, ResponsesDeliveryValidator};
 
 use super::{
-    super::{DecodedResponsesRequest, OpenAiResponsesEncoder, PendingExecution, ProtocolErrorBody},
+    super::{DecodedResponsesRequest, OpenAiResponsesEncoder, ProtocolErrorBody},
     connection::{FramePhase, ResponsesWebSocketConnection, WriteContext},
     protocol::{error_event, initial_engine_error_event, response_metadata_event},
 };
@@ -23,7 +32,7 @@ pub(super) enum ForwardOutcome {
     Disconnect,
 }
 
-#[derive(Default)]
+#[derive(Clone, Default)]
 pub(super) struct ConnectionReplaySnapshot {
     last_response_id: Option<String>,
     provider_state: Option<ProviderSessionState>,
@@ -49,99 +58,129 @@ impl ConnectionReplaySnapshot {
     }
 }
 
-pub(super) async fn forward_execution(
-    connection: &mut ResponsesWebSocketConnection,
+#[derive(Default)]
+pub(super) struct ReplayCapture {
+    response_id: Option<String>,
+    provider_state: Option<ProviderSessionState>,
+}
+
+pub(super) type ReplayCaptureHandle = Arc<Mutex<ReplayCapture>>;
+
+pub(super) fn new_replay_capture() -> ReplayCaptureHandle {
+    Arc::new(Mutex::new(ReplayCapture::default()))
+}
+
+pub(super) async fn execution_response(
     started: StartedExecution,
-    replay: &mut ConnectionReplaySnapshot,
-) -> ForwardOutcome {
+    capture: ReplayCaptureHandle,
+    validation: ResponseValidationFacts,
+) -> Result<MiddlewareResponse, MiddlewareError> {
+    if !started.stream {
+        return Err(MiddlewareError::InvalidState);
+    }
     let request_id = Arc::<str>::from(started.request_id.to_string());
-    let streaming = started.stream;
-    let mut execution = PendingExecution::new(started.session);
-    if !streaming {
-        let error = GatewayError::new(
-            GatewayErrorKind::Internal,
-            "WebSocket execution was not initialized as a stream",
-        );
-        return send_gateway_error(connection, &error, &request_id).await;
-    }
-    let first = match next_active_input(connection, &mut execution).await {
-        ActiveInput::Event(Ok(Some(event))) => event,
-        ActiveInput::Event(Ok(None)) => {
-            let error = GatewayError::new(
-                GatewayErrorKind::Internal,
-                "gateway response ended before its first event",
-            );
-            return send_gateway_error(connection, &error, &request_id).await;
+    let mut body = WebSocketExecutionBody::new(
+        started.session,
+        Arc::clone(&request_id),
+        Arc::clone(&capture),
+        validation,
+    );
+    if let Err(error) = body.prime().await {
+        let headers = body.response_headers().to_vec();
+        let status = middleware_error_status(&error);
+        let _ = body.record_client_status(status).await;
+        Box::new(body).close().await;
+        if let MiddlewareError::Engine(error) = error {
+            let response_headers = headers
+                .iter()
+                .map(|header| MiddlewareHeader::new(header.name(), header.value().clone()))
+                .collect();
+            return Ok(MiddlewareResponse::new(
+                "openai".to_owned(),
+                status,
+                response_headers,
+                Box::new(SingleFrameBody(Some(MiddlewareFrame::new(
+                    Bytes::from(initial_engine_error_event(
+                        &error,
+                        request_id.as_ref(),
+                        &headers,
+                    )),
+                    MiddlewareFraming::JsonDocument,
+                    true,
+                )))),
+            ));
         }
-        ActiveInput::Event(Err(error)) => {
-            return send_initial_engine_error(connection, &mut execution, &error, &request_id)
-                .await;
+        return Err(error);
+    }
+    let headers = body
+        .response_headers()
+        .iter()
+        .map(|header| MiddlewareHeader::new(header.name(), header.value().clone()))
+        .collect();
+    Ok(MiddlewareResponse::new(
+        "openai".to_owned(),
+        200,
+        headers,
+        Box::new(body),
+    ))
+}
+
+struct SingleFrameBody(Option<MiddlewareFrame>);
+
+impl MiddlewareBody for SingleFrameBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async { Ok(self.0.take()) })
+    }
+
+    fn close(self: Box<Self>) -> BoxFuture<'static, ()> {
+        Box::pin(async move { drop(self) })
+    }
+}
+
+pub(super) async fn forward_response(
+    connection: &mut ResponsesWebSocketConnection,
+    response: MiddlewareResponse,
+    request_id: Arc<str>,
+    replay: &mut ConnectionReplaySnapshot,
+    capture: ReplayCaptureHandle,
+    validation: ResponseValidationFacts,
+) -> ForwardOutcome {
+    let (protocol, status, headers, mut body, _) = response.into_parts();
+    if protocol != "openai" || StatusCode::from_u16(status).is_err() {
+        return fail_body(connection, body, MiddlewareError::InvalidState, &request_id).await;
+    }
+    let response_headers = headers
+        .into_iter()
+        .map(|header| {
+            let (name, value) = header.into_parts();
+            ProviderResponseHeader::new(name, value)
+        })
+        .collect::<Vec<_>>();
+    let first = match next_body_input(connection, body.as_mut()).await {
+        BodyInput::Frame(Ok(Some(frame))) => frame,
+        BodyInput::Frame(Ok(None)) => {
+            return fail_body(connection, body, MiddlewareError::InvalidState, &request_id).await;
         }
-        ActiveInput::Disconnect => return ForwardOutcome::Disconnect,
-    };
-    let requirement = first.commit_requirement();
-    let mut first = first.into_provider_events();
-    if requirement != CommitRequirement::CommitBeforeDelivery {
-        let error = GatewayError::new(
-            GatewayErrorKind::Internal,
-            "gateway first event did not require commit",
-        );
-        return send_gateway_error(connection, &error, &request_id).await;
-    }
-    let mut encoder = OpenAiResponsesEncoder::new();
-    let mut provider_state = None;
-    let mut first_messages = Vec::new();
-    for event in &mut first {
-        if let Some(update) = event.take_session_update() {
-            provider_state = Some(update);
+        BodyInput::Frame(Err(error)) => {
+            return fail_body(connection, body, error, &request_id).await;
         }
-        first_messages.extend(encoder.push_websocket(event));
-    }
-    if first_messages.is_empty() {
-        let error = GatewayError::new(
-            GatewayErrorKind::Internal,
-            "gateway commit batch encoded no output",
-        );
-        return send_gateway_error(connection, &error, &request_id).await;
-    }
-    let Some(response_session) = execution.session_mut() else {
-        return ForwardOutcome::Disconnect;
-    };
-    let response_headers = response_session.response_headers().to_vec();
-    if let Err(error) = response_session.commit_downstream(None).await {
-        let error = gateway_error_from_engine(&error);
-        return send_gateway_error(connection, &error, &request_id).await;
-    }
-    let mut first_frame_written = false;
-    if encoder.is_completed() {
-        if let Err(outcome) =
-            confirm_completed_execution(connection, &mut execution, &request_id).await
-        {
-            return outcome;
-        }
-        let provider_terminal_at = Instant::now();
-        commit_connection_replay(replay, &encoder, provider_state.take());
-        let writes_succeeded = send_metadata(
-            connection,
-            &request_id,
-            response_metadata_event(&request_id, &response_headers),
-        )
-        .await
-            && send_messages(
-                connection,
-                first_messages,
-                &request_id,
-                &mut first_frame_written,
-                true,
-            )
-            .await;
-        if !writes_succeeded {
-            log_terminal_write_failure(connection, &request_id, provider_terminal_at.elapsed());
+        BodyInput::Disconnect => {
+            detach_body(body);
             return ForwardOutcome::Disconnect;
         }
-        log_terminal_write_success(connection, &request_id, provider_terminal_at.elapsed());
-        execution.disarm();
-        return ForwardOutcome::Continue;
+    };
+    if let Err(error) = validate_frame(&first) {
+        return fail_body(connection, body, error, &request_id).await;
+    }
+    let mut delivery_validator = ResponsesDeliveryValidator::default();
+    if delivery_validator
+        .validate_websocket_frame(first.bytes(), first.transformed(), &validation)
+        .is_err()
+    {
+        return fail_body(connection, body, MiddlewareError::InvalidState, &request_id).await;
+    }
+    if let Err(error) = body.commit_downstream(None).await {
+        return fail_body(connection, body, error, &request_id).await;
     }
     if !send_metadata(
         connection,
@@ -149,206 +188,406 @@ pub(super) async fn forward_execution(
         response_metadata_event(&request_id, &response_headers),
     )
     .await
-        || !send_messages(
-            connection,
-            first_messages,
-            &request_id,
-            &mut first_frame_written,
-            encoder.has_wire_failure(),
-        )
-        .await
     {
+        detach_body(body);
         return ForwardOutcome::Disconnect;
     }
 
+    let mut first_frame_written = false;
+    let mut current = Some(first);
+    let mut terminal_seen = false;
+    let mut first_protocol_validated = true;
     loop {
-        match next_active_input(connection, &mut execution).await {
-            ActiveInput::Event(Ok(Some(delivery))) => {
-                let requirement = delivery.commit_requirement();
-                let mut events = delivery.into_provider_events();
-                if requirement != CommitRequirement::AlreadyCommitted {
-                    let error = GatewayError::new(
-                        GatewayErrorKind::Internal,
-                        "gateway requested another downstream commit",
-                    );
-                    return send_gateway_error(connection, &error, &request_id).await;
-                }
-                let mut messages = Vec::new();
-                for event in &mut events {
-                    if let Some(update) = event.take_session_update() {
-                        provider_state = Some(update);
-                    }
-                    messages.extend(encoder.push_websocket(event));
-                }
-                if encoder.is_completed() {
-                    if let Err(outcome) =
-                        confirm_completed_execution(connection, &mut execution, &request_id).await
-                    {
-                        return outcome;
-                    }
-                    let provider_terminal_at = Instant::now();
-                    commit_connection_replay(replay, &encoder, provider_state.take());
-                    if !send_messages(
-                        connection,
-                        messages,
-                        &request_id,
-                        &mut first_frame_written,
-                        true,
-                    )
-                    .await
-                    {
-                        log_terminal_write_failure(
+        let frame = match current.take() {
+            Some(frame) => frame,
+            None => match next_body_input(connection, body.as_mut()).await {
+                BodyInput::Frame(Ok(Some(frame))) => frame,
+                BodyInput::Frame(Ok(None)) if terminal_seen && body.is_finalized() => {
+                    if delivery_validator.finish_websocket_delivery().is_err() {
+                        return fail_body(
                             connection,
+                            body,
+                            MiddlewareError::InvalidState,
                             &request_id,
-                            provider_terminal_at.elapsed(),
-                        );
-                        return ForwardOutcome::Disconnect;
+                        )
+                        .await;
                     }
-                    log_terminal_write_success(
-                        connection,
-                        &request_id,
-                        provider_terminal_at.elapsed(),
-                    );
-                    execution.disarm();
+                    {
+                        let captured = capture
+                            .lock()
+                            .unwrap_or_else(std::sync::PoisonError::into_inner);
+                        if let Some(response_id) = captured.response_id.clone() {
+                            replay.commit(response_id, captured.provider_state.clone());
+                        }
+                    }
+                    body.close().await;
                     return ForwardOutcome::Continue;
                 }
-                let terminal_batch = encoder.has_wire_failure();
-                if !send_messages(
-                    connection,
-                    messages,
-                    &request_id,
-                    &mut first_frame_written,
-                    terminal_batch,
-                )
-                .await
-                {
+                BodyInput::Frame(Ok(None)) => {
+                    return fail_body(connection, body, MiddlewareError::InvalidState, &request_id)
+                        .await;
+                }
+                BodyInput::Frame(Err(error)) => {
+                    return fail_body(connection, body, error, &request_id).await;
+                }
+                BodyInput::Disconnect => {
+                    detach_body(body);
                     return ForwardOutcome::Disconnect;
                 }
-            }
-            ActiveInput::Event(Ok(None)) => {
-                if execution
-                    .session_mut()
-                    .is_some_and(|session| session.is_finalized())
-                {
-                    commit_connection_replay(replay, &encoder, provider_state.take());
-                    execution.disarm();
-                    return ForwardOutcome::Continue;
-                }
-                let error = GatewayError::new(
-                    GatewayErrorKind::Internal,
-                    "gateway response ended without finalizing the execution",
-                );
-                return send_gateway_error(connection, &error, &request_id).await;
-            }
-            ActiveInput::Event(Err(error)) => {
-                if encoder.has_wire_failure() {
-                    execution.disarm();
-                    return ForwardOutcome::Continue;
-                }
-                let error = gateway_error_from_engine(&error);
-                return send_gateway_error(connection, &error, &request_id).await;
-            }
-            ActiveInput::Disconnect => return ForwardOutcome::Disconnect,
+            },
+        };
+        if terminal_seen || validate_frame(&frame).is_err() {
+            return fail_body(connection, body, MiddlewareError::InvalidState, &request_id).await;
         }
-    }
-}
-
-async fn send_initial_engine_error(
-    connection: &mut ResponsesWebSocketConnection,
-    execution: &mut PendingExecution,
-    error: &EngineError,
-    request_id: &Arc<str>,
-) -> ForwardOutcome {
-    let response_headers = execution
-        .session_mut()
-        .map(|session| session.response_headers().to_vec())
-        .unwrap_or_default();
-    if !response_headers.is_empty()
-        && !send_metadata(
-            connection,
-            request_id,
-            response_metadata_event(request_id, &response_headers),
-        )
-        .await
-    {
-        return ForwardOutcome::Disconnect;
-    }
-    send_error_message(
-        connection,
-        initial_engine_error_event(error, request_id, &response_headers),
-        request_id,
-    )
-    .await
-}
-
-fn commit_connection_replay(
-    replay: &mut ConnectionReplaySnapshot,
-    encoder: &OpenAiResponsesEncoder,
-    provider_state: Option<ProviderSessionState>,
-) {
-    if let Some(response_id) = encoder.response_id() {
-        replay.commit(response_id.to_owned(), provider_state);
-    }
-}
-
-async fn confirm_completed_execution(
-    connection: &mut ResponsesWebSocketConnection,
-    execution: &mut PendingExecution,
-    request_id: &Arc<str>,
-) -> Result<(), ForwardOutcome> {
-    match next_active_input(connection, execution).await {
-        ActiveInput::Event(Ok(None))
-            if execution
-                .session_mut()
-                .is_some_and(|session| session.is_finalized()) =>
+        if first_protocol_validated {
+            first_protocol_validated = false;
+        } else if delivery_validator
+            .validate_websocket_frame(frame.bytes(), frame.transformed(), &validation)
+            .is_err()
         {
-            Ok(())
+            return fail_body(connection, body, MiddlewareError::InvalidState, &request_id).await;
         }
-        ActiveInput::Event(Ok(None)) => {
-            let error = GatewayError::new(
-                GatewayErrorKind::Internal,
-                "gateway response was not finalized after its terminal event",
-            );
-            Err(send_gateway_error(connection, &error, request_id).await)
+        let terminal = frame.terminal();
+        let Ok(message) = String::from_utf8(frame.into_bytes().to_vec()) else {
+            return fail_body(connection, body, MiddlewareError::InvalidState, &request_id).await;
+        };
+        let phase = match (first_frame_written, terminal) {
+            (false, true) => FramePhase::FirstAndTerminal,
+            (false, false) => FramePhase::First,
+            (true, true) => FramePhase::Terminal,
+            (true, false) => FramePhase::Data,
+        };
+        if connection
+            .send_text(message, WriteContext::request(&request_id, phase))
+            .await
+            .is_err()
+        {
+            detach_body(body);
+            return ForwardOutcome::Disconnect;
         }
-        ActiveInput::Event(Ok(Some(_))) => {
-            let error = GatewayError::new(
-                GatewayErrorKind::Internal,
-                "gateway response continued after its terminal event",
-            );
-            Err(send_gateway_error(connection, &error, request_id).await)
-        }
-        ActiveInput::Event(Err(error)) => {
-            let error = gateway_error_from_engine(&error);
-            Err(send_gateway_error(connection, &error, request_id).await)
-        }
-        ActiveInput::Disconnect => Err(ForwardOutcome::Disconnect),
+        first_frame_written = true;
+        terminal_seen = terminal;
     }
 }
 
-enum ActiveInput {
-    Event(Result<Option<CoordinatedEvent>, EngineError>),
+fn detach_body(body: Box<dyn MiddlewareBody>) {
+    // 客户端已离线时不能让连接 handler 等待可能仍在结算的请求；close future
+    // 继续持有唯一正文和执行守卫，保证已启动的费用与租约清理不会被取消。
+    drop(tokio::spawn(body.close()));
+}
+
+fn validate_frame(frame: &MiddlewareFrame) -> Result<(), MiddlewareError> {
+    if frame.framing() != MiddlewareFraming::JsonDocument
+        || serde_json::from_slice::<serde::de::IgnoredAny>(frame.bytes()).is_err()
+    {
+        return Err(MiddlewareError::InvalidState);
+    }
+    Ok(())
+}
+
+enum BodyInput {
+    Frame(Result<Option<MiddlewareFrame>, MiddlewareError>),
     Disconnect,
 }
 
-async fn next_active_input(
+async fn next_body_input(
     connection: &mut ResponsesWebSocketConnection,
-    execution: &mut PendingExecution,
-) -> ActiveInput {
-    let Some(session) = execution.session_mut() else {
-        return ActiveInput::Disconnect;
-    };
-    // 与 Codex stream_request 的连接锁一致：本轮结束前不消费下一条请求。
-    // pump 继续接收有界业务帧和处理 Ping/Pong；退出通过独立通知取消本轮。
+    body: &mut dyn MiddlewareBody,
+) -> BodyInput {
     tokio::select! {
         biased;
-        _ = connection.wait_for_exit() => {
-            session.trace().record("downstream.cancelled", serde_json::json!({
-                "reason": "websocket_connection_exit", "connectionId": connection.id(),
-            }));
-            ActiveInput::Disconnect
-        },
-        event = session.next_event() => ActiveInput::Event(event),
+        _ = connection.wait_for_exit() => BodyInput::Disconnect,
+        frame = body.next_frame() => BodyInput::Frame(frame),
+    }
+}
+
+async fn fail_body(
+    connection: &mut ResponsesWebSocketConnection,
+    mut body: Box<dyn MiddlewareBody>,
+    error: MiddlewareError,
+    request_id: &Arc<str>,
+) -> ForwardOutcome {
+    let gateway = middleware_gateway_error(error);
+    let _ = body
+        .record_client_status(gateway_error_contract(gateway.kind()).0.as_u16())
+        .await;
+    body.close().await;
+    send_gateway_error(connection, &gateway, request_id).await
+}
+
+fn middleware_gateway_error(error: MiddlewareError) -> GatewayError {
+    match error {
+        MiddlewareError::Gateway(error) => error,
+        MiddlewareError::Engine(error) => gateway_error_from_engine(&error),
+        MiddlewareError::Provider(error) => GatewayError::from_provider(&error),
+        MiddlewareError::Rejected => GatewayError::new(
+            GatewayErrorKind::PolicyDenied,
+            "request middleware rejected the request",
+        ),
+        MiddlewareError::Fault | MiddlewareError::InvalidState => GatewayError::new(
+            GatewayErrorKind::Internal,
+            "request middleware returned an invalid response",
+        ),
+    }
+}
+
+fn middleware_error_status(error: &MiddlewareError) -> u16 {
+    match error {
+        MiddlewareError::Gateway(error) => gateway_error_contract(error.kind()).0.as_u16(),
+        MiddlewareError::Engine(error) => {
+            gateway_error_contract(gateway_error_from_engine(error).kind())
+                .0
+                .as_u16()
+        }
+        MiddlewareError::Provider(error) => {
+            gateway_error_contract(GatewayError::from_provider(error).kind())
+                .0
+                .as_u16()
+        }
+        MiddlewareError::Rejected => StatusCode::FORBIDDEN.as_u16(),
+        MiddlewareError::Fault | MiddlewareError::InvalidState => {
+            StatusCode::INTERNAL_SERVER_ERROR.as_u16()
+        }
+    }
+}
+
+pub(super) async fn send_middleware_error(
+    connection: &mut ResponsesWebSocketConnection,
+    error: MiddlewareError,
+    request_id: &Arc<str>,
+) -> ForwardOutcome {
+    send_gateway_error(connection, &middleware_gateway_error(error), request_id).await
+}
+
+struct WebSocketExecutionBody {
+    execution: PendingExecution,
+    encoder: OpenAiResponsesEncoder,
+    validation: ResponseValidationFacts,
+    pending: VecDeque<MiddlewareFrame>,
+    provider_state: Option<ProviderSessionState>,
+    request_id: Arc<str>,
+    capture: ReplayCaptureHandle,
+    batch_pending: bool,
+    transformed_pending: bool,
+    awaiting_terminal_eof: bool,
+    committed: bool,
+    finished: bool,
+}
+
+impl WebSocketExecutionBody {
+    fn new(
+        session: Box<dyn ExecutionSession>,
+        request_id: Arc<str>,
+        capture: ReplayCaptureHandle,
+        validation: ResponseValidationFacts,
+    ) -> Self {
+        Self {
+            execution: PendingExecution::new(session),
+            encoder: OpenAiResponsesEncoder::new(),
+            validation,
+            pending: VecDeque::new(),
+            provider_state: None,
+            request_id,
+            capture,
+            batch_pending: false,
+            transformed_pending: false,
+            awaiting_terminal_eof: false,
+            committed: false,
+            finished: false,
+        }
+    }
+
+    async fn prime(&mut self) -> Result<(), MiddlewareError> {
+        self.fill_pending().await?;
+        if self.pending.is_empty() {
+            return Err(MiddlewareError::InvalidState);
+        }
+        Ok(())
+    }
+
+    fn response_headers(&mut self) -> &[ProviderResponseHeader] {
+        self.execution
+            .session_mut()
+            .map_or(&[], |session| session.response_headers())
+    }
+
+    async fn fill_pending(&mut self) -> Result<(), MiddlewareError> {
+        while self.pending.is_empty() && !self.finished {
+            if self.awaiting_terminal_eof {
+                if !self.committed {
+                    return Err(MiddlewareError::InvalidState);
+                }
+                let result = self
+                    .execution
+                    .session_mut()
+                    .ok_or(MiddlewareError::InvalidState)?
+                    .next_event()
+                    .await;
+                match result {
+                    Ok(None) if self.execution.is_finalized() => {
+                        let mut capture = self
+                            .capture
+                            .lock()
+                            .unwrap_or_else(std::sync::PoisonError::into_inner);
+                        capture.response_id = self.encoder.response_id().map(str::to_owned);
+                        capture.provider_state = self.provider_state.take();
+                        drop(capture);
+                        self.execution.disarm();
+                        self.finished = true;
+                        continue;
+                    }
+                    Err(_) if self.encoder.has_wire_failure() && self.execution.is_finalized() => {
+                        self.execution.disarm();
+                        self.finished = true;
+                        continue;
+                    }
+                    Ok(None | Some(_)) => return Err(MiddlewareError::InvalidState),
+                    Err(error) => return Err(MiddlewareError::Engine(error)),
+                }
+            }
+            if self.batch_pending {
+                if !self.committed {
+                    self.execution
+                        .session_mut()
+                        .ok_or(MiddlewareError::InvalidState)?
+                        .discard_pending_delivery()
+                        .map_err(MiddlewareError::Engine)?;
+                }
+                self.batch_pending = false;
+            }
+            let result = self
+                .execution
+                .session_mut()
+                .ok_or(MiddlewareError::InvalidState)?
+                .next_event()
+                .await;
+            let delivery = match result {
+                Ok(Some(delivery)) => delivery,
+                Ok(None) => return Err(MiddlewareError::InvalidState),
+                Err(error) if self.committed => {
+                    self.push_gateway_error(gateway_error_from_engine(&error));
+                    continue;
+                }
+                Err(error) => return Err(MiddlewareError::Engine(error)),
+            };
+            let expected = if self.committed {
+                CommitRequirement::AlreadyCommitted
+            } else {
+                CommitRequirement::CommitBeforeDelivery
+            };
+            if delivery.commit_requirement() != expected {
+                return Err(MiddlewareError::InvalidState);
+            }
+            let mut messages = Vec::new();
+            for mut event in delivery.into_provider_events() {
+                self.validation.observe_event(&event);
+                let transformed = self.transformed_pending || event.middleware_transformed();
+                if let Some(update) = event.take_session_update() {
+                    self.provider_state = Some(update);
+                }
+                let encoded = self.encoder.push_websocket(&event);
+                if encoded.is_empty() {
+                    self.transformed_pending = transformed;
+                    continue;
+                }
+                messages.extend(encoded.into_iter().map(|message| (message, transformed)));
+                self.transformed_pending = false;
+            }
+            let terminal = self.encoder.is_completed() || self.encoder.has_wire_failure();
+            let last = messages.len().saturating_sub(1);
+            self.pending.extend(messages.into_iter().enumerate().map(
+                |(index, (message, transformed))| {
+                    MiddlewareFrame::new(
+                        Bytes::from(message),
+                        MiddlewareFraming::JsonDocument,
+                        terminal && index == last,
+                    )
+                    .with_transformed(transformed)
+                },
+            ));
+            self.awaiting_terminal_eof = terminal;
+            self.batch_pending = !self.committed;
+            if self.pending.is_empty() {
+                if terminal {
+                    return Err(MiddlewareError::InvalidState);
+                }
+                continue;
+            }
+        }
+        Ok(())
+    }
+
+    fn push_gateway_error(&mut self, error: GatewayError) {
+        let (status, default_type, default_code) = gateway_error_contract(error.kind());
+        self.pending.push_back(MiddlewareFrame::new(
+            Bytes::from(error_event(
+                status,
+                error.client_error_type().unwrap_or(default_type),
+                error.client_error_code().unwrap_or(default_code),
+                error.client_message(),
+                None,
+                Some(&self.request_id),
+                serde_json::Map::new(),
+            )),
+            MiddlewareFraming::JsonDocument,
+            true,
+        ));
+        self.finished = true;
+    }
+}
+
+impl MiddlewareBody for WebSocketExecutionBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async move {
+            if let Some(frame) = self.pending.pop_front() {
+                return Ok(Some(frame));
+            }
+            if self.finished {
+                return Ok(None);
+            }
+            self.fill_pending().await?;
+            Ok(self.pending.pop_front())
+        })
+    }
+
+    fn commit_downstream(
+        &mut self,
+        status: Option<u16>,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        Box::pin(async move {
+            if self.committed {
+                return Ok(());
+            }
+            self.execution
+                .session_mut()
+                .ok_or(MiddlewareError::InvalidState)?
+                .commit_downstream(status)
+                .await
+                .map_err(MiddlewareError::Engine)?;
+            self.committed = true;
+            self.batch_pending = false;
+            Ok(())
+        })
+    }
+
+    fn record_client_status(&mut self, status: u16) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        Box::pin(async move {
+            let Some(session) = self.execution.session_mut() else {
+                return Ok(());
+            };
+            session
+                .record_client_status(status)
+                .await
+                .map_err(MiddlewareError::Engine)
+        })
+    }
+
+    fn is_finalized(&self) -> bool {
+        self.execution.is_finalized()
+    }
+
+    fn close(mut self: Box<Self>) -> BoxFuture<'static, ()> {
+        Box::pin(async move { self.execution.cancel_and_finalize().await })
     }
 }
 
@@ -398,27 +637,15 @@ async fn send_error(
     param: Option<&str>,
     request_id: &Arc<str>,
 ) -> ForwardOutcome {
-    send_error_message(
-        connection,
-        error_event(
-            status,
-            error_type,
-            code,
-            message,
-            param,
-            Some(request_id),
-            serde_json::Map::new(),
-        ),
-        request_id,
-    )
-    .await
-}
-
-async fn send_error_message(
-    connection: &mut ResponsesWebSocketConnection,
-    message: String,
-    request_id: &Arc<str>,
-) -> ForwardOutcome {
+    let message = error_event(
+        status,
+        error_type,
+        code,
+        message,
+        param,
+        Some(request_id),
+        serde_json::Map::new(),
+    );
     if connection
         .send_text(
             message,
@@ -446,61 +673,3 @@ async fn send_metadata(
         .await
         .is_ok()
 }
-
-async fn send_messages(
-    connection: &mut ResponsesWebSocketConnection,
-    messages: Vec<String>,
-    request_id: &Arc<str>,
-    first_frame_written: &mut bool,
-    terminal_batch: bool,
-) -> bool {
-    let message_count = messages.len();
-    for (index, message) in messages.into_iter().enumerate() {
-        let is_terminal = terminal_batch && index + 1 == message_count;
-        let phase = match (*first_frame_written, is_terminal) {
-            (false, true) => FramePhase::FirstAndTerminal,
-            (false, false) => FramePhase::First,
-            (true, true) => FramePhase::Terminal,
-            (true, false) => FramePhase::Data,
-        };
-        if connection
-            .send_text(message, WriteContext::request(request_id, phase))
-            .await
-            .is_err()
-        {
-            return false;
-        }
-        *first_frame_written = true;
-    }
-    true
-}
-
-fn log_terminal_write_success(
-    connection: &ResponsesWebSocketConnection,
-    request_id: &Arc<str>,
-    provider_terminal_to_write: std::time::Duration,
-) {
-    tracing::info!(
-        target: "request_trace", stage = "downstream.terminal.written",
-        websocket_connection_id = connection.id(),
-        request_id = %request_id,
-        provider_terminal_to_terminal_write_ms = provider_terminal_to_write.as_millis(),
-        terminal_frame_written = true,
-        "Provider execution terminal was written to the WebSocket transport"
-    );
-}
-
-fn log_terminal_write_failure(
-    connection: &ResponsesWebSocketConnection,
-    request_id: &Arc<str>,
-    provider_terminal_to_write: std::time::Duration,
-) {
-    tracing::info!(
-        target: "request_trace", stage = "downstream.terminal.write_failed",
-        websocket_connection_id = connection.id(),
-        request_id = %request_id,
-        provider_terminal_to_terminal_write_ms = provider_terminal_to_write.as_millis(),
-        provider_succeeded_but_terminal_write_failed = true,
-        "Provider execution succeeded before the terminal WebSocket frame write failed"
-    );
-}
diff --git a/backend/crates/gateway-api/src/openai/responses/websocket/mod.rs b/backend/crates/gateway-api/src/openai/responses/websocket/mod.rs
index d34196c18..956ddfae4 100644
--- a/backend/crates/gateway-api/src/openai/responses/websocket/mod.rs
+++ b/backend/crates/gateway-api/src/openai/responses/websocket/mod.rs
@@ -18,14 +18,23 @@ use axum::{
     http::{HeaderMap, StatusCode},
     response::{IntoResponse, Response},
 };
+use bytes::Bytes;
 use gateway_core::{
     diagnostics::{TraceContext, diagnostic_json},
-    engine::execution::{AuthenticatedClient, ClientTransport},
+    engine::{
+        execution::{AuthenticatedClient, ClientTransport},
+        middleware::MiddlewareError,
+    },
     lifecycle::{ConnectionGuard, ConnectionLifecycle},
+    operation::OperationKind,
 };
 
 use crate::{
     ApiState,
+    openai::middleware::{
+        HttpMiddlewareInput, invoke_http_middleware, request_headers as middleware_request_headers,
+        request_parts,
+    },
     openai::{
         auth::{authenticate_client, client_access_error_response},
         error::runtime_unavailable_response,
@@ -33,11 +42,14 @@ use crate::{
     },
 };
 
-use super::{http::request_client_context, request::OpenAiRequestHeaders};
+use super::{
+    http::request_client_context, request::OpenAiRequestHeaders,
+    validation::ResponseValidationFacts,
+};
 use connection::{ConnectionEvent, FramePhase, ResponsesWebSocketConnection, WriteContext};
 use forward::{
-    ConnectionReplaySnapshot, ForwardOutcome, forward_execution, send_gateway_error,
-    send_protocol_error,
+    ConnectionReplaySnapshot, ForwardOutcome, execution_response, forward_response,
+    new_replay_capture, send_gateway_error, send_middleware_error, send_protocol_error,
 };
 use protocol::connection_limit_event;
 pub use protocol::{ResponseCreateFrameError, decode_response_create_with_context};
@@ -53,7 +65,7 @@ pub(crate) async fn responses_websocket(
     websocket: WebSocketUpgrade,
 ) -> Response {
     let service = state.openai().clone();
-    let client = match authenticate_client(&service, &headers) {
+    let client = match authenticate_client(&service, &headers).await {
         Ok(client) => client,
         Err(error) => return client_access_error_response(error),
     };
@@ -101,7 +113,7 @@ impl ResponsesWebSocketAdapter {
         let connection_id = self.service.next_request_id().replacen("req_", "ws_", 1);
         TraceContext::new(&connection_id).headers(
             "client.connection.headers",
-            serde_json::json!({"transport": "websocket", "method": "GET", "path": "/v1/responses"}),
+            serde_json::json!({"transport": "websocket", "method": "GET", "path": crate::openai::router::RESPONSES_PATH}),
             raw_headers
                 .iter()
                 .map(|(name, value)| (name.as_str(), value.as_bytes())),
@@ -113,6 +125,7 @@ impl ResponsesWebSocketAdapter {
             client_ip,
             user_agent,
             request_headers,
+            raw_headers,
             lifecycle: self.service.lifecycle(),
             connection_guard,
         };
@@ -134,6 +147,7 @@ struct ResponsesWebSocketSession {
     client_ip: Option<IpAddr>,
     user_agent: Option<String>,
     request_headers: OpenAiRequestHeaders,
+    raw_headers: HeaderMap,
     lifecycle: Arc<dyn ConnectionLifecycle>,
     connection_guard: Box<dyn ConnectionGuard>,
 }
@@ -146,6 +160,7 @@ async fn serve_responses_websocket(socket: WebSocket, session: ResponsesWebSocke
         client_ip,
         user_agent,
         request_headers,
+        raw_headers,
         lifecycle,
         connection_guard,
     } = session;
@@ -184,7 +199,7 @@ async fn serve_responses_websocket(socket: WebSocket, session: ResponsesWebSocke
         request_count = request_count.saturating_add(1);
         let correlation_id = Arc::<str>::from(service.next_request_id());
         let decoded = match decode_response_create_with_context(&payload, &request_headers) {
-            Ok(decoded) => decoded.with_client_context(client_ip, user_agent.clone()),
+            Ok(decoded) => decoded,
             Err(error) => {
                 trace_rejected_request(
                     &correlation_id,
@@ -207,7 +222,6 @@ async fn serve_responses_websocket(socket: WebSocket, session: ResponsesWebSocke
                 continue;
             }
         };
-        let decoded = replay.prepare(decoded);
         // deadline 与 Text 可能同时就绪；在任何上游执行开始前再次封住该竞争窗口。
         if connection.is_expired() {
             trace_rejected_request(
@@ -220,16 +234,9 @@ async fn serve_responses_websocket(socket: WebSocket, session: ResponsesWebSocke
             expire_connection(&mut connection).await;
             break;
         }
-        let started = match service
-            .start_response(
-                client.clone(),
-                decoded,
-                ClientTransport::WebSocket,
-                "/v1/responses",
-            )
-            .await
-        {
-            Ok(started) => started,
+        let execution = service.execution();
+        let prepared = match execution.prepare_execution(client.clone()).await {
+            Ok(prepared) => prepared,
             Err(error) => {
                 trace_rejected_request(
                     &correlation_id,
@@ -246,16 +253,96 @@ async fn serve_responses_websocket(socket: WebSocket, session: ResponsesWebSocke
                 continue;
             }
         };
-        started.session.trace().record("client.connection", serde_json::json!({
-            "transport": "websocket", "connectionId": connection.id(), "correlationId": correlation_id.as_ref(),
-            "requestIndex": request_count,
-        }));
-        started
-            .session
-            .trace()
-            .capture("client.request.body", payload.as_bytes());
-
-        if forward_execution(&mut connection, started, &mut replay).await
+        let request_id = Arc::<str>::from(prepared.request_id().to_string());
+        let capture = new_replay_capture();
+        let validation = ResponseValidationFacts::default();
+        let input = HttpMiddlewareInput {
+            endpoint: crate::openai::router::RESPONSES_PATH.to_owned(),
+            protocol: "openai".to_owned(),
+            operation: Some(OperationKind::Generate),
+            transport: ClientTransport::WebSocket,
+            model_hint: Some(decoded.metadata().requested_model().to_owned()),
+            headers: middleware_request_headers(&raw_headers),
+            body: Bytes::from(payload.clone()),
+        };
+        let service_for_terminal = service.clone();
+        let replay_for_terminal = replay.clone();
+        let connection_id_for_terminal = connection.id().to_owned();
+        let user_agent_for_terminal = user_agent.clone();
+        let request_id_for_terminal = Arc::clone(&request_id);
+        let capture_for_terminal = Arc::clone(&capture);
+        let validation_for_terminal = validation.clone();
+        let invoke = invoke_http_middleware(
+            execution,
+            prepared,
+            input,
+            Box::new(move |prepared, request| {
+                Box::pin(async move {
+                    let (protocol, headers, body) = request_parts(request)?;
+                    if protocol != "openai" {
+                        return Err(MiddlewareError::Rejected);
+                    }
+                    let payload =
+                        std::str::from_utf8(&body).map_err(|_| MiddlewareError::Rejected)?;
+                    let request_headers = OpenAiRequestHeaders::from_headers(&headers)
+                        .with_downstream_websocket_connection_id(
+                            connection_id_for_terminal.clone(),
+                        );
+                    let decoded = decode_response_create_with_context(payload, &request_headers)
+                        .map_err(|_| MiddlewareError::Rejected)?
+                        .with_client_context(client_ip, user_agent_for_terminal);
+                    let decoded = replay_for_terminal.prepare(decoded);
+                    let started = service_for_terminal
+                        .start_prepared_response(
+                            prepared,
+                            decoded,
+                            ClientTransport::WebSocket,
+                            crate::openai::router::RESPONSES_PATH,
+                        )
+                        .await
+                        .map_err(MiddlewareError::Gateway)?;
+                    started.session.trace().record(
+                        "client.connection",
+                        serde_json::json!({
+                            "transport": "websocket",
+                            "connectionId": connection_id_for_terminal,
+                            "correlationId": request_id_for_terminal.as_ref(),
+                            "requestIndex": request_count,
+                        }),
+                    );
+                    started
+                        .session
+                        .trace()
+                        .capture("client.request.body", &body);
+                    execution_response(started, capture_for_terminal, validation_for_terminal).await
+                })
+            }),
+        );
+        let response = tokio::select! {
+            biased;
+            _ = connection.wait_for_exit() => break,
+            response = invoke => response,
+        };
+        let response = match response {
+            Ok(response) => response,
+            Err(error) => {
+                if send_middleware_error(&mut connection, error, &request_id).await
+                    == ForwardOutcome::Disconnect
+                {
+                    break;
+                }
+                continue;
+            }
+        };
+        if forward_response(
+            &mut connection,
+            response,
+            request_id,
+            &mut replay,
+            capture,
+            validation,
+        )
+        .await
             == ForwardOutcome::Disconnect
         {
             break;
diff --git a/backend/crates/gateway-api/src/openai/router.rs b/backend/crates/gateway-api/src/openai/router.rs
index 32cf2ad64..b655b5301 100644
--- a/backend/crates/gateway-api/src/openai/router.rs
+++ b/backend/crates/gateway-api/src/openai/router.rs
@@ -16,16 +16,25 @@ use super::{
 
 use crate::ApiState;
 
+// 公开协议路径由 API 层统一定义；Core 使用操作类型，不根据这些路径分派业务。
+pub(super) const RESPONSES_PATH: &str = "/v1/responses";
+pub(super) const IMAGE_GENERATIONS_PATH: &str = "/v1/images/generations";
+pub(super) const IMAGE_EDITS_PATH: &str = "/v1/images/edits";
+pub(super) const SEARCH_PATH: &str = "/v1/alpha/search";
+pub(super) const MODELS_PATH: &str = "/v1/models";
+pub(super) const MODEL_DETAIL_PATH: &str = "/v1/models/{model_id}";
+pub(super) const USAGE_PATH: &str = "/v1/usage";
+
 /// 构造 OpenAI 客户端协议路由。
 pub(crate) fn router() -> Router<ApiState> {
     Router::new()
-        .route("/v1/images/generations", post(image_generations))
-        .route("/v1/images/edits", post(image_edits))
-        .route("/v1/alpha/search", post(standalone_search))
-        .route("/v1/responses", get(responses_websocket).post(responses))
-        .route("/v1/models", get(models))
+        .route(IMAGE_GENERATIONS_PATH, post(image_generations))
+        .route(IMAGE_EDITS_PATH, post(image_edits))
+        .route(SEARCH_PATH, post(standalone_search))
+        .route(RESPONSES_PATH, get(responses_websocket).post(responses))
+        .route(MODELS_PATH, get(models))
         // 官方 OpenAI 模型详情合同使用 path ID；它不属于 Admin API 约束。
-        .route("/v1/models/{model_id}", get(model_detail))
+        .route(MODEL_DETAIL_PATH, get(model_detail))
         .merge(usage::router())
         // OpenAI 数据面正文属于客户端/上游协议；代理不能用私有大小上限提前拒绝
         // 上游本可接受的未来 payload。
diff --git a/backend/crates/gateway-api/src/openai/search/http.rs b/backend/crates/gateway-api/src/openai/search/http.rs
index 449d2fd80..055cae166 100644
--- a/backend/crates/gateway-api/src/openai/search/http.rs
+++ b/backend/crates/gateway-api/src/openai/search/http.rs
@@ -8,15 +8,17 @@ use axum::{
     http::HeaderMap,
     response::Response,
 };
+use gateway_core::engine::execution::ClientTransport;
 use gateway_core::error::{GatewayError, GatewayErrorKind};
-use gateway_core::operation::{Operation, RawJsonPayload, StandaloneSearchRequest};
+use gateway_core::operation::{Operation, OperationKind, RawJsonPayload, StandaloneSearchRequest};
 
 use crate::ApiState;
+use crate::openai::middleware::{HttpMiddlewareInput, request_headers};
 use crate::openai::{
     auth::{authenticate_client, client_access_error_response},
-    endpoint::collect_raw_json_response,
-    error::gateway_error_response,
+    endpoint::provider_endpoint_response,
     responses::{OpenAiRequestHeaders, request_client_context},
+    router::SEARCH_PATH,
 };
 
 const OPENAI_PROTOCOL: &str = "openai";
@@ -29,7 +31,7 @@ pub(crate) async fn standalone_search(
     body: Bytes,
 ) -> Response {
     let service = state.openai();
-    let client = match authenticate_client(service, &headers) {
+    let client = match authenticate_client(service, &headers).await {
         Ok(client) => client,
         Err(error) => return client_access_error_response(error),
     };
@@ -37,18 +39,23 @@ pub(crate) async fn standalone_search(
         &headers,
         connect_info.map(|Extension(ConnectInfo(address))| address),
     );
-    let operation = match search_operation(body, &headers) {
-        Ok(operation) => operation,
-        Err(error) => return gateway_error_response(&error),
-    };
-    let started = match service
-        .start_provider_endpoint(client, operation, client_ip, user_agent, "/v1/alpha/search")
-        .await
-    {
-        Ok(started) => started,
-        Err(error) => return gateway_error_response(&error),
-    };
-    collect_raw_json_response(started).await
+    provider_endpoint_response(
+        service.clone(),
+        client,
+        HttpMiddlewareInput {
+            endpoint: SEARCH_PATH.to_owned(),
+            protocol: OPENAI_PROTOCOL.to_owned(),
+            operation: Some(OperationKind::Search),
+            transport: ClientTransport::HttpJson,
+            model_hint: None,
+            headers: request_headers(&headers),
+            body,
+        },
+        client_ip,
+        user_agent,
+        search_operation,
+    )
+    .await
 }
 
 fn search_operation(body: Bytes, headers: &HeaderMap) -> Result<Operation, GatewayError> {
diff --git a/backend/crates/gateway-api/src/openai/service.rs b/backend/crates/gateway-api/src/openai/service.rs
index 874206cb9..c8d3e4527 100644
--- a/backend/crates/gateway-api/src/openai/service.rs
+++ b/backend/crates/gateway-api/src/openai/service.rs
@@ -3,14 +3,18 @@
 use std::net::IpAddr;
 use std::sync::Arc;
 
+use gateway_core::engine::authentication::ClientAuthenticationRequest;
 use gateway_core::engine::continuation::PreviousResponseId;
 use gateway_core::engine::execution::{
     AuthenticatedClient, ClientAuthenticationError, ClientTransport, ExecutionRequestMetadata,
-    ExecutionService, StartExecution, StartProviderExecution, StartedExecution,
+    ExecutionService, PreparedExecutionRequest, PreparedRootExecution, StartProviderExecution,
+    StartedExecution,
 };
 use gateway_core::error::{GatewayError, GatewayErrorKind};
 use gateway_core::lifecycle::{ConnectionDraining, ConnectionGuard, ConnectionLifecycle};
-use gateway_core::routing::{ProviderCatalogUnavailable, PublicModelDescriptor, PublicModelId};
+use gateway_core::routing::{
+    ProviderCatalogUnavailable, ProviderKind, PublicModelDescriptor, PublicModelId,
+};
 use uuid::Uuid;
 
 use super::auth::ClientApiKeyAuthError;
@@ -24,6 +28,10 @@ pub(crate) struct OpenAiService {
 }
 
 impl OpenAiService {
+    pub(crate) fn execution(&self) -> Arc<dyn ExecutionService> {
+        Arc::clone(&self.execution)
+    }
+
     #[must_use]
     pub(crate) const fn new(
         execution: Arc<dyn ExecutionService>,
@@ -35,12 +43,23 @@ impl OpenAiService {
         }
     }
 
-    pub(crate) fn authenticate(
+    pub(crate) async fn authenticate(
         &self,
-        plaintext: &str,
+        request: ClientAuthenticationRequest,
     ) -> Result<AuthenticatedClient, ClientApiKeyAuthError> {
         self.execution
-            .authenticate(plaintext)
+            .authenticate_request(request)
+            .await
+            .map_err(map_authentication_error)
+    }
+
+    pub(crate) async fn verify(
+        &self,
+        request: ClientAuthenticationRequest,
+    ) -> Result<AuthenticatedClient, ClientApiKeyAuthError> {
+        self.execution
+            .verify_request(request)
+            .await
             .map_err(map_authentication_error)
     }
 
@@ -70,9 +89,9 @@ impl OpenAiService {
         self.execution.contains_public_model(client, model)
     }
 
-    pub(crate) async fn start_response(
+    pub(crate) async fn start_prepared_response(
         &self,
-        client: AuthenticatedClient,
+        prepared: PreparedRootExecution,
         request: DecodedResponsesRequest,
         transport: ClientTransport,
         endpoint: &'static str,
@@ -92,55 +111,65 @@ impl OpenAiService {
             }
         };
         self.execution
-            .start(StartExecution {
-                client,
-                public_model,
-                operation,
-                metadata: ExecutionRequestMetadata {
-                    protocol: "openai".to_owned(),
-                    endpoint: endpoint.to_owned(),
-                    transport,
-                    stream: metadata.stream(),
-                    client_ip: metadata.client_ip(),
-                    user_agent: metadata.user_agent().map(str::to_owned),
-                    previous_response_id,
+            .start_prepared(
+                prepared,
+                PreparedExecutionRequest {
+                    public_model,
+                    operation,
+                    metadata: ExecutionRequestMetadata {
+                        protocol: "openai".to_owned(),
+                        endpoint: endpoint.to_owned(),
+                        transport,
+                        stream: metadata.stream(),
+                        client_ip: metadata.client_ip(),
+                        user_agent: metadata.user_agent().map(str::to_owned),
+                        previous_response_id,
+                    },
                 },
-            })
+            )
             .await
     }
 
-    pub(crate) async fn start_provider_endpoint(
+    pub(crate) async fn start_prepared_provider_endpoint(
         &self,
-        client: AuthenticatedClient,
+        prepared: PreparedRootExecution,
         operation: gateway_core::operation::Operation,
         client_ip: Option<IpAddr>,
         user_agent: Option<String>,
-        endpoint: &'static str,
+        endpoint: String,
     ) -> Result<StartedExecution, GatewayError> {
-        let provider = gateway_core::routing::ProviderKind::new("openai").map_err(|_| {
+        let provider = ProviderKind::new("openai").map_err(|_| {
             GatewayError::new(
                 GatewayErrorKind::Internal,
                 "OpenAI provider identifier is invalid",
             )
         })?;
         self.execution
-            .start_provider_endpoint(StartProviderExecution {
-                client,
+            .start_prepared_provider_endpoint(
+                prepared,
                 provider,
+                None,
                 operation,
-                metadata: ExecutionRequestMetadata {
+                ExecutionRequestMetadata {
                     protocol: "openai".to_owned(),
-                    endpoint: endpoint.to_owned(),
+                    endpoint,
                     transport: ClientTransport::HttpJson,
                     stream: false,
                     client_ip,
                     user_agent,
                     previous_response_id: None,
                 },
-            })
+            )
             .await
     }
 
+    pub(crate) async fn start_bound_provider_endpoint(
+        &self,
+        request: StartProviderExecution,
+    ) -> Result<StartedExecution, GatewayError> {
+        self.execution.start_provider_endpoint(request).await
+    }
+
     pub(crate) fn try_register_connection(
         &self,
     ) -> Result<Box<dyn ConnectionGuard>, ConnectionDraining> {
@@ -162,5 +191,6 @@ const fn map_authentication_error(error: ClientAuthenticationError) -> ClientApi
     match error {
         ClientAuthenticationError::InvalidKey => ClientApiKeyAuthError::InvalidKey,
         ClientAuthenticationError::SnapshotUnavailable => ClientApiKeyAuthError::RuntimeUnavailable,
+        ClientAuthenticationError::ProviderUnavailable => ClientApiKeyAuthError::RuntimeUnavailable,
     }
 }
diff --git a/backend/crates/gateway-api/src/openai/usage.rs b/backend/crates/gateway-api/src/openai/usage.rs
index ffcdb8ac9..2af6e94c1 100644
--- a/backend/crates/gateway-api/src/openai/usage.rs
+++ b/backend/crates/gateway-api/src/openai/usage.rs
@@ -11,20 +11,24 @@ use axum::{
     routing::get,
 };
 use chrono::{DateTime, Utc};
-use gateway_core::metering::Decimal;
+use gateway_core::{engine::execution::AuthenticatedClient, metering::Decimal};
 use serde::Deserialize;
 use serde_json::{Value, json};
 
-use crate::{ApiState, auth::SessionState as _};
+use crate::{
+    ApiState,
+    auth::SessionState as _,
+    openai::middleware::{self as plugin_middleware, HttpMiddlewareInput},
+};
 
 use super::{
-    auth::{bearer_client_api_key, client_access_error_response},
+    auth::{client_access_error_response, verify_client},
     error::{missing_client_api_key_response, openai_error_response},
 };
 
 pub(super) fn router() -> Router<ApiState> {
     Router::new()
-        .route("/v1/usage", get(usage))
+        .route(super::router::USAGE_PATH, get(usage))
         .layer(middleware::map_response(no_store))
 }
 
@@ -37,11 +41,25 @@ async fn usage(
     headers: HeaderMap,
     uri: axum::http::Uri,
 ) -> Response {
-    let key = match bearer_client_api_key(&headers) {
-        Ok(key) => key,
+    let client = match verify_client(state.openai(), &headers).await {
+        Ok(client) => client,
         Err(error) => return client_access_error_response(error.into()),
     };
-    // 范围只能来自 Bearer 身份，不接受调用者指定 Key、账号或时间窗口。
+    plugin_middleware::query_response(
+        state.openai().execution(),
+        client,
+        HttpMiddlewareInput::query(super::router::USAGE_PATH.to_owned(), None, &headers),
+        move |client| usage_response(state, client, uri),
+    )
+    .await
+}
+
+async fn usage_response(
+    state: ApiState,
+    client: AuthenticatedClient,
+    uri: axum::http::Uri,
+) -> Response {
+    // 范围只能来自宿主认证后的身份，不接受插件或调用者指定 Key、账号或时间窗口。
     if Query::<UsageQuery>::try_from_uri(&uri).is_err() {
         return openai_error_response(
             StatusCode::BAD_REQUEST,
@@ -51,7 +69,12 @@ async fn usage(
         )
         .into_response();
     }
-    let budget = match state.admin_services().key_usage().budget(key).await {
+    let budget = match state
+        .admin_services()
+        .key_usage()
+        .budget_for_client(client.policy().key_id())
+        .await
+    {
         Ok(Some(budget)) => budget,
         Ok(None) => return missing_client_api_key_response().into_response(),
         Err(_) => {
diff --git a/backend/crates/gateway-api/src/provider.rs b/backend/crates/gateway-api/src/provider.rs
new file mode 100644
index 000000000..881823c3e
--- /dev/null
+++ b/backend/crates/gateway-api/src/provider.rs
@@ -0,0 +1,465 @@
+//! Provider 自有操作的稳定 HTTP adapter。
+
+use std::net::SocketAddr;
+
+use axum::{
+    Router,
+    body::{Body, Bytes},
+    extract::{ConnectInfo, DefaultBodyLimit, Extension, Path, State},
+    http::{HeaderMap, HeaderName, HeaderValue, Method, StatusCode, Uri, header},
+    response::{IntoResponse, Response},
+    routing::{MethodFilter, on, post},
+};
+use bytes::BytesMut;
+use gateway_core::{
+    engine::execution::{
+        ClientTransport, ExecutionRequestMetadata, ExecutionSession, StartProviderExecution,
+        StartedExecution,
+    },
+    event::{ProviderEvent, ProviderResponseHeader},
+    operation::{
+        Operation, ProviderHttpHeader, ProviderHttpMethod, ProviderHttpRequest, RawHttpPayload,
+        RawJsonPayload, TokenCountRequest,
+    },
+    routing::{ProviderKind, UpstreamModelId},
+};
+
+use crate::{
+    ApiState,
+    openai::{
+        auth::{authenticate_client, client_access_error_response},
+        error::{engine_error_response, gateway_error_response, openai_error_response},
+        middleware::PendingExecution,
+        responses::request_client_context,
+        with_model_request_id,
+    },
+};
+
+const MAXIMUM_BODY_BYTES: usize = 8 * 1024 * 1024;
+const MAXIMUM_RAW_BODY_CHUNK_BYTES: usize = 64 * 1024;
+const TOKEN_COUNT_PROTOCOL: &str = "token-count";
+const PROVIDER_HTTP_PROTOCOL: &str = "provider-http";
+
+pub(crate) fn router() -> Router<ApiState> {
+    Router::new()
+        .route(
+            "/v1/providers/{provider}/models/{model}/count_tokens",
+            post(count_tokens),
+        )
+        // `get()` 会隐式接受 HEAD；这里必须只匹配明确声明的 GET/POST。
+        .route(
+            "/v1/providers/{provider}/http/{endpoint}",
+            on(MethodFilter::GET.or(MethodFilter::POST), provider_http).head(provider_http_head),
+        )
+        .layer(DefaultBodyLimit::max(MAXIMUM_BODY_BYTES))
+}
+
+async fn provider_http_head() -> StatusCode {
+    StatusCode::METHOD_NOT_ALLOWED
+}
+
+async fn count_tokens(
+    State(state): State<ApiState>,
+    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
+    Path((provider, model)): Path<(String, String)>,
+    uri: Uri,
+    headers: HeaderMap,
+    body: Bytes,
+) -> Response {
+    let service = state.openai();
+    let client = match authenticate_client(service, &headers).await {
+        Ok(client) => client,
+        Err(error) => return client_access_error_response(error),
+    };
+    let provider = match ProviderKind::new(provider) {
+        Ok(provider) => provider,
+        Err(_) => return invalid_request("provider identifier is invalid"),
+    };
+    let model = match UpstreamModelId::new(model) {
+        Ok(model) => model,
+        Err(_) => return invalid_request("provider model identifier is invalid"),
+    };
+    if serde_json::from_slice::<serde::de::IgnoredAny>(&body).is_err() {
+        return invalid_request("token count request must be valid JSON");
+    }
+    let payload = match RawJsonPayload::new(TOKEN_COUNT_PROTOCOL, body) {
+        Ok(payload) => payload,
+        Err(_) => return invalid_request("token count request is invalid"),
+    };
+    let (client_ip, user_agent) = request_client_context(
+        &headers,
+        connect_info.map(|Extension(ConnectInfo(address))| address),
+    );
+    let started = match service
+        .start_bound_provider_endpoint(StartProviderExecution {
+            client,
+            provider,
+            upstream_model: Some(model),
+            operation: Operation::CountTokens(TokenCountRequest::from_raw_json(payload)),
+            metadata: ExecutionRequestMetadata {
+                protocol: TOKEN_COUNT_PROTOCOL.to_owned(),
+                endpoint: uri.path().to_owned(),
+                transport: ClientTransport::HttpJson,
+                stream: false,
+                client_ip,
+                user_agent,
+                previous_response_id: None,
+            },
+        })
+        .await
+    {
+        Ok(started) => started,
+        Err(error) => return gateway_error_response(&error),
+    };
+    collect_provider_response(started, ResponseBodyKind::Json).await
+}
+
+async fn provider_http(
+    State(state): State<ApiState>,
+    connect_info: Option<Extension<ConnectInfo<SocketAddr>>>,
+    Path((provider, endpoint)): Path<(String, String)>,
+    uri: Uri,
+    method: Method,
+    headers: HeaderMap,
+    body: Bytes,
+) -> Response {
+    if method == Method::GET && !body.is_empty() {
+        return invalid_request("GET provider HTTP operations cannot carry a request body");
+    }
+    let method = match method {
+        Method::GET => ProviderHttpMethod::Get,
+        Method::POST => ProviderHttpMethod::Post,
+        _ => return invalid_request("provider HTTP method is unsupported"),
+    };
+    let service = state.openai();
+    let client = match authenticate_client(service, &headers).await {
+        Ok(client) => client,
+        Err(error) => return client_access_error_response(error),
+    };
+    let provider = match ProviderKind::new(provider) {
+        Ok(provider) => provider,
+        Err(_) => return invalid_request("provider identifier is invalid"),
+    };
+    let connection_options = headers
+        .get_all(header::CONNECTION)
+        .iter()
+        .filter_map(|value| value.to_str().ok())
+        .flat_map(|value| value.split(','))
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(str::to_ascii_lowercase)
+        .collect::<Vec<_>>();
+    let request_headers = headers
+        .iter()
+        .filter(|(name, _)| request_header_is_forwardable(name, &connection_options))
+        .map(|(name, value)| {
+            ProviderHttpHeader::new(name.as_str(), Bytes::copy_from_slice(value.as_bytes()))
+        })
+        .collect();
+    let payload = match RawHttpPayload::new(PROVIDER_HTTP_PROTOCOL, body) {
+        Ok(payload) => payload,
+        Err(_) => return invalid_request("provider HTTP request is invalid"),
+    };
+    let operation = match ProviderHttpRequest::new(
+        endpoint,
+        method,
+        uri.query().map(str::to_owned),
+        request_headers,
+        payload,
+    ) {
+        Ok(request) => Operation::ProviderHttp(request),
+        Err(_) => return invalid_request("provider HTTP request is invalid"),
+    };
+    let (client_ip, user_agent) = request_client_context(
+        &headers,
+        connect_info.map(|Extension(ConnectInfo(address))| address),
+    );
+    let started = match service
+        .start_bound_provider_endpoint(StartProviderExecution {
+            client,
+            provider,
+            upstream_model: None,
+            operation,
+            metadata: ExecutionRequestMetadata {
+                protocol: PROVIDER_HTTP_PROTOCOL.to_owned(),
+                endpoint: uri.path().to_owned(),
+                transport: ClientTransport::HttpJson,
+                stream: false,
+                client_ip,
+                user_agent,
+                previous_response_id: None,
+            },
+        })
+        .await
+    {
+        Ok(started) => started,
+        Err(error) => return gateway_error_response(&error),
+    };
+    collect_provider_response(started, ResponseBodyKind::Opaque).await
+}
+
+#[derive(Clone, Copy)]
+enum ResponseBodyKind {
+    Json,
+    Opaque,
+}
+
+async fn collect_provider_response(started: StartedExecution, kind: ResponseBodyKind) -> Response {
+    let request_id = started.request_id;
+    let response = collect_provider_session(started.session, kind).await;
+    with_model_request_id(response, &request_id)
+}
+
+async fn collect_provider_session(
+    session: Box<dyn ExecutionSession>,
+    kind: ResponseBodyKind,
+) -> Response {
+    let mut execution = PendingExecution::new(session);
+    let Some(session) = execution.session_mut() else {
+        return invalid_upstream_response();
+    };
+    let events = match session.collect_uncommitted().await {
+        Ok(events) => events,
+        Err(error) => {
+            let response = sanitize_response_headers(engine_error_response(&error));
+            return execution.record_response_status(response).await;
+        }
+    };
+    let Some(body) = response_body(events, kind) else {
+        let response = execution
+            .record_response_status(invalid_upstream_response())
+            .await;
+        execution.cancel_and_finalize().await;
+        return response;
+    };
+    let status = match session.response_status_code() {
+        None => StatusCode::OK,
+        Some(status) => match StatusCode::from_u16(status) {
+            Ok(status) if status.is_success() => status,
+            _ => {
+                let response = execution
+                    .record_response_status(invalid_upstream_response())
+                    .await;
+                execution.cancel_and_finalize().await;
+                return response;
+            }
+        },
+    };
+    let response_headers = session.response_headers().to_vec();
+    let response = body_response(body, status, &response_headers, kind);
+    let Some(session) = execution.session_mut() else {
+        return invalid_upstream_response();
+    };
+    if let Err(error) = session.commit_downstream(Some(status.as_u16())).await {
+        execution.cancel_and_finalize().await;
+        let response = sanitize_response_headers(engine_error_response(&error));
+        return execution.record_response_status(response).await;
+    }
+    if !session.is_finalized() {
+        execution.cancel_and_finalize().await;
+        return invalid_upstream_response();
+    }
+    execution.disarm();
+    response
+}
+
+fn response_body(events: Vec<ProviderEvent>, kind: ResponseBodyKind) -> Option<Bytes> {
+    let expected_protocol = match kind {
+        ResponseBodyKind::Json => TOKEN_COUNT_PROTOCOL,
+        ResponseBodyKind::Opaque => PROVIDER_HTTP_PROTOCOL,
+    };
+    let mut body = BytesMut::new();
+    let mut raw_body_events = 0usize;
+    let mut empty_body_event = false;
+    for event in events {
+        let (_, wire) = event.into_parts();
+        let Some(wire) = wire.filter(|wire| wire.protocol() == expected_protocol) else {
+            continue;
+        };
+        let raw = match kind {
+            ResponseBodyKind::Json => wire.into_raw_json_body(),
+            ResponseBodyKind::Opaque => wire.into_raw_http_body(),
+        }?;
+        raw_body_events = raw_body_events.checked_add(1)?;
+        if matches!(kind, ResponseBodyKind::Json) && raw_body_events > 1 {
+            return None;
+        }
+        if matches!(kind, ResponseBodyKind::Opaque) && raw.len() > MAXIMUM_RAW_BODY_CHUNK_BYTES {
+            return None;
+        }
+        let total = body.len().checked_add(raw.len())?;
+        if total > MAXIMUM_BODY_BYTES
+            || empty_body_event
+            || (raw.is_empty() && (raw_body_events > 1 || !body.is_empty()))
+        {
+            return None;
+        }
+        if raw.is_empty() {
+            empty_body_event = true;
+        }
+        body.extend_from_slice(&raw);
+    }
+    if raw_body_events == 0 {
+        return None;
+    }
+    let body = body.freeze();
+    if matches!(kind, ResponseBodyKind::Json)
+        && serde_json::from_slice::<serde::de::IgnoredAny>(&body).is_err()
+    {
+        return None;
+    }
+    Some(body)
+}
+
+fn body_response(
+    body: Bytes,
+    status: StatusCode,
+    response_headers: &[ProviderResponseHeader],
+    kind: ResponseBodyKind,
+) -> Response {
+    let length = body.len();
+    let mut response = Response::new(Body::from(body));
+    *response.status_mut() = status;
+    apply_safe_response_headers(&mut response, response_headers);
+    if matches!(kind, ResponseBodyKind::Json) {
+        response.headers_mut().insert(
+            header::CONTENT_TYPE,
+            HeaderValue::from_static("application/json"),
+        );
+    } else if !response.headers().contains_key(header::CONTENT_TYPE) {
+        response.headers_mut().insert(
+            header::CONTENT_TYPE,
+            HeaderValue::from_static("application/octet-stream"),
+        );
+    }
+    if let Ok(length) = HeaderValue::from_str(&length.to_string()) {
+        response
+            .headers_mut()
+            .insert(header::CONTENT_LENGTH, length);
+    }
+    response
+}
+
+fn apply_safe_response_headers(
+    response: &mut Response,
+    response_headers: &[ProviderResponseHeader],
+) {
+    let connection_options = connection_options(response_headers);
+    for header in response_headers {
+        if !response_header_is_forwardable(header.name(), &connection_options) {
+            continue;
+        }
+        let Ok(name) = HeaderName::from_bytes(header.name().as_bytes()) else {
+            continue;
+        };
+        let Ok(value) = HeaderValue::from_bytes(header.value()) else {
+            continue;
+        };
+        if name == header::CONTENT_TYPE {
+            response.headers_mut().insert(name, value);
+        } else {
+            response.headers_mut().append(name, value);
+        }
+    }
+}
+
+fn sanitize_response_headers(mut response: Response) -> Response {
+    let connection_options = response
+        .headers()
+        .get_all(header::CONNECTION)
+        .iter()
+        .filter_map(|value| value.to_str().ok())
+        .flat_map(|value| value.split(','))
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(str::to_ascii_lowercase)
+        .collect::<Vec<_>>();
+    let blocked = response
+        .headers()
+        .keys()
+        .filter(|name| !response_header_is_forwardable(name.as_str(), &connection_options))
+        .cloned()
+        .collect::<Vec<_>>();
+    for name in blocked {
+        response.headers_mut().remove(name);
+    }
+    response
+}
+
+fn connection_options(headers: &[ProviderResponseHeader]) -> Vec<String> {
+    headers
+        .iter()
+        .filter(|header| header.name().eq_ignore_ascii_case("connection"))
+        .filter_map(|header| std::str::from_utf8(header.value()).ok())
+        .flat_map(|value| value.split(','))
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(str::to_ascii_lowercase)
+        .collect()
+}
+
+fn request_header_is_forwardable(name: &HeaderName, connection_options: &[String]) -> bool {
+    let name = name.as_str();
+    !matches!(
+        name,
+        "authorization"
+            | "proxy-authorization"
+            | "x-api-key"
+            | "api-key"
+            | "cookie"
+            | "host"
+            | "content-length"
+            | "transfer-encoding"
+            | "connection"
+            | "keep-alive"
+            | "upgrade"
+            | "trailer"
+            | "forwarded"
+            | "x-forwarded-for"
+            | "x-forwarded-host"
+            | "x-forwarded-proto"
+            | "cf-connecting-ip"
+            | "x-real-ip"
+    ) && !name.starts_with("proxy-")
+        && !connection_options.iter().any(|option| option == name)
+}
+
+fn response_header_is_forwardable(name: &str, connection_options: &[String]) -> bool {
+    let name = name.trim().to_ascii_lowercase();
+    !matches!(
+        name.as_str(),
+        "authorization"
+            | "proxy-authenticate"
+            | "www-authenticate"
+            | "set-cookie"
+            | "location"
+            | "content-length"
+            | "content-encoding"
+            | "transfer-encoding"
+            | "connection"
+            | "keep-alive"
+            | "upgrade"
+            | "trailer"
+    ) && !name.starts_with("proxy-")
+        && !connection_options.iter().any(|option| option == &name)
+}
+
+fn invalid_request(message: &'static str) -> Response {
+    openai_error_response(
+        StatusCode::BAD_REQUEST,
+        message,
+        "invalid_request_error",
+        "invalid_provider_operation",
+    )
+    .into_response()
+}
+
+fn invalid_upstream_response() -> Response {
+    openai_error_response(
+        StatusCode::BAD_GATEWAY,
+        "The gateway could not forward the provider response.",
+        "server_error",
+        "invalid_upstream_response",
+    )
+    .into_response()
+}
diff --git a/backend/crates/gateway-api/tests/admin/accounts/capabilities.rs b/backend/crates/gateway-api/tests/admin/accounts/capabilities.rs
new file mode 100644
index 000000000..060a07ae1
--- /dev/null
+++ b/backend/crates/gateway-api/tests/admin/accounts/capabilities.rs
@@ -0,0 +1,95 @@
+use axum::{
+    body::{Body, to_bytes},
+    http::{Request, StatusCode, header},
+};
+use gateway_api::admin;
+use serde_json::{Value, json};
+use tower::ServiceExt as _;
+
+use super::super::{AdminTestFixture, AdminTestState};
+
+#[tokio::test]
+async fn provider_capabilities_require_admin_and_do_not_invent_unsupported_operations() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    for authenticated in [false, true] {
+        let mut request = Request::builder()
+            .uri("/api/admin/accounts/providers")
+            .header("x-request-id", "provider-capabilities-test");
+        if authenticated {
+            request = request.header(header::COOKIE, "cpr_session=valid-session");
+        }
+        let response = admin::router::<AdminTestState>()
+            .with_state(fixture.state())
+            .oneshot(request.body(Body::empty()).unwrap())
+            .await
+            .unwrap();
+        assert_eq!(
+            response.status(),
+            if authenticated {
+                StatusCode::OK
+            } else {
+                StatusCode::UNAUTHORIZED
+            }
+        );
+        assert_eq!(response.headers()[header::CACHE_CONTROL], "no-store");
+        if authenticated {
+            let body = to_bytes(response.into_body(), 8192).await.unwrap();
+            let value: Value = serde_json::from_slice(&body).unwrap();
+            assert_eq!(
+                value["data"],
+                json!([
+                    {"provider":"openai", "credentials":{"import":null,"login":null,"refresh":false,"export":false}},
+                    {"provider":"xai", "credentials":{"import":null,"login":null,"refresh":false,"export":false}}
+                ])
+            );
+        }
+    }
+}
+
+#[test]
+fn schema_and_completion_mode_are_preserved_in_the_api_contract() {
+    use gateway_admin::model::provider_capabilities::{
+        AuthorizationCompletion, ProviderCredentialCapabilities, ProviderCredentialDescriptor,
+        ProviderLoginCapability,
+    };
+    let schema = json!({"type":"object", "properties":{"code":{"type":"string", "writeOnly":true}}, "required":["code"]});
+    for (completion, expected) in [
+        (AuthorizationCompletion::Callback, "callback"),
+        (AuthorizationCompletion::Poll, "poll"),
+    ] {
+        let data = admin::accounts::AccountProviderData::from(ProviderCredentialDescriptor {
+            provider: gateway_core::routing::ProviderKind::new("custom").unwrap(),
+            capabilities: ProviderCredentialCapabilities {
+                login: Some(ProviderLoginCapability {
+                    input_schema: schema.clone(),
+                    completion,
+                }),
+                ..Default::default()
+            },
+        });
+        let value = serde_json::to_value(data).unwrap();
+        assert_eq!(
+            value["credentials"]["login"],
+            json!({"inputSchema":schema, "completion":expected})
+        );
+    }
+}
+
+#[test]
+fn login_input_is_optional_but_must_be_a_bounded_object() {
+    use admin::accounts::StartAccountAuthorizationRequest;
+    let base = json!({"provider":"custom", "name":"account"});
+    let request: StartAccountAuthorizationRequest = serde_json::from_value(base.clone()).unwrap();
+    assert!(request.input.is_empty());
+    request.validate().unwrap();
+    for invalid in [Value::Null, json!([]), json!("token")] {
+        let mut value = base.clone();
+        value["input"] = invalid;
+        assert!(serde_json::from_value::<StartAccountAuthorizationRequest>(value).is_err());
+    }
+    let mut value = base;
+    value["input"] = json!({"token":"x".repeat(64 * 1024)});
+    let request: StartAccountAuthorizationRequest = serde_json::from_value(value).unwrap();
+    assert_eq!(request.validate().unwrap_err().field(), "input");
+}
diff --git a/backend/crates/gateway-api/tests/admin/accounts/handlers.rs b/backend/crates/gateway-api/tests/admin/accounts/handlers.rs
index a8871e4d2..24cb15625 100644
--- a/backend/crates/gateway-api/tests/admin/accounts/handlers.rs
+++ b/backend/crates/gateway-api/tests/admin/accounts/handlers.rs
@@ -7,6 +7,147 @@ use tower::ServiceExt as _;
 
 use super::super::{AdminTestFixture, AdminTestState};
 
+#[tokio::test]
+async fn standalone_credential_rotation_route_is_not_exposed() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let response = admin::router::<AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .method("POST")
+                .uri("/api/admin/accounts/rotate")
+                .header(header::COOKIE, "cpr_session=valid-session")
+                .header(header::CONTENT_TYPE, "application/json")
+                .body(Body::from("{}"))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(response.status(), StatusCode::NOT_FOUND);
+}
+
+#[tokio::test]
+async fn connection_update_requires_admin_and_validates_before_calling_the_service() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let input = serde_json::json!({
+        "accountId":"acct_api",
+        "enabled":true,
+        "concurrencyLimit":null,
+        "weight":1,
+        "groupIds":[],
+        "connection":{"baseUrl":"https://api.example.invalid/v1", "transport":"http"}
+    });
+    for (authenticated, transport, expected) in [
+        (false, "http", StatusCode::UNAUTHORIZED),
+        (true, "invalid", StatusCode::BAD_REQUEST),
+        // 夹具没有凭据 Store，合法输入必须进入服务，不能按普通设置静默保存。
+        (true, "http", StatusCode::SERVICE_UNAVAILABLE),
+    ] {
+        let mut input = input.clone();
+        input["connection"]["transport"] = serde_json::json!(transport);
+        let mut request = Request::builder()
+            .method("POST")
+            .uri("/api/admin/accounts/update")
+            .header(header::CONTENT_TYPE, "application/json")
+            .header("x-request-id", "req_connection_update");
+        if authenticated {
+            request = request.header(header::COOKIE, "cpr_session=valid-session");
+        }
+        let response = admin::router::<AdminTestState>()
+            .with_state(fixture.state())
+            .oneshot(request.body(Body::from(input.to_string())).unwrap())
+            .await
+            .unwrap();
+        assert_eq!(response.status(), expected);
+        assert_eq!(response.headers()[header::CACHE_CONTROL], "no-store");
+    }
+}
+
+#[test]
+fn authorization_poll_response_preserves_every_committed_account() {
+    use gateway_admin::model::{
+        Revision,
+        provider_credentials::{
+            AuthorizationPollResult, AuthorizedAccount, CredentialBatchMutationResult,
+        },
+    };
+    let data = gateway_api::admin::accounts::AccountAuthorizationPollData::from(
+        AuthorizationPollResult::Complete(CredentialBatchMutationResult {
+            config_revision: Revision::new(3).unwrap(),
+            accounts: ["acct_first", "acct_second"]
+                .into_iter()
+                .map(|id| AuthorizedAccount {
+                    account_id: gateway_core::account::ProviderAccountId::new(id).unwrap(),
+                    credential_revision: Some(Revision::new(1).unwrap()),
+                })
+                .collect(),
+        }),
+    );
+    assert_eq!(
+        serde_json::to_value(data).unwrap(),
+        serde_json::json!({"status":"complete", "accountIds":["acct_first", "acct_second"]})
+    );
+}
+
+#[tokio::test]
+async fn authorization_poll_requires_admin_validates_input_and_preserves_pending_result() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    for (input, authenticated, expected) in [
+        (
+            serde_json::json!({"provider":"xai", "flowId":"flow-test"}),
+            false,
+            StatusCode::UNAUTHORIZED,
+        ),
+        (
+            serde_json::json!({"provider":"xai", "flowId":""}),
+            true,
+            StatusCode::BAD_REQUEST,
+        ),
+        (
+            serde_json::json!({"provider":"xai", "flowId":"flow-test", "accountId":"acct_forged"}),
+            true,
+            StatusCode::UNPROCESSABLE_ENTITY,
+        ),
+        (
+            serde_json::json!({"provider":"xai", "flowId":"flow-test", "callbackUrl":""}),
+            true,
+            StatusCode::BAD_REQUEST,
+        ),
+        (
+            serde_json::json!({"provider":"xai", "flowId":"flow-test"}),
+            true,
+            StatusCode::OK,
+        ),
+    ] {
+        let mut request = Request::builder()
+            .method("POST")
+            .uri("/api/admin/accounts/oauth/poll")
+            .header(header::CONTENT_TYPE, "application/json")
+            .header("x-request-id", "req_login_poll");
+        if authenticated {
+            request = request.header(header::COOKIE, "cpr_session=valid-session");
+        }
+        let response = admin::router::<AdminTestState>()
+            .with_state(fixture.state())
+            .oneshot(request.body(Body::from(input.to_string())).unwrap())
+            .await
+            .unwrap();
+        assert_eq!(response.status(), expected);
+        assert_eq!(response.headers()[header::CACHE_CONTROL], "no-store");
+        let body = to_bytes(response.into_body(), 8192).await.unwrap();
+        let value: serde_json::Value = serde_json::from_slice(&body).unwrap();
+        if expected == StatusCode::OK {
+            assert_eq!(
+                value["data"],
+                serde_json::json!({"status":"pending", "retryAfterMs":1250})
+            );
+        }
+    }
+}
+
 #[tokio::test]
 async fn personal_info_requires_admin_and_a_valid_account_query() {
     let fixture = AdminTestFixture::new().await;
diff --git a/backend/crates/gateway-api/tests/admin/accounts/mod.rs b/backend/crates/gateway-api/tests/admin/accounts/mod.rs
index 2d956e27c..90da58670 100644
--- a/backend/crates/gateway-api/tests/admin/accounts/mod.rs
+++ b/backend/crates/gateway-api/tests/admin/accounts/mod.rs
@@ -1,3 +1,4 @@
+mod capabilities;
 mod handlers;
 mod import_tasks;
 mod presenter;
@@ -78,6 +79,34 @@ mod query {
     use gateway_api::admin::accounts::ListQuery;
     use serde_json::json;
 
+    #[test]
+    fn account_query_should_filter_every_explicit_provider_id_literally() {
+        for provider in ["all", "ALL", "example"] {
+            let query: ListQuery = serde_json::from_value(json!({ "provider": provider })).unwrap();
+            assert_eq!(
+                query
+                    .validate()
+                    .unwrap()
+                    .provider_kind
+                    .as_ref()
+                    .map(|kind| kind.as_str()),
+                Some(provider)
+            );
+        }
+    }
+
+    #[test]
+    fn account_query_should_only_omit_empty_provider_filters() {
+        for value in [
+            json!({}),
+            json!({ "provider": "" }),
+            json!({ "provider": "  " }),
+        ] {
+            let query: ListQuery = serde_json::from_value(value).unwrap();
+            assert!(query.validate().unwrap().provider_kind.is_none());
+        }
+    }
+
     #[test]
     fn account_query_should_parse_provider_status_and_sort_once() {
         let query: ListQuery = serde_json::from_value(json!({
@@ -501,7 +530,7 @@ mod actions {
         AccountDeletionRequest, AccountExportData, AccountExportQuery, AccountIdQuery,
         AccountImportData, AccountImportRequest, AccountMutationData, AccountRefreshRequest,
         AccountResetCreditConsumeRequest, AccountTestQuery, CompleteAccountAuthorizationRequest,
-        RotateAccountRequest, StartAccountAuthorizationRequest,
+        StartAccountAuthorizationRequest, UpdateAccountRequest,
     };
     use gateway_core::{
         account::ProviderAccountId, engine::probe::AccountProbeErrorSource,
@@ -601,43 +630,81 @@ mod actions {
     }
 
     #[test]
-    fn api_key_rotation_settings_must_target_the_same_account_and_remain_valid() {
+    fn account_update_validates_connection_and_settings_together() {
         let mut request = json!({
-            "provider": "openai",
             "accountId": "acct_api",
-            "baseUrl": "https://api.example.invalid/v1",
-            "transport": "http",
-            "settings": {
-                "accountId": "acct_api",
-                "enabled": true,
-                "concurrencyLimit": null,
-                "weight": 1,
-                "groupIds": []
-            }
+            "connection": {
+                "baseUrl": "https://api.example.invalid/v1",
+                "transport": "http"
+            },
+            "enabled": true,
+            "concurrencyLimit": null,
+            "weight": 1,
+            "groupIds": []
         });
-        serde_json::from_value::<RotateAccountRequest>(request.clone())
+        serde_json::from_value::<UpdateAccountRequest>(request.clone())
             .expect("decode combined save")
             .validate()
-            .expect("blank replacement key preserves the existing key");
-        request["settings"]["accountId"] = json!("acct_other");
+            .expect("omitted replacement key preserves the existing key");
+        request["connection"]["apiKey"] = json!("");
         assert_eq!(
-            serde_json::from_value::<RotateAccountRequest>(request.clone())
+            serde_json::from_value::<UpdateAccountRequest>(request.clone())
                 .unwrap()
                 .validate()
                 .unwrap_err()
                 .field(),
-            "settings.accountId"
+            "connection.apiKey"
         );
-        request["settings"]["accountId"] = json!("acct_api");
-        request["settings"]["concurrencyLimit"] = json!(0);
+        request["connection"]["apiKey"] = json!("test-replacement-key");
+        request["concurrencyLimit"] = json!(0);
         assert!(
-            serde_json::from_value::<RotateAccountRequest>(request)
+            serde_json::from_value::<UpdateAccountRequest>(request)
                 .unwrap()
                 .validate()
                 .is_err()
         );
     }
 
+    #[test]
+    fn account_connection_update_rejects_invalid_fields_and_generic_credentials() {
+        let request = json!({
+            "accountId": "acct_api",
+            "enabled": true,
+            "concurrencyLimit": null,
+            "weight": 1,
+            "groupIds": [],
+            "connection": {"baseUrl": "https://api.example.invalid/v1", "transport": "http"}
+        });
+        for (field, value, expected) in [
+            ("baseUrl", "", "connection.baseUrl"),
+            ("transport", "websocket", "connection.transport"),
+            ("apiKey", "invalid key", "connection.apiKey"),
+        ] {
+            let mut invalid = request.clone();
+            invalid["connection"][field] = json!(value);
+            assert_eq!(
+                serde_json::from_value::<UpdateAccountRequest>(invalid)
+                    .unwrap()
+                    .validate()
+                    .unwrap_err()
+                    .field(),
+                expected
+            );
+        }
+        for field in [
+            "accountId",
+            "provider",
+            "accessToken",
+            "refreshToken",
+            "data",
+            "expectedCredentialRevision",
+        ] {
+            let mut invalid = request.clone();
+            invalid["connection"][field] = json!("unsupported");
+            assert!(serde_json::from_value::<UpdateAccountRequest>(invalid).is_err());
+        }
+    }
+
     #[test]
     fn credential_recovery_requests_should_not_accept_client_revision_fences() {
         let authorization: StartAccountAuthorizationRequest = serde_json::from_value(json!({
@@ -656,25 +723,6 @@ mod actions {
             }))
             .is_err()
         );
-
-        let rotation: RotateAccountRequest = serde_json::from_value(json!({
-            "provider": "openai",
-            "accountId": "acct_1",
-            "accessToken": "header.payload.signature",
-            "refreshToken": "refresh-token",
-            "idToken": "id-header.id-payload.id-signature"
-        }))
-        .expect("decode rotation");
-        assert!(rotation.validate().is_ok());
-        assert!(
-            serde_json::from_value::<RotateAccountRequest>(json!({
-                "provider": "openai",
-                "accountId": "acct_1",
-                "expectedCredentialRevision": 1,
-                "accessToken": "header.payload.signature"
-            }))
-            .is_err()
-        );
     }
 
     #[test]
diff --git a/backend/crates/gateway-api/tests/admin/client_keys.rs b/backend/crates/gateway-api/tests/admin/client_keys.rs
index 8b2e00da9..6c2ca4f45 100644
--- a/backend/crates/gateway-api/tests/admin/client_keys.rs
+++ b/backend/crates/gateway-api/tests/admin/client_keys.rs
@@ -432,8 +432,7 @@ fn client_key_responses_should_keep_shape_and_redact_creation_debug() {
         .single()
         .expect("valid time");
     let view = ClientKeyView::from(gateway_admin::model::client_keys::ClientKeyRecord {
-        openai_client_profile_override: None,
-        xai_client_profile_override: None,
+        request_profile_overrides: Default::default(),
         budget: Default::default(),
         id: gateway_core::policy::ClientApiKeyId::new("key_visible").expect("Client Key ID"),
         name: "visible".to_owned(),
@@ -574,11 +573,13 @@ async fn list_route_should_accept_the_full_nonzero_u16_page_size() {
 fn profile_override_distinguishes_omission_from_explicit_inheritance() {
     let mut payload = json!({"id":"key_profile", "name":"profile", "groupIds":[], "maxConcurrency":0, "requestsPerMinute":0});
     let decode = |body| {
-        serde_json::from_value::<UpdateClientKeyRequest>(body)
+        let mut command = serde_json::from_value::<UpdateClientKeyRequest>(body)
             .unwrap()
             .into_command()
-            .unwrap()
-            .openai_client_profile_override
+            .unwrap();
+        command
+            .request_profile_override_updates
+            .remove(&gateway_core::routing::ProviderKind::new("openai").expect("Provider kind"))
     };
     assert_eq!(decode(payload.clone()), None);
     payload["openaiClientProfileOverride"] = json!(null);
@@ -592,11 +593,13 @@ fn profile_override_distinguishes_omission_from_explicit_inheritance() {
 fn xai_profile_override_distinguishes_omission_from_explicit_inheritance() {
     let mut payload = json!({"id":"key_profile", "name":"profile", "groupIds":[], "maxConcurrency":0, "requestsPerMinute":0});
     let decode = |body| {
-        serde_json::from_value::<UpdateClientKeyRequest>(body)
+        let mut command = serde_json::from_value::<UpdateClientKeyRequest>(body)
             .unwrap()
             .into_command()
-            .unwrap()
-            .xai_client_profile_override
+            .unwrap();
+        command
+            .request_profile_override_updates
+            .remove(&gateway_core::routing::ProviderKind::new("xai").expect("Provider kind"))
     };
     assert_eq!(decode(payload.clone()), None);
     payload["xaiClientProfileOverride"] = json!(null);
@@ -604,3 +607,58 @@ fn xai_profile_override_distinguishes_omission_from_explicit_inheritance() {
     payload["xaiClientProfileOverride"] = json!({"versionMode":"latest"});
     assert!(decode(payload).unwrap().is_some());
 }
+
+#[test]
+fn generic_profile_overrides_accept_dynamic_providers_and_reject_legacy_conflicts() {
+    let profile = json!({"preset":"desktop"});
+    let dynamic = json!({"preset":"managed"});
+    let request: CreateClientKeyRequest = serde_json::from_value(json!({
+        "name":"profile",
+        "groupIds":[],
+        "maxConcurrency":0,
+        "requestsPerMinute":0,
+        "providerRequestProfileOverrides": {
+            "openai": profile,
+            "provider.example": dynamic,
+        },
+        "openaiClientProfileOverride": {"preset":"desktop"},
+    }))
+    .unwrap();
+    let command = request.into_command().unwrap();
+    assert_eq!(command.request_profile_overrides.len(), 2);
+    assert!(command.request_profile_overrides.contains_key(
+        &gateway_core::routing::ProviderKind::new("provider.example").expect("Provider kind")
+    ));
+
+    let conflict: CreateClientKeyRequest = serde_json::from_value(json!({
+        "name":"profile",
+        "groupIds":[],
+        "maxConcurrency":0,
+        "requestsPerMinute":0,
+        "providerRequestProfileOverrides": {"openai":{"preset":"desktop"}},
+        "openaiClientProfileOverride": {"preset":"cli"},
+    }))
+    .unwrap();
+    assert_eq!(
+        conflict.into_command().unwrap_err().field(),
+        "providerRequestProfileOverrides"
+    );
+}
+
+#[test]
+fn generic_profile_override_clear_rejects_conflicting_legacy_update() {
+    let request: UpdateClientKeyRequest = serde_json::from_value(json!({
+        "id":"key_profile",
+        "name":"profile",
+        "groupIds":[],
+        "maxConcurrency":0,
+        "requestsPerMinute":0,
+        "providerRequestProfileOverrides": {"xai":null},
+        "xaiClientProfileOverride": {"preset":"desktop"},
+    }))
+    .unwrap();
+    assert_eq!(
+        request.into_command().unwrap_err().field(),
+        "providerRequestProfileOverrides"
+    );
+}
diff --git a/backend/crates/gateway-api/tests/admin/mod.rs b/backend/crates/gateway-api/tests/admin/mod.rs
index e7475c8cf..0989b4e99 100644
--- a/backend/crates/gateway-api/tests/admin/mod.rs
+++ b/backend/crates/gateway-api/tests/admin/mod.rs
@@ -1,3 +1,4 @@
+mod plugins;
 use std::{
     collections::BTreeMap,
     sync::{
@@ -41,10 +42,10 @@ use gateway_admin::{
         provider_credentials::{
             AuthorizationCommit, AuthorizationStarted, CompleteAuthorization, CredentialDetails,
             CredentialImportCommit, CredentialImportResult, CredentialMutationResult,
-            CredentialRotationCommit, PendingAuthorizationMutation, PrepareCredentialImport,
-            PrepareCredentialRefresh, PrepareCredentialRotation, PreparedAuthorizationCommit,
-            PreparedCredentialImport, PreparedCredentialRotation, ProviderExport,
-            ProviderExportCredentialInput, ProviderModels, ProviderQuota,
+            CredentialRotationCommit, PrepareCredentialImport, PrepareCredentialRefresh,
+            PrepareCredentialRotation, PreparedAuthorizationCommit, PreparedCredentialImport,
+            PreparedCredentialRotation, ProviderExport, ProviderExportCredentialInput,
+            ProviderModels, ProviderQuota,
         },
         settings::{
             AdminApiKey, AdminApiKeyMutation, ModelMappings, ReplaceRuntimeSettings,
@@ -91,6 +92,8 @@ mod wire;
 
 pub(super) struct AdminTestFixture {
     pub services: AdminServices,
+    plugin_ports: Arc<plugins::TestPluginPorts>,
+    published_snapshot: gateway_core::runtime::RuntimeSnapshotHandle,
     pub client_key: Arc<Mutex<Option<ClientKeyRecord>>>,
     pub observations: Arc<Mutex<MemoryObservations>>,
     pub auth: Arc<MemoryAuthStore>,
@@ -150,6 +153,8 @@ impl AdminTestFixture {
             dashboard_summary_range: Arc::clone(&dashboard_summary_range),
             account: Arc::clone(&account),
         });
+        let plugin_ports = Arc::new(plugins::TestPluginPorts::default());
+        let published_snapshot = gateway_core::runtime::RuntimeSnapshotHandle::default();
         let stores = AdminStorePorts::new(
             AdminAccountStorePorts::new(
                 unused.clone(),
@@ -162,6 +167,8 @@ impl AdminTestFixture {
             unused,
             settings.clone(),
             gateway_admin::ports::backup::BackupStorePorts::disabled(),
+            plugin_ports.clone(),
+            plugin_ports.clone(),
         );
         let providers: Vec<Arc<dyn ProviderAdmin>> = vec![
             Arc::new(UnusedProvider::new("openai", Arc::clone(&provider_error))),
@@ -176,8 +183,14 @@ impl AdminTestFixture {
             ClientConfig::default(),
             stores,
             gateway_admin::AdminRuntimePorts {
+                plugin_preparation: plugin_ports.clone(),
+                plugin_management: plugin_ports.clone(),
+                published_snapshot: published_snapshot.clone(),
+                plugin_inspector: plugin_ports.clone(),
+                plugin_distribution: plugin_ports.clone(),
                 pricing_source: Arc::new(StaticPricingSource),
-                providers,
+                providers: gateway_admin::ports::provider::ProviderAdminRegistry::new(providers)
+                    .unwrap(),
                 snapshot: Arc::new(NoopSnapshot),
                 account_probe: Arc::new(NoopProbe),
                 proxy_probe: Arc::new(proxies::SuccessfulProbe),
@@ -190,6 +203,8 @@ impl AdminTestFixture {
         .expect("initialize test admin services");
         Self {
             services: bundle.services(),
+            plugin_ports,
+            published_snapshot,
             client_key,
             observations,
             auth,
@@ -519,9 +534,16 @@ impl SettingsStore for MemorySettingsStore {
         _: &MutationContext,
     ) -> AdminStoreResult<RuntimeSettings> {
         let mut settings = self.settings.lock().expect("settings");
+        let mut request_profiles = settings.request_profiles.clone();
+        for (provider, profile) in command.request_profile_updates {
+            if let Some(profile) = profile {
+                request_profiles.insert(provider, profile);
+            } else {
+                request_profiles.remove(&provider);
+            }
+        }
         let updated = RuntimeSettings {
-            openai_client_profile: None,
-            xai_client_profile: None,
+            request_profiles,
             request_location_enabled: command.request_location_enabled,
             request_location: command.request_location,
             config_revision: next_revision(settings.config_revision),
@@ -896,8 +918,7 @@ impl ClientKeyStore for MemoryClientKeyStore {
         let now = Utc::now();
         Ok(Some(ClientKeySecret::new(
             ClientKeyRecord {
-                openai_client_profile_override: None,
-                xai_client_profile_override: None,
+                request_profile_overrides: Default::default(),
                 budget: Default::default(),
                 id: id.clone(),
                 name: "revealed".to_owned(),
@@ -969,6 +990,13 @@ impl ClientKeyVerifier for UnusedClientKeyVerifier {
 
 #[async_trait]
 impl AccountStore for UnusedStore {
+    async fn list_plugin_accounts(
+        &self,
+        _: gateway_admin::model::provider_credentials::PluginAccountListQuery,
+    ) -> AdminStoreResult<gateway_admin::model::provider_credentials::PluginAccountPage> {
+        Err(unavailable("plugin account list"))
+    }
+
     async fn list_accounts(
         &self,
         _: AccountListQuery,
@@ -1018,6 +1046,13 @@ impl AccountStore for UnusedStore {
         Err(unavailable("credential"))
     }
 
+    async fn credential_details_by_id(
+        &self,
+        _: &ProviderAccountId,
+    ) -> AdminStoreResult<Option<CredentialDetails>> {
+        Err(unavailable("plugin credential"))
+    }
+
     async fn load_credentials_for_export(
         &self,
         _: &ProviderKind,
@@ -1026,6 +1061,13 @@ impl AccountStore for UnusedStore {
         Err(unavailable("credential export"))
     }
 
+    async fn load_credential_for_plugin(
+        &self,
+        _: &ProviderAccountId,
+    ) -> AdminStoreResult<Option<ProviderExportCredentialInput>> {
+        Err(unavailable("plugin credential export"))
+    }
+
     async fn commit_credential_import(
         &self,
         _: CredentialImportCommit,
@@ -1034,11 +1076,21 @@ impl AccountStore for UnusedStore {
         Err(unavailable("credential import"))
     }
 
+    async fn authorization_receipt(
+        &self,
+        _: &gateway_admin::model::provider_credentials::AuthorizationReceiptKey,
+    ) -> AdminStoreResult<
+        Option<gateway_admin::model::provider_credentials::CredentialBatchMutationResult>,
+    > {
+        Ok(None)
+    }
+
     async fn commit_authorization(
         &self,
         _: AuthorizationCommit,
         _: &MutationContext,
-    ) -> AdminStoreResult<CredentialMutationResult> {
+    ) -> AdminStoreResult<gateway_admin::model::provider_credentials::AuthorizationCommitResult>
+    {
         Err(unavailable("authorization"))
     }
 
@@ -1189,6 +1241,10 @@ impl ObservabilityStore for UnusedStore {
         }))
     }
 
+    async fn usage_provider_kinds(&self, _: TimeRange) -> AdminStoreResult<Vec<String>> {
+        Ok(vec!["retired-provider".into()])
+    }
+
     async fn list_usage_records(&self, query: UsageQuery) -> AdminStoreResult<UsagePage> {
         self.observations
             .lock()
@@ -1281,7 +1337,7 @@ impl ProviderAdmin for UnusedProvider {
 
     async fn account_unavailable(&self, _: &ProviderAccountId) {}
 
-    fn connection_test_operation(
+    async fn connection_test_operation(
         &self,
         _: &gateway_core::routing::UpstreamModelId,
         _: &str,
@@ -1319,7 +1375,7 @@ impl ProviderAdmin for UnusedProvider {
 
     async fn start_authorization(
         &self,
-        _: PendingAuthorizationMutation,
+        _: gateway_admin::model::provider_credentials::PrepareAuthorization,
     ) -> Result<AuthorizationStarted, ProviderAdminError> {
         Err(unsupported_provider())
     }
@@ -1331,6 +1387,23 @@ impl ProviderAdmin for UnusedProvider {
         Err(unsupported_provider())
     }
 
+    async fn poll_authorization(
+        &self,
+        _: gateway_admin::model::provider_credentials::PollAuthorization,
+    ) -> Result<
+        gateway_admin::model::provider_credentials::PreparedAuthorizationPoll,
+        ProviderAdminError,
+    > {
+        if let Some(error) = self.error.lock().expect("provider error").clone() {
+            return Err(error);
+        }
+        Ok(
+            gateway_admin::model::provider_credentials::PreparedAuthorizationPoll::Pending {
+                retry_after: std::time::Duration::from_millis(1250),
+            },
+        )
+    }
+
     async fn prepare_rotation(
         &self,
         _: PrepareCredentialRotation,
@@ -1387,6 +1460,7 @@ impl AccountProbe for NoopProbe {
     fn probe(
         &self,
         _: AccountProbeRequest,
+        _: Option<Arc<gateway_core::routing::RuntimeSnapshot>>,
     ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
         Box::pin(async { panic!("unused account probe") })
     }
@@ -1411,6 +1485,7 @@ impl SystemOperations for UnusedSystem {
     async fn perform_update(
         &self,
         _: Option<String>,
+        _: Arc<dyn gateway_admin::ports::system::SystemUpdatePreflight>,
     ) -> Result<SystemOperationAccepted, SystemOperationError> {
         Err(unavailable_system())
     }
@@ -1419,7 +1494,10 @@ impl SystemOperations for UnusedSystem {
         Err(unavailable_system())
     }
 
-    async fn rollback(&self) -> Result<SystemOperationAccepted, SystemOperationError> {
+    async fn rollback(
+        &self,
+        _: Arc<dyn gateway_admin::ports::system::SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError> {
         Err(unavailable_system())
     }
 
@@ -1440,8 +1518,7 @@ fn test_runtime_settings() -> RuntimeSettings {
         ),
     ]);
     RuntimeSettings {
-        openai_client_profile: None,
-        xai_client_profile: None,
+        request_profiles: Default::default(),
         request_location_enabled: false,
         request_location: Default::default(),
         config_revision: Revision::new(7).expect("revision"),
diff --git a/backend/crates/gateway-api/tests/admin/observability/response.rs b/backend/crates/gateway-api/tests/admin/observability/response.rs
index d1d4b3b7b..1a4bd618c 100644
--- a/backend/crates/gateway-api/tests/admin/observability/response.rs
+++ b/backend/crates/gateway-api/tests/admin/observability/response.rs
@@ -10,6 +10,67 @@ use gateway_api::admin::observability::{
 };
 use serde_json::json;
 
+#[tokio::test]
+async fn usage_provider_filters_require_admin_and_validate_the_range() {
+    use crate::admin::{AdminTestFixture, AdminTestState};
+    use axum::{
+        body::{Body, to_bytes},
+        http::{Request, StatusCode, header},
+    };
+    use gateway_api::admin::observability;
+    use tower::ServiceExt as _;
+
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let app = observability::router::<AdminTestState>().with_state(fixture.state());
+    let anonymous = app
+        .clone()
+        .oneshot(
+            Request::builder()
+                .uri("/api/admin/usage/providers")
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(anonymous.status(), StatusCode::UNAUTHORIZED);
+    for query in [
+        "startTime=invalid",
+        "startTime=2026-02-02T00:00:00Z&endTime=2026-02-01T00:00:00Z",
+        "startTime=2024-01-01T00:00:00Z&endTime=2026-01-01T00:00:00Z",
+        "provider=openai",
+    ] {
+        let response = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .uri(format!("/api/admin/usage/providers?{query}"))
+                    .header(header::COOKIE, "cpr_session=valid-session")
+                    .header("x-request-id", "req_provider_filter_invalid")
+                    .body(Body::empty())
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(response.status(), StatusCode::BAD_REQUEST, "{query}");
+    }
+    let response = app
+        .oneshot(
+            Request::builder()
+                .uri("/api/admin/usage/providers?startTime=2026-02-01T00:00:00Z&endTime=2026-02-02T00:00:00Z")
+                .header(header::COOKIE, "cpr_session=valid-session")
+                .header("x-request-id", "req_provider_filter_valid")
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(response.status(), StatusCode::OK);
+    let body = to_bytes(response.into_body(), 1024).await.unwrap();
+    let value: serde_json::Value = serde_json::from_slice(&body).unwrap();
+    assert_eq!(value["data"], json!(["retired-provider"]));
+}
+
 #[test]
 fn usage_page_should_keep_terminal_camel_case_shape() {
     let data = PageData {
diff --git a/backend/crates/gateway-api/tests/admin/plugins/management.rs b/backend/crates/gateway-api/tests/admin/plugins/management.rs
new file mode 100644
index 000000000..33fa81e20
--- /dev/null
+++ b/backend/crates/gateway-api/tests/admin/plugins/management.rs
@@ -0,0 +1,680 @@
+use axum::{
+    body::Body,
+    http::{Request, StatusCode},
+};
+use futures::future::BoxFuture;
+use gateway_core::{
+    engine::{
+        execution::{
+            AuthenticatedClient, ClientAuthenticationError, ExecutionService,
+            PreparedRootExecution, StartExecution, StartProviderExecution, StartedExecution,
+        },
+        middleware::{
+            FrozenMiddlewarePlan, MiddlewareBody, MiddlewareContext, MiddlewareError,
+            MiddlewareFrame, MiddlewareFraming, MiddlewareHeader, MiddlewareNext, MiddlewarePlan,
+            MiddlewareRequest, MiddlewareResponse,
+        },
+    },
+    error::GatewayError,
+    lifecycle::CancellationToken,
+    policy::ClientApiKeyId,
+    routing::PublicModelId,
+    runtime::extensions::{ExtensionSetId, ExtensionSetLease, ExtensionSetReference},
+};
+use std::sync::{
+    Arc, Mutex,
+    atomic::{AtomicBool, Ordering},
+};
+use tower::ServiceExt as _;
+
+use super::super::AdminTestFixture;
+
+#[derive(Debug, Clone, Copy)]
+enum ModelReply {
+    Complete,
+    PendingResponse,
+    PendingBody,
+}
+
+struct ModelExecution {
+    reply: ModelReply,
+    cancellation: Mutex<Option<CancellationToken>>,
+    entered: Arc<tokio::sync::Notify>,
+    closed: Arc<AtomicBool>,
+}
+
+impl ModelExecution {
+    fn new(reply: ModelReply) -> Arc<Self> {
+        Arc::new(Self {
+            reply,
+            cancellation: Mutex::new(None),
+            entered: Arc::default(),
+            closed: Arc::default(),
+        })
+    }
+}
+
+impl ExecutionService for ModelExecution {
+    fn authenticate(&self, _: &str) -> Result<AuthenticatedClient, ClientAuthenticationError> {
+        panic!("管理模型桥不能使用管理 Cookie 或 Bearer 作为 Client Key")
+    }
+    fn public_models(&self, _: &AuthenticatedClient) -> Vec<PublicModelId> {
+        vec![]
+    }
+    fn contains_public_model(&self, _: &AuthenticatedClient, _: &PublicModelId) -> bool {
+        true
+    }
+    fn prepare_plugin_execution(
+        &self,
+        key: &ClientApiKeyId,
+    ) -> BoxFuture<'_, Result<PreparedRootExecution, GatewayError>> {
+        assert_eq!(key.as_str(), "client-key");
+        Box::pin(async move {
+            let prepared = self
+                .prepare_execution(crate::openai::authenticated_client("fixture-client-key"))
+                .await?;
+            *self.cancellation.lock().unwrap() = Some(prepared.cancellation());
+            Ok(prepared)
+        })
+    }
+    fn middleware_plan(&self, _: &PreparedRootExecution) -> Option<FrozenMiddlewarePlan> {
+        Some(FrozenMiddlewarePlan::new(
+            Arc::new(ModelMiddleware {
+                reply: self.reply,
+                entered: self.entered.clone(),
+                closed: self.closed.clone(),
+            }),
+            ExtensionSetReference::new(
+                ExtensionSetId::new("model-bridge-test".into()).unwrap(),
+                Arc::new(ModelLease),
+            ),
+        ))
+    }
+    fn start(&self, _: StartExecution) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        panic!("测试中间件直接返回响应")
+    }
+    fn start_provider_endpoint(
+        &self,
+        _: StartProviderExecution,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        panic!("Responses 不走 Provider 端点")
+    }
+}
+
+struct ModelLease;
+impl ExtensionSetLease for ModelLease {
+    fn is_ready(&self) -> bool {
+        true
+    }
+}
+
+#[derive(Debug)]
+struct ModelMiddleware {
+    reply: ModelReply,
+    entered: Arc<tokio::sync::Notify>,
+    closed: Arc<AtomicBool>,
+}
+
+impl MiddlewarePlan for ModelMiddleware {
+    fn handle(
+        &self,
+        _: MiddlewareContext,
+        request: MiddlewareRequest,
+        _: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        for header in request.headers() {
+            assert!(!["cookie", "authorization", "x-api-key"].contains(&header.name()));
+        }
+        assert!(
+            request
+                .headers()
+                .iter()
+                .any(|header| header.name() == "content-type")
+        );
+        let reply = self.reply;
+        let closed = self.closed.clone();
+        let entered = self.entered.clone();
+        Box::pin(async move {
+            entered.notify_one();
+            if matches!(reply, ModelReply::PendingResponse) {
+                return futures::future::pending().await;
+            }
+            let (bytes, framing, terminal) = if matches!(reply, ModelReply::PendingBody) {
+                (
+                    "event: response.created\ndata: {\"type\":\"response.created\",\"response\":{\"id\":\"resp_bridge\",\"object\":\"response\",\"status\":\"in_progress\",\"output\":[]}}\n\n",
+                    MiddlewareFraming::SseEvent,
+                    false,
+                )
+            } else {
+                (
+                    "{\"id\":\"resp_bridge\",\"object\":\"response\",\"status\":\"completed\",\"output\":[]}",
+                    MiddlewareFraming::JsonDocument,
+                    true,
+                )
+            };
+            Ok(MiddlewareResponse::new(
+                "openai".into(),
+                200,
+                vec![
+                    MiddlewareHeader::new("set-cookie", "fixture=value".into()),
+                    MiddlewareHeader::new("www-authenticate", "Bearer".into()),
+                ],
+                Box::new(ModelBody {
+                    frame: Some(MiddlewareFrame::new(bytes.into(), framing, terminal)),
+                    pending: !terminal,
+                    closed,
+                }),
+            ))
+        })
+    }
+}
+
+struct ModelBody {
+    frame: Option<MiddlewareFrame>,
+    pending: bool,
+    closed: Arc<AtomicBool>,
+}
+
+impl MiddlewareBody for ModelBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async move {
+            if let Some(frame) = self.frame.take() {
+                return Ok(Some(frame));
+            }
+            if self.pending {
+                return futures::future::pending().await;
+            }
+            Ok(None)
+        })
+    }
+    fn close(self: Box<Self>) -> BoxFuture<'static, ()> {
+        Box::pin(async move {
+            self.closed.store(true, Ordering::SeqCst);
+        })
+    }
+}
+
+fn model_request(stream: bool) -> Request<Body> {
+    Request::post(format!("/api/admin/plugins/extensions/plugin-instance-diagnostic/{}/7/models/responses?clientKeyId=client-key", "a".repeat(64)))
+        .header("cookie", "cpr_session=management-session")
+        .header("authorization", "Bearer admin-fixture")
+        .header("x-api-key", format!("admin-{}", "a".repeat(64)))
+        .header("content-type", "application/json")
+        .body(Body::from(serde_json::json!({"model":"model-a", "input":"hello", "stream":stream}).to_string())).unwrap()
+}
+
+#[tokio::test]
+async fn model_bridge_executes_and_protects_request_and_response_headers() {
+    let fixture = published_fixture().await;
+    let execution = ModelExecution::new(ModelReply::Complete);
+    let response = crate::openai::api_router_with_admin_and_execution(fixture.services, execution)
+        .oneshot(model_request(false))
+        .await
+        .unwrap();
+    assert_eq!(response.status(), StatusCode::OK);
+    assert!(!response.headers().contains_key("set-cookie"));
+    assert!(!response.headers().contains_key("www-authenticate"));
+    assert_eq!(response.headers()["x-content-type-options"], "nosniff");
+    assert_eq!(response.headers()["referrer-policy"], "no-referrer");
+    assert_eq!(response.headers()["cache-control"], "no-store");
+    let body = axum::body::to_bytes(response.into_body(), 4096)
+        .await
+        .unwrap();
+    assert_eq!(
+        serde_json::from_slice::<serde_json::Value>(&body).unwrap()["id"],
+        "resp_bridge"
+    );
+}
+
+#[tokio::test(start_paused = true)]
+async fn model_bridge_revokes_while_waiting_for_the_first_response() {
+    let fixture = published_fixture().await;
+    let execution = ModelExecution::new(ModelReply::PendingResponse);
+    let router =
+        crate::openai::api_router_with_admin_and_execution(fixture.services, execution.clone());
+    let request = tokio::spawn(router.oneshot(model_request(false)));
+    tokio::time::timeout(
+        std::time::Duration::from_secs(5),
+        execution.entered.notified(),
+    )
+    .await
+    .expect("请求已进入模型执行链");
+    *fixture.plugin_ports.instances.lock().unwrap() = Some(vec![]);
+    tokio::time::advance(std::time::Duration::from_secs(1)).await;
+    assert_eq!(
+        request.await.unwrap().unwrap().status(),
+        StatusCode::FORBIDDEN
+    );
+    assert!(
+        execution
+            .cancellation
+            .lock()
+            .unwrap()
+            .as_ref()
+            .unwrap()
+            .is_cancelled()
+    );
+}
+
+#[tokio::test(start_paused = true)]
+async fn model_bridge_revokes_and_closes_a_pending_stream() {
+    let fixture = published_fixture().await;
+    let execution = ModelExecution::new(ModelReply::PendingBody);
+    let response =
+        crate::openai::api_router_with_admin_and_execution(fixture.services, execution.clone())
+            .oneshot(model_request(true))
+            .await
+            .unwrap();
+    assert_eq!(response.status(), StatusCode::OK);
+    let body = tokio::spawn(axum::body::to_bytes(response.into_body(), 4096));
+    *fixture.plugin_ports.instances.lock().unwrap() = Some(vec![]);
+    tokio::time::advance(std::time::Duration::from_secs(1)).await;
+    let body = body.await.unwrap().unwrap();
+    let body = std::str::from_utf8(&body).unwrap();
+    assert!(body.contains("response.failed"));
+    assert!(!body.contains("response.completed"));
+    assert!(body.ends_with("data: [DONE]\n\n"));
+    assert!(
+        execution
+            .cancellation
+            .lock()
+            .unwrap()
+            .as_ref()
+            .unwrap()
+            .is_cancelled()
+    );
+    assert!(execution.closed.load(Ordering::SeqCst));
+}
+
+pub(super) fn resource_fixture(
+    path: &str,
+) -> gateway_admin::model::plugins::management::PluginManagementResponse {
+    gateway_admin::model::plugins::management::PluginManagementResponse {
+        status: if path == "missing" { 404 } else { 200 },
+        content_type: if path.ends_with(".css") {
+            "text/css"
+        } else {
+            "text/html"
+        }
+        .into(),
+        body: std::sync::Arc::from(path.as_bytes()),
+    }
+}
+
+async fn published_fixture() -> AdminTestFixture {
+    use gateway_core::{
+        account::{AccountSelectionPolicy, RotationStrategy},
+        routing::{ConfigRevision, RuntimeSnapshot},
+        runtime::extensions::{ExtensionSetId, ExtensionSetLease, ExtensionSetReference},
+    };
+    use std::{num::NonZeroU32, sync::Arc, time::Duration};
+    struct Lease;
+    impl ExtensionSetLease for Lease {
+        fn is_ready(&self) -> bool {
+            true
+        }
+    }
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("management-session");
+    fixture
+        .auth
+        .set_api_key(&format!("admin-{}", "a".repeat(64)));
+    fixture.published_snapshot.publish(
+        RuntimeSnapshot::new(
+            ConfigRevision::new(7).unwrap(),
+            AccountSelectionPolicy::new(
+                RotationStrategy::Smart,
+                NonZeroU32::new(1).unwrap(),
+                Duration::ZERO,
+            ),
+            vec![],
+            vec![],
+            vec![],
+        )
+        .unwrap()
+        .with_extensions(Some(ExtensionSetReference::new(
+            ExtensionSetId::new("management-test".into()).unwrap(),
+            Arc::new(Lease),
+        ))),
+    );
+    fixture
+}
+
+async fn resource_request(
+    fixture: &AdminTestFixture,
+    method: &str,
+    uri: &str,
+    session: bool,
+    validators: &[&str],
+) -> axum::response::Response {
+    let mut request = Request::builder()
+        .method(method)
+        .uri(uri)
+        .header("x-request-id", "management-cache-test");
+    if session {
+        request = request.header("cookie", "cpr_session=management-session");
+    }
+    for validator in validators {
+        request = request.header("if-none-match", *validator);
+    }
+    crate::openai::api_router_with_admin_and_execution(
+        fixture.services.clone(),
+        ModelExecution::new(ModelReply::Complete),
+    )
+    .oneshot(request.body(Body::empty()).unwrap())
+    .await
+    .unwrap()
+}
+
+#[tokio::test]
+async fn static_resources_revalidate_privately_after_authorization() {
+    use axum::body::to_bytes;
+    use gateway_admin::ports::plugins::PluginStore as _;
+
+    let fixture = published_fixture().await;
+    let prefix = format!(
+        "/api/admin/plugins/extensions/plugin-instance-diagnostic/{}/7",
+        "a".repeat(64)
+    );
+    let uri = format!("{prefix}/resources/ui/index.html");
+    let first = resource_request(&fixture, "GET", &uri, true, &[]).await;
+    assert_eq!(first.status(), StatusCode::OK);
+    assert_eq!(first.headers()["cache-control"], "private, no-cache");
+    let etag = first.headers()["etag"].to_str().unwrap().to_owned();
+    let csp = first.headers()["content-security-policy"].clone();
+    assert_eq!(
+        to_bytes(first.into_body(), 1024).await.unwrap(),
+        "ui/index.html"
+    );
+
+    for validators in [
+        vec![etag.as_str()],
+        vec!["*"],
+        vec!["\"other,tag\"", etag.as_str()],
+        vec!["\"other\"", &format!("W/{etag}")],
+    ] {
+        for method in ["GET", "HEAD"] {
+            let response = resource_request(&fixture, method, &uri, true, &validators).await;
+            assert_eq!(
+                response.status(),
+                StatusCode::NOT_MODIFIED,
+                "{validators:?}"
+            );
+            assert_eq!(response.headers()["etag"], etag);
+            assert_eq!(response.headers()["cache-control"], "private, no-cache");
+            assert_eq!(response.headers()["content-security-policy"], csp);
+            assert_eq!(response.headers()["x-content-type-options"], "nosniff");
+            assert!(
+                to_bytes(response.into_body(), 1024)
+                    .await
+                    .unwrap()
+                    .is_empty()
+            );
+        }
+    }
+    for validators in [vec!["\"other\""], vec!["invalid"]] {
+        assert_eq!(
+            resource_request(&fixture, "GET", &uri, true, &validators)
+                .await
+                .status(),
+            StatusCode::OK
+        );
+    }
+    let changed = resource_request(
+        &fixture,
+        "GET",
+        &format!("{prefix}/resources/ui/other.css"),
+        true,
+        &[&etag],
+    )
+    .await;
+    assert_eq!(changed.status(), StatusCode::OK);
+    assert_ne!(changed.headers()["etag"], etag);
+    let unauthenticated = resource_request(&fixture, "GET", &uri, false, &[&etag]).await;
+    assert_eq!(unauthenticated.status(), StatusCode::UNAUTHORIZED);
+    assert_eq!(unauthenticated.headers()["cache-control"], "no-store");
+
+    let original = fixture
+        .plugin_ports
+        .load_instances()
+        .await
+        .unwrap()
+        .instances;
+    for change in ["disable", "untrust", "revision", "version"] {
+        let mut instances = original.clone();
+        match change {
+            "disable" => instances[0].enabled = false,
+            "untrust" => instances[0].trusted_process = false,
+            "revision" => instances[0].revision = gateway_admin::model::Revision::new(8).unwrap(),
+            _ => instances[0].artifact_sha256 = "b".repeat(64),
+        }
+        *fixture.plugin_ports.instances.lock().unwrap() = Some(instances);
+        let response = resource_request(&fixture, "GET", &uri, true, &[&etag]).await;
+        assert_eq!(response.status(), StatusCode::CONFLICT, "{change}");
+        assert_eq!(response.headers()["cache-control"], "no-store");
+        assert!(!response.headers().contains_key("etag"));
+    }
+}
+
+#[tokio::test]
+async fn public_resources_cache_but_dynamic_calls_callbacks_and_errors_do_not() {
+    let fixture = published_fixture().await;
+    let target = format!("plugin-instance-diagnostic/{}/7", "a".repeat(64));
+    let public = format!("/plugins/resources/{target}/public/login.css");
+    let first = resource_request(&fixture, "GET", &public, false, &[]).await;
+    assert_eq!(first.status(), StatusCode::OK);
+    let etag = first.headers()["etag"].to_str().unwrap();
+    assert_eq!(
+        resource_request(&fixture, "GET", &public, false, &[etag])
+            .await
+            .status(),
+        StatusCode::NOT_MODIFIED
+    );
+    for (uri, status) in [
+        (
+            format!("/plugins/resources/{target}/ui/index.html"),
+            StatusCode::NOT_FOUND,
+        ),
+        (
+            format!("/api/admin/plugins/extensions/{target}/resources/missing"),
+            StatusCode::NOT_FOUND,
+        ),
+        (
+            format!("/api/admin/plugins/extensions/{target}/api/echo"),
+            StatusCode::OK,
+        ),
+        (
+            format!("/plugins/callbacks/{target}/oauth?state=nonce"),
+            StatusCode::OK,
+        ),
+    ] {
+        let response = resource_request(&fixture, "GET", &uri, true, &["*"]).await;
+        assert_eq!(response.status(), status, "{uri}");
+        assert_eq!(response.headers()["cache-control"], "no-store");
+        assert!(!response.headers().contains_key("etag"));
+    }
+    *fixture.plugin_ports.instances.lock().unwrap() = Some(vec![]);
+    let response = resource_request(&fixture, "GET", &public, false, &[etag]).await;
+    assert_eq!(response.status(), StatusCode::CONFLICT);
+    assert_eq!(response.headers()["cache-control"], "no-store");
+}
+
+#[tokio::test]
+async fn model_responses_requires_the_exact_authorized_target_before_execution() {
+    let fixture = published_fixture().await;
+    let target = format!("plugin-instance-diagnostic/{}/7", "a".repeat(64));
+    let request = |target: &str, query: &str| {
+        Request::builder()
+            .method("POST")
+            .uri(format!(
+                "/api/admin/plugins/extensions/{target}/models/responses?{query}"
+            ))
+            .header("cookie", "cpr_session=management-session")
+            .header("content-type", "application/json")
+            .header("x-request-id", "management-model-request")
+            .body(Body::from(
+                serde_json::json!({"model":"model-a","input":"hello","stream":false}).to_string(),
+            ))
+            .unwrap()
+    };
+
+    let response = crate::openai::api_router_with_admin_and_execution(
+        fixture.services.clone(),
+        ModelExecution::new(ModelReply::Complete),
+    )
+    .oneshot(request(&target, "clientKeyId=client-key"))
+    .await
+    .unwrap();
+    assert_eq!(
+        response.status(),
+        StatusCode::OK,
+        "精确目标通过授权后应执行并返回结果"
+    );
+
+    for changed in [
+        format!("plugin-instance-diagnostic/{}/8", "a".repeat(64)),
+        format!("plugin-instance-diagnostic/{}/7", "b".repeat(64)),
+    ] {
+        let response = crate::openai::api_router_with_admin_and_execution(
+            fixture.services.clone(),
+            ModelExecution::new(ModelReply::Complete),
+        )
+        .oneshot(request(&changed, "clientKeyId=client-key"))
+        .await
+        .unwrap();
+        assert_eq!(response.status(), StatusCode::CONFLICT);
+    }
+
+    let response = crate::openai::api_router_with_admin_and_execution(
+        fixture.services.clone(),
+        ModelExecution::new(ModelReply::Complete),
+    )
+    .oneshot(request(
+        &target,
+        "clientKeyId=client-key&accountId=forbidden",
+    ))
+    .await
+    .unwrap();
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+}
+
+#[tokio::test]
+async fn protected_plugin_routes_require_admin_before_reading_bodies_but_public_resources_do_not() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("management-session");
+    let prefix = "/api/admin/plugins/extensions/instance/sha256/1";
+    for (method, uri) in [
+        ("GET", "/api/admin/plugins/extensions".to_owned()),
+        ("GET", format!("{prefix}/resources/ui/index.html")),
+        ("POST", format!("{prefix}/api/echo")),
+        ("POST", format!("{prefix}/callback-tickets")),
+        (
+            "POST",
+            format!("{prefix}/models/responses?clientKeyId=client-key"),
+        ),
+    ] {
+        let response = crate::openai::api_router_with_admin_and_execution(
+            fixture.services.clone(),
+            ModelExecution::new(ModelReply::Complete),
+        )
+        .oneshot(
+            Request::builder()
+                .method(method)
+                .uri(uri)
+                .header("x-request-id", "management-test")
+                .body(Body::from_stream(futures::stream::poll_fn(
+                    |_| -> std::task::Poll<Option<Result<bytes::Bytes, std::io::Error>>> {
+                        panic!("未认证请求不能读取正文")
+                    },
+                )))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
+        assert_eq!(response.headers()["cache-control"], "no-store");
+    }
+    let response = crate::openai::api_router_with_admin_and_execution(
+        fixture.services.clone(),
+        ModelExecution::new(ModelReply::Complete),
+    )
+    .oneshot(
+        Request::builder()
+            .uri("/plugins/resources/instance/sha256/1/ui/index.html")
+            .body(Body::empty())
+            .unwrap(),
+    )
+    .await
+    .unwrap();
+    assert_eq!(
+        response.status(),
+        StatusCode::SERVICE_UNAVAILABLE,
+        "公开资源仍要求可用的发布视图，不能绕过实例授权"
+    );
+    let response = crate::openai::api_router_with_admin_and_execution(
+        fixture.services.clone(),
+        ModelExecution::new(ModelReply::Complete),
+    )
+    .oneshot(
+        Request::builder()
+            .method("POST")
+            .uri(format!("{prefix}/api/echo"))
+            .header("x-request-id", "management-limit")
+            .header("cookie", "cpr_session=management-session")
+            .header("content-type", "application/octet-stream")
+            .body(Body::from(vec![0_u8; 1024 * 1024 + 1]))
+            .unwrap(),
+    )
+    .await
+    .unwrap();
+    assert_eq!(response.status(), StatusCode::PAYLOAD_TOO_LARGE);
+
+    let response = crate::openai::api_router_with_admin_and_execution(
+        fixture.services.clone(),
+        ModelExecution::new(ModelReply::Complete),
+    )
+    .oneshot(
+        Request::builder()
+            .method("POST")
+            .uri(format!("{prefix}/models/responses?clientKeyId=client-key"))
+            .header("x-request-id", "management-model-limit")
+            .header("cookie", "cpr_session=management-session")
+            .header("content-type", "application/json")
+            .body(Body::from(vec![0_u8; 8 * 1024 * 1024 + 1]))
+            .unwrap(),
+    )
+    .await
+    .unwrap();
+    assert_eq!(response.status(), StatusCode::PAYLOAD_TOO_LARGE);
+}
+
+#[tokio::test]
+async fn public_callback_rejects_head_missing_duplicate_state_and_body_before_dispatch() {
+    let fixture = AdminTestFixture::new().await;
+    let prefix = "/plugins/callbacks/instance/sha256/1/oauth";
+    for (method, query, body, expected) in [
+        ("HEAD", "state=one", "", StatusCode::METHOD_NOT_ALLOWED),
+        ("GET", "code=one", "", StatusCode::BAD_REQUEST),
+        ("GET", "state=", "", StatusCode::BAD_REQUEST),
+        ("GET", "state=one&state=two", "", StatusCode::BAD_REQUEST),
+        ("GET", "state=one&%73tate=two", "", StatusCode::BAD_REQUEST),
+        ("GET", "state=one", "body", StatusCode::BAD_REQUEST),
+        // 合法 GET 没有管理 Cookie 仍进入服务；当前测试未发布视图，返回 503 而不是 401。
+        ("GET", "state=one", "", StatusCode::SERVICE_UNAVAILABLE),
+    ] {
+        let response = crate::openai::api_router_with_admin_and_execution(
+            fixture.services.clone(),
+            ModelExecution::new(ModelReply::Complete),
+        )
+        .oneshot(
+            Request::builder()
+                .method(method)
+                .uri(format!("{prefix}?{query}"))
+                .body(Body::from(body))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+        assert_eq!(response.status(), expected, "{method} {query}");
+    }
+}
diff --git a/backend/crates/gateway-api/tests/admin/plugins/mod.rs b/backend/crates/gateway-api/tests/admin/plugins/mod.rs
new file mode 100644
index 000000000..384e3cb51
--- /dev/null
+++ b/backend/crates/gateway-api/tests/admin/plugins/mod.rs
@@ -0,0 +1,1013 @@
+use async_trait::async_trait;
+use gateway_admin::model::plugins::distribution::{
+    DownloadedPlugin, GithubReleaseQuery, PluginRelease, RemotePluginLocation, SourceCredential,
+    SourceCredentialInfo,
+};
+use gateway_admin::model::plugins::distribution::{PluginSourceBinding, PluginUpdateSource};
+use gateway_admin::{
+    model::{
+        AdminError, MutationContext, Revision,
+        plugins::{
+            InspectedPluginArtifact, InstalledPluginArtifact, PluginArtifactIcon,
+            PluginArtifactIconResource, PluginArtifactMetadata, PluginArtifactMutation,
+            PluginIconTheme, PluginSource,
+            state::{
+                ApplyPluginStateMigration, DeletePluginState, PluginStateConfiguration,
+                PluginStateMigrationBatch, PluginStateOwner, PluginStateOwnerRequest,
+                PluginStateRecord, PluginStateTransition, PluginStateWrite, PutPluginState,
+            },
+        },
+    },
+    ports::{
+        plugins::{
+            PluginPackageInspector, PluginStateStore, PluginStateStoreError,
+            PluginStateStoreErrorKind, PluginStateStoreResult, PluginStore,
+        },
+        store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult},
+    },
+};
+use std::{collections::BTreeMap, sync::Arc};
+
+mod management;
+
+#[test]
+fn artifact_metadata_wire_exposes_v2_identity_and_contributions() {
+    use gateway_admin::model::plugins::{
+        PluginArtifactIcon, PluginArtifactIconVariants, PluginArtifactMetadata, PluginContribution,
+    };
+
+    let metadata = PluginArtifactMetadata {
+        plugin_id: "test.example".into(),
+        version: "1.0.0".into(),
+        name: "example".into(),
+        display_name: "Example".into(),
+        publisher: "test".into(),
+        author: None,
+        description: "fixture".into(),
+        license: "MIT".into(),
+        sha256: "a".repeat(64),
+        platforms: vec!["linux-x86_64".into()],
+        icon: Some(PluginArtifactIcon::Themed(PluginArtifactIconVariants {
+            light: "assets/icon-light.png".into(),
+            dark: "assets/icon-dark.webp".into(),
+        })),
+        contributes: BTreeMap::from([(
+            "middleware".into(),
+            PluginContribution {
+                id: "test.example.middleware".into(),
+                version: 1,
+                stages: vec!["attempt".into()],
+                input_formats: vec!["openai".into()],
+                output_formats: vec!["openai".into()],
+            },
+        )]),
+        requested_permissions: vec![],
+        configuration_schema: serde_json::json!({}),
+        secret_fields: vec![],
+        state_namespaces: vec![],
+    };
+    let value = serde_json::to_value(metadata).expect("v2 artifact metadata JSON");
+    assert_eq!(value["displayName"], "Example");
+    assert_eq!(value["publisher"], "test");
+    assert!(value["author"].is_null());
+    assert_eq!(value["icon"]["light"], "assets/icon-light.png");
+    assert_eq!(value["icon"]["dark"], "assets/icon-dark.webp");
+    assert_eq!(
+        value["contributes"]["middleware"]["id"],
+        "test.example.middleware"
+    );
+    assert!(value.get("capabilities").is_none());
+    assert!(value.get("permissionDescriptions").is_none());
+}
+
+#[test]
+fn instance_binding_wire_uses_contribution_without_capability_alias() {
+    use gateway_admin::model::plugins::instances::PluginCapabilityBinding;
+
+    let binding = serde_json::from_value::<PluginCapabilityBinding>(serde_json::json!({
+        "contribution": "test.example.usage",
+        "stage": "observation",
+        "order": 0,
+        "failurePolicy": "observe"
+    }))
+    .expect("v2 contribution binding");
+    assert_eq!(binding.contribution, "test.example.usage");
+
+    assert!(
+        serde_json::from_value::<PluginCapabilityBinding>(serde_json::json!({
+            "capability": "usage",
+            "stage": "observation",
+            "order": 0,
+            "failurePolicy": "observe"
+        }))
+        .is_err(),
+        "legacy capability binding must be rejected"
+    );
+}
+
+#[tokio::test]
+async fn artifact_icon_is_admin_only_digest_bound_and_hardened() {
+    use axum::{
+        body::{Body, to_bytes},
+        http::{Request, StatusCode},
+    };
+    use tower::ServiceExt as _;
+
+    let fixture = super::AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let digest = "f".repeat(64);
+    let response = gateway_api::admin::router::<super::AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri(format!(
+                    "/api/admin/plugins/artifacts/{digest}/icon?theme=light"
+                ))
+                .header("cookie", "cpr_session=valid-session")
+                .header("x-request-id", "req_plugin_icon")
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    let status = response.status();
+    let headers = response.headers().clone();
+    let body = to_bytes(response.into_body(), 1024).await.unwrap();
+    assert_eq!(status, StatusCode::OK, "{}", String::from_utf8_lossy(&body));
+    assert_eq!(headers["content-type"], "image/png");
+    assert_eq!(headers["x-content-type-options"], "nosniff");
+    assert_eq!(
+        headers["content-security-policy"],
+        "sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data:; base-uri 'none'; form-action 'none'"
+    );
+    assert_eq!(
+        headers["cache-control"],
+        "private, max-age=31536000, immutable"
+    );
+    assert_eq!(body.as_ref(), b"icon fixture");
+
+    let response = gateway_api::admin::router::<super::AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri(format!(
+                    "/api/admin/plugins/artifacts/{digest}/icon?theme=dark"
+                ))
+                .header("cookie", "cpr_session=valid-session")
+                .header("x-request-id", "req_plugin_svg_icon")
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(response.headers()["content-type"], "image/svg+xml");
+    assert_eq!(
+        response.headers()["content-security-policy"],
+        headers["content-security-policy"]
+    );
+    assert_eq!(response.headers()["x-content-type-options"], "nosniff");
+    assert_eq!(
+        response.headers()["cache-control"],
+        headers["cache-control"]
+    );
+    let body = to_bytes(response.into_body(), 1024).await.unwrap();
+    assert_eq!(
+        body.as_ref(),
+        br#"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"/>"#
+    );
+
+    let response = gateway_api::admin::router::<super::AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri(format!(
+                    "/api/admin/plugins/artifacts/{digest}/icon?theme=light"
+                ))
+                .header("x-request-id", "req_plugin_icon_unauthorized")
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
+
+    let response = gateway_api::admin::router::<super::AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri(format!(
+                    "/api/admin/plugins/artifacts/{}/icon?theme=light",
+                    "e".repeat(64)
+                ))
+                .header("cookie", "cpr_session=valid-session")
+                .header("x-request-id", "req_plugin_icon_missing")
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(response.status(), StatusCode::NOT_FOUND);
+}
+
+#[tokio::test]
+async fn distribution_rate_limit_keeps_its_safe_owner_message() {
+    use axum::{
+        body::{Body, to_bytes},
+        http::{Request, StatusCode},
+    };
+    use tower::ServiceExt as _;
+
+    let fixture = super::AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let direct = fixture
+        .services
+        .plugins()
+        .query_release(
+            GithubReleaseQuery {
+                repository: "rate-limit/fixture".to_owned(),
+                tag: None,
+                allow_prerelease: false,
+            },
+            &[],
+            None,
+        )
+        .await
+        .expect_err("fixture release query should be rate limited");
+    assert_eq!(
+        direct.kind(),
+        gateway_admin::model::AdminErrorKind::RateLimited
+    );
+    let response = gateway_api::admin::router::<super::AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .method("POST")
+                .uri("/api/admin/plugins/releases/query")
+                .header("content-type", "application/json")
+                .header("cookie", "cpr_session=valid-session")
+                .header("x-request-id", "req_plugin_distribution_rate_limit")
+                .body(Body::from(
+                    serde_json::json!({
+                        "query": {
+                            "repository": "rate-limit/fixture",
+                            "tag": null,
+                            "allowPrerelease": false
+                        },
+                        "credentialIds": []
+                    })
+                    .to_string(),
+                ))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    let status = response.status();
+    assert!(response.headers().get("retry-after").is_none());
+    let body = to_bytes(response.into_body(), 64 * 1024)
+        .await
+        .expect("rate limited response body");
+    assert_eq!(
+        status,
+        StatusCode::TOO_MANY_REQUESTS,
+        "{}",
+        String::from_utf8_lossy(&body)
+    );
+    assert_eq!(
+        serde_json::from_slice::<serde_json::Value>(&body).expect("rate limited response JSON"),
+        serde_json::json!({
+            "code": 42902,
+            "message": "插件来源限流，请稍后重试",
+            "data": null
+        })
+    );
+}
+
+#[tokio::test]
+async fn instance_list_serializes_safe_runtime_diagnostics() {
+    use axum::{
+        body::{Body, to_bytes},
+        http::{Request, StatusCode},
+    };
+    use tower::ServiceExt as _;
+
+    let fixture = super::AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let direct = fixture
+        .services
+        .plugins()
+        .instances()
+        .await
+        .expect("direct plugin instance projection");
+    assert_eq!(direct.len(), 1);
+    let response = gateway_api::admin::router::<super::AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri("/api/admin/plugins/instances")
+                .header("cookie", "cpr_session=valid-session")
+                .header("x-request-id", "req_plugin_instance_diagnostics")
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    let status = response.status();
+    let body = to_bytes(response.into_body(), 64 * 1024)
+        .await
+        .expect("response body");
+    assert_eq!(status, StatusCode::OK, "{}", String::from_utf8_lossy(&body));
+    let value: serde_json::Value = serde_json::from_slice(&body).expect("response json");
+    let instance = &value["data"][0];
+    assert_eq!(instance["running"], false);
+    assert_eq!(instance["runtime"]["status"], "preparation_failed");
+    assert_eq!(instance["runtime"]["actualRevision"], 6);
+    assert_eq!(
+        instance["runtime"]["drainingRevisions"],
+        serde_json::json!([5])
+    );
+    assert_eq!(instance["runtime"]["retainedContinuations"], 1);
+    assert_eq!(instance["runtime"]["failure"]["code"], "unavailable");
+    assert_eq!(
+        instance["runtime"]["failure"]["message"],
+        "插件候选准备失败"
+    );
+    assert!(instance["runtime"].get("configuration").is_none());
+}
+
+#[tokio::test]
+async fn plugin_upload_endpoints_require_admin_and_bound_raw_bodies() {
+    use axum::{
+        body::Body,
+        http::{Request, StatusCode},
+    };
+    use tower::ServiceExt as _;
+
+    let fixture = super::AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    for path in ["artifacts/upload", "artifacts/upload/verify"] {
+        for authenticated in [false, true] {
+            let mut request = Request::builder()
+                .method("POST")
+                .uri(format!("/api/admin/plugins/{path}"))
+                .header("x-request-id", "req_plugin_upload_limit")
+                .header("content-type", "application/octet-stream");
+            if authenticated {
+                request = request.header("cookie", "cpr_session=valid-session");
+            }
+            let response = gateway_api::admin::router::<super::AdminTestState>()
+                .with_state(fixture.state())
+                .oneshot(
+                    request
+                        .body(Body::from(vec![0_u8; 32 * 1024 * 1024 + 1]))
+                        .unwrap(),
+                )
+                .await
+                .unwrap();
+            assert_eq!(
+                response.status(),
+                if authenticated {
+                    StatusCode::PAYLOAD_TOO_LARGE
+                } else {
+                    StatusCode::UNAUTHORIZED
+                },
+                "{path}"
+            );
+        }
+    }
+}
+
+#[tokio::test]
+async fn artifact_acceptance_returns_the_flat_install_contract() {
+    use axum::{
+        body::{Body, to_bytes},
+        http::{Request, StatusCode},
+    };
+    use tower::ServiceExt as _;
+
+    let fixture = super::AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let response = gateway_api::admin::router::<super::AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .method("POST")
+                .uri("/api/admin/plugins/artifacts/accept")
+                .header("content-type", "application/json")
+                .header("cookie", "cpr_session=valid-session")
+                .header("x-request-id", "req_plugin_accept")
+                .body(Body::from(format!(r#"{{"sha256":"{}"}}"#, "a".repeat(64))))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    let status = response.status();
+    let body = to_bytes(response.into_body(), 64 * 1024).await.unwrap();
+    assert_eq!(
+        status,
+        StatusCode::CREATED,
+        "{}",
+        String::from_utf8_lossy(&body)
+    );
+    let value: serde_json::Value = serde_json::from_slice(&body).unwrap();
+    let result = &value["data"];
+    assert_eq!(result["configRevision"], 7);
+    assert_eq!(result["defaultInstanceId"], serde_json::Value::Null);
+    assert_eq!(result["configurationRequired"], false);
+    assert_eq!(result["artifact"]["metadata"]["sha256"], "a".repeat(64));
+    assert_eq!(
+        result["artifact"]["metadata"]["permissionDescriptions"][0]["permission"],
+        "models"
+    );
+    assert_eq!(
+        result["artifact"]["metadata"]["permissionDescriptions"][0]["label"],
+        "当前宿主标签"
+    );
+    assert!(result["artifact"]["acceptedAt"].is_string());
+    assert!(result.get("mutation").is_none());
+}
+
+#[tokio::test]
+async fn removed_instance_policy_fields_and_extra_accept_fields_are_rejected() {
+    use axum::{
+        body::Body,
+        http::{Request, StatusCode},
+    };
+    use tower::ServiceExt as _;
+
+    let fixture = super::AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    for (path, body) in [
+        (
+            "/api/admin/plugins/instances",
+            serde_json::json!({
+                "name":"Example",
+                "artifactSha256":"a".repeat(64),
+                "enabled":false,
+                "trustedProcess":true,
+                "configuration":{},
+                "grants":[],
+                "bindings":[]
+            }),
+        ),
+        (
+            "/api/admin/plugins/artifacts/accept",
+            serde_json::json!({"sha256":"a".repeat(64),"trusted":true}),
+        ),
+    ] {
+        let response = gateway_api::admin::router::<super::AdminTestState>()
+            .with_state(fixture.state())
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri(path)
+                    .header("content-type", "application/json")
+                    .header("cookie", "cpr_session=valid-session")
+                    .header("x-request-id", "req_plugin_strict_input")
+                    .body(Body::from(body.to_string()))
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(
+            response.status(),
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "{path}"
+        );
+    }
+}
+
+#[tokio::test]
+async fn plugin_mutations_require_admin_and_validate_json_on_static_post_routes() {
+    use axum::{
+        body::Body,
+        http::{Request, StatusCode},
+    };
+    use tower::ServiceExt as _;
+
+    let fixture = super::AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    for path in [
+        "artifacts/accept",
+        "artifacts/delete",
+        "artifacts/install",
+        "releases/query",
+        "updates/check",
+        "artifacts/verify",
+        "source-credentials",
+        "source-credentials/delete",
+        "update-sources",
+        "instances",
+        "instances/update",
+        "instances/rollback",
+        "instances/switch-version",
+        "instances/disable",
+        "instances/delete",
+    ] {
+        for authenticated in [false, true] {
+            let mut request = Request::builder()
+                .method("POST")
+                .uri(format!("/api/admin/plugins/{path}"))
+                .header("content-type", "application/json")
+                .header("x-request-id", "req_plugin_routes");
+            if authenticated {
+                request = request.header("cookie", "cpr_session=valid-session");
+            }
+            let response = gateway_api::admin::router::<super::AdminTestState>()
+                .with_state(fixture.state())
+                .oneshot(request.body(Body::from("{}")).unwrap())
+                .await
+                .unwrap();
+            assert_eq!(
+                response.status(),
+                if authenticated {
+                    // 字段缺失沿用 AdminJson 的结构校验合同。
+                    StatusCode::UNPROCESSABLE_ENTITY
+                } else {
+                    StatusCode::UNAUTHORIZED
+                },
+                "{path}"
+            );
+            assert_eq!(response.headers()["cache-control"], "no-store");
+        }
+    }
+}
+
+#[derive(Default)]
+pub(super) struct TestPluginPorts {
+    instances:
+        std::sync::Mutex<Option<Vec<gateway_admin::model::plugins::instances::PluginInstance>>>,
+}
+
+#[async_trait]
+impl gateway_admin::ports::plugin_management::PluginManagement for TestPluginPorts {
+    async fn authorize_models(
+        &self,
+        _: &gateway_core::runtime::extensions::ExtensionSetReference,
+        _: &gateway_admin::model::plugins::management::PluginManagementTarget,
+    ) -> Result<(), AdminError> {
+        Ok(())
+    }
+
+    async fn start_callback(
+        &self,
+        _: &gateway_core::runtime::extensions::ExtensionSetReference,
+        _: &gateway_admin::model::plugins::management::PluginManagementTarget,
+        _: gateway_admin::model::plugins::management::StartPluginManagementCallback,
+        _: &gateway_admin::model::auth::AdminRequestContext,
+    ) -> Result<gateway_admin::model::plugins::management::PluginManagementCallbackTicket, AdminError>
+    {
+        Err(AdminError::not_found("unused plugin fixture"))
+    }
+    async fn callback(
+        &self,
+        _: &gateway_core::runtime::extensions::ExtensionSetReference,
+        _: &gateway_admin::model::plugins::management::PluginManagementTarget,
+        _: &str,
+        _: gateway_admin::model::plugins::management::PluginManagementRequest,
+    ) -> Result<gateway_admin::model::plugins::management::PluginManagementResponse, AdminError>
+    {
+        Ok(management::resource_fixture("ui/index.html"))
+    }
+    async fn views(
+        &self,
+        _: &gateway_core::runtime::extensions::ExtensionSetReference,
+    ) -> Result<Vec<gateway_admin::model::plugins::management::PluginManagementView>, AdminError>
+    {
+        Ok(Vec::new())
+    }
+    async fn resource(
+        &self,
+        _: &gateway_core::runtime::extensions::ExtensionSetReference,
+        _: &gateway_admin::model::plugins::management::PluginManagementTarget,
+        path: &str,
+        public: bool,
+    ) -> Result<gateway_admin::model::plugins::management::PluginManagementResponse, AdminError>
+    {
+        if public && path != "public/login.css" {
+            return Err(AdminError::not_found("resource is not public"));
+        }
+        Ok(management::resource_fixture(path))
+    }
+    async fn handle(
+        &self,
+        _: &gateway_core::runtime::extensions::ExtensionSetReference,
+        _: &gateway_admin::model::plugins::management::PluginManagementTarget,
+        _: gateway_admin::model::plugins::management::PluginManagementRequest,
+    ) -> Result<gateway_admin::model::plugins::management::PluginManagementResponse, AdminError>
+    {
+        Ok(management::resource_fixture("api/echo"))
+    }
+}
+
+#[async_trait]
+impl gateway_admin::ports::plugins::PluginPreparation for TestPluginPorts {
+    async fn configuration_ready(
+        &self,
+        _: gateway_admin::model::plugins::instances::PluginInstance,
+        _: &gateway_admin::model::plugins::PluginArtifactMetadata,
+    ) -> Result<bool, AdminError> {
+        Ok(true)
+    }
+
+    async fn validate(
+        &self,
+        _: gateway_admin::model::plugins::instances::PluginInstance,
+    ) -> Result<gateway_admin::model::plugins::state::PluginStateConfiguration, AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+    async fn prepare(
+        &self,
+        _: gateway_admin::model::Revision,
+        _: gateway_admin::model::plugins::instances::PluginInstanceSnapshot,
+    ) -> Result<gateway_core::runtime::extensions::ExtensionSetReference, AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+
+    async fn runtime_diagnostics(
+        &self,
+        snapshot: &gateway_admin::model::plugins::instances::PluginInstanceSnapshot,
+        _: Option<u64>,
+        _: Option<&gateway_core::runtime::extensions::ExtensionSetReference>,
+    ) -> Option<BTreeMap<String, gateway_admin::model::plugins::instances::PluginInstanceRuntime>>
+    {
+        Some(
+            snapshot
+                .instances
+                .iter()
+                .map(|instance| {
+                    (
+                        instance.id.clone(),
+                        gateway_admin::model::plugins::instances::PluginInstanceRuntime {
+                            status: gateway_admin::model::plugins::instances::PluginInstanceRuntimeStatus::PreparationFailed,
+                            actual_revision: Some(6),
+                            actual_artifact_sha256: Some("b".repeat(64)),
+                            failure: Some(gateway_admin::model::plugins::instances::PluginInstanceRuntimeFailure {
+                                code: "unavailable".into(),
+                                message: "插件候选准备失败".into(),
+                            }),
+                            draining_revisions: vec![5],
+                            retained_continuations: 1,
+                        },
+                    )
+                })
+                .collect(),
+        )
+    }
+}
+
+fn unavailable() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Unavailable,
+        "plugin",
+        "unused plugin fixture",
+    )
+}
+
+fn icon_artifact(digest: &str) -> InspectedPluginArtifact {
+    InspectedPluginArtifact {
+        metadata: PluginArtifactMetadata {
+            plugin_id: "test.icon".into(),
+            version: "1.0.0".into(),
+            name: "icon".into(),
+            display_name: "Icon fixture".into(),
+            publisher: "test".into(),
+            author: None,
+            description: "fixture".into(),
+            license: "MIT".into(),
+            sha256: digest.into(),
+            platforms: vec!["linux-x86_64".into()],
+            icon: (digest.as_bytes()[0] == b'f')
+                .then(|| PluginArtifactIcon::Path("assets/icon.png".into())),
+            contributes: BTreeMap::new(),
+            requested_permissions: Vec::new(),
+            configuration_schema: serde_json::json!({}),
+            secret_fields: Vec::new(),
+            state_namespaces: Vec::new(),
+        },
+        archive: b"icon archive fixture".as_slice().into(),
+    }
+}
+
+fn accepted_artifact() -> InstalledPluginArtifact {
+    let mut metadata = icon_artifact(&"a".repeat(64)).metadata;
+    metadata.requested_permissions = vec!["models".into()];
+    InstalledPluginArtifact {
+        metadata,
+        source: PluginSource::Upload,
+        installed_at: chrono::Utc::now(),
+        accepted_at: Some(chrono::Utc::now()),
+    }
+}
+
+fn state_unavailable<T>() -> PluginStateStoreResult<T> {
+    Err(PluginStateStoreError::new(
+        PluginStateStoreErrorKind::Unavailable,
+    ))
+}
+
+#[async_trait]
+impl PluginStateStore for TestPluginPorts {
+    async fn load_owner(
+        &self,
+        _: PluginStateOwnerRequest,
+    ) -> PluginStateStoreResult<Option<PluginStateOwner>> {
+        state_unavailable()
+    }
+    async fn get(
+        &self,
+        _: &PluginStateOwner,
+        _: &str,
+        _: &str,
+    ) -> PluginStateStoreResult<Option<PluginStateRecord>> {
+        state_unavailable()
+    }
+    async fn put(
+        &self,
+        _: &PluginStateOwner,
+        _: PutPluginState,
+    ) -> PluginStateStoreResult<PluginStateWrite> {
+        state_unavailable()
+    }
+    async fn delete(
+        &self,
+        _: &PluginStateOwner,
+        _: DeletePluginState,
+    ) -> PluginStateStoreResult<bool> {
+        state_unavailable()
+    }
+    async fn transition_required(
+        &self,
+        _: &str,
+        _: &PluginStateConfiguration,
+    ) -> PluginStateStoreResult<bool> {
+        state_unavailable()
+    }
+    async fn begin_transition(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &str,
+        _: PluginStateConfiguration,
+    ) -> PluginStateStoreResult<PluginStateTransition> {
+        state_unavailable()
+    }
+    async fn migration_batch(
+        &self,
+        _: &str,
+        _: &str,
+        _: u32,
+    ) -> PluginStateStoreResult<PluginStateMigrationBatch> {
+        state_unavailable()
+    }
+    async fn apply_migration_batch(
+        &self,
+        _: ApplyPluginStateMigration,
+    ) -> PluginStateStoreResult<()> {
+        state_unavailable()
+    }
+    async fn abort_transition(&self, _: &str) -> PluginStateStoreResult<()> {
+        state_unavailable()
+    }
+}
+
+#[async_trait]
+impl PluginStore for TestPluginPorts {
+    async fn management_target_is_current(
+        &self,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+    ) -> AdminStoreResult<bool> {
+        Ok(self
+            .load_instances()
+            .await?
+            .instances
+            .iter()
+            .any(|instance| {
+                instance.enabled
+                    && instance.trusted_process
+                    && instance.id == target.instance_id
+                    && instance.artifact_sha256 == target.artifact_sha256
+                    && instance.revision.get() == target.revision
+            }))
+    }
+    async fn load_instances(
+        &self,
+    ) -> AdminStoreResult<gateway_admin::model::plugins::instances::PluginInstanceSnapshot> {
+        Ok(
+            gateway_admin::model::plugins::instances::PluginInstanceSnapshot {
+                config_revision: Revision::new(7).unwrap(),
+                instances: self.instances.lock().unwrap().clone().unwrap_or_else(|| {
+                    vec![gateway_admin::model::plugins::instances::PluginInstance {
+                        id: "plugin-instance-diagnostic".into(),
+                        name: "Diagnostic fixture".into(),
+                        artifact_sha256: "a".repeat(64),
+                        enabled: true,
+                        trusted_process: true,
+                        configuration: serde_json::json!({}),
+                        secrets: BTreeMap::new(),
+                        grants: Vec::new(),
+                        bindings: Vec::new(),
+                        revision: Revision::new(7).unwrap(),
+                    }]
+                }),
+            },
+        )
+    }
+    async fn save_instance(
+        &self,
+        _: gateway_admin::model::plugins::instances::PluginInstance,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<gateway_admin::model::plugins::instances::PluginInstanceMutation> {
+        Err(unavailable())
+    }
+    async fn delete_instance(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unavailable())
+    }
+    async fn list_update_sources(&self) -> AdminStoreResult<Vec<PluginSourceBinding>> {
+        Ok(Vec::new())
+    }
+    async fn change_update_source(
+        &self,
+        _: PluginSourceBinding,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unavailable())
+    }
+
+    async fn list_source_credentials(&self) -> AdminStoreResult<Vec<SourceCredentialInfo>> {
+        Ok(Vec::new())
+    }
+    async fn load_source_credential(&self, _: &str) -> AdminStoreResult<SourceCredential> {
+        Err(unavailable())
+    }
+    async fn save_source_credential(
+        &self,
+        _: SourceCredential,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unavailable())
+    }
+    async fn delete_source_credential(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unavailable())
+    }
+
+    async fn list_artifacts(&self) -> AdminStoreResult<Vec<InstalledPluginArtifact>> {
+        Ok(vec![accepted_artifact()])
+    }
+    async fn load_artifact(&self, digest: &str) -> AdminStoreResult<InspectedPluginArtifact> {
+        if matches!(digest.as_bytes().first(), Some(b'e' | b'f')) && digest.len() == 64 {
+            return Ok(icon_artifact(digest));
+        }
+        Err(unavailable())
+    }
+    async fn install_artifact(
+        &self,
+        _: InspectedPluginArtifact,
+        _: PluginSource,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        Err(unavailable())
+    }
+    async fn accept_artifact(
+        &self,
+        digest: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        if digest != "a".repeat(64) {
+            return Err(unavailable());
+        }
+        Ok(PluginArtifactMutation {
+            config_revision: Revision::new(7).unwrap(),
+            artifact: accepted_artifact(),
+        })
+    }
+    async fn delete_artifact(&self, _: &str, _: &MutationContext) -> AdminStoreResult<Revision> {
+        Err(unavailable())
+    }
+}
+
+#[async_trait]
+impl PluginPackageInspector for TestPluginPorts {
+    fn permission_descriptions(
+        &self,
+        permissions: &[String],
+    ) -> Vec<gateway_admin::model::plugins::PluginPermissionDescription> {
+        permissions
+            .iter()
+            .map(
+                |permission| gateway_admin::model::plugins::PluginPermissionDescription {
+                    permission: permission.clone(),
+                    label: "当前宿主标签".into(),
+                    description: "当前宿主说明".into(),
+                },
+            )
+            .collect()
+    }
+
+    async fn inspect(
+        &self,
+        _: Arc<[u8]>,
+        _: Option<String>,
+    ) -> Result<InspectedPluginArtifact, AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+
+    async fn icon(
+        &self,
+        _: Arc<[u8]>,
+        expected_sha256: String,
+        theme: PluginIconTheme,
+    ) -> Result<Option<PluginArtifactIconResource>, AdminError> {
+        Ok(
+            (expected_sha256 == "f".repeat(64)).then(|| PluginArtifactIconResource {
+                content_type: match theme {
+                    PluginIconTheme::Light => "image/png",
+                    PluginIconTheme::Dark => "image/svg+xml",
+                }
+                .into(),
+                body: match theme {
+                    PluginIconTheme::Light => b"icon fixture".to_vec(),
+                    PluginIconTheme::Dark => {
+                        br#"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"/>"#.to_vec()
+                    }
+                },
+            }),
+        )
+    }
+}
+
+#[async_trait]
+impl gateway_admin::ports::plugins::PluginDistribution for TestPluginPorts {
+    fn validate_source(&self, _: &PluginUpdateSource) -> Result<(), AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+
+    fn validate_credential(&self, _: &SourceCredential) -> Result<(), AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+    async fn query_release(
+        &self,
+        query: GithubReleaseQuery,
+        _: Vec<SourceCredential>,
+        _: Option<gateway_admin::model::plugins::distribution::PluginDistributionEgress>,
+    ) -> Result<PluginRelease, AdminError> {
+        if query.repository == "rate-limit/fixture" {
+            return Err(AdminError::new(
+                gateway_admin::model::AdminErrorKind::RateLimited,
+                "插件来源限流，请稍后重试",
+            ));
+        }
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+    async fn download(
+        &self,
+        _: RemotePluginLocation,
+        _: Vec<SourceCredential>,
+        _: Option<gateway_admin::model::plugins::distribution::PluginDistributionEgress>,
+    ) -> Result<DownloadedPlugin, AdminError> {
+        Err(AdminError::invalid("unused plugin fixture"))
+    }
+}
+
+#[tokio::test]
+async fn version_plan_requires_admin_and_an_explicit_target() {
+    use axum::{
+        body::Body,
+        http::{Request, StatusCode},
+    };
+    use tower::ServiceExt as _;
+    let fixture = super::AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    for authenticated in [false, true] {
+        let mut request = Request::builder()
+            .uri("/api/admin/plugins/instances/version-plan")
+            .header("x-request-id", "version-plan");
+        if authenticated {
+            request = request.header("cookie", "cpr_session=valid-session");
+        }
+        let response = gateway_api::admin::router::<super::AdminTestState>()
+            .with_state(fixture.state())
+            .oneshot(request.body(Body::empty()).unwrap())
+            .await
+            .unwrap();
+        assert_eq!(
+            response.status(),
+            if authenticated {
+                StatusCode::BAD_REQUEST
+            } else {
+                StatusCode::UNAUTHORIZED
+            }
+        );
+        assert_eq!(response.headers()["cache-control"], "no-store");
+    }
+}
diff --git a/backend/crates/gateway-api/tests/admin/settings.rs b/backend/crates/gateway-api/tests/admin/settings.rs
index 72a4b8762..ca4fb5aae 100644
--- a/backend/crates/gateway-api/tests/admin/settings.rs
+++ b/backend/crates/gateway-api/tests/admin/settings.rs
@@ -67,6 +67,24 @@ fn update_body() -> Value {
     })
 }
 
+fn insert_orphan_profile(fixture: &AdminTestFixture) {
+    fixture
+        .settings
+        .settings
+        .lock()
+        .expect("settings")
+        .request_profiles
+        .insert(
+            gateway_core::routing::ProviderKind::new("plugin.orphan").expect("provider kind"),
+            gateway_core::account::OpaqueProviderData::new(
+                json!({"preset":"legacy"})
+                    .as_object()
+                    .expect("profile object")
+                    .clone(),
+            ),
+        );
+}
+
 #[test]
 fn settings_request_should_reject_unknown_rotation_strategy() {
     let mut body = update_body();
@@ -111,8 +129,7 @@ fn settings_response_should_cover_the_full_runtime_settings_contract() {
     use gateway_core::routing::{PublicModelId, UpstreamModelId};
 
     let settings = RuntimeSettings {
-        openai_client_profile: None,
-        xai_client_profile: None,
+        request_profiles: Default::default(),
         request_location_enabled: false,
         request_location: Default::default(),
         config_revision: Revision::new(7).expect("revision"),
@@ -157,6 +174,7 @@ fn settings_response_should_cover_the_full_runtime_settings_contract() {
     assert_eq!(
         value,
         json!({
+            "providerRequestProfiles": {},
             "openaiClientProfile": null,
             "xaiClientProfile": null,
         "requestLocationEnabled": false,
@@ -212,8 +230,7 @@ fn settings_request_and_response_fields_should_stay_in_lockstep() {
         .cloned()
         .collect();
     let settings = RuntimeSettings {
-        openai_client_profile: None,
-        xai_client_profile: None,
+        request_profiles: Default::default(),
         request_location_enabled: false,
         request_location: Default::default(),
         config_revision: Revision::new(7).expect("revision"),
@@ -262,6 +279,7 @@ fn settings_request_and_response_fields_should_stay_in_lockstep() {
             .cloned()
             .collect();
     let mut expected_fields = request_fields;
+    expected_fields.insert("providerRequestProfiles".to_owned());
     expected_fields.insert("openaiClientProfile".to_owned());
     expected_fields.insert("xaiClientProfile".to_owned());
     expected_fields.insert("updatedAt".to_owned());
@@ -305,6 +323,26 @@ async fn settings_get_should_preserve_global_model_mappings() {
     );
 }
 
+#[tokio::test]
+async fn client_profile_providers_should_come_from_provider_capabilities() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let response = app(fixture.state())
+        .oneshot(request(
+            Method::GET,
+            "/api/admin/settings/client-profiles",
+            None,
+        ))
+        .await
+        .expect("client profile providers response");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(
+        response_json(response).await["data"],
+        json!({"providers": []})
+    );
+}
+
 #[tokio::test]
 async fn settings_post_should_replace_global_model_mappings() {
     let fixture = AdminTestFixture::new().await;
@@ -664,6 +702,130 @@ fn global_profile_can_be_omitted_but_cannot_be_cleared() {
     }
 }
 
+#[tokio::test]
+async fn generic_global_profiles_decode_dynamic_providers_and_reject_legacy_conflicts() {
+    let mut body = update_body();
+    body["providerRequestProfiles"] = json!({
+        "openai":{"preset":"desktop"},
+        "provider.example":{"preset":"managed"},
+    });
+    body["openaiClientProfile"] = json!({"preset":"desktop"});
+    let decoded = serde_json::from_value::<UpdateRuntimeSettingsRequest>(body.clone()).unwrap();
+    assert!(
+        decoded
+            .provider_request_profiles
+            .contains_key("provider.example")
+    );
+
+    body["openaiClientProfile"] = json!({"preset":"cli"});
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let response = app(fixture.state())
+        .oneshot(request(
+            Method::POST,
+            "/api/admin/settings/update",
+            Some(body),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+}
+
+#[tokio::test]
+async fn settings_update_preserves_an_unchanged_orphan_profile() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    insert_orphan_profile(&fixture);
+    let mut body = update_body();
+    body["providerRequestProfiles"] = json!({
+        "plugin.orphan":{"preset":"legacy"}
+    });
+
+    let response = app(fixture.state())
+        .oneshot(request(
+            Method::POST,
+            "/api/admin/settings/update",
+            Some(body),
+        ))
+        .await
+        .unwrap();
+    let status = response.status();
+    let data = response_json(response).await["data"].clone();
+
+    assert_eq!(
+        (status, &data["providerRequestProfiles"]["plugin.orphan"]),
+        (StatusCode::OK, &json!({"preset":"legacy"})),
+    );
+}
+
+#[tokio::test]
+async fn settings_update_rejects_a_modified_orphan_profile() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    insert_orphan_profile(&fixture);
+    let mut body = update_body();
+    body["providerRequestProfiles"] = json!({
+        "plugin.orphan":{"preset":"changed"}
+    });
+
+    let response = app(fixture.state())
+        .oneshot(request(
+            Method::POST,
+            "/api/admin/settings/update",
+            Some(body),
+        ))
+        .await
+        .unwrap();
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+}
+
+#[tokio::test]
+async fn settings_update_rejects_a_new_unknown_profile() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let mut body = update_body();
+    body["providerRequestProfiles"] = json!({
+        "plugin.unknown":{"preset":"new"}
+    });
+
+    let response = app(fixture.state())
+        .oneshot(request(
+            Method::POST,
+            "/api/admin/settings/update",
+            Some(body),
+        ))
+        .await
+        .unwrap();
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+}
+
+#[tokio::test]
+async fn settings_update_explicitly_removes_an_orphan_profile() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    insert_orphan_profile(&fixture);
+    let mut body = update_body();
+    body["providerRequestProfiles"] = json!({"plugin.orphan":null});
+
+    let response = app(fixture.state())
+        .oneshot(request(
+            Method::POST,
+            "/api/admin/settings/update",
+            Some(body),
+        ))
+        .await
+        .unwrap();
+    let status = response.status();
+    let data = response_json(response).await["data"].clone();
+
+    assert_eq!(
+        (status, data["providerRequestProfiles"].get("plugin.orphan"),),
+        (StatusCode::OK, None),
+    );
+}
+
 fn custom_pricing() -> Value {
     json!({"multiplierBps":12500,"bands":{"standard":{"input":"3","output":"12","cacheRead":"0","cacheWrite":"0"}}})
 }
diff --git a/backend/crates/gateway-api/tests/admin/system.rs b/backend/crates/gateway-api/tests/admin/system.rs
index c488cd39b..b3f77b3bd 100644
--- a/backend/crates/gateway-api/tests/admin/system.rs
+++ b/backend/crates/gateway-api/tests/admin/system.rs
@@ -147,6 +147,7 @@ impl SystemOperations for ProgressSystem {
     async fn perform_update(
         &self,
         target: Option<String>,
+        _: Arc<dyn gateway_admin::ports::system::SystemUpdatePreflight>,
     ) -> Result<SystemOperationAccepted, SystemOperationError> {
         Ok(SystemOperationAccepted::Update {
             operation_id: "update-1".to_owned(),
@@ -174,7 +175,10 @@ impl SystemOperations for ProgressSystem {
         })
     }
 
-    async fn rollback(&self) -> Result<SystemOperationAccepted, SystemOperationError> {
+    async fn rollback(
+        &self,
+        _: Arc<dyn gateway_admin::ports::system::SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError> {
         Err(unavailable_system())
     }
 
diff --git a/backend/crates/gateway-api/tests/admin/wire.rs b/backend/crates/gateway-api/tests/admin/wire.rs
index e1cc4f006..d6176709d 100644
--- a/backend/crates/gateway-api/tests/admin/wire.rs
+++ b/backend/crates/gateway-api/tests/admin/wire.rs
@@ -36,6 +36,7 @@ mod error {
             AdminErrorCode::NOT_FOUND,
             AdminErrorCode::CONFLICT,
             AdminErrorCode::TOO_MANY_LOGIN_ATTEMPTS,
+            AdminErrorCode::RATE_LIMITED,
             AdminErrorCode::SETTINGS_PERSIST,
             AdminErrorCode::INTERNAL,
             AdminErrorCode::USAGE_RECORD_ACCOUNTS,
@@ -48,8 +49,8 @@ mod error {
         assert_eq!(
             actual,
             [
-                40000, 40001, 40002, 40003, 40101, 40102, 40103, 40401, 40901, 42901, 50000, 50001,
-                50002, 50201, 50202, 50301,
+                40000, 40001, 40002, 40003, 40101, 40102, 40103, 40401, 40901, 42901, 42902, 50000,
+                50001, 50002, 50201, 50202, 50301,
             ]
         );
     }
@@ -189,6 +190,11 @@ mod response {
                 StatusCode::TOO_MANY_REQUESTS,
                 42901,
             ),
+            (
+                AdminError::rate_limited(),
+                StatusCode::TOO_MANY_REQUESTS,
+                42902,
+            ),
             (
                 AdminError::conflict("conflict"),
                 StatusCode::CONFLICT,
@@ -228,4 +234,33 @@ mod response {
             assert!(body["data"].is_null());
         }
     }
+
+    #[tokio::test]
+    async fn generic_and_login_rate_limits_should_keep_distinct_wire_contracts() {
+        let generic = AdminError::rate_limited().into_response();
+        assert_eq!(generic.status(), StatusCode::TOO_MANY_REQUESTS);
+        assert!(generic.headers().get("retry-after").is_none());
+        assert_eq!(
+            response_json(generic).await,
+            json!({
+                "code": 42902,
+                "message": "请求过于频繁，请稍后重试",
+                "data": null
+            })
+        );
+
+        let login = AdminError::too_many_login_attempts()
+            .with_retry_after(17)
+            .into_response();
+        assert_eq!(login.status(), StatusCode::TOO_MANY_REQUESTS);
+        assert_eq!(login.headers()["retry-after"], "17");
+        assert_eq!(
+            response_json(login).await,
+            json!({
+                "code": 42901,
+                "message": "登录尝试过多，请稍后重试",
+                "data": null
+            })
+        );
+    }
 }
diff --git a/backend/crates/gateway-api/tests/architecture.rs b/backend/crates/gateway-api/tests/architecture.rs
index 668b1266e..d2bc63c04 100644
--- a/backend/crates/gateway-api/tests/architecture.rs
+++ b/backend/crates/gateway-api/tests/architecture.rs
@@ -34,6 +34,7 @@ fn source_tree_should_match_frozen_machine_manifest() {
     actual.sort();
     let mut expected = vec![
         "src/admin/account_groups.rs",
+        "src/admin/accounts/capabilities.rs",
         "src/admin/accounts/credentials.rs",
         "src/admin/accounts/handlers.rs",
         "src/admin/accounts/import_tasks.rs",
@@ -50,6 +51,11 @@ fn source_tree_should_match_frozen_machine_manifest() {
         "src/admin/observability/query.rs",
         "src/admin/observability/routes.rs",
         "src/admin/observability/wire.rs",
+        "src/admin/plugins/artifacts.rs",
+        "src/admin/plugins/distribution.rs",
+        "src/admin/plugins/instances.rs",
+        "src/admin/plugins/management.rs",
+        "src/admin/plugins/mod.rs",
         "src/admin/presenter.rs",
         "src/admin/proxies.rs",
         "src/admin/settings.rs",
@@ -61,6 +67,10 @@ fn source_tree_should_match_frozen_machine_manifest() {
         "src/key_usage/query.rs",
         "src/key_usage/presenter.rs",
         "src/lib.rs",
+        "src/openai/middleware/http.rs",
+        "src/openai/middleware/mod.rs",
+        "src/openai/middleware/request.rs",
+        "src/openai/middleware/session.rs",
         "src/openai/auth.rs",
         "src/openai/error.rs",
         "src/openai/images/http.rs",
@@ -73,6 +83,7 @@ fn source_tree_should_match_frozen_machine_manifest() {
         "src/openai/responses/mod.rs",
         "src/openai/responses/request.rs",
         "src/openai/responses/response.rs",
+        "src/openai/responses/validation.rs",
         "src/openai/responses/websocket/connection.rs",
         "src/openai/responses/websocket/forward.rs",
         "src/openai/responses/websocket/mod.rs",
@@ -82,6 +93,7 @@ fn source_tree_should_match_frozen_machine_manifest() {
         "src/openai/search/mod.rs",
         "src/openai/service.rs",
         "src/openai/usage.rs",
+        "src/provider.rs",
         "src/session_cookie.rs",
     ];
     expected.sort_unstable();
@@ -96,6 +108,7 @@ fn test_tree_should_match_frozen_rust_mirror() {
     actual.sort();
     let mut expected = vec![
         "tests/admin/account_groups.rs",
+        "tests/admin/accounts/capabilities.rs",
         "tests/admin/accounts/handlers.rs",
         "tests/admin/accounts/import_tasks.rs",
         "tests/admin/accounts/mod.rs",
@@ -107,6 +120,8 @@ fn test_tree_should_match_frozen_rust_mirror() {
         "tests/admin/observability/mod.rs",
         "tests/admin/observability/query.rs",
         "tests/admin/observability/response.rs",
+        "tests/admin/plugins/management.rs",
+        "tests/admin/plugins/mod.rs",
         "tests/admin/proxies.rs",
         "tests/admin/settings.rs",
         "tests/admin/system.rs",
@@ -118,6 +133,7 @@ fn test_tree_should_match_frozen_rust_mirror() {
         "tests/key_usage/mod.rs",
         "tests/key_usage/fixtures.rs",
         "tests/main.rs",
+        "tests/openai/middleware/mod.rs",
         "tests/openai/auth.rs",
         "tests/openai/error.rs",
         "tests/openai/images/mod.rs",
@@ -134,6 +150,7 @@ fn test_tree_should_match_frozen_rust_mirror() {
         "tests/openai/router.rs",
         "tests/openai/search/mod.rs",
         "tests/openai/usage.rs",
+        "tests/provider.rs",
     ];
     expected.sort_unstable();
 
diff --git a/backend/crates/gateway-api/tests/key_usage/fixtures.rs b/backend/crates/gateway-api/tests/key_usage/fixtures.rs
index 56200d723..3fe5e372a 100644
--- a/backend/crates/gateway-api/tests/key_usage/fixtures.rs
+++ b/backend/crates/gateway-api/tests/key_usage/fixtures.rs
@@ -17,8 +17,7 @@ pub(super) async fn fixture() -> AdminTestFixture {
     let fixture = key_fixture().await;
     let now = Utc::now();
     *fixture.client_key.lock().unwrap() = Some(ClientKeyRecord {
-        openai_client_profile_override: None,
-        xai_client_profile_override: None,
+        request_profile_overrides: Default::default(),
         id: ClientApiKeyId::new("key-42").unwrap(),
         name: "Development".to_owned(),
         label: Some("private-sentinel".to_owned()),
diff --git a/backend/crates/gateway-api/tests/main.rs b/backend/crates/gateway-api/tests/main.rs
index 4d0e55378..b13aac930 100644
--- a/backend/crates/gateway-api/tests/main.rs
+++ b/backend/crates/gateway-api/tests/main.rs
@@ -4,6 +4,7 @@ mod auth;
 mod health;
 mod key_usage;
 mod openai;
+mod provider;
 mod support;
 
 #[tokio::test]
@@ -18,6 +19,7 @@ async fn api_should_serve_resolved_assets_with_relative_environment_override() {
         fs::create_dir_all(directory.join("deploy")).expect("config directory");
         fs::create_dir_all(directory.join("web/dist")).expect("asset directory");
         fs::write(directory.join("web/dist/index.html"), "resolved-web-assets").expect("index");
+        fs::write(directory.join("web/dist/favicon.svg"), "<svg/>").expect("favicon");
         let output = Command::new(std::env::current_exe().expect("test executable"))
             .args([
                 "--exact",
@@ -47,13 +49,33 @@ async fn api_should_serve_resolved_assets_with_relative_environment_override() {
         .resolve_and_validate(&std::path::Path::new(&directory).join("deploy"))
         .expect("resolved API config");
     let admin = admin::AdminTestFixture::new().await;
-    let response = openai::api_router_with_config(admin.services, config)
+    let router = openai::api_router_with_config(admin.services, config);
+    let response = router
+        .clone()
         .oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
         .await
         .expect("static response");
     assert_eq!(response.status(), axum::http::StatusCode::OK);
+    assert_eq!(response.headers()["cache-control"], "no-cache");
     let body = axum::body::to_bytes(response.into_body(), 1024)
         .await
         .unwrap();
     assert_eq!(body.as_ref(), b"resolved-web-assets");
+    for (uri, expected_body) in [
+        ("/favicon.svg", "<svg/>"),
+        ("/assets/missing.svg", "resolved-web-assets"),
+        ("/plugins/one/main", "resolved-web-assets"),
+    ] {
+        let response = router
+            .clone()
+            .oneshot(Request::builder().uri(uri).body(Body::empty()).unwrap())
+            .await
+            .unwrap();
+        assert_eq!(response.status(), axum::http::StatusCode::OK, "{uri}");
+        assert_eq!(response.headers()["cache-control"], "no-cache", "{uri}");
+        let body = axum::body::to_bytes(response.into_body(), 1024)
+            .await
+            .unwrap();
+        assert_eq!(body.as_ref(), expected_body.as_bytes(), "{uri}");
+    }
 }
diff --git a/backend/crates/gateway-api/tests/openai/auth.rs b/backend/crates/gateway-api/tests/openai/auth.rs
index 5d31ad170..731e8fe28 100644
--- a/backend/crates/gateway-api/tests/openai/auth.rs
+++ b/backend/crates/gateway-api/tests/openai/auth.rs
@@ -1,9 +1,120 @@
-use axum::http::{HeaderMap, HeaderValue, header::AUTHORIZATION};
+use std::sync::{
+    Arc,
+    atomic::{AtomicUsize, Ordering},
+};
+
+use axum::http::{
+    HeaderMap, HeaderValue, Method, StatusCode,
+    header::{self, AUTHORIZATION},
+};
+use futures::future::BoxFuture;
 
 use gateway_api::openai::auth::{
     ClientApiKeyAuthError, bearer_client_api_key, identify_codex_client,
 };
-use gateway_core::policy::CodexClientKind;
+use gateway_core::{
+    engine::{
+        authentication::ClientAuthenticationRequest,
+        execution::{
+            AuthenticatedClient, ClientAuthenticationError, ExecutionService, StartExecution,
+            StartProviderExecution, StartedExecution,
+        },
+    },
+    error::{GatewayError, GatewayErrorKind},
+    policy::CodexClientKind,
+    routing::PublicModelId,
+};
+use tower::ServiceExt as _;
+
+struct EnvelopeAuthentication {
+    client: AuthenticatedClient,
+    calls: AtomicUsize,
+}
+
+impl ExecutionService for EnvelopeAuthentication {
+    fn authenticate(&self, _: &str) -> Result<AuthenticatedClient, ClientAuthenticationError> {
+        Err(ClientAuthenticationError::InvalidKey)
+    }
+
+    fn authenticate_request(
+        &self,
+        request: ClientAuthenticationRequest,
+    ) -> BoxFuture<'_, Result<AuthenticatedClient, ClientAuthenticationError>> {
+        assert_eq!(request.authorization(), "External controlled-credential");
+        let debug = format!("{request:?}");
+        for private in [
+            "controlled-credential",
+            "controlled-fixture",
+            "private-client",
+            "192.0.2.9",
+        ] {
+            assert!(!debug.contains(private));
+        }
+        self.calls.fetch_add(1, Ordering::SeqCst);
+        let client = self.client.clone();
+        Box::pin(async move { Ok(client) })
+    }
+
+    fn public_models(&self, _: &AuthenticatedClient) -> Vec<PublicModelId> {
+        Vec::new()
+    }
+
+    fn contains_public_model(&self, _: &AuthenticatedClient, _: &PublicModelId) -> bool {
+        false
+    }
+
+    fn start(&self, _: StartExecution) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async {
+            Err(GatewayError::new(
+                GatewayErrorKind::Internal,
+                "authentication envelope test must not execute",
+            ))
+        })
+    }
+
+    fn start_provider_endpoint(
+        &self,
+        _: StartProviderExecution,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async {
+            Err(GatewayError::new(
+                GatewayErrorKind::Internal,
+                "authentication envelope test must not execute",
+            ))
+        })
+    }
+}
+
+#[tokio::test]
+async fn plugin_authentication_envelope_contains_only_authorization() {
+    let fixture = crate::admin::AdminTestFixture::new().await;
+    let execution = Arc::new(EnvelopeAuthentication {
+        client: super::authenticated_client("unused-native-key"),
+        calls: AtomicUsize::new(0),
+    });
+    let app = super::api_router_with_admin_and_execution(fixture.services, execution.clone());
+    let mut request = crate::support::empty_request(Method::GET, "/v1/models");
+    request.headers_mut().insert(
+        header::AUTHORIZATION,
+        HeaderValue::from_static("External controlled-credential"),
+    );
+    request.headers_mut().insert(
+        header::COOKIE,
+        HeaderValue::from_static("admin_session=controlled-fixture"),
+    );
+    request.headers_mut().insert(
+        header::USER_AGENT,
+        HeaderValue::from_static("private-client"),
+    );
+    request
+        .headers_mut()
+        .insert("x-forwarded-for", HeaderValue::from_static("192.0.2.9"));
+
+    let response = app.oneshot(request).await.unwrap();
+
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(execution.calls.load(Ordering::SeqCst), 1);
+}
 
 #[test]
 fn bearer_client_api_key_should_reject_missing_authorization() {
diff --git a/backend/crates/gateway-api/tests/openai/images/mod.rs b/backend/crates/gateway-api/tests/openai/images/mod.rs
index be14ecd8b..bdf4eee91 100644
--- a/backend/crates/gateway-api/tests/openai/images/mod.rs
+++ b/backend/crates/gateway-api/tests/openai/images/mod.rs
@@ -19,7 +19,7 @@ use gateway_core::error::{
     ClientVisibleUpstreamResponse, GatewayError, GatewayErrorKind, ProviderError, ProviderErrorKind,
 };
 use gateway_core::event::{ProtocolWireEvent, ProviderEvent, ProviderResponseHeader};
-use gateway_core::operation::{ImageRequestKind, Operation};
+use gateway_core::operation::{ImageRequestKind, Operation, OperationKind};
 use gateway_core::routing::PublicModelId;
 use gateway_core::upstream::UpstreamSendState;
 use serde_json::{Value, json};
@@ -44,7 +44,9 @@ struct ImageExecution {
     client: AuthenticatedClient,
     captured: Arc<Mutex<Vec<CapturedImageRequest>>>,
     committed_statuses: Arc<Mutex<Vec<u16>>>,
+    error_statuses: Arc<Mutex<Vec<u16>>>,
     fail_with_upstream_response: bool,
+    middleware: Option<Arc<crate::openai::middleware::RequestMiddleware>>,
 }
 
 impl ImageExecution {
@@ -53,7 +55,9 @@ impl ImageExecution {
             client: authenticated_client("sk_images_test"),
             captured: Arc::new(Mutex::new(Vec::new())),
             committed_statuses: Arc::new(Mutex::new(Vec::new())),
+            error_statuses: Arc::new(Mutex::new(Vec::new())),
             fail_with_upstream_response: false,
+            middleware: None,
         })
     }
 
@@ -62,7 +66,9 @@ impl ImageExecution {
             client: authenticated_client("sk_images_test"),
             captured: Arc::new(Mutex::new(Vec::new())),
             committed_statuses: Arc::new(Mutex::new(Vec::new())),
+            error_statuses: Arc::new(Mutex::new(Vec::new())),
             fail_with_upstream_response: true,
+            middleware: None,
         })
     }
 
@@ -79,6 +85,13 @@ impl ImageExecution {
 }
 
 impl ExecutionService for ImageExecution {
+    fn middleware_plan(
+        &self,
+        _: &gateway_core::engine::execution::PreparedRootExecution,
+    ) -> Option<gateway_core::engine::middleware::FrozenMiddlewarePlan> {
+        self.middleware.as_ref().map(|plan| plan.frozen())
+    }
+
     fn authenticate(
         &self,
         plaintext: &str,
@@ -139,6 +152,7 @@ impl ExecutionService for ImageExecution {
                         Bytes::from_static(b"42"),
                     )],
                     committed_statuses: Arc::clone(&self.committed_statuses),
+                    error_statuses: Arc::clone(&self.error_statuses),
                     finalized: Arc::new(AtomicBool::new(false)),
                     fail_with_upstream_response: self.fail_with_upstream_response,
                 }),
@@ -151,6 +165,7 @@ struct ImageSession {
     response: Option<Bytes>,
     response_headers: Vec<ProviderResponseHeader>,
     committed_statuses: Arc<Mutex<Vec<u16>>>,
+    error_statuses: Arc<Mutex<Vec<u16>>>,
     finalized: Arc<AtomicBool>,
     fail_with_upstream_response: bool,
 }
@@ -216,8 +231,14 @@ impl ExecutionSession for ImageSession {
         })
     }
 
-    fn record_client_status(&mut self, _: u16) -> BoxFuture<'_, Result<(), EngineError>> {
-        Box::pin(async { Ok(()) })
+    fn record_client_status(&mut self, status: u16) -> BoxFuture<'_, Result<(), EngineError>> {
+        Box::pin(async move {
+            self.error_statuses
+                .lock()
+                .expect("error status lock")
+                .push(status);
+            Ok(())
+        })
     }
 
     fn is_finalized(&self) -> bool {
@@ -237,29 +258,43 @@ impl ExecutionSession for ImageSession {
 
 #[tokio::test]
 async fn image_routes_should_not_decode_bodies_and_should_preserve_both_directions() {
-    let execution = ImageExecution::new();
+    let mut execution = ImageExecution::new();
+    let middleware = Arc::new(crate::openai::middleware::RequestMiddleware {
+        expected_operation: Some(OperationKind::GenerateImage),
+        committed_statuses: Some(execution.committed_statuses.clone()),
+        ..Default::default()
+    });
+    Arc::get_mut(&mut execution).unwrap().middleware = Some(middleware.clone());
     let router = api_router(execution.clone()).await;
     let cases = [
         (
             "/v1/images/generations",
             ImageRequestKind::Generation,
+            "application/json",
             br#"{ "model":"gpt-image-future", "prompt":"a lighthouse", "future":9007199254740993 }"#.as_slice(),
         ),
         (
             "/v1/images/edits",
             ImageRequestKind::Edit,
+            "application/json",
             br#"{"model":"gpt-image-2","images":[{"image_url":"data:image/png;base64,AAEC"}],"prompt":"add fog","prompt":"duplicate stays raw"}"#.as_slice(),
         ),
+        (
+            "/v1/images/edits",
+            ImageRequestKind::Edit,
+            "multipart/form-data; boundary=image-boundary",
+            b"--image-boundary\r\nContent-Disposition: form-data; name=\"image\"; filename=\"image.png\"\r\nContent-Type: image/png\r\n\r\n\x89PNG\x00\xff\r\n--image-boundary--\r\n".as_slice(),
+        ),
     ];
 
-    for (path, _, body) in &cases {
+    for (path, _, content_type, body) in &cases {
         let response = router
             .clone()
             .oneshot(
                 Request::post(*path)
                     .header(AUTHORIZATION, "Bearer sk_images_test")
                     .header("x-request-id", "caller-image-request")
-                    .header("content-type", "application/json")
+                    .header("content-type", *content_type)
                     .header("x-codex-image-turn-id", "turn_image_route")
                     .header("session-id", "root-image-session")
                     .header("thread-id", "child-image-thread")
@@ -269,6 +304,7 @@ async fn image_routes_should_not_decode_bodies_and_should_preserve_both_directio
             .await
             .expect("image response");
         assert_eq!(response.status(), StatusCode::CREATED);
+        assert_eq!(response.headers()["x-request-middleware"], "applied");
         assert_eq!(response.headers()["x-request-id"], "req_images_test");
         assert_eq!(
             response.headers()["x-gateway-request-id"],
@@ -286,7 +322,15 @@ async fn image_routes_should_not_decode_bodies_and_should_preserve_both_directio
 
     let captured = execution.captured();
     assert_eq!(captured.len(), cases.len());
-    for (captured, (endpoint, kind, body)) in captured.iter().zip(cases.iter()) {
+    assert_eq!(
+        *middleware.endpoints.lock().unwrap(),
+        vec![
+            "/v1/images/generations",
+            "/v1/images/edits",
+            "/v1/images/edits"
+        ]
+    );
+    for (captured, (endpoint, kind, _, body)) in captured.iter().zip(cases.iter()) {
         assert_eq!(captured.provider, "openai");
         assert_eq!(captured.endpoint, *endpoint);
         assert_eq!(captured.transport, ClientTransport::HttpJson);
@@ -306,7 +350,7 @@ async fn image_routes_should_not_decode_bodies_and_should_preserve_both_directio
 #[tokio::test]
 async fn image_route_should_return_the_exact_upstream_error_response() {
     let execution = ImageExecution::failing();
-    let response = api_router(execution)
+    let response = api_router(execution.clone())
         .await
         .oneshot(
             Request::post("/v1/images/edits")
@@ -341,4 +385,9 @@ async fn image_route_should_return_the_exact_upstream_error_response() {
         body.as_ref(),
         br#"{ "error":{"message":"future image validation"}, "future":9007199254740993 }"#
     );
+    assert!(execution.committed_statuses().is_empty());
+    assert_eq!(
+        *execution.error_statuses.lock().expect("error status lock"),
+        vec![422]
+    );
 }
diff --git a/backend/crates/gateway-api/tests/openai/middleware/mod.rs b/backend/crates/gateway-api/tests/openai/middleware/mod.rs
new file mode 100644
index 000000000..0ccef5e77
--- /dev/null
+++ b/backend/crates/gateway-api/tests/openai/middleware/mod.rs
@@ -0,0 +1,231 @@
+use std::{
+    collections::VecDeque,
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicUsize, Ordering},
+    },
+};
+
+use bytes::Bytes;
+use futures::future::BoxFuture;
+use gateway_core::{
+    engine::middleware::{
+        FrozenMiddlewarePlan, MiddlewareBody, MiddlewareContext, MiddlewareError, MiddlewareFrame,
+        MiddlewareFraming, MiddlewareHeader, MiddlewareMount, MiddlewareNext, MiddlewarePlan,
+        MiddlewareRequest, MiddlewareResponse,
+    },
+    operation::OperationKind,
+    runtime::extensions::{ExtensionSetId, ExtensionSetLease, ExtensionSetReference},
+};
+
+/// OpenAI API 入口共用的中间件夹具；授权和 RPC 由 Runtime 行为测试覆盖。
+#[derive(Debug, Default)]
+pub(super) struct RequestMiddleware {
+    pub(super) endpoints: Mutex<Vec<String>>,
+    pub(super) live_leases: Arc<AtomicUsize>,
+    pub(super) expected_operation: Option<OperationKind>,
+    pub(super) committed_statuses: Option<Arc<Mutex<Vec<u16>>>>,
+    pub(super) response_actions: Mutex<VecDeque<ResponseFrameAction>>,
+    pub(super) response_headers: Vec<MiddlewareHeader>,
+    pub(super) short_circuit_json: Option<Bytes>,
+}
+
+#[derive(Debug, Clone)]
+pub(super) enum ResponseFrameAction {
+    Continue,
+    Replace(Bytes),
+    Drop,
+}
+
+impl RequestMiddleware {
+    pub(super) fn frozen(self: &Arc<Self>) -> FrozenMiddlewarePlan {
+        self.live_leases.fetch_add(1, Ordering::SeqCst);
+        FrozenMiddlewarePlan::new(
+            self.clone(),
+            ExtensionSetReference::new(
+                ExtensionSetId::new("request-middleware".to_owned()).unwrap(),
+                Arc::new(RequestLease(self.live_leases.clone())),
+            ),
+        )
+    }
+
+    #[must_use]
+    pub(super) fn with_response_actions(self, actions: Vec<ResponseFrameAction>) -> Self {
+        Self {
+            response_actions: Mutex::new(actions.into()),
+            ..self
+        }
+    }
+
+    #[must_use]
+    pub(super) fn with_response_headers(self, headers: Vec<MiddlewareHeader>) -> Self {
+        Self {
+            response_headers: headers,
+            ..self
+        }
+    }
+
+    #[must_use]
+    pub(super) fn with_json_short_circuit(self, body: Bytes) -> Self {
+        Self {
+            short_circuit_json: Some(body),
+            ..self
+        }
+    }
+}
+
+struct RequestLease(Arc<AtomicUsize>);
+
+impl ExtensionSetLease for RequestLease {
+    fn is_ready(&self) -> bool {
+        true
+    }
+}
+
+impl Drop for RequestLease {
+    fn drop(&mut self) {
+        self.0.fetch_sub(1, Ordering::SeqCst);
+    }
+}
+
+impl MiddlewarePlan for RequestMiddleware {
+    fn handle(
+        &self,
+        context: MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        assert_eq!(context.mount(), MiddlewareMount::Request);
+        assert_eq!(context.operation(), self.expected_operation);
+        assert!(context.attempt_index().is_none());
+        assert!(context.account_id().is_none());
+        self.endpoints
+            .lock()
+            .unwrap()
+            .push(context.endpoint().to_owned());
+        let statuses = self.committed_statuses.clone();
+        let actions = std::mem::take(&mut *self.response_actions.lock().unwrap());
+        let response_headers = self.response_headers.clone();
+        let short_circuit_json = self.short_circuit_json.clone();
+        Box::pin(async move {
+            if let Some(body) = short_circuit_json {
+                return Ok(MiddlewareResponse::new(
+                    "openai".to_owned(),
+                    200,
+                    Vec::new(),
+                    Box::new(SingleFrameBody(Some(MiddlewareFrame::new(
+                        body,
+                        MiddlewareFraming::JsonDocument,
+                        true,
+                    )))),
+                ));
+            }
+            let count = statuses.as_ref().map(|values| values.lock().unwrap().len());
+            let response = next.run(request).await?;
+            assert_eq!(
+                statuses.as_ref().map(|values| values.lock().unwrap().len()),
+                count
+            );
+            let (protocol, status, mut headers, body, envelope) = response.into_parts();
+            headers.push(MiddlewareHeader::new(
+                "x-request-middleware",
+                Bytes::from_static(b"applied"),
+            ));
+            headers.extend(response_headers);
+            let mut response = MiddlewareResponse::new(
+                protocol,
+                status,
+                headers,
+                Box::new(ResponseMiddlewareBody {
+                    body,
+                    actions,
+                    transformed_pending: false,
+                }),
+            );
+            if let Some(envelope) = envelope {
+                response = response.with_envelope(envelope);
+            }
+            Ok(response)
+        })
+    }
+}
+
+struct SingleFrameBody(Option<MiddlewareFrame>);
+
+impl MiddlewareBody for SingleFrameBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async { Ok(self.0.take()) })
+    }
+
+    fn close(self: Box<Self>) -> BoxFuture<'static, ()> {
+        Box::pin(async move { drop(self) })
+    }
+}
+
+struct ResponseMiddlewareBody {
+    body: Box<dyn MiddlewareBody>,
+    actions: VecDeque<ResponseFrameAction>,
+    transformed_pending: bool,
+}
+
+impl MiddlewareBody for ResponseMiddlewareBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async move {
+            loop {
+                let Some(frame) = self.body.next_frame().await? else {
+                    return Ok(None);
+                };
+                let action = self
+                    .actions
+                    .pop_front()
+                    .unwrap_or(ResponseFrameAction::Continue);
+                let transformed = self.transformed_pending || frame.transformed();
+                let (bytes, framing, terminal, envelope) = frame.into_parts();
+                match action {
+                    ResponseFrameAction::Continue => {
+                        self.transformed_pending = false;
+                        let mut frame = MiddlewareFrame::new(bytes, framing, terminal)
+                            .with_transformed(transformed);
+                        if let Some(envelope) = envelope {
+                            frame = frame.with_envelope(envelope);
+                        }
+                        return Ok(Some(frame));
+                    }
+                    ResponseFrameAction::Replace(bytes) => {
+                        self.transformed_pending = false;
+                        let mut frame =
+                            MiddlewareFrame::new(bytes, framing, terminal).with_transformed(true);
+                        if let Some(envelope) = envelope {
+                            frame = frame.with_envelope(envelope);
+                        }
+                        return Ok(Some(frame));
+                    }
+                    ResponseFrameAction::Drop if envelope.is_some() => {
+                        return Err(MiddlewareError::InvalidState);
+                    }
+                    ResponseFrameAction::Drop => self.transformed_pending = true,
+                }
+            }
+        })
+    }
+
+    fn commit_downstream(
+        &mut self,
+        status: Option<u16>,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        self.body.commit_downstream(status)
+    }
+
+    fn record_client_status(&mut self, status: u16) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        self.body.record_client_status(status)
+    }
+
+    fn is_finalized(&self) -> bool {
+        self.body.is_finalized()
+    }
+
+    fn close(self: Box<Self>) -> BoxFuture<'static, ()> {
+        let Self { body, .. } = *self;
+        body.close()
+    }
+}
diff --git a/backend/crates/gateway-api/tests/openai/mod.rs b/backend/crates/gateway-api/tests/openai/mod.rs
index 63950002f..bb1f8dbb8 100644
--- a/backend/crates/gateway-api/tests/openai/mod.rs
+++ b/backend/crates/gateway-api/tests/openai/mod.rs
@@ -2,6 +2,7 @@ mod auth;
 mod endpoint;
 mod error;
 mod images;
+mod middleware;
 mod models;
 mod responses;
 mod router;
@@ -62,21 +63,63 @@ pub(super) fn api_router_with_admin(admin: gateway_admin::AdminServices) -> axum
     )
 }
 
+pub(super) fn api_router_with_admin_and_execution(
+    admin: gateway_admin::AdminServices,
+    execution: Arc<dyn ExecutionService>,
+) -> axum::Router {
+    api_router_with_config_and_execution(
+        admin,
+        gateway_api::ApiConfig {
+            asset_directory: std::env::temp_dir(),
+            cors_allowed_origins: Vec::new(),
+            request_timeout_seconds: None,
+            request_id_header: "x-request-id".to_owned(),
+        },
+        execution,
+    )
+}
+
+pub(super) fn api_router_with_admin_and_client(
+    admin: gateway_admin::AdminServices,
+    plaintext: &str,
+    client_key_id: &str,
+) -> axum::Router {
+    let execution = Arc::new(DefaultExecutionService::new(
+        RuntimeSnapshotHandle::new(snapshot_with_client_key(plaintext, "openai", client_key_id)),
+        Arc::new(UnusedExecutionStore),
+        ProviderRegistry::default(),
+        Arc::new(UnusedAdmissions),
+        Arc::new(UnusedCircuits),
+        Arc::new(UnusedContinuation),
+        Arc::new(IgnoredClientApiKeyUsage),
+    ));
+    api_router_with_admin_and_execution(admin, execution)
+}
+
 pub(super) fn api_router_with_config(
     admin: gateway_admin::AdminServices,
     config: gateway_api::ApiConfig,
+) -> axum::Router {
+    let execution = Arc::new(DefaultExecutionService::new(
+        RuntimeSnapshotHandle::new(snapshot("unused-client-route-key", "openai")),
+        Arc::new(UnusedExecutionStore),
+        ProviderRegistry::default(),
+        Arc::new(UnusedAdmissions),
+        Arc::new(UnusedCircuits),
+        Arc::new(UnusedContinuation),
+        Arc::new(IgnoredClientApiKeyUsage),
+    ));
+    api_router_with_config_and_execution(admin, config, execution)
+}
+
+fn api_router_with_config_and_execution(
+    admin: gateway_admin::AdminServices,
+    config: gateway_api::ApiConfig,
+    execution: Arc<dyn ExecutionService>,
 ) -> axum::Router {
     gateway_api::initialize(
         config,
-        Arc::new(DefaultExecutionService::new(
-            RuntimeSnapshotHandle::new(snapshot("unused-client-route-key", "openai")),
-            Arc::new(UnusedExecutionStore),
-            ProviderRegistry::default(),
-            Arc::new(UnusedAdmissions),
-            Arc::new(UnusedCircuits),
-            Arc::new(UnusedContinuation),
-            Arc::new(IgnoredClientApiKeyUsage),
-        )),
+        execution,
         admin,
         Vec::new(),
         Arc::new(EmptyWorkerHealth),
@@ -191,6 +234,14 @@ impl ClientApiKeyUsageSink for IgnoredClientApiKeyUsage {
 }
 
 fn snapshot(plaintext: &str, provider_name: &str) -> RuntimeSnapshot {
+    snapshot_with_client_key(plaintext, provider_name, "key_api_test")
+}
+
+fn snapshot_with_client_key(
+    plaintext: &str,
+    provider_name: &str,
+    client_key_id: &str,
+) -> RuntimeSnapshot {
     let provider = ProviderKind::new(provider_name).expect("provider");
     let account_directory = Arc::new(RuntimeAccountDirectory::new(BTreeMap::from([(
         ProviderAccountId::new("acct_api_test").expect("account ID"),
@@ -219,7 +270,7 @@ fn snapshot(plaintext: &str, provider_name: &str) -> RuntimeSnapshot {
             })
             .collect(),
         vec![ClientPolicy::new(
-            ClientApiKeyId::new("key_api_test").expect("key ID"),
+            ClientApiKeyId::new(client_key_id).expect("key ID"),
             PlaintextClientApiKey::new(plaintext).expect("plaintext key"),
             Arc::new(FrozenAccountScope::new(
                 Arc::clone(&account_directory),
diff --git a/backend/crates/gateway-api/tests/openai/models.rs b/backend/crates/gateway-api/tests/openai/models.rs
index 0df1bc7be..60bd9383b 100644
--- a/backend/crates/gateway-api/tests/openai/models.rs
+++ b/backend/crates/gateway-api/tests/openai/models.rs
@@ -4,6 +4,7 @@ use axum::{
     body::{Body, to_bytes},
     http::{Request, StatusCode, header::AUTHORIZATION},
 };
+use bytes::Bytes;
 use futures::future::BoxFuture;
 use gateway_core::engine::execution::{
     AuthenticatedClient, ClientAuthenticationError, ExecutionService, StartExecution,
@@ -23,6 +24,7 @@ pub(super) struct ModelsExecution {
     presentation: Option<ModelPresentation>,
     native: Option<Result<Vec<PublicModelDescriptor>, ProviderCatalogUnavailable>>,
     requested_versions: Mutex<Vec<String>>,
+    middleware: Option<Arc<crate::openai::middleware::RequestMiddleware>>,
 }
 
 impl ModelsExecution {
@@ -32,6 +34,7 @@ impl ModelsExecution {
             presentation: None,
             native: None,
             requested_versions: Mutex::default(),
+            middleware: None,
         })
     }
 
@@ -68,6 +71,7 @@ impl ModelsExecution {
             presentation: Some(presentation),
             native: None,
             requested_versions: Mutex::default(),
+            middleware: None,
         })
     }
 
@@ -77,6 +81,7 @@ impl ModelsExecution {
             presentation: None,
             native: None,
             requested_versions: Mutex::default(),
+            middleware: None,
         })
     }
 
@@ -90,6 +95,7 @@ impl ModelsExecution {
             presentation: None,
             native: None,
             requested_versions: Mutex::default(),
+            middleware: None,
         })
     }
 
@@ -108,6 +114,15 @@ impl ModelsExecution {
 }
 
 impl ExecutionService for ModelsExecution {
+    fn middleware_plan(
+        &self,
+        _: &gateway_core::engine::execution::PreparedRootExecution,
+    ) -> Option<gateway_core::engine::middleware::FrozenMiddlewarePlan> {
+        self.middleware
+            .as_ref()
+            .map(|middleware| middleware.frozen())
+    }
+
     fn client_model_catalog<'a>(
         &'a self,
         _client: &'a AuthenticatedClient,
@@ -181,6 +196,81 @@ fn authorized_request(path: &str) -> Request<Body> {
         .expect("build models request")
 }
 
+#[tokio::test]
+async fn model_queries_enter_the_same_chain_after_auth_and_hold_generation_until_body_end() {
+    use std::sync::atomic::Ordering;
+
+    let middleware = Arc::new(crate::openai::middleware::RequestMiddleware::default());
+    let mut execution = ModelsExecution::new();
+    Arc::get_mut(&mut execution).unwrap().middleware = Some(middleware.clone());
+    let app = api_router(execution).await;
+    let unauthenticated = Request::get("/v1/models").body(Body::empty()).unwrap();
+    assert_eq!(
+        app.clone().oneshot(unauthenticated).await.unwrap().status(),
+        StatusCode::UNAUTHORIZED
+    );
+    assert!(middleware.endpoints.lock().unwrap().is_empty());
+
+    for (path, status) in [
+        ("/v1/models", StatusCode::OK),
+        ("/v1/models/model-a", StatusCode::OK),
+        ("/v1/models/hidden-model", StatusCode::NOT_FOUND),
+    ] {
+        let response = app.clone().oneshot(authorized_request(path)).await.unwrap();
+        assert_eq!(response.status(), status);
+        assert_eq!(response.headers()["x-request-middleware"], "applied");
+        assert_eq!(middleware.live_leases.load(Ordering::SeqCst), 1);
+        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
+        assert!(!body.is_empty());
+        assert_eq!(middleware.live_leases.load(Ordering::SeqCst), 0);
+    }
+    assert_eq!(
+        *middleware.endpoints.lock().unwrap(),
+        [
+            "/v1/models",
+            "/v1/models/model-a",
+            "/v1/models/hidden-model"
+        ]
+    );
+}
+
+#[tokio::test]
+async fn model_query_middleware_short_circuit_sets_json_content_type_without_calling_terminal() {
+    let middleware = Arc::new(
+        crate::openai::middleware::RequestMiddleware::default().with_json_short_circuit(
+            Bytes::from_static(br#"{"object":"list","data":[],"source":"middleware"}"#),
+        ),
+    );
+    let mut execution = ModelsExecution::new();
+    Arc::get_mut(&mut execution).unwrap().middleware = Some(middleware);
+
+    let response = api_router(execution.clone())
+        .await
+        .oneshot(authorized_request(
+            "/v1/models?client_version=0.154.0-alpha.3",
+        ))
+        .await
+        .expect("short-circuit response");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(response.headers()["content-type"], "application/json");
+    let body = to_bytes(response.into_body(), usize::MAX)
+        .await
+        .expect("short-circuit body");
+    assert_eq!(
+        serde_json::from_slice::<serde_json::Value>(&body).expect("short-circuit JSON"),
+        serde_json::json!({"object":"list","data":[],"source":"middleware"})
+    );
+    assert!(
+        execution
+            .requested_versions
+            .lock()
+            .expect("versions")
+            .is_empty(),
+        "terminal catalog lookup must not run after middleware short circuit"
+    );
+}
+
 #[tokio::test]
 async fn native_catalog_preserves_complete_objects_and_only_rewrites_alias_slug() {
     let original = serde_json::json!({
@@ -204,6 +294,7 @@ async fn native_catalog_preserves_complete_objects_and_only_rewrites_alias_slug(
         presentation: None,
         native: Some(Ok(vec![entry("gpt-native"), entry("my-alias")])),
         requested_versions: Mutex::default(),
+        middleware: None,
     });
     let response = api_router(execution.clone())
         .await
@@ -236,6 +327,7 @@ async fn native_catalog_failure_does_not_publish_a_synthetic_or_empty_success()
         presentation: None,
         native: Some(Err(ProviderCatalogUnavailable)),
         requested_versions: Mutex::default(),
+        middleware: None,
     });
     let response = api_router(execution)
         .await
diff --git a/backend/crates/gateway-api/tests/openai/responses/http.rs b/backend/crates/gateway-api/tests/openai/responses/http.rs
index 74cb5fa78..7c43ef435 100644
--- a/backend/crates/gateway-api/tests/openai/responses/http.rs
+++ b/backend/crates/gateway-api/tests/openai/responses/http.rs
@@ -3,7 +3,7 @@ use std::io::Read;
 use std::net::{IpAddr, SocketAddr};
 use std::sync::{
     Arc, Mutex,
-    atomic::{AtomicBool, Ordering},
+    atomic::{AtomicBool, AtomicUsize, Ordering},
 };
 use std::time::Duration;
 
@@ -23,6 +23,7 @@ use gateway_core::engine::execution::{
     AuthenticatedClient, ClientAuthenticationError, ExecutionService, ExecutionSession,
     StartExecution, StartProviderExecution, StartedExecution,
 };
+use gateway_core::engine::middleware::{FrozenMiddlewarePlan, MiddlewareHeader};
 use gateway_core::engine::{CommitRequirement, CoordinatedEvent, EngineError, ModelRequestId};
 use gateway_core::error::{
     ClientVisibleUpstreamError, ClientVisibleUpstreamResponse, GatewayError, GatewayErrorKind,
@@ -41,15 +42,24 @@ use serde_json::{Value, json};
 use gateway_api::openai::responses::{collect_execution_response, stream_execution_response};
 use tower::ServiceExt;
 
+use crate::openai::middleware::{RequestMiddleware, ResponseFrameAction};
 use crate::openai::{
     api_router, authenticated_client_for_provider, authenticated_client_with_min_versions,
 };
 
+fn responses_middleware() -> RequestMiddleware {
+    RequestMiddleware {
+        expected_operation: Some(OperationKind::Generate),
+        ..RequestMiddleware::default()
+    }
+}
+
 #[derive(Default)]
 struct Trace {
     events: Mutex<Vec<&'static str>>,
     client_statuses: Mutex<Vec<u16>>,
     cancelled: AtomicBool,
+    detached_finalizations: AtomicUsize,
 }
 
 impl Trace {
@@ -82,6 +92,10 @@ impl Trace {
     fn is_cancelled(&self) -> bool {
         self.cancelled.load(Ordering::Acquire)
     }
+
+    fn detached_finalizations(&self) -> usize {
+        self.detached_finalizations.load(Ordering::Acquire)
+    }
 }
 
 enum NextStep {
@@ -335,6 +349,11 @@ impl ExecutionSession for FakeSession {
         &self.response_headers
     }
 
+    fn discard_pending_delivery(&mut self) -> Result<(), EngineError> {
+        self.trace.push("discard");
+        Ok(())
+    }
+
     fn commit_downstream(
         &mut self,
         client_status_code: Option<u16>,
@@ -372,6 +391,9 @@ impl ExecutionSession for FakeSession {
 
     fn detach_finalize(mut self: Box<Self>) -> BoxFuture<'static, ()> {
         Box::pin(async move {
+            self.trace
+                .detached_finalizations
+                .fetch_add(1, Ordering::AcqRel);
             if !self.finalized {
                 let _ = self.next_event().await;
             }
@@ -835,6 +857,268 @@ async fn streaming_encodes_first_frame_before_commit_and_http_delivery() {
     std::mem::forget(response);
 }
 
+#[tokio::test]
+async fn streaming_dropped_unknown_initial_batch_discards_without_committing() {
+    let trace = Arc::new(Trace::default());
+    let dropped_raw = Bytes::from_static(
+        b"event: response.future_metadata\ndata: {\"type\":\"response.future_metadata\",\"dropped\":true}\n\n",
+    );
+    let dropped = ProviderEvent::wire(
+        ProtocolWireEvent::raw_sse("openai", dropped_raw.clone()).expect("future SSE event"),
+    );
+    let session = FakeSession::streaming(
+        Arc::clone(&trace),
+        vec![
+            NextStep::Event(delivery_provider(
+                dropped,
+                CommitRequirement::CommitBeforeDelivery,
+            )),
+            NextStep::Event(delivery(started(), CommitRequirement::CommitBeforeDelivery)),
+            NextStep::Event(delivery(completed(), CommitRequirement::AlreadyCommitted)),
+            NextStep::FinalizeSuccess,
+        ],
+    );
+    let middleware = Arc::new(responses_middleware().with_response_actions(vec![
+        ResponseFrameAction::Drop,
+        ResponseFrameAction::Continue,
+        ResponseFrameAction::Continue,
+        ResponseFrameAction::Continue,
+    ]));
+
+    let response = response_with_middleware("openai", session, true, Some(middleware)).await;
+    let body = to_bytes(response.into_body(), usize::MAX)
+        .await
+        .expect("read filtered SSE response");
+
+    assert!(!body.as_ref().starts_with(dropped_raw.as_ref()));
+    assert!(!String::from_utf8_lossy(&body).contains("\"dropped\":true"));
+    assert!(String::from_utf8_lossy(&body).contains("response.created"));
+    assert!(String::from_utf8_lossy(&body).contains("response.completed"));
+    assert!(body.as_ref().ends_with(b"data: [DONE]\n\n"));
+    assert_eq!(trace.client_statuses(), vec![200]);
+    assert_eq!(
+        trace.snapshot(),
+        vec![
+            "next_event",
+            "discard",
+            "next_event",
+            "commit",
+            "next_event",
+            "next_end"
+        ]
+    );
+    assert_eq!(trace.detached_finalizations(), 0);
+}
+
+#[tokio::test]
+async fn streaming_modified_sse_rejects_out_of_order_tool_events_without_replay() {
+    let trace = Arc::new(Trace::default());
+    let added = super::openai_wire_event(
+        vec![],
+        "response.output_item.added",
+        json!({
+            "type": "response.output_item.added",
+            "output_index": 0,
+            "item": {
+                "id": "item_tool", "type": "function_call",
+                "call_id": "call_tool", "name": "lookup"
+            }
+        }),
+    );
+    let out_of_order = encode_sse_event(
+        "response.function_call_arguments.done",
+        &json!({
+            "type": "response.function_call_arguments.done",
+            "output_index": 0, "item_id": "item_tool",
+            "call_id": "call_tool", "arguments": "{}"
+        })
+        .to_string(),
+    );
+    let session = FakeSession::streaming(
+        Arc::clone(&trace),
+        vec![
+            NextStep::Event(delivery(started(), CommitRequirement::CommitBeforeDelivery)),
+            NextStep::Event(delivery_provider(
+                added,
+                CommitRequirement::AlreadyCommitted,
+            )),
+            NextStep::FinalizeCancelled,
+        ],
+    );
+    let middleware = Arc::new(responses_middleware().with_response_actions(vec![
+        ResponseFrameAction::Continue,
+        ResponseFrameAction::Replace(Bytes::from(out_of_order)),
+    ]));
+
+    let response = response_with_middleware("openai", session, true, Some(middleware)).await;
+    let body = to_bytes(response.into_body(), usize::MAX)
+        .await
+        .expect("read rejected transformed SSE");
+    tokio::task::yield_now().await;
+    let body = String::from_utf8(body.to_vec()).expect("gateway SSE is UTF-8");
+
+    assert_eq!(body.matches("event: response.created").count(), 1);
+    assert!(!body.contains("response.function_call_arguments.done"));
+    assert!(body.contains("response.failed"));
+    assert!(body.ends_with("data: [DONE]\n\n"));
+    assert!(trace.is_cancelled());
+    assert_eq!(
+        trace.snapshot(),
+        vec!["next_event", "commit", "next_event", "cancel_finalize"]
+    );
+}
+
+#[tokio::test]
+async fn streaming_modified_sse_rejects_wrong_tool_association_without_replay() {
+    let trace = Arc::new(Trace::default());
+    let added = super::openai_wire_event(
+        vec![],
+        "response.output_item.added",
+        json!({
+            "type": "response.output_item.added",
+            "output_index": 0,
+            "item": {
+                "id": "item_tool", "type": "function_call",
+                "call_id": "call_tool", "name": "lookup"
+            }
+        }),
+    );
+    let arguments = super::openai_wire_event(
+        vec![],
+        "response.function_call_arguments.delta",
+        json!({
+            "type": "response.function_call_arguments.delta",
+            "output_index": 0, "item_id": "item_tool",
+            "call_id": "call_tool", "delta": "{}"
+        }),
+    );
+    let wrong_association = encode_sse_event(
+        "response.function_call_arguments.delta",
+        &json!({
+            "type": "response.function_call_arguments.delta",
+            "output_index": 0, "item_id": "item_tool",
+            "call_id": "call_other", "delta": "{}"
+        })
+        .to_string(),
+    );
+    let session = FakeSession::streaming(
+        Arc::clone(&trace),
+        vec![
+            NextStep::Event(delivery(started(), CommitRequirement::CommitBeforeDelivery)),
+            NextStep::Event(delivery_provider(
+                added,
+                CommitRequirement::AlreadyCommitted,
+            )),
+            NextStep::Event(delivery_provider(
+                arguments,
+                CommitRequirement::AlreadyCommitted,
+            )),
+            NextStep::FinalizeCancelled,
+        ],
+    );
+    let middleware = Arc::new(responses_middleware().with_response_actions(vec![
+        ResponseFrameAction::Continue,
+        ResponseFrameAction::Continue,
+        ResponseFrameAction::Replace(Bytes::from(wrong_association)),
+    ]));
+
+    let response = response_with_middleware("openai", session, true, Some(middleware)).await;
+    let body = to_bytes(response.into_body(), usize::MAX)
+        .await
+        .expect("read rejected transformed SSE");
+    tokio::task::yield_now().await;
+    let body = String::from_utf8(body.to_vec()).expect("gateway SSE is UTF-8");
+
+    assert!(!body.contains("call_other"));
+    assert!(body.contains("response.failed"));
+    assert_eq!(body.matches("event: response.created").count(), 1);
+    assert_eq!(
+        trace.snapshot(),
+        vec![
+            "next_event",
+            "commit",
+            "next_event",
+            "next_event",
+            "cancel_finalize"
+        ]
+    );
+}
+
+#[tokio::test]
+async fn streaming_modified_sse_cannot_change_terminal_classification() {
+    let trace = Arc::new(Trace::default());
+    let incomplete = encode_sse_event(
+        "response.incomplete",
+        &json!({
+            "type": "response.incomplete",
+            "response": {
+                "id": "resp_test", "model": "public-model",
+                "status": "incomplete", "output": []
+            }
+        })
+        .to_string(),
+    );
+    let session = FakeSession::streaming(
+        Arc::clone(&trace),
+        vec![
+            NextStep::Event(delivery(started(), CommitRequirement::CommitBeforeDelivery)),
+            NextStep::Event(delivery(completed(), CommitRequirement::AlreadyCommitted)),
+            NextStep::FinalizeSuccess,
+        ],
+    );
+    let middleware = Arc::new(responses_middleware().with_response_actions(vec![
+        ResponseFrameAction::Continue,
+        ResponseFrameAction::Replace(Bytes::from(incomplete)),
+    ]));
+
+    let response = response_with_middleware("openai", session, true, Some(middleware)).await;
+    let body = to_bytes(response.into_body(), usize::MAX)
+        .await
+        .expect("read terminal-class rejection");
+    tokio::task::yield_now().await;
+    let body = String::from_utf8(body.to_vec()).expect("gateway SSE is UTF-8");
+
+    assert!(body.contains("response.failed"));
+    assert!(!body.contains("response.incomplete"));
+    assert_eq!(body.matches("event: response.created").count(), 1);
+    assert_eq!(
+        trace.snapshot(),
+        vec!["next_event", "commit", "next_event", "next_end"]
+    );
+    assert!(!trace.is_cancelled());
+}
+
+#[tokio::test]
+async fn streaming_terminal_drop_fails_before_commit() {
+    let trace = Arc::new(Trace::default());
+    let session = FakeSession::streaming(
+        Arc::clone(&trace),
+        vec![
+            NextStep::Event(delivery(
+                completed(),
+                CommitRequirement::CommitBeforeDelivery,
+            )),
+            NextStep::FinalizeCancelled,
+        ],
+    );
+    let middleware =
+        Arc::new(responses_middleware().with_response_actions(vec![ResponseFrameAction::Drop]));
+
+    let response = response_with_middleware("openai", session, true, Some(middleware)).await;
+
+    assert_eq!(response.status(), StatusCode::BAD_GATEWAY);
+    let body = to_bytes(response.into_body(), usize::MAX)
+        .await
+        .expect("read middleware error response");
+    assert_eq!(
+        serde_json::from_slice::<Value>(&body).expect("middleware error JSON")["error"]["code"],
+        "middleware_failed"
+    );
+    assert_eq!(trace.client_statuses(), vec![502]);
+    assert!(trace.is_cancelled());
+    assert!(!trace.snapshot().contains(&"commit"));
+}
+
 #[tokio::test(start_paused = true)]
 async fn streaming_should_keep_alive_during_silent_compaction_without_restarting_execution() {
     let trace = Arc::new(Trace::default());
@@ -922,6 +1206,7 @@ async fn dropping_stream_during_keepalive_should_cancel_and_finalize_execution()
         trace.snapshot(),
         vec!["next_event", "commit", "wait_event", "cancel_finalize"]
     );
+    assert_eq!(trace.detached_finalizations(), 1);
 }
 
 #[tokio::test(start_paused = true)]
@@ -1396,6 +1681,7 @@ async fn streaming_success_should_emit_terminal_event_and_done_marker() {
             "next_end",
         ]
     );
+    assert_eq!(trace.detached_finalizations(), 0);
 }
 
 #[tokio::test]
@@ -1464,6 +1750,7 @@ async fn streaming_completed_event_without_finalized_execution_should_fail_close
             "cancel_finalize"
         ]
     );
+    assert_eq!(trace.detached_finalizations(), 1);
 }
 
 #[tokio::test]
@@ -1910,6 +2197,257 @@ async fn buffered_response_commits_only_after_complete_json_is_encoded() {
     assert!(!trace.is_cancelled());
 }
 
+#[tokio::test]
+async fn buffered_response_collects_completed_output_items_without_rewriting_streams() {
+    let message = json!({
+        "id": "msg_test", "type": "message", "role": "assistant", "status": "completed",
+        "content": [{"type": "output_text", "text": "完整文本", "annotations": []}],
+        "future_item_field": {"keep": true}
+    });
+    let tool = json!({
+        "id": "fc_test", "type": "function_call", "call_id": "call_test",
+        "name": "calculate", "arguments": "{\"value\":42}", "status": "completed"
+    });
+    let terminal = json!({
+        "id": "resp_test", "status": "completed", "output": [],
+        "usage": {"input_tokens": 20, "output_tokens": 8, "total_tokens": 28},
+        "future_terminal_field": {"keep": true}
+    });
+    let mut events = vec![provider_event_for_fact(started())];
+    // 完成顺序不决定输出顺序；相同完成项重传不能产生重复正文。
+    for (index, item) in [(1, &tool), (0, &message), (0, &message)] {
+        events.push(super::openai_wire_event(
+            vec![],
+            "response.output_item.done",
+            json!({"type": "response.output_item.done", "output_index": index, "item": item}),
+        ));
+    }
+    events.push(super::openai_wire_event(
+        vec![],
+        "response.completed",
+        json!({"type": "response.completed", "response": terminal}),
+    ));
+    let mut sse = super::OpenAiResponsesEncoder::new();
+    let mut websocket = super::OpenAiResponsesEncoder::new();
+    for event in &events {
+        let frames = sse.push_sse(event);
+        let messages = websocket.push_websocket(event);
+        let wire = event.wire_event().unwrap();
+        let parsed = parse_sse_events(std::str::from_utf8(&frames.concat()).unwrap()).unwrap();
+        assert_eq!(
+            serde_json::from_str::<Value>(&parsed[0].data).unwrap(),
+            *wire.data()
+        );
+        assert_eq!(
+            serde_json::from_str::<Value>(&messages[0]).unwrap(),
+            *wire.data()
+        );
+    }
+    assert_eq!(sse.finish().unwrap(), terminal);
+    assert_eq!(websocket.finish().unwrap(), terminal);
+
+    let trace = Arc::new(Trace::default());
+    let session = FakeSession::buffered_provider(Arc::clone(&trace), events);
+    let response = collect_execution_response(Box::new(session)).await;
+    assert_eq!(response.status(), StatusCode::OK);
+    let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
+    let mut expected = terminal;
+    expected["output"] = json!([message, tool]);
+    assert_eq!(serde_json::from_slice::<Value>(&body).unwrap(), expected);
+    assert_eq!(trace.snapshot(), ["collect", "commit"]);
+    assert!(!trace.is_cancelled());
+}
+
+#[tokio::test]
+async fn buffered_response_keeps_authoritative_terminal_and_supports_omitted_output() {
+    let item = json!({"id": "rs_test", "type": "reasoning", "encrypted_content": "opaque"});
+    for (terminal, expected_output) in [
+        (
+            json!({"id": "resp_test", "output": [{"type": "future", "result": "terminal"}]}),
+            json!([{"type": "future", "result": "terminal"}]),
+        ),
+        (
+            json!({"id": "resp_test", "status": "incomplete", "incomplete_details": {"reason": "max_output_tokens"}}),
+            json!([item]),
+        ),
+    ] {
+        let trace = Arc::new(Trace::default());
+        let event_type = if terminal["status"] == "incomplete" {
+            "response.incomplete"
+        } else {
+            "response.completed"
+        };
+        let session = FakeSession::buffered_provider(
+            Arc::clone(&trace),
+            vec![
+                provider_event_for_fact(started()),
+                super::openai_wire_event(
+                    vec![],
+                    "response.output_item.done",
+                    json!({"output_index": 0, "item": item}),
+                ),
+                super::openai_wire_event(vec![], event_type, json!({"response": terminal})),
+            ],
+        );
+        let response = collect_execution_response(Box::new(session)).await;
+        assert_eq!(response.status(), StatusCode::OK);
+        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
+        let mut expected = terminal;
+        expected["output"] = expected_output;
+        assert_eq!(serde_json::from_slice::<Value>(&body).unwrap(), expected);
+        assert_eq!(trace.snapshot(), ["collect", "commit"]);
+    }
+}
+
+#[tokio::test]
+async fn buffered_response_rejects_incomplete_or_conflicting_output_items_before_commit() {
+    let item =
+        json!({"id": "msg_test", "type": "message", "content": [{"text": "private-output"}]});
+    for done_items in [
+        vec![json!({"output_index": 1, "item": item})],
+        vec![json!({"output_index": u64::MAX, "item": item})],
+        vec![json!({"output_index": -1, "item": item})],
+        vec![json!({"item": item})],
+        vec![json!({"output_index": 0, "item": []})],
+        vec![
+            json!({"output_index": 0, "item": item}),
+            json!({"output_index": 0, "item": {"type": "different"}}),
+        ],
+    ] {
+        let trace = Arc::new(Trace::default());
+        let mut events = vec![provider_event_for_fact(started())];
+        events.extend(
+            done_items
+                .into_iter()
+                .map(|item| super::openai_wire_event(vec![], "response.output_item.done", item)),
+        );
+        events.push(super::openai_wire_event(
+            vec![],
+            "response.completed",
+            json!({"response": {"id": "resp_test", "output": []}}),
+        ));
+        let response = collect_execution_response(Box::new(FakeSession::buffered_provider(
+            Arc::clone(&trace),
+            events,
+        )))
+        .await;
+        assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
+        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
+        let value: Value = serde_json::from_slice(&body).unwrap();
+        assert_eq!(value["error"]["code"], "invalid_upstream_response");
+        assert!(!String::from_utf8_lossy(&body).contains("private-output"));
+        assert!(!trace.snapshot().contains(&"commit"));
+        assert!(trace.is_cancelled());
+    }
+}
+
+#[tokio::test]
+async fn buffered_response_never_merges_items_from_a_different_wire_response() {
+    for conflicting_event in [
+        json!({"output_index": 0, "item": {"type": "message", "content": [{"text": "earlier-response"}]}}),
+        json!({"response_id": "foreign-response", "output_index": 0, "item": {"type": "message", "content": [{"text": "foreign-response"}]}}),
+    ] {
+        let trace = Arc::new(Trace::default());
+        let terminal_id = if conflicting_event.get("response_id").is_some() {
+            "resp_test"
+        } else {
+            "new-response"
+        };
+        let terminal = json!({"id": terminal_id, "status": "completed", "output": []});
+        let events = vec![
+            provider_event_for_fact(started()),
+            super::openai_wire_event(vec![], "response.output_item.done", conflicting_event),
+            super::openai_wire_event(vec![], "response.completed", json!({"response": terminal})),
+        ];
+        let response = collect_execution_response(Box::new(FakeSession::buffered_provider(
+            Arc::clone(&trace),
+            events,
+        )))
+        .await;
+        assert_eq!(response.status(), StatusCode::OK);
+        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
+        assert_eq!(serde_json::from_slice::<Value>(&body).unwrap(), terminal);
+        assert_eq!(trace.snapshot(), ["collect", "commit"]);
+    }
+}
+
+#[tokio::test]
+async fn buffered_response_middleware_replaces_body_and_filters_unsafe_headers() {
+    let trace = Arc::new(Trace::default());
+    let session = FakeSession::buffered(Arc::clone(&trace), vec![started(), completed()]);
+    let middleware = Arc::new(
+        responses_middleware()
+            .with_response_actions(vec![ResponseFrameAction::Replace(
+            Bytes::from_static(
+                b"{\"id\":\"resp_test\",\"status\":\"completed\",\"output\":[],\"future_policy_field\":true}",
+            ),
+            )])
+            .with_response_headers(vec![
+                MiddlewareHeader::new("x-policy-result", Bytes::from_static(b"replaced")),
+                MiddlewareHeader::new("authorization", Bytes::from_static(b"hidden")),
+            ]),
+    );
+
+    let response = response_with_middleware("openai", session, false, Some(middleware)).await;
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(response.headers()["x-policy-result"], "replaced");
+    assert!(response.headers().get(AUTHORIZATION).is_none());
+    let body = to_bytes(response.into_body(), usize::MAX)
+        .await
+        .expect("read policy JSON body");
+    assert_eq!(
+        serde_json::from_slice::<Value>(&body).expect("policy response JSON"),
+        json!({
+            "id": "resp_test", "status": "completed", "output": [],
+            "future_policy_field": true
+        })
+    );
+    assert_eq!(trace.client_statuses(), vec![200]);
+    assert_eq!(trace.snapshot(), vec!["collect", "commit"]);
+}
+
+#[tokio::test]
+async fn buffered_response_middleware_rejects_missing_terminal_fields_or_duplicate_tool_identity() {
+    for replacement in [
+        json!({"id": "resp_test", "output": []}),
+        json!({"id": "resp_test", "status": "incomplete", "output": []}),
+        json!({
+            "id": "resp_test", "status": "completed", "output": [
+                {
+                    "id": "item_a", "type": "function_call", "call_id": "call_same",
+                    "name": "first", "arguments": "{}"
+                },
+                {
+                    "id": "item_b", "type": "function_call", "call_id": "call_same",
+                    "name": "second", "arguments": "{}"
+                }
+            ]
+        }),
+    ] {
+        let trace = Arc::new(Trace::default());
+        let session = FakeSession::buffered(Arc::clone(&trace), vec![started(), completed()]);
+        let middleware = Arc::new(responses_middleware().with_response_actions(vec![
+            ResponseFrameAction::Replace(Bytes::from(
+                serde_json::to_vec(&replacement).expect("replacement JSON"),
+            )),
+        ]));
+
+        let response = response_with_middleware("openai", session, false, Some(middleware)).await;
+        assert_eq!(response.status(), StatusCode::BAD_GATEWAY);
+        let body = to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("read middleware error response");
+        assert_eq!(
+            serde_json::from_slice::<Value>(&body).expect("middleware error JSON")["error"]["code"],
+            "middleware_failed"
+        );
+        assert_eq!(trace.client_statuses(), vec![502]);
+        assert!(!trace.snapshot().contains(&"commit"));
+        assert!(trace.is_cancelled());
+        assert_eq!(trace.snapshot(), vec!["collect", "cancel_finalize"]);
+    }
+}
+
 #[tokio::test]
 async fn buffered_response_forwards_long_ordinary_provider_header_values() {
     let trace = Arc::new(Trace::default());
@@ -2007,6 +2545,7 @@ const MODEL_REQUEST_ID: &str = "req_model_correlation";
 struct SessionExecution {
     client: AuthenticatedClient,
     session: Mutex<Option<Box<dyn ExecutionSession>>>,
+    middleware: Option<FrozenMiddlewarePlan>,
 }
 
 #[tokio::test]
@@ -2040,6 +2579,7 @@ async fn chatgpt_remote_responses_should_only_skip_missing_desktop_versions() {
                         NextStep::FinalizeSuccess,
                     ],
                 )))),
+                middleware: None,
             });
             let mut request = Request::post("/v1/responses")
                 .header(AUTHORIZATION, "Bearer sk_remote_test")
@@ -2128,6 +2668,13 @@ impl ExecutionService for SessionExecution {
         true
     }
 
+    fn middleware_plan(
+        &self,
+        _: &gateway_core::engine::execution::PreparedRootExecution,
+    ) -> Option<FrozenMiddlewarePlan> {
+        self.middleware.clone()
+    }
+
     fn start(
         &self,
         request: StartExecution,
@@ -2154,10 +2701,20 @@ async fn response(
     provider: &str,
     session: FakeSession,
     streaming: bool,
+) -> axum::response::Response {
+    response_with_middleware(provider, session, streaming, None).await
+}
+
+async fn response_with_middleware(
+    provider: &str,
+    session: FakeSession,
+    streaming: bool,
+    middleware: Option<Arc<RequestMiddleware>>,
 ) -> axum::response::Response {
     let execution = Arc::new(SessionExecution {
         client: authenticated_client_for_provider("sk_correlation_test", provider),
         session: Mutex::new(Some(Box::new(session))),
+        middleware: middleware.map(|middleware| middleware.frozen()),
     });
     api_router(execution)
         .await
diff --git a/backend/crates/gateway-api/tests/openai/responses/websocket/mod.rs b/backend/crates/gateway-api/tests/openai/responses/websocket/mod.rs
index fadb243b1..02d31ed91 100644
--- a/backend/crates/gateway-api/tests/openai/responses/websocket/mod.rs
+++ b/backend/crates/gateway-api/tests/openai/responses/websocket/mod.rs
@@ -1030,7 +1030,7 @@ impl Provider for ChargedWebSocketProvider {
     }
 
     async fn execute(
-        &self,
+        self: Arc<Self>,
         request: ProviderRequest,
         _: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
diff --git a/backend/crates/gateway-api/tests/openai/search/mod.rs b/backend/crates/gateway-api/tests/openai/search/mod.rs
index aab238ebf..0bddb7ef3 100644
--- a/backend/crates/gateway-api/tests/openai/search/mod.rs
+++ b/backend/crates/gateway-api/tests/openai/search/mod.rs
@@ -16,7 +16,7 @@ use gateway_core::error::{
     ClientVisibleUpstreamResponse, GatewayError, GatewayErrorKind, ProviderError, ProviderErrorKind,
 };
 use gateway_core::event::ProviderResponseHeader;
-use gateway_core::operation::Operation;
+use gateway_core::operation::{Operation, OperationKind};
 use gateway_core::routing::PublicModelId;
 use gateway_core::upstream::UpstreamSendState;
 use serde_json::{Value, json};
@@ -41,6 +41,7 @@ struct SearchExecution {
     captured: Mutex<Vec<CapturedSearchRequest>>,
     committed_statuses: Arc<Mutex<Vec<u16>>>,
     fail_with_upstream_response: bool,
+    middleware: Option<Arc<crate::openai::middleware::RequestMiddleware>>,
 }
 
 impl SearchExecution {
@@ -50,6 +51,7 @@ impl SearchExecution {
             captured: Mutex::new(Vec::new()),
             committed_statuses: Arc::new(Mutex::new(Vec::new())),
             fail_with_upstream_response,
+            middleware: None,
         })
     }
 
@@ -59,6 +61,13 @@ impl SearchExecution {
 }
 
 impl ExecutionService for SearchExecution {
+    fn middleware_plan(
+        &self,
+        _: &gateway_core::engine::execution::PreparedRootExecution,
+    ) -> Option<gateway_core::engine::middleware::FrozenMiddlewarePlan> {
+        self.middleware.as_ref().map(|plan| plan.frozen())
+    }
+
     fn authenticate(
         &self,
         plaintext: &str,
@@ -151,7 +160,13 @@ impl ExecutionService for SearchExecution {
 
 #[tokio::test]
 async fn search_route_should_preserve_request_and_success_response_bytes() {
-    let execution = SearchExecution::new(false);
+    let mut execution = SearchExecution::new(false);
+    let middleware = Arc::new(crate::openai::middleware::RequestMiddleware {
+        expected_operation: Some(OperationKind::Search),
+        committed_statuses: Some(execution.committed_statuses.clone()),
+        ..Default::default()
+    });
+    Arc::get_mut(&mut execution).unwrap().middleware = Some(middleware.clone());
     let request_body = br#"{ "id":"search-session", "model":"gpt-future", "commands":{"search_query":[{"q":"private query"}]}, "future":1, "future":2 }"#;
     let turn_metadata =
         r#"{"session_id":"session","thread_id":"thread","turn_id":"turn","future":true}"#;
@@ -171,6 +186,11 @@ async fn search_route_should_preserve_request_and_success_response_bytes() {
         .expect("search response");
 
     assert_eq!(response.status(), StatusCode::CREATED);
+    assert_eq!(response.headers()["x-request-middleware"], "applied");
+    assert_eq!(
+        *middleware.endpoints.lock().unwrap(),
+        vec!["/v1/alpha/search"]
+    );
     assert_eq!(response.headers()["x-request-id"], "req_search_test");
     assert_eq!(
         response.headers()["x-gateway-request-id"],
diff --git a/backend/crates/gateway-api/tests/openai/usage.rs b/backend/crates/gateway-api/tests/openai/usage.rs
index 7faa10b1d..d19dd482d 100644
--- a/backend/crates/gateway-api/tests/openai/usage.rs
+++ b/backend/crates/gateway-api/tests/openai/usage.rs
@@ -1,12 +1,27 @@
+use std::sync::{
+    Arc,
+    atomic::{AtomicUsize, Ordering},
+};
+
 use axum::{
     Router,
     http::{Method, StatusCode, header},
     response::Response,
 };
 use chrono::{Duration, Utc};
+use futures::future::BoxFuture;
 use gateway_core::{
     engine::budget::{ClientBudgetLimits, ClientBudgetStatus},
+    engine::{
+        authentication::ClientAuthenticationRequest,
+        execution::{
+            AuthenticatedClient, ClientAuthenticationError, ExecutionService, StartExecution,
+            StartProviderExecution, StartedExecution,
+        },
+    },
+    error::{GatewayError, GatewayErrorKind},
     policy::ClientApiKeyId,
+    routing::PublicModelId,
 };
 use serde_json::json;
 use tower::ServiceExt as _;
@@ -41,7 +56,7 @@ async fn fixture() -> (AdminTestFixture, Router) {
         weekly_resets_at: Some((Utc::now() + Duration::days(7)).into()),
     };
     *fixture.client_key.lock().unwrap() = Some(key);
-    let app = super::api_router_with_admin(fixture.services.clone());
+    let app = super::api_router_with_admin_and_client(fixture.services.clone(), KEY, "key-42");
     (fixture, app)
 }
 
@@ -83,6 +98,106 @@ async fn usage_returns_current_key_budget_without_exposing_private_data_or_writi
     assert!(fixture.observations.lock().unwrap().summaries.is_empty());
 }
 
+struct FrontendUsageAuthentication {
+    client: AuthenticatedClient,
+    authentication_calls: AtomicUsize,
+    verification_calls: AtomicUsize,
+    middleware: Arc<crate::openai::middleware::RequestMiddleware>,
+}
+
+impl ExecutionService for FrontendUsageAuthentication {
+    fn middleware_plan(
+        &self,
+        _: &gateway_core::engine::execution::PreparedRootExecution,
+    ) -> Option<gateway_core::engine::middleware::FrozenMiddlewarePlan> {
+        Some(self.middleware.frozen())
+    }
+
+    fn authenticate(&self, _: &str) -> Result<AuthenticatedClient, ClientAuthenticationError> {
+        Err(ClientAuthenticationError::InvalidKey)
+    }
+
+    fn authenticate_request(
+        &self,
+        _: ClientAuthenticationRequest,
+    ) -> BoxFuture<'_, Result<AuthenticatedClient, ClientAuthenticationError>> {
+        self.authentication_calls.fetch_add(1, Ordering::SeqCst);
+        Box::pin(async { Err(ClientAuthenticationError::InvalidKey) })
+    }
+
+    fn verify_request(
+        &self,
+        request: ClientAuthenticationRequest,
+    ) -> BoxFuture<'_, Result<AuthenticatedClient, ClientAuthenticationError>> {
+        assert_eq!(request.authorization(), "External controlled-fixture");
+        self.verification_calls.fetch_add(1, Ordering::SeqCst);
+        let client = self.client.clone();
+        Box::pin(async move { Ok(client) })
+    }
+
+    fn public_models(&self, _: &AuthenticatedClient) -> Vec<PublicModelId> {
+        Vec::new()
+    }
+
+    fn contains_public_model(&self, _: &AuthenticatedClient, _: &PublicModelId) -> bool {
+        false
+    }
+
+    fn start(&self, _: StartExecution) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async {
+            Err(GatewayError::new(
+                GatewayErrorKind::Internal,
+                "usage route must not start an execution",
+            ))
+        })
+    }
+
+    fn start_provider_endpoint(
+        &self,
+        _: StartProviderExecution,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async {
+            Err(GatewayError::new(
+                GatewayErrorKind::Internal,
+                "usage route must not start a provider execution",
+            ))
+        })
+    }
+}
+
+#[tokio::test]
+async fn usage_uses_the_entry_authentication_identity_without_recording_request_usage() {
+    let fixture = key_fixture().await;
+    let id = ClientApiKeyId::new("key_api_test").unwrap();
+    let key = fixture
+        .services
+        .client_keys()
+        .reveal(&id)
+        .await
+        .unwrap()
+        .record;
+    *fixture.client_key.lock().unwrap() = Some(key);
+    let execution = Arc::new(FrontendUsageAuthentication {
+        client: super::authenticated_client("unused-native-key"),
+        authentication_calls: AtomicUsize::new(0),
+        verification_calls: AtomicUsize::new(0),
+        middleware: Arc::new(crate::openai::middleware::RequestMiddleware::default()),
+    });
+    let app =
+        super::api_router_with_admin_and_execution(fixture.services.clone(), execution.clone());
+
+    let response = query(&app, "/v1/usage", Some("External controlled-fixture")).await;
+    assert_eq!(response.headers()["x-request-middleware"], "applied");
+    assert_eq!(
+        *execution.middleware.endpoints.lock().unwrap(),
+        ["/v1/usage"]
+    );
+
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(execution.verification_calls.load(Ordering::SeqCst), 1);
+    assert_eq!(execution.authentication_calls.load(Ordering::SeqCst), 0);
+}
+
 #[tokio::test]
 async fn usage_remains_readable_when_exhausted_and_never_returns_negative_remaining() {
     let (fixture, app) = fixture().await;
diff --git a/backend/crates/gateway-api/tests/provider.rs b/backend/crates/gateway-api/tests/provider.rs
new file mode 100644
index 000000000..ec821607e
--- /dev/null
+++ b/backend/crates/gateway-api/tests/provider.rs
@@ -0,0 +1,474 @@
+use std::{
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicBool, Ordering},
+    },
+    time::SystemTime,
+};
+
+use axum::{
+    body::{Body, to_bytes},
+    http::{Method, Request, StatusCode, header::AUTHORIZATION},
+};
+use bytes::Bytes;
+use futures::future::BoxFuture;
+use gateway_core::{
+    engine::execution::{
+        AuthenticatedClient, ClientAuthenticationError, ExecutionService, ExecutionSession,
+        StartExecution, StartProviderExecution, StartedExecution,
+    },
+    engine::{CoordinatedEvent, EngineError, ModelRequestId},
+    error::{GatewayError, GatewayErrorKind},
+    event::{ProtocolWireEvent, ProviderEvent, ProviderResponseHeader},
+    operation::{Operation, ProviderHttpMethod},
+    routing::PublicModelId,
+};
+use tower::ServiceExt as _;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum CapturedOperation {
+    CountTokens {
+        provider: String,
+        model: String,
+        protocol: String,
+        endpoint: String,
+        body: Bytes,
+    },
+    Http {
+        provider: String,
+        endpoint_id: String,
+        method: ProviderHttpMethod,
+        query: Option<String>,
+        protocol: String,
+        route: String,
+        headers: Vec<(String, Bytes)>,
+        body: Bytes,
+    },
+}
+
+struct ProviderExecution {
+    client: AuthenticatedClient,
+    captured: Mutex<Vec<CapturedOperation>>,
+}
+
+impl ProviderExecution {
+    fn new() -> Arc<Self> {
+        Arc::new(Self {
+            client: crate::openai::authenticated_client_for_provider(
+                "sk_provider_operation_test",
+                "local-echo",
+            ),
+            captured: Mutex::new(Vec::new()),
+        })
+    }
+
+    fn captured(&self) -> Vec<CapturedOperation> {
+        self.captured.lock().expect("capture lock").clone()
+    }
+}
+
+impl ExecutionService for ProviderExecution {
+    fn authenticate(
+        &self,
+        plaintext: &str,
+    ) -> Result<AuthenticatedClient, ClientAuthenticationError> {
+        (plaintext == "sk_provider_operation_test")
+            .then(|| self.client.clone())
+            .ok_or(ClientAuthenticationError::InvalidKey)
+    }
+
+    fn public_models(&self, _: &AuthenticatedClient) -> Vec<PublicModelId> {
+        Vec::new()
+    }
+
+    fn contains_public_model(&self, _: &AuthenticatedClient, _: &PublicModelId) -> bool {
+        false
+    }
+
+    fn start(&self, _: StartExecution) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async {
+            Err(GatewayError::new(
+                GatewayErrorKind::Internal,
+                "provider operation test must use a provider endpoint",
+            ))
+        })
+    }
+
+    fn start_provider_endpoint(
+        &self,
+        request: StartProviderExecution,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async move {
+            let (captured, response, status) = match request.operation {
+                Operation::CountTokens(count) => {
+                    let model = request
+                        .upstream_model
+                        .expect("token count model binding")
+                        .as_str()
+                        .to_owned();
+                    (
+                        CapturedOperation::CountTokens {
+                            provider: request.provider.as_str().to_owned(),
+                            model,
+                            protocol: request.metadata.protocol,
+                            endpoint: request.metadata.endpoint,
+                            body: count.payload().body().clone(),
+                        },
+                        SessionResponse::Json(Bytes::from_static(
+                            br#"{ "input_tokens": 2, "tokenizer":"local_whitespace_v1" }"#,
+                        )),
+                        StatusCode::OK.as_u16(),
+                    )
+                }
+                Operation::ProviderHttp(http) => {
+                    let status = if http.endpoint() == "redirect-fixture" {
+                        StatusCode::FOUND
+                    } else {
+                        StatusCode::OK
+                    };
+                    (
+                        CapturedOperation::Http {
+                            provider: request.provider.as_str().to_owned(),
+                            endpoint_id: http.endpoint().to_owned(),
+                            method: http.method(),
+                            query: http.query().map(str::to_owned),
+                            protocol: request.metadata.protocol,
+                            route: request.metadata.endpoint,
+                            headers: http
+                                .headers()
+                                .iter()
+                                .map(|header| (header.name().to_owned(), header.value().clone()))
+                                .collect(),
+                            body: http.payload().body().clone(),
+                        },
+                        SessionResponse::Opaque(match http.endpoint() {
+                            "oversized-fragment-fixture" => {
+                                vec![Bytes::from(vec![0; 64 * 1024 + 1])]
+                            }
+                            "aggregate-overflow-fixture" => {
+                                vec![Bytes::from_static(&[0; 64 * 1024]); 129]
+                            }
+                            "missing-body-fixture" => Vec::new(),
+                            "empty-body-fixture" => vec![Bytes::new()],
+                            _ => vec![
+                                Bytes::from_static(b"\0raw-provider-"),
+                                Bytes::from_static(b"body\xff"),
+                            ],
+                        }),
+                        status.as_u16(),
+                    )
+                }
+                _ => {
+                    return Err(GatewayError::new(
+                        GatewayErrorKind::Internal,
+                        "unexpected provider operation",
+                    ));
+                }
+            };
+            self.captured.lock().expect("capture lock").push(captured);
+            Ok(StartedExecution {
+                request_id: ModelRequestId::new("req_provider_operation_test").expect("request ID"),
+                created_at: SystemTime::now(),
+                stream: false,
+                session: Box::new(ProviderSession {
+                    response: Some(response),
+                    status,
+                    finalized: AtomicBool::new(false),
+                }),
+            })
+        })
+    }
+}
+
+enum SessionResponse {
+    Json(Bytes),
+    Opaque(Vec<Bytes>),
+}
+
+struct ProviderSession {
+    response: Option<SessionResponse>,
+    status: u16,
+    finalized: AtomicBool,
+}
+
+impl ExecutionSession for ProviderSession {
+    fn next_event(&mut self) -> BoxFuture<'_, Result<Option<CoordinatedEvent>, EngineError>> {
+        Box::pin(async { unreachable!("buffered provider response does not stream") })
+    }
+
+    fn collect_uncommitted(&mut self) -> BoxFuture<'_, Result<Vec<ProviderEvent>, EngineError>> {
+        Box::pin(async move {
+            match self.response.take().expect("single response") {
+                SessionResponse::Json(body) => Ok(vec![ProviderEvent::wire(
+                    ProtocolWireEvent::raw_json("token-count", body).expect("JSON protocol"),
+                )]),
+                SessionResponse::Opaque(chunks) => Ok(chunks
+                    .into_iter()
+                    .map(|body| {
+                        ProviderEvent::wire(
+                            ProtocolWireEvent::raw_http_body("provider-http", body)
+                                .expect("HTTP protocol"),
+                        )
+                    })
+                    .collect()),
+            }
+        })
+    }
+
+    fn response_headers(&self) -> &[ProviderResponseHeader] {
+        static HEADERS: std::sync::LazyLock<Vec<ProviderResponseHeader>> =
+            std::sync::LazyLock::new(|| {
+                vec![
+                    ProviderResponseHeader::new(
+                        "content-type",
+                        Bytes::from_static(b"application/x-provider"),
+                    ),
+                    ProviderResponseHeader::new("content-length", Bytes::from_static(b"9999")),
+                    ProviderResponseHeader::new("set-cookie", Bytes::from_static(b"secret=1")),
+                    ProviderResponseHeader::new(
+                        "location",
+                        Bytes::from_static(b"https://evil.invalid"),
+                    ),
+                    ProviderResponseHeader::new("connection", Bytes::from_static(b"x-hop")),
+                    ProviderResponseHeader::new("x-hop", Bytes::from_static(b"secret")),
+                    ProviderResponseHeader::new("x-provider-safe", Bytes::from_static(b"kept")),
+                ]
+            });
+        HEADERS.as_slice()
+    }
+
+    fn response_status_code(&self) -> Option<u16> {
+        Some(self.status)
+    }
+
+    fn commit_downstream(&mut self, _: Option<u16>) -> BoxFuture<'_, Result<(), EngineError>> {
+        Box::pin(async move {
+            self.finalized.store(true, Ordering::Release);
+            Ok(())
+        })
+    }
+
+    fn record_client_status(&mut self, _: u16) -> BoxFuture<'_, Result<(), EngineError>> {
+        Box::pin(async { Ok(()) })
+    }
+
+    fn is_finalized(&self) -> bool {
+        self.finalized.load(Ordering::Acquire)
+    }
+
+    fn cancel(&self) {
+        self.finalized.store(true, Ordering::Release);
+    }
+
+    fn detach_finalize(self: Box<Self>) -> BoxFuture<'static, ()> {
+        Box::pin(async move {
+            self.finalized.store(true, Ordering::Release);
+        })
+    }
+}
+
+#[tokio::test]
+async fn token_count_should_bind_provider_model_and_preserve_exact_json() {
+    let execution = ProviderExecution::new();
+    let request_body = Bytes::from_static(br#"{ "input":"one two", "future":9007199254740993 }"#);
+    let response = crate::openai::api_router(execution.clone())
+        .await
+        .oneshot(
+            Request::post("/v1/providers/local-echo/models/local-echo/count_tokens")
+                .header(AUTHORIZATION, "Bearer sk_provider_operation_test")
+                .body(Body::from(request_body.clone()))
+                .expect("token count request"),
+        )
+        .await
+        .expect("token count response");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(response.headers()["content-type"], "application/json");
+    assert_eq!(response.headers()["content-length"], "56");
+    assert_eq!(response.headers()["x-provider-safe"], "kept");
+    assert!(!response.headers().contains_key("set-cookie"));
+    assert!(!response.headers().contains_key("location"));
+    assert!(!response.headers().contains_key("x-hop"));
+    let body = to_bytes(response.into_body(), 1024).await.expect("body");
+    assert_eq!(
+        body.as_ref(),
+        br#"{ "input_tokens": 2, "tokenizer":"local_whitespace_v1" }"#
+    );
+    assert_eq!(
+        execution.captured(),
+        vec![CapturedOperation::CountTokens {
+            provider: "local-echo".to_owned(),
+            model: "local-echo".to_owned(),
+            protocol: "token-count".to_owned(),
+            endpoint: "/v1/providers/local-echo/models/local-echo/count_tokens".to_owned(),
+            body: request_body,
+        }]
+    );
+}
+
+#[tokio::test]
+async fn provider_http_should_strip_sensitive_headers_and_preserve_opaque_bytes() {
+    let execution = ProviderExecution::new();
+    let request_body = Bytes::from_static(b"\x00input\xff");
+    let response = crate::openai::api_router(execution.clone())
+        .await
+        .oneshot(
+            Request::post("/v1/providers/local-echo/http/inspect?mode=future")
+                .header(AUTHORIZATION, "Bearer sk_provider_operation_test")
+                .header("x-api-key", "must-not-reach-plugin")
+                .header("cookie", "must-not-reach-plugin=1")
+                .header("connection", "x-hop-client")
+                .header("x-hop-client", "must-not-reach-plugin")
+                .header("x-safe-client", "kept")
+                .body(Body::from(request_body.clone()))
+                .expect("provider HTTP request"),
+        )
+        .await
+        .expect("provider HTTP response");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(response.headers()["content-type"], "application/x-provider");
+    assert_eq!(response.headers()["content-length"], "19");
+    assert!(!response.headers().contains_key("set-cookie"));
+    assert!(!response.headers().contains_key("location"));
+    let body = to_bytes(response.into_body(), 1024).await.expect("body");
+    assert_eq!(body.as_ref(), b"\0raw-provider-body\xff");
+
+    let captured = execution.captured();
+    let [CapturedOperation::Http { headers, .. }] = captured.as_slice() else {
+        panic!("HTTP operation captured");
+    };
+    assert!(
+        headers
+            .iter()
+            .any(|(name, value)| { name == "x-safe-client" && value.as_ref() == b"kept" })
+    );
+    assert!(!headers.iter().any(|(name, _)| {
+        matches!(
+            name.as_str(),
+            "authorization" | "x-api-key" | "cookie" | "connection" | "x-hop-client"
+        )
+    }));
+    assert_eq!(
+        captured[0],
+        CapturedOperation::Http {
+            provider: "local-echo".to_owned(),
+            endpoint_id: "inspect".to_owned(),
+            method: ProviderHttpMethod::Post,
+            query: Some("mode=future".to_owned()),
+            protocol: "provider-http".to_owned(),
+            route: "/v1/providers/local-echo/http/inspect".to_owned(),
+            headers: headers.clone(),
+            body: request_body,
+        }
+    );
+}
+
+#[tokio::test]
+async fn provider_http_should_reject_head_and_get_bodies_before_execution() {
+    let execution = ProviderExecution::new();
+    let router = crate::openai::api_router(execution.clone()).await;
+    let head = router
+        .clone()
+        .oneshot(
+            Request::builder()
+                .method(Method::HEAD)
+                .uri("/v1/providers/local-echo/http/inspect")
+                .header(AUTHORIZATION, "Bearer sk_provider_operation_test")
+                .body(Body::empty())
+                .expect("HEAD request"),
+        )
+        .await
+        .expect("HEAD response");
+    assert_eq!(head.status(), StatusCode::METHOD_NOT_ALLOWED);
+
+    let get = router
+        .oneshot(
+            Request::get("/v1/providers/local-echo/http/inspect")
+                .header(AUTHORIZATION, "Bearer sk_provider_operation_test")
+                .body(Body::from("not-empty"))
+                .expect("GET request"),
+        )
+        .await
+        .expect("GET response");
+    assert_eq!(get.status(), StatusCode::BAD_REQUEST);
+    assert!(execution.captured().is_empty());
+}
+
+#[tokio::test]
+async fn token_count_should_reject_invalid_json_before_execution() {
+    let execution = ProviderExecution::new();
+    let response = crate::openai::api_router(execution.clone())
+        .await
+        .oneshot(
+            Request::post("/v1/providers/local-echo/models/local-echo/count_tokens")
+                .header(AUTHORIZATION, "Bearer sk_provider_operation_test")
+                .body(Body::from("{not-json"))
+                .expect("token count request"),
+        )
+        .await
+        .expect("token count response");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+    assert!(execution.captured().is_empty());
+}
+
+#[tokio::test]
+async fn provider_http_should_fail_closed_on_non_success_success_envelope() {
+    let execution = ProviderExecution::new();
+    let response = crate::openai::api_router(execution)
+        .await
+        .oneshot(
+            Request::get("/v1/providers/local-echo/http/redirect-fixture")
+                .header(AUTHORIZATION, "Bearer sk_provider_operation_test")
+                .body(Body::empty())
+                .expect("provider HTTP request"),
+        )
+        .await
+        .expect("provider HTTP response");
+
+    assert_eq!(response.status(), StatusCode::BAD_GATEWAY);
+    assert!(!response.headers().contains_key("location"));
+}
+
+#[tokio::test]
+async fn provider_http_should_enforce_fragment_aggregate_and_body_presence_bounds() {
+    let empty = crate::openai::api_router(ProviderExecution::new())
+        .await
+        .oneshot(
+            Request::get("/v1/providers/local-echo/http/empty-body-fixture")
+                .header(AUTHORIZATION, "Bearer sk_provider_operation_test")
+                .body(Body::empty())
+                .expect("empty provider HTTP request"),
+        )
+        .await
+        .expect("empty provider HTTP response");
+    assert_eq!(empty.status(), StatusCode::OK);
+    assert_eq!(empty.headers()["content-length"], "0");
+    assert!(
+        to_bytes(empty.into_body(), 1)
+            .await
+            .expect("empty body")
+            .is_empty()
+    );
+
+    for endpoint in [
+        "oversized-fragment-fixture",
+        "aggregate-overflow-fixture",
+        "missing-body-fixture",
+    ] {
+        let execution = ProviderExecution::new();
+        let response = crate::openai::api_router(execution)
+            .await
+            .oneshot(
+                Request::get(format!("/v1/providers/local-echo/http/{endpoint}"))
+                    .header(AUTHORIZATION, "Bearer sk_provider_operation_test")
+                    .body(Body::empty())
+                    .expect("provider HTTP request"),
+            )
+            .await
+            .expect("provider HTTP response");
+
+        assert_eq!(response.status(), StatusCode::BAD_GATEWAY, "{endpoint}");
+    }
+}
diff --git a/backend/crates/gateway-api/tests/support.rs b/backend/crates/gateway-api/tests/support.rs
index ea4e9af88..0e6adcefa 100644
--- a/backend/crates/gateway-api/tests/support.rs
+++ b/backend/crates/gateway-api/tests/support.rs
@@ -111,6 +111,7 @@ impl SystemOperations for VersionSystem {
     async fn perform_update(
         &self,
         _: Option<String>,
+        _: std::sync::Arc<dyn gateway_admin::ports::system::SystemUpdatePreflight>,
     ) -> Result<SystemOperationAccepted, SystemOperationError> {
         unreachable!("client route must not perform updates")
     }
@@ -119,7 +120,10 @@ impl SystemOperations for VersionSystem {
         unreachable!("client route must not request update status")
     }
 
-    async fn rollback(&self) -> Result<SystemOperationAccepted, SystemOperationError> {
+    async fn rollback(
+        &self,
+        _: std::sync::Arc<dyn gateway_admin::ports::system::SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError> {
         unreachable!("client route must not roll back")
     }
 
diff --git a/backend/crates/gateway-core/src/account/scope.rs b/backend/crates/gateway-core/src/account/scope.rs
index 941b04562..effdafbb5 100644
--- a/backend/crates/gateway-core/src/account/scope.rs
+++ b/backend/crates/gateway-core/src/account/scope.rs
@@ -251,6 +251,9 @@ pub struct FrozenAccountScope {
     request_profiles: BTreeMap<ProviderKind, super::OpaqueProviderData>,
     directory: Arc<RuntimeAccountDirectory>,
     client_scope: ClientRoutingScope,
+    provider_kinds: Arc<BTreeSet<ProviderKind>>,
+    allowed_account_ids: Option<Arc<BTreeSet<ProviderAccountId>>>,
+    excluded_account_ids: Arc<BTreeSet<ProviderAccountId>>,
 }
 
 impl FrozenAccountScope {
@@ -282,23 +285,80 @@ impl FrozenAccountScope {
     }
 
     #[must_use]
-    pub const fn new(
-        directory: Arc<RuntimeAccountDirectory>,
-        client_scope: ClientRoutingScope,
-    ) -> Self {
+    pub fn new(directory: Arc<RuntimeAccountDirectory>, client_scope: ClientRoutingScope) -> Self {
+        let provider_kinds = match &client_scope {
+            ClientRoutingScope::AllAccounts => Arc::new(directory.providers_with_accounts.clone()),
+            ClientRoutingScope::Restricted { provider_kinds, .. } => Arc::clone(provider_kinds),
+        };
         Self {
             disable_fast: false,
             request_profiles: BTreeMap::new(),
             directory,
             client_scope,
+            provider_kinds,
+            allowed_account_ids: None,
+            excluded_account_ids: Arc::default(),
         }
     }
 
+    /// 在已经冻结的 Key 范围内施加一次请求局部的 Provider/账号交集。
+    ///
+    /// 空集合表示该维度不额外收窄；非空集合即使没有有效交集也保持为空，
+    /// 不能回退为父请求的完整范围。
+    #[must_use]
+    pub fn restricted_to(
+        &self,
+        providers: &BTreeSet<ProviderKind>,
+        accounts: &BTreeSet<ProviderAccountId>,
+    ) -> Self {
+        let mut restricted = self.clone();
+        let mut provider_kinds = self.provider_kinds.as_ref().clone();
+        if !providers.is_empty() {
+            provider_kinds.retain(|provider| providers.contains(provider));
+        }
+        if !accounts.is_empty() {
+            let allowed_account_ids = accounts
+                .iter()
+                .filter(|account| self.allows(account))
+                .cloned()
+                .collect::<BTreeSet<_>>();
+            provider_kinds.retain(|provider| {
+                allowed_account_ids.iter().any(|account| {
+                    self.directory
+                        .account(account)
+                        .is_some_and(|entry| entry.provider_kind() == provider)
+                })
+            });
+            restricted.allowed_account_ids = Some(Arc::new(allowed_account_ids));
+        }
+        restricted.provider_kinds = Arc::new(provider_kinds);
+        restricted
+    }
+
+    /// 排除父 attempt 当前已经持有的账号，避免嵌套调用形成账号 lease 自等待。
+    #[must_use]
+    pub fn excluding_account(&self, account: ProviderAccountId) -> Self {
+        let mut restricted = self.clone();
+        let mut excluded = self.excluded_account_ids.as_ref().clone();
+        excluded.insert(account);
+        restricted.excluded_account_ids = Arc::new(excluded);
+        restricted
+    }
+
     #[must_use]
     pub fn allows(&self, account_id: &ProviderAccountId) -> bool {
         let Some(account) = self.directory.account(account_id) else {
             return false;
         };
+        if self.excluded_account_ids.contains(account_id)
+            || !self.provider_kinds.contains(account.provider_kind())
+            || self
+                .allowed_account_ids
+                .as_ref()
+                .is_some_and(|accounts| !accounts.contains(account_id))
+        {
+            return false;
+        }
         match &self.client_scope {
             ClientRoutingScope::AllAccounts => true,
             ClientRoutingScope::Restricted {
@@ -322,17 +382,23 @@ impl FrozenAccountScope {
     /// 目录按整个授权账号池过滤，不能只看用于获取元数据的账号政策。
     #[must_use]
     pub fn allows_provider_model(&self, provider: &ProviderKind, upstream_model: &str) -> bool {
-        self.directory.accounts.iter().any(|(id, account)| {
-            account.provider_kind() == provider && self.allows_model(id, upstream_model)
-        })
+        self.provider_kinds.contains(provider)
+            && self.directory.accounts.iter().any(|(id, account)| {
+                account.provider_kind() == provider && self.allows_model(id, upstream_model)
+            })
     }
 
     #[must_use]
     pub fn provider_kinds(&self) -> &BTreeSet<ProviderKind> {
-        match &self.client_scope {
-            ClientRoutingScope::AllAccounts => self.directory.providers_with_accounts(),
-            ClientRoutingScope::Restricted { provider_kinds, .. } => provider_kinds,
-        }
+        &self.provider_kinds
+    }
+
+    /// 返回冻结目录中账号所属 Provider；调用方仍须另行检查 [`Self::allows`]。
+    #[must_use]
+    pub fn account_provider(&self, account_id: &ProviderAccountId) -> Option<&ProviderKind> {
+        self.directory
+            .account(account_id)
+            .map(RuntimeAccount::provider_kind)
     }
 
     #[must_use]
diff --git a/backend/crates/gateway-core/src/account/selection.rs b/backend/crates/gateway-core/src/account/selection.rs
index 2169a4d18..80fa79ec5 100644
--- a/backend/crates/gateway-core/src/account/selection.rs
+++ b/backend/crates/gateway-core/src/account/selection.rs
@@ -454,6 +454,7 @@ pub enum AccountSchedulingBlocker {
 pub enum PreferredAccountSelection {
     NotRequested,
     Hit,
+    OverriddenByPolicy,
     Missing,
     Blocked(AccountSchedulingBlocker),
 }
@@ -482,6 +483,52 @@ impl<'a> AccountSelection<'a> {
 pub struct AccountSelector;
 
 impl AccountSelector {
+    /// 返回调度策略可见的全部合格候选；权重层授权由调用策略的宿主适配器裁剪。
+    #[must_use]
+    pub(crate) fn policy_candidates<'a>(
+        &self,
+        candidates: &'a [AccountCandidate],
+        context: &AccountSelectionContext,
+    ) -> Vec<&'a AccountCandidate> {
+        candidates
+            .iter()
+            .filter(|candidate| self.scheduling_blocker(candidate, context).is_none())
+            .collect()
+    }
+
+    /// 对插件返回的 ID 再执行同一资格判断，并保留原有亲和遥测结果。
+    #[must_use]
+    pub(crate) fn select_policy_candidate<'a>(
+        &self,
+        candidates: &'a [AccountCandidate],
+        context: &AccountSelectionContext,
+        account_id: &ProviderAccountId,
+    ) -> Option<AccountSelection<'a>> {
+        let candidate = candidates
+            .iter()
+            .find(|candidate| candidate.account.id() == account_id)?;
+        if self.scheduling_blocker(candidate, context).is_some() {
+            return None;
+        }
+        let highest_weight = candidates
+            .iter()
+            .filter(|candidate| self.scheduling_blocker(candidate, context).is_none())
+            .map(|candidate| candidate.account.weight())
+            .max()?;
+        let (preferred, _) = self.preferred_decision(candidates, context, highest_weight);
+        let preferred = if preferred == PreferredAccountSelection::Hit
+            && context.preferred_account.as_ref() != Some(account_id)
+        {
+            PreferredAccountSelection::OverriddenByPolicy
+        } else {
+            preferred
+        };
+        Some(AccountSelection {
+            candidate,
+            preferred,
+        })
+    }
+
     /// 汇总与本次调度约束一致的并发容量，供请求级观测使用。
     #[must_use]
     pub fn capacity_snapshot(
@@ -538,30 +585,14 @@ impl AccountSelector {
             .iter()
             .map(|candidate| candidate.account.weight())
             .max()?;
-        let preferred = if let Some(preferred) = context.preferred_account.as_ref() {
-            match candidates
-                .iter()
-                .find(|candidate| candidate.account.id() == preferred)
-            {
-                Some(candidate) => match self.scheduling_blocker(candidate, context) {
-                    Some(blocker) => PreferredAccountSelection::Blocked(blocker),
-                    None if !context.preferred_account_overrides_weight
-                        && candidate.account.weight() < highest_weight =>
-                    {
-                        PreferredAccountSelection::Blocked(AccountSchedulingBlocker::LowerWeight)
-                    }
-                    None => {
-                        return Some(AccountSelection {
-                            candidate,
-                            preferred: PreferredAccountSelection::Hit,
-                        });
-                    }
-                },
-                None => PreferredAccountSelection::Missing,
-            }
-        } else {
-            PreferredAccountSelection::NotRequested
-        };
+        let (preferred, preferred_candidate) =
+            self.preferred_decision(candidates, context, highest_weight);
+        if let Some(candidate) = preferred_candidate {
+            return Some(AccountSelection {
+                candidate,
+                preferred: PreferredAccountSelection::Hit,
+            });
+        }
         eligible.retain(|candidate| candidate.account.weight() == highest_weight);
 
         let candidate = match context.policy.strategy() {
@@ -615,6 +646,35 @@ impl AccountSelector {
         })
     }
 
+    fn preferred_decision<'a>(
+        &self,
+        candidates: &'a [AccountCandidate],
+        context: &AccountSelectionContext,
+        highest_weight: super::AccountWeight,
+    ) -> (PreferredAccountSelection, Option<&'a AccountCandidate>) {
+        let Some(preferred) = context.preferred_account.as_ref() else {
+            return (PreferredAccountSelection::NotRequested, None);
+        };
+        let Some(candidate) = candidates
+            .iter()
+            .find(|candidate| candidate.account.id() == preferred)
+        else {
+            return (PreferredAccountSelection::Missing, None);
+        };
+        match self.scheduling_blocker(candidate, context) {
+            Some(blocker) => (PreferredAccountSelection::Blocked(blocker), None),
+            None if !context.preferred_account_overrides_weight
+                && candidate.account.weight() < highest_weight =>
+            {
+                (
+                    PreferredAccountSelection::Blocked(AccountSchedulingBlocker::LowerWeight),
+                    None,
+                )
+            }
+            None => (PreferredAccountSelection::Hit, Some(candidate)),
+        }
+    }
+
     /// 只有本地并发/调度间隔可等待；账号权限、失效、额度与上游冷却仍立即排除。
     #[must_use]
     pub fn wait_candidates(
diff --git a/backend/crates/gateway-core/src/engine/authentication.rs b/backend/crates/gateway-core/src/engine/authentication.rs
new file mode 100644
index 000000000..750610a7a
--- /dev/null
+++ b/backend/crates/gateway-core/src/engine/authentication.rs
@@ -0,0 +1,154 @@
+//! 数据面入口认证计划；插件只产生 principal，Core 解析既有 Client Key 策略。
+
+use std::{
+    collections::BTreeMap,
+    fmt,
+    sync::{Arc, RwLock, Weak},
+};
+
+use futures::future::BoxFuture;
+
+use crate::{
+    policy::{ClientApiKeyId, PlaintextClientApiKey},
+    runtime::extensions::{ExtensionSetId, ExtensionSetReference},
+};
+
+pub const MAXIMUM_AUTHORIZATION_BYTES: usize = 8 * 1024;
+
+/// API 从数据面 Authorization 头构造的有界认证信封。
+#[derive(Clone, PartialEq, Eq)]
+pub struct ClientAuthenticationRequest {
+    authorization: Arc<str>,
+    native_bearer: Option<PlaintextClientApiKey>,
+}
+
+impl ClientAuthenticationRequest {
+    /// 创建入口认证信封；HTTP 语法与缺失头仍由 API owner 负责。
+    pub fn new(authorization: impl Into<String>) -> Result<Self, ClientAuthenticationRequestError> {
+        let authorization = authorization.into();
+        if authorization.is_empty()
+            || authorization.len() > MAXIMUM_AUTHORIZATION_BYTES
+            || !authorization.is_ascii()
+            || authorization.chars().any(char::is_control)
+        {
+            return Err(ClientAuthenticationRequestError);
+        }
+        let native_bearer = authorization
+            .strip_prefix("Bearer ")
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .and_then(|value| PlaintextClientApiKey::new(value.to_owned()).ok());
+        Ok(Self {
+            authorization: authorization.into(),
+            native_bearer,
+        })
+    }
+
+    /// 原生调用方显式构造 Bearer 信封；仍经过同一长度与字符校验。
+    pub fn bearer(plaintext: &str) -> Result<Self, ClientAuthenticationRequestError> {
+        Self::new(format!("Bearer {plaintext}"))
+    }
+
+    #[must_use]
+    pub fn authorization(&self) -> &str {
+        &self.authorization
+    }
+
+    #[must_use]
+    pub(crate) const fn native_bearer(&self) -> Option<&PlaintextClientApiKey> {
+        self.native_bearer.as_ref()
+    }
+}
+
+impl fmt::Debug for ClientAuthenticationRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("ClientAuthenticationRequest")
+            .field("authorization", &"[REDACTED]")
+            .finish()
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+#[error("client authorization is invalid")]
+pub struct ClientAuthenticationRequestError;
+
+/// 插件认证结果不携带宿主执行身份。
+#[derive(Clone, PartialEq, Eq)]
+pub enum FrontendAuthenticationDecision {
+    Authenticated { principal: String },
+    NotMatched,
+    Rejected,
+}
+
+impl fmt::Debug for FrontendAuthenticationDecision {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Authenticated { .. } => formatter
+                .debug_struct("Authenticated")
+                .field("principal", &"[REDACTED]")
+                .finish(),
+            Self::NotMatched => formatter.write_str("NotMatched"),
+            Self::Rejected => formatter.write_str("Rejected"),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+#[error("frontend authentication provider is unavailable")]
+pub struct FrontendAuthenticationError;
+
+/// 一个发布代次中唯一的入口认证计划。
+pub trait FrontendAuthenticationPlan: Send + Sync {
+    fn authenticate<'a>(
+        &'a self,
+        request: &'a ClientAuthenticationRequest,
+    ) -> BoxFuture<'a, Result<FrontendAuthenticationDecision, FrontendAuthenticationError>>;
+
+    /// 映射由管理员配置冻结，插件结果不能选择 Key ID。
+    fn client_key_id(&self, principal: &str) -> Option<ClientApiKeyId>;
+
+    /// 独占计划不允许 `NotMatched` 回退原生 Bearer。
+    fn exclusive(&self) -> bool;
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+#[error("frontend authentication generation is already registered")]
+pub struct FrontendAuthenticationRegistrationError;
+
+/// 按已发布集合解析的非拥有索引；旧代次由快照和在途调用保活。
+#[derive(Clone, Default)]
+pub struct FrontendAuthenticationExtensionIndex {
+    sets: Arc<RwLock<BTreeMap<ExtensionSetId, Weak<dyn FrontendAuthenticationPlan>>>>,
+}
+
+impl FrontendAuthenticationExtensionIndex {
+    pub fn register(
+        &self,
+        id: ExtensionSetId,
+        plan: Arc<dyn FrontendAuthenticationPlan>,
+    ) -> Result<Arc<dyn FrontendAuthenticationPlan>, FrontendAuthenticationRegistrationError> {
+        let mut sets = self
+            .sets
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        sets.retain(|_, plan| plan.strong_count() > 0);
+        if sets.contains_key(&id) {
+            return Err(FrontendAuthenticationRegistrationError);
+        }
+        sets.insert(id, Arc::downgrade(&plan));
+        Ok(plan)
+    }
+
+    #[must_use]
+    pub fn resolve(
+        &self,
+        generation: &ExtensionSetReference,
+    ) -> Option<Arc<dyn FrontendAuthenticationPlan>> {
+        self.sets
+            .read()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .get(generation.id())
+            .and_then(Weak::upgrade)
+    }
+}
diff --git a/backend/crates/gateway-core/src/engine/coordinator.rs b/backend/crates/gateway-core/src/engine/coordinator.rs
index a7c85ae4c..36b9c72eb 100644
--- a/backend/crates/gateway-core/src/engine/coordinator.rs
+++ b/backend/crates/gateway-core/src/engine/coordinator.rs
@@ -5,12 +5,14 @@ use crate::diagnostics::TraceContext;
 use serde_json::json;
 
 use std::collections::{BTreeMap, BTreeSet};
-use std::future::Future;
 use std::num::NonZeroU32;
 use std::sync::Arc;
 use std::time::{Duration, Instant, SystemTime};
 
-use super::observation::ResponseObservation;
+use super::nested::ExecutionEffects;
+use super::observation::{
+    RequestObservationDispatch, ResponseObservation, WebSocketResponseAttempt,
+};
 use crate::engine::continuation::{
     ContinuationBinding, NativeContinuationPin, NativeContinuationScope, PreviousResponseId,
 };
@@ -49,6 +51,83 @@ enum AccountSelection {
     Diagnostic(crate::account::ProviderAccountId),
 }
 
+pub(super) struct CoordinationExtensions {
+    continuation: Option<ContinuationBinding>,
+    observation: Option<RequestObservationDispatch>,
+    request_policy: Option<super::policy::RequestPolicyContext>,
+    execution_effects: Option<Arc<ExecutionEffects>>,
+    execution_effects_baseline: usize,
+    middleware: Option<super::middleware::FrozenMiddlewarePlan>,
+    account_group_ids: Arc<[crate::account::scope::AccountGroupId]>,
+    endpoint: String,
+    client_transport: super::execution::ClientTransport,
+    extension_scope: super::extensions::ExtensionCallScope,
+}
+
+impl CoordinationExtensions {
+    pub(super) fn new(
+        continuation: Option<ContinuationBinding>,
+        observation: Option<RequestObservationDispatch>,
+    ) -> Self {
+        Self {
+            continuation,
+            observation,
+            request_policy: None,
+            execution_effects: None,
+            execution_effects_baseline: 0,
+            middleware: None,
+            account_group_ids: Arc::from([]),
+            endpoint: String::new(),
+            client_transport: super::execution::ClientTransport::InternalProbe,
+            extension_scope: super::extensions::ExtensionCallScope::default(),
+        }
+    }
+
+    #[must_use]
+    pub(super) fn with_extension_scope(
+        mut self,
+        extension_scope: super::extensions::ExtensionCallScope,
+    ) -> Self {
+        self.extension_scope = extension_scope;
+        self
+    }
+
+    #[must_use]
+    pub(super) fn with_request_policy(
+        mut self,
+        request_policy: Option<super::policy::RequestPolicyContext>,
+    ) -> Self {
+        self.request_policy = request_policy;
+        self
+    }
+
+    #[must_use]
+    pub(super) fn with_execution_effects(
+        mut self,
+        execution_effects: Option<Arc<ExecutionEffects>>,
+        execution_effects_baseline: usize,
+    ) -> Self {
+        self.execution_effects = execution_effects;
+        self.execution_effects_baseline = execution_effects_baseline;
+        self
+    }
+
+    #[must_use]
+    pub(super) fn with_middleware(
+        mut self,
+        middleware: Option<super::middleware::FrozenMiddlewarePlan>,
+        account_group_ids: Arc<[crate::account::scope::AccountGroupId]>,
+        endpoint: String,
+        client_transport: super::execution::ClientTransport,
+    ) -> Self {
+        self.middleware = middleware;
+        self.account_group_ids = account_group_ids;
+        self.endpoint = endpoint;
+        self.client_transport = client_transport;
+        self
+    }
+}
+
 impl AccountSelection {
     fn required_account(&self) -> Option<&crate::account::ProviderAccountId> {
         match self {
@@ -92,7 +171,27 @@ where
             operation,
             plan,
             AccountSelection::Scheduled(required_account),
-            continuation,
+            CoordinationExtensions::new(continuation, None),
+            cancellation,
+        )
+        .await
+    }
+
+    pub(super) async fn start_observed(
+        &self,
+        request: NewModelRequest,
+        operation: Operation,
+        plan: RoutingPlan,
+        required_account: Option<crate::account::ProviderAccountId>,
+        extensions: CoordinationExtensions,
+        cancellation: CancellationToken,
+    ) -> Result<ResponseExecutionSession<S>, EngineError> {
+        self.start_with_account_selection(
+            request,
+            operation,
+            plan,
+            AccountSelection::Scheduled(required_account),
+            extensions,
             cancellation,
         )
         .await
@@ -115,7 +214,7 @@ where
             operation,
             plan,
             AccountSelection::Diagnostic(required_account),
-            continuation,
+            CoordinationExtensions::new(continuation, None),
             cancellation,
         )
         .await
@@ -127,9 +226,21 @@ where
         operation: Operation,
         plan: RoutingPlan,
         account_selection: AccountSelection,
-        continuation: Option<ContinuationBinding>,
+        extensions: CoordinationExtensions,
         cancellation: CancellationToken,
     ) -> Result<ResponseExecutionSession<S>, EngineError> {
+        let CoordinationExtensions {
+            continuation,
+            observation: request_observation,
+            request_policy,
+            execution_effects,
+            execution_effects_baseline,
+            middleware,
+            account_group_ids,
+            endpoint,
+            client_transport,
+            extension_scope,
+        } = extensions;
         let request_id = request.id.clone();
         let client_api_key_ref = request.client_api_key_ref.clone();
         let timing_started_at = Instant::now();
@@ -169,6 +280,7 @@ where
             client_api_key_ref,
             concurrency_wait_budget: ConcurrencyWaitBudget::default(),
             observation: ResponseObservation::new(timing_started_at),
+            request_observation,
             budget_prior_attempts_usd: Decimal::ZERO,
             budget_attempt_already_counted: false,
             trace,
@@ -183,12 +295,21 @@ where
             request_persisted: false,
             operation,
             plan,
+            request_policy,
+            execution_effects,
+            execution_effects_baseline,
+            middleware,
+            account_group_ids,
+            endpoint,
+            client_transport,
+            extension_scope,
             account_selection,
             continuation,
             continuation_attempt,
             account_state_owner,
             cancellation,
             attempts: 0,
+            websocket_observation_sequence: 0,
             routing_attempts: 0,
             candidate_index,
             excluded_accounts: BTreeSet::new(),
@@ -275,6 +396,7 @@ pub struct ResponseExecutionSession<S: ?Sized> {
     client_api_key_ref: crate::policy::ClientApiKeyId,
     concurrency_wait_budget: ConcurrencyWaitBudget,
     observation: ResponseObservation,
+    request_observation: Option<RequestObservationDispatch>,
     budget_prior_attempts_usd: Decimal,
     budget_attempt_already_counted: bool,
     trace: TraceContext,
@@ -285,6 +407,14 @@ pub struct ResponseExecutionSession<S: ?Sized> {
     request_persisted: bool,
     operation: Operation,
     plan: RoutingPlan,
+    request_policy: Option<super::policy::RequestPolicyContext>,
+    execution_effects: Option<Arc<ExecutionEffects>>,
+    execution_effects_baseline: usize,
+    middleware: Option<super::middleware::FrozenMiddlewarePlan>,
+    account_group_ids: Arc<[crate::account::scope::AccountGroupId]>,
+    endpoint: String,
+    client_transport: super::execution::ClientTransport,
+    extension_scope: super::extensions::ExtensionCallScope,
     account_selection: AccountSelection,
     continuation: Option<ContinuationBinding>,
     continuation_attempt: ContinuationAttempt,
@@ -292,6 +422,8 @@ pub struct ResponseExecutionSession<S: ?Sized> {
     cancellation: CancellationToken,
     /// 所有实际上游 attempt 数；包含同账号传输重试，作为持久化序号。
     attempts: u32,
+    /// WebSocket 观察序列在同一逻辑请求内按实际上游 wire 单调递增。
+    websocket_observation_sequence: u64,
     /// 路由预算只统计正常选号/账号恢复，不被 Provider-owned 传输预算消耗。
     routing_attempts: u32,
     candidate_index: usize,
@@ -371,18 +503,14 @@ where
         }
         loop {
             match self.pull().await? {
-                PullOutcome::Event(event) => {
-                    if self.downstream_committed_at.is_some() {
-                        return Ok(Some(CoordinatedEvent::single(
-                            event,
-                            CommitRequirement::AlreadyCommitted,
-                        )));
-                    }
-                    self.delivery_pending = true;
-                    return Ok(Some(CoordinatedEvent::single(
-                        event,
-                        CommitRequirement::CommitBeforeDelivery,
-                    )));
+                PullOutcome::Events(events) => {
+                    let requirement = if self.downstream_committed_at.is_some() {
+                        CommitRequirement::AlreadyCommitted
+                    } else {
+                        self.delivery_pending = true;
+                        CommitRequirement::CommitBeforeDelivery
+                    };
+                    return CoordinatedEvent::try_batch(events, requirement).map(Some);
                 }
                 PullOutcome::AttemptDiscarded => {}
                 PullOutcome::TerminalFailure {
@@ -427,7 +555,7 @@ where
         let mut events = Vec::new();
         loop {
             match self.pull().await? {
-                PullOutcome::Event(event) => events.push(event),
+                PullOutcome::Events(next) => events.extend(next),
                 PullOutcome::AttemptDiscarded => events.clear(),
                 PullOutcome::TerminalFailure {
                     error, send_state, ..
@@ -485,6 +613,20 @@ where
         Ok(())
     }
 
+    /// 仅当 HTTP 流插件明确丢弃了整个尚未提交的非终态批次时释放交付屏障。
+    /// 原始 Provider facts 已经观察，不回滚计量，也不把丢弃误记为客户端 commit。
+    pub fn discard_pending_delivery(&mut self) -> Result<(), EngineError> {
+        if !self.delivery_pending
+            || self.downstream_committed_at.is_some()
+            || self.pending_terminal_failure.is_some()
+            || self.is_finalized()
+        {
+            return Err(EngineError::InvalidDeliveryState);
+        }
+        self.delivery_pending = false;
+        Ok(())
+    }
+
     /// 在 HTTP adapter 已确定首字节前错误响应后补写最终状态。
     ///
     /// # Errors
@@ -684,10 +826,34 @@ where
                     if event.wire_event().is_some() && !event.has_canonical_facts() {
                         self.observe_wire_event().await;
                     }
+                    if self.request_observation.is_some() && event.wire_event().is_some() {
+                        let websocket_attempt = self
+                            .current
+                            .as_ref()
+                            .and_then(websocket_observation_attempt);
+                        self.observe_websocket_response(&event, websocket_attempt);
+                    }
                     if !event.has_client_event() {
                         continue;
                     }
-                    return Ok(PullOutcome::Event(event));
+                    let terminal = event
+                        .canonical_facts()
+                        .iter()
+                        .any(|fact| matches!(fact, GatewayEvent::Completed(_)));
+                    let translated = self
+                        .current
+                        .as_mut()
+                        .ok_or(EngineError::NoActiveAttempt)?
+                        .stream
+                        .translate_native_response(event, terminal);
+                    match translated {
+                        Ok(events) if events.is_empty() => continue,
+                        Ok(events) => return Ok(PullOutcome::Events(events)),
+                        Err(error) => {
+                            self.finish_provider_error(&error).await?;
+                            return Err(provider_engine_error(error));
+                        }
+                    }
                 }
                 PollBoundary::Item(Some(Err(error))) => {
                     match self.handle_stream_error(error).await? {
@@ -797,17 +963,21 @@ where
             .ok_or_else(|| EngineError::ProviderNotRegistered {
                 provider: candidate.provider().as_str().to_owned(),
             })?;
-        if !self.request_profiles.contains_key(candidate.provider())
-            && let Some(configuration) = self
+        if !self.request_profiles.contains_key(candidate.provider()) {
+            let profile = match self
                 .plan
                 .account_scope()
                 .request_profile(candidate.provider())
-        {
-            match provider.resolve_request_profile(configuration) {
-                Ok(profile) => {
+            {
+                Some(configuration) => provider.resolve_request_profile(configuration).map(Some),
+                None => provider.default_request_profile(),
+            };
+            match profile {
+                Ok(Some(profile)) => {
                     self.request_profiles
                         .insert(candidate.provider().clone(), profile);
                 }
+                Ok(None) => {}
                 Err(error) => {
                     self.finish_provider_error(&error).await?;
                     return Err(provider_engine_error(error));
@@ -822,6 +992,15 @@ where
                 .with_request_location(self.plan.request_location().cloned())
                 .with_concurrency_wait_budget(self.concurrency_wait_budget.clone())
                 .with_timing_started_at(self.observation.timing_started_at)
+                .with_request_policy(self.request_policy.clone())
+                .with_execution_effects(self.execution_effects.as_ref().map(Arc::clone))
+                .with_middleware(
+                    self.middleware.clone(),
+                    Arc::clone(&self.account_group_ids),
+                    self.endpoint.clone(),
+                    self.client_transport,
+                )
+                .with_extension_scope(self.extension_scope.clone())
                 .with_trace(self.trace.clone()),
             next_attempt,
             self.deadline,
@@ -850,15 +1029,15 @@ where
             }),
         );
         let provider_request = ProviderRequest::new(self.operation.clone(), candidate.clone());
-        let stream = match poll_provider(
+        let provider_boundary = poll_provider(
             provider,
             provider_request,
             context,
             self.cancellation.clone(),
             self.deadline,
         )
-        .await
-        {
+        .await;
+        let stream = match provider_boundary {
             ProviderBoundary::Cancelled => {
                 self.finish_interruption(&EngineError::Cancelled).await?;
                 return Err(EngineError::Cancelled);
@@ -886,6 +1065,7 @@ where
                             | ProviderErrorKind::ConcurrencyQueueFull
                             | ProviderErrorKind::ConcurrencyQueueTimeout
                     ) && error.send_state() == UpstreamSendState::NotSent
+                        && self.current_send_state() == UpstreamSendState::NotSent
                         && matches!(
                             self.continuation_attempt,
                             ContinuationAttempt::None | ContinuationAttempt::ReplayAny
@@ -1177,15 +1357,25 @@ where
         record_trace_error(&self.trace.attempt(self.attempts), &error);
         let mut atomic_client_events = error.take_atomic_client_events();
         let current = self.current.take().ok_or(EngineError::NoActiveAttempt)?;
+        if self.request_observation.is_some() {
+            let websocket_attempt = websocket_observation_attempt(&current);
+            for event in atomic_client_events
+                .iter()
+                .filter(|event| event.wire_event().is_some())
+            {
+                self.observe_websocket_response(event, websocket_attempt.clone());
+            }
+        }
         self.record_provider_failure(current.metadata.provider().clone(), error.kind());
-        // attempt_send_state 是本 attempt 自身的发送事实，驱动重试门；
-        // 持久化与终态用请求级水位，二者不可混用（水位会把早先 attempt 的
-        // sent 传染给本 attempt，从而错误放行/拦截重试）。
+        // attempt_send_state 是本 attempt 自身的发送事实；共享 effect 单独作为
+        // 一票否决的重试门。持久化与终态用请求级水位，不能把早先 Provider attempt
+        // 的 sent 传染给当前 attempt，但任何已观测外部副作用都必须阻止重放。
         let attempt_send_state = if current.send_observed {
             UpstreamSendState::Sent
         } else {
             error.send_state()
         };
+        let execution_effect_observed = self.execution_effect_observed();
         let send_state = self.raise_send_watermark(attempt_send_state);
         if self.request_persisted {
             best_effort_store_write(
@@ -1198,13 +1388,15 @@ where
             .await;
         }
         let provider_proved_replay_safe = provider_proved_replay_safe(&error);
-        let continuation_retry = self.prepare_continuation_retry(
-            &current,
-            &error,
-            attempt_send_state,
-            provider_proved_replay_safe,
-        );
-        let account_rotation_retry = self.account_selection.required_account().is_none()
+        let continuation_retry = !execution_effect_observed
+            && self.prepare_continuation_retry(
+                &current,
+                &error,
+                attempt_send_state,
+                provider_proved_replay_safe,
+            );
+        let account_rotation_retry = !execution_effect_observed
+            && self.account_selection.required_account().is_none()
             && self.continuation_attempt == ContinuationAttempt::None
             && self.downstream_committed_at.is_none()
             && !self.delivery_pending
@@ -1218,14 +1410,16 @@ where
             Some(crate::error::PreDeliveryRetry::SameAccountTransportRetry {
                 retry_index,
                 delay,
-            }) if self.downstream_committed_at.is_none()
+            }) if !execution_effect_observed
+                && self.downstream_committed_at.is_none()
                 && !self.delivery_pending
                 && attempt_send_state != UpstreamSendState::Ambiguous =>
             {
                 Some((AttemptTransport::Retry(retry_index), delay))
             }
             Some(crate::error::PreDeliveryRetry::SameAccountTransportFallback)
-                if self.downstream_committed_at.is_none()
+                if !execution_effect_observed
+                    && self.downstream_committed_at.is_none()
                     && !self.delivery_pending
                     && attempt_send_state != UpstreamSendState::Ambiguous =>
             {
@@ -1233,7 +1427,8 @@ where
             }
             _ => None,
         };
-        let ordinary_retry = self.account_selection.required_account().is_none()
+        let ordinary_retry = !execution_effect_observed
+            && self.account_selection.required_account().is_none()
             && self.continuation_attempt == ContinuationAttempt::None
             && self.downstream_committed_at.is_none()
             && !self.delivery_pending
@@ -1261,7 +1456,8 @@ where
             }
             _ => None,
         };
-        let same_account_retry = error.retries_same_account()
+        let same_account_retry = !execution_effect_observed
+            && error.retries_same_account()
             && provider_proved_replay_safe
             && self.downstream_committed_at.is_none()
             && !self.delivery_pending
@@ -1281,6 +1477,7 @@ where
             "sameAccountRetry": same_account_retry, "accountRotationRetry": account_rotation_retry,
             "ordinaryRetry": ordinary_retry, "transportRecovery": transport_recovery.is_some(),
             "transientRetry": transient_retry.is_some(),
+            "executionEffectObserved": execution_effect_observed,
             "delayMs": transient_retry.or(transport_recovery.map(|(_, delay)| delay)).map(duration_ms),
             "downstreamCommitted": self.downstream_committed_at.is_some(),
             "sendState": format!("{attempt_send_state:?}"),
@@ -1381,6 +1578,24 @@ where
         }
     }
 
+    fn observe_websocket_response(
+        &mut self,
+        event: &ProviderEvent,
+        attempt: Option<WebSocketResponseAttempt>,
+    ) {
+        let Some(observer) = self.request_observation.clone() else {
+            return;
+        };
+        let Some(wire) = event.wire_event().cloned() else {
+            return;
+        };
+        let Some(attempt) = attempt else {
+            return;
+        };
+        self.websocket_observation_sequence = self.websocket_observation_sequence.saturating_add(1);
+        observer.websocket_response(attempt, self.websocket_observation_sequence, wire);
+    }
+
     fn prepare_continuation_retry(
         &mut self,
         current: &CurrentAttempt,
@@ -1446,6 +1661,7 @@ where
     fn prepare_unavailable_native_continuation_replay(&mut self, error: &ProviderError) -> bool {
         if self.account_selection.required_account().is_some()
             || self.continuation_attempt != ContinuationAttempt::Native
+            || self.current_send_state() != UpstreamSendState::NotSent
             || !matches!(
                 error.kind(),
                 ProviderErrorKind::NoEligibleAccount
@@ -1717,6 +1933,23 @@ where
 
     async fn persist_finalization(&mut self, finalization: ModelRequestFinalization) {
         self.finalized_at = Some(finalization.completed_at);
+        let observed_provider = self
+            .current
+            .as_ref()
+            .map(|current| current.metadata.provider().clone())
+            .or_else(|| {
+                self.provider_attempt_outcomes
+                    .last()
+                    .map(|outcome| outcome.provider_kind().clone())
+            });
+        let observer = self.request_observation.clone();
+        let observation = observer.as_ref().map(|observer| {
+            observer.finalization(
+                &finalization,
+                observed_provider,
+                self.current.as_ref().map(|current| &current.metadata),
+            )
+        });
         let mut persisted = self.request_persisted;
         // 首次合并写失败后不能以零 attempt 补行；建流前也只有确定未发送的请求可按零次收敛。
         let request = if !persisted
@@ -1748,6 +1981,9 @@ where
                 )
                 .await;
             }
+            if let (Some(observer), Some(observation)) = (observer, observation) {
+                observer.dispatch(observation);
+            }
             persisted
         })));
         self.resume_finalization().await;
@@ -1818,13 +2054,25 @@ where
         } else {
             UpstreamSendState::NotSent
         };
+        let observed = if self.execution_effect_observed() {
+            escalate_send_state(observed, UpstreamSendState::Ambiguous)
+        } else {
+            observed
+        };
         escalate_send_state(self.send_state_watermark, observed)
     }
 
+    fn execution_effect_observed(&self) -> bool {
+        self.execution_effects
+            .as_ref()
+            .is_some_and(|effects| effects.epoch() != self.execution_effects_baseline)
+    }
+
     /// 抬升并返回请求级发送水位；attempt 间切换（`current` 被取走）后，
     /// 后续终态沿用已达到的最高档，不会把已落库的 `sent` 写回 `not_sent`。
     fn raise_send_watermark(&mut self, observed: UpstreamSendState) -> UpstreamSendState {
-        self.send_state_watermark = escalate_send_state(self.send_state_watermark, observed);
+        let observed = escalate_send_state(self.current_send_state(), observed);
+        self.send_state_watermark = observed;
         self.send_state_watermark
     }
 
@@ -1872,7 +2120,7 @@ async fn best_effort_store_write<T>(
 }
 
 enum PullOutcome {
-    Event(ProviderEvent),
+    Events(Vec<ProviderEvent>),
     AttemptDiscarded,
     TerminalFailure {
         events: Vec<ProviderEvent>,
@@ -1985,6 +2233,16 @@ async fn poll_provider(
     }
 }
 
+fn websocket_observation_attempt(current: &CurrentAttempt) -> Option<WebSocketResponseAttempt> {
+    (current.metadata.transport().as_str() == "websocket").then(|| {
+        WebSocketResponseAttempt::new(
+            current.metadata.provider().clone(),
+            current.metadata.provider_account_id().clone(),
+            current.index,
+        )
+    })
+}
+
 fn initial_continuation_attempt(
     operation: &Operation,
     plan: &RoutingPlan,
diff --git a/backend/crates/gateway-core/src/engine/execution.rs b/backend/crates/gateway-core/src/engine/execution.rs
index 2b1c90b91..f7b1a13c2 100644
--- a/backend/crates/gateway-core/src/engine/execution.rs
+++ b/backend/crates/gateway-core/src/engine/execution.rs
@@ -1,10 +1,13 @@
 //! 数据面执行用例：认证、准入、路由、continuation、circuit 与会话生命周期。
 
-use std::collections::BTreeSet;
+use std::collections::{BTreeMap, BTreeSet};
 use std::fmt;
 use std::net::IpAddr;
 use std::num::NonZeroU32;
-use std::sync::Arc;
+use std::sync::{
+    Arc, Mutex, Weak,
+    atomic::{AtomicUsize, Ordering},
+};
 use std::time::{Duration, Instant, SystemTime};
 
 use futures::{FutureExt, future::BoxFuture, pin_mut, select_biased};
@@ -15,12 +18,32 @@ use crate::concurrency::{CapacityWait, ConcurrencyWaitBudget, ConcurrencyWaitQue
 use crate::engine::admission::{
     ClientAdmissionDecision, ClientAdmissionPort, ClientAdmissionRejection, ClientAdmissionRequest,
 };
+use crate::engine::authentication::{
+    ClientAuthenticationRequest, FrontendAuthenticationDecision,
+    FrontendAuthenticationExtensionIndex,
+};
 use crate::engine::budget::{ClientBudgetCharge, ClientBudgetPort};
 use crate::engine::continuation::{
     ContinuationBinding, NativeContinuationPin, NativeContinuationPort,
     NativeContinuationStoreErrorKind, PreviousResponseId,
 };
-use crate::engine::coordinator::ResponseExecutionSession;
+use crate::engine::coordinator::{CoordinationExtensions, ResponseExecutionSession};
+use crate::engine::extensions::ExtensionCallScope;
+use crate::engine::middleware::{
+    FrozenMiddlewarePlan, MiddlewareAuthority, MiddlewareContext, MiddlewareExtensionIndex,
+    MiddlewareTarget,
+};
+use crate::engine::nested::{
+    AffinityLookupPort, AffinityLookupRequest, AffinityLookupResult, BoundModelExecutionBinding,
+    BoundModelExecutionRequest, ExecutionEffects, NestedModelExecutionPort,
+    NestedModelExecutionRequest,
+};
+use crate::engine::observation::{
+    FrozenRequestObservationContext, RequestObservationDispatch, RequestObserverExtensionIndex,
+};
+use crate::engine::policy::{
+    ModelRouteDecision, RequestPolicyContext, RequestPolicyExtensionIndex,
+};
 use crate::engine::probe::{
     AccountProbe, AccountProbeError, AccountProbeErrorSource, AccountProbeRequest,
     AccountProbeResult, AccountProbeUpstreamResponse,
@@ -37,14 +60,18 @@ use crate::identity::ProviderKind;
 use crate::lifecycle::CancellationToken;
 use crate::operation::{Operation, ProviderSessionState};
 use crate::policy::{ClientApiKeyId, ClientPolicy};
+use crate::provider_ports::{ProviderSessionAffinityPort, ProviderStoreErrorKind};
 use crate::routing::{
-    ProviderCatalogUnavailable, PublicModelDescriptor, PublicModelId, RoutingContext,
-    RuntimeSnapshot, UpstreamModelId,
+    FrozenAccountScope, ProviderCatalogUnavailable, PublicModelDescriptor, PublicModelId,
+    RoutingContext, RuntimeSnapshot, UpstreamModelId,
 };
-use crate::runtime::RuntimeSnapshotHandle;
+use crate::runtime::{RuntimeSnapshotHandle, RuntimeSnapshotPublisher};
 
 const MODEL_REQUEST_DEADLINE: Duration = Duration::from_secs(10 * 60);
 const COORDINATION_TIMEOUT: Duration = Duration::from_millis(100);
+const MAX_NESTED_DEPTH: usize = 4;
+const MAX_NESTED_EXECUTIONS: usize = 16;
+const MAX_CONCURRENT_NESTED_EXECUTIONS: usize = 4;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ClientTransport {
@@ -52,6 +79,7 @@ pub enum ClientTransport {
     HttpSse,
     WebSocket,
     InternalProbe,
+    InternalPlugin,
 }
 
 impl ClientTransport {
@@ -62,6 +90,7 @@ impl ClientTransport {
             Self::HttpSse => "http_sse",
             Self::WebSocket => "websocket",
             Self::InternalProbe => "internal",
+            Self::InternalPlugin => "internal_plugin",
         }
     }
 }
@@ -82,6 +111,7 @@ pub struct ExecutionRequestMetadata {
 pub struct AuthenticatedClient {
     snapshot: Arc<RuntimeSnapshot>,
     policy: ClientPolicy,
+    authentication: Option<ClientAuthenticationRequest>,
 }
 
 impl AuthenticatedClient {
@@ -112,6 +142,8 @@ pub enum ClientAuthenticationError {
     InvalidKey,
     #[error("runtime snapshot is unavailable")]
     SnapshotUnavailable,
+    #[error("frontend authentication provider is unavailable")]
+    ProviderUnavailable,
 }
 
 pub struct StartExecution {
@@ -121,24 +153,134 @@ pub struct StartExecution {
     pub metadata: ExecutionRequestMetadata,
 }
 
+/// 入口中间件开始前冻结的根请求身份与生命周期。
+///
+/// 中间件短路时本值直接释放；调用 `next` 后必须原样交回
+/// [`ExecutionService::start_prepared`]，不能重新认证为另一个 Key。
+pub struct PreparedRootExecution {
+    client: AuthenticatedClient,
+    request_id: ModelRequestId,
+    started_at: SystemTime,
+    deadline_at: SystemTime,
+    cancellation: CancellationToken,
+    execution_effects: Arc<ExecutionEffects>,
+    execution_effects_baseline: usize,
+}
+
+impl PreparedRootExecution {
+    fn new(client: AuthenticatedClient) -> Result<Self, GatewayError> {
+        let started_at = SystemTime::now();
+        let deadline_at = started_at
+            .checked_add(MODEL_REQUEST_DEADLINE)
+            .ok_or_else(|| {
+                GatewayError::new(GatewayErrorKind::Internal, "system clock is invalid")
+            })?;
+        let execution_effects = Arc::new(ExecutionEffects::default());
+        let execution_effects_baseline = execution_effects.epoch();
+        Ok(Self {
+            client,
+            request_id: new_request_id()?,
+            started_at,
+            deadline_at,
+            cancellation: CancellationToken::new(),
+            execution_effects,
+            execution_effects_baseline,
+        })
+    }
+
+    #[must_use]
+    pub const fn request_id(&self) -> &ModelRequestId {
+        &self.request_id
+    }
+
+    #[must_use]
+    pub const fn client(&self) -> &AuthenticatedClient {
+        &self.client
+    }
+
+    #[must_use]
+    pub const fn started_at(&self) -> SystemTime {
+        self.started_at
+    }
+
+    #[must_use]
+    pub const fn deadline_at(&self) -> SystemTime {
+        self.deadline_at
+    }
+
+    #[must_use]
+    pub fn cancellation(&self) -> CancellationToken {
+        self.cancellation.clone()
+    }
+
+    /// 以冻结的入口身份补齐 Runtime-only binding 事实；调用位置事实由 API/Core 提供。
+    #[must_use]
+    pub fn middleware_context(
+        &self,
+        mut target: MiddlewareTarget,
+        extension_scope: ExtensionCallScope,
+    ) -> MiddlewareContext {
+        target.request_id = self.request_id.clone();
+        let account_group_ids = self
+            .client
+            .policy
+            .account_scope()
+            .routing_snapshot()
+            .groups_snapshot()
+            .iter()
+            .map(|group| group.id().clone())
+            .collect::<Vec<_>>();
+        MiddlewareContext::new(
+            target,
+            MiddlewareAuthority {
+                client_key_id: self.client.policy.key_id().clone(),
+                account_group_ids: Arc::from(account_group_ids),
+                cancellation: self.cancellation.clone(),
+                deadline: self.deadline_at,
+                extension_scope,
+                execution_effects: Some(Arc::clone(&self.execution_effects)),
+            },
+        )
+    }
+}
+
+/// 入口中间件调用 `next` 后交给 Core 的已解码执行输入。
+pub struct PreparedExecutionRequest {
+    pub public_model: PublicModelId,
+    pub operation: Operation,
+    pub metadata: ExecutionRequestMetadata,
+}
+
 /// 启动一个由协议 adapter 明确绑定到 Provider 自有端点的请求。
 pub struct StartProviderExecution {
     pub client: AuthenticatedClient,
     pub provider: ProviderKind,
+    /// Provider 自有模型端点可固定上游模型；非模型端点保持 `None`。
+    pub upstream_model: Option<UpstreamModelId>,
     pub operation: Operation,
     pub metadata: ExecutionRequestMetadata,
 }
 
 enum ExecutionTarget {
     Model(PublicModelId),
-    ProviderEndpoint(ProviderKind),
+    ProviderEndpoint {
+        provider: ProviderKind,
+        upstream_model: Option<UpstreamModelId>,
+    },
 }
 
 impl ExecutionTarget {
+    fn public_model(&self) -> Option<&PublicModelId> {
+        match self {
+            Self::Model(model) => Some(model),
+            Self::ProviderEndpoint { .. } => None,
+        }
+    }
+
     fn into_public_model(self) -> Option<PublicModelId> {
         match self {
             Self::Model(model) => Some(model),
-            Self::ProviderEndpoint(_) => None,
+            Self::ProviderEndpoint { .. } => None,
         }
     }
 }
@@ -150,6 +292,193 @@ struct PendingStartExecution {
     metadata: ExecutionRequestMetadata,
 }
 
+struct AuthorizedExecution {
+    account_scope: Arc<FrozenAccountScope>,
+    deadline_at: SystemTime,
+    cancellation: CancellationToken,
+    extension_scope: ExtensionCallScope,
+    required_provider: Option<ProviderKind>,
+    required_account: Option<ProviderAccountId>,
+    nested: Option<NestedExecutionFacts>,
+    bound: Option<BoundExecutionFacts>,
+    graph: Option<Arc<NestedExecutionGraph>>,
+    execution_effects_baseline: usize,
+    nested_permit: Option<NestedExecutionPermit>,
+}
+
+struct ExecutionStartGuard {
+    admission: ExecutionAdmission,
+    active_request: Option<ActiveRequestLease>,
+    concurrency_wait_budget: ConcurrencyWaitBudget,
+    admission_decision_ms: Option<u64>,
+}
+
+struct PreparedExecutionStart {
+    request_id: ModelRequestId,
+    started_at: SystemTime,
+    plan: crate::routing::RoutingPlan,
+    extensions: CoordinationExtensions,
+    authorization: AuthorizedExecution,
+    guard: ExecutionStartGuard,
+}
+
+struct NestedExecutionFacts {
+    parent_request_id: ModelRequestId,
+    initiating_plugin_instance_id: String,
+}
+
+struct BoundExecutionFacts {
+    initiating_plugin_instance_id: String,
+}
+
+struct NestedExecutionGraph {
+    total_started: AtomicUsize,
+    active: AtomicUsize,
+    effects: Arc<ExecutionEffects>,
+}
+
+impl NestedExecutionGraph {
+    fn new(effects: Arc<ExecutionEffects>) -> Self {
+        Self {
+            total_started: AtomicUsize::new(0),
+            active: AtomicUsize::new(0),
+            effects,
+        }
+    }
+
+    fn acquire(self: &Arc<Self>) -> Result<NestedExecutionPermit, GatewayError> {
+        if self
+            .active
+            .fetch_update(Ordering::AcqRel, Ordering::Acquire, |active| {
+                (active < MAX_CONCURRENT_NESTED_EXECUTIONS).then_some(active + 1)
+            })
+            .is_err()
+        {
+            return Err(GatewayError::new(
+                GatewayErrorKind::ConcurrencyQueueFull,
+                "nested model execution concurrency is exhausted",
+            ));
+        }
+        if self
+            .total_started
+            .fetch_update(Ordering::AcqRel, Ordering::Acquire, |total| {
+                (total < MAX_NESTED_EXECUTIONS).then_some(total + 1)
+            })
+            .is_err()
+        {
+            self.active.fetch_sub(1, Ordering::AcqRel);
+            return Err(GatewayError::new(
+                GatewayErrorKind::PolicyDenied,
+                "nested model execution budget is exhausted",
+            ));
+        }
+        Ok(NestedExecutionPermit {
+            graph: Arc::clone(self),
+            armed: true,
+        })
+    }
+}
+
+struct NestedExecutionPermit {
+    graph: Arc<NestedExecutionGraph>,
+    armed: bool,
+}
+
+impl NestedExecutionPermit {
+    fn release(mut self) {
+        if self.armed {
+            self.graph.active.fetch_sub(1, Ordering::AcqRel);
+            self.armed = false;
+        }
+    }
+}
+
+impl Drop for NestedExecutionPermit {
+    fn drop(&mut self) {
+        if self.armed {
+            self.graph.active.fetch_sub(1, Ordering::AcqRel);
+        }
+    }
+}
+
+struct ActiveRequestAuthority {
+    client: AuthenticatedClient,
+    account_scope: Arc<FrozenAccountScope>,
+    deadline_at: SystemTime,
+    cancellation: CancellationToken,
+    extension_scope: ExtensionCallScope,
+    graph: Arc<NestedExecutionGraph>,
+}
+
+type ActiveRequestRegistry = Arc<Mutex<BTreeMap<ModelRequestId, Weak<ActiveRequestAuthority>>>>;
+
+struct ActiveRequestLease {
+    registry: ActiveRequestRegistry,
+    request_id: ModelRequestId,
+    authority: Arc<ActiveRequestAuthority>,
+}
+
+/// 管理页或 CLI 一次调用持有的显式模型执行身份。
+///
+/// 结构不暴露 Key 明文；Runtime 只能把它原样交回 Core 发起模型请求。
+#[derive(Clone)]
+pub struct BoundModelExecutionContext {
+    authority: Arc<BoundModelExecutionAuthority>,
+}
+
+struct BoundModelExecutionAuthority {
+    client: AuthenticatedClient,
+    account_scope: Arc<FrozenAccountScope>,
+    deadline_at: SystemTime,
+    cancellation: CancellationToken,
+    extension_scope: ExtensionCallScope,
+    graph: Arc<NestedExecutionGraph>,
+    initiating_plugin_instance_id: String,
+}
+
+impl fmt::Debug for BoundModelExecutionContext {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("BoundModelExecutionContext")
+            .field("key_id", &self.authority.client.policy.key_id())
+            .field(
+                "initiating_plugin_instance_id",
+                &self.authority.initiating_plugin_instance_id,
+            )
+            .field("deadline_at", &self.authority.deadline_at)
+            .finish_non_exhaustive()
+    }
+}
+
+impl Drop for BoundModelExecutionAuthority {
+    fn drop(&mut self) {
+        self.cancellation.cancel();
+    }
+}
+
+impl ActiveRequestLease {
+    fn release(self) {
+        drop(self);
+    }
+}
+
+impl Drop for ActiveRequestLease {
+    fn drop(&mut self) {
+        self.authority.cancellation.cancel();
+        let mut active = self
+            .registry
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if active
+            .get(&self.request_id)
+            .and_then(Weak::upgrade)
+            .is_some_and(|authority| Arc::ptr_eq(&authority, &self.authority))
+        {
+            active.remove(&self.request_id);
+        }
+    }
+}
+
 pub struct StartedExecution {
     pub request_id: ModelRequestId,
     pub created_at: SystemTime,
@@ -167,6 +496,9 @@ pub trait ExecutionSession: Send {
     fn response_status_code(&self) -> Option<u16> {
         None
     }
+    fn discard_pending_delivery(&mut self) -> Result<(), EngineError> {
+        Err(EngineError::InvalidDeliveryState)
+    }
     fn commit_downstream(
         &mut self,
         client_status_code: Option<u16>,
@@ -188,6 +520,24 @@ pub trait ExecutionService: Send + Sync {
         &self,
         plaintext: &str,
     ) -> Result<AuthenticatedClient, ClientAuthenticationError>;
+    fn authenticate_request(
+        &self,
+        request: ClientAuthenticationRequest,
+    ) -> BoxFuture<'_, Result<AuthenticatedClient, ClientAuthenticationError>> {
+        Box::pin(async move {
+            let plaintext = request
+                .native_bearer()
+                .ok_or(ClientAuthenticationError::InvalidKey)?;
+            self.authenticate(plaintext.expose_for_auth())
+        })
+    }
+    /// 只验证入口认证信封，不记录 Key 使用事实或执行推理准入。
+    fn verify_request(
+        &self,
+        _request: ClientAuthenticationRequest,
+    ) -> BoxFuture<'_, Result<AuthenticatedClient, ClientAuthenticationError>> {
+        Box::pin(async { Err(ClientAuthenticationError::InvalidKey) })
+    }
     fn public_models(&self, client: &AuthenticatedClient) -> Vec<PublicModelId>;
     fn client_model_catalog<'a>(
         &'a self,
@@ -198,6 +548,80 @@ pub trait ExecutionService: Send + Sync {
         Box::pin(async { Err(ProviderCatalogUnavailable) })
     }
     fn contains_public_model(&self, client: &AuthenticatedClient, model: &PublicModelId) -> bool;
+
+    /// 重新鉴权并冻结本次根请求身份、请求 ID、deadline 与取消域。
+    fn prepare_execution(
+        &self,
+        client: AuthenticatedClient,
+    ) -> BoxFuture<'_, Result<PreparedRootExecution, GatewayError>> {
+        Box::pin(async move { PreparedRootExecution::new(client) })
+    }
+
+    /// 由已经验证管理会话与插件 models 域的宿主入口选择 Key。
+    /// 不向页面提供明文，也不跳过普通请求的扩展、准入和计量。
+    fn prepare_plugin_execution(
+        &self,
+        _client_key_id: &ClientApiKeyId,
+    ) -> BoxFuture<'_, Result<PreparedRootExecution, GatewayError>> {
+        Box::pin(async {
+            Err(GatewayError::new(
+                GatewayErrorKind::Unauthorized,
+                "plugin model entry is unavailable",
+            ))
+        })
+    }
+
+    /// 为已经通过 `verify_request` 的只读入口建立中间件生命周期，不重复写 Key 使用事实。
+    fn prepare_verified_execution(
+        &self,
+        client: AuthenticatedClient,
+    ) -> Result<PreparedRootExecution, GatewayError> {
+        PreparedRootExecution::new(client)
+    }
+
+    /// 解析与准备阶段冻结的发布代次一致的中间件计划。
+    fn middleware_plan(&self, _prepared: &PreparedRootExecution) -> Option<FrozenMiddlewarePlan> {
+        None
+    }
+
+    /// 消费一次已准备身份并进入原有 Core 路由、准入、attempt 与结算路径。
+    fn start_prepared(
+        &self,
+        prepared: PreparedRootExecution,
+        request: PreparedExecutionRequest,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async move {
+            self.start(StartExecution {
+                client: prepared.client,
+                public_model: request.public_model,
+                operation: request.operation,
+                metadata: request.metadata,
+            })
+            .await
+        })
+    }
+
+    /// 消费一次已准备身份，并进入 Provider 自有端点的原有准入与结算路径。
+    fn start_prepared_provider_endpoint(
+        &self,
+        prepared: PreparedRootExecution,
+        provider: ProviderKind,
+        upstream_model: Option<UpstreamModelId>,
+        operation: Operation,
+        metadata: ExecutionRequestMetadata,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async move {
+            self.start_provider_endpoint(StartProviderExecution {
+                client: prepared.client,
+                provider,
+                upstream_model,
+                operation,
+                metadata,
+            })
+            .await
+        })
+    }
+
     fn start(
         &self,
         request: StartExecution,
@@ -268,8 +692,6 @@ pub trait ProviderCircuitPort: Send + Sync {
 
 pub struct DefaultExecutionService {
     snapshots: RuntimeSnapshotHandle,
-    coordinator: Arc<AttemptCoordinator<dyn ExecutionStore>>,
-    probe_coordinator: Arc<AttemptCoordinator<dyn ExecutionStore>>,
     /// probe 自身走 transient store，探测失败仍写入持久 store 的 ops_events。
     observations: Arc<dyn ExecutionStore>,
     providers: ProviderRegistry,
@@ -279,6 +701,13 @@ pub struct DefaultExecutionService {
     continuation: Arc<dyn NativeContinuationPort>,
     client_api_key_usage: Arc<dyn ClientApiKeyUsageSink>,
     budget: Option<Arc<dyn ClientBudgetPort>>,
+    request_observers: Option<RequestObserverExtensionIndex>,
+    request_policies: Option<RequestPolicyExtensionIndex>,
+    middlewares: Option<MiddlewareExtensionIndex>,
+    frontend_authentication: Option<FrontendAuthenticationExtensionIndex>,
+    session_affinity: Option<Arc<dyn ProviderSessionAffinityPort>>,
+    snapshot_refresh: Option<Arc<RuntimeSnapshotPublisher>>,
+    active_requests: ActiveRequestRegistry,
 }
 
 impl DefaultExecutionService {
@@ -292,15 +721,9 @@ impl DefaultExecutionService {
         continuation: Arc<dyn NativeContinuationPort>,
         client_api_key_usage: Arc<dyn ClientApiKeyUsageSink>,
     ) -> Self {
-        let observations = Arc::clone(&execution);
-        let engine = GatewayEngine::<dyn ExecutionStore>::new(execution, providers.clone());
-        let transient: Arc<dyn ExecutionStore> = Arc::new(TransientExecutionStore);
-        let probe_engine = GatewayEngine::<dyn ExecutionStore>::new(transient, providers.clone());
         Self {
             snapshots,
-            coordinator: Arc::new(AttemptCoordinator::new(engine)),
-            probe_coordinator: Arc::new(AttemptCoordinator::new(probe_engine)),
-            observations,
+            observations: execution,
             providers,
             admissions,
             admission_waiting: ConcurrencyWaitQueue::default(),
@@ -308,6 +731,13 @@ impl DefaultExecutionService {
             continuation,
             client_api_key_usage,
             budget: None,
+            request_observers: None,
+            request_policies: None,
+            middlewares: None,
+            frontend_authentication: None,
+            session_affinity: None,
+            snapshot_refresh: None,
+            active_requests: Arc::default(),
         }
     }
 
@@ -317,10 +747,55 @@ impl DefaultExecutionService {
         self
     }
 
+    #[must_use]
+    pub fn with_request_observers(mut self, observers: RequestObserverExtensionIndex) -> Self {
+        self.request_observers = Some(observers);
+        self
+    }
+
+    #[must_use]
+    pub fn with_request_policies(mut self, policies: RequestPolicyExtensionIndex) -> Self {
+        self.request_policies = Some(policies);
+        self
+    }
+
+    #[must_use]
+    pub fn with_middlewares(mut self, middlewares: MiddlewareExtensionIndex) -> Self {
+        self.middlewares = Some(middlewares);
+        self
+    }
+
+    #[must_use]
+    pub fn with_frontend_authentication(
+        mut self,
+        authentication: FrontendAuthenticationExtensionIndex,
+    ) -> Self {
+        self.frontend_authentication = Some(authentication);
+        self
+    }
+
+    #[must_use]
+    pub fn with_session_affinity(
+        mut self,
+        session_affinity: Arc<dyn ProviderSessionAffinityPort>,
+    ) -> Self {
+        self.session_affinity = Some(session_affinity);
+        self
+    }
+
+    /// CLI command-plane 没有后台订阅；每次绑定显式身份前主动编译最新事实。
+    #[must_use]
+    pub fn with_snapshot_refresh(mut self, refresh: Arc<RuntimeSnapshotPublisher>) -> Self {
+        self.snapshot_refresh = Some(refresh);
+        self
+    }
+
     fn authenticate_without_usage(
         &self,
         plaintext: &str,
     ) -> Result<AuthenticatedClient, ClientAuthenticationError> {
+        let authentication = ClientAuthenticationRequest::bearer(plaintext)
+            .map_err(|_| ClientAuthenticationError::InvalidKey)?;
         let snapshot = self
             .snapshots
             .acquire()
@@ -333,7 +808,59 @@ impl DefaultExecutionService {
             .find(|policy| policy.authorize().is_ok())
             .cloned()
             .ok_or(ClientAuthenticationError::InvalidKey)?;
-        Ok(AuthenticatedClient { snapshot, policy })
+        Ok(AuthenticatedClient {
+            snapshot,
+            policy,
+            authentication: Some(authentication),
+        })
+    }
+
+    async fn authenticate_request_without_usage(
+        &self,
+        authentication: ClientAuthenticationRequest,
+    ) -> Result<AuthenticatedClient, ClientAuthenticationError> {
+        let snapshot = self
+            .snapshots
+            .acquire()
+            .map_err(|_| ClientAuthenticationError::SnapshotUnavailable)?;
+        let frontend = self
+            .frontend_authentication
+            .as_ref()
+            .and_then(|index| snapshot.extensions().and_then(|set| index.resolve(set)));
+        let policy = if let Some(frontend) = frontend {
+            match frontend
+                .authenticate(&authentication)
+                .await
+                .map_err(|_| ClientAuthenticationError::ProviderUnavailable)?
+            {
+                FrontendAuthenticationDecision::Authenticated { principal } => {
+                    let id = frontend
+                        .client_key_id(&principal)
+                        .ok_or(ClientAuthenticationError::InvalidKey)?;
+                    snapshot
+                        .client_policy(&id)
+                        .filter(|policy| policy.authorize().is_ok())
+                        .cloned()
+                        .ok_or(ClientAuthenticationError::InvalidKey)?
+                }
+                FrontendAuthenticationDecision::Rejected => {
+                    return Err(ClientAuthenticationError::InvalidKey);
+                }
+                FrontendAuthenticationDecision::NotMatched if frontend.exclusive() => {
+                    return Err(ClientAuthenticationError::InvalidKey);
+                }
+                FrontendAuthenticationDecision::NotMatched => {
+                    native_policy(&snapshot, &authentication)?
+                }
+            }
+        } else {
+            native_policy(&snapshot, &authentication)?
+        };
+        Ok(AuthenticatedClient {
+            snapshot,
+            policy,
+            authentication: Some(authentication),
+        })
     }
 
     async fn start_inner(&self, request: StartExecution) -> Result<StartedExecution, GatewayError> {
@@ -343,12 +870,13 @@ impl DefaultExecutionService {
             operation,
             metadata,
         } = request;
-        self.start_inner_with_target(PendingStartExecution {
-            client,
-            target: ExecutionTarget::Model(public_model),
+        let prepared = self.prepare_root_execution_inner(client).await?;
+        self.start_prepared_with_target(
+            prepared,
+            ExecutionTarget::Model(public_model),
             operation,
             metadata,
-        })
+        )
         .await
     }
 
@@ -359,204 +887,497 @@ impl DefaultExecutionService {
         let StartProviderExecution {
             client,
             provider,
+            upstream_model,
             operation,
             metadata,
         } = request;
-        self.start_inner_with_target(PendingStartExecution {
-            client,
-            target: ExecutionTarget::ProviderEndpoint(provider),
+        let prepared = self.prepare_root_execution_inner(client).await?;
+        self.start_prepared_with_target(
+            prepared,
+            ExecutionTarget::ProviderEndpoint {
+                provider,
+                upstream_model,
+            },
             operation,
             metadata,
-        })
+        )
         .await
     }
 
-    async fn start_inner_with_target(
+    async fn prepare_root_execution_inner(
         &self,
-        mut request: PendingStartExecution,
-    ) -> Result<StartedExecution, GatewayError> {
+        mut client: AuthenticatedClient,
+    ) -> Result<PreparedRootExecution, GatewayError> {
         // 长连接每次执行都重新鉴权并冻结当前策略，确保限额和授权变更对新请求生效。
-        request.client = self
-            .authenticate(request.client.policy.plaintext_key().expose_for_auth())
-            .map_err(|error| match error {
-                ClientAuthenticationError::InvalidKey => {
-                    GatewayError::new(GatewayErrorKind::Unauthorized, "client API key is invalid")
-                }
-                ClientAuthenticationError::SnapshotUnavailable => GatewayError::new(
-                    GatewayErrorKind::Internal,
-                    "runtime snapshot is unavailable",
-                ),
-            })?;
-        let started_at = SystemTime::now();
-        let deadline_at = started_at
-            .checked_add(MODEL_REQUEST_DEADLINE)
-            .ok_or_else(|| {
-                GatewayError::new(GatewayErrorKind::Internal, "system clock is invalid")
-            })?;
-        let request_id = new_request_id()?;
-        let routing_context = self
-            .route_context(request.client.policy.account_scope().provider_kinds())
-            .await?;
-        let account_scope = Arc::clone(request.client.policy.account_scope());
-        let plan = match &request.target {
-            ExecutionTarget::ProviderEndpoint(provider) => {
-                request.client.snapshot.plan_provider_endpoint(
-                    provider,
-                    &request.operation,
-                    account_scope,
-                    &routing_context,
-                )
-            }
-            ExecutionTarget::Model(public_model) => request.client.snapshot.plan(
-                public_model,
-                &request.operation,
-                account_scope,
-                &routing_context,
-            ),
-        }
-        .map_err(map_routing_error)?;
-        let continuation = match request.metadata.previous_response_id.as_ref() {
-            Some(previous) => {
-                let resolve = self
-                    .continuation
-                    .resolve(request.client.policy.key_id(), previous)
-                    .fuse();
-                let timeout = Delay::new(COORDINATION_TIMEOUT).fuse();
-                pin_mut!(resolve, timeout);
-                let pin = select_biased! {
-                    result = resolve => match result {
-                        Ok(pin) => pin,
-                        Err(error)
-                            if error.kind() == NativeContinuationStoreErrorKind::Unavailable =>
-                        {
-                            tracing::debug!(
-                                request_id = request_id.as_str(),
-                                %error,
-                                "Continuation affinity 查询失败，退化为外部续接"
-                            );
-                            None
-                        }
-                        Err(error)
-                            if error.kind()
-                                == NativeContinuationStoreErrorKind::OwnershipMismatch =>
-                        {
-                            return Err(GatewayError::new(
-                                GatewayErrorKind::PolicyDenied,
-                                "continuation does not belong to this client API key",
-                            ));
-                        }
-                        Err(error) => {
-                            tracing::warn!(
-                                request_id = request_id.as_str(),
-                                %error,
-                                "Continuation affinity 记录无效，已拒绝续接"
-                            );
-                            return Err(GatewayError::new(
-                                GatewayErrorKind::Internal,
-                                "continuation state is invalid",
-                            ));
-                        }
-                    },
-                    _ = timeout => None,
-                };
-                match pin {
-                    Some(pin) if !pin.matches_client(request.client.policy.key_id()) => {
-                        return Err(GatewayError::new(
-                            GatewayErrorKind::PolicyDenied,
-                            "continuation does not belong to this client API key",
-                        ));
-                    }
-                    Some(pin) if !request.client.policy.account_scope().allows(pin.account()) => {
-                        return Err(GatewayError::new(
-                            GatewayErrorKind::PolicyDenied,
-                            "continuation account is outside the client account scope",
-                        ));
-                    }
-                    Some(pin)
-                        if !plan
-                            .candidates()
-                            .iter()
-                            .any(|candidate| candidate.provider() == pin.provider()) =>
-                    {
-                        return Err(GatewayError::new(
-                            GatewayErrorKind::NoAvailableProvider,
-                            "continuation provider is not available",
-                        ));
-                    }
-                    Some(pin) => {
-                        attach_continuation_session_state(&mut request.operation, &pin);
-                        ContinuationBinding::Pinned(pin)
-                    }
-                    None => ContinuationBinding::External(previous.clone()),
-                }
-            }
-            None => {
-                return self
-                    .start_without_continuation(
-                        request,
-                        request_id,
-                        started_at,
-                        deadline_at,
-                        plan,
-                        None,
-                    )
-                    .await;
-            }
-        };
-        self.start_without_continuation(
-            request,
+        let expected_key_id = client.policy.key_id().clone();
+        let authentication = client.authentication.clone().ok_or_else(|| {
+            GatewayError::new(
+                GatewayErrorKind::Internal,
+                "bound execution identity cannot enter the public start path",
+            )
+        })?;
+        client = self
+            .authenticate_request_without_usage(authentication)
+            .await
+            .and_then(|client| {
+                (client.policy.key_id() == &expected_key_id)
+                    .then_some(client)
+                    .ok_or(ClientAuthenticationError::InvalidKey)
+            })
+            .map_err(authentication_gateway_error)?;
+        self.client_api_key_usage
+            .record_used(client.policy().key_id());
+        PreparedRootExecution::new(client)
+    }
+
+    async fn start_prepared_with_target(
+        &self,
+        prepared: PreparedRootExecution,
+        target: ExecutionTarget,
+        operation: Operation,
+        metadata: ExecutionRequestMetadata,
+    ) -> Result<StartedExecution, GatewayError> {
+        let PreparedRootExecution {
+            client,
             request_id,
             started_at,
             deadline_at,
-            plan,
-            Some(continuation),
+            cancellation,
+            execution_effects,
+            execution_effects_baseline,
+        } = prepared;
+        let authorization = AuthorizedExecution {
+            account_scope: Arc::clone(client.policy.account_scope()),
+            deadline_at,
+            cancellation,
+            extension_scope: ExtensionCallScope::default(),
+            required_provider: None,
+            required_account: None,
+            nested: None,
+            bound: None,
+            graph: client
+                .snapshot
+                .extensions()
+                .map(|_| Arc::new(NestedExecutionGraph::new(execution_effects))),
+            execution_effects_baseline,
+            nested_permit: None,
+        };
+        self.start_authorized(
+            PendingStartExecution {
+                client,
+                target,
+                operation,
+                metadata,
+            },
+            authorization,
+            started_at,
+            Some(request_id),
         )
         .await
     }
 
+    async fn start_authorized(
+        &self,
+        mut request: PendingStartExecution,
+        mut authorization: AuthorizedExecution,
+        started_at: SystemTime,
+        request_id: Option<ModelRequestId>,
+    ) -> Result<StartedExecution, GatewayError> {
+        let request_id = request_id.map_or_else(new_request_id, Ok)?;
+        if authorization.cancellation.is_cancelled() {
+            return Err(GatewayError::new(
+                GatewayErrorKind::Cancelled,
+                "parent request was cancelled",
+            ));
+        }
+        if authorization
+            .deadline_at
+            .duration_since(SystemTime::now())
+            .unwrap_or_default()
+            .is_zero()
+        {
+            return Err(GatewayError::new(
+                GatewayErrorKind::Timeout,
+                "request deadline elapsed",
+            ));
+        }
+        let account_group_ids = authorization
+            .account_scope
+            .routing_snapshot()
+            .groups_snapshot()
+            .iter()
+            .map(|group| group.id().clone())
+            .collect::<Vec<_>>();
+        let middleware = self.middlewares.as_ref().and_then(|middlewares| {
+            let generation = request.client.snapshot.extensions()?.clone();
+            middlewares.resolve(&generation)
+        });
+        let request_policy = self.request_policies.as_ref().and_then(|policies| {
+            let generation = request.client.snapshot.extensions()?.clone();
+            let plan = policies.resolve(&generation)?;
+            Some(
+                RequestPolicyContext::new(
+                    plan,
+                    generation,
+                    request_id.clone(),
+                    request.client.policy.key_id().clone(),
+                    account_group_ids.clone(),
+                )
+                .with_extension_scope(authorization.extension_scope.clone())
+                .with_execution_effects(Arc::clone(&authorization.graph.as_ref()?.effects)),
+            )
+        });
+        // 路由插件可以调用 host.model/host.affinity；仅这条扩展路径必须在首次 RPC
+        // 前取得父 Key 准入。无策略的原生路由仍保持“先路由、后准入”的既有顺序。
+        let mut start_guard = if request_policy.is_some() {
+            Some(
+                self.prepare_execution_start(&request, &request_id, &mut authorization)
+                    .await?,
+            )
+        } else {
+            None
+        };
+        let request_observation = self.request_observers.as_ref().and_then(|observers| {
+            let generation = request.client.snapshot.extensions()?.clone();
+            let plan = observers.resolve(&generation)?;
+            Some(RequestObservationDispatch::new(
+                plan,
+                generation,
+                FrozenRequestObservationContext::new(
+                    request_id.clone(),
+                    request.client.snapshot.revision(),
+                    request.client.policy.key_id().clone(),
+                    account_group_ids.clone(),
+                    request.operation.kind(),
+                    request.target.public_model().cloned(),
+                    authorization.extension_scope.clone(),
+                ),
+            ))
+        });
+        let budget_key_id = request.client.policy.key_id().clone();
+        let result = async {
+            let mut routing_context = self
+                .route_context(authorization.account_scope.provider_kinds())
+                .await?;
+            if let Some(provider) = authorization.required_provider.clone() {
+                if !authorization.account_scope.provider_kinds().contains(&provider) {
+                    return Err(GatewayError::new(
+                        GatewayErrorKind::PolicyDenied,
+                        "nested provider is outside the frozen account scope",
+                    ));
+                }
+                routing_context.required_provider = Some(provider);
+            }
+            let account_scope = Arc::clone(&authorization.account_scope);
+            let plan = match &request.target {
+                ExecutionTarget::ProviderEndpoint {
+                    provider,
+                    upstream_model,
+                } => request.client.snapshot.plan_provider_endpoint(
+                    provider,
+                    upstream_model.as_ref(),
+                    &request.operation,
+                    account_scope,
+                    &routing_context,
+                ),
+                ExecutionTarget::Model(public_model) => {
+                    let mut target_model = public_model.clone();
+                    let mut target_context = routing_context.clone();
+                    if let Some(policy) = &request_policy {
+                        let available = request
+                            .client
+                            .snapshot
+                            .available_providers(&account_scope, &routing_context);
+                        match policy
+                            .route_model(request.operation.clone(), public_model.clone(), available)
+                            .await
+                            .map_err(|_| {
+                                GatewayError::new(
+                                    GatewayErrorKind::Internal,
+                                    "model routing policy failed",
+                                )
+                            })? {
+                            ModelRouteDecision::Unhandled => {}
+                            ModelRouteDecision::Reject => {
+                                return Err(GatewayError::new(
+                                    GatewayErrorKind::PolicyDenied,
+                                    "model routing policy rejected the request",
+                                ));
+                            }
+                            ModelRouteDecision::Route { provider, model } => {
+                                if provider.is_none() && model.is_none() {
+                                    return Err(GatewayError::new(
+                                        GatewayErrorKind::Internal,
+                                        "model routing policy returned an empty target",
+                                    ));
+                                }
+                                if let Some(provider) = provider {
+                                    if authorization
+                                        .required_provider
+                                        .as_ref()
+                                        .is_some_and(|required| required != &provider)
+                                        || !authorization
+                                            .account_scope
+                                            .provider_kinds()
+                                            .contains(&provider)
+                                    {
+                                        return Err(GatewayError::new(
+                                            GatewayErrorKind::PolicyDenied,
+                                            "model routing policy exceeded the frozen provider scope",
+                                        ));
+                                    }
+                                    target_context.required_provider = Some(provider);
+                                }
+                                if let Some(model) = model {
+                                    target_model = model;
+                                }
+                            }
+                        }
+                    }
+                    request.client.snapshot.plan(
+                        &target_model,
+                        &request.operation,
+                        account_scope,
+                        &target_context,
+                    )
+                }
+            }
+            .map_err(map_routing_error)?;
+            let continuation = match request.metadata.previous_response_id.as_ref() {
+                Some(previous) => {
+                    let resolve = self
+                        .continuation
+                        .resolve(request.client.policy.key_id(), previous)
+                        .fuse();
+                    let timeout = Delay::new(COORDINATION_TIMEOUT).fuse();
+                    pin_mut!(resolve, timeout);
+                    let pin = select_biased! {
+                        result = resolve => match result {
+                            Ok(pin) => pin,
+                            Err(error)
+                                if error.kind() == NativeContinuationStoreErrorKind::Unavailable =>
+                            {
+                                tracing::debug!(request_id = request_id.as_str(), %error, "Continuation affinity 查询失败，退化为外部续接");
+                                None
+                            }
+                            Err(error)
+                                if error.kind() == NativeContinuationStoreErrorKind::OwnershipMismatch =>
+                            {
+                                return Err(GatewayError::new(GatewayErrorKind::PolicyDenied, "continuation does not belong to this client API key"));
+                            }
+                            Err(error) => {
+                                tracing::warn!(request_id = request_id.as_str(), %error, "Continuation affinity 记录无效，已拒绝续接");
+                                return Err(GatewayError::new(GatewayErrorKind::Internal, "continuation state is invalid"));
+                            }
+                        },
+                        _ = timeout => None,
+                    };
+                    Some(match pin {
+                        Some(pin) if !pin.matches_client(request.client.policy.key_id()) => {
+                            return Err(GatewayError::new(GatewayErrorKind::PolicyDenied, "continuation does not belong to this client API key"));
+                        }
+                        Some(pin) if !authorization.account_scope.allows(pin.account()) => {
+                            return Err(GatewayError::new(GatewayErrorKind::PolicyDenied, "continuation account is outside the client account scope"));
+                        }
+                        Some(pin)
+                            if !plan.candidates().iter().any(|candidate| candidate.provider() == pin.provider()) =>
+                        {
+                            return Err(GatewayError::new(GatewayErrorKind::NoAvailableProvider, "continuation provider is not available"));
+                        }
+                        Some(pin) => {
+                            attach_continuation_session_state(&mut request.operation, &pin);
+                            ContinuationBinding::Pinned(pin)
+                        }
+                        None => ContinuationBinding::External(previous.clone()),
+                    })
+                }
+                None => None,
+            };
+            if start_guard.is_none() {
+                start_guard = Some(
+                    self.prepare_execution_start(&request, &request_id, &mut authorization)
+                        .await?,
+                );
+            }
+            let execution_effects = authorization
+                .graph
+                .as_ref()
+                .map(|graph| Arc::clone(&graph.effects));
+            let extensions =
+                CoordinationExtensions::new(continuation, request_observation.clone())
+                    .with_request_policy(request_policy)
+                    .with_execution_effects(
+                        execution_effects,
+                        authorization.execution_effects_baseline,
+                    )
+                    .with_middleware(
+                        middleware,
+                        Arc::from(account_group_ids.clone()),
+                        request.metadata.endpoint.clone(),
+                        request.metadata.transport,
+                    )
+                    .with_extension_scope(authorization.extension_scope.clone());
+            self.start_without_continuation(
+                request,
+                PreparedExecutionStart {
+                    request_id: request_id.clone(),
+                    started_at,
+                    plan,
+                    extensions,
+                    authorization,
+                    guard: start_guard
+                        .take()
+                        .expect("execution start guard was prepared"),
+                },
+            )
+            .await
+        }
+        .await;
+        if let (Some(observation), Err(error)) = (&request_observation, &result) {
+            observation.reject(error);
+        }
+        if result.is_err()
+            && let Some(guard) = start_guard.take()
+        {
+            guard
+                .release_failed(self.budget.as_deref(), request_id, budget_key_id)
+                .await;
+        }
+        result
+    }
+
+    async fn prepare_execution_start(
+        &self,
+        request: &PendingStartExecution,
+        request_id: &ModelRequestId,
+        authorization: &mut AuthorizedExecution,
+    ) -> Result<ExecutionStartGuard, GatewayError> {
+        let concurrency_wait_budget = ConcurrencyWaitBudget::default();
+        let (admission, admission_decision_ms) = if authorization.nested.is_some() {
+            let permit = authorization.nested_permit.take().ok_or_else(|| {
+                GatewayError::new(
+                    GatewayErrorKind::Internal,
+                    "nested execution admission is unavailable",
+                )
+            })?;
+            (ExecutionAdmission::Nested(permit), None)
+        } else {
+            let admission_started_at = Instant::now();
+            let admission = self
+                .acquire_client_admission(
+                    &request.client,
+                    request_id,
+                    authorization.deadline_at,
+                    &concurrency_wait_budget,
+                )
+                .await?;
+            let admission = if let Some(permit) = authorization.nested_permit.take() {
+                ExecutionAdmission::Bound(admission, permit)
+            } else {
+                ExecutionAdmission::Client(admission)
+            };
+            (admission, Some(duration_ms(admission_started_at.elapsed())))
+        };
+        if let Some(budget) = &self.budget
+            && let Err(error) = budget.admit(request.client.policy.key_id().clone()).await
+        {
+            admission.release().await;
+            return Err(error);
+        }
+        let active_request = authorization.graph.as_ref().map(|graph| {
+            self.register_active_request(
+                request_id.clone(),
+                ActiveRequestAuthority {
+                    client: request.client.clone(),
+                    account_scope: Arc::clone(&authorization.account_scope),
+                    deadline_at: authorization.deadline_at,
+                    // 回收嵌套调用权限只取消子作用域，父请求仍需完成响应流终态加工。
+                    cancellation: authorization.cancellation.child_token(),
+                    extension_scope: authorization.extension_scope.clone(),
+                    graph: Arc::clone(graph),
+                },
+            )
+        });
+        Ok(ExecutionStartGuard {
+            admission,
+            active_request,
+            concurrency_wait_budget,
+            admission_decision_ms,
+        })
+    }
+
     async fn start_without_continuation(
         &self,
         request: PendingStartExecution,
-        request_id: ModelRequestId,
-        started_at: SystemTime,
-        deadline_at: SystemTime,
-        plan: crate::routing::RoutingPlan,
-        continuation: Option<ContinuationBinding>,
+        prepared: PreparedExecutionStart,
     ) -> Result<StartedExecution, GatewayError> {
+        let PreparedExecutionStart {
+            request_id,
+            started_at,
+            plan,
+            extensions,
+            authorization,
+            guard: start_guard,
+        } = prepared;
         let PendingStartExecution {
             client,
             target,
             operation,
             metadata,
         } = request;
-        let admission_started_at = Instant::now();
-        let concurrency_wait_budget = ConcurrencyWaitBudget::default();
-        let admission = self
-            .acquire_client_admission(&client, &request_id, deadline_at, &concurrency_wait_budget)
-            .await?;
-        let admission_decision_ms = duration_ms(admission_started_at.elapsed());
-        if let Some(budget) = &self.budget
-            && let Err(error) = budget.admit(client.policy.key_id().clone()).await
-        {
-            admission.release().await;
-            return Err(error);
-        }
+        let providers = self
+            .providers
+            .for_extensions(client.snapshot.extensions())
+            .map_err(|_| {
+                GatewayError::new(
+                    GatewayErrorKind::Internal,
+                    "provider generation is unavailable",
+                )
+            })?;
+        let ExecutionStartGuard {
+            admission,
+            active_request,
+            concurrency_wait_budget,
+            admission_decision_ms,
+        } = start_guard;
         let observation = plan
             .candidates()
             .first()
             .map_or_else(Default::default, |candidate| {
-                self.providers.request_observation(
+                providers.request_observation(
                     candidate.provider(),
                     &operation,
                     client.policy.key_id(),
                 )
             });
+        let (request_kind, subagent_kind) = if let Some(nested) = authorization.nested.as_ref() {
+            (
+                Some("plugin_child_model".to_owned()),
+                Some(nested.initiating_plugin_instance_id.clone()),
+            )
+        } else if let Some(bound) = authorization.bound.as_ref() {
+            (
+                Some("plugin_bound_model".to_owned()),
+                Some(bound.initiating_plugin_instance_id.clone()),
+            )
+        } else {
+            (observation.request_kind, observation.subagent_kind)
+        };
+        if let Some(nested) = authorization.nested.as_ref() {
+            tracing::debug!(
+                parent_request_id = nested.parent_request_id.as_str(),
+                child_request_id = request_id.as_str(),
+                plugin_instance_id = nested.initiating_plugin_instance_id,
+                depth = authorization.extension_scope.len(),
+                "插件子模型请求已继承父请求身份与 deadline"
+            );
+        }
         let new_request = NewModelRequest {
             id: request_id.clone(),
             client_api_key_id: Some(client.policy.key_id().clone()),
             client_api_key_ref: client.policy.key_id().clone(),
             config_revision: plan.config_revision(),
-            routing: client.policy.account_scope().routing_snapshot(),
+            routing: authorization.account_scope.routing_snapshot(),
             protocol: metadata.protocol,
             operation: operation.kind(),
             endpoint: metadata.endpoint,
@@ -566,24 +1387,25 @@ impl DefaultExecutionService {
             user_agent: metadata.user_agent,
             reasoning_effort: observation.reasoning_effort,
             reasoning_preset: observation.reasoning_preset,
-            request_kind: observation.request_kind,
-            subagent_kind: observation.subagent_kind,
+            request_kind,
+            subagent_kind,
             compact: observation.compact,
             continuation: observation.continuation,
             image_generation_requested: operation.image_generation_requested(),
-            admission_decision_ms: Some(admission_decision_ms),
+            admission_decision_ms,
             started_at,
-            deadline_at,
+            deadline_at: authorization.deadline_at,
         };
-        let core = match self
-            .coordinator
-            .start(
+        let coordinator =
+            AttemptCoordinator::new(GatewayEngine::new(self.observations.clone(), providers));
+        let core = match coordinator
+            .start_observed(
                 new_request,
                 operation,
                 plan,
-                None,
-                continuation,
-                CancellationToken::new(),
+                authorization.required_account,
+                extensions,
+                authorization.cancellation,
             )
             .await
         {
@@ -601,6 +1423,9 @@ impl DefaultExecutionService {
                     )
                     .await;
                 }
+                if let Some(active_request) = active_request {
+                    active_request.release();
+                }
                 admission.release().await;
                 return Err(gateway_error_from_engine(&error));
             }
@@ -612,6 +1437,7 @@ impl DefaultExecutionService {
             session: Box::new(DefaultExecutionSession::new(
                 core,
                 admission,
+                active_request,
                 Arc::clone(&self.circuits),
                 Arc::clone(&self.continuation),
                 self.budget.clone(),
@@ -619,6 +1445,346 @@ impl DefaultExecutionService {
         })
     }
 
+    fn register_active_request(
+        &self,
+        request_id: ModelRequestId,
+        authority: ActiveRequestAuthority,
+    ) -> ActiveRequestLease {
+        let authority = Arc::new(authority);
+        let mut active = self
+            .active_requests
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let previous = active.insert(request_id.clone(), Arc::downgrade(&authority));
+        debug_assert!(previous.is_none(), "model request IDs must be unique");
+        drop(active);
+        ActiveRequestLease {
+            registry: Arc::clone(&self.active_requests),
+            request_id,
+            authority,
+        }
+    }
+
+    fn active_request(
+        &self,
+        request_id: &ModelRequestId,
+    ) -> Result<Arc<ActiveRequestAuthority>, GatewayError> {
+        let authority = self
+            .active_requests
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .get(request_id)
+            .and_then(Weak::upgrade)
+            .ok_or_else(|| {
+                GatewayError::new(
+                    GatewayErrorKind::PolicyDenied,
+                    "parent model request is not active",
+                )
+            })?;
+        if authority.cancellation.is_cancelled() {
+            return Err(GatewayError::new(
+                GatewayErrorKind::Cancelled,
+                "parent request was cancelled",
+            ));
+        }
+        if authority
+            .deadline_at
+            .duration_since(SystemTime::now())
+            .unwrap_or_default()
+            .is_zero()
+        {
+            return Err(GatewayError::new(
+                GatewayErrorKind::Timeout,
+                "parent request deadline elapsed",
+            ));
+        }
+        Ok(authority)
+    }
+
+    async fn start_nested_inner(
+        &self,
+        request: NestedModelExecutionRequest,
+    ) -> Result<StartedExecution, GatewayError> {
+        let NestedModelExecutionRequest {
+            parent_request_id,
+            initiating_plugin_instance_id,
+            public_model,
+            operation,
+            mut metadata,
+            provider,
+            account,
+            parent_account,
+        } = request;
+        let parent = self.active_request(&parent_request_id)?;
+        if parent.extension_scope.len() >= MAX_NESTED_DEPTH {
+            return Err(GatewayError::new(
+                GatewayErrorKind::PolicyDenied,
+                "nested model execution depth is exhausted",
+            ));
+        }
+        let extension_scope = parent
+            .extension_scope
+            .extending(initiating_plugin_instance_id.clone())
+            .ok_or_else(|| {
+                GatewayError::new(
+                    GatewayErrorKind::PolicyDenied,
+                    "recursive plugin model execution is not allowed",
+                )
+            })?;
+        let (account_scope, required_provider) = restrict_model_execution_scope(
+            parent.account_scope.as_ref(),
+            provider,
+            account.as_ref(),
+            parent_account.as_ref(),
+        )?;
+        let nested_permit = parent.graph.acquire()?;
+        // Core.start 之后的路由/Provider 可以继续调用外部系统；在进入子执行前即按
+        // 可能已出站记水位，不能让父 attempt 随后的 `not_sent` 触发重放。
+        parent.graph.effects.observe();
+        let execution_effects_baseline = parent.graph.effects.epoch();
+        metadata.endpoint = "host.model".to_owned();
+        metadata.transport = ClientTransport::InternalPlugin;
+        metadata.client_ip = None;
+        metadata.user_agent = None;
+        let authorization = AuthorizedExecution {
+            account_scope,
+            deadline_at: parent.deadline_at,
+            cancellation: parent.cancellation.child_token(),
+            extension_scope,
+            required_provider,
+            required_account: account,
+            nested: Some(NestedExecutionFacts {
+                parent_request_id,
+                initiating_plugin_instance_id,
+            }),
+            bound: None,
+            graph: Some(Arc::clone(&parent.graph)),
+            execution_effects_baseline,
+            nested_permit: Some(nested_permit),
+        };
+        self.start_authorized(
+            PendingStartExecution {
+                client: parent.client.clone(),
+                target: ExecutionTarget::Model(public_model),
+                operation,
+                metadata,
+            },
+            authorization,
+            SystemTime::now(),
+            None,
+        )
+        .await
+    }
+
+    async fn client_for_key_id(
+        &self,
+        client_key_id: &ClientApiKeyId,
+    ) -> Result<AuthenticatedClient, GatewayError> {
+        if let Some(refresh) = &self.snapshot_refresh {
+            refresh.refresh().await.map_err(|_| {
+                GatewayError::new(
+                    GatewayErrorKind::Internal,
+                    "current runtime snapshot is unavailable",
+                )
+            })?;
+        }
+        let snapshot = self.snapshots.acquire().map_err(|_| {
+            GatewayError::new(
+                GatewayErrorKind::Internal,
+                "current runtime snapshot is unavailable",
+            )
+        })?;
+        let policy = snapshot
+            .client_policy(client_key_id)
+            .cloned()
+            .ok_or_else(|| {
+                GatewayError::new(
+                    GatewayErrorKind::Unauthorized,
+                    "client API key no longer exists",
+                )
+            })?;
+        policy.authorize().map_err(|_| {
+            GatewayError::new(GatewayErrorKind::PolicyDenied, "client API key is disabled")
+        })?;
+        Ok(AuthenticatedClient {
+            snapshot,
+            policy,
+            authentication: None,
+        })
+    }
+
+    async fn bind_bound_model_inner(
+        &self,
+        binding: BoundModelExecutionBinding,
+    ) -> Result<BoundModelExecutionContext, GatewayError> {
+        if binding.timeout.is_zero() {
+            return Err(GatewayError::new(
+                GatewayErrorKind::InvalidRequest,
+                "bound model execution timeout is invalid",
+            ));
+        }
+        let client = self.client_for_key_id(&binding.client_key_id).await?;
+        let deadline_at = SystemTime::now()
+            .checked_add(binding.timeout.min(MODEL_REQUEST_DEADLINE))
+            .ok_or_else(|| {
+                GatewayError::new(GatewayErrorKind::Internal, "system clock is invalid")
+            })?;
+        if binding.extension_scope.len() >= MAX_NESTED_DEPTH {
+            return Err(GatewayError::new(
+                GatewayErrorKind::PolicyDenied,
+                "plugin model execution depth exceeded",
+            ));
+        }
+        let extension_scope = binding
+            .extension_scope
+            .extending(binding.initiating_plugin_instance_id.clone())
+            .ok_or_else(|| {
+                GatewayError::new(
+                    GatewayErrorKind::Internal,
+                    "bound plugin execution scope is invalid",
+                )
+            })?;
+        let account_scope = Arc::clone(client.policy.account_scope());
+        Ok(BoundModelExecutionContext {
+            authority: Arc::new(BoundModelExecutionAuthority {
+                client,
+                account_scope,
+                deadline_at,
+                cancellation: binding.cancellation,
+                extension_scope,
+                graph: Arc::new(NestedExecutionGraph::new(Arc::new(
+                    ExecutionEffects::default(),
+                ))),
+                initiating_plugin_instance_id: binding.initiating_plugin_instance_id,
+            }),
+        })
+    }
+
+    async fn start_bound_model_inner(
+        &self,
+        request: BoundModelExecutionRequest,
+    ) -> Result<StartedExecution, GatewayError> {
+        let BoundModelExecutionRequest {
+            context,
+            public_model,
+            operation,
+            mut metadata,
+            provider,
+            account,
+        } = request;
+        let authority = &context.authority;
+        if authority.cancellation.is_cancelled() {
+            return Err(GatewayError::new(
+                GatewayErrorKind::Cancelled,
+                "bound plugin invocation was cancelled",
+            ));
+        }
+        if authority
+            .deadline_at
+            .duration_since(SystemTime::now())
+            .unwrap_or_default()
+            .is_zero()
+        {
+            return Err(GatewayError::new(
+                GatewayErrorKind::Timeout,
+                "bound plugin invocation deadline elapsed",
+            ));
+        }
+        let (account_scope, required_provider) = restrict_model_execution_scope(
+            authority.account_scope.as_ref(),
+            provider,
+            account.as_ref(),
+            None,
+        )?;
+        let permit = authority.graph.acquire()?;
+        let execution_effects_baseline = authority.graph.effects.epoch();
+        metadata.endpoint = "host.model".to_owned();
+        metadata.transport = ClientTransport::InternalPlugin;
+        metadata.client_ip = None;
+        metadata.user_agent = None;
+        self.client_api_key_usage
+            .record_used(authority.client.policy.key_id());
+        self.start_authorized(
+            PendingStartExecution {
+                client: authority.client.clone(),
+                target: ExecutionTarget::Model(public_model),
+                operation,
+                metadata,
+            },
+            AuthorizedExecution {
+                account_scope,
+                deadline_at: authority.deadline_at,
+                cancellation: authority.cancellation.child_token(),
+                extension_scope: authority.extension_scope.clone(),
+                required_provider,
+                required_account: account,
+                nested: None,
+                bound: Some(BoundExecutionFacts {
+                    initiating_plugin_instance_id: authority.initiating_plugin_instance_id.clone(),
+                }),
+                graph: Some(Arc::clone(&authority.graph)),
+                execution_effects_baseline,
+                nested_permit: Some(permit),
+            },
+            SystemTime::now(),
+            None,
+        )
+        .await
+    }
+
+    async fn lookup_affinity_inner(
+        &self,
+        request: AffinityLookupRequest,
+    ) -> Result<Option<AffinityLookupResult>, GatewayError> {
+        let AffinityLookupRequest {
+            parent_request_id,
+            provider,
+            key,
+        } = request;
+        let parent = self.active_request(&parent_request_id)?;
+        if !parent.account_scope.provider_kinds().contains(&provider) {
+            return Err(GatewayError::new(
+                GatewayErrorKind::PolicyDenied,
+                "affinity provider is outside the frozen authorization scope",
+            ));
+        }
+        let affinity = self.session_affinity.as_ref().ok_or_else(|| {
+            GatewayError::new(
+                GatewayErrorKind::PolicyDenied,
+                "provider session affinity is unavailable",
+            )
+        })?;
+        let account = {
+            let load = affinity.load(&provider, &key).fuse();
+            let timeout = Delay::new(COORDINATION_TIMEOUT).fuse();
+            pin_mut!(load, timeout);
+            select_biased! {
+                result = load => result.map_err(|error| match error.kind() {
+                    ProviderStoreErrorKind::Unavailable => GatewayError::new(
+                        GatewayErrorKind::ProviderInfrastructureUnavailable,
+                        "provider session affinity is temporarily unavailable",
+                    ),
+                    ProviderStoreErrorKind::InvalidData | ProviderStoreErrorKind::Conflict => {
+                        GatewayError::new(GatewayErrorKind::Internal, "provider session affinity is invalid")
+                    }
+                })?,
+                _ = timeout => return Err(GatewayError::new(
+                    GatewayErrorKind::ProviderInfrastructureUnavailable,
+                    "provider session affinity lookup timed out",
+                )),
+            }
+        };
+        let Some(account) = account else {
+            return Ok(None);
+        };
+        if !parent.account_scope.allows(&account)
+            || parent.account_scope.account_provider(&account) != Some(&provider)
+        {
+            return Ok(None);
+        }
+        Ok(Some(AffinityLookupResult::new(provider, account)))
+    }
+
     async fn acquire_client_admission(
         &self,
         client: &AuthenticatedClient,
@@ -743,6 +1909,7 @@ impl DefaultExecutionService {
     async fn probe_inner(
         &self,
         request: AccountProbeRequest,
+        frozen: Option<Arc<crate::routing::RuntimeSnapshot>>,
     ) -> Result<AccountProbeResult, AccountProbeError> {
         let AccountProbeRequest {
             account_id,
@@ -755,12 +1922,14 @@ impl DefaultExecutionService {
             account_id: account_id.clone(),
             upstream_model: upstream_model.clone(),
         };
-        let snapshot = self.snapshots.acquire().map_err(|_| {
-            GatewayError::new(
-                GatewayErrorKind::Internal,
-                "runtime snapshot is unavailable",
-            )
-        })?;
+        let snapshot = frozen
+            .map_or_else(|| self.snapshots.acquire(), Ok)
+            .map_err(|_| {
+                GatewayError::new(
+                    GatewayErrorKind::Internal,
+                    "runtime snapshot is unavailable",
+                )
+            })?;
         let public_model =
             PublicModelId::new(upstream_model.as_str().to_owned()).map_err(|_| {
                 GatewayError::new(GatewayErrorKind::Unsupported, "requested model is invalid")
@@ -770,12 +1939,7 @@ impl DefaultExecutionService {
             ..RoutingContext::default()
         };
         let plan = snapshot
-            .plan(
-                &public_model,
-                &operation,
-                snapshot.all_account_scope(),
-                &routing_context,
-            )
+            .plan_diagnostic(&public_model, &operation, &routing_context)
             .map_err(map_routing_error)?;
         let started_at = SystemTime::now();
         let deadline_at = started_at
@@ -810,8 +1974,18 @@ impl DefaultExecutionService {
             started_at,
             deadline_at,
         };
-        let mut session = match self
-            .probe_coordinator
+        let providers = self
+            .providers
+            .for_extensions(snapshot.extensions())
+            .map_err(|_| {
+                GatewayError::new(
+                    GatewayErrorKind::Internal,
+                    "provider generation is unavailable",
+                )
+            })?;
+        let transient: Arc<dyn ExecutionStore> = Arc::new(TransientExecutionStore);
+        let coordinator = AttemptCoordinator::new(GatewayEngine::new(transient, providers));
+        let mut session = match coordinator
             .start_diagnostic(
                 new_request,
                 operation,
@@ -993,6 +2167,25 @@ impl ExecutionService for DefaultExecutionService {
         Ok(client)
     }
 
+    fn authenticate_request(
+        &self,
+        request: ClientAuthenticationRequest,
+    ) -> BoxFuture<'_, Result<AuthenticatedClient, ClientAuthenticationError>> {
+        Box::pin(async move {
+            let client = self.authenticate_request_without_usage(request).await?;
+            self.client_api_key_usage
+                .record_used(client.policy().key_id());
+            Ok(client)
+        })
+    }
+
+    fn verify_request(
+        &self,
+        request: ClientAuthenticationRequest,
+    ) -> BoxFuture<'_, Result<AuthenticatedClient, ClientAuthenticationError>> {
+        Box::pin(self.authenticate_request_without_usage(request))
+    }
+
     fn public_models(&self, client: &AuthenticatedClient) -> Vec<PublicModelId> {
         client
             .snapshot
@@ -1007,10 +2200,14 @@ impl ExecutionService for DefaultExecutionService {
     ) -> BoxFuture<'a, Result<Vec<PublicModelDescriptor>, ProviderCatalogUnavailable>> {
         Box::pin(async move {
             let scope = client.policy.account_scope();
+            let providers = self
+                .providers
+                .for_extensions(client.snapshot.extensions())
+                .map_err(|_| ProviderCatalogUnavailable)?;
             let mut result = Vec::new();
             let mut seen = BTreeSet::new();
             for kind in scope.provider_kinds() {
-                let provider = self.providers.get(kind).ok_or(ProviderCatalogUnavailable)?;
+                let provider = providers.get(kind).ok_or(ProviderCatalogUnavailable)?;
                 let Some(models) = provider
                     .query_client_model_catalog(scope, protocol, client_version)
                     .await?
@@ -1084,6 +2281,69 @@ impl ExecutionService for DefaultExecutionService {
             .contains_public_model_for_scope(model, client.policy.account_scope())
     }
 
+    fn prepare_execution(
+        &self,
+        client: AuthenticatedClient,
+    ) -> BoxFuture<'_, Result<PreparedRootExecution, GatewayError>> {
+        Box::pin(async move { self.prepare_root_execution_inner(client).await })
+    }
+
+    fn middleware_plan(&self, prepared: &PreparedRootExecution) -> Option<FrozenMiddlewarePlan> {
+        let generation = prepared.client.snapshot.extensions()?.clone();
+        self.middlewares.as_ref()?.resolve(&generation)
+    }
+
+    fn prepare_plugin_execution(
+        &self,
+        client_key_id: &ClientApiKeyId,
+    ) -> BoxFuture<'_, Result<PreparedRootExecution, GatewayError>> {
+        let client_key_id = client_key_id.clone();
+        Box::pin(async move {
+            let client = self.client_for_key_id(&client_key_id).await?;
+            self.client_api_key_usage
+                .record_used(client.policy.key_id());
+            PreparedRootExecution::new(client)
+        })
+    }
+
+    fn start_prepared(
+        &self,
+        prepared: PreparedRootExecution,
+        request: PreparedExecutionRequest,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async move {
+            self.start_prepared_with_target(
+                prepared,
+                ExecutionTarget::Model(request.public_model),
+                request.operation,
+                request.metadata,
+            )
+            .await
+        })
+    }
+
+    fn start_prepared_provider_endpoint(
+        &self,
+        prepared: PreparedRootExecution,
+        provider: ProviderKind,
+        upstream_model: Option<UpstreamModelId>,
+        operation: Operation,
+        metadata: ExecutionRequestMetadata,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async move {
+            self.start_prepared_with_target(
+                prepared,
+                ExecutionTarget::ProviderEndpoint {
+                    provider,
+                    upstream_model,
+                },
+                operation,
+                metadata,
+            )
+            .await
+        })
+    }
+
     fn start(
         &self,
         request: StartExecution,
@@ -1099,6 +2359,71 @@ impl ExecutionService for DefaultExecutionService {
     }
 }
 
+impl NestedModelExecutionPort for DefaultExecutionService {
+    fn models(
+        &self,
+        context: BoundModelExecutionContext,
+        protocol: String,
+        client_version: String,
+    ) -> BoxFuture<'_, Result<Vec<PublicModelId>, GatewayError>> {
+        Box::pin(async move {
+            let authority = &context.authority;
+            let remaining = authority
+                .deadline_at
+                .duration_since(SystemTime::now())
+                .unwrap_or_default();
+            let cancellation = authority.cancellation.cancelled().fuse();
+            let timeout = Delay::new(remaining).fuse();
+            let catalog = self
+                .client_model_catalog(&authority.client, &protocol, &client_version)
+                .fuse();
+            pin_mut!(cancellation, timeout, catalog);
+            let models = select_biased! {
+                () = cancellation => return Err(GatewayError::new(GatewayErrorKind::Cancelled, "model catalog call was cancelled")),
+                () = timeout => return Err(GatewayError::new(GatewayErrorKind::Timeout, "model catalog deadline elapsed")),
+                result = catalog => result.map_err(|_| GatewayError::new(GatewayErrorKind::Internal, "model catalog is unavailable"))?,
+            };
+            Ok(models
+                .into_iter()
+                .map(|model| match model {
+                    PublicModelDescriptor::Native { model, .. } => model,
+                    PublicModelDescriptor::Adapted(profile) => profile.model().clone(),
+                })
+                .collect())
+        })
+    }
+
+    fn bind(
+        &self,
+        binding: BoundModelExecutionBinding,
+    ) -> BoxFuture<'_, Result<BoundModelExecutionContext, GatewayError>> {
+        Box::pin(async move { self.bind_bound_model_inner(binding).await })
+    }
+
+    fn start(
+        &self,
+        request: NestedModelExecutionRequest,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async move { self.start_nested_inner(request).await })
+    }
+
+    fn start_bound(
+        &self,
+        request: BoundModelExecutionRequest,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async move { self.start_bound_model_inner(request).await })
+    }
+}
+
+impl AffinityLookupPort for DefaultExecutionService {
+    fn lookup(
+        &self,
+        request: AffinityLookupRequest,
+    ) -> BoxFuture<'_, Result<Option<AffinityLookupResult>, GatewayError>> {
+        Box::pin(async move { self.lookup_affinity_inner(request).await })
+    }
+}
+
 impl ClientKeyVerifier for DefaultExecutionService {
     fn verify_client_key(
         &self,
@@ -1113,8 +2438,9 @@ impl AccountProbe for DefaultExecutionService {
     fn probe(
         &self,
         request: AccountProbeRequest,
+        snapshot: Option<Arc<crate::routing::RuntimeSnapshot>>,
     ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>> {
-        Box::pin(async move { self.probe_inner(request).await })
+        Box::pin(async move { self.probe_inner(request, snapshot).await })
     }
 }
 
@@ -1153,9 +2479,55 @@ impl Drop for AdmissionLease {
     }
 }
 
+enum ExecutionAdmission {
+    Client(AdmissionLease),
+    Nested(NestedExecutionPermit),
+    Bound(AdmissionLease, NestedExecutionPermit),
+}
+
+impl ExecutionAdmission {
+    async fn release(self) {
+        match self {
+            Self::Client(admission) => admission.release().await,
+            Self::Nested(permit) => permit.release(),
+            Self::Bound(admission, permit) => {
+                admission.release().await;
+                permit.release();
+            }
+        }
+    }
+}
+
+impl ExecutionStartGuard {
+    async fn release_failed(
+        self,
+        budget: Option<&dyn ClientBudgetPort>,
+        request_id: ModelRequestId,
+        key_id: ClientApiKeyId,
+    ) {
+        if let Some(active_request) = self.active_request {
+            active_request.release();
+        }
+        if let Some(budget) = budget {
+            settle_budget(
+                budget,
+                ClientBudgetCharge {
+                    key_id,
+                    request_id,
+                    amount_usd: crate::metering::Decimal::ZERO,
+                    completed_at: SystemTime::now(),
+                },
+            )
+            .await;
+        }
+        self.admission.release().await;
+    }
+}
+
 struct DefaultExecutionSession {
     core: ResponseExecutionSession<dyn ExecutionStore>,
-    admission: Option<AdmissionLease>,
+    admission: Option<ExecutionAdmission>,
+    active_request: Option<ActiveRequestLease>,
     cleanup: Option<BoxFuture<'static, ()>>,
     circuits: Arc<dyn ProviderCircuitPort>,
     continuation: Arc<dyn NativeContinuationPort>,
@@ -1167,7 +2539,8 @@ struct DefaultExecutionSession {
 impl DefaultExecutionSession {
     fn new(
         core: ResponseExecutionSession<dyn ExecutionStore>,
-        admission: AdmissionLease,
+        admission: ExecutionAdmission,
+        active_request: Option<ActiveRequestLease>,
         circuits: Arc<dyn ProviderCircuitPort>,
         continuation: Arc<dyn NativeContinuationPort>,
         budget: Option<Arc<dyn ClientBudgetPort>>,
@@ -1175,6 +2548,7 @@ impl DefaultExecutionSession {
         Self {
             core,
             admission: Some(admission),
+            active_request,
             cleanup: None,
             circuits,
             continuation,
@@ -1188,6 +2562,9 @@ impl DefaultExecutionSession {
         if self.core.is_finalized()
             && let Some(admission) = self.admission.take()
         {
+            if let Some(active_request) = self.active_request.take() {
+                active_request.release();
+            }
             let budget = self.budget.take();
             let charge = self.core.budget_charge();
             // 在首次 await 前把完整清理责任留在会话内。事件等待被取消后，后续 poll
@@ -1241,6 +2618,7 @@ impl DefaultExecutionSession {
 impl Drop for DefaultExecutionSession {
     fn drop(&mut self) {
         self.core.cancel();
+        drop(self.active_request.take());
     }
 }
 
@@ -1281,6 +2659,10 @@ impl ExecutionSession for DefaultExecutionSession {
         self.core.response_status_code()
     }
 
+    fn discard_pending_delivery(&mut self) -> Result<(), EngineError> {
+        self.core.discard_pending_delivery()
+    }
+
     fn commit_downstream(
         &mut self,
         client_status_code: Option<u16>,
@@ -1306,7 +2688,10 @@ impl ExecutionSession for DefaultExecutionSession {
     }
 
     fn is_finalized(&self) -> bool {
-        self.core.is_finalized() && self.admission.is_none() && self.cleanup.is_none()
+        self.core.is_finalized()
+            && self.admission.is_none()
+            && self.active_request.is_none()
+            && self.cleanup.is_none()
     }
 
     fn cancel(&self) {
@@ -1394,6 +2779,87 @@ fn constant_time_equal(left: &str, right: &str) -> bool {
         == 0
 }
 
+fn restrict_model_execution_scope(
+    parent_scope: &FrozenAccountScope,
+    provider: Option<ProviderKind>,
+    account: Option<&ProviderAccountId>,
+    parent_account: Option<&ProviderAccountId>,
+) -> Result<(Arc<FrozenAccountScope>, Option<ProviderKind>), GatewayError> {
+    let mut account_scope = parent_scope.clone();
+    if let Some(parent_account) = parent_account {
+        if !parent_scope.allows(parent_account) {
+            return Err(GatewayError::new(
+                GatewayErrorKind::PolicyDenied,
+                "parent attempt account is outside the frozen account scope",
+            ));
+        }
+        if account == Some(parent_account) {
+            return Err(GatewayError::new(
+                GatewayErrorKind::PolicyDenied,
+                "nested execution cannot wait for the parent attempt account",
+            ));
+        }
+        account_scope = account_scope.excluding_account(parent_account.clone());
+    }
+    let required_provider = match account {
+        Some(account) => {
+            if !account_scope.allows(account) {
+                return Err(GatewayError::new(
+                    GatewayErrorKind::PolicyDenied,
+                    "model account is outside the frozen authorization scope",
+                ));
+            }
+            let account_provider = account_scope
+                .account_provider(account)
+                .cloned()
+                .ok_or_else(|| {
+                    GatewayError::new(
+                        GatewayErrorKind::PolicyDenied,
+                        "model account is unavailable in the frozen snapshot",
+                    )
+                })?;
+            if provider
+                .as_ref()
+                .is_some_and(|provider| provider != &account_provider)
+            {
+                return Err(GatewayError::new(
+                    GatewayErrorKind::PolicyDenied,
+                    "model provider and account do not match",
+                ));
+            }
+            Some(account_provider)
+        }
+        None => provider,
+    };
+    if required_provider
+        .as_ref()
+        .is_some_and(|provider| !account_scope.provider_kinds().contains(provider))
+        || account_scope.provider_kinds().is_empty()
+    {
+        return Err(GatewayError::new(
+            GatewayErrorKind::PolicyDenied,
+            "model provider is outside the frozen authorization scope",
+        ));
+    }
+    Ok((Arc::new(account_scope), required_provider))
+}
+
+fn native_policy(
+    snapshot: &RuntimeSnapshot,
+    authentication: &ClientAuthenticationRequest,
+) -> Result<ClientPolicy, ClientAuthenticationError> {
+    let plaintext = authentication
+        .native_bearer()
+        .ok_or(ClientAuthenticationError::InvalidKey)?
+        .expose_for_auth();
+    snapshot
+        .client_policies()
+        .filter(|policy| constant_time_equal(plaintext, policy.plaintext_key().expose_for_auth()))
+        .find(|policy| policy.authorize().is_ok())
+        .cloned()
+        .ok_or(ClientAuthenticationError::InvalidKey)
+}
+
 fn duration_ms(duration: Duration) -> u64 {
     u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
 }
@@ -1403,6 +2869,22 @@ fn new_request_id() -> Result<ModelRequestId, GatewayError> {
         .map_err(|_| GatewayError::new(GatewayErrorKind::Internal, "failed to allocate request ID"))
 }
 
+fn authentication_gateway_error(error: ClientAuthenticationError) -> GatewayError {
+    match error {
+        ClientAuthenticationError::InvalidKey => {
+            GatewayError::new(GatewayErrorKind::Unauthorized, "client API key is invalid")
+        }
+        ClientAuthenticationError::SnapshotUnavailable => GatewayError::new(
+            GatewayErrorKind::Internal,
+            "runtime snapshot is unavailable",
+        ),
+        ClientAuthenticationError::ProviderUnavailable => GatewayError::new(
+            GatewayErrorKind::Internal,
+            "frontend authentication provider is unavailable",
+        ),
+    }
+}
+
 fn map_routing_error(error: crate::validation::RoutingError) -> GatewayError {
     match error {
         crate::validation::RoutingError::ModelNotFound {
@@ -1422,6 +2904,10 @@ fn map_routing_error(error: crate::validation::RoutingError) -> GatewayError {
             GatewayErrorKind::NoAvailableProvider,
             "no provider can execute this request",
         ),
+        crate::validation::RoutingError::UnsupportedProviderEndpoint { .. } => GatewayError::new(
+            GatewayErrorKind::Unsupported,
+            "the selected provider does not support this operation",
+        ),
         _ => GatewayError::new(
             GatewayErrorKind::Internal,
             "runtime routing configuration is invalid",
diff --git a/backend/crates/gateway-core/src/engine/extensions.rs b/backend/crates/gateway-core/src/engine/extensions.rs
new file mode 100644
index 000000000..c7f504564
--- /dev/null
+++ b/backend/crates/gateway-core/src/engine/extensions.rs
@@ -0,0 +1,104 @@
+//! 执行器按发布集合查找；索引不持有当前代次，也不延长旧代次寿命。
+
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    sync::{Arc, RwLock, Weak},
+};
+
+use crate::{identity::ProviderKind, runtime::extensions::ExtensionSetId};
+
+use super::provider::{Provider, ProviderRegistry, RegistryError};
+
+/// 一次请求已经进入过的插件实例集合。
+///
+/// Core 把它随子请求传播给 Provider、策略与观察边界；Runtime 只据此跳过对应
+/// 实例，不能自行扩大授权或改变路由。集合同时用于拒绝 A → B → A 间接递归。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ExtensionCallScope {
+    instance_ids: Arc<BTreeSet<String>>,
+}
+
+impl ExtensionCallScope {
+    #[must_use]
+    pub fn contains(&self, instance_id: &str) -> bool {
+        self.instance_ids.contains(instance_id)
+    }
+
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.instance_ids.len()
+    }
+
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.instance_ids.is_empty()
+    }
+
+    /// 返回加入当前发起实例后的新作用域；重复实例表示间接递归。
+    #[must_use]
+    pub fn extending(&self, instance_id: String) -> Option<Self> {
+        if self.contains(&instance_id) {
+            return None;
+        }
+        let mut instance_ids = self.instance_ids.as_ref().clone();
+        instance_ids.insert(instance_id);
+        Some(Self {
+            instance_ids: Arc::new(instance_ids),
+        })
+    }
+}
+
+#[derive(Clone)]
+pub struct ProviderExtensionIndex {
+    base: Arc<BTreeMap<ProviderKind, Arc<dyn Provider>>>,
+    sets: Arc<RwLock<BTreeMap<ExtensionSetId, Weak<ProviderRegistry>>>>,
+}
+
+impl ProviderExtensionIndex {
+    #[must_use]
+    pub fn new(base: ProviderRegistry) -> Self {
+        Self {
+            base: base.providers,
+            sets: Arc::default(),
+        }
+    }
+
+    /// 准备阶段检查原生与插件身份冲突；返回值由候选集合保活。
+    pub fn register(
+        &self,
+        id: ExtensionSetId,
+        providers: impl IntoIterator<Item = Arc<dyn Provider>>,
+    ) -> Result<Arc<ProviderRegistry>, RegistryError> {
+        let registry = Arc::new(ProviderRegistry::new(
+            self.base.values().cloned().chain(providers),
+        )?);
+        let mut sets = self
+            .sets
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        sets.retain(|_, set| set.strong_count() > 0);
+        if sets.contains_key(&id) {
+            return Err(RegistryError::DuplicateGeneration);
+        }
+        sets.insert(id, Arc::downgrade(&registry));
+        Ok(registry)
+    }
+
+    /// 组合根使用的解析入口；请求仍须显式提供冻结的集合引用。
+    #[must_use]
+    pub fn registry(&self) -> ProviderRegistry {
+        ProviderRegistry {
+            providers: self.base.clone(),
+            extensions: Some(self.clone()),
+            lease: None,
+        }
+    }
+
+    pub(super) fn resolve(&self, id: &ExtensionSetId) -> Option<Arc<ProviderRegistry>> {
+        self.sets
+            .read()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .get(id)
+            .and_then(Weak::upgrade)
+    }
+}
diff --git a/backend/crates/gateway-core/src/engine/middleware.rs b/backend/crates/gateway-core/src/engine/middleware.rs
new file mode 100644
index 000000000..066bfff5a
--- /dev/null
+++ b/backend/crates/gateway-core/src/engine/middleware.rs
@@ -0,0 +1,728 @@
+//! 数据面请求/响应的统一洋葱中间件端口。
+//!
+//! 本模块只承载宿主内部组合合同。插件 RPC 如何表示 `next` 和正文句柄由
+//! Runtime/SDK 负责；身份、路由、账号租约、发送事实、重试、计量与结算仍由 Core
+//! 持有，不能通过本端口交给插件解释。
+
+use std::collections::BTreeMap;
+use std::fmt;
+use std::num::NonZeroU32;
+use std::sync::{Arc, RwLock, Weak};
+use std::time::SystemTime;
+
+use bytes::Bytes;
+use futures::future::BoxFuture;
+
+use crate::account::{ProviderAccountId, scope::AccountGroupId};
+use crate::engine::execution::ClientTransport;
+use crate::engine::extensions::ExtensionCallScope;
+use crate::engine::nested::ExecutionEffects;
+use crate::engine::provider::ProviderCallMetadata;
+use crate::engine::{EngineError, ModelRequestId};
+use crate::error::{GatewayError, ProviderError};
+use crate::event::ProviderEvent;
+use crate::identity::ProviderKind;
+use crate::lifecycle::CancellationToken;
+use crate::operation::OperationKind;
+use crate::policy::ClientApiKeyId;
+use crate::runtime::extensions::{ExtensionSetId, ExtensionSetReference};
+
+/// 中间件在一次逻辑请求中的挂载位置。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MiddlewareMount {
+    /// 客户端请求外层；一次逻辑请求只执行一次。
+    Request,
+    /// 受管 Provider attempt 内层；每次真实 retry 都重新建立。
+    Attempt,
+}
+
+/// 中间件正文块的宿主边界。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MiddlewareFraming {
+    /// 一个完整 JSON document。
+    JsonDocument,
+    /// 一个完整 SSE event，包含终止该事件的空行。
+    SseEvent,
+    /// 不承诺 UTF-8 或消息边界的原始字节。
+    RawBytes,
+}
+
+/// 允许进入中间件合同的多值 HTTP 头。
+#[derive(Clone, PartialEq, Eq)]
+pub struct MiddlewareHeader {
+    name: String,
+    value: Bytes,
+}
+
+impl MiddlewareHeader {
+    #[must_use]
+    pub fn new(name: impl Into<String>, value: Bytes) -> Self {
+        Self {
+            name: name.into(),
+            value,
+        }
+    }
+
+    #[must_use]
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    #[must_use]
+    pub const fn value(&self) -> &Bytes {
+        &self.value
+    }
+
+    #[must_use]
+    pub fn into_parts(self) -> (String, Bytes) {
+        (self.name, self.value)
+    }
+}
+
+impl fmt::Debug for MiddlewareHeader {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("MiddlewareHeader")
+            .field("name", &self.name)
+            .field("value", &"<not included in Debug>")
+            .finish()
+    }
+}
+
+/// 一次中间件调用可修改的请求事实。
+#[derive(Clone, PartialEq, Eq)]
+pub struct MiddlewareRequest {
+    protocol: String,
+    headers: Vec<MiddlewareHeader>,
+    body: Bytes,
+}
+
+impl MiddlewareRequest {
+    #[must_use]
+    pub fn new(protocol: impl Into<String>, headers: Vec<MiddlewareHeader>, body: Bytes) -> Self {
+        Self {
+            protocol: protocol.into(),
+            headers,
+            body,
+        }
+    }
+
+    #[must_use]
+    pub fn protocol(&self) -> &str {
+        &self.protocol
+    }
+
+    #[must_use]
+    pub fn headers(&self) -> &[MiddlewareHeader] {
+        &self.headers
+    }
+
+    #[must_use]
+    pub const fn body(&self) -> &Bytes {
+        &self.body
+    }
+
+    #[must_use]
+    pub fn into_parts(self) -> (String, Vec<MiddlewareHeader>, Bytes) {
+        (self.protocol, self.headers, self.body)
+    }
+}
+
+impl fmt::Debug for MiddlewareRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("MiddlewareRequest")
+            .field("protocol", &self.protocol)
+            .field("headers", &self.headers)
+            .field("body", &"<not included in Debug>")
+            .finish()
+    }
+}
+
+/// 中间件逐次拉取的完整正文边界。
+pub struct MiddlewareFrame {
+    bytes: Bytes,
+    framing: MiddlewareFraming,
+    terminal: bool,
+    transformed: bool,
+    envelope: Option<MiddlewareFrameEnvelope>,
+}
+
+impl MiddlewareFrame {
+    #[must_use]
+    pub const fn new(bytes: Bytes, framing: MiddlewareFraming, terminal: bool) -> Self {
+        Self {
+            bytes,
+            framing,
+            terminal,
+            transformed: false,
+            envelope: None,
+        }
+    }
+
+    #[must_use]
+    pub const fn bytes(&self) -> &Bytes {
+        &self.bytes
+    }
+
+    #[must_use]
+    pub const fn framing(&self) -> MiddlewareFraming {
+        self.framing
+    }
+
+    #[must_use]
+    pub const fn terminal(&self) -> bool {
+        self.terminal
+    }
+
+    /// 返回正文是否经过至少一个中间件的替换、展开或丢弃映射。
+    ///
+    /// 该事实只在宿主进程内传播，不进入插件 RPC wire，插件不能自行伪造。
+    #[must_use]
+    pub const fn transformed(&self) -> bool {
+        self.transformed
+    }
+
+    /// 继承宿主确认的改写事实；`false` 不能清除内层已经记录的改写。
+    #[must_use]
+    pub fn with_transformed(mut self, transformed: bool) -> Self {
+        self.transformed |= transformed;
+        self
+    }
+
+    #[must_use]
+    pub fn into_bytes(self) -> Bytes {
+        self.bytes
+    }
+
+    /// 拆出插件可见正文与只能由宿主原样搬运的事实信封。
+    ///
+    /// Runtime 在一对多转换时必须把信封附到最后一个输出；这样 `Completed` 不会在
+    /// 前置输出交付前提前终结。信封不能被读取、序列化、复制或伪造。
+    #[must_use]
+    pub fn into_parts(
+        self,
+    ) -> (
+        Bytes,
+        MiddlewareFraming,
+        bool,
+        Option<MiddlewareFrameEnvelope>,
+    ) {
+        (self.bytes, self.framing, self.terminal, self.envelope)
+    }
+
+    /// 把宿主持有的事实信封附到改写后的最后一个输出。
+    #[must_use]
+    pub fn with_envelope(mut self, envelope: MiddlewareFrameEnvelope) -> Self {
+        self.envelope = Some(envelope);
+        self
+    }
+
+    pub(crate) fn from_provider_event(
+        bytes: Bytes,
+        framing: MiddlewareFraming,
+        terminal: bool,
+        event: ProviderEvent,
+    ) -> Self {
+        let transformed = event.middleware_transformed();
+        Self {
+            bytes,
+            framing,
+            terminal,
+            transformed,
+            envelope: Some(MiddlewareFrameEnvelope { event }),
+        }
+    }
+
+    pub(crate) fn into_provider_parts(
+        self,
+    ) -> (Bytes, MiddlewareFraming, bool, Option<ProviderEvent>) {
+        (
+            self.bytes,
+            self.framing,
+            self.terminal,
+            self.envelope.map(|envelope| envelope.event),
+        )
+    }
+}
+
+impl fmt::Debug for MiddlewareFrame {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("MiddlewareFrame")
+            .field("bytes", &"<not included in Debug>")
+            .field("framing", &self.framing)
+            .field("terminal", &self.terminal)
+            .field("transformed", &self.transformed)
+            .field("has_host_envelope", &self.envelope.is_some())
+            .finish()
+    }
+}
+
+/// Runtime 可移动但不能检查或构造的 Core 事实信封。
+///
+/// 该类型故意不实现 `Clone`，防止同一 usage/cost 在一对多响应中被复制。
+pub struct MiddlewareFrameEnvelope {
+    event: ProviderEvent,
+}
+
+impl fmt::Debug for MiddlewareFrameEnvelope {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("MiddlewareFrameEnvelope")
+            .finish_non_exhaustive()
+    }
+}
+
+/// 洋葱返回路径上的惰性正文。
+///
+/// 实现必须让 `Drop` 与 [`Self::close`] 都回收底层流。请求 finalization 继续委托
+/// 原有 [`crate::engine::execution::ExecutionSession`]，本端口不建立第二套清理器。
+pub trait MiddlewareBody: Send {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>>;
+
+    /// 在最外层输出准备完成后提交原有 Core delivery barrier。中间件实现只能向内委托。
+    fn commit_downstream(
+        &mut self,
+        _client_status_code: Option<u16>,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        Box::pin(async { Ok(()) })
+    }
+
+    /// 首字节前失败时记录最终返回给客户端的状态。中间件实现只能向内委托。
+    fn record_client_status(
+        &mut self,
+        _client_status_code: u16,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        Box::pin(async { Ok(()) })
+    }
+
+    /// 没有调用 `next` 的短路正文视为无需 Core 结算；调用过 `next` 的包装器必须委托。
+    fn is_finalized(&self) -> bool {
+        true
+    }
+
+    fn close(self: Box<Self>) -> BoxFuture<'static, ()>;
+}
+
+/// `next` 或短路返回的响应头与惰性正文。
+pub struct MiddlewareResponse {
+    protocol: String,
+    status_code: u16,
+    headers: Vec<MiddlewareHeader>,
+    body: Box<dyn MiddlewareBody>,
+    envelope: Option<MiddlewareResponseEnvelope>,
+}
+
+impl MiddlewareResponse {
+    #[must_use]
+    pub fn new(
+        protocol: String,
+        status_code: u16,
+        headers: Vec<MiddlewareHeader>,
+        body: Box<dyn MiddlewareBody>,
+    ) -> Self {
+        Self {
+            protocol,
+            status_code,
+            headers,
+            body,
+            envelope: None,
+        }
+    }
+
+    #[must_use]
+    pub fn protocol(&self) -> &str {
+        &self.protocol
+    }
+
+    #[must_use]
+    pub const fn status_code(&self) -> u16 {
+        self.status_code
+    }
+
+    #[must_use]
+    pub fn headers(&self) -> &[MiddlewareHeader] {
+        &self.headers
+    }
+
+    #[must_use]
+    pub fn into_parts(
+        self,
+    ) -> (
+        String,
+        u16,
+        Vec<MiddlewareHeader>,
+        Box<dyn MiddlewareBody>,
+        Option<MiddlewareResponseEnvelope>,
+    ) {
+        (
+            self.protocol,
+            self.status_code,
+            self.headers,
+            self.body,
+            self.envelope,
+        )
+    }
+
+    /// 搬运宿主 terminal 的不透明来源事实；Runtime 不得序列化或自行构造。
+    #[must_use]
+    pub fn with_envelope(mut self, envelope: MiddlewareResponseEnvelope) -> Self {
+        self.envelope = Some(envelope);
+        self
+    }
+
+    pub(crate) fn with_provider_metadata(mut self, metadata: ProviderCallMetadata) -> Self {
+        self.envelope = Some(MiddlewareResponseEnvelope { metadata });
+        self
+    }
+}
+
+impl fmt::Debug for MiddlewareResponse {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("MiddlewareResponse")
+            .field("protocol", &self.protocol)
+            .field("status_code", &self.status_code)
+            .field("headers", &self.headers)
+            .field("body", &"<stream>")
+            .field("has_host_envelope", &self.envelope.is_some())
+            .finish()
+    }
+}
+
+/// Attempt terminal 的 Core 来源事实；中间件只能随响应原样搬运。
+pub struct MiddlewareResponseEnvelope {
+    metadata: ProviderCallMetadata,
+}
+
+impl MiddlewareResponseEnvelope {
+    pub(crate) fn into_provider_metadata(self) -> ProviderCallMetadata {
+        self.metadata
+    }
+}
+
+impl fmt::Debug for MiddlewareResponseEnvelope {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("MiddlewareResponseEnvelope")
+            .finish_non_exhaustive()
+    }
+}
+
+/// Core 已冻结、但不会序列化敏感身份的调用事实。
+#[derive(Clone)]
+pub struct MiddlewareContext {
+    request_id: ModelRequestId,
+    mount: MiddlewareMount,
+    attempt_index: Option<NonZeroU32>,
+    operation: Option<OperationKind>,
+    endpoint: String,
+    transport: ClientTransport,
+    provider: Option<ProviderKind>,
+    model: Option<String>,
+    account_id: Option<ProviderAccountId>,
+    client_key_id: ClientApiKeyId,
+    account_group_ids: Arc<[AccountGroupId]>,
+    cancellation: CancellationToken,
+    deadline: SystemTime,
+    extension_scope: ExtensionCallScope,
+    execution_effects: Option<Arc<ExecutionEffects>>,
+}
+
+impl MiddlewareContext {
+    #[must_use]
+    pub fn new(target: MiddlewareTarget, authority: MiddlewareAuthority) -> Self {
+        let MiddlewareTarget {
+            request_id,
+            mount,
+            attempt_index,
+            operation,
+            endpoint,
+            transport,
+            provider,
+            model,
+            account_id,
+        } = target;
+        let MiddlewareAuthority {
+            client_key_id,
+            account_group_ids,
+            cancellation,
+            deadline,
+            extension_scope,
+            execution_effects,
+        } = authority;
+        Self {
+            request_id,
+            mount,
+            attempt_index,
+            operation,
+            endpoint,
+            transport,
+            provider,
+            model,
+            account_id,
+            client_key_id,
+            account_group_ids,
+            cancellation,
+            deadline,
+            extension_scope,
+            execution_effects,
+        }
+    }
+
+    #[must_use]
+    pub const fn request_id(&self) -> &ModelRequestId {
+        &self.request_id
+    }
+
+    #[must_use]
+    pub const fn mount(&self) -> MiddlewareMount {
+        self.mount
+    }
+
+    #[must_use]
+    pub const fn attempt_index(&self) -> Option<NonZeroU32> {
+        self.attempt_index
+    }
+
+    #[must_use]
+    pub const fn operation(&self) -> Option<OperationKind> {
+        self.operation
+    }
+
+    #[must_use]
+    pub fn endpoint(&self) -> &str {
+        &self.endpoint
+    }
+
+    #[must_use]
+    pub const fn transport(&self) -> ClientTransport {
+        self.transport
+    }
+
+    #[must_use]
+    pub const fn provider(&self) -> Option<&ProviderKind> {
+        self.provider.as_ref()
+    }
+
+    #[must_use]
+    pub fn model(&self) -> Option<&str> {
+        self.model.as_deref()
+    }
+
+    #[must_use]
+    pub const fn account_id(&self) -> Option<&ProviderAccountId> {
+        self.account_id.as_ref()
+    }
+
+    /// 只供宿主 Runtime 匹配冻结 binding；不得序列化给插件。
+    #[must_use]
+    pub const fn client_key_id(&self) -> &ClientApiKeyId {
+        &self.client_key_id
+    }
+
+    /// 只供宿主 Runtime 匹配冻结 binding；不得序列化给插件。
+    #[must_use]
+    pub fn account_group_ids(&self) -> &[AccountGroupId] {
+        &self.account_group_ids
+    }
+
+    #[must_use]
+    pub const fn cancellation(&self) -> &CancellationToken {
+        &self.cancellation
+    }
+
+    #[must_use]
+    pub const fn deadline(&self) -> SystemTime {
+        self.deadline
+    }
+
+    #[must_use]
+    pub const fn extension_scope(&self) -> &ExtensionCallScope {
+        &self.extension_scope
+    }
+
+    /// 只供受信 Runtime 记录本次中间件调用已经产生的外部副作用，不进入插件 wire。
+    #[must_use]
+    pub fn execution_effects(&self) -> Option<Arc<ExecutionEffects>> {
+        self.execution_effects.as_ref().map(Arc::clone)
+    }
+}
+
+/// 不含授权主体的调用位置与目标事实。
+pub struct MiddlewareTarget {
+    pub request_id: ModelRequestId,
+    pub mount: MiddlewareMount,
+    pub attempt_index: Option<NonZeroU32>,
+    pub operation: Option<OperationKind>,
+    pub endpoint: String,
+    pub transport: ClientTransport,
+    pub provider: Option<ProviderKind>,
+    pub model: Option<String>,
+    pub account_id: Option<ProviderAccountId>,
+}
+
+/// Runtime 只用于授权求交的冻结主体；字段不得进入插件 wire。
+pub struct MiddlewareAuthority {
+    pub client_key_id: ClientApiKeyId,
+    pub account_group_ids: Arc<[AccountGroupId]>,
+    pub cancellation: CancellationToken,
+    pub deadline: SystemTime,
+    pub extension_scope: ExtensionCallScope,
+    pub execution_effects: Option<Arc<ExecutionEffects>>,
+}
+
+impl fmt::Debug for MiddlewareContext {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("MiddlewareContext")
+            .field("request_id", &self.request_id)
+            .field("mount", &self.mount)
+            .field("attempt_index", &self.attempt_index)
+            .field("operation", &self.operation)
+            .field("endpoint", &self.endpoint)
+            .field("transport", &self.transport)
+            .field("provider", &self.provider)
+            .field("model", &self.model)
+            .field("account_id", &self.account_id)
+            .field("deadline", &self.deadline)
+            .finish_non_exhaustive()
+    }
+}
+
+/// 中间件链调用错误。原有域错误保持原类型，不能被插件故障改写为“未发送”。
+#[derive(Debug)]
+pub enum MiddlewareError {
+    Rejected,
+    Fault,
+    InvalidState,
+    Gateway(GatewayError),
+    Engine(EngineError),
+    Provider(ProviderError),
+}
+
+impl fmt::Display for MiddlewareError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(match self {
+            Self::Rejected => "middleware rejected the request",
+            Self::Fault => "middleware call failed",
+            Self::InvalidState => "middleware state is invalid",
+            Self::Gateway(_) => "gateway middleware terminal failed",
+            Self::Engine(_) => "execution middleware terminal failed",
+            Self::Provider(_) => "provider middleware terminal failed",
+        })
+    }
+}
+
+impl std::error::Error for MiddlewareError {}
+
+impl From<GatewayError> for MiddlewareError {
+    fn from(error: GatewayError) -> Self {
+        Self::Gateway(error)
+    }
+}
+
+impl From<EngineError> for MiddlewareError {
+    fn from(error: EngineError) -> Self {
+        Self::Engine(error)
+    }
+}
+
+impl From<ProviderError> for MiddlewareError {
+    fn from(error: ProviderError) -> Self {
+        Self::Provider(error)
+    }
+}
+
+/// 绑定当前调用且只能消费一次的宿主续体。
+pub trait MiddlewareNext: Send {
+    fn run(
+        self: Box<Self>,
+        request: MiddlewareRequest,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>>;
+}
+
+/// 一个发布代次冻结的统一数据面中间件计划。
+pub trait MiddlewarePlan: Send + Sync + fmt::Debug {
+    fn handle(
+        &self,
+        context: MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>>;
+}
+
+/// 调用期间同时保活发布代次与中间件计划。
+#[derive(Clone)]
+pub struct FrozenMiddlewarePlan {
+    plan: Arc<dyn MiddlewarePlan>,
+    _generation: ExtensionSetReference,
+}
+
+impl FrozenMiddlewarePlan {
+    #[must_use]
+    pub fn new(plan: Arc<dyn MiddlewarePlan>, generation: ExtensionSetReference) -> Self {
+        Self {
+            plan,
+            _generation: generation,
+        }
+    }
+
+    pub fn handle(
+        &self,
+        context: MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        self.plan.handle(context, request, next)
+    }
+}
+
+impl fmt::Debug for FrozenMiddlewarePlan {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("FrozenMiddlewarePlan")
+            .finish_non_exhaustive()
+    }
+}
+
+/// 同一发布代次不能被静默替换。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+#[error("middleware generation is already registered")]
+pub struct MiddlewareRegistrationError;
+
+/// 按请求冻结的发布集合解析中间件计划；索引不延长旧代次寿命。
+#[derive(Clone, Default)]
+pub struct MiddlewareExtensionIndex {
+    sets: Arc<RwLock<BTreeMap<ExtensionSetId, Weak<dyn MiddlewarePlan>>>>,
+}
+
+impl MiddlewareExtensionIndex {
+    pub fn register(
+        &self,
+        id: ExtensionSetId,
+        plan: Arc<dyn MiddlewarePlan>,
+    ) -> Result<Arc<dyn MiddlewarePlan>, MiddlewareRegistrationError> {
+        let mut sets = self
+            .sets
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        sets.retain(|_, plan| plan.strong_count() > 0);
+        if sets.contains_key(&id) {
+            return Err(MiddlewareRegistrationError);
+        }
+        sets.insert(id, Arc::downgrade(&plan));
+        Ok(plan)
+    }
+
+    #[must_use]
+    pub fn resolve(&self, generation: &ExtensionSetReference) -> Option<FrozenMiddlewarePlan> {
+        self.sets
+            .read()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .get(generation.id())
+            .and_then(Weak::upgrade)
+            .map(|plan| FrozenMiddlewarePlan::new(plan, generation.clone()))
+    }
+}
diff --git a/backend/crates/gateway-core/src/engine/mod.rs b/backend/crates/gateway-core/src/engine/mod.rs
index f5f6c6ab1..5ae8b40a7 100644
--- a/backend/crates/gateway-core/src/engine/mod.rs
+++ b/backend/crates/gateway-core/src/engine/mod.rs
@@ -1,11 +1,16 @@
 //! 模型请求生命周期、单行持久化 port 与 commit/send/cancellation 边界。
 
 pub mod admission;
+pub mod authentication;
 pub mod budget;
 pub mod continuation;
 pub mod coordinator;
 pub mod execution;
-mod observation;
+pub mod extensions;
+pub mod middleware;
+pub mod nested;
+pub mod observation;
+pub mod policy;
 pub mod probe;
 pub mod provider;
 
@@ -21,7 +26,10 @@ use std::time::{Duration, Instant, SystemTime};
 use async_trait::async_trait;
 use thiserror::Error;
 
-use crate::account::{AccountSelectionPolicy, ProviderAccountId};
+use crate::account::{
+    AccountCandidate, AccountSelection, AccountSelectionContext, AccountSelectionPolicy,
+    ProviderAccountId,
+};
 use crate::engine::continuation::{ContinuationBinding, NativeContinuationPin};
 use crate::error::{
     GatewayError, ProviderConnectionObservation, ProviderError, ProviderErrorKind, StoreError,
@@ -323,6 +331,13 @@ pub struct RequestAttemptContext {
     timing_started_at: Instant,
     trace: crate::diagnostics::TraceContext,
     concurrency_wait_budget: crate::concurrency::ConcurrencyWaitBudget,
+    request_policy: Option<policy::RequestPolicyContext>,
+    execution_effects: Option<Arc<nested::ExecutionEffects>>,
+    middleware: Option<middleware::FrozenMiddlewarePlan>,
+    account_group_ids: Arc<[crate::account::scope::AccountGroupId]>,
+    endpoint: String,
+    client_transport: execution::ClientTransport,
+    extension_scope: extensions::ExtensionCallScope,
 }
 
 impl RequestAttemptContext {
@@ -368,6 +383,13 @@ impl RequestAttemptContext {
             timing_started_at: Instant::now(),
             trace: crate::diagnostics::TraceContext::default(),
             concurrency_wait_budget: crate::concurrency::ConcurrencyWaitBudget::default(),
+            request_policy: None,
+            execution_effects: None,
+            middleware: None,
+            account_group_ids: Arc::from([]),
+            endpoint: String::new(),
+            client_transport: execution::ClientTransport::InternalProbe,
+            extension_scope: extensions::ExtensionCallScope::default(),
         }
     }
 
@@ -394,6 +416,45 @@ impl RequestAttemptContext {
         self
     }
 
+    /// 附着与发布视图同代次的请求策略；诊断与无插件路径保持 `None`。
+    #[must_use]
+    pub fn with_request_policy(mut self, policy: Option<policy::RequestPolicyContext>) -> Self {
+        self.request_policy = policy;
+        self
+    }
+
+    /// 附着本次逻辑请求共享的外部副作用水位；不会传给 Provider 或插件 wire。
+    #[must_use]
+    pub fn with_execution_effects(
+        mut self,
+        effects: Option<Arc<nested::ExecutionEffects>>,
+    ) -> Self {
+        self.execution_effects = effects;
+        self
+    }
+
+    /// 附着与路由快照同代次的 attempt 中间件及可信绑定事实。
+    #[must_use]
+    pub fn with_middleware(
+        mut self,
+        middleware: Option<middleware::FrozenMiddlewarePlan>,
+        account_group_ids: Arc<[crate::account::scope::AccountGroupId]>,
+        endpoint: String,
+        client_transport: execution::ClientTransport,
+    ) -> Self {
+        self.middleware = middleware;
+        self.account_group_ids = account_group_ids;
+        self.endpoint = endpoint;
+        self.client_transport = client_transport;
+        self
+    }
+
+    #[must_use]
+    pub fn with_extension_scope(mut self, extension_scope: extensions::ExtensionCallScope) -> Self {
+        self.extension_scope = extension_scope;
+        self
+    }
+
     #[must_use]
     pub const fn request_id(&self) -> &ModelRequestId {
         &self.request_id
@@ -409,6 +470,36 @@ impl RequestAttemptContext {
     pub const fn timing_started_at(&self) -> Instant {
         self.timing_started_at
     }
+
+    #[must_use]
+    pub const fn request_policy(&self) -> Option<&policy::RequestPolicyContext> {
+        self.request_policy.as_ref()
+    }
+
+    #[must_use]
+    pub const fn extension_scope(&self) -> &extensions::ExtensionCallScope {
+        &self.extension_scope
+    }
+
+    #[must_use]
+    pub const fn middleware(&self) -> Option<&middleware::FrozenMiddlewarePlan> {
+        self.middleware.as_ref()
+    }
+
+    #[must_use]
+    pub fn account_group_ids(&self) -> &[crate::account::scope::AccountGroupId] {
+        &self.account_group_ids
+    }
+
+    #[must_use]
+    pub fn endpoint(&self) -> &str {
+        &self.endpoint
+    }
+
+    #[must_use]
+    pub const fn client_transport(&self) -> execution::ClientTransport {
+        self.client_transport
+    }
 }
 
 /// Provider 每次执行可见的 request-local context。
@@ -515,6 +606,60 @@ impl AttemptContext {
         self.request.timing_started_at()
     }
 
+    /// 返回同一次请求冻结的插件策略上下文。
+    #[must_use]
+    pub const fn request_policy_context(&self) -> Option<&policy::RequestPolicyContext> {
+        self.request.request_policy()
+    }
+
+    #[must_use]
+    pub const fn extension_scope(&self) -> &extensions::ExtensionCallScope {
+        self.request.extension_scope()
+    }
+
+    /// 在已选账号并持有其 lease 后，以 owned terminal 执行本次 retry 的中间件链。
+    ///
+    /// terminal 返回的 stream 仍须保持 cold；中间件不能取得 credential、发送状态、
+    /// canonical usage/cost 或结算所有权。
+    pub async fn execute_middleware(
+        &self,
+        operation: crate::operation::Operation,
+        provider: ProviderKind,
+        model: Option<String>,
+        account_id: ProviderAccountId,
+        terminal: provider::ProviderMiddlewareTerminal,
+    ) -> Result<provider::ProviderStream, ProviderError> {
+        let context = middleware::MiddlewareContext::new(
+            middleware::MiddlewareTarget {
+                request_id: self.request.request_id.clone(),
+                mount: middleware::MiddlewareMount::Attempt,
+                attempt_index: Some(self.attempt_index),
+                operation: Some(operation.kind()),
+                endpoint: self.request.endpoint.clone(),
+                transport: self.request.client_transport,
+                provider: Some(provider),
+                model,
+                account_id: Some(account_id),
+            },
+            middleware::MiddlewareAuthority {
+                client_key_id: self.request.client_api_key_ref.clone(),
+                account_group_ids: Arc::clone(&self.request.account_group_ids),
+                cancellation: self.cancellation.clone(),
+                deadline: self.deadline,
+                extension_scope: self.request.extension_scope.clone(),
+                execution_effects: self.request.execution_effects.as_ref().map(Arc::clone),
+            },
+        );
+        provider::execute_attempt_middleware(
+            self.request.middleware.as_ref(),
+            context,
+            operation,
+            self.request.client_transport,
+            terminal,
+        )
+        .await
+    }
+
     #[must_use]
     pub const fn attempt_index(&self) -> NonZeroU32 {
         self.attempt_index
@@ -590,6 +735,24 @@ impl AttemptContext {
     pub const fn cancellation(&self) -> &CancellationToken {
         &self.cancellation
     }
+
+    /// 使用冻结策略选择账号；没有匹配策略时委托现有 `AccountSelector`。
+    pub async fn select_account<'a>(
+        &self,
+        provider: &ProviderKind,
+        model: Option<&str>,
+        candidates: &'a [AccountCandidate],
+        context: &AccountSelectionContext,
+    ) -> Result<Option<AccountSelection<'a>>, policy::AccountPolicyError> {
+        match self.request.request_policy() {
+            Some(policy) => {
+                policy
+                    .select_account(self.attempt_index, provider, model, candidates, context)
+                    .await
+            }
+            None => Ok(crate::account::AccountSelector.select(candidates, context)),
+        }
+    }
 }
 
 /// 创建唯一 `model_requests` 行所需的入口事实。
diff --git a/backend/crates/gateway-core/src/engine/nested.rs b/backend/crates/gateway-core/src/engine/nested.rs
new file mode 100644
index 000000000..dbb34daa0
--- /dev/null
+++ b/backend/crates/gateway-core/src/engine/nested.rs
@@ -0,0 +1,203 @@
+//! 插件宿主模型调用与亲和查询的中立 Core 端口。
+//!
+//! Runtime 只传递宿主签发的父请求关联和业务目标；调用方身份、
+//! 快照、准入、续写资格与计费始终由 [`super::execution::DefaultExecutionService`]
+//! 持有和复核。
+
+use std::{
+    fmt,
+    sync::atomic::{AtomicUsize, Ordering},
+    time::Duration,
+};
+
+use futures::future::BoxFuture;
+
+use crate::{
+    account::ProviderAccountId, error::GatewayError, identity::ProviderKind,
+    lifecycle::CancellationToken, operation::Operation, policy::ClientApiKeyId,
+    provider_ports::ProviderSessionAffinityKey, routing::PublicModelId,
+};
+
+use super::{
+    ModelRequestId,
+    execution::{BoundModelExecutionContext, ExecutionRequestMetadata, StartedExecution},
+};
+
+/// 同一请求图内不可逆外部副作用的单调水位。
+///
+/// 受信 Runtime 只在受管子执行或外部 HTTP 已发送、或无法证明未发送时调用
+/// [`Self::observe`]。它不承载费用或插件输入；Coordinator 用每次执行自己的基线
+/// 阻止把随后 Provider 的 `not_sent` 错当作可重放。
+#[derive(Debug, Default)]
+pub struct ExecutionEffects(AtomicUsize);
+
+impl ExecutionEffects {
+    pub fn observe(&self) {
+        self.0.fetch_add(1, Ordering::AcqRel);
+    }
+
+    pub(crate) fn epoch(&self) -> usize {
+        self.0.load(Ordering::Acquire)
+    }
+}
+
+/// 插件发起的一个子模型请求。
+///
+/// `parent_request_id` 与 `initiating_plugin_instance_id` 都来自宿主保存的
+/// `CallContext`，不能接受插件自行构造的关联事实。
+pub struct NestedModelExecutionRequest {
+    pub parent_request_id: ModelRequestId,
+    pub initiating_plugin_instance_id: String,
+    pub public_model: PublicModelId,
+    pub operation: Operation,
+    pub metadata: ExecutionRequestMetadata,
+    pub provider: Option<ProviderKind>,
+    pub account: Option<ProviderAccountId>,
+    /// 发起回调时父 attempt 已持有的账号。该事实由宿主从 `CallContext` 注入，
+    /// 用于阻止子请求在父请求等待其返回时再次等待同一账号 lease。
+    pub parent_account: Option<ProviderAccountId>,
+}
+
+/// 管理页或 CLI 为一次插件调用显式绑定的模型执行身份。
+///
+/// Key ID 由已获模型域访问的调用选择，发起实例由宿主确定。Core 在绑定时冻结当前
+/// Key 策略；每个实际模型请求仍独立经过准入、预算、账本与计费。
+pub struct BoundModelExecutionBinding {
+    pub client_key_id: ClientApiKeyId,
+    pub initiating_plugin_instance_id: String,
+    pub timeout: Duration,
+    pub cancellation: CancellationToken,
+    /// 宿主保留的扩展调用链，异步观察不能通过新建模型请求清空防递归事实。
+    pub extension_scope: super::extensions::ExtensionCallScope,
+}
+
+impl fmt::Debug for BoundModelExecutionBinding {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("BoundModelExecutionBinding")
+            .field("client_key_id", &self.client_key_id)
+            .field(
+                "initiating_plugin_instance_id",
+                &self.initiating_plugin_instance_id,
+            )
+            .field("timeout", &self.timeout)
+            .finish_non_exhaustive()
+    }
+}
+
+/// 显式身份作用域内的一次模型请求。
+pub struct BoundModelExecutionRequest {
+    pub context: BoundModelExecutionContext,
+    pub public_model: PublicModelId,
+    pub operation: Operation,
+    pub metadata: ExecutionRequestMetadata,
+    pub provider: Option<ProviderKind>,
+    pub account: Option<ProviderAccountId>,
+}
+
+impl fmt::Debug for BoundModelExecutionRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("BoundModelExecutionRequest")
+            .field("context", &self.context)
+            .field("public_model", &self.public_model)
+            .field("operation", &self.operation.kind())
+            .field("provider", &self.provider)
+            .field("account", &self.account)
+            .finish_non_exhaustive()
+    }
+}
+
+impl fmt::Debug for NestedModelExecutionRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("NestedModelExecutionRequest")
+            .field("parent_request_id", &self.parent_request_id)
+            .field(
+                "initiating_plugin_instance_id",
+                &self.initiating_plugin_instance_id,
+            )
+            .field("public_model", &self.public_model)
+            .field("operation", &self.operation.kind())
+            .field("provider", &self.provider)
+            .field("account", &self.account)
+            .field("parent_account", &self.parent_account)
+            .finish_non_exhaustive()
+    }
+}
+
+/// 嵌套模型执行只进入 Core 的既有执行会话；Runtime 不实现重试、commit 或计费。
+pub trait NestedModelExecutionPort: Send + Sync {
+    fn models(
+        &self,
+        context: BoundModelExecutionContext,
+        protocol: String,
+        client_version: String,
+    ) -> BoxFuture<'_, Result<Vec<PublicModelId>, GatewayError>>;
+
+    /// 为单次受保护管理调用或 CLI 命令冻结显式执行身份与共享调用图。
+    fn bind(
+        &self,
+        binding: BoundModelExecutionBinding,
+    ) -> BoxFuture<'_, Result<BoundModelExecutionContext, GatewayError>>;
+
+    fn start(
+        &self,
+        request: NestedModelExecutionRequest,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>>;
+
+    fn start_bound(
+        &self,
+        request: BoundModelExecutionRequest,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>>;
+}
+
+/// 带父请求身份与授权范围的会话亲和查询。
+pub struct AffinityLookupRequest {
+    pub parent_request_id: ModelRequestId,
+    pub provider: ProviderKind,
+    pub key: ProviderSessionAffinityKey,
+}
+
+impl fmt::Debug for AffinityLookupRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("AffinityLookupRequest")
+            .field("parent_request_id", &self.parent_request_id)
+            .field("provider", &self.provider)
+            .field("key", &self.key)
+            .finish_non_exhaustive()
+    }
+}
+
+/// 只公开后续请求可作为偏好提交、但仍须 Core 再次复核的亲和提示。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AffinityLookupResult {
+    provider: ProviderKind,
+    account: ProviderAccountId,
+}
+
+impl AffinityLookupResult {
+    #[must_use]
+    pub const fn new(provider: ProviderKind, account: ProviderAccountId) -> Self {
+        Self { provider, account }
+    }
+
+    #[must_use]
+    pub const fn provider(&self) -> &ProviderKind {
+        &self.provider
+    }
+
+    #[must_use]
+    pub const fn account(&self) -> &ProviderAccountId {
+        &self.account
+    }
+}
+
+/// 会话亲和查询失败沿用公开网关错误分类，不暴露响应句柄或归属细节。
+pub trait AffinityLookupPort: Send + Sync {
+    fn lookup(
+        &self,
+        request: AffinityLookupRequest,
+    ) -> BoxFuture<'_, Result<Option<AffinityLookupResult>, GatewayError>>;
+}
diff --git a/backend/crates/gateway-core/src/engine/observation.rs b/backend/crates/gateway-core/src/engine/observation.rs
index 1df1c1b44..b572fe02e 100644
--- a/backend/crates/gateway-core/src/engine/observation.rs
+++ b/backend/crates/gateway-core/src/engine/observation.rs
@@ -1,10 +1,751 @@
-//! 单次响应的计量、时间与响应身份事实；重试丢弃时统一清理。
+//! 单次响应事实与请求终态扩展派发；重试丢弃时统一清理。
 
-use super::ModelRequestTimings;
-use crate::event::GatewayEvent;
-use crate::event::ProviderResponseObservation;
-use crate::metering::{CostEstimate, CostSource, Usage};
-use std::time::Instant;
+use std::{
+    collections::BTreeMap,
+    num::NonZeroU32,
+    sync::{
+        Arc, RwLock, Weak,
+        atomic::{AtomicBool, Ordering},
+    },
+    time::{Instant, SystemTime},
+};
+
+use super::{
+    ExecutionOutcome, ModelRequestFinalization, ModelRequestId, ModelRequestTimings,
+    extensions::ExtensionCallScope,
+};
+use crate::{
+    account::ProviderAccountId,
+    error::{GatewayError, GatewayErrorKind},
+    event::{GatewayEvent, ProtocolWireEvent, ProviderResponseObservation},
+    identity::ProviderKind,
+    metering::{CostEstimate, CostSource, Usage},
+    operation::OperationKind,
+    policy::ClientApiKeyId,
+    routing::{AccountGroupId, ConfigRevision, PublicModelId},
+    runtime::extensions::{ExtensionSetId, ExtensionSetReference},
+    upstream::UpstreamSendState,
+};
+
+/// 一条 WebSocket 响应事件所属的实际上游 attempt 身份。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WebSocketResponseAttempt {
+    provider: ProviderKind,
+    account_id: ProviderAccountId,
+    attempt_index: NonZeroU32,
+}
+
+impl WebSocketResponseAttempt {
+    /// 固定一条响应事件所属的实际上游 attempt。
+    #[must_use]
+    pub const fn new(
+        provider: ProviderKind,
+        account_id: ProviderAccountId,
+        attempt_index: NonZeroU32,
+    ) -> Self {
+        Self {
+            provider,
+            account_id,
+            attempt_index,
+        }
+    }
+
+    #[must_use]
+    pub const fn provider(&self) -> &ProviderKind {
+        &self.provider
+    }
+
+    #[must_use]
+    pub const fn account_id(&self) -> &ProviderAccountId {
+        &self.account_id
+    }
+
+    #[must_use]
+    pub const fn attempt_index(&self) -> NonZeroU32 {
+        self.attempt_index
+    }
+}
+
+/// 实际上游 WebSocket 响应事件的只读观察。
+///
+/// Key 与账号组只用于 Runtime 匹配冻结绑定，不得进入插件 wire；`wire` 保留策略加工前
+/// 的 Provider 原始事实，由 Runtime 再按正文读取授权投影。
+#[derive(Clone, PartialEq)]
+pub struct WebSocketResponseObservation {
+    event_id: String,
+    request_id: ModelRequestId,
+    config_revision: ConfigRevision,
+    client_key_id: Option<ClientApiKeyId>,
+    account_group_ids: Arc<[AccountGroupId]>,
+    extension_scope: ExtensionCallScope,
+    operation: OperationKind,
+    requested_model: Option<PublicModelId>,
+    attempt: WebSocketResponseAttempt,
+    sequence: u64,
+    wire: ProtocolWireEvent,
+}
+
+impl WebSocketResponseObservation {
+    /// 创建一个尚未附加冻结 Key/组/公开模型范围的实际上游事件。
+    #[must_use]
+    pub fn new(
+        request_id: ModelRequestId,
+        config_revision: ConfigRevision,
+        operation: OperationKind,
+        attempt: WebSocketResponseAttempt,
+        sequence: u64,
+        wire: ProtocolWireEvent,
+    ) -> Self {
+        Self {
+            event_id: format!(
+                "{}:websocket:{}:{sequence}",
+                request_id.as_str(),
+                attempt.attempt_index().get()
+            ),
+            request_id,
+            config_revision,
+            client_key_id: None,
+            account_group_ids: Arc::from([]),
+            extension_scope: ExtensionCallScope::default(),
+            operation,
+            requested_model: None,
+            attempt,
+            sequence,
+            wire,
+        }
+    }
+
+    #[must_use]
+    pub fn with_client_scope(
+        mut self,
+        client_key_id: ClientApiKeyId,
+        mut account_group_ids: Vec<AccountGroupId>,
+    ) -> Self {
+        account_group_ids.sort();
+        account_group_ids.dedup();
+        self.client_key_id = Some(client_key_id);
+        self.account_group_ids = account_group_ids.into();
+        self
+    }
+
+    #[must_use]
+    pub fn with_requested_model(mut self, model: PublicModelId) -> Self {
+        self.requested_model = Some(model);
+        self
+    }
+
+    #[must_use]
+    pub fn with_extension_scope(mut self, extension_scope: ExtensionCallScope) -> Self {
+        self.extension_scope = extension_scope;
+        self
+    }
+
+    #[must_use]
+    pub fn suppresses_plugin(&self, instance_id: &str) -> bool {
+        self.extension_scope.contains(instance_id)
+    }
+
+    #[must_use]
+    pub const fn extension_scope(&self) -> &ExtensionCallScope {
+        &self.extension_scope
+    }
+
+    #[must_use]
+    pub fn event_id(&self) -> &str {
+        &self.event_id
+    }
+
+    #[must_use]
+    pub const fn request_id(&self) -> &ModelRequestId {
+        &self.request_id
+    }
+
+    #[must_use]
+    pub const fn config_revision(&self) -> ConfigRevision {
+        self.config_revision
+    }
+
+    #[must_use]
+    pub const fn client_key_id(&self) -> Option<&ClientApiKeyId> {
+        self.client_key_id.as_ref()
+    }
+
+    #[must_use]
+    pub fn account_group_ids(&self) -> &[AccountGroupId] {
+        &self.account_group_ids
+    }
+
+    #[must_use]
+    pub const fn operation(&self) -> OperationKind {
+        self.operation
+    }
+
+    #[must_use]
+    pub const fn requested_model(&self) -> Option<&PublicModelId> {
+        self.requested_model.as_ref()
+    }
+
+    #[must_use]
+    pub const fn provider(&self) -> &ProviderKind {
+        self.attempt.provider()
+    }
+
+    #[must_use]
+    pub const fn account_id(&self) -> &ProviderAccountId {
+        self.attempt.account_id()
+    }
+
+    #[must_use]
+    pub const fn attempt_index(&self) -> NonZeroU32 {
+        self.attempt.attempt_index()
+    }
+
+    #[must_use]
+    pub const fn sequence(&self) -> u64 {
+        self.sequence
+    }
+
+    #[must_use]
+    pub const fn wire(&self) -> &ProtocolWireEvent {
+        &self.wire
+    }
+}
+
+/// 插件可观察的请求终态；拒绝表示请求没有进入 Provider 执行。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RequestObservationOutcome {
+    Succeeded,
+    Failed,
+    Rejected,
+    Cancelled,
+    Incomplete,
+}
+
+/// Core 在业务结果确定后产生的一次最终观察，不包含原始正文或凭据。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RequestObservation {
+    event_id: String,
+    request_id: ModelRequestId,
+    config_revision: ConfigRevision,
+    client_key_id: Option<ClientApiKeyId>,
+    account_group_ids: Arc<[AccountGroupId]>,
+    extension_scope: ExtensionCallScope,
+    operation: OperationKind,
+    requested_model: Option<PublicModelId>,
+    provider: Option<ProviderKind>,
+    account_id: Option<ProviderAccountId>,
+    upstream_model: Option<crate::routing::UpstreamModelId>,
+    response_model: Option<String>,
+    service_tier: Option<String>,
+    outcome: RequestObservationOutcome,
+    send_state: UpstreamSendState,
+    attempt_count: u32,
+    client_status_code: Option<u16>,
+    upstream_status_code: Option<u16>,
+    error_kind: Option<GatewayErrorKind>,
+    retry_after_ms: Option<u64>,
+    usage: Usage,
+    cost: CostEstimate,
+    timings: ModelRequestTimings,
+    completed_at: SystemTime,
+}
+
+impl RequestObservation {
+    /// 创建一个不带 Provider、模型、用量或错误详情的最终事实。
+    #[must_use]
+    pub fn new(
+        request_id: ModelRequestId,
+        config_revision: ConfigRevision,
+        operation: OperationKind,
+        outcome: RequestObservationOutcome,
+        send_state: UpstreamSendState,
+        completed_at: SystemTime,
+    ) -> Self {
+        Self {
+            event_id: format!("{}:terminal", request_id.as_str()),
+            request_id,
+            config_revision,
+            client_key_id: None,
+            account_group_ids: Arc::from([]),
+            extension_scope: ExtensionCallScope::default(),
+            operation,
+            requested_model: None,
+            provider: None,
+            account_id: None,
+            upstream_model: None,
+            response_model: None,
+            service_tier: None,
+            outcome,
+            send_state,
+            attempt_count: 0,
+            client_status_code: None,
+            upstream_status_code: None,
+            error_kind: None,
+            retry_after_ms: None,
+            usage: Usage::new(),
+            cost: CostEstimate::unavailable(),
+            timings: ModelRequestTimings::default(),
+            completed_at,
+        }
+    }
+
+    #[must_use]
+    pub fn with_client_scope(
+        mut self,
+        client_key_id: ClientApiKeyId,
+        mut account_group_ids: Vec<AccountGroupId>,
+    ) -> Self {
+        account_group_ids.sort();
+        account_group_ids.dedup();
+        self.client_key_id = Some(client_key_id);
+        self.account_group_ids = account_group_ids.into();
+        self
+    }
+
+    #[must_use]
+    pub fn with_requested_model(mut self, model: PublicModelId) -> Self {
+        self.requested_model = Some(model);
+        self
+    }
+
+    #[must_use]
+    pub fn with_extension_scope(mut self, extension_scope: ExtensionCallScope) -> Self {
+        self.extension_scope = extension_scope;
+        self
+    }
+
+    #[must_use]
+    pub fn suppresses_plugin(&self, instance_id: &str) -> bool {
+        self.extension_scope.contains(instance_id)
+    }
+
+    #[must_use]
+    pub const fn extension_scope(&self) -> &ExtensionCallScope {
+        &self.extension_scope
+    }
+
+    #[must_use]
+    pub fn with_provider(mut self, provider: ProviderKind) -> Self {
+        self.provider = Some(provider);
+        self
+    }
+
+    #[must_use]
+    pub fn account_id(&self) -> Option<&ProviderAccountId> {
+        self.account_id.as_ref()
+    }
+
+    #[must_use]
+    pub fn upstream_model(&self) -> Option<&crate::routing::UpstreamModelId> {
+        self.upstream_model.as_ref()
+    }
+
+    #[must_use]
+    pub fn response_model(&self) -> Option<&str> {
+        self.response_model.as_deref()
+    }
+
+    #[must_use]
+    pub fn service_tier(&self) -> Option<&str> {
+        self.service_tier.as_deref()
+    }
+
+    #[must_use]
+    pub const fn with_attempt_count(mut self, attempt_count: u32) -> Self {
+        self.attempt_count = attempt_count;
+        self
+    }
+
+    #[must_use]
+    pub const fn with_client_status_code(mut self, client_status_code: u16) -> Self {
+        self.client_status_code = Some(client_status_code);
+        self
+    }
+
+    #[must_use]
+    pub const fn with_upstream_status_code(mut self, upstream_status_code: u16) -> Self {
+        self.upstream_status_code = Some(upstream_status_code);
+        self
+    }
+
+    #[must_use]
+    pub const fn with_error_kind(mut self, error_kind: GatewayErrorKind) -> Self {
+        self.error_kind = Some(error_kind);
+        self
+    }
+
+    #[must_use]
+    pub const fn with_retry_after_ms(mut self, retry_after_ms: u64) -> Self {
+        self.retry_after_ms = Some(retry_after_ms);
+        self
+    }
+
+    #[must_use]
+    pub fn with_usage(mut self, usage: Usage) -> Self {
+        self.usage = usage;
+        self
+    }
+
+    #[must_use]
+    pub fn with_cost(mut self, cost: CostEstimate) -> Self {
+        self.cost = cost;
+        self
+    }
+
+    #[must_use]
+    pub fn with_timings(mut self, timings: ModelRequestTimings) -> Self {
+        self.timings = timings;
+        self
+    }
+
+    #[must_use]
+    pub fn event_id(&self) -> &str {
+        &self.event_id
+    }
+
+    #[must_use]
+    pub const fn request_id(&self) -> &ModelRequestId {
+        &self.request_id
+    }
+
+    #[must_use]
+    pub const fn config_revision(&self) -> ConfigRevision {
+        self.config_revision
+    }
+
+    #[must_use]
+    pub const fn client_key_id(&self) -> Option<&ClientApiKeyId> {
+        self.client_key_id.as_ref()
+    }
+
+    #[must_use]
+    pub fn account_group_ids(&self) -> &[AccountGroupId] {
+        &self.account_group_ids
+    }
+
+    #[must_use]
+    pub const fn operation(&self) -> OperationKind {
+        self.operation
+    }
+
+    #[must_use]
+    pub const fn requested_model(&self) -> Option<&PublicModelId> {
+        self.requested_model.as_ref()
+    }
+
+    #[must_use]
+    pub const fn provider(&self) -> Option<&ProviderKind> {
+        self.provider.as_ref()
+    }
+
+    #[must_use]
+    pub const fn outcome(&self) -> RequestObservationOutcome {
+        self.outcome
+    }
+
+    #[must_use]
+    pub const fn send_state(&self) -> UpstreamSendState {
+        self.send_state
+    }
+
+    #[must_use]
+    pub const fn attempt_count(&self) -> u32 {
+        self.attempt_count
+    }
+
+    #[must_use]
+    pub const fn client_status_code(&self) -> Option<u16> {
+        self.client_status_code
+    }
+
+    #[must_use]
+    pub const fn upstream_status_code(&self) -> Option<u16> {
+        self.upstream_status_code
+    }
+
+    #[must_use]
+    pub const fn error_kind(&self) -> Option<GatewayErrorKind> {
+        self.error_kind
+    }
+
+    #[must_use]
+    pub const fn retry_after_ms(&self) -> Option<u64> {
+        self.retry_after_ms
+    }
+
+    #[must_use]
+    pub const fn usage(&self) -> &Usage {
+        &self.usage
+    }
+
+    #[must_use]
+    pub const fn cost(&self) -> &CostEstimate {
+        &self.cost
+    }
+
+    #[must_use]
+    pub const fn timings(&self) -> &ModelRequestTimings {
+        &self.timings
+    }
+
+    #[must_use]
+    pub const fn completed_at(&self) -> SystemTime {
+        self.completed_at
+    }
+}
+
+/// 一个发布代次的不可变请求观察计划；实现必须自行保证派发有界且不阻塞业务结果。
+pub trait RequestObserverPlan: Send + Sync {
+    /// 旁路观察一条实际上游 WebSocket 事件；未启用观察时，默认实现不额外处理事件。
+    fn dispatch_websocket_response(
+        &self,
+        _generation: ExtensionSetReference,
+        _observation: WebSocketResponseObservation,
+    ) {
+    }
+
+    /// `generation` 必须由后台工作持有到本次派发结束，避免旧代次提前排空。
+    fn dispatch(&self, generation: ExtensionSetReference, observation: RequestObservation);
+}
+
+/// 观察计划注册冲突；同一个集合 ID 不能被静默替换。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+#[error("request observer generation is already registered")]
+pub struct RequestObserverRegistrationError;
+
+/// 按发布集合解析计划的非拥有索引；旧代次由发布视图和在途派发保活。
+#[derive(Clone, Default)]
+pub struct RequestObserverExtensionIndex {
+    sets: Arc<RwLock<BTreeMap<ExtensionSetId, Weak<dyn RequestObserverPlan>>>>,
+}
+
+impl RequestObserverExtensionIndex {
+    /// 注册候选代次；返回值必须由候选集合强持有。
+    pub fn register(
+        &self,
+        id: ExtensionSetId,
+        plan: Arc<dyn RequestObserverPlan>,
+    ) -> Result<Arc<dyn RequestObserverPlan>, RequestObserverRegistrationError> {
+        let mut sets = self
+            .sets
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        sets.retain(|_, plan| plan.strong_count() > 0);
+        if sets.contains_key(&id) {
+            return Err(RequestObserverRegistrationError);
+        }
+        sets.insert(id, Arc::downgrade(&plan));
+        Ok(plan)
+    }
+
+    /// 只解析请求已经冻结的集合；缺少计划表示该代次没有观察绑定。
+    #[must_use]
+    pub fn resolve(
+        &self,
+        generation: &ExtensionSetReference,
+    ) -> Option<Arc<dyn RequestObserverPlan>> {
+        self.sets
+            .read()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .get(generation.id())
+            .and_then(Weak::upgrade)
+    }
+}
+
+/// 同一请求的所有终结分支共享这个一次性派发状态。
+#[derive(Clone)]
+pub(super) struct RequestObservationDispatch {
+    state: Arc<RequestObservationDispatchState>,
+}
+
+struct RequestObservationDispatchState {
+    plan: Arc<dyn RequestObserverPlan>,
+    generation: ExtensionSetReference,
+    dispatched: AtomicBool,
+    context: FrozenRequestObservationContext,
+}
+
+pub(super) struct FrozenRequestObservationContext {
+    request_id: ModelRequestId,
+    config_revision: ConfigRevision,
+    client_key_id: ClientApiKeyId,
+    account_group_ids: Arc<[AccountGroupId]>,
+    operation: OperationKind,
+    requested_model: Option<PublicModelId>,
+    extension_scope: ExtensionCallScope,
+}
+
+impl FrozenRequestObservationContext {
+    #[must_use]
+    pub(super) fn new(
+        request_id: ModelRequestId,
+        config_revision: ConfigRevision,
+        client_key_id: ClientApiKeyId,
+        mut account_group_ids: Vec<AccountGroupId>,
+        operation: OperationKind,
+        requested_model: Option<PublicModelId>,
+        extension_scope: ExtensionCallScope,
+    ) -> Self {
+        account_group_ids.sort();
+        account_group_ids.dedup();
+        Self {
+            request_id,
+            config_revision,
+            client_key_id,
+            account_group_ids: account_group_ids.into(),
+            operation,
+            requested_model,
+            extension_scope,
+        }
+    }
+}
+
+impl RequestObservationDispatch {
+    #[must_use]
+    pub(super) fn new(
+        plan: Arc<dyn RequestObserverPlan>,
+        generation: ExtensionSetReference,
+        context: FrozenRequestObservationContext,
+    ) -> Self {
+        Self {
+            state: Arc::new(RequestObservationDispatchState {
+                plan,
+                generation,
+                dispatched: AtomicBool::new(false),
+                context,
+            }),
+        }
+    }
+
+    pub(super) fn reject(&self, error: &GatewayError) {
+        self.dispatch(RequestObservation {
+            event_id: self.event_id(),
+            request_id: self.state.context.request_id.clone(),
+            config_revision: self.state.context.config_revision,
+            client_key_id: Some(self.state.context.client_key_id.clone()),
+            account_group_ids: Arc::clone(&self.state.context.account_group_ids),
+            extension_scope: self.state.context.extension_scope.clone(),
+            operation: self.state.context.operation,
+            requested_model: self.state.context.requested_model.clone(),
+            provider: None,
+            outcome: RequestObservationOutcome::Rejected,
+            account_id: None,
+            upstream_model: None,
+            response_model: None,
+            service_tier: None,
+            send_state: UpstreamSendState::NotSent,
+            attempt_count: 0,
+            client_status_code: None,
+            upstream_status_code: None,
+            error_kind: Some(error.kind()),
+            retry_after_ms: error.retry_after().map(duration_millis),
+            usage: Usage::new(),
+            cost: CostEstimate::unavailable(),
+            timings: ModelRequestTimings::default(),
+            completed_at: SystemTime::now(),
+        });
+    }
+
+    pub(super) fn websocket_response(
+        &self,
+        attempt: WebSocketResponseAttempt,
+        sequence: u64,
+        wire: ProtocolWireEvent,
+    ) {
+        let mut observation = WebSocketResponseObservation::new(
+            self.state.context.request_id.clone(),
+            self.state.context.config_revision,
+            self.state.context.operation,
+            attempt,
+            sequence,
+            wire,
+        )
+        .with_client_scope(
+            self.state.context.client_key_id.clone(),
+            self.state.context.account_group_ids.to_vec(),
+        )
+        .with_extension_scope(self.state.context.extension_scope.clone());
+        if let Some(model) = self.state.context.requested_model.clone() {
+            observation = observation.with_requested_model(model);
+        }
+        self.state
+            .plan
+            .dispatch_websocket_response(self.state.generation.clone(), observation);
+    }
+
+    #[must_use]
+    pub(super) fn finalization(
+        &self,
+        finalization: &ModelRequestFinalization,
+        provider: Option<ProviderKind>,
+        attempt: Option<&super::provider::ProviderCallMetadata>,
+    ) -> RequestObservation {
+        let policy_rejected = finalization.send_state == UpstreamSendState::NotSent
+            && finalization
+                .error
+                .as_ref()
+                .is_some_and(|error| error.kind() == GatewayErrorKind::PolicyDenied);
+        let outcome = match finalization.outcome {
+            ExecutionOutcome::Succeeded => RequestObservationOutcome::Succeeded,
+            ExecutionOutcome::Failed | ExecutionOutcome::Running if policy_rejected => {
+                RequestObservationOutcome::Rejected
+            }
+            ExecutionOutcome::Failed | ExecutionOutcome::Running => {
+                RequestObservationOutcome::Failed
+            }
+            ExecutionOutcome::Cancelled => RequestObservationOutcome::Cancelled,
+            ExecutionOutcome::Incomplete => RequestObservationOutcome::Incomplete,
+        };
+        RequestObservation {
+            event_id: self.event_id(),
+            request_id: self.state.context.request_id.clone(),
+            config_revision: self.state.context.config_revision,
+            client_key_id: Some(self.state.context.client_key_id.clone()),
+            account_group_ids: Arc::clone(&self.state.context.account_group_ids),
+            extension_scope: self.state.context.extension_scope.clone(),
+            operation: self.state.context.operation,
+            requested_model: self.state.context.requested_model.clone(),
+            provider,
+            account_id: attempt.map(|attempt| attempt.provider_account_id().clone()),
+            upstream_model: attempt.and_then(|attempt| attempt.upstream_model().cloned()),
+            response_model: finalization.upstream_response_model.clone(),
+            service_tier: finalization.service_tier.clone(),
+            outcome,
+            send_state: finalization.send_state,
+            attempt_count: finalization.attempt_count,
+            client_status_code: finalization.client_status_code,
+            upstream_status_code: finalization.upstream_status_code,
+            error_kind: finalization.error.as_ref().map(GatewayError::kind),
+            retry_after_ms: finalization.retry_after_ms,
+            usage: finalization.usage.clone(),
+            cost: finalization.cost.clone(),
+            timings: finalization.timings.clone(),
+            completed_at: finalization.completed_at,
+        }
+    }
+
+    pub(super) fn dispatch(&self, observation: RequestObservation) {
+        if self
+            .state
+            .dispatched
+            .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
+            .is_err()
+        {
+            return;
+        }
+        self.state
+            .plan
+            .dispatch(self.state.generation.clone(), observation);
+    }
+
+    fn event_id(&self) -> String {
+        format!("{}:terminal", self.state.context.request_id.as_str())
+    }
+}
+
+fn duration_millis(duration: std::time::Duration) -> u64 {
+    duration.as_millis().try_into().unwrap_or(u64::MAX)
+}
 
 pub(super) struct ResponseObservation {
     pub(super) timing_started_at: Instant,
diff --git a/backend/crates/gateway-core/src/engine/policy.rs b/backend/crates/gateway-core/src/engine/policy.rs
new file mode 100644
index 000000000..1c487af6d
--- /dev/null
+++ b/backend/crates/gateway-core/src/engine/policy.rs
@@ -0,0 +1,462 @@
+//! 请求级插件路由与账号调度计划；Core 保留目标、资格和租约复核。
+
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    fmt,
+    num::NonZeroU32,
+    sync::{Arc, RwLock, Weak},
+    time::SystemTime,
+};
+
+use futures::future::BoxFuture;
+
+use crate::{
+    account::{
+        AccountCandidate, AccountSelection, AccountSelectionContext, AccountSelector,
+        ProviderAccountId,
+    },
+    engine::{extensions::ExtensionCallScope, nested::ExecutionEffects},
+    identity::ProviderKind,
+    operation::Operation,
+    policy::ClientApiKeyId,
+    routing::{AccountGroupId, PublicModelId},
+    runtime::extensions::{ExtensionSetId, ExtensionSetReference},
+};
+
+/// 模型路由插件的一次输入；正文仍保存在 `operation` 中，由 Runtime 按权限投影。
+#[derive(Clone)]
+pub struct ModelRouteInput {
+    request_id: super::ModelRequestId,
+    client_key_id: ClientApiKeyId,
+    account_group_ids: Arc<[AccountGroupId]>,
+    extension_scope: ExtensionCallScope,
+    operation: Operation,
+    requested_model: PublicModelId,
+    available_providers: BTreeSet<ProviderKind>,
+    execution_effects: Arc<ExecutionEffects>,
+}
+
+impl ModelRouteInput {
+    #[must_use]
+    pub const fn request_id(&self) -> &super::ModelRequestId {
+        &self.request_id
+    }
+
+    #[must_use]
+    pub const fn client_key_id(&self) -> &ClientApiKeyId {
+        &self.client_key_id
+    }
+
+    #[must_use]
+    pub fn account_group_ids(&self) -> &[AccountGroupId] {
+        &self.account_group_ids
+    }
+
+    #[must_use]
+    pub fn suppresses_plugin(&self, instance_id: &str) -> bool {
+        self.extension_scope.contains(instance_id)
+    }
+
+    #[must_use]
+    pub const fn operation(&self) -> &Operation {
+        &self.operation
+    }
+
+    #[must_use]
+    pub const fn requested_model(&self) -> &PublicModelId {
+        &self.requested_model
+    }
+
+    #[must_use]
+    pub const fn available_providers(&self) -> &BTreeSet<ProviderKind> {
+        &self.available_providers
+    }
+
+    /// 只供受信 Runtime 记录本次策略调用已经产生的外部副作用，不进入插件 wire。
+    #[must_use]
+    pub fn execution_effects(&self) -> Arc<ExecutionEffects> {
+        Arc::clone(&self.execution_effects)
+    }
+}
+
+impl fmt::Debug for ModelRouteInput {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("ModelRouteInput")
+            .field("request_id", &self.request_id)
+            .field("client_key_id", &self.client_key_id)
+            .field("account_group_ids", &self.account_group_ids)
+            .field("operation", &self.operation.kind())
+            .field("requested_model", &self.requested_model)
+            .field("available_providers", &self.available_providers)
+            .finish()
+    }
+}
+
+/// 模型路由结果；Runtime 区分未处理、明确拒绝和调用故障。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ModelRouteDecision {
+    Unhandled,
+    Route {
+        provider: Option<ProviderKind>,
+        model: Option<PublicModelId>,
+    },
+    Reject,
+}
+
+/// 账号调度插件可见的单个候选事实，不包含凭据或账号资料。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountScheduleCandidate {
+    account_id: ProviderAccountId,
+    weight: u16,
+    in_flight: u32,
+    maximum_concurrency: u32,
+    last_started_at: Option<SystemTime>,
+    quota_reset_at: Option<SystemTime>,
+    quota_remaining_rank: Option<u64>,
+    failure_rate_basis_points: Option<u16>,
+    first_output_latency_ms: Option<u64>,
+}
+
+impl AccountScheduleCandidate {
+    #[must_use]
+    pub const fn account_id(&self) -> &ProviderAccountId {
+        &self.account_id
+    }
+
+    #[must_use]
+    pub const fn weight(&self) -> u16 {
+        self.weight
+    }
+
+    #[must_use]
+    pub const fn in_flight(&self) -> u32 {
+        self.in_flight
+    }
+
+    #[must_use]
+    pub const fn maximum_concurrency(&self) -> u32 {
+        self.maximum_concurrency
+    }
+
+    #[must_use]
+    pub const fn last_started_at(&self) -> Option<SystemTime> {
+        self.last_started_at
+    }
+
+    #[must_use]
+    pub const fn quota_reset_at(&self) -> Option<SystemTime> {
+        self.quota_reset_at
+    }
+
+    #[must_use]
+    pub const fn quota_remaining_rank(&self) -> Option<u64> {
+        self.quota_remaining_rank
+    }
+
+    #[must_use]
+    pub const fn failure_rate_basis_points(&self) -> Option<u16> {
+        self.failure_rate_basis_points
+    }
+
+    #[must_use]
+    pub const fn first_output_latency_ms(&self) -> Option<u64> {
+        self.first_output_latency_ms
+    }
+}
+
+/// 账号调度输入；Key 与账号组仅用于 Runtime 匹配绑定，不发送给插件。
+#[derive(Debug, Clone)]
+pub struct AccountScheduleInput {
+    request_id: super::ModelRequestId,
+    attempt_index: NonZeroU32,
+    client_key_id: ClientApiKeyId,
+    account_group_ids: Arc<[AccountGroupId]>,
+    extension_scope: ExtensionCallScope,
+    provider: ProviderKind,
+    model: Option<String>,
+    candidates: Vec<AccountScheduleCandidate>,
+    execution_effects: Arc<ExecutionEffects>,
+}
+
+impl AccountScheduleInput {
+    #[must_use]
+    pub const fn request_id(&self) -> &super::ModelRequestId {
+        &self.request_id
+    }
+
+    #[must_use]
+    pub const fn attempt_index(&self) -> NonZeroU32 {
+        self.attempt_index
+    }
+
+    #[must_use]
+    pub const fn client_key_id(&self) -> &ClientApiKeyId {
+        &self.client_key_id
+    }
+
+    #[must_use]
+    pub fn account_group_ids(&self) -> &[AccountGroupId] {
+        &self.account_group_ids
+    }
+
+    #[must_use]
+    pub fn suppresses_plugin(&self, instance_id: &str) -> bool {
+        self.extension_scope.contains(instance_id)
+    }
+
+    #[must_use]
+    pub const fn provider(&self) -> &ProviderKind {
+        &self.provider
+    }
+
+    #[must_use]
+    pub fn model(&self) -> Option<&str> {
+        self.model.as_deref()
+    }
+
+    #[must_use]
+    pub fn candidates(&self) -> &[AccountScheduleCandidate] {
+        &self.candidates
+    }
+
+    /// 只供受信 Runtime 记录本次策略调用已经产生的外部副作用，不进入插件 wire。
+    #[must_use]
+    pub fn execution_effects(&self) -> Arc<ExecutionEffects> {
+        Arc::clone(&self.execution_effects)
+    }
+}
+
+/// 账号调度结果；插件选中的账号仍须通过 Core 资格复核并取得 Provider 租约。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AccountScheduleDecision {
+    Pick(ProviderAccountId),
+    Delegate,
+    Reject,
+}
+
+/// 策略调用失败不携带插件原始消息，避免跨层泄漏不可信诊断。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+#[error("request policy call failed")]
+pub struct RequestPolicyFault;
+
+/// Provider 选择器需要区分明确拒绝、策略故障和等待期间过期的选择。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+pub enum AccountPolicyError {
+    #[error("account scheduling policy rejected the request")]
+    Rejected,
+    #[error("account scheduling policy failed")]
+    Fault,
+    #[error("account scheduling candidate became stale")]
+    StaleCandidate,
+}
+
+/// 一个发布代次的不可变请求策略计划。
+pub trait RequestPolicyPlan: Send + Sync + fmt::Debug {
+    fn route_model(
+        &self,
+        input: ModelRouteInput,
+    ) -> BoxFuture<'static, Result<ModelRouteDecision, RequestPolicyFault>>;
+
+    fn schedule_account(
+        &self,
+        input: AccountScheduleInput,
+    ) -> BoxFuture<'static, Result<AccountScheduleDecision, RequestPolicyFault>>;
+}
+
+/// 同一次请求冻结的策略计划和授权身份；完整集合引用保活所有 RPC 会话。
+#[derive(Clone)]
+pub struct RequestPolicyContext {
+    plan: Arc<dyn RequestPolicyPlan>,
+    _generation: ExtensionSetReference,
+    request_id: super::ModelRequestId,
+    client_key_id: ClientApiKeyId,
+    account_group_ids: Arc<[AccountGroupId]>,
+    extension_scope: ExtensionCallScope,
+    execution_effects: Arc<ExecutionEffects>,
+}
+
+impl fmt::Debug for RequestPolicyContext {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("RequestPolicyContext")
+            .field("request_id", &self.request_id)
+            .field("client_key_id", &self.client_key_id)
+            .field("account_group_ids", &self.account_group_ids)
+            .finish_non_exhaustive()
+    }
+}
+
+impl RequestPolicyContext {
+    #[must_use]
+    pub fn new(
+        plan: Arc<dyn RequestPolicyPlan>,
+        generation: ExtensionSetReference,
+        request_id: super::ModelRequestId,
+        client_key_id: ClientApiKeyId,
+        mut account_group_ids: Vec<AccountGroupId>,
+    ) -> Self {
+        account_group_ids.sort();
+        account_group_ids.dedup();
+        Self {
+            plan,
+            _generation: generation,
+            request_id,
+            client_key_id,
+            account_group_ids: account_group_ids.into(),
+            extension_scope: ExtensionCallScope::default(),
+            execution_effects: Arc::new(ExecutionEffects::default()),
+        }
+    }
+
+    /// 附着父子调用图；计划必须跳过集合中的实例，防止直接或间接重入。
+    #[must_use]
+    pub fn with_extension_scope(mut self, extension_scope: ExtensionCallScope) -> Self {
+        self.extension_scope = extension_scope;
+        self
+    }
+
+    #[must_use]
+    pub(crate) fn with_execution_effects(mut self, effects: Arc<ExecutionEffects>) -> Self {
+        self.execution_effects = effects;
+        self
+    }
+
+    #[must_use]
+    pub fn extension_scope(&self) -> &ExtensionCallScope {
+        &self.extension_scope
+    }
+
+    pub async fn route_model(
+        &self,
+        operation: Operation,
+        requested_model: PublicModelId,
+        available_providers: BTreeSet<ProviderKind>,
+    ) -> Result<ModelRouteDecision, RequestPolicyFault> {
+        self.plan
+            .route_model(ModelRouteInput {
+                request_id: self.request_id.clone(),
+                client_key_id: self.client_key_id.clone(),
+                account_group_ids: Arc::clone(&self.account_group_ids),
+                extension_scope: self.extension_scope.clone(),
+                operation,
+                requested_model,
+                available_providers,
+                execution_effects: Arc::clone(&self.execution_effects),
+            })
+            .await
+    }
+
+    /// 硬绑定已在候选资格中收窄；插件先决定，委托时再采用内置亲和与排序。
+    pub async fn select_account<'a>(
+        &self,
+        attempt_index: NonZeroU32,
+        provider: &ProviderKind,
+        model: Option<&str>,
+        candidates: &'a [AccountCandidate],
+        context: &AccountSelectionContext,
+    ) -> Result<Option<AccountSelection<'a>>, AccountPolicyError> {
+        let eligible = AccountSelector.policy_candidates(candidates, context);
+        if eligible.is_empty() {
+            return Ok(None);
+        }
+        let policy = context.policy;
+        let projected = eligible
+            .iter()
+            .map(|candidate| AccountScheduleCandidate {
+                account_id: candidate.account.id().clone(),
+                weight: candidate.account.weight().get(),
+                in_flight: candidate.signals.in_flight,
+                maximum_concurrency: candidate
+                    .account
+                    .effective_concurrency(policy.max_concurrent_per_account())
+                    .get(),
+                last_started_at: candidate.signals.last_started_at,
+                quota_reset_at: candidate.signals.quota_reset_at,
+                quota_remaining_rank: candidate.signals.quota_remaining_rank,
+                failure_rate_basis_points: candidate.signals.failure_rate_basis_points,
+                first_output_latency_ms: candidate.signals.first_output_latency_ms,
+            })
+            .collect();
+        let decision = self
+            .plan
+            .schedule_account(AccountScheduleInput {
+                request_id: self.request_id.clone(),
+                attempt_index,
+                client_key_id: self.client_key_id.clone(),
+                account_group_ids: Arc::clone(&self.account_group_ids),
+                extension_scope: self.extension_scope.clone(),
+                provider: provider.clone(),
+                model: model.map(str::to_owned),
+                candidates: projected,
+                execution_effects: Arc::clone(&self.execution_effects),
+            })
+            .await
+            .map_err(|_| AccountPolicyError::Fault)?;
+        // 插件调用可能消耗显著时间；无论插件选择还是委托，均用返回时刻重新执行
+        // 同一资格判断，不能让调用前尚未过期的候选在调用后被内置策略选中。
+        let mut current = context.clone();
+        current.now = SystemTime::now();
+        match decision {
+            AccountScheduleDecision::Delegate => AccountSelector
+                .select(candidates, &current)
+                .map(Some)
+                .ok_or(AccountPolicyError::StaleCandidate),
+            AccountScheduleDecision::Reject => Err(AccountPolicyError::Rejected),
+            AccountScheduleDecision::Pick(account_id) => {
+                if !eligible
+                    .iter()
+                    .any(|candidate| candidate.account.id() == &account_id)
+                {
+                    return Err(AccountPolicyError::Fault);
+                }
+                AccountSelector
+                    .select_policy_candidate(candidates, &current, &account_id)
+                    .map(Some)
+                    .ok_or(AccountPolicyError::StaleCandidate)
+            }
+        }
+    }
+}
+
+/// 策略计划注册冲突；同一代次不能被静默替换。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+#[error("request policy generation is already registered")]
+pub struct RequestPolicyRegistrationError;
+
+/// 按发布集合解析策略计划的非拥有索引。
+#[derive(Clone, Default)]
+pub struct RequestPolicyExtensionIndex {
+    sets: Arc<RwLock<BTreeMap<ExtensionSetId, Weak<dyn RequestPolicyPlan>>>>,
+}
+
+impl RequestPolicyExtensionIndex {
+    pub fn register(
+        &self,
+        id: ExtensionSetId,
+        plan: Arc<dyn RequestPolicyPlan>,
+    ) -> Result<Arc<dyn RequestPolicyPlan>, RequestPolicyRegistrationError> {
+        let mut sets = self
+            .sets
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        sets.retain(|_, plan| plan.strong_count() > 0);
+        if sets.contains_key(&id) {
+            return Err(RequestPolicyRegistrationError);
+        }
+        sets.insert(id, Arc::downgrade(&plan));
+        Ok(plan)
+    }
+
+    #[must_use]
+    pub fn resolve(
+        &self,
+        generation: &ExtensionSetReference,
+    ) -> Option<Arc<dyn RequestPolicyPlan>> {
+        self.sets
+            .read()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .get(generation.id())
+            .and_then(Weak::upgrade)
+    }
+}
diff --git a/backend/crates/gateway-core/src/engine/probe.rs b/backend/crates/gateway-core/src/engine/probe.rs
index 6980a2960..6e434978c 100644
--- a/backend/crates/gateway-core/src/engine/probe.rs
+++ b/backend/crates/gateway-core/src/engine/probe.rs
@@ -162,8 +162,10 @@ impl From<GatewayError> for AccountProbeError {
 }
 
 pub trait AccountProbe: Send + Sync {
+    /// 插件管理操作传入其冻结快照；未绑定动态 Provider 的调用可使用当前发布视图。
     fn probe(
         &self,
         request: AccountProbeRequest,
+        snapshot: Option<std::sync::Arc<crate::routing::RuntimeSnapshot>>,
     ) -> BoxFuture<'_, Result<AccountProbeResult, AccountProbeError>>;
 }
diff --git a/backend/crates/gateway-core/src/engine/provider.rs b/backend/crates/gateway-core/src/engine/provider.rs
index 5bb50ea02..b0e0221cd 100644
--- a/backend/crates/gateway-core/src/engine/provider.rs
+++ b/backend/crates/gateway-core/src/engine/provider.rs
@@ -1,6 +1,6 @@
 //! Provider 的唯一动态执行边界。
 
-use std::collections::BTreeMap;
+use std::collections::{BTreeMap, VecDeque};
 use std::fmt;
 use std::pin::Pin;
 use std::sync::Arc;
@@ -8,15 +8,21 @@ use std::task::{Context, Poll};
 use std::time::Instant;
 
 use async_trait::async_trait;
-use futures::{Stream, future::BoxFuture};
+use bytes::Bytes;
+use futures::{Stream, StreamExt, future::BoxFuture};
 use thiserror::Error;
 
 use crate::account::{
     AccountAttemptFeedback, AccountCapacitySnapshot, AccountFeedbackStats, ProviderAccountId,
 };
 use crate::engine::AttemptContext;
+use crate::engine::execution::ClientTransport;
+use crate::engine::middleware::{
+    MiddlewareBody, MiddlewareContext, MiddlewareError, MiddlewareFrame, MiddlewareFraming,
+    MiddlewareHeader, MiddlewareNext, MiddlewareRequest, MiddlewareResponse,
+};
 use crate::error::{PreDeliveryRetry, ProviderError, ProviderErrorKind};
-use crate::event::{EventSequenceValidator, ProviderEvent};
+use crate::event::{EventSequenceValidator, GatewayEvent, ProtocolWireEvent, ProviderEvent};
 use crate::identity::ProviderKind;
 use crate::operation::Operation;
 use crate::policy::ClientApiKeyId;
@@ -176,6 +182,30 @@ pub trait ResourceLease: Send + Sync + 'static {}
 
 impl<T> ResourceLease for T where T: Send + Sync + 'static {}
 
+/// Provider 原生响应格式到统一响应格式的有状态转换边界。
+///
+/// Core 只负责调用顺序、格式与终态约束，不解释协议正文。实现必须由一次
+/// [`ProviderStream`] 独占，不能在并发请求间共享可变转换状态。
+pub trait NativeResponseTranslator: Send + 'static {
+    /// 转换前协议格式。
+    fn source_protocol(&self) -> &str;
+
+    /// 转换后协议格式。
+    fn target_protocol(&self) -> &str;
+
+    /// 把一个原生响应事件转换为零至多个统一响应事件。
+    ///
+    /// # Errors
+    ///
+    /// 原生协议事件无效或转换状态不一致时返回已发送的 Provider 错误。
+    fn translate(
+        &mut self,
+        event: &crate::event::ProtocolWireEvent,
+    ) -> Result<Vec<crate::event::ProtocolWireEvent>, ProviderError>;
+}
+
+const MAX_NATIVE_RESPONSE_EVENTS_PER_INPUT: usize = 64;
+
 /// Metadata、canonical event stream 与 owned lease 的统一返回值。
 ///
 /// 底层 stream 必须是 cold stream：在第一次 poll 前不得发送请求级 handshake
@@ -184,6 +214,7 @@ pub struct ProviderStream {
     metadata: ProviderCallMetadata,
     events: EventStream,
     _lease: Box<dyn ResourceLease>,
+    native_response_translator: Option<Box<dyn NativeResponseTranslator>>,
     account_feedback: Option<ProviderStreamAccountFeedback>,
     validator: EventSequenceValidator,
     strict_canonical_seen: bool,
@@ -290,6 +321,7 @@ impl ProviderStream {
             metadata,
             events: Box::pin(events),
             _lease: Box::new(lease),
+            native_response_translator: None,
             account_feedback: None,
             validator: EventSequenceValidator::new(),
             strict_canonical_seen: false,
@@ -315,6 +347,80 @@ impl ProviderStream {
         self
     }
 
+    /// 在原生响应加工的两个策略阶段之间安装 Provider 自有转换器。
+    #[must_use]
+    pub fn with_native_response_translator(
+        mut self,
+        translator: impl NativeResponseTranslator,
+    ) -> Self {
+        self.native_response_translator = Some(Box::new(translator));
+        self
+    }
+
+    /// 返回本次 stream 是否需要原生响应转换。
+    #[must_use]
+    pub const fn has_native_response_translator(&self) -> bool {
+        self.native_response_translator.is_some()
+    }
+
+    /// 在 Core 已记录原始事实且完成 `BeforeTranslation` 后执行原生转换。
+    ///
+    /// # Errors
+    ///
+    /// source/target 格式不一致、单事件展开越界、终态被丢弃或 Provider 转换失败时
+    /// 返回错误。
+    pub fn translate_native_response(
+        &mut self,
+        mut event: ProviderEvent,
+        terminal: bool,
+    ) -> Result<Vec<ProviderEvent>, ProviderError> {
+        let Some(translator) = self.native_response_translator.as_mut() else {
+            return Ok(vec![event]);
+        };
+        let middleware_transformed = event.middleware_transformed();
+        let Some(wire) = event.wire_event() else {
+            return Ok(vec![event]);
+        };
+        if wire.protocol() != translator.source_protocol() {
+            return Err(native_response_protocol_error());
+        }
+        let mut translated = translator.translate(wire)?;
+        if translated.len() > MAX_NATIVE_RESPONSE_EVENTS_PER_INPUT
+            || (terminal && translated.is_empty())
+            || translated
+                .iter()
+                .any(|wire| wire.protocol() != translator.target_protocol())
+        {
+            return Err(native_response_protocol_error());
+        }
+        let Some(last) = translated.pop() else {
+            // wire 转换器可以吞掉纯协议结构事件，但不能连带丢失 Core 已经
+            // 识别出的 usage 等 canonical facts。facts-only 封套仍需交给
+            // 客户端 adapter；没有 facts 时才是真正的零输出。
+            event.replace_wire(None);
+            return Ok(event
+                .has_canonical_facts()
+                .then_some(event)
+                .into_iter()
+                .collect());
+        };
+        // 一对多时把 canonical/observation/session 信封放到最后一个 wire；这样
+        // `Completed` 不会在同一源事件的前置输出交付前提前终结 Coordinator。
+        let mut events = translated
+            .into_iter()
+            .map(|wire| {
+                let mut translated_event = ProviderEvent::wire(wire);
+                if middleware_transformed {
+                    translated_event.inherit_middleware_provenance(&event);
+                }
+                translated_event
+            })
+            .collect::<Vec<_>>();
+        event.replace_wire(Some(last));
+        events.push(event);
+        Ok(events)
+    }
+
     fn set_account_feedback(
         &mut self,
         stats: Arc<AccountFeedbackStats>,
@@ -336,6 +442,401 @@ impl ProviderStream {
     pub const fn metadata(&self) -> &ProviderCallMetadata {
         &self.metadata
     }
+
+    fn middleware_protocol(&self, fallback: &str) -> String {
+        self.native_response_translator.as_ref().map_or_else(
+            || fallback.to_owned(),
+            |translator| translator.target_protocol().to_owned(),
+        )
+    }
+}
+
+/// Attempt 中间件消费一次后建立 cold Provider stream 的 owned terminal。
+pub type ProviderMiddlewareTerminal = Box<
+    dyn FnOnce(
+            Operation,
+            Vec<MiddlewareHeader>,
+        ) -> BoxFuture<'static, Result<ProviderStream, ProviderError>>
+        + Send
+        + 'static,
+>;
+
+const MAX_ATTEMPT_HEADERS: usize = 128;
+const MAX_ATTEMPT_HEADER_NAME_BYTES: usize = 128;
+const MAX_ATTEMPT_HEADER_VALUE_BYTES: usize = 16 * 1024;
+const MAX_ATTEMPT_HEADER_TOTAL_BYTES: usize = 64 * 1024;
+
+struct ProviderMiddlewareNext {
+    operation: Operation,
+    transport: ClientTransport,
+    terminal: Option<ProviderMiddlewareTerminal>,
+}
+
+impl MiddlewareNext for ProviderMiddlewareNext {
+    fn run(
+        mut self: Box<Self>,
+        request: MiddlewareRequest,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        Box::pin(async move {
+            let fallback_protocol = self.operation.protocol().to_owned();
+            let (protocol, headers, body) = request.into_parts();
+            validate_attempt_headers(&headers)?;
+            let operation = self
+                .operation
+                .replace_middleware_wire(protocol, body)
+                .map_err(|_| MiddlewareError::InvalidState)?;
+            let terminal = self.terminal.take().ok_or(MiddlewareError::InvalidState)?;
+            let stream = terminal(operation, headers)
+                .await
+                .map_err(MiddlewareError::Provider)?;
+            let metadata = stream.metadata().clone();
+            let protocol = stream.middleware_protocol(&fallback_protocol);
+            let body = ProviderMiddlewareBody {
+                stream,
+                pending: VecDeque::new(),
+                transport: self.transport,
+            };
+            Ok(
+                MiddlewareResponse::new(protocol, 200, Vec::new(), Box::new(body))
+                    .with_provider_metadata(metadata),
+            )
+        })
+    }
+}
+
+fn validate_attempt_headers(headers: &[MiddlewareHeader]) -> Result<(), MiddlewareError> {
+    if headers.len() > MAX_ATTEMPT_HEADERS {
+        return Err(MiddlewareError::InvalidState);
+    }
+    let mut total = 0_usize;
+    for header in headers {
+        let name = header.name();
+        let normalized = name.to_ascii_lowercase();
+        if name.is_empty()
+            || name.len() > MAX_ATTEMPT_HEADER_NAME_BYTES
+            || !name
+                .bytes()
+                .all(|byte| byte.is_ascii_alphanumeric() || b"!#$%&'*+-.^_`|~".contains(&byte))
+            || header.value().len() > MAX_ATTEMPT_HEADER_VALUE_BYTES
+            || header
+                .value()
+                .iter()
+                .any(|byte| *byte != b'\t' && (*byte < b' ' || *byte == 0x7f))
+            || attempt_header_is_protected(&normalized)
+        {
+            return Err(MiddlewareError::InvalidState);
+        }
+        total = total
+            .checked_add(name.len())
+            .and_then(|value| value.checked_add(header.value().len()))
+            .ok_or(MiddlewareError::InvalidState)?;
+        if total > MAX_ATTEMPT_HEADER_TOTAL_BYTES {
+            return Err(MiddlewareError::InvalidState);
+        }
+    }
+    Ok(())
+}
+
+fn attempt_header_is_protected(name: &str) -> bool {
+    name.contains("auth")
+        || name.contains("credential")
+        || name.contains("secret")
+        || name.contains("token")
+        || name.contains("cookie")
+        || name.contains("session")
+        || name.contains("conversation")
+        || name.contains("thread")
+        || name.contains("account")
+        || name.contains("organization")
+        || name.contains("project")
+        || name.contains("tenant")
+        || name.contains("principal")
+        || name.contains("identity")
+        || name.contains("user-id")
+        || name.ends_with("-key")
+        || name.ends_with("_key")
+        || name.starts_with("sec-websocket-")
+        || matches!(
+            name,
+            "connection"
+                | "keep-alive"
+                | "proxy-connection"
+                | "proxy-authenticate"
+                | "proxy-authorization"
+                | "te"
+                | "trailer"
+                | "transfer-encoding"
+                | "upgrade"
+                | "host"
+                | "content-length"
+                | "content-type"
+                | "content-encoding"
+                | "accept"
+                | "accept-encoding"
+                | "user-agent"
+                | "x-request-id"
+                | "x-gateway-request-id"
+        )
+}
+
+struct ProviderMiddlewareBody {
+    stream: ProviderStream,
+    pending: VecDeque<(ProviderEvent, bool)>,
+    transport: ClientTransport,
+}
+
+impl MiddlewareBody for ProviderMiddlewareBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async move {
+            loop {
+                if let Some((event, terminal)) = self.pending.pop_front() {
+                    return provider_event_to_middleware_frame(event, self.transport, terminal)
+                        .map(Some)
+                        .map_err(MiddlewareError::Provider);
+                }
+                let Some(event) = self.stream.next().await else {
+                    return Ok(None);
+                };
+                let event = event.map_err(MiddlewareError::Provider)?;
+                let terminal = event
+                    .canonical_facts()
+                    .iter()
+                    .any(|fact| matches!(fact, GatewayEvent::Completed(_)));
+                let translated = self
+                    .stream
+                    .translate_native_response(event, terminal)
+                    .map_err(MiddlewareError::Provider)?;
+                let last = translated.len().saturating_sub(1);
+                self.pending.extend(
+                    translated
+                        .into_iter()
+                        .enumerate()
+                        .map(|(index, event)| (event, terminal && index == last)),
+                );
+            }
+        })
+    }
+
+    fn close(self: Box<Self>) -> BoxFuture<'static, ()> {
+        Box::pin(async move { drop(self) })
+    }
+}
+
+fn provider_event_to_middleware_frame(
+    event: ProviderEvent,
+    transport: ClientTransport,
+    terminal: bool,
+) -> Result<MiddlewareFrame, ProviderError> {
+    let Some(wire) = event.wire_event() else {
+        return Ok(MiddlewareFrame::from_provider_event(
+            Bytes::new(),
+            MiddlewareFraming::RawBytes,
+            terminal,
+            event,
+        ));
+    };
+    let (bytes, framing) = match transport {
+        ClientTransport::HttpSse => (
+            wire.raw_sse_frame()
+                .cloned()
+                .map_or_else(|| encode_sse_wire_event(wire), Ok)?,
+            MiddlewareFraming::SseEvent,
+        ),
+        ClientTransport::HttpJson => (
+            wire.raw_json_body()
+                .or_else(|| wire.raw_http_body_bytes())
+                .cloned()
+                .map_or_else(|| serde_json::to_vec(wire.data()).map(Bytes::from), Ok)
+                .map_err(|_| middleware_protocol_error(UpstreamSendState::Sent))?,
+            MiddlewareFraming::JsonDocument,
+        ),
+        ClientTransport::WebSocket
+        | ClientTransport::InternalProbe
+        | ClientTransport::InternalPlugin => (
+            serde_json::to_vec(wire.data())
+                .map(Bytes::from)
+                .map_err(|_| middleware_protocol_error(UpstreamSendState::Sent))?,
+            MiddlewareFraming::JsonDocument,
+        ),
+    };
+    Ok(MiddlewareFrame::from_provider_event(
+        bytes, framing, terminal, event,
+    ))
+}
+
+fn encode_sse_wire_event(wire: &ProtocolWireEvent) -> Result<Bytes, ProviderError> {
+    let mut encoded = Vec::new();
+    if let Some(id) = wire.sse_id() {
+        encoded.extend_from_slice(b"id: ");
+        encoded.extend_from_slice(id.as_bytes());
+        encoded.push(b'\n');
+    }
+    if let Some(retry) = wire.sse_retry() {
+        encoded.extend_from_slice(format!("retry: {retry}\n").as_bytes());
+    }
+    if let Some(event_type) = wire.event_type() {
+        encoded.extend_from_slice(b"event: ");
+        encoded.extend_from_slice(event_type.as_bytes());
+        encoded.push(b'\n');
+    }
+    encoded.extend_from_slice(b"data: ");
+    serde_json::to_writer(&mut encoded, wire.data())
+        .map_err(|_| middleware_protocol_error(UpstreamSendState::Sent))?;
+    encoded.extend_from_slice(b"\n\n");
+    Ok(Bytes::from(encoded))
+}
+
+/// 执行每次 retry 都重新建立的 attempt 中间件链。
+pub async fn execute_attempt_middleware(
+    plan: Option<&crate::engine::middleware::FrozenMiddlewarePlan>,
+    context: MiddlewareContext,
+    operation: Operation,
+    transport: ClientTransport,
+    terminal: ProviderMiddlewareTerminal,
+) -> Result<ProviderStream, ProviderError> {
+    let Some(plan) = plan else {
+        return terminal(operation, Vec::new()).await;
+    };
+    let request = MiddlewareRequest::new(
+        operation.protocol(),
+        Vec::<MiddlewareHeader>::new(),
+        operation
+            .middleware_body()
+            .map_err(|_| middleware_protocol_error(UpstreamSendState::NotSent))?,
+    );
+    let response = plan
+        .handle(
+            context,
+            request,
+            Box::new(ProviderMiddlewareNext {
+                operation,
+                transport,
+                terminal: Some(terminal),
+            }),
+        )
+        .await
+        .map_err(middleware_prepare_error)?;
+    let (protocol, status_code, headers, body, envelope) = response.into_parts();
+    if status_code != 200 || !headers.is_empty() {
+        return Err(middleware_protocol_error(UpstreamSendState::NotSent));
+    }
+    crate::validation::validate_text(&protocol, 64, true, None)
+        .map_err(|_| middleware_protocol_error(UpstreamSendState::NotSent))?;
+    let metadata = envelope
+        .ok_or_else(|| middleware_protocol_error(UpstreamSendState::NotSent))?
+        .into_provider_metadata();
+    let events = futures::stream::try_unfold((body, protocol), |(mut body, protocol)| async move {
+        let Some(frame) = body.next_frame().await.map_err(middleware_body_error)? else {
+            return Ok(None);
+        };
+        let event = middleware_frame_to_provider_event(frame, &protocol)?;
+        Ok(Some((event, (body, protocol))))
+    });
+    Ok(ProviderStream::new(metadata, events, ()))
+}
+
+fn middleware_frame_to_provider_event(
+    frame: MiddlewareFrame,
+    protocol: &str,
+) -> Result<ProviderEvent, ProviderError> {
+    let transformed = frame.transformed();
+    let (bytes, framing, _, mut envelope) = frame.into_provider_parts();
+    // 透传不能把已解析的事件降格成 raw bytes，否则 Responses 会丢失终态和 WS 帧。
+    // 同时核对正文，避免进程内中间件漏标 transformed 时忽略了实际改写。
+    if let Some(event) = envelope.as_ref()
+        && let Some(wire) = event
+            .wire_event()
+            .filter(|wire| wire.protocol() == protocol)
+    {
+        let original = match framing {
+            MiddlewareFraming::JsonDocument => wire
+                .raw_json_body()
+                .or_else(|| wire.raw_http_body_bytes())
+                .cloned()
+                .or_else(|| serde_json::to_vec(wire.data()).ok().map(Bytes::from)),
+            MiddlewareFraming::SseEvent => wire
+                .raw_sse_frame()
+                .cloned()
+                .or_else(|| encode_sse_wire_event(wire).ok()),
+            MiddlewareFraming::RawBytes => wire.raw_http_body_bytes().cloned(),
+        };
+        if original.as_ref() == Some(&bytes)
+            && let Some(mut event) = envelope.take()
+        {
+            if transformed {
+                event.mark_middleware_transformed();
+            }
+            return Ok(event);
+        }
+    }
+    let wire = if bytes.is_empty() {
+        None
+    } else {
+        Some(
+            match framing {
+                MiddlewareFraming::JsonDocument => ProtocolWireEvent::raw_json(protocol, bytes),
+                MiddlewareFraming::SseEvent => ProtocolWireEvent::raw_sse(protocol, bytes),
+                MiddlewareFraming::RawBytes => ProtocolWireEvent::raw_http_body(protocol, bytes),
+            }
+            .map_err(|_| middleware_protocol_error(UpstreamSendState::Ambiguous))?,
+        )
+    };
+    if let Some(mut event) = envelope {
+        if transformed {
+            event.replace_middleware_wire(wire);
+        } else {
+            event.replace_wire(wire);
+        }
+        return Ok(event);
+    }
+    let mut event = wire
+        .map(ProviderEvent::wire)
+        .ok_or_else(|| middleware_protocol_error(UpstreamSendState::Ambiguous))?;
+    if transformed {
+        event.mark_middleware_transformed();
+    }
+    Ok(event)
+}
+
+fn middleware_prepare_error(error: MiddlewareError) -> ProviderError {
+    match error {
+        MiddlewareError::Provider(error) => error,
+        MiddlewareError::Rejected => ProviderError::new(
+            ProviderErrorKind::RequestPolicyDenied,
+            UpstreamSendState::NotSent,
+        ),
+        MiddlewareError::Fault
+        | MiddlewareError::InvalidState
+        | MiddlewareError::Gateway(_)
+        | MiddlewareError::Engine(_) => middleware_protocol_error(UpstreamSendState::NotSent),
+    }
+}
+
+fn middleware_body_error(error: MiddlewareError) -> ProviderError {
+    match error {
+        MiddlewareError::Provider(error) => error,
+        MiddlewareError::Rejected => ProviderError::new(
+            ProviderErrorKind::RequestPolicyDenied,
+            UpstreamSendState::Ambiguous,
+        ),
+        MiddlewareError::Fault
+        | MiddlewareError::InvalidState
+        | MiddlewareError::Gateway(_)
+        | MiddlewareError::Engine(_) => middleware_protocol_error(UpstreamSendState::Ambiguous),
+    }
+}
+
+fn middleware_protocol_error(send_state: UpstreamSendState) -> ProviderError {
+    ProviderError::new(ProviderErrorKind::Protocol, send_state)
+        .redact_sensitive_context("invalid middleware boundary")
+}
+
+fn native_response_protocol_error() -> ProviderError {
+    ProviderError::new(
+        ProviderErrorKind::Protocol,
+        crate::upstream::UpstreamSendState::Sent,
+    )
+    .redact_sensitive_context("invalid native response translation")
 }
 
 impl Stream for ProviderStream {
@@ -491,8 +992,15 @@ pub trait Provider: Send + Sync {
         Ok(configuration.clone())
     }
 
-    /// 返回编译期注册名称。
-    fn name(&self) -> &'static str;
+    /// 没有持久选择时返回 Provider 的已准备默认画像；结果仍由 Core 按请求冻结。
+    fn default_request_profile(
+        &self,
+    ) -> Result<Option<crate::account::OpaqueProviderData>, ProviderError> {
+        Ok(None)
+    }
+
+    /// 返回实例生命周期内稳定的注册名称。
+    fn name(&self) -> &str;
 
     /// 返回当前进程已经成功发布的目录代次。
     fn catalog_generation(&self) -> ProviderCatalogGeneration;
@@ -545,7 +1053,7 @@ pub trait Provider: Send + Sync {
     /// 没有可用资源、请求无效或准备失败时返回 `NotSent` 错误；
     /// 可能已发送的失败必须通过 stream 返回，不得降级发送事实。
     async fn execute(
-        &self,
+        self: Arc<Self>,
         request: ProviderRequest,
         context: AttemptContext,
     ) -> Result<ProviderStream, ProviderError>;
@@ -554,6 +1062,10 @@ pub trait Provider: Send + Sync {
 /// Provider Registry 构建错误。
 #[derive(Debug, Clone, PartialEq, Eq, Error)]
 pub enum RegistryError {
+    #[error("provider extension generation is unavailable")]
+    GenerationUnavailable,
+    #[error("provider extension generation is already registered")]
+    DuplicateGeneration,
     /// Provider 名称无效。
     #[error("invalid provider registry name")]
     InvalidName,
@@ -601,17 +1113,41 @@ impl ProviderRegistryBuilder {
     pub fn build(self) -> ProviderRegistry {
         ProviderRegistry {
             providers: Arc::new(self.providers),
+            extensions: None,
+            lease: None,
         }
     }
 }
 
-/// Bootstrap 后不可变的 Provider Registry。
+/// 不可变 Provider 视图；动态入口按请求冻结的集合解析。
 #[derive(Clone, Default)]
 pub struct ProviderRegistry {
-    providers: Arc<BTreeMap<ProviderKind, Arc<dyn Provider>>>,
+    pub(super) providers: Arc<BTreeMap<ProviderKind, Arc<dyn Provider>>>,
+    pub(super) extensions: Option<super::extensions::ProviderExtensionIndex>,
+    pub(super) lease: Option<crate::runtime::extensions::ExtensionSetReference>,
 }
 
 impl ProviderRegistry {
+    pub fn for_extensions(
+        &self,
+        reference: Option<&crate::runtime::extensions::ExtensionSetReference>,
+    ) -> Result<Self, RegistryError> {
+        let Some(index) = &self.extensions else {
+            return Ok(self.clone());
+        };
+        let reference = reference.ok_or(RegistryError::GenerationUnavailable)?;
+        if !reference.can_serve() {
+            return Err(RegistryError::GenerationUnavailable);
+        }
+        let mut registry = index
+            .resolve(reference.id())
+            .ok_or(RegistryError::GenerationUnavailable)?
+            .as_ref()
+            .clone();
+        registry.lease = Some(reference.clone());
+        Ok(registry)
+    }
+
     /// 从一组异构 Provider 构造冻结注册表。
     pub fn new(
         providers: impl IntoIterator<Item = Arc<dyn Provider>>,
@@ -669,6 +1205,15 @@ impl ProviderRegistry {
 }
 
 impl ProviderCatalogPort for ProviderRegistry {
+    fn for_extensions(
+        &self,
+        reference: Option<&crate::runtime::extensions::ExtensionSetReference>,
+    ) -> Result<Option<Arc<dyn ProviderCatalogPort>>, ProviderCatalogUnavailable> {
+        self.for_extensions(reference)
+            .map(|registry| Some(Arc::new(registry) as Arc<dyn ProviderCatalogPort>))
+            .map_err(|_| ProviderCatalogUnavailable)
+    }
+
     fn model_catalog_is_exhaustive(&self, provider: &ProviderKind) -> bool {
         self.providers
             .get(provider)
diff --git a/backend/crates/gateway-core/src/error.rs b/backend/crates/gateway-core/src/error.rs
index 7c8eb8876..5caedebfd 100644
--- a/backend/crates/gateway-core/src/error.rs
+++ b/backend/crates/gateway-core/src/error.rs
@@ -28,6 +28,8 @@ pub enum ProviderErrorKind {
     Unauthorized,
     /// Credential 没有权限。
     PermissionDenied,
+    /// 冻结的请求策略在 Provider 发送前明确拒绝本次请求。
+    RequestPolicyDenied,
     /// Provider 限流。
     RateLimited,
     /// Credential 配额耗尽。
@@ -66,6 +68,7 @@ impl ProviderErrorKind {
             Self::Unsupported => "unsupported",
             Self::Unauthorized => "unauthorized",
             Self::PermissionDenied => "permission_denied",
+            Self::RequestPolicyDenied => "request_policy_denied",
             Self::RateLimited => "rate_limited",
             Self::QuotaExhausted => "quota_exhausted",
             Self::AccountCapacityUnavailable => "account_capacity_unavailable",
@@ -1079,6 +1082,10 @@ impl GatewayError {
                 GatewayErrorKind::UpstreamUnavailable,
                 "upstream authentication resource is unavailable",
             ),
+            ProviderErrorKind::RequestPolicyDenied => Self::new(
+                GatewayErrorKind::PolicyDenied,
+                "request policy rejected the request",
+            ),
             ProviderErrorKind::RateLimited | ProviderErrorKind::QuotaExhausted => Self::new(
                 GatewayErrorKind::RateLimited,
                 "upstream capacity is temporarily unavailable",
diff --git a/backend/crates/gateway-core/src/event.rs b/backend/crates/gateway-core/src/event.rs
index 2b98272e9..d82d42f5f 100644
--- a/backend/crates/gateway-core/src/event.rs
+++ b/backend/crates/gateway-core/src/event.rs
@@ -2,6 +2,7 @@
 
 use std::collections::BTreeMap;
 use std::fmt;
+use std::sync::Arc;
 
 use bytes::Bytes;
 use serde_json::Value;
@@ -202,6 +203,7 @@ pub struct ProtocolWireEvent {
     has_json_data: bool,
     raw_sse_frame: Option<Bytes>,
     raw_json_body: Option<Bytes>,
+    raw_http_body: Option<Bytes>,
     sse_id: Option<String>,
     sse_retry: Option<u64>,
 }
@@ -241,6 +243,7 @@ impl ProtocolWireEvent {
             has_json_data: true,
             raw_sse_frame: None,
             raw_json_body: None,
+            raw_http_body: None,
             sse_id,
             sse_retry,
         })
@@ -288,6 +291,7 @@ impl ProtocolWireEvent {
             has_json_data: false,
             raw_sse_frame: Some(raw_sse_frame),
             raw_json_body: None,
+            raw_http_body: None,
             sse_id: None,
             sse_retry: None,
         })
@@ -313,6 +317,31 @@ impl ProtocolWireEvent {
             has_json_data: false,
             raw_sse_frame: None,
             raw_json_body: Some(raw_json_body),
+            raw_http_body: None,
+            sse_id: None,
+            sse_retry: None,
+        })
+    }
+
+    /// 创建未经改写的 HTTP 响应正文片段；正文不要求为 JSON。
+    ///
+    /// # Errors
+    ///
+    /// 协议名不满足内部路由标识约束时返回错误。
+    pub fn raw_http_body(
+        protocol: impl Into<String>,
+        raw_http_body: Bytes,
+    ) -> Result<Self, IdentifierError> {
+        let protocol = protocol.into();
+        validate_text(&protocol, 64, true, None)?;
+        Ok(Self {
+            protocol,
+            event_type: None,
+            data: Value::Null,
+            has_json_data: false,
+            raw_sse_frame: None,
+            raw_json_body: None,
+            raw_http_body: Some(raw_http_body),
             sse_id: None,
             sse_retry: None,
         })
@@ -372,6 +401,18 @@ impl ProtocolWireEvent {
         self.raw_json_body
     }
 
+    /// 返回可直接交付给 HTTP 客户端的任意响应正文片段。
+    #[must_use]
+    pub const fn raw_http_body_bytes(&self) -> Option<&Bytes> {
+        self.raw_http_body.as_ref()
+    }
+
+    /// 拆出未经改写的 HTTP 响应正文片段。
+    #[must_use]
+    pub fn into_raw_http_body(self) -> Option<Bytes> {
+        self.raw_http_body
+    }
+
     /// 拆出协议原生 JSON 数据。
     #[must_use]
     pub fn into_data(self) -> Value {
@@ -388,6 +429,7 @@ impl fmt::Debug for ProtocolWireEvent {
             .field("has_json_data", &self.has_json_data)
             .field("has_raw_sse_frame", &self.raw_sse_frame.is_some())
             .field("has_raw_json_body", &self.raw_json_body.is_some())
+            .field("has_raw_http_body", &self.raw_http_body.is_some())
             .field("has_sse_id", &self.sse_id.is_some())
             .field("sse_retry", &self.sse_retry)
             .field("data", &"<not included in Debug>")
@@ -734,6 +776,8 @@ pub struct ProviderEvent {
     wire: Option<Box<ProtocolWireEvent>>,
     observation: Option<Box<ProviderResponseObservation>>,
     session_update: Option<Box<ProviderSessionState>>,
+    middleware_transformed: bool,
+    middleware_origin_wire: Option<Arc<ProtocolWireEvent>>,
 }
 
 impl ProviderEvent {
@@ -745,9 +789,18 @@ impl ProviderEvent {
             wire: None,
             observation: None,
             session_update: None,
+            middleware_transformed: false,
+            middleware_origin_wire: None,
         }
     }
 
+    /// 附加同一上游事件产生的业务事实，不重复生成协议输出。
+    #[must_use]
+    pub fn with_fact(mut self, fact: GatewayEvent) -> Self {
+        self.canonical.push(fact);
+        self
+    }
+
     /// 创建只有协议原生表达的事件。
     #[must_use]
     pub fn wire(wire: ProtocolWireEvent) -> Self {
@@ -756,6 +809,8 @@ impl ProviderEvent {
             wire: Some(Box::new(wire)),
             observation: None,
             session_update: None,
+            middleware_transformed: false,
+            middleware_origin_wire: None,
         }
     }
 
@@ -767,6 +822,8 @@ impl ProviderEvent {
             wire: Some(Box::new(wire)),
             observation: None,
             session_update: None,
+            middleware_transformed: false,
+            middleware_origin_wire: None,
         }
     }
 
@@ -778,9 +835,51 @@ impl ProviderEvent {
             wire: None,
             observation: Some(Box::new(observation)),
             session_update: None,
+            middleware_transformed: false,
+            middleware_origin_wire: None,
         }
     }
 
+    /// 返回协议表达是否由中间件替换、展开或丢弃映射产生。
+    ///
+    /// 该事实只供宿主最终协议边界决定是否启用严格复核，不进入插件 wire。
+    #[must_use]
+    pub const fn middleware_transformed(&self) -> bool {
+        self.middleware_transformed
+    }
+
+    /// 返回中间件第一次改写前的协议表达；仅宿主协议复核可见。
+    #[must_use]
+    pub fn middleware_origin_wire(&self) -> Option<&ProtocolWireEvent> {
+        self.middleware_origin_wire.as_deref()
+    }
+
+    /// 记录宿主已经确认的中间件改写；后续原生编码和投递必须继续传播。
+    pub(crate) fn mark_middleware_transformed(&mut self) {
+        self.middleware_transformed = true;
+    }
+
+    /// 用中间件输出替换正文，同时冻结第一次改写前的原始 wire。
+    pub(crate) fn replace_middleware_wire(&mut self, wire: Option<ProtocolWireEvent>) {
+        let previous = self.wire.take();
+        if self.middleware_origin_wire.is_none() {
+            self.middleware_origin_wire = previous.map(Arc::from);
+        }
+        self.wire = wire.map(Box::new);
+        self.middleware_transformed = true;
+    }
+
+    /// 一对多或内建协议转换生成的新封套继承同一份宿主 provenance。
+    pub(crate) fn inherit_middleware_provenance(&mut self, source: &Self) {
+        self.middleware_transformed = source.middleware_transformed;
+        self.middleware_origin_wire = source.middleware_origin_wire.clone();
+    }
+
+    /// 把响应观察附在同一上游封套，不拆分或重复交付原生表达。
+    pub fn attach_observation(&mut self, observation: ProviderResponseObservation) {
+        self.observation = Some(Box::new(observation));
+    }
+
     /// 附加 Provider 私有状态检查点；Core 可将其用于同请求恢复，协议连接可在
     /// terminal 事件上持有它供下一轮使用。
     pub fn attach_session_update(&mut self, state: ProviderSessionState) {
@@ -811,6 +910,11 @@ impl ProviderEvent {
         self.wire.as_deref()
     }
 
+    /// 仅替换客户端协议表达；canonical facts、响应观察和会话状态保持原始事实。
+    pub fn replace_wire(&mut self, wire: Option<ProtocolWireEvent>) {
+        self.wire = wire.map(Box::new);
+    }
+
     /// 取出仅供 Core 持久化的响应观察。
     #[must_use]
     pub fn take_observation(&mut self) -> Option<ProviderResponseObservation> {
diff --git a/backend/crates/gateway-core/src/lib.rs b/backend/crates/gateway-core/src/lib.rs
index 1e65bcc7e..06e14e1eb 100644
--- a/backend/crates/gateway-core/src/lib.rs
+++ b/backend/crates/gateway-core/src/lib.rs
@@ -34,9 +34,11 @@ use engine::execution::{
     ClientApiKeyUsageSink, ClientKeyVerifier, DefaultExecutionService, ExecutionService,
     ProviderCircuitPort,
 };
+use engine::nested::{AffinityLookupPort, NestedModelExecutionPort};
 use engine::probe::AccountProbe;
 use engine::provider::ProviderRegistry;
 use health::HealthProbe;
+use provider_ports::ProviderSessionAffinityPort;
 use routing::snapshot::{RuntimeSnapshotCompiler, SnapshotStorePort};
 use runtime::{
     RuntimeSnapshotHandle, RuntimeSnapshotPublisher, SnapshotControl, SnapshotSubscriptionPort,
@@ -55,6 +57,7 @@ pub struct CoreStorePorts {
     snapshot_subscriptions: Arc<dyn SnapshotSubscriptionPort>,
     client_api_key_usage: Arc<dyn ClientApiKeyUsageSink>,
     budget: Option<Arc<dyn engine::budget::ClientBudgetPort>>,
+    session_affinity: Option<Arc<dyn ProviderSessionAffinityPort>>,
 }
 
 impl CoreStorePorts {
@@ -83,6 +86,7 @@ impl CoreStorePorts {
             snapshot_subscriptions,
             client_api_key_usage,
             budget: None,
+            session_affinity: None,
         }
     }
 
@@ -91,18 +95,139 @@ impl CoreStorePorts {
         self.budget = Some(budget);
         self
     }
+
+    #[must_use]
+    pub fn with_session_affinity(
+        mut self,
+        session_affinity: Arc<dyn ProviderSessionAffinityPort>,
+    ) -> Self {
+        self.session_affinity = Some(session_affinity);
+        self
+    }
 }
 
 pub struct CoreBundle {
+    snapshots: RuntimeSnapshotHandle,
     execution: Arc<dyn ExecutionService>,
     client_key_verifier: Arc<dyn ClientKeyVerifier>,
     snapshot_control: Arc<dyn SnapshotControl>,
     account_probe: Arc<dyn AccountProbe>,
+    nested_model_execution: Arc<dyn NestedModelExecutionPort>,
+    affinity_lookup: Arc<dyn AffinityLookupPort>,
     health_probes: Vec<Arc<dyn HealthProbe>>,
     worker_contributions: Vec<WorkerContribution>,
 }
 
+/// 已构造但尚未恢复准入或发现 Provider 目录的数据面启动对象。
+pub struct CoreStartup {
+    ports: CoreStorePorts,
+    providers: ProviderRegistry,
+    request_observers: Option<engine::observation::RequestObserverExtensionIndex>,
+    request_policies: Option<engine::policy::RequestPolicyExtensionIndex>,
+    middlewares: Option<engine::middleware::MiddlewareExtensionIndex>,
+    frontend_authentication: Option<engine::authentication::FrontendAuthenticationExtensionIndex>,
+    control: CoreControlPlaneStartup,
+}
+
+impl CoreStartup {
+    #[must_use]
+    pub fn snapshots(&self) -> RuntimeSnapshotHandle {
+        self.control.snapshots()
+    }
+
+    #[must_use]
+    pub fn snapshot_control(&self) -> Arc<dyn SnapshotControl> {
+        self.control.snapshot_control()
+    }
+
+    /// 绑定组合根依赖后执行 fail-closed 准入恢复与首次目录发现。
+    pub async fn activate(self) -> Result<CoreBundle, CoreError> {
+        restore_client_admission_startup(
+            self.ports.execution.as_ref(),
+            self.ports.admission_recovery.as_ref(),
+            self.ports.admissions.as_ref(),
+            SystemTime::now(),
+        )
+        .await
+        .map_err(|_| CoreError::AdmissionRecoveryUnavailable)?;
+        let control = self.control.activate().await?;
+        let snapshots = control.snapshots;
+        let publisher = control.publisher;
+        let worker_contributions = publisher.worker_contributions()?;
+        let service = Arc::new(build_execution_service(
+            snapshots.clone(),
+            &self.ports,
+            self.providers,
+            self.request_observers,
+            self.request_policies,
+            self.middlewares,
+            self.frontend_authentication,
+        ));
+        let execution: Arc<dyn ExecutionService> = service.clone();
+        let client_key_verifier: Arc<dyn ClientKeyVerifier> = service.clone();
+        let account_probe: Arc<dyn AccountProbe> = service.clone();
+        let nested_model_execution: Arc<dyn NestedModelExecutionPort> = service.clone();
+        let affinity_lookup: Arc<dyn AffinityLookupPort> = service;
+        let snapshot_control: Arc<dyn SnapshotControl> = publisher;
+        let health_probes: Vec<Arc<dyn HealthProbe>> = vec![Arc::new(snapshots.clone())];
+        Ok(CoreBundle {
+            snapshots,
+            execution,
+            client_key_verifier,
+            snapshot_control,
+            account_probe,
+            nested_model_execution,
+            affinity_lookup,
+            health_probes,
+            worker_contributions,
+        })
+    }
+}
+
+fn build_execution_service(
+    snapshots: RuntimeSnapshotHandle,
+    ports: &CoreStorePorts,
+    providers: ProviderRegistry,
+    request_observers: Option<engine::observation::RequestObserverExtensionIndex>,
+    request_policies: Option<engine::policy::RequestPolicyExtensionIndex>,
+    middlewares: Option<engine::middleware::MiddlewareExtensionIndex>,
+    frontend_authentication: Option<engine::authentication::FrontendAuthenticationExtensionIndex>,
+) -> DefaultExecutionService {
+    let mut service = DefaultExecutionService::new(
+        snapshots,
+        Arc::clone(&ports.execution),
+        providers,
+        Arc::clone(&ports.admissions),
+        Arc::clone(&ports.circuits),
+        Arc::clone(&ports.continuation),
+        Arc::clone(&ports.client_api_key_usage),
+    );
+    if let Some(budget) = &ports.budget {
+        service = service.with_budget(Arc::clone(budget));
+    }
+    if let Some(request_observers) = request_observers {
+        service = service.with_request_observers(request_observers);
+    }
+    if let Some(request_policies) = request_policies {
+        service = service.with_request_policies(request_policies);
+    }
+    if let Some(middlewares) = middlewares {
+        service = service.with_middlewares(middlewares);
+    }
+    if let Some(frontend_authentication) = frontend_authentication {
+        service = service.with_frontend_authentication(frontend_authentication);
+    }
+    if let Some(session_affinity) = &ports.session_affinity {
+        service = service.with_session_affinity(Arc::clone(session_affinity));
+    }
+    service
+}
+
 impl CoreBundle {
+    #[must_use]
+    pub fn snapshots(&self) -> RuntimeSnapshotHandle {
+        self.snapshots.clone()
+    }
     #[must_use]
     pub fn execution_service(&self) -> Arc<dyn ExecutionService> {
         Arc::clone(&self.execution)
@@ -123,6 +248,16 @@ impl CoreBundle {
         Arc::clone(&self.account_probe)
     }
 
+    #[must_use]
+    pub fn nested_model_execution_port(&self) -> Arc<dyn NestedModelExecutionPort> {
+        Arc::clone(&self.nested_model_execution)
+    }
+
+    #[must_use]
+    pub fn affinity_lookup_port(&self) -> Arc<dyn AffinityLookupPort> {
+        Arc::clone(&self.affinity_lookup)
+    }
+
     #[must_use]
     pub fn health_probes(&self) -> Vec<Arc<dyn HealthProbe>> {
         self.health_probes.clone()
@@ -137,56 +272,224 @@ impl CoreBundle {
 pub async fn initialize(
     ports: CoreStorePorts,
     providers: ProviderRegistry,
+    extensions: Option<Arc<dyn runtime::extensions::ExtensionPreparationPort>>,
+    request_observers: Option<engine::observation::RequestObserverExtensionIndex>,
+    request_policies: Option<engine::policy::RequestPolicyExtensionIndex>,
+    middlewares: Option<engine::middleware::MiddlewareExtensionIndex>,
+    frontend_authentication: Option<engine::authentication::FrontendAuthenticationExtensionIndex>,
 ) -> Result<CoreBundle, CoreError> {
-    restore_client_admission_startup(
-        ports.execution.as_ref(),
-        ports.admission_recovery.as_ref(),
-        ports.admissions.as_ref(),
-        SystemTime::now(),
+    prepare(
+        ports,
+        providers,
+        extensions,
+        request_observers,
+        request_policies,
+        middlewares,
+        frontend_authentication,
     )
+    .activate()
     .await
-    .map_err(|_| CoreError::AdmissionRecoveryUnavailable)?;
-    let compiler = Arc::new(RuntimeSnapshotCompiler::new(
-        Arc::clone(&ports.snapshots),
-        Arc::new(providers.clone()),
-    ));
-    let initial = compiler
-        .compile()
+}
+
+/// 构造 Core 与快照发布能力；首次 Provider 目录发现延迟到 [`CoreStartup::activate`]。
+#[must_use]
+pub fn prepare(
+    ports: CoreStorePorts,
+    providers: ProviderRegistry,
+    extensions: Option<Arc<dyn runtime::extensions::ExtensionPreparationPort>>,
+    request_observers: Option<engine::observation::RequestObserverExtensionIndex>,
+    request_policies: Option<engine::policy::RequestPolicyExtensionIndex>,
+    middlewares: Option<engine::middleware::MiddlewareExtensionIndex>,
+    frontend_authentication: Option<engine::authentication::FrontendAuthenticationExtensionIndex>,
+) -> CoreStartup {
+    let control = prepare_control_plane(ports.clone(), providers.clone(), extensions);
+    CoreStartup {
+        ports,
+        providers,
+        request_observers,
+        request_policies,
+        middlewares,
+        frontend_authentication,
+        control,
+    }
+}
+
+/// 管理命令只持有快照读写能力，不恢复数据面准入，也不启动执行/结算 Worker。
+pub struct CoreControlPlaneBundle {
+    snapshots: RuntimeSnapshotHandle,
+    publisher: Arc<RuntimeSnapshotPublisher>,
+}
+
+/// CLI/组合根可先绑定回调端口，再激活首次目录发现。
+pub struct CoreControlPlaneStartup {
+    snapshots: RuntimeSnapshotHandle,
+    publisher: Arc<RuntimeSnapshotPublisher>,
+}
+
+impl CoreControlPlaneStartup {
+    #[must_use]
+    pub fn snapshots(&self) -> RuntimeSnapshotHandle {
+        self.snapshots.clone()
+    }
+
+    #[must_use]
+    pub fn snapshot_control(&self) -> Arc<dyn SnapshotControl> {
+        self.publisher.clone()
+    }
+
+    pub async fn activate(self) -> Result<CoreControlPlaneBundle, CoreError> {
+        match self.publisher.refresh().await {
+            Ok(_) => {}
+            // 故障插件不能封锁管理修复入口；没有可用快照时数据面仍拒绝新请求。
+            Err(routing::snapshot::RuntimeSnapshotCompileError::ExtensionsUnavailable) => {}
+            Err(_) => return Err(CoreError::SnapshotUnavailable),
+        }
+        Ok(CoreControlPlaneBundle {
+            snapshots: self.snapshots,
+            publisher: self.publisher,
+        })
+    }
+}
+
+impl CoreControlPlaneBundle {
+    #[must_use]
+    pub fn snapshots(&self) -> RuntimeSnapshotHandle {
+        self.snapshots.clone()
+    }
+
+    #[must_use]
+    pub fn snapshot_control(&self) -> Arc<dyn SnapshotControl> {
+        self.publisher.clone()
+    }
+}
+
+/// CLI 命令按需拥有嵌套模型执行与会话亲和查询端口，但不恢复网关启动时的准入租约，
+/// 也不产生任何后台 Worker 定义。
+pub struct CoreCommandPlaneStartup {
+    ports: CoreStorePorts,
+    providers: ProviderRegistry,
+    request_observers: Option<engine::observation::RequestObserverExtensionIndex>,
+    request_policies: Option<engine::policy::RequestPolicyExtensionIndex>,
+    middlewares: Option<engine::middleware::MiddlewareExtensionIndex>,
+    control: CoreControlPlaneStartup,
+}
+
+pub struct CoreCommandPlaneBundle {
+    control: CoreControlPlaneBundle,
+    nested_model_execution: Arc<dyn NestedModelExecutionPort>,
+    affinity_lookup: Arc<dyn AffinityLookupPort>,
+}
+
+impl CoreCommandPlaneStartup {
+    #[must_use]
+    pub fn snapshots(&self) -> RuntimeSnapshotHandle {
+        self.control.snapshots()
+    }
+
+    #[must_use]
+    pub fn snapshot_control(&self) -> Arc<dyn SnapshotControl> {
+        self.control.snapshot_control()
+    }
+
+    pub async fn activate(self) -> Result<CoreCommandPlaneBundle, CoreError> {
+        let control = self.control.activate().await?;
+        let service = Arc::new(
+            build_execution_service(
+                control.snapshots.clone(),
+                &self.ports,
+                self.providers,
+                self.request_observers,
+                self.request_policies,
+                self.middlewares,
+                None,
+            )
+            .with_snapshot_refresh(Arc::clone(&control.publisher)),
+        );
+        let nested_model_execution: Arc<dyn NestedModelExecutionPort> = service.clone();
+        let affinity_lookup: Arc<dyn AffinityLookupPort> = service;
+        Ok(CoreCommandPlaneBundle {
+            control,
+            nested_model_execution,
+            affinity_lookup,
+        })
+    }
+}
+
+impl CoreCommandPlaneBundle {
+    #[must_use]
+    pub fn snapshots(&self) -> RuntimeSnapshotHandle {
+        self.control.snapshots()
+    }
+
+    #[must_use]
+    pub fn snapshot_control(&self) -> Arc<dyn SnapshotControl> {
+        self.control.snapshot_control()
+    }
+
+    #[must_use]
+    pub fn nested_model_execution_port(&self) -> Arc<dyn NestedModelExecutionPort> {
+        Arc::clone(&self.nested_model_execution)
+    }
+
+    #[must_use]
+    pub fn affinity_lookup_port(&self) -> Arc<dyn AffinityLookupPort> {
+        Arc::clone(&self.affinity_lookup)
+    }
+}
+
+/// 为单次 CLI 命令构造当前快照与窄执行端口；激活时不恢复全局准入状态。
+#[must_use]
+pub fn prepare_command_plane(
+    ports: CoreStorePorts,
+    providers: ProviderRegistry,
+    extensions: Option<Arc<dyn runtime::extensions::ExtensionPreparationPort>>,
+    request_observers: Option<engine::observation::RequestObserverExtensionIndex>,
+    request_policies: Option<engine::policy::RequestPolicyExtensionIndex>,
+    middlewares: Option<engine::middleware::MiddlewareExtensionIndex>,
+) -> CoreCommandPlaneStartup {
+    let control = prepare_control_plane(ports.clone(), providers.clone(), extensions);
+    CoreCommandPlaneStartup {
+        ports,
+        providers,
+        request_observers,
+        request_policies,
+        middlewares,
+        control,
+    }
+}
+
+pub async fn initialize_control_plane(
+    ports: CoreStorePorts,
+    providers: ProviderRegistry,
+    extensions: Option<Arc<dyn runtime::extensions::ExtensionPreparationPort>>,
+) -> Result<CoreControlPlaneBundle, CoreError> {
+    prepare_control_plane(ports, providers, extensions)
+        .activate()
         .await
-        .map_err(|_| CoreError::SnapshotUnavailable)?;
-    let snapshots = RuntimeSnapshotHandle::new(initial);
+}
+
+/// 仅构造管理命令所需快照能力，不恢复准入、不发现目录且不启动 Worker。
+#[must_use]
+pub fn prepare_control_plane(
+    ports: CoreStorePorts,
+    providers: ProviderRegistry,
+    extensions: Option<Arc<dyn runtime::extensions::ExtensionPreparationPort>>,
+) -> CoreControlPlaneStartup {
+    let mut compiler = RuntimeSnapshotCompiler::new(ports.snapshots, Arc::new(providers));
+    if let Some(extensions) = extensions {
+        compiler = compiler.with_extensions(extensions);
+    }
+    let compiler = Arc::new(compiler);
+    let snapshots = RuntimeSnapshotHandle::default();
     let publisher = Arc::new(RuntimeSnapshotPublisher::new(
         compiler,
         snapshots.clone(),
-        Arc::clone(&ports.snapshot_subscriptions),
+        ports.snapshot_subscriptions,
     ));
-    let worker_contributions = publisher.worker_contributions()?;
-    let mut service = DefaultExecutionService::new(
-        snapshots.clone(),
-        ports.execution,
-        providers,
-        ports.admissions,
-        ports.circuits,
-        ports.continuation,
-        ports.client_api_key_usage,
-    );
-    if let Some(budget) = ports.budget {
-        service = service.with_budget(budget);
+    CoreControlPlaneStartup {
+        snapshots,
+        publisher,
     }
-    let service = Arc::new(service);
-    let execution: Arc<dyn ExecutionService> = service.clone();
-    let client_key_verifier: Arc<dyn ClientKeyVerifier> = service.clone();
-    let account_probe: Arc<dyn AccountProbe> = service;
-    let snapshot_control: Arc<dyn SnapshotControl> = publisher;
-    let health_probes: Vec<Arc<dyn HealthProbe>> = vec![Arc::new(snapshots)];
-    Ok(CoreBundle {
-        execution,
-        client_key_verifier,
-        snapshot_control,
-        account_probe,
-        health_probes,
-        worker_contributions,
-    })
 }
 
 #[derive(Debug, thiserror::Error)]
diff --git a/backend/crates/gateway-core/src/lifecycle.rs b/backend/crates/gateway-core/src/lifecycle.rs
index 58a918888..3b20cd022 100644
--- a/backend/crates/gateway-core/src/lifecycle.rs
+++ b/backend/crates/gateway-core/src/lifecycle.rs
@@ -4,7 +4,7 @@ use std::fmt;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex};
 
-use futures::channel::oneshot;
+use futures::{channel::oneshot, future::BoxFuture};
 
 struct CancellationState {
     cancelled: AtomicBool,
@@ -13,7 +13,10 @@ struct CancellationState {
 
 /// 可克隆的请求、任务与连接取消信号。
 #[derive(Clone)]
-pub struct CancellationToken(Arc<CancellationState>);
+pub struct CancellationToken {
+    state: Arc<CancellationState>,
+    ancestors: Arc<[Arc<CancellationState>]>,
+}
 
 impl fmt::Debug for CancellationToken {
     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
@@ -33,18 +36,36 @@ impl Default for CancellationToken {
 impl CancellationToken {
     #[must_use]
     pub fn new() -> Self {
-        Self(Arc::new(CancellationState {
-            cancelled: AtomicBool::new(false),
-            waiters: Mutex::new(Vec::new()),
-        }))
+        Self {
+            state: Arc::new(CancellationState {
+                cancelled: AtomicBool::new(false),
+                waiters: Mutex::new(Vec::new()),
+            }),
+            ancestors: Arc::from([]),
+        }
+    }
+
+    /// 创建只从父级继承取消的子 token；取消子级不会反向取消父请求。
+    #[must_use]
+    pub fn child_token(&self) -> Self {
+        let ancestors = std::iter::once(Arc::clone(&self.state))
+            .chain(self.ancestors.iter().cloned())
+            .collect::<Vec<_>>();
+        Self {
+            state: Arc::new(CancellationState {
+                cancelled: AtomicBool::new(false),
+                waiters: Mutex::new(Vec::new()),
+            }),
+            ancestors: ancestors.into(),
+        }
     }
 
     pub fn cancel(&self) {
-        if self.0.cancelled.swap(true, Ordering::AcqRel) {
+        if self.state.cancelled.swap(true, Ordering::AcqRel) {
             return;
         }
         let waiters = {
-            let mut guard = lock_unpoisoned(&self.0.waiters);
+            let mut guard = lock_unpoisoned(&self.state.waiters);
             std::mem::take(&mut *guard)
         };
         for waiter in waiters {
@@ -54,23 +75,39 @@ impl CancellationToken {
 
     #[must_use]
     pub fn is_cancelled(&self) -> bool {
-        self.0.cancelled.load(Ordering::Acquire)
+        self.state.cancelled.load(Ordering::Acquire)
+            || self
+                .ancestors
+                .iter()
+                .any(|state| state.cancelled.load(Ordering::Acquire))
     }
 
     pub async fn cancelled(&self) {
         if self.is_cancelled() {
             return;
         }
+        let mut waiters: Vec<BoxFuture<'static, ()>> = Vec::with_capacity(1 + self.ancestors.len());
+        waiters.push(wait_for_state(Arc::clone(&self.state)));
+        waiters.extend(self.ancestors.iter().cloned().map(wait_for_state));
+        let _ = futures::future::select_all(waiters).await;
+    }
+}
+
+fn wait_for_state(state: Arc<CancellationState>) -> BoxFuture<'static, ()> {
+    Box::pin(async move {
+        if state.cancelled.load(Ordering::Acquire) {
+            return;
+        }
         let (sender, receiver) = oneshot::channel();
         {
-            let mut waiters = lock_unpoisoned(&self.0.waiters);
-            if self.is_cancelled() {
+            let mut waiters = lock_unpoisoned(&state.waiters);
+            if state.cancelled.load(Ordering::Acquire) {
                 return;
             }
             waiters.push(sender);
         }
         let _ = receiver.await;
-    }
+    })
 }
 
 fn lock_unpoisoned<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
diff --git a/backend/crates/gateway-core/src/operation/mod.rs b/backend/crates/gateway-core/src/operation/mod.rs
index 31d438071..e5baedb2f 100644
--- a/backend/crates/gateway-core/src/operation/mod.rs
+++ b/backend/crates/gateway-core/src/operation/mod.rs
@@ -24,6 +24,10 @@ pub enum OperationKind {
     GenerateImage,
     /// Provider 原生 standalone search。
     Search,
+    /// 使用目标模型的真实 tokenizer 计数，不允许 Core 估算。
+    CountTokens,
+    /// Provider 声明并映射到固定上游目标的账号认证 HTTP 操作。
+    ProviderHttp,
 }
 
 impl OperationKind {
@@ -34,6 +38,8 @@ impl OperationKind {
             Self::Generate => "generate",
             Self::GenerateImage => "generate_image",
             Self::Search => "search",
+            Self::CountTokens => "count_tokens",
+            Self::ProviderHttp => "provider_http",
         }
     }
 }
@@ -234,6 +240,7 @@ pub struct RawJsonPayload {
     protocol: String,
     body: Bytes,
     context: Map<String, Value>,
+    translated: bool,
 }
 
 impl RawJsonPayload {
@@ -251,6 +258,7 @@ impl RawJsonPayload {
             protocol,
             body,
             context: Map::new(),
+            translated: false,
         })
     }
 
@@ -291,6 +299,70 @@ impl fmt::Debug for RawJsonPayload {
     }
 }
 
+/// Provider HTTP 端点使用的不透明字节正文。
+///
+/// 与 [`RawJsonPayload`] 不同，这里不要求正文是 JSON。Core 只保留字节和
+/// 非 wire 上下文，最终 origin、路径与账号认证仍由 Provider 决定。
+#[derive(Clone, PartialEq, Eq)]
+pub struct RawHttpPayload {
+    protocol: String,
+    body: Bytes,
+    context: Map<String, Value>,
+    translated: bool,
+}
+
+impl RawHttpPayload {
+    /// 创建不透明 HTTP 正文。
+    ///
+    /// # Errors
+    ///
+    /// 协议名称为空、过长或含控制字符时返回错误。
+    pub fn new(protocol: impl Into<String>, body: Bytes) -> Result<Self, OperationError> {
+        let protocol = protocol.into();
+        validate_text(&protocol, 64, true, None).map_err(|_| OperationError::EmptyField {
+            field: "raw_http_payload protocol",
+        })?;
+        Ok(Self {
+            protocol,
+            body,
+            context: Map::new(),
+            translated: false,
+        })
+    }
+
+    #[must_use]
+    pub fn protocol(&self) -> &str {
+        &self.protocol
+    }
+
+    #[must_use]
+    pub const fn body(&self) -> &Bytes {
+        &self.body
+    }
+
+    #[must_use]
+    pub fn with_context(mut self, context: Map<String, Value>) -> Self {
+        self.context = context;
+        self
+    }
+
+    #[must_use]
+    pub const fn context(&self) -> &Map<String, Value> {
+        &self.context
+    }
+}
+
+impl fmt::Debug for RawHttpPayload {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("RawHttpPayload")
+            .field("protocol", &self.protocol)
+            .field("body", &"<not included in Debug>")
+            .field("context", &"<not included in Debug>")
+            .finish()
+    }
+}
+
 /// 通用生成请求。
 #[derive(Clone, PartialEq)]
 pub struct GenerateRequest {
@@ -301,6 +373,7 @@ pub struct GenerateRequest {
 struct GeneratePayload {
     protocol_payload: ProtocolPayload,
     provider_session_state: Option<ProviderSessionState>,
+    source_requirements: Option<CapabilityRequirements>,
 }
 
 impl GenerateRequest {
@@ -314,10 +387,33 @@ impl GenerateRequest {
             payload: Arc::new(GeneratePayload {
                 protocol_payload,
                 provider_session_state: None,
+                source_requirements: None,
             }),
         }
     }
 
+    /// 写回原生 Provider 编码结果，保留已准入的能力、连接上下文和会话状态。
+    ///
+    /// 原生编码不消耗中间件的一次跨协议改写额度：可以保留协议名，也可以在一次
+    /// 中间件改写后编码到 Provider wire。调用方仍须验证保护字段没有被改动。
+    ///
+    /// # Errors
+    ///
+    /// 目标协议名无效时返回错误。
+    pub fn with_native_encoded_body(
+        mut self,
+        protocol: impl Into<String>,
+        body: Map<String, Value>,
+    ) -> Result<Self, OperationError> {
+        let encoded = ProtocolPayload::json_object(protocol, body)?
+            .with_context(self.protocol_payload().context().clone());
+        let requirements = self.requirements();
+        let payload = Arc::make_mut(&mut self.payload);
+        payload.protocol_payload = encoded;
+        payload.source_requirements = Some(requirements);
+        Ok(self)
+    }
+
     /// 附着同一客户端连接上一轮由 Provider 返回的不透明状态。
     #[must_use]
     pub fn with_provider_session_state(mut self, state: ProviderSessionState) -> Self {
@@ -386,6 +482,9 @@ impl GenerateRequest {
     }
 
     fn requirements(&self) -> CapabilityRequirements {
+        if let Some(requirements) = &self.payload.source_requirements {
+            return requirements.clone();
+        }
         let mut requirements = CapabilityRequirements::new(OperationKind::Generate)
             .with_requested_output_tokens(self.max_output_tokens());
         if self
@@ -533,6 +632,194 @@ impl fmt::Debug for StandaloneSearchRequest {
     }
 }
 
+/// 使用目标模型的 Provider 原生 Token 计数请求。
+#[derive(Clone, PartialEq, Eq)]
+pub struct TokenCountRequest {
+    payload: RawJsonPayload,
+}
+
+impl TokenCountRequest {
+    #[must_use]
+    pub const fn from_raw_json(payload: RawJsonPayload) -> Self {
+        Self { payload }
+    }
+
+    #[must_use]
+    pub const fn payload(&self) -> &RawJsonPayload {
+        &self.payload
+    }
+}
+
+impl fmt::Debug for TokenCountRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("TokenCountRequest")
+            .field("payload", &"<not included in Debug>")
+            .finish()
+    }
+}
+
+/// API 可公开的 Provider HTTP method 集合；不自动包含 `HEAD` 或任意 method。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum ProviderHttpMethod {
+    Get,
+    Post,
+}
+
+impl ProviderHttpMethod {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Get => "GET",
+            Self::Post => "POST",
+        }
+    }
+}
+
+/// 已由 API 解析的单个 HTTP header；值不会出现在 `Debug`。
+#[derive(Clone, PartialEq, Eq)]
+pub struct ProviderHttpHeader {
+    name: String,
+    value: Bytes,
+}
+
+impl ProviderHttpHeader {
+    #[must_use]
+    pub fn new(name: impl Into<String>, value: Bytes) -> Self {
+        Self {
+            name: name.into(),
+            value,
+        }
+    }
+
+    #[must_use]
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    #[must_use]
+    pub const fn value(&self) -> &Bytes {
+        &self.value
+    }
+}
+
+impl fmt::Debug for ProviderHttpHeader {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("ProviderHttpHeader")
+            .field("name", &self.name)
+            .field("value", &"<not included in Debug>")
+            .finish()
+    }
+}
+
+/// Provider 显式声明的账号认证 HTTP 操作。
+#[derive(Clone, PartialEq, Eq)]
+pub struct ProviderHttpRequest {
+    endpoint: String,
+    method: ProviderHttpMethod,
+    query: Option<String>,
+    headers: Vec<ProviderHttpHeader>,
+    payload: RawHttpPayload,
+}
+
+impl ProviderHttpRequest {
+    /// # Errors
+    ///
+    /// endpoint 不是安全符号名，query 或 headers 超过边界时返回错误。
+    pub fn new(
+        endpoint: impl Into<String>,
+        method: ProviderHttpMethod,
+        query: Option<String>,
+        headers: Vec<ProviderHttpHeader>,
+        payload: RawHttpPayload,
+    ) -> Result<Self, OperationError> {
+        let endpoint = endpoint.into();
+        let valid_endpoint = !endpoint.is_empty()
+            && endpoint.len() <= 64
+            && endpoint != "."
+            && endpoint != ".."
+            && endpoint
+                .bytes()
+                .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.'));
+        let valid_query = query.as_ref().is_none_or(|query| {
+            query.len() <= 8 * 1024 && !query.bytes().any(|byte| matches!(byte, b'\r' | b'\n' | 0))
+        });
+        let valid_headers = headers.len() <= 64
+            && headers
+                .iter()
+                .try_fold(0_usize, |total, header| {
+                    let valid_name = !header.name.is_empty()
+                        && header.name.len() <= 128
+                        && header
+                            .name
+                            .bytes()
+                            .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-');
+                    let valid_value = header.value.len() <= 8 * 1024
+                        && !header
+                            .value
+                            .iter()
+                            .any(|byte| matches!(byte, b'\r' | b'\n' | 0));
+                    valid_name
+                        .then_some(())
+                        .filter(|_| valid_value)
+                        .and_then(|()| total.checked_add(header.name.len() + header.value.len()))
+                        .filter(|total| *total <= 32 * 1024)
+                })
+                .is_some();
+        if !valid_endpoint || !valid_query || !valid_headers {
+            return Err(OperationError::EmptyField {
+                field: "provider_http_request",
+            });
+        }
+        Ok(Self {
+            endpoint,
+            method,
+            query,
+            headers,
+            payload,
+        })
+    }
+
+    #[must_use]
+    pub fn endpoint(&self) -> &str {
+        &self.endpoint
+    }
+
+    #[must_use]
+    pub const fn method(&self) -> ProviderHttpMethod {
+        self.method
+    }
+
+    #[must_use]
+    pub fn query(&self) -> Option<&str> {
+        self.query.as_deref()
+    }
+
+    #[must_use]
+    pub fn headers(&self) -> &[ProviderHttpHeader] {
+        &self.headers
+    }
+
+    #[must_use]
+    pub const fn payload(&self) -> &RawHttpPayload {
+        &self.payload
+    }
+}
+
+impl fmt::Debug for ProviderHttpRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("ProviderHttpRequest")
+            .field("endpoint", &self.endpoint)
+            .field("method", &self.method)
+            .field("query", &self.query.as_ref().map(|_| "<present>"))
+            .field("header_count", &self.headers.len())
+            .field("payload", &self.payload)
+            .finish()
+    }
+}
+
 /// 网关内部业务请求；不包含任何客户端 wire 或 Provider SDK 类型。
 #[derive(Clone, PartialEq)]
 #[non_exhaustive]
@@ -543,9 +830,249 @@ pub enum Operation {
     GenerateImage(ImageRequest),
     /// Provider 原生 standalone search。
     Search(StandaloneSearchRequest),
+    /// 使用目标模型进行真实 Token 计数。
+    CountTokens(TokenCountRequest),
+    /// Provider 显式登记的账号认证 HTTP 操作。
+    ProviderHttp(ProviderHttpRequest),
 }
 
 impl Operation {
+    /// 把协议正文编码为中间件可见的原始字节；不包含非 wire context 或会话状态。
+    ///
+    /// # Errors
+    ///
+    /// 生成请求的 JSON object 无法编码时返回错误。
+    pub fn middleware_body(&self) -> Result<Bytes, OperationError> {
+        match self {
+            Self::Generate(request) => serde_json::to_vec(request.protocol_payload().body())
+                .map(Bytes::from)
+                .map_err(|_| OperationError::EmptyField {
+                    field: "protocol_payload body",
+                }),
+            Self::GenerateImage(request) => Ok(request.payload().body().clone()),
+            Self::Search(request) => Ok(request.payload().body().clone()),
+            Self::CountTokens(request) => Ok(request.payload().body().clone()),
+            Self::ProviderHttp(request) => Ok(request.payload().body().clone()),
+        }
+    }
+
+    /// 写回中间件返回的协议与正文，同时保留宿主持有的非 wire context。
+    ///
+    /// 同协议是正文替换；跨协议只能使用既有 direct-once 转换边界，不能借中间件
+    /// 绕过重复转换保护。
+    ///
+    /// # Errors
+    ///
+    /// 协议名或正文无效，或请求已经发生过一次跨协议转换时返回错误。
+    pub fn replace_middleware_wire(
+        self,
+        protocol: impl Into<String>,
+        body: Bytes,
+    ) -> Result<Self, OperationError> {
+        let protocol = protocol.into();
+        if self.protocol() != protocol {
+            return self.translate_protocol_wire(protocol, body);
+        }
+        let context = match &self {
+            Self::Generate(request) => request.protocol_payload().context().clone(),
+            Self::GenerateImage(request) => request.payload().context().clone(),
+            Self::Search(request) => request.payload().context().clone(),
+            Self::CountTokens(request) => request.payload().context().clone(),
+            Self::ProviderHttp(request) => request.payload().context().clone(),
+        };
+        self.replace_protocol_wire(Some(body), context)
+    }
+
+    /// 替换协议正文和非 wire 上下文，同时保留 operation 类别、Provider 会话状态与
+    /// 原协议名称。`body=None` 表示只改上下文，避免无加工路径重新编码正文。
+    ///
+    /// # Errors
+    ///
+    /// Generate 的替换正文不是 JSON object 时返回错误；原始 JSON 端点继续按字节保存。
+    pub fn replace_protocol_wire(
+        self,
+        body: Option<Bytes>,
+        context: Map<String, Value>,
+    ) -> Result<Self, OperationError> {
+        self.replace_protocol_wire_inner(None, body, context)
+    }
+
+    /// 替换 Provider HTTP 正文、非 wire 上下文和已解析 headers，同时保持 endpoint、
+    /// method 与 query 不变。headers 继续由 [`ProviderHttpRequest::new`] 统一验证；
+    /// Core 不解析插件传输使用的 base64 表示。
+    ///
+    /// # Errors
+    ///
+    /// 当前 operation 不是 Provider HTTP，或替换后的 headers 超出请求边界时返回错误。
+    pub fn replace_provider_http_wire(
+        self,
+        body: Option<Bytes>,
+        context: Map<String, Value>,
+        headers: Vec<ProviderHttpHeader>,
+    ) -> Result<Self, OperationError> {
+        let Self::ProviderHttp(request) = self else {
+            return Err(OperationError::EmptyField {
+                field: "provider_http_request",
+            });
+        };
+        let payload = request.payload;
+        ProviderHttpRequest::new(
+            request.endpoint,
+            request.method,
+            request.query,
+            headers,
+            RawHttpPayload {
+                protocol: payload.protocol,
+                body: body.unwrap_or(payload.body),
+                context,
+                translated: payload.translated,
+            },
+        )
+        .map(Self::ProviderHttp)
+    }
+
+    /// 把一次已选择的协议转换结果写回 operation，同时保留非 wire 上下文和
+    /// Provider 会话状态。该方法只验证公共载荷形状，不解释目标协议字段。
+    ///
+    /// # Errors
+    ///
+    /// 目标协议名无效，或 Generate 的目标正文不是 JSON object 时返回错误。
+    pub fn translate_protocol_wire(
+        self,
+        target_protocol: impl Into<String>,
+        body: Bytes,
+    ) -> Result<Self, OperationError> {
+        let target_protocol = target_protocol.into();
+        validate_text(&target_protocol, 64, true, None).map_err(|_| {
+            OperationError::EmptyField {
+                field: "translated protocol",
+            }
+        })?;
+        if self.protocol() == target_protocol || self.protocol_was_translated() {
+            return Err(OperationError::EmptyField {
+                field: "direct protocol translation",
+            });
+        }
+        let context = match &self {
+            Self::Generate(request) => request.protocol_payload().context().clone(),
+            Self::GenerateImage(request) => request.payload().context().clone(),
+            Self::Search(request) => request.payload().context().clone(),
+            Self::CountTokens(request) => request.payload().context().clone(),
+            Self::ProviderHttp(request) => request.payload().context().clone(),
+        };
+        self.replace_protocol_wire_inner(Some(target_protocol), Some(body), context)
+    }
+
+    fn protocol_was_translated(&self) -> bool {
+        match self {
+            Self::Generate(request) => request.payload.source_requirements.is_some(),
+            Self::GenerateImage(request) => request.payload().translated,
+            Self::Search(request) => request.payload().translated,
+            Self::CountTokens(request) => request.payload().translated,
+            Self::ProviderHttp(request) => request.payload().translated,
+        }
+    }
+
+    fn replace_protocol_wire_inner(
+        self,
+        target_protocol: Option<String>,
+        body: Option<Bytes>,
+        context: Map<String, Value>,
+    ) -> Result<Self, OperationError> {
+        let translating = target_protocol.is_some();
+        match self {
+            Self::Generate(request) => {
+                let protocol_payload = request.protocol_payload();
+                let source_requirements = translating.then(|| request.requirements());
+                let body = match body {
+                    Some(body) => {
+                        serde_json::from_slice::<Map<String, Value>>(&body).map_err(|_| {
+                            OperationError::EmptyField {
+                                field: "protocol_payload body",
+                            }
+                        })?
+                    }
+                    None => protocol_payload.body().clone(),
+                };
+                let replacement = ProtocolPayload {
+                    protocol: target_protocol
+                        .unwrap_or_else(|| protocol_payload.protocol().to_owned()),
+                    body,
+                    context,
+                };
+                let mut payload = (*request.payload).clone();
+                payload.protocol_payload = replacement;
+                if let Some(requirements) = source_requirements {
+                    payload.source_requirements = Some(requirements);
+                }
+                Ok(Self::Generate(GenerateRequest {
+                    payload: Arc::new(payload),
+                }))
+            }
+            Self::GenerateImage(request) => {
+                let payload = request.payload;
+                Ok(Self::GenerateImage(ImageRequest {
+                    kind: request.kind,
+                    payload: RawJsonPayload {
+                        protocol: target_protocol.unwrap_or(payload.protocol),
+                        body: body.unwrap_or(payload.body),
+                        context,
+                        translated: payload.translated || translating,
+                    },
+                }))
+            }
+            Self::Search(request) => {
+                let payload = request.payload;
+                Ok(Self::Search(StandaloneSearchRequest {
+                    payload: RawJsonPayload {
+                        protocol: target_protocol.unwrap_or(payload.protocol),
+                        body: body.unwrap_or(payload.body),
+                        context,
+                        translated: payload.translated || translating,
+                    },
+                }))
+            }
+            Self::CountTokens(request) => {
+                let payload = request.payload;
+                Ok(Self::CountTokens(TokenCountRequest {
+                    payload: RawJsonPayload {
+                        protocol: target_protocol.unwrap_or(payload.protocol),
+                        body: body.unwrap_or(payload.body),
+                        context,
+                        translated: payload.translated || translating,
+                    },
+                }))
+            }
+            Self::ProviderHttp(request) => {
+                let payload = request.payload;
+                Ok(Self::ProviderHttp(ProviderHttpRequest {
+                    endpoint: request.endpoint,
+                    method: request.method,
+                    query: request.query,
+                    headers: request.headers,
+                    payload: RawHttpPayload {
+                        protocol: target_protocol.unwrap_or(payload.protocol),
+                        body: body.unwrap_or(payload.body),
+                        context,
+                        translated: payload.translated || translating,
+                    },
+                }))
+            }
+        }
+    }
+
+    /// 返回协议 adapter 持有的不透明格式标识。
+    #[must_use]
+    pub fn protocol(&self) -> &str {
+        match self {
+            Self::Generate(request) => request.protocol_payload().protocol(),
+            Self::GenerateImage(request) => request.payload().protocol(),
+            Self::Search(request) => request.payload().protocol(),
+            Self::CountTokens(request) => request.payload().protocol(),
+            Self::ProviderHttp(request) => request.payload().protocol(),
+        }
+    }
+
     /// 附着协议连接持有的 Provider 私有状态；非生成 operation 保持不变。
     #[must_use]
     pub fn with_provider_session_state(self, state: ProviderSessionState) -> Self {
@@ -569,6 +1096,8 @@ impl Operation {
             Self::Generate(_) => OperationKind::Generate,
             Self::GenerateImage(_) => OperationKind::GenerateImage,
             Self::Search(_) => OperationKind::Search,
+            Self::CountTokens(_) => OperationKind::CountTokens,
+            Self::ProviderHttp(_) => OperationKind::ProviderHttp,
         }
     }
 
@@ -579,6 +1108,8 @@ impl Operation {
             Self::Generate(request) => request.requirements(),
             Self::GenerateImage(_) => CapabilityRequirements::new(OperationKind::GenerateImage),
             Self::Search(_) => CapabilityRequirements::new(OperationKind::Search),
+            Self::CountTokens(_) => CapabilityRequirements::new(OperationKind::CountTokens),
+            Self::ProviderHttp(_) => CapabilityRequirements::new(OperationKind::ProviderHttp),
         }
     }
 
@@ -588,7 +1119,7 @@ impl Operation {
         match self {
             Self::Generate(request) => request.image_generation_requested(),
             Self::GenerateImage(_) => true,
-            Self::Search(_) => false,
+            Self::Search(_) | Self::CountTokens(_) | Self::ProviderHttp(_) => false,
         }
     }
 
@@ -597,7 +1128,10 @@ impl Operation {
     pub fn provider_session_state(&self, provider: &str) -> Option<&ProviderSessionState> {
         match self {
             Self::Generate(request) => request.provider_session_state(provider),
-            Self::GenerateImage(_) | Self::Search(_) => None,
+            Self::GenerateImage(_)
+            | Self::Search(_)
+            | Self::CountTokens(_)
+            | Self::ProviderHttp(_) => None,
         }
     }
 }
diff --git a/backend/crates/gateway-core/src/provider_ports/mod.rs b/backend/crates/gateway-core/src/provider_ports/mod.rs
index 1a35c3301..b85d5e93b 100644
--- a/backend/crates/gateway-core/src/provider_ports/mod.rs
+++ b/backend/crates/gateway-core/src/provider_ports/mod.rs
@@ -14,7 +14,7 @@ use crate::account::{
 };
 use crate::identity::ProviderKind;
 use crate::policy::ClientApiKeyId;
-use crate::routing::UpstreamModelId;
+use crate::routing::{ConfigRevision, UpstreamModelId};
 use crate::validation::{IdentifierError, validate_text};
 
 const MAX_PENDING_FLOW_TTL: Duration = Duration::from_secs(30 * 60);
@@ -945,6 +945,18 @@ pub trait ProviderRuntimePolicyPort: Send + Sync {
         Box::pin(async move { Ok(initial) })
     }
 
+    /// 读取候选配置版本实际引用的全局与 Client Key 画像配置。
+    ///
+    /// 实现必须在同一数据库快照内核对 revision，且只返回画像投影，不能读取 Key
+    /// 明文。Provider 代次据此在发布前拒绝已失效的选择。
+    fn load_request_profile_configurations<'a>(
+        &'a self,
+        _revision: ConfigRevision,
+        _provider: &'a ProviderKind,
+    ) -> BoxFuture<'a, Result<Vec<OpaqueProviderData>, ProviderStoreError>> {
+        Box::pin(async move { Ok(Vec::new()) })
+    }
+
     fn load_refresh_policy(
         &self,
     ) -> BoxFuture<'_, Result<ProviderRefreshPolicy, ProviderStoreError>>;
diff --git a/backend/crates/gateway-core/src/routing/catalog.rs b/backend/crates/gateway-core/src/routing/catalog.rs
index 0d58638ab..35c314f19 100644
--- a/backend/crates/gateway-core/src/routing/catalog.rs
+++ b/backend/crates/gateway-core/src/routing/catalog.rs
@@ -113,12 +113,20 @@ pub struct ProviderCatalogUnavailable;
 
 /// 快照编译与对账使用的对象安全目录端口。
 pub trait ProviderCatalogPort: Send + Sync {
+    /// 动态目录返回对应集合的冻结视图；静态目录继续使用自身。
+    fn for_extensions(
+        &self,
+        _reference: Option<&crate::runtime::extensions::ExtensionSetReference>,
+    ) -> Result<Option<std::sync::Arc<dyn ProviderCatalogPort>>, ProviderCatalogUnavailable> {
+        Ok(None)
+    }
+
     /// 目录是否完整到足以根据缺项拒绝请求；发现型目录交由上游验证模型名。
     fn model_catalog_is_exhaustive(&self, _provider: &ProviderKind) -> bool {
         true
     }
 
-    /// 返回全部已注册 Provider 的目录代次；注册集合在初始化后保持不变。
+    /// 返回当前冻结视图内全部 Provider 的目录代次。
     ///
     /// 即使某个目录暂时不可读，也必须保留它的 Provider 与最近成功发布的代次。
     fn catalog_generations(&self) -> BTreeMap<ProviderKind, ProviderCatalogGeneration>;
diff --git a/backend/crates/gateway-core/src/routing/snapshot.rs b/backend/crates/gateway-core/src/routing/snapshot.rs
index 6b132b65e..5531120ae 100644
--- a/backend/crates/gateway-core/src/routing/snapshot.rs
+++ b/backend/crates/gateway-core/src/routing/snapshot.rs
@@ -11,7 +11,7 @@ use crate::account::{
     AccountConcurrency, AccountSelectionPolicy, ProviderAccountId, RotationStrategy,
 };
 use crate::concurrency::ConcurrencyQueuePolicy;
-use crate::operation::Operation;
+use crate::operation::{Operation, OperationKind};
 use crate::policy::{
     ClientApiKeyId, ClientPolicy, CodexClientMinVersions, CodexClientVersion,
     PlaintextClientApiKey, RateLimits,
@@ -295,6 +295,8 @@ pub trait SnapshotStorePort: Send + Sync {
 /// 快照未发布时可安全记录的稳定错误。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
 pub enum RuntimeSnapshotCompileError {
+    #[error("runtime extensions could not be prepared")]
+    ExtensionsUnavailable,
     #[error("runtime snapshot store is unavailable")]
     StoreUnavailable,
     #[error("runtime configuration changed while the snapshot was loading")]
@@ -310,6 +312,7 @@ pub enum RuntimeSnapshotCompileError {
 pub struct RuntimeSnapshotCompiler {
     store: Arc<dyn SnapshotStorePort>,
     catalogs: Arc<dyn ProviderCatalogPort>,
+    extensions: Option<Arc<dyn crate::runtime::extensions::ExtensionPreparationPort>>,
 }
 
 impl RuntimeSnapshotCompiler {
@@ -318,7 +321,20 @@ impl RuntimeSnapshotCompiler {
         store: Arc<dyn SnapshotStorePort>,
         catalogs: Arc<dyn ProviderCatalogPort>,
     ) -> Self {
-        Self { store, catalogs }
+        Self {
+            store,
+            catalogs,
+            extensions: None,
+        }
+    }
+
+    #[must_use]
+    pub fn with_extensions(
+        mut self,
+        extensions: Arc<dyn crate::runtime::extensions::ExtensionPreparationPort>,
+    ) -> Self {
+        self.extensions = Some(extensions);
+        self
     }
 
     pub(crate) fn store(&self) -> Arc<dyn SnapshotStorePort> {
@@ -327,14 +343,34 @@ impl RuntimeSnapshotCompiler {
 
     pub(crate) fn provider_catalog_generations(
         &self,
-    ) -> BTreeMap<ProviderKind, ProviderCatalogGeneration> {
-        self.catalogs.catalog_generations()
+        extensions: Option<&crate::runtime::extensions::ExtensionSetReference>,
+    ) -> Result<BTreeMap<ProviderKind, ProviderCatalogGeneration>, RuntimeSnapshotCompileError>
+    {
+        Ok(self
+            .catalogs_for_extensions(extensions)?
+            .catalog_generations())
+    }
+
+    fn catalogs_for_extensions(
+        &self,
+        extensions: Option<&crate::runtime::extensions::ExtensionSetReference>,
+    ) -> Result<Arc<dyn ProviderCatalogPort>, RuntimeSnapshotCompileError> {
+        self.catalogs
+            .for_extensions(extensions)
+            .map(|catalogs| catalogs.unwrap_or_else(|| self.catalogs.clone()))
+            .map_err(|_| RuntimeSnapshotCompileError::ExtensionsUnavailable)
     }
 
     /// 读取一个 revision，并为已注册 Provider 查询实时模型目录。
     pub async fn compile(&self) -> Result<RuntimeSnapshot, RuntimeSnapshotCompileError> {
+        // 同一配置 revision 的目录稳定性重试必须复用且强持有同一个扩展集合。
+        // 否则一次动态目录发布会让临时候选在下一轮前析构，随后重复 prepare
+        // 得到新的初始目录代次，稳定性检查永远无法收敛。
+        let mut prepared_extensions: Option<(
+            ConfigRevision,
+            crate::runtime::extensions::ExtensionSetReference,
+        )> = None;
         for _ in 0..MAXIMUM_CATALOG_STABILITY_ATTEMPTS {
-            let catalog_generations = self.catalogs.catalog_generations();
             let facts = self
                 .store
                 .load_snapshot_facts()
@@ -343,12 +379,48 @@ impl RuntimeSnapshotCompiler {
             if facts.config_revision != facts.observed_current_revision {
                 return Err(RuntimeSnapshotCompileError::RevisionChanged);
             }
+            let revision = facts.config_revision;
+            let extensions = match &self.extensions {
+                Some(preparer) => {
+                    let must_prepare =
+                        prepared_extensions
+                            .as_ref()
+                            .is_none_or(|(prepared_revision, prepared)| {
+                                *prepared_revision != revision || !prepared.is_ready()
+                            });
+                    if must_prepare {
+                        let prepared = preparer
+                            .prepare(revision)
+                            .await
+                            .map_err(|_| RuntimeSnapshotCompileError::ExtensionsUnavailable)?;
+                        prepared_extensions = Some((revision, prepared));
+                    }
+                    prepared_extensions
+                        .as_ref()
+                        .map(|(_, prepared)| prepared.clone())
+                }
+                None => None,
+            };
+            let catalogs = self.catalogs_for_extensions(extensions.as_ref())?;
+            let catalog_generations = catalogs.catalog_generations();
             let provider_kinds = catalog_generations.keys().cloned().collect();
             let snapshot =
-                compile_runtime_snapshot(facts, self.catalogs.as_ref(), provider_kinds).await?;
-            let observed_generations = self.catalogs.catalog_generations();
+                compile_runtime_snapshot(facts, catalogs.as_ref(), provider_kinds).await?;
+            let observed_generations = catalogs.catalog_generations();
             if catalog_generations == observed_generations {
-                return Ok(snapshot.with_provider_catalog_generations(observed_generations));
+                if extensions.is_some()
+                    && self
+                        .store
+                        .current_config_revision()
+                        .await
+                        .map_err(|_| RuntimeSnapshotCompileError::StoreUnavailable)?
+                        != revision
+                {
+                    return Err(RuntimeSnapshotCompileError::RevisionChanged);
+                }
+                return Ok(snapshot
+                    .with_provider_catalog_generations(observed_generations)
+                    .with_extensions(extensions));
             }
         }
         Err(RuntimeSnapshotCompileError::CatalogChanged)
@@ -360,8 +432,6 @@ async fn compile_runtime_snapshot(
     catalogs: &dyn ProviderCatalogPort,
     provider_kinds: Vec<ProviderKind>,
 ) -> Result<RuntimeSnapshot, RuntimeSnapshotCompileError> {
-    let registered_providers = provider_kinds.iter().cloned().collect::<BTreeSet<_>>();
-
     // 只有成功取得的完整目录能证明模型缺项；发现型目录和查询失败均交由上游验证。
     let mut provider_models = Vec::new();
     let mut exhaustive_provider_catalogs = BTreeSet::new();
@@ -402,14 +472,14 @@ async fn compile_runtime_snapshot(
     for account in facts.provider_accounts {
         let provider_kind = ProviderKind::new(account.provider_kind)
             .map_err(|_| RuntimeSnapshotCompileError::InvalidData)?;
-        if !registered_providers.contains(&provider_kind)
-            || accounts
-                .insert(
-                    account.account_id.clone(),
-                    RuntimeAccount::new(provider_kind, BTreeSet::new())
-                        .with_model_access(account.model_access),
-                )
-                .is_some()
+        // 账号归属独立于当前执行器集合；Provider 撤下后仍保留账号和分组，路由只选已注册执行器。
+        if accounts
+            .insert(
+                account.account_id.clone(),
+                RuntimeAccount::new(provider_kind, BTreeSet::new())
+                    .with_model_access(account.model_access),
+            )
+            .is_some()
         {
             return Err(RuntimeSnapshotCompileError::InvalidData);
         }
@@ -571,6 +641,7 @@ async fn compile_runtime_snapshot(
 /// 数据面使用的不可变配置快照。
 #[derive(Debug, Clone)]
 pub struct RuntimeSnapshot {
+    extensions: Option<crate::runtime::extensions::ExtensionSetReference>,
     pricing: Arc<crate::metering::PricingOverrides>,
     responses_max_decompressed_body_bytes: std::num::NonZeroUsize,
     request_location: Option<crate::account::RequestLocation>,
@@ -590,6 +661,19 @@ pub struct RuntimeSnapshot {
 }
 
 impl RuntimeSnapshot {
+    #[must_use]
+    pub fn with_extensions(
+        mut self,
+        extensions: Option<crate::runtime::extensions::ExtensionSetReference>,
+    ) -> Self {
+        self.extensions = extensions;
+        self
+    }
+
+    #[must_use]
+    pub const fn extensions(&self) -> Option<&crate::runtime::extensions::ExtensionSetReference> {
+        self.extensions.as_ref()
+    }
     #[must_use]
     pub fn with_pricing(mut self, pricing: Arc<crate::metering::PricingOverrides>) -> Self {
         self.pricing = pricing;
@@ -698,6 +782,7 @@ impl RuntimeSnapshot {
         client_policy_map.retain(|_, policy| policy.enabled());
 
         Ok(Self {
+            extensions: None,
             responses_max_decompressed_body_bytes: std::num::NonZeroUsize::new(64 * 1024 * 1024)
                 .expect("positive default limit"),
             pricing: Arc::default(),
@@ -773,6 +858,9 @@ impl RuntimeSnapshot {
     /// 返回目录发现模型与设置映射的并集，仅用于公开模型展示。
     #[must_use]
     pub fn public_models_for_provider(&self, provider: &ProviderKind) -> Vec<PublicModelId> {
+        if !self.providers.contains(provider) {
+            return Vec::new();
+        }
         let mut models = BTreeSet::new();
         if let Some(discovered) = self.provider_models.get(provider) {
             models.extend(
@@ -926,6 +1014,33 @@ impl RuntimeSnapshot {
         self.client_policies.values()
     }
 
+    #[must_use]
+    pub fn client_policy(&self, id: &ClientApiKeyId) -> Option<&ClientPolicy> {
+        self.client_policies.get(id)
+    }
+
+    /// 返回当前 Key 范围、本代次注册表与 circuit 条件共同允许的 Provider。
+    #[must_use]
+    pub fn available_providers(
+        &self,
+        account_scope: &FrozenAccountScope,
+        context: &RoutingContext,
+    ) -> BTreeSet<ProviderKind> {
+        account_scope
+            .provider_kinds()
+            .iter()
+            .filter(|provider| {
+                self.providers.contains(*provider)
+                    && context
+                        .required_provider
+                        .as_ref()
+                        .is_none_or(|required| required == *provider)
+                    && !context.blocked_providers.contains(*provider)
+            })
+            .cloned()
+            .collect()
+    }
+
     #[must_use]
     pub const fn min_codex_client_versions(&self) -> &CodexClientMinVersions {
         &self.min_codex_client_versions
@@ -937,6 +1052,33 @@ impl RuntimeSnapshot {
         operation: &Operation,
         account_scope: Arc<FrozenAccountScope>,
         context: &RoutingContext,
+    ) -> Result<RoutingPlan, RoutingError> {
+        self.plan_inner(public_model, operation, account_scope, context, true)
+    }
+
+    /// 管理探测已固定目标账号，不使用数据面 Key 的账号模型政策裁决探测资格。
+    pub(crate) fn plan_diagnostic(
+        &self,
+        public_model: &PublicModelId,
+        operation: &Operation,
+        context: &RoutingContext,
+    ) -> Result<RoutingPlan, RoutingError> {
+        self.plan_inner(
+            public_model,
+            operation,
+            self.all_account_scope(),
+            context,
+            false,
+        )
+    }
+
+    fn plan_inner(
+        &self,
+        public_model: &PublicModelId,
+        operation: &Operation,
+        account_scope: Arc<FrozenAccountScope>,
+        context: &RoutingContext,
+        enforce_account_model_policy: bool,
     ) -> Result<RoutingPlan, RoutingError> {
         let requirements = operation.capability_requirements();
         let mut candidates = Vec::new();
@@ -969,6 +1111,12 @@ impl RuntimeSnapshot {
                 UpstreamModelId::from_client_wire(mapped_model)
             }
             .map_err(|_| RoutingError::InvalidIdentifier)?;
+            // 强制 Provider 路由也不能扩大 Key 授权；管理诊断的目标账号由探测入口固定。
+            if enforce_account_model_policy
+                && !account_scope.allows_provider_model(provider, upstream_model.as_str())
+            {
+                continue;
+            }
             let emulated_features = match self
                 .provider_models
                 .get(provider)
@@ -1023,18 +1171,19 @@ impl RuntimeSnapshot {
         })
     }
 
-    /// 为 Provider 自有、且不属于文本模型目录的端点冻结请求计划。
+    /// 为 Provider 自有端点冻结请求计划。
     ///
-    /// 端点 adapter 已经确定 Provider，因此这里只执行账号范围、circuit 和注册
-    /// 状态检查；不会读取业务正文、构造模型或查询 Provider 文本模型目录。
+    /// 端点 adapter 已经确定 Provider。非模型 HTTP 端点不读取文本模型目录；Token
+    /// 计数端点仍必须匹配冻结账号范围及该模型声明的计数能力。
     pub fn plan_provider_endpoint(
         &self,
         provider: &ProviderKind,
+        upstream_model: Option<&UpstreamModelId>,
         operation: &Operation,
         account_scope: Arc<FrozenAccountScope>,
         context: &RoutingContext,
     ) -> Result<RoutingPlan, RoutingError> {
-        let allowed = !account_scope.provider_kinds().is_empty()
+        let available = !account_scope.provider_kinds().is_empty()
             && account_scope.provider_kinds().contains(provider)
             && self.providers.contains(provider)
             && context
@@ -1042,14 +1191,37 @@ impl RuntimeSnapshot {
                 .as_ref()
                 .is_none_or(|required| required == provider)
             && !context.blocked_providers.contains(provider);
-        if !allowed {
+        if !available
+            || upstream_model
+                .is_some_and(|model| !account_scope.allows_provider_model(provider, model.as_str()))
+        {
             return Err(RoutingError::NoCapableProviderEndpoint {
                 provider: provider.as_str().to_owned(),
             });
         }
+        let model_binding_valid =
+            matches!(operation.kind(), OperationKind::CountTokens) == upstream_model.is_some();
+        let model_capable = upstream_model.is_none_or(|model| {
+            match self
+                .provider_models
+                .get(provider)
+                .and_then(|models| models.get(model))
+            {
+                Some(capabilities) => capabilities
+                    .match_requirements(&operation.capability_requirements())
+                    .is_some(),
+                None => !self.exhaustive_provider_catalogs.contains(provider),
+            }
+        });
+        if !model_binding_valid || !model_capable {
+            return Err(RoutingError::UnsupportedProviderEndpoint {
+                provider: provider.as_str().to_owned(),
+                operation: operation.kind().as_str(),
+            });
+        }
         let candidate = ProviderCandidate {
             provider: provider.clone(),
-            upstream_model: None,
+            upstream_model: upstream_model.cloned(),
             emulated_features: BTreeSet::new(),
             account_scope: Arc::clone(&account_scope),
         };
diff --git a/backend/crates/gateway-core/src/runtime/extensions.rs b/backend/crates/gateway-core/src/runtime/extensions.rs
new file mode 100644
index 000000000..c44357dd9
--- /dev/null
+++ b/backend/crates/gateway-core/src/runtime/extensions.rs
@@ -0,0 +1,85 @@
+//! 可发布能力集合的中立身份与保活合同；不解释包格式、进程或管理配置。
+
+use std::{fmt, sync::Arc};
+
+use futures::future::BoxFuture;
+
+use crate::routing::ConfigRevision;
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct ExtensionSetId(String);
+
+impl ExtensionSetId {
+    pub fn new(value: String) -> Result<Self, ExtensionPreparationError> {
+        if value.is_empty()
+            || value.len() > 128
+            || !value
+                .bytes()
+                .all(|byte| byte.is_ascii_alphanumeric() || b"-_".contains(&byte))
+        {
+            return Err(ExtensionPreparationError);
+        }
+        Ok(Self(value))
+    }
+
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+/// 发布视图及在途请求持有引用；准备器只能用非拥有索引查找代次。
+pub trait ExtensionSetLease: Send + Sync {
+    fn is_ready(&self) -> bool;
+
+    /// 局部故障已有请求级处理计划时，集合仍可提供服务。
+    fn can_serve(&self) -> bool {
+        self.is_ready()
+    }
+}
+
+#[derive(Clone)]
+pub struct ExtensionSetReference {
+    id: ExtensionSetId,
+    lease: Arc<dyn ExtensionSetLease>,
+}
+
+impl ExtensionSetReference {
+    #[must_use]
+    pub fn new(id: ExtensionSetId, lease: Arc<dyn ExtensionSetLease>) -> Self {
+        Self { id, lease }
+    }
+    #[must_use]
+    pub const fn id(&self) -> &ExtensionSetId {
+        &self.id
+    }
+    #[must_use]
+    pub fn is_ready(&self) -> bool {
+        self.lease.is_ready()
+    }
+    #[must_use]
+    pub fn can_serve(&self) -> bool {
+        self.lease.can_serve()
+    }
+}
+
+impl fmt::Debug for ExtensionSetReference {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("ExtensionSetReference")
+            .field("id", &self.id)
+            .finish_non_exhaustive()
+    }
+}
+
+#[derive(Debug, Clone, Copy, thiserror::Error)]
+#[error("extension preparation is unavailable")]
+pub struct ExtensionPreparationError;
+
+/// 准备阶段读取与请求快照相同的持久 revision；不得自行发布当前代次。
+pub trait ExtensionPreparationPort: Send + Sync {
+    fn prepare(
+        &self,
+        revision: ConfigRevision,
+    ) -> BoxFuture<'_, Result<ExtensionSetReference, ExtensionPreparationError>>;
+}
diff --git a/backend/crates/gateway-core/src/runtime/mod.rs b/backend/crates/gateway-core/src/runtime/mod.rs
index 5595709f4..d352803ca 100644
--- a/backend/crates/gateway-core/src/runtime/mod.rs
+++ b/backend/crates/gateway-core/src/runtime/mod.rs
@@ -1,8 +1,10 @@
 //! 运行时快照的原子发布、健康状态与跨进程版本收敛。
 
+pub mod extensions;
+
 use std::collections::BTreeMap;
 use std::pin::Pin;
-use std::sync::{Arc, RwLock};
+use std::sync::{Arc, Mutex as SyncMutex, RwLock};
 use std::time::Duration;
 
 use futures::future::BoxFuture;
@@ -28,6 +30,7 @@ const INITIAL_BACKOFF: Duration = Duration::from_secs(1);
 const MAXIMUM_BACKOFF: Duration = Duration::from_secs(30);
 const UNUSED_LEASE_TTL: Duration = Duration::from_secs(30);
 const UNUSED_LEASE_RENEWAL: Duration = Duration::from_secs(10);
+const MAXIMUM_DEFERRED_REFRESH_ATTEMPTS: usize = 2;
 
 /// 不泄漏订阅基础设施细节的通知错误。
 #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
@@ -100,10 +103,17 @@ impl RuntimeSnapshotHandle {
             .map(|snapshot| snapshot.provider_catalog_generations().clone())
     }
 
+    /// 控制面只读诊断可观察尚未就绪的发布候选；数据面仍必须通过 [`Self::acquire`]。
+    #[must_use]
+    pub fn snapshot_for_diagnostics(&self) -> Option<Arc<RuntimeSnapshot>> {
+        read_unpoisoned(&self.current).clone()
+    }
+
     /// 冻结当前 Arc；后续发布不改变已经开始的请求。
     pub fn acquire(&self) -> Result<Arc<RuntimeSnapshot>, RuntimeSnapshotUnavailable> {
         read_unpoisoned(&self.current)
             .clone()
+            .filter(|snapshot| snapshot.extensions().is_none_or(|set| set.can_serve()))
             .ok_or(RuntimeSnapshotUnavailable)
     }
 }
@@ -115,7 +125,7 @@ impl HealthProbe for RuntimeSnapshotHandle {
 
     fn check(&self) -> BoxFuture<'_, HealthState> {
         Box::pin(async move {
-            if self.revision().is_some() {
+            if self.acquire().is_ok() {
                 HealthState::Healthy
             } else {
                 HealthState::Unhealthy("Runtime snapshot is unavailable".to_owned())
@@ -127,6 +137,93 @@ impl HealthProbe for RuntimeSnapshotHandle {
 /// Admin 提交配置后触发本进程刷新与跨进程通知的对象安全端口。
 pub trait SnapshotControl: Send + Sync {
     fn publish_committed(&self, committed_revision: ConfigRevision) -> BoxFuture<'_, ()>;
+
+    /// 目录发现回调可能发生在快照编译内部；该入口允许实现合并提交并在外层编译后刷新。
+    fn publish_committed_deferred(&self, committed_revision: ConfigRevision) -> BoxFuture<'_, ()> {
+        self.publish_committed(committed_revision)
+    }
+}
+
+#[derive(Default)]
+struct DeferredPublicationState {
+    active: bool,
+    scheduled: bool,
+    pending_revision: Option<ConfigRevision>,
+}
+
+struct ActiveRefreshGuard {
+    deferred: Arc<SyncMutex<DeferredPublicationState>>,
+    committed_revision: Option<ConfigRevision>,
+    armed: bool,
+}
+
+impl ActiveRefreshGuard {
+    fn begin(deferred: Arc<SyncMutex<DeferredPublicationState>>) -> Self {
+        let committed_revision = {
+            let mut state = lock_unpoisoned(&deferred);
+            state.active = true;
+            state.pending_revision.take()
+        };
+        Self {
+            deferred,
+            committed_revision,
+            armed: true,
+        }
+    }
+
+    fn merge(&mut self, revision: ConfigRevision) {
+        self.committed_revision = latest_revision(self.committed_revision, revision);
+    }
+
+    fn finish(&mut self) {
+        lock_unpoisoned(&self.deferred).active = false;
+        self.armed = false;
+    }
+}
+
+impl Drop for ActiveRefreshGuard {
+    fn drop(&mut self) {
+        if self.armed {
+            let mut state = lock_unpoisoned(&self.deferred);
+            if let Some(revision) = self.committed_revision {
+                state.pending_revision = latest_revision(state.pending_revision, revision);
+            }
+            state.active = false;
+        }
+    }
+}
+
+struct DeferredScheduleGuard {
+    deferred: Arc<SyncMutex<DeferredPublicationState>>,
+    armed: bool,
+}
+
+impl DeferredScheduleGuard {
+    fn new(deferred: Arc<SyncMutex<DeferredPublicationState>>) -> Self {
+        Self {
+            deferred,
+            armed: true,
+        }
+    }
+
+    fn finish(&mut self) {
+        lock_unpoisoned(&self.deferred).scheduled = false;
+        self.armed = false;
+    }
+}
+
+impl Drop for DeferredScheduleGuard {
+    fn drop(&mut self) {
+        if self.armed {
+            let mut state = lock_unpoisoned(&self.deferred);
+            state.scheduled = false;
+            if state.pending_revision.is_some() {
+                tracing::warn!(
+                    "deferred runtime snapshot publication was cancelled; reconciliation will retry"
+                );
+            }
+        }
+    }
 }
 
 /// 配置提交后的本进程快照发布与跨进程失效通知。
@@ -136,6 +233,7 @@ pub struct RuntimeSnapshotPublisher {
     snapshots: RuntimeSnapshotHandle,
     subscriptions: Arc<dyn SnapshotSubscriptionPort>,
     refresh_lock: Arc<Mutex<()>>,
+    deferred: Arc<SyncMutex<DeferredPublicationState>>,
 }
 
 enum RefreshMode {
@@ -155,6 +253,7 @@ impl RuntimeSnapshotPublisher {
             snapshots,
             subscriptions,
             refresh_lock: Arc::new(Mutex::new(())),
+            deferred: Arc::new(SyncMutex::new(DeferredPublicationState::default())),
         }
     }
 
@@ -170,6 +269,14 @@ impl RuntimeSnapshotPublisher {
         // 所有入口共享从读取事实到发布或暂停的完整临界区；只锁最后的替换会让
         // 旧编译覆盖新授权，或让晚到的失败暂停新快照。请求读取不等待此锁。
         let _refresh = self.refresh_lock.lock().await;
+        self.refresh_locked(mode).await
+    }
+
+    async fn refresh_locked(
+        &self,
+        mode: RefreshMode,
+    ) -> Result<ConfigRevision, RuntimeSnapshotCompileError> {
+        let mut active = ActiveRefreshGuard::begin(Arc::clone(&self.deferred));
         let configuration_changed = if matches!(mode, RefreshMode::Reconcile) {
             let persisted_revision = self
                 .compiler
@@ -184,23 +291,107 @@ impl RuntimeSnapshotPublisher {
                 self.published_revision().map(ConfigRevision::get),
                 persisted_revision.get(),
             );
-            if !changed && !self.provider_catalogs_need_refresh() {
+            if !changed
+                && !self.provider_catalogs_need_refresh()
+                && active.committed_revision.is_none()
+                && self
+                    .snapshots
+                    .acquire()
+                    .is_ok_and(|snapshot| snapshot.extensions().is_none_or(|set| set.is_ready()))
+            {
+                active.finish();
                 return Ok(persisted_revision);
             }
             changed
         } else {
             true
         };
-        let snapshot = self.compiler.compile().await.inspect_err(|_| {
-            // 仅目录代次变化时保留旧快照，下一周期继续对账；配置缺失、变化
-            // 或持久 revision 回退均须 fail closed，不按 revision 大小丢弃刷新。
-            if configuration_changed {
-                self.snapshots.suspend();
+        for attempt in 0..MAXIMUM_DEFERRED_REFRESH_ATTEMPTS {
+            let snapshot = match self.compiler.compile().await {
+                Ok(snapshot) => snapshot,
+                Err(RuntimeSnapshotCompileError::RevisionChanged)
+                    if attempt + 1 < MAXIMUM_DEFERRED_REFRESH_ATTEMPTS =>
+                {
+                    let pending = lock_unpoisoned(&self.deferred).pending_revision.take();
+                    if let Some(pending) = pending {
+                        active.merge(pending);
+                        continue;
+                    }
+                    if configuration_changed {
+                        self.snapshots.suspend();
+                    }
+                    return Err(RuntimeSnapshotCompileError::RevisionChanged);
+                }
+                Err(error) => {
+                    // 仅目录代次变化时保留旧快照，下一周期继续对账；配置缺失、变化
+                    // 或持久 revision 回退均须 fail closed，不按 revision 大小丢弃刷新。
+                    if configuration_changed {
+                        self.snapshots.suspend();
+                    }
+                    return Err(error);
+                }
+            };
+            let revision = snapshot.revision();
+            self.snapshots.publish(snapshot);
+            if let Some(committed_revision) = active.committed_revision.take() {
+                self.notify_committed_revision(committed_revision).await;
             }
-        })?;
-        let revision = snapshot.revision();
-        self.snapshots.publish(snapshot);
-        Ok(revision)
+            loop {
+                let pending = {
+                    let mut deferred = lock_unpoisoned(&self.deferred);
+                    match deferred.pending_revision.take() {
+                        Some(pending) => pending,
+                        None => {
+                            deferred.active = false;
+                            active.armed = false;
+                            return Ok(revision);
+                        }
+                    }
+                };
+                if pending <= revision {
+                    // 编译器自身可能因目录代次变化重读事实，已经包含该提交时
+                    // 只发送通知，不再做一次重复编译。通知期间的新提交仍回到同一单槽。
+                    self.notify_committed_revision(pending).await;
+                    continue;
+                }
+                active.merge(pending);
+                break;
+            }
+        }
+        self.snapshots.suspend();
+        tracing::warn!("deferred runtime snapshot refresh attempt limit reached");
+        Err(RuntimeSnapshotCompileError::RevisionChanged)
+    }
+
+    async fn publish_committed_deferred_inner(&self, committed_revision: ConfigRevision) {
+        let should_refresh = {
+            let mut deferred = lock_unpoisoned(&self.deferred);
+            deferred.pending_revision =
+                latest_revision(deferred.pending_revision, committed_revision);
+            if deferred.active || deferred.scheduled {
+                false
+            } else {
+                deferred.scheduled = true;
+                true
+            }
+        };
+        if !should_refresh {
+            return;
+        }
+
+        let mut schedule = DeferredScheduleGuard::new(Arc::clone(&self.deferred));
+        let _refresh = self.refresh_lock.lock().await;
+        schedule.finish();
+        let has_pending = {
+            let deferred = lock_unpoisoned(&self.deferred);
+            deferred.pending_revision.is_some()
+        };
+        if !has_pending {
+            return;
+        }
+        if let Err(error) = self.refresh_locked(RefreshMode::Required).await {
+            tracing::warn!(?error, "deferred runtime snapshot publication failed");
+        }
     }
 
     #[must_use]
@@ -210,17 +401,35 @@ impl RuntimeSnapshotPublisher {
 
     #[must_use]
     fn provider_catalogs_need_refresh(&self) -> bool {
-        self.snapshots.provider_catalog_generations().as_ref()
-            != Some(&self.compiler.provider_catalog_generations())
+        let Ok(snapshot) = self.snapshots.acquire() else {
+            return true;
+        };
+        self.compiler
+            .provider_catalog_generations(snapshot.extensions())
+            .as_ref()
+            != Ok(snapshot.provider_catalog_generations())
     }
 
     /// 数据库提交不能被目录或通知基础设施的暂时故障伪装成回滚。
     async fn publish_committed_inner(&self, committed_revision: ConfigRevision) {
-        let _ = self.refresh().await;
-        let _ = self
+        if let Err(error) = self.refresh().await {
+            tracing::warn!(?error, "committed runtime snapshot refresh failed");
+        }
+        self.notify_committed_revision(committed_revision).await;
+    }
+
+    async fn notify_committed_revision(&self, committed_revision: ConfigRevision) {
+        if let Err(error) = self
             .subscriptions
             .publish_snapshot_revision(committed_revision)
-            .await;
+            .await
+        {
+            tracing::warn!(
+                ?error,
+                revision = committed_revision.get(),
+                "runtime snapshot revision notification failed"
+            );
+        }
     }
 
     /// 交给 Host 的周期对账与长驻订阅任务。
@@ -272,6 +481,13 @@ impl SnapshotControl for RuntimeSnapshotPublisher {
             self.publish_committed_inner(committed_revision).await;
         })
     }
+
+    fn publish_committed_deferred(&self, committed_revision: ConfigRevision) -> BoxFuture<'_, ()> {
+        Box::pin(async move {
+            self.publish_committed_deferred_inner(committed_revision)
+                .await;
+        })
+    }
 }
 
 struct RuntimeSnapshotReconciliationTask {
@@ -366,3 +582,15 @@ fn write_unpoisoned<T>(lock: &RwLock<T>) -> std::sync::RwLockWriteGuard<'_, T> {
     lock.write()
         .unwrap_or_else(std::sync::PoisonError::into_inner)
 }
+
+fn lock_unpoisoned<T>(lock: &SyncMutex<T>) -> std::sync::MutexGuard<'_, T> {
+    lock.lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+}
+
+fn latest_revision(
+    current: Option<ConfigRevision>,
+    candidate: ConfigRevision,
+) -> Option<ConfigRevision> {
+    Some(current.map_or(candidate, |current| current.max(candidate)))
+}
diff --git a/backend/crates/gateway-core/src/validation.rs b/backend/crates/gateway-core/src/validation.rs
index 04b19a5be..622140256 100644
--- a/backend/crates/gateway-core/src/validation.rs
+++ b/backend/crates/gateway-core/src/validation.rs
@@ -107,6 +107,14 @@ pub enum RoutingError {
         /// adapter 已绑定的 Provider。
         provider: String,
     },
+    /// 固定 Provider 可用，但未声明该原生端点操作所需能力。
+    #[error("provider endpoint `{provider}` does not support `{operation}`")]
+    UnsupportedProviderEndpoint {
+        /// adapter 已绑定的 Provider。
+        provider: String,
+        /// 请求的稳定操作名。
+        operation: &'static str,
+    },
 }
 
 /// 调用方策略不满足约束或拒绝请求。
diff --git a/backend/crates/gateway-core/tests/engine/coordinator.rs b/backend/crates/gateway-core/tests/engine/coordinator.rs
index 4459462ba..899330ac8 100644
--- a/backend/crates/gateway-core/tests/engine/coordinator.rs
+++ b/backend/crates/gateway-core/tests/engine/coordinator.rs
@@ -294,6 +294,8 @@ enum Script {
 
 struct ScriptedProvider {
     profile_generation: AtomicUsize,
+    default_profile_calls: AtomicUsize,
+    default_profile: Mutex<Option<gateway_core::account::OpaqueProviderData>>,
     scripts: Mutex<VecDeque<Script>>,
     contexts: Mutex<Vec<AttemptContext>>,
     operations: Mutex<Vec<Operation>>,
@@ -312,6 +314,8 @@ impl ScriptedProvider {
     fn new(scripts: Vec<Script>) -> Self {
         Self {
             profile_generation: AtomicUsize::new(1),
+            default_profile_calls: AtomicUsize::new(0),
+            default_profile: Mutex::new(None),
             scripts: Mutex::new(scripts.into()),
             contexts: Mutex::new(Vec::new()),
             operations: Mutex::new(Vec::new()),
@@ -334,6 +338,13 @@ impl Provider for ScriptedProvider {
         Ok(gateway_core::account::OpaqueProviderData::new(fields))
     }
 
+    fn default_request_profile(
+        &self,
+    ) -> Result<Option<gateway_core::account::OpaqueProviderData>, ProviderError> {
+        self.default_profile_calls.fetch_add(1, Ordering::SeqCst);
+        Ok(self.default_profile.lock().unwrap().clone())
+    }
+
     fn name(&self) -> &'static str {
         "openai"
     }
@@ -349,7 +360,7 @@ impl Provider for ScriptedProvider {
     }
 
     async fn execute(
-        &self,
+        self: Arc<Self>,
         request: ProviderRequest,
         context: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
@@ -4680,3 +4691,47 @@ fn first_resolved_profile_is_frozen_across_account_retries() {
     assert_eq!(first.expose_to_provider()["generation"], 1);
     assert_eq!(contexts[1].request_profile(), Some(first));
 }
+
+#[test]
+fn provider_default_profile_is_applied_once_and_frozen_across_account_retries() {
+    use gateway_core::account::OpaqueProviderData;
+    let operation = generate_operation();
+    let route_plan = plan(&operation);
+    let (coordinator, _, provider) = coordinator(vec![
+        Script::Stream {
+            account_id: "acct_first",
+            items: vec![Err(ProviderError::new(
+                ProviderErrorKind::RateLimited,
+                UpstreamSendState::Sent,
+            )
+            .with_status(429)
+            .with_replay_safe())],
+        },
+        Script::Stream {
+            account_id: "acct_second",
+            items: complete_stream(None),
+        },
+    ]);
+    *provider.default_profile.lock().unwrap() = Some(OpaqueProviderData::new(
+        json!({"selection":"plugin-default"})
+            .as_object()
+            .unwrap()
+            .clone(),
+    ));
+    let mut session = block_on(coordinator.start(
+        model_request(&operation, SystemTime::now() + Duration::from_secs(30)),
+        operation,
+        route_plan,
+        None,
+        None,
+        CancellationToken::new(),
+    ))
+    .unwrap();
+    block_on(session.collect_uncommitted()).unwrap();
+    let contexts = provider.contexts.lock().unwrap();
+    assert_eq!(provider.default_profile_calls.load(Ordering::SeqCst), 1);
+    assert_eq!(contexts.len(), 2);
+    let first = contexts[0].request_profile().unwrap();
+    assert_eq!(first.expose_to_provider()["selection"], "plugin-default");
+    assert_eq!(contexts[1].request_profile(), Some(first));
+}
diff --git a/backend/crates/gateway-core/tests/engine/execution.rs b/backend/crates/gateway-core/tests/engine/execution.rs
index 3d5dc4b13..ec6fca267 100644
--- a/backend/crates/gateway-core/tests/engine/execution.rs
+++ b/backend/crates/gateway-core/tests/engine/execution.rs
@@ -1,5 +1,5 @@
 use std::{
-    collections::{BTreeMap, BTreeSet},
+    collections::{BTreeMap, BTreeSet, VecDeque},
     sync::{
         Arc, Mutex,
         atomic::{AtomicBool, AtomicUsize, Ordering},
@@ -159,6 +159,118 @@ fn budget_rejection_releases_client_concurrency_without_creating_a_charge() {
     }
 }
 
+#[test]
+fn plugin_page_key_selection_uses_normal_root_admission_and_budget() {
+    block_on(async {
+        let admissions = Arc::new(Admissions::default());
+        let budget = Arc::new(Budget {
+            reject: true,
+            active: admissions.active.clone(),
+            ..Default::default()
+        });
+        let service = service(admissions.clone(), budget.clone());
+        let key = ClientApiKeyId::new("key_start_test").unwrap();
+        let prepared = service.prepare_plugin_execution(&key).await.unwrap();
+        assert_eq!(prepared.client().policy().key_id(), &key);
+        let request = request(&service, ClientTransport::HttpSse);
+        let result = service
+            .start_prepared(
+                prepared,
+                gateway_core::engine::execution::PreparedExecutionRequest {
+                    public_model: request.public_model,
+                    operation: request.operation,
+                    metadata: request.metadata,
+                },
+            )
+            .await;
+        assert!(
+            matches!(result, Err(error) if error.client_error_code() == Some("key_daily_budget_exceeded"))
+        );
+        assert!(!admissions.active.load(Ordering::SeqCst));
+        assert!(budget.charges.lock().unwrap().is_empty());
+        assert!(
+            matches!(service.prepare_plugin_execution(&ClientApiKeyId::new("key_missing").unwrap()).await, Err(error) if error.kind() == GatewayErrorKind::Unauthorized)
+        );
+    });
+}
+
+#[test]
+fn provider_http_endpoint_uses_the_same_admission_and_budget_gate() {
+    let admissions = Arc::new(Admissions::default());
+    let budget = Arc::new(Budget {
+        reject: true,
+        active: admissions.active.clone(),
+        charges: Mutex::default(),
+        ..Default::default()
+    });
+    let service = service(admissions.clone(), budget.clone());
+    let operation = Operation::ProviderHttp(
+        ProviderHttpRequest::new(
+            "models",
+            ProviderHttpMethod::Get,
+            None,
+            Vec::new(),
+            RawHttpPayload::new("provider-http", Bytes::new()).expect("HTTP payload"),
+        )
+        .expect("provider HTTP operation"),
+    );
+    let result = block_on(service.start_provider_endpoint(StartProviderExecution {
+        client: service.authenticate("sk_start_test").expect("client"),
+        provider: ProviderKind::new("openai").expect("provider"),
+        upstream_model: None,
+        operation,
+        metadata: ExecutionRequestMetadata {
+            protocol: "provider-http".to_owned(),
+            endpoint: "/v1/providers/openai/http/models".to_owned(),
+            transport: ClientTransport::HttpJson,
+            stream: false,
+            client_ip: None,
+            user_agent: None,
+            previous_response_id: None,
+        },
+    }));
+
+    assert!(
+        matches!(result, Err(error) if error.client_error_code() == Some("key_daily_budget_exceeded"))
+    );
+    assert!(!admissions.active.load(Ordering::SeqCst));
+    assert!(budget.charges.lock().unwrap().is_empty());
+}
+
+#[test]
+fn bound_token_count_reports_an_explicit_unsupported_capability() {
+    let admissions = Arc::new(Admissions::default());
+    let budget = Arc::new(Budget {
+        active: admissions.active.clone(),
+        ..Budget::default()
+    });
+    let service = service(admissions.clone(), budget.clone());
+    let operation = Operation::CountTokens(TokenCountRequest::from_raw_json(
+        RawJsonPayload::new("token-count", Bytes::from_static(br#"{"input":"hello"}"#))
+            .expect("token count payload"),
+    ));
+
+    let result = block_on(service.start_provider_endpoint(StartProviderExecution {
+        client: service.authenticate("sk_start_test").expect("client"),
+        provider: ProviderKind::new("openai").expect("provider"),
+        upstream_model: Some(UpstreamModelId::new("gpt-start").expect("model")),
+        operation,
+        metadata: ExecutionRequestMetadata {
+            protocol: "token-count".to_owned(),
+            endpoint: "/v1/providers/openai/models/gpt-start/count_tokens".to_owned(),
+            transport: ClientTransport::HttpJson,
+            stream: false,
+            client_ip: None,
+            user_agent: None,
+            previous_response_id: None,
+        },
+    }));
+
+    assert!(matches!(result, Err(error) if error.kind() == GatewayErrorKind::Unsupported));
+    assert!(!admissions.active.load(Ordering::SeqCst));
+    assert!(budget.charges.lock().unwrap().is_empty());
+}
+
 #[test]
 fn reused_client_uses_updated_limits_for_each_execution() {
     let snapshots = RuntimeSnapshotHandle::new(start_snapshot());
@@ -226,6 +338,126 @@ fn reused_client_cannot_start_after_key_disable_or_snapshot_suspension() {
     }
 }
 
+struct FrontendAuthenticationFixture {
+    decisions: Mutex<VecDeque<FrontendAuthenticationDecision>>,
+    identities: BTreeMap<String, ClientApiKeyId>,
+    exclusive: bool,
+    calls: AtomicUsize,
+}
+
+impl FrontendAuthenticationPlan for FrontendAuthenticationFixture {
+    fn authenticate<'a>(
+        &'a self,
+        _: &'a ClientAuthenticationRequest,
+    ) -> BoxFuture<'a, Result<FrontendAuthenticationDecision, FrontendAuthenticationError>> {
+        Box::pin(async move {
+            self.calls.fetch_add(1, Ordering::SeqCst);
+            self.decisions
+                .lock()
+                .unwrap()
+                .pop_front()
+                .ok_or(FrontendAuthenticationError)
+        })
+    }
+
+    fn client_key_id(&self, principal: &str) -> Option<ClientApiKeyId> {
+        self.identities.get(principal).cloned()
+    }
+
+    fn exclusive(&self) -> bool {
+        self.exclusive
+    }
+}
+
+struct AuthenticationGeneration(Arc<dyn FrontendAuthenticationPlan>);
+
+impl ExtensionSetLease for AuthenticationGeneration {
+    fn is_ready(&self) -> bool {
+        Arc::strong_count(&self.0) > 0
+    }
+}
+
+fn authentication_generation(
+    index: &FrontendAuthenticationExtensionIndex,
+    id: &str,
+    plan: Arc<dyn FrontendAuthenticationPlan>,
+) -> ExtensionSetReference {
+    let id = ExtensionSetId::new(id.to_owned()).unwrap();
+    let plan = index.register(id.clone(), plan).unwrap();
+    ExtensionSetReference::new(id, Arc::new(AuthenticationGeneration(plan)))
+}
+
+#[test]
+fn reused_client_is_reauthenticated_by_the_current_frontend_plan_without_identity_drift() {
+    block_on(async {
+        let authentication = FrontendAuthenticationExtensionIndex::default();
+        let initial_plan = Arc::new(FrontendAuthenticationFixture {
+            decisions: Mutex::new(VecDeque::from([
+                FrontendAuthenticationDecision::Authenticated {
+                    principal: "external-user".into(),
+                },
+            ])),
+            identities: BTreeMap::from([(
+                "external-user".into(),
+                ClientApiKeyId::new("key_start_test").unwrap(),
+            )]),
+            exclusive: true,
+            calls: AtomicUsize::new(0),
+        });
+        let initial = start_snapshot().with_extensions(Some(authentication_generation(
+            &authentication,
+            "authentication-first",
+            initial_plan.clone(),
+        )));
+        let snapshots = RuntimeSnapshotHandle::new(initial);
+        let admissions = Arc::new(Admissions::default());
+        let service = DefaultExecutionService::new(
+            snapshots.clone(),
+            Arc::new(TrackingExecutionStore::default()),
+            ProviderRegistry::default(),
+            admissions.clone(),
+            Arc::new(UnusedCircuits),
+            Arc::new(UnusedContinuation),
+            Arc::new(RecordingClientApiKeyUsage::default()),
+        )
+        .with_frontend_authentication(authentication.clone());
+        let client = service
+            .authenticate_request(
+                ClientAuthenticationRequest::new("External controlled-fixture").unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(initial_plan.calls.load(Ordering::SeqCst), 1);
+
+        let replacement_plan = Arc::new(FrontendAuthenticationFixture {
+            decisions: Mutex::new(VecDeque::from([
+                FrontendAuthenticationDecision::Authenticated {
+                    principal: "external-user".into(),
+                },
+            ])),
+            identities: BTreeMap::from([(
+                "external-user".into(),
+                ClientApiKeyId::new("another-key").unwrap(),
+            )]),
+            exclusive: true,
+            calls: AtomicUsize::new(0),
+        });
+        snapshots.publish(
+            start_snapshot().with_extensions(Some(authentication_generation(
+                &authentication,
+                "authentication-second",
+                replacement_plan.clone(),
+            ))),
+        );
+        let mut next = request(&service, ClientTransport::WebSocket);
+        next.client = client;
+        let result = service.start(next).await;
+        assert!(matches!(result, Err(error) if error.kind() == GatewayErrorKind::Unauthorized));
+        assert_eq!(replacement_plan.calls.load(Ordering::SeqCst), 1);
+        assert!(admissions.limits.lock().unwrap().is_empty());
+    });
+}
+
 #[test]
 fn cancellation_and_pre_send_failure_settle_zero_and_release_concurrency_for_all_transports() {
     let admissions = Arc::new(Admissions::default());
@@ -490,10 +722,1702 @@ struct ChargedProvider {
     fail: bool,
 }
 
+#[test]
+fn published_provider_update_does_not_replace_an_already_started_request() {
+    block_on(async {
+        let index = gateway_core::engine::extensions::ProviderExtensionIndex::new(
+            ProviderRegistry::default(),
+        );
+        let old = Arc::new(ChargedProvider::default());
+        let current = Arc::new(ChargedProvider::default());
+        let reference = super::extensions::register(&index, "first", vec![old.clone()]);
+        let snapshots =
+            RuntimeSnapshotHandle::new(start_snapshot().with_extensions(Some(reference)));
+        let service = DefaultExecutionService::new(
+            snapshots.clone(),
+            Arc::new(TrackingExecutionStore::default()),
+            index.registry(),
+            Arc::new(Admissions::default()),
+            Arc::new(UnusedCircuits),
+            Arc::new(UnusedContinuation),
+            Arc::new(RecordingClientApiKeyUsage::default()),
+        );
+        let mut started = service
+            .start(request(&service, ClientTransport::HttpJson))
+            .await
+            .unwrap();
+        let reference = super::extensions::register(&index, "second", vec![current.clone()]);
+        snapshots.publish(start_snapshot().with_extensions(Some(reference)));
+        assert_eq!(
+            started.session.collect_uncommitted().await.unwrap().len(),
+            3
+        );
+        started.session.commit_downstream(Some(200)).await.unwrap();
+        started.session.detach_finalize().await;
+        assert_eq!(old.policies.lock().unwrap().len(), 1);
+        assert!(current.policies.lock().unwrap().is_empty());
+        let mut started = service
+            .start(request(&service, ClientTransport::HttpJson))
+            .await
+            .unwrap();
+        assert_eq!(
+            started.session.collect_uncommitted().await.unwrap().len(),
+            3
+        );
+        started.session.commit_downstream(Some(200)).await.unwrap();
+        started.session.detach_finalize().await;
+        assert_eq!(current.policies.lock().unwrap().len(), 1);
+    });
+}
+
+#[derive(Debug)]
+struct FixedRoutingPolicy {
+    decision: ModelRouteDecision,
+    inputs: Mutex<Vec<ModelRouteInput>>,
+}
+
+impl RequestPolicyPlan for FixedRoutingPolicy {
+    fn route_model(
+        &self,
+        input: ModelRouteInput,
+    ) -> BoxFuture<'static, Result<ModelRouteDecision, RequestPolicyFault>> {
+        self.inputs.lock().unwrap().push(input);
+        let decision = self.decision.clone();
+        Box::pin(async move { Ok(decision) })
+    }
+
+    fn schedule_account(
+        &self,
+        _: AccountScheduleInput,
+    ) -> BoxFuture<'static, Result<AccountScheduleDecision, RequestPolicyFault>> {
+        Box::pin(async { Ok(AccountScheduleDecision::Delegate) })
+    }
+}
+
+#[derive(Debug)]
+struct NestedRoutingPolicy;
+
+impl RequestPolicyPlan for NestedRoutingPolicy {
+    fn route_model(
+        &self,
+        input: ModelRouteInput,
+    ) -> BoxFuture<'static, Result<ModelRouteDecision, RequestPolicyFault>> {
+        let provider = if input.suppresses_plugin("nested-fixture") {
+            "nested"
+        } else {
+            "openai"
+        };
+        Box::pin(async move {
+            Ok(ModelRouteDecision::Route {
+                provider: Some(ProviderKind::new(provider).unwrap()),
+                model: None,
+            })
+        })
+    }
+
+    fn schedule_account(
+        &self,
+        _: AccountScheduleInput,
+    ) -> BoxFuture<'static, Result<AccountScheduleDecision, RequestPolicyFault>> {
+        Box::pin(async { Ok(AccountScheduleDecision::Delegate) })
+    }
+}
+
+#[derive(Debug)]
+struct EffectObservingPolicy;
+
+impl RequestPolicyPlan for EffectObservingPolicy {
+    fn route_model(
+        &self,
+        input: ModelRouteInput,
+    ) -> BoxFuture<'static, Result<ModelRouteDecision, RequestPolicyFault>> {
+        input.execution_effects().observe();
+        Box::pin(async { Ok(ModelRouteDecision::Unhandled) })
+    }
+
+    fn schedule_account(
+        &self,
+        _: AccountScheduleInput,
+    ) -> BoxFuture<'static, Result<AccountScheduleDecision, RequestPolicyFault>> {
+        Box::pin(async { Ok(AccountScheduleDecision::Delegate) })
+    }
+}
+
+struct ProcessingProvider;
+
+#[async_trait]
+impl Provider for ProcessingProvider {
+    fn name(&self) -> &'static str {
+        "openai"
+    }
+
+    fn catalog_generation(&self) -> ProviderCatalogGeneration {
+        ProviderCatalogGeneration::default()
+    }
+
+    async fn query_model_capabilities(
+        &self,
+    ) -> Result<Vec<ProviderModelCapabilities>, ProviderError> {
+        Ok(Vec::new())
+    }
+
+    async fn execute(
+        self: Arc<Self>,
+        request: ProviderRequest,
+        _: AttemptContext,
+    ) -> Result<ProviderStream, ProviderError> {
+        let candidate = request.candidate();
+        let provider = candidate.provider().clone();
+        let account = ProviderAccountId::new("acct_openai").unwrap();
+        let transport = UpstreamTransport::new("websocket").unwrap();
+        let metadata = ProviderCallMetadata::new(
+            provider,
+            candidate.upstream_model().cloned().unwrap(),
+            account,
+            transport,
+        );
+        let response = ResponseMeta::new("response-policy", "gpt-start");
+        let event = |event_type: &str, fact| {
+            ProviderEvent::canonical_with_wire(
+                vec![fact],
+                ProtocolWireEvent::json(
+                    "openai",
+                    Some(event_type.to_owned()),
+                    json!({"type": event_type, "future": {"nested": true}}),
+                )
+                .unwrap(),
+            )
+        };
+        Ok(ProviderStream::new(
+            metadata,
+            futures::stream::iter([
+                Ok(event(
+                    "response.created",
+                    GatewayEvent::Started(response.clone()),
+                )),
+                Ok(event(
+                    "response.completed",
+                    GatewayEvent::Completed(response),
+                )),
+            ]),
+            (),
+        ))
+    }
+}
+
+struct PendingNestedProvider;
+
+#[async_trait]
+impl Provider for PendingNestedProvider {
+    fn name(&self) -> &'static str {
+        "nested"
+    }
+
+    fn catalog_generation(&self) -> ProviderCatalogGeneration {
+        ProviderCatalogGeneration::default()
+    }
+
+    async fn query_model_capabilities(
+        &self,
+    ) -> Result<Vec<ProviderModelCapabilities>, ProviderError> {
+        Ok(Vec::new())
+    }
+
+    async fn execute(
+        self: Arc<Self>,
+        request: ProviderRequest,
+        _: AttemptContext,
+    ) -> Result<ProviderStream, ProviderError> {
+        let candidate = request.candidate();
+        let metadata = ProviderCallMetadata::new(
+            candidate.provider().clone(),
+            candidate.upstream_model().cloned().unwrap(),
+            ProviderAccountId::new("acct_nested").unwrap(),
+            UpstreamTransport::new("websocket").unwrap(),
+        );
+        Ok(ProviderStream::new(
+            metadata,
+            futures::stream::pending::<Result<ProviderEvent, ProviderError>>(),
+            (),
+        ))
+    }
+}
+
+fn request_policy_snapshot(
+    generation: ExtensionSetReference,
+    providers: &[ProviderKind],
+) -> RuntimeSnapshot {
+    let directory = Arc::new(RuntimeAccountDirectory::new(
+        providers
+            .iter()
+            .map(|provider| {
+                (
+                    ProviderAccountId::new(format!("acct_{}", provider.as_str())).unwrap(),
+                    RuntimeAccount::new(provider.clone(), BTreeSet::new()),
+                )
+            })
+            .collect(),
+    ));
+    let capabilities =
+        ModelCapabilities::new(BTreeSet::from([OperationKind::Generate]), Some(16_000));
+    RuntimeSnapshot::new(
+        ConfigRevision::new(1).unwrap(),
+        AccountSelectionPolicy::new(
+            RotationStrategy::Smart,
+            std::num::NonZeroU32::new(2).unwrap(),
+            Duration::from_millis(1),
+        ),
+        providers.to_vec(),
+        providers
+            .iter()
+            .map(|provider| {
+                ProviderModel::new(
+                    provider.clone(),
+                    UpstreamModelId::new("gpt-start").unwrap(),
+                    capabilities.clone(),
+                )
+            })
+            .collect(),
+        vec![ClientPolicy::new(
+            ClientApiKeyId::new("key_start_test").unwrap(),
+            PlaintextClientApiKey::new("sk_start_test").unwrap(),
+            Arc::new(FrozenAccountScope::new(
+                Arc::clone(&directory),
+                ClientRoutingScope::all_accounts(),
+            )),
+            true,
+            RateLimits::unlimited(),
+        )],
+    )
+    .unwrap()
+    .with_account_directory(directory)
+    .with_extensions(Some(generation))
+}
+
+#[test]
+fn completed_parent_rejects_new_nested_execution_and_cancels_an_active_child() {
+    block_on(async {
+        let parent_provider = Arc::new(ProcessingProvider);
+        let providers = ProviderRegistry::new([
+            parent_provider as Arc<dyn Provider>,
+            Arc::new(PendingNestedProvider) as Arc<dyn Provider>,
+        ])
+        .unwrap();
+        let provider_index = ProviderExtensionIndex::new(providers);
+        let generation = super::extensions::register(&provider_index, "nested-cancel", vec![]);
+        let policy_index = RequestPolicyExtensionIndex::default();
+        let _owner = policy_index
+            .register(generation.id().clone(), Arc::new(NestedRoutingPolicy))
+            .unwrap();
+        let service = DefaultExecutionService::new(
+            RuntimeSnapshotHandle::new(request_policy_snapshot(
+                generation,
+                &[
+                    ProviderKind::new("openai").unwrap(),
+                    ProviderKind::new("nested").unwrap(),
+                ],
+            )),
+            Arc::new(TrackingExecutionStore::default()),
+            provider_index.registry(),
+            Arc::new(Admissions::default()),
+            Arc::new(UnusedCircuits),
+            Arc::new(UnusedContinuation),
+            Arc::new(RecordingClientApiKeyUsage::default()),
+        )
+        .with_request_policies(policy_index);
+
+        let mut parent = service
+            .start(request(&service, ClientTransport::HttpJson))
+            .await
+            .unwrap();
+        let nested_request = |parent_request_id| NestedModelExecutionRequest {
+            parent_request_id,
+            initiating_plugin_instance_id: "nested-fixture".to_owned(),
+            public_model: PublicModelId::new("gpt-start").unwrap(),
+            operation: start_operation(),
+            metadata: ExecutionRequestMetadata {
+                protocol: "openai".to_owned(),
+                endpoint: "host.model".to_owned(),
+                transport: ClientTransport::InternalPlugin,
+                stream: true,
+                client_ip: None,
+                user_agent: None,
+                previous_response_id: None,
+            },
+            provider: Some(ProviderKind::new("nested").unwrap()),
+            account: None,
+            parent_account: None,
+        };
+        let mut child = gateway_core::engine::nested::NestedModelExecutionPort::start(
+            &service,
+            nested_request(parent.request_id.clone()),
+        )
+        .await
+        .unwrap();
+
+        let events = parent.session.collect_uncommitted().await.unwrap();
+        assert!(
+            events
+                .iter()
+                .any(|event| { matches!(event.canonical_facts(), [GatewayEvent::Completed(_)]) })
+        );
+        parent.session.commit_downstream(Some(200)).await.unwrap();
+        assert!(parent.session.is_finalized());
+
+        let new_child = gateway_core::engine::nested::NestedModelExecutionPort::start(
+            &service,
+            nested_request(parent.request_id.clone()),
+        )
+        .await;
+        assert!(
+            matches!(new_child, Err(error) if error.kind() == GatewayErrorKind::PolicyDenied),
+            "a finalized parent must be removed from the callback registry"
+        );
+        assert!(
+            matches!(
+                child.session.next_event().await,
+                Err(EngineError::Cancelled)
+            ),
+            "an in-flight child must inherit cancellation from the released parent authority"
+        );
+        child.session.detach_finalize().await;
+        parent.session.detach_finalize().await;
+    });
+}
+
+struct TestNativeResponseTranslator;
+
+impl NativeResponseTranslator for TestNativeResponseTranslator {
+    fn source_protocol(&self) -> &str {
+        "xai"
+    }
+
+    fn target_protocol(&self) -> &str {
+        "openai"
+    }
+
+    fn translate(
+        &mut self,
+        event: &ProtocolWireEvent,
+    ) -> Result<Vec<ProtocolWireEvent>, ProviderError> {
+        if event.data().get("drop").and_then(Value::as_bool) == Some(true) {
+            return Ok(Vec::new());
+        }
+        let count = if event.data().get("expand").and_then(Value::as_bool) == Some(true) {
+            2
+        } else {
+            1
+        };
+        (0..count)
+            .map(|part| {
+                let mut body = event.data().clone();
+                body["native_translated"] = json!(true);
+                body["native_part"] = json!(part);
+                ProtocolWireEvent::json("openai", event.event_type().map(str::to_owned), body)
+                    .map_err(|_| {
+                        ProviderError::new(ProviderErrorKind::Protocol, UpstreamSendState::Sent)
+                    })
+            })
+            .collect()
+    }
+}
+
+struct NativeResponseBoundaryProvider;
+
+#[async_trait]
+impl Provider for NativeResponseBoundaryProvider {
+    fn name(&self) -> &'static str {
+        "xai"
+    }
+
+    fn catalog_generation(&self) -> ProviderCatalogGeneration {
+        ProviderCatalogGeneration::default()
+    }
+
+    async fn query_model_capabilities(
+        &self,
+    ) -> Result<Vec<ProviderModelCapabilities>, ProviderError> {
+        Ok(Vec::new())
+    }
+
+    async fn execute(
+        self: Arc<Self>,
+        request: ProviderRequest,
+        _: AttemptContext,
+    ) -> Result<ProviderStream, ProviderError> {
+        let candidate = request.candidate();
+        let response = ResponseMeta::new("response-native-boundary", "gpt-start");
+        let event = |event_type: &str, body: Value, facts: Vec<GatewayEvent>| {
+            let wire = ProtocolWireEvent::json("xai", Some(event_type.to_owned()), body).unwrap();
+            if facts.is_empty() {
+                ProviderEvent::wire(wire)
+            } else {
+                ProviderEvent::canonical_with_wire(facts, wire)
+            }
+        };
+        let events = futures::stream::iter([
+            Ok(event(
+                "response.created",
+                json!({"type":"response.created","future":{"nested":true}}),
+                vec![GatewayEvent::Started(response.clone())],
+            )),
+            Ok(event(
+                "response.internal",
+                json!({"type":"response.internal","drop":true}),
+                vec![GatewayEvent::Usage(Usage {
+                    input_tokens: Some(3),
+                    total_tokens: Some(3),
+                    ..Usage::default()
+                })],
+            )),
+            Ok(event(
+                "response.output_text.delta",
+                json!({"type":"response.output_text.delta","delta":"hi","expand":true}),
+                Vec::new(),
+            )),
+            Ok(event(
+                "response.completed",
+                json!({"type":"response.completed"}),
+                vec![GatewayEvent::Completed(response)],
+            )),
+        ]);
+        let metadata = ProviderCallMetadata::new(
+            candidate.provider().clone(),
+            candidate.upstream_model().unwrap().clone(),
+            ProviderAccountId::new("acct_xai").unwrap(),
+            UpstreamTransport::new("websocket").unwrap(),
+        );
+        Ok(ProviderStream::new(metadata, events, ())
+            .with_native_response_translator(TestNativeResponseTranslator))
+    }
+}
+
+#[test]
+fn native_response_processing_uses_the_real_translation_boundary() {
+    block_on(async {
+        let provider_index = ProviderExtensionIndex::new(
+            ProviderRegistry::new([Arc::new(NativeResponseBoundaryProvider) as Arc<dyn Provider>])
+                .unwrap(),
+        );
+        let generation = super::extensions::register(&provider_index, "native-response", vec![]);
+        let observer_index = RequestObserverExtensionIndex::default();
+        let observer = Arc::new(RecordingRequestObserver::default());
+        let _observer_owner = observer_index
+            .register(generation.id().clone(), observer.clone())
+            .unwrap();
+        let service = DefaultExecutionService::new(
+            RuntimeSnapshotHandle::new(request_policy_snapshot(
+                generation,
+                &[ProviderKind::new("xai").unwrap()],
+            )),
+            Arc::new(TrackingExecutionStore::default()),
+            provider_index.registry(),
+            Arc::new(Admissions::default()),
+            Arc::new(UnusedCircuits),
+            Arc::new(UnusedContinuation),
+            Arc::new(RecordingClientApiKeyUsage::default()),
+        )
+        .with_request_observers(observer_index);
+
+        let mut started = service
+            .start(request(&service, ClientTransport::HttpJson))
+            .await
+            .unwrap();
+        let events = started.session.collect_uncommitted().await.unwrap();
+        assert_eq!(events.len(), 5);
+        assert!(events.iter().all(|event| {
+            event.wire_event().is_none_or(|wire| {
+                wire.protocol() == "openai" && wire.data()["native_translated"] == json!(true)
+            })
+        }));
+        assert_eq!(
+            events
+                .iter()
+                .filter(|event| event.wire_event().is_none())
+                .flat_map(ProviderEvent::canonical_facts)
+                .filter(|fact| matches!(fact, GatewayEvent::Usage(_)))
+                .count(),
+            1
+        );
+        assert_eq!(
+            events[0]
+                .wire_event()
+                .and_then(|wire| wire.data().pointer("/future/nested")),
+            Some(&json!(true))
+        );
+        assert_eq!(
+            events
+                .iter()
+                .filter(|event| event
+                    .wire_event()
+                    .is_some_and(|wire| wire.data()["expand"] == json!(true)))
+                .count(),
+            2
+        );
+        assert_eq!(
+            events
+                .iter()
+                .flat_map(ProviderEvent::canonical_facts)
+                .filter(|fact| matches!(fact, GatewayEvent::Started(_)))
+                .count(),
+            1
+        );
+        assert_eq!(
+            events
+                .iter()
+                .flat_map(ProviderEvent::canonical_facts)
+                .filter(|fact| matches!(fact, GatewayEvent::Completed(_)))
+                .count(),
+            1
+        );
+
+        {
+            let websocket = observer.websocket_observations.lock().unwrap();
+            assert_eq!(websocket.len(), 4);
+            assert!(websocket.iter().all(|observation| {
+                observation.wire().protocol() == "xai"
+                    && observation.wire().data().get("native_translated").is_none()
+            }));
+        }
+        started.session.commit_downstream(Some(200)).await.unwrap();
+        started.session.detach_finalize().await;
+    });
+}
+
+struct NativeTranslationFactsProvider;
+
+#[async_trait]
+impl Provider for NativeTranslationFactsProvider {
+    fn name(&self) -> &'static str {
+        "xai"
+    }
+
+    fn catalog_generation(&self) -> ProviderCatalogGeneration {
+        ProviderCatalogGeneration::default()
+    }
+
+    async fn query_model_capabilities(
+        &self,
+    ) -> Result<Vec<ProviderModelCapabilities>, ProviderError> {
+        Ok(Vec::new())
+    }
+
+    async fn execute(
+        self: Arc<Self>,
+        request: ProviderRequest,
+        _: AttemptContext,
+    ) -> Result<ProviderStream, ProviderError> {
+        let candidate = request.candidate();
+        let response = ResponseMeta::new("response-translated-facts", "gpt-start");
+        let event = |event_type: &str, body: Value, facts: Vec<GatewayEvent>| {
+            ProviderEvent::canonical_with_wire(
+                facts,
+                ProtocolWireEvent::json("xai", Some(event_type.to_owned()), body).unwrap(),
+            )
+        };
+        let events = futures::stream::iter([
+            Ok(event(
+                "response.created",
+                json!({"type":"response.created"}),
+                vec![GatewayEvent::Started(response.clone())],
+            )),
+            Ok(event(
+                "response.usage",
+                json!({"type":"response.usage","drop":true}),
+                vec![GatewayEvent::Usage(Usage {
+                    input_tokens: Some(9),
+                    output_tokens: Some(4),
+                    total_tokens: Some(13),
+                    ..Usage::default()
+                })],
+            )),
+            Ok(event(
+                "response.completed",
+                json!({"type":"response.completed"}),
+                vec![GatewayEvent::Completed(response)],
+            )),
+        ]);
+        let metadata = ProviderCallMetadata::new(
+            candidate.provider().clone(),
+            candidate.upstream_model().unwrap().clone(),
+            ProviderAccountId::new("acct_xai").unwrap(),
+            UpstreamTransport::new("http_sse").unwrap(),
+        );
+        Ok(ProviderStream::new(metadata, events, ())
+            .with_native_response_translator(TestNativeResponseTranslator))
+    }
+}
+
+#[test]
+fn response_translation_zero_output_preserves_canonical_usage_and_finalization() {
+    block_on(async {
+        let provider_index = ProviderExtensionIndex::new(
+            ProviderRegistry::new([Arc::new(NativeTranslationFactsProvider) as Arc<dyn Provider>])
+                .unwrap(),
+        );
+        let generation = super::extensions::register(&provider_index, "translated-facts", vec![]);
+        let store = Arc::new(TrackingExecutionStore::default());
+        let service = DefaultExecutionService::new(
+            RuntimeSnapshotHandle::new(request_policy_snapshot(
+                generation,
+                &[ProviderKind::new("xai").unwrap()],
+            )),
+            store.clone(),
+            provider_index.registry(),
+            Arc::new(Admissions::default()),
+            Arc::new(UnusedCircuits),
+            Arc::new(UnusedContinuation),
+            Arc::new(RecordingClientApiKeyUsage::default()),
+        );
+
+        let mut started = service
+            .start(request(&service, ClientTransport::HttpJson))
+            .await
+            .unwrap();
+        let events = started.session.collect_uncommitted().await.unwrap();
+        assert_eq!(events.len(), 3);
+        let usage = events
+            .iter()
+            .filter(|event| event.wire_event().is_none())
+            .flat_map(ProviderEvent::canonical_facts)
+            .find_map(|fact| match fact {
+                GatewayEvent::Usage(usage) => Some(usage),
+                _ => None,
+            })
+            .expect("wire-filtered Usage must remain client-visible");
+        assert_eq!(usage.total_tokens, Some(13));
+        assert_eq!(
+            events
+                .iter()
+                .flat_map(ProviderEvent::canonical_facts)
+                .filter(|fact| matches!(fact, GatewayEvent::Completed(_)))
+                .count(),
+            1
+        );
+
+        started.session.commit_downstream(Some(200)).await.unwrap();
+        started.session.detach_finalize().await;
+        let finalizations = store.finalizations.lock().unwrap();
+        assert_eq!(finalizations.len(), 1);
+        assert_eq!(finalizations[0].usage, usage.clone());
+    });
+}
+
+#[derive(Default)]
+struct FailingNativeResponseTranslator {
+    translated: bool,
+}
+
+impl NativeResponseTranslator for FailingNativeResponseTranslator {
+    fn source_protocol(&self) -> &str {
+        "xai"
+    }
+
+    fn target_protocol(&self) -> &str {
+        "openai"
+    }
+
+    fn translate(
+        &mut self,
+        event: &ProtocolWireEvent,
+    ) -> Result<Vec<ProtocolWireEvent>, ProviderError> {
+        if self.translated {
+            return Err(ProviderError::new(
+                ProviderErrorKind::Protocol,
+                UpstreamSendState::Sent,
+            ));
+        }
+        self.translated = true;
+        Ok(vec![
+            ProtocolWireEvent::json(
+                "openai",
+                event.event_type().map(str::to_owned),
+                event.data().clone(),
+            )
+            .unwrap(),
+        ])
+    }
+}
+
+struct FailingNativeResponseProvider {
+    calls: Arc<AtomicUsize>,
+}
+
+#[async_trait]
+impl Provider for FailingNativeResponseProvider {
+    fn name(&self) -> &'static str {
+        "xai"
+    }
+
+    fn catalog_generation(&self) -> ProviderCatalogGeneration {
+        ProviderCatalogGeneration::default()
+    }
+
+    async fn query_model_capabilities(
+        &self,
+    ) -> Result<Vec<ProviderModelCapabilities>, ProviderError> {
+        Ok(Vec::new())
+    }
+
+    async fn execute(
+        self: Arc<Self>,
+        request: ProviderRequest,
+        _: AttemptContext,
+    ) -> Result<ProviderStream, ProviderError> {
+        self.calls.fetch_add(1, Ordering::SeqCst);
+        let candidate = request.candidate();
+        let response = ResponseMeta::new("response-native-failure", "gpt-start");
+        let event = |event_type: &str, fact| {
+            ProviderEvent::canonical_with_wire(
+                vec![fact],
+                ProtocolWireEvent::json(
+                    "xai",
+                    Some(event_type.to_owned()),
+                    json!({"type": event_type}),
+                )
+                .unwrap(),
+            )
+        };
+        let metadata = ProviderCallMetadata::new(
+            candidate.provider().clone(),
+            candidate.upstream_model().unwrap().clone(),
+            ProviderAccountId::new("acct_xai").unwrap(),
+            UpstreamTransport::new("websocket").unwrap(),
+        );
+        Ok(ProviderStream::new(
+            metadata,
+            futures::stream::iter([
+                Ok(event(
+                    "response.created",
+                    GatewayEvent::Started(response.clone()),
+                )),
+                Ok(event(
+                    "response.completed",
+                    GatewayEvent::Completed(response),
+                )),
+            ]),
+            (),
+        )
+        .with_native_response_translator(FailingNativeResponseTranslator::default()))
+    }
+}
+
+#[test]
+fn native_response_failure_after_downstream_commit_is_not_replayed() {
+    block_on(async {
+        let calls = Arc::new(AtomicUsize::new(0));
+        let provider_index = ProviderExtensionIndex::new(
+            ProviderRegistry::new([Arc::new(FailingNativeResponseProvider {
+                calls: Arc::clone(&calls),
+            }) as Arc<dyn Provider>])
+            .unwrap(),
+        );
+        let generation =
+            super::extensions::register(&provider_index, "native-response-failure", vec![]);
+        let service = DefaultExecutionService::new(
+            RuntimeSnapshotHandle::new(request_policy_snapshot(
+                generation,
+                &[ProviderKind::new("xai").unwrap()],
+            )),
+            Arc::new(TrackingExecutionStore::default()),
+            provider_index.registry(),
+            Arc::new(Admissions::default()),
+            Arc::new(UnusedCircuits),
+            Arc::new(UnusedContinuation),
+            Arc::new(RecordingClientApiKeyUsage::default()),
+        );
+
+        let mut started = service
+            .start(request(&service, ClientTransport::HttpSse))
+            .await
+            .unwrap();
+        let first = started.session.next_event().await.unwrap().unwrap();
+        assert_eq!(
+            first.commit_requirement(),
+            CommitRequirement::CommitBeforeDelivery
+        );
+        assert!(first.into_provider_events().iter().all(|event| {
+            event
+                .wire_event()
+                .is_some_and(|wire| wire.protocol() == "openai")
+        }));
+        started.session.commit_downstream(Some(200)).await.unwrap();
+
+        let error = started.session.next_event().await.unwrap_err();
+        assert!(matches!(
+            error,
+            EngineError::Provider(ref error)
+                if error.kind() == ProviderErrorKind::Protocol
+                    && error.send_state() == UpstreamSendState::Sent
+        ));
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+        started.session.detach_finalize().await;
+    });
+}
+
+#[test]
+fn model_routing_policy_selects_native_and_generation_plugin_providers() {
+    block_on(async {
+        for target in ["xai", "plugin-example"] {
+            let openai = Arc::new(ObservationProvider {
+                name: "openai",
+                behavior: ObservationProviderBehavior::CompleteWithUsage,
+                calls: AtomicUsize::new(0),
+            });
+            let selected = Arc::new(ObservationProvider {
+                name: target,
+                behavior: ObservationProviderBehavior::CompleteWithUsage,
+                calls: AtomicUsize::new(0),
+            });
+            let (base, extensions) = if target == "xai" {
+                (
+                    vec![
+                        openai.clone() as Arc<dyn Provider>,
+                        selected.clone() as Arc<dyn Provider>,
+                    ],
+                    Vec::new(),
+                )
+            } else {
+                (
+                    vec![openai.clone() as Arc<dyn Provider>],
+                    vec![selected.clone() as Arc<dyn Provider>],
+                )
+            };
+            let provider_index = ProviderExtensionIndex::new(ProviderRegistry::new(base).unwrap());
+            let generation = super::extensions::register(
+                &provider_index,
+                &format!("route-{target}"),
+                extensions,
+            );
+            let policy_index = RequestPolicyExtensionIndex::default();
+            let policy = Arc::new(FixedRoutingPolicy {
+                decision: ModelRouteDecision::Route {
+                    provider: Some(ProviderKind::new(target).unwrap()),
+                    model: None,
+                },
+                inputs: Mutex::new(Vec::new()),
+            });
+            let _owner = policy_index
+                .register(generation.id().clone(), policy.clone())
+                .unwrap();
+            let providers = [
+                ProviderKind::new("openai").unwrap(),
+                ProviderKind::new(target).unwrap(),
+            ];
+            let service = DefaultExecutionService::new(
+                RuntimeSnapshotHandle::new(request_policy_snapshot(generation, &providers)),
+                Arc::new(TrackingExecutionStore::default()),
+                provider_index.registry(),
+                Arc::new(Admissions::default()),
+                Arc::new(UnusedCircuits),
+                Arc::new(UnusedContinuation),
+                Arc::new(RecordingClientApiKeyUsage::default()),
+            )
+            .with_request_policies(policy_index);
+            let mut started = service
+                .start(request(&service, ClientTransport::HttpJson))
+                .await
+                .unwrap();
+            started.session.collect_uncommitted().await.unwrap();
+            started.session.detach_finalize().await;
+            assert_eq!(openai.calls.load(Ordering::SeqCst), 0);
+            assert_eq!(selected.calls.load(Ordering::SeqCst), 1);
+            let inputs = policy.inputs.lock().unwrap();
+            assert_eq!(inputs.len(), 1);
+            assert_eq!(inputs[0].client_key_id().as_str(), "key_start_test");
+            assert_eq!(
+                inputs[0]
+                    .available_providers()
+                    .iter()
+                    .map(ProviderKind::as_str)
+                    .collect::<BTreeSet<_>>(),
+                BTreeSet::from(["openai", target])
+            );
+        }
+    });
+}
+
+#[test]
+fn model_routing_reject_stops_before_provider_execution() {
+    block_on(async {
+        let provider = Arc::new(ObservationProvider {
+            name: "openai",
+            behavior: ObservationProviderBehavior::CompleteWithUsage,
+            calls: AtomicUsize::new(0),
+        });
+        let provider_index = ProviderExtensionIndex::new(
+            ProviderRegistry::new([provider.clone() as Arc<dyn Provider>]).unwrap(),
+        );
+        let generation = super::extensions::register(&provider_index, "route-reject", vec![]);
+        let policy_index = RequestPolicyExtensionIndex::default();
+        let policy: Arc<dyn RequestPolicyPlan> = Arc::new(FixedRoutingPolicy {
+            decision: ModelRouteDecision::Reject,
+            inputs: Mutex::new(Vec::new()),
+        });
+        let _owner = policy_index
+            .register(generation.id().clone(), policy)
+            .unwrap();
+        let service = DefaultExecutionService::new(
+            RuntimeSnapshotHandle::new(request_policy_snapshot(
+                generation,
+                &[ProviderKind::new("openai").unwrap()],
+            )),
+            Arc::new(TrackingExecutionStore::default()),
+            provider_index.registry(),
+            Arc::new(Admissions::default()),
+            Arc::new(UnusedCircuits),
+            Arc::new(UnusedContinuation),
+            Arc::new(RecordingClientApiKeyUsage::default()),
+        )
+        .with_request_policies(policy_index);
+        assert!(matches!(
+            service.start(request(&service, ClientTransport::HttpJson)).await,
+            Err(error) if error.kind() == GatewayErrorKind::PolicyDenied
+        ));
+        assert_eq!(provider.calls.load(Ordering::SeqCst), 0);
+    });
+}
+
+#[test]
+fn model_routing_cannot_expand_the_frozen_key_model_scope() {
+    block_on(async {
+        let kind = ProviderKind::new("openai").unwrap();
+        let provider = Arc::new(ObservationProvider {
+            name: "openai",
+            behavior: ObservationProviderBehavior::CompleteWithUsage,
+            calls: AtomicUsize::new(0),
+        });
+        let provider_index = ProviderExtensionIndex::new(
+            ProviderRegistry::new([provider.clone() as Arc<dyn Provider>]).unwrap(),
+        );
+        let generation = super::extensions::register(&provider_index, "route-model-scope", vec![]);
+        let policy_index = RequestPolicyExtensionIndex::default();
+        let policy: Arc<dyn RequestPolicyPlan> = Arc::new(FixedRoutingPolicy {
+            decision: ModelRouteDecision::Route {
+                provider: None,
+                model: Some(PublicModelId::new("gpt-blocked").unwrap()),
+            },
+            inputs: Mutex::new(Vec::new()),
+        });
+        let _owner = policy_index
+            .register(generation.id().clone(), policy)
+            .unwrap();
+        let directory = Arc::new(RuntimeAccountDirectory::new(BTreeMap::from([(
+            ProviderAccountId::new("acct_openai").unwrap(),
+            RuntimeAccount::new(kind.clone(), BTreeSet::new()).with_model_access(
+                AccountModelAccess::new(
+                    AccountModelAccessMode::Allowlist,
+                    vec!["gpt-start".to_owned()],
+                )
+                .unwrap(),
+            ),
+        )])));
+        let capabilities =
+            ModelCapabilities::new(BTreeSet::from([OperationKind::Generate]), Some(16_000));
+        let snapshot = RuntimeSnapshot::new(
+            ConfigRevision::new(1).unwrap(),
+            AccountSelectionPolicy::new(
+                RotationStrategy::Smart,
+                std::num::NonZeroU32::new(2).unwrap(),
+                Duration::from_millis(1),
+            ),
+            vec![kind.clone()],
+            ["gpt-start", "gpt-blocked"]
+                .into_iter()
+                .map(|model| {
+                    ProviderModel::new(
+                        kind.clone(),
+                        UpstreamModelId::new(model).unwrap(),
+                        capabilities.clone(),
+                    )
+                })
+                .collect(),
+            vec![ClientPolicy::new(
+                ClientApiKeyId::new("key_start_test").unwrap(),
+                PlaintextClientApiKey::new("sk_start_test").unwrap(),
+                Arc::new(FrozenAccountScope::new(
+                    Arc::clone(&directory),
+                    ClientRoutingScope::all_accounts(),
+                )),
+                true,
+                RateLimits::unlimited(),
+            )],
+        )
+        .unwrap()
+        .with_account_directory(directory)
+        .with_extensions(Some(generation));
+        let service = DefaultExecutionService::new(
+            RuntimeSnapshotHandle::new(snapshot),
+            Arc::new(TrackingExecutionStore::default()),
+            provider_index.registry(),
+            Arc::new(Admissions::default()),
+            Arc::new(UnusedCircuits),
+            Arc::new(UnusedContinuation),
+            Arc::new(RecordingClientApiKeyUsage::default()),
+        )
+        .with_request_policies(policy_index);
+
+        assert!(matches!(
+            service.start(request(&service, ClientTransport::HttpJson)).await,
+            Err(error) if error.kind() == GatewayErrorKind::NoAvailableProvider
+        ));
+        assert_eq!(provider.calls.load(Ordering::SeqCst), 0);
+    });
+}
+
+#[derive(Debug, Default)]
+struct RejectingSchedulerPolicy {
+    inputs: Mutex<Vec<AccountScheduleInput>>,
+}
+
+impl RequestPolicyPlan for RejectingSchedulerPolicy {
+    fn route_model(
+        &self,
+        _: ModelRouteInput,
+    ) -> BoxFuture<'static, Result<ModelRouteDecision, RequestPolicyFault>> {
+        Box::pin(async { Ok(ModelRouteDecision::Unhandled) })
+    }
+
+    fn schedule_account(
+        &self,
+        input: AccountScheduleInput,
+    ) -> BoxFuture<'static, Result<AccountScheduleDecision, RequestPolicyFault>> {
+        self.inputs.lock().unwrap().push(input);
+        Box::pin(async { Ok(AccountScheduleDecision::Reject) })
+    }
+}
+
+struct PolicySelectingProvider;
+
+#[async_trait]
+impl Provider for PolicySelectingProvider {
+    fn name(&self) -> &'static str {
+        "openai"
+    }
+
+    fn catalog_generation(&self) -> ProviderCatalogGeneration {
+        ProviderCatalogGeneration::default()
+    }
+
+    async fn query_model_capabilities(
+        &self,
+    ) -> Result<Vec<ProviderModelCapabilities>, ProviderError> {
+        Ok(Vec::new())
+    }
+
+    async fn execute(
+        self: Arc<Self>,
+        request: ProviderRequest,
+        attempt: AttemptContext,
+    ) -> Result<ProviderStream, ProviderError> {
+        let account = ProviderAccount::new(
+            ProviderAccountId::new("acct_openai").unwrap(),
+            ProviderKind::new("openai").unwrap(),
+            "scheduler test".to_owned(),
+            None,
+            "test".to_owned(),
+            CredentialRevision::new(1).unwrap(),
+            None,
+        )
+        .with_account_facts(
+            true,
+            CredentialState::Ready,
+            QuotaState::unknown(),
+            None,
+            None,
+        )
+        .with_scheduling(None, AccountWeight::new(100).unwrap());
+        let candidates = [AccountCandidate {
+            account,
+            signals: AccountRuntimeSignals {
+                in_flight: 0,
+                last_started_at: None,
+                quota_reset_at: None,
+                quota_remaining_rank: None,
+                cooldown: None,
+                failure_rate_basis_points: None,
+                first_output_latency_ms: None,
+            },
+        }];
+        let selection = AccountSelectionContext {
+            policy: attempt.account_selection_policy(),
+            now: SystemTime::now(),
+            excluded_accounts: attempt.excluded_accounts().clone(),
+            preferred_account: attempt.required_account().cloned(),
+            preferred_account_overrides_weight: true,
+            round_robin_cursor: 0,
+            eligibility: AccountEligibilityPolicy::Enforce,
+            account_scope: attempt.account_scope().cloned(),
+        };
+        match attempt
+            .select_account(
+                request.candidate().provider(),
+                request
+                    .candidate()
+                    .upstream_model()
+                    .map(UpstreamModelId::as_str),
+                &candidates,
+                &selection,
+            )
+            .await
+        {
+            Err(AccountPolicyError::Rejected) => Err(ProviderError::new(
+                ProviderErrorKind::RequestPolicyDenied,
+                UpstreamSendState::NotSent,
+            )),
+            Err(AccountPolicyError::Fault | AccountPolicyError::StaleCandidate) => Err(
+                ProviderError::new(ProviderErrorKind::Unavailable, UpstreamSendState::NotSent),
+            ),
+            Ok(_) => panic!("rejecting scheduler unexpectedly selected an account"),
+        }
+    }
+}
+
+#[test]
+fn scheduler_reject_is_a_terminal_policy_rejection_before_upstream_send() {
+    block_on(async {
+        let provider_index = ProviderExtensionIndex::new(
+            ProviderRegistry::new([Arc::new(PolicySelectingProvider) as Arc<dyn Provider>])
+                .unwrap(),
+        );
+        let generation = super::extensions::register(&provider_index, "schedule-reject", vec![]);
+        let policy_index = RequestPolicyExtensionIndex::default();
+        let policy = Arc::new(RejectingSchedulerPolicy::default());
+        let _policy_owner = policy_index
+            .register(generation.id().clone(), policy.clone())
+            .unwrap();
+        let observer_index = RequestObserverExtensionIndex::default();
+        let observer = Arc::new(RecordingRequestObserver::default());
+        let _observer_owner = observer_index
+            .register(generation.id().clone(), observer.clone())
+            .unwrap();
+        let service = DefaultExecutionService::new(
+            RuntimeSnapshotHandle::new(request_policy_snapshot(
+                generation,
+                &[ProviderKind::new("openai").unwrap()],
+            )),
+            Arc::new(TrackingExecutionStore::default()),
+            provider_index.registry(),
+            Arc::new(Admissions::default()),
+            Arc::new(UnusedCircuits),
+            Arc::new(UnusedContinuation),
+            Arc::new(RecordingClientApiKeyUsage::default()),
+        )
+        .with_request_policies(policy_index)
+        .with_request_observers(observer_index);
+        let mut started = service
+            .start(request(&service, ClientTransport::HttpJson))
+            .await
+            .unwrap();
+        let error = started.session.collect_uncommitted().await.unwrap_err();
+        let provider_error = match error {
+            EngineError::Provider(error) => error,
+            error => panic!("unexpected engine error: {error:?}"),
+        };
+        assert_eq!(
+            provider_error.kind(),
+            ProviderErrorKind::RequestPolicyDenied
+        );
+        assert_eq!(provider_error.send_state(), UpstreamSendState::NotSent);
+        assert_eq!(
+            GatewayError::from_provider(&provider_error).kind(),
+            GatewayErrorKind::PolicyDenied
+        );
+        started.session.detach_finalize().await;
+        let observations = observer.observations.lock().unwrap();
+        assert_eq!(observations.len(), 1);
+        assert_eq!(
+            observations[0].outcome(),
+            RequestObservationOutcome::Rejected
+        );
+        assert_eq!(observations[0].send_state(), UpstreamSendState::NotSent);
+        assert_eq!(
+            observations[0].attempt_count(),
+            0,
+            "调度拒绝发生在 ProviderStream/上游 attempt 持久化前"
+        );
+        assert_eq!(policy.inputs.lock().unwrap().len(), 1);
+    });
+}
+
 fn known_charge() -> Decimal {
     "1.25".parse().unwrap()
 }
 
+#[derive(Clone, Copy)]
+enum ObservationProviderBehavior {
+    CompleteWithUsage,
+    RetryableFailure,
+    CapacityFailure,
+}
+
+struct ObservationProvider {
+    name: &'static str,
+    behavior: ObservationProviderBehavior,
+    calls: AtomicUsize,
+}
+
+#[async_trait]
+impl Provider for ObservationProvider {
+    fn name(&self) -> &'static str {
+        self.name
+    }
+
+    fn catalog_generation(&self) -> ProviderCatalogGeneration {
+        ProviderCatalogGeneration::default()
+    }
+
+    async fn query_model_capabilities(
+        &self,
+    ) -> Result<Vec<ProviderModelCapabilities>, ProviderError> {
+        Ok(Vec::new())
+    }
+
+    async fn execute(
+        self: Arc<Self>,
+        request: ProviderRequest,
+        _: AttemptContext,
+    ) -> Result<ProviderStream, ProviderError> {
+        let call_index = self.calls.fetch_add(1, Ordering::SeqCst);
+        match self.behavior {
+            ObservationProviderBehavior::CompleteWithUsage => {
+                let candidate = request.candidate();
+                let metadata = ProviderCallMetadata::new(
+                    candidate.provider().clone(),
+                    candidate.upstream_model().unwrap().clone(),
+                    ProviderAccountId::new(format!("acct_{}", self.name)).unwrap(),
+                    UpstreamTransport::new("http_sse").unwrap(),
+                );
+                let response = ResponseMeta::new("response-observed", "gpt-start");
+                let mut started: ProviderEvent = GatewayEvent::Started(response.clone()).into();
+                started.attach_observation(
+                    gateway_core::event::ProviderResponseObservation::new(
+                        UpstreamTransport::new("http_sse").unwrap(),
+                    )
+                    .with_upstream_response_model_if_valid("gpt-reported")
+                    .with_service_tier_if_valid("priority"),
+                );
+                Ok(ProviderStream::new(
+                    metadata,
+                    futures::stream::iter([
+                        Ok(started),
+                        Ok(GatewayEvent::Usage(Usage {
+                            input_tokens: Some(11),
+                            output_tokens: Some(7),
+                            total_tokens: Some(18),
+                            ..Usage::default()
+                        })
+                        .into()),
+                        Ok(GatewayEvent::ProviderCost(
+                            ProviderReportedCost::from_usd_ticks(123_000_000).unwrap(),
+                        )
+                        .into()),
+                        Ok(GatewayEvent::Completed(response).into()),
+                    ]),
+                    (),
+                ))
+            }
+            ObservationProviderBehavior::CapacityFailure => Err(ProviderError::new(
+                ProviderErrorKind::NoEligibleAccount,
+                UpstreamSendState::NotSent,
+            )),
+            ObservationProviderBehavior::RetryableFailure => {
+                if call_index > 0 {
+                    return Err(ProviderError::new(
+                        ProviderErrorKind::NoEligibleAccount,
+                        UpstreamSendState::NotSent,
+                    ));
+                }
+                let candidate = request.candidate();
+                let metadata = ProviderCallMetadata::new(
+                    candidate.provider().clone(),
+                    candidate.upstream_model().unwrap().clone(),
+                    ProviderAccountId::new(format!("acct_{}", self.name)).unwrap(),
+                    UpstreamTransport::new("http_sse").unwrap(),
+                );
+                let error =
+                    ProviderError::new(ProviderErrorKind::Transport, UpstreamSendState::NotSent)
+                        .with_status(503)
+                        .with_retry_after(Duration::from_millis(750))
+                        .with_pre_delivery_retry();
+                Ok(ProviderStream::new(
+                    metadata,
+                    futures::stream::iter([Err(error)]),
+                    (),
+                ))
+            }
+        }
+    }
+}
+
+#[derive(Default)]
+struct RecordingRequestObserver {
+    observations: Mutex<Vec<RequestObservation>>,
+    websocket_observations: Mutex<Vec<WebSocketResponseObservation>>,
+}
+
+impl RequestObserverPlan for RecordingRequestObserver {
+    fn dispatch_websocket_response(
+        &self,
+        generation: ExtensionSetReference,
+        observation: WebSocketResponseObservation,
+    ) {
+        assert!(generation.is_ready());
+        self.websocket_observations
+            .lock()
+            .unwrap()
+            .push(observation);
+    }
+
+    fn dispatch(&self, generation: ExtensionSetReference, observation: RequestObservation) {
+        assert!(generation.is_ready());
+        self.observations.lock().unwrap().push(observation);
+    }
+}
+
+fn fallback_observation_snapshot(reference: ExtensionSetReference) -> RuntimeSnapshot {
+    let providers = [
+        ProviderKind::new("openai").unwrap(),
+        ProviderKind::new("xai").unwrap(),
+    ];
+    let enabled_group = AccountGroupId::new("grp_11111111111111111111111111111111").unwrap();
+    let disabled_group = AccountGroupId::new("grp_22222222222222222222222222222222").unwrap();
+    let directory = Arc::new(RuntimeAccountDirectory::new(
+        providers
+            .iter()
+            .map(|provider| {
+                (
+                    ProviderAccountId::new(format!("acct_{}", provider.as_str())).unwrap(),
+                    RuntimeAccount::new(provider.clone(), BTreeSet::from([enabled_group.clone()])),
+                )
+            })
+            .collect(),
+    ));
+    let capabilities =
+        ModelCapabilities::new(BTreeSet::from([OperationKind::Generate]), Some(16_000));
+    RuntimeSnapshot::new(
+        ConfigRevision::new(1).unwrap(),
+        AccountSelectionPolicy::new(
+            RotationStrategy::Smart,
+            std::num::NonZeroU32::new(2).unwrap(),
+            Duration::from_millis(1),
+        ),
+        providers.to_vec(),
+        providers
+            .iter()
+            .map(|provider| {
+                ProviderModel::new(
+                    provider.clone(),
+                    UpstreamModelId::new("gpt-start").unwrap(),
+                    capabilities.clone(),
+                )
+            })
+            .collect(),
+        vec![ClientPolicy::new(
+            ClientApiKeyId::new("key_start_test").unwrap(),
+            PlaintextClientApiKey::new("sk_start_test").unwrap(),
+            Arc::new(FrozenAccountScope::new(
+                Arc::clone(&directory),
+                ClientRoutingScope::restricted(
+                    vec![
+                        RoutingGroupSnapshot::new(enabled_group.clone(), "Enabled".to_owned()),
+                        RoutingGroupSnapshot::new(disabled_group, "Disabled".to_owned()),
+                    ],
+                    BTreeSet::from([enabled_group]),
+                    BTreeSet::from(providers),
+                )
+                .unwrap(),
+            )),
+            true,
+            RateLimits::unlimited(),
+        )],
+    )
+    .unwrap()
+    .with_account_directory(directory)
+    .with_extensions(Some(reference))
+}
+
+fn observation_service(
+    behavior: ObservationProviderBehavior,
+    reject_budget: bool,
+) -> (
+    DefaultExecutionService,
+    Arc<RecordingRequestObserver>,
+    Arc<dyn RequestObserverPlan>,
+) {
+    let openai = Arc::new(ObservationProvider {
+        name: "openai",
+        behavior,
+        calls: AtomicUsize::new(0),
+    });
+    let xai = Arc::new(ObservationProvider {
+        name: "xai",
+        behavior: ObservationProviderBehavior::CapacityFailure,
+        calls: AtomicUsize::new(0),
+    });
+    let provider_extensions = ProviderExtensionIndex::new(
+        ProviderRegistry::new([openai as Arc<dyn Provider>, xai as Arc<dyn Provider>]).unwrap(),
+    );
+    let generation = super::extensions::register(&provider_extensions, "observer-terminal", vec![]);
+    let observer_index = RequestObserverExtensionIndex::default();
+    let observer = Arc::new(RecordingRequestObserver::default());
+    let owner = observer_index
+        .register(generation.id().clone(), observer.clone())
+        .unwrap();
+    let admissions = Arc::new(Admissions::default());
+    let budget = Arc::new(Budget {
+        reject: reject_budget,
+        active: admissions.active.clone(),
+        ..Budget::default()
+    });
+    let service = DefaultExecutionService::new(
+        RuntimeSnapshotHandle::new(fallback_observation_snapshot(generation)),
+        Arc::new(TrackingExecutionStore::default()),
+        provider_extensions.registry(),
+        admissions,
+        Arc::new(UnusedCircuits),
+        Arc::new(UnusedContinuation),
+        Arc::new(RecordingClientApiKeyUsage::default()),
+    )
+    .with_budget(budget)
+    .with_request_observers(observer_index);
+    (service, observer, owner)
+}
+
+#[test]
+fn fallback_exhaustion_observation_uses_the_last_actual_provider_not_the_candidate_cursor() {
+    block_on(async {
+        let openai = Arc::new(ObservationProvider {
+            name: "openai",
+            behavior: ObservationProviderBehavior::RetryableFailure,
+            calls: AtomicUsize::new(0),
+        });
+        let xai = Arc::new(ObservationProvider {
+            name: "xai",
+            behavior: ObservationProviderBehavior::CapacityFailure,
+            calls: AtomicUsize::new(0),
+        });
+        let provider_extensions = ProviderExtensionIndex::new(
+            ProviderRegistry::new([
+                openai.clone() as Arc<dyn Provider>,
+                xai.clone() as Arc<dyn Provider>,
+            ])
+            .unwrap(),
+        );
+        let generation =
+            super::extensions::register(&provider_extensions, "observer-fallback", vec![]);
+        let observer_index = RequestObserverExtensionIndex::default();
+        let observer = Arc::new(RecordingRequestObserver::default());
+        let _observer_owner = observer_index
+            .register(generation.id().clone(), observer.clone())
+            .unwrap();
+        let service = DefaultExecutionService::new(
+            RuntimeSnapshotHandle::new(fallback_observation_snapshot(generation)),
+            Arc::new(TrackingExecutionStore::default()),
+            provider_extensions.registry(),
+            Arc::new(Admissions::default()),
+            Arc::new(UnusedCircuits),
+            Arc::new(UnusedContinuation),
+            Arc::new(RecordingClientApiKeyUsage::default()),
+        )
+        .with_request_observers(observer_index);
+        let mut started = service
+            .start(request(&service, ClientTransport::HttpJson))
+            .await
+            .unwrap();
+        assert!(matches!(
+            started.session.collect_uncommitted().await,
+            Err(EngineError::Provider(error))
+                if error.kind() == ProviderErrorKind::Transport
+        ));
+        started.session.detach_finalize().await;
+
+        assert_eq!(openai.calls.load(Ordering::SeqCst), 2);
+        assert_eq!(xai.calls.load(Ordering::SeqCst), 1);
+        let observations = observer.observations.lock().unwrap();
+        assert_eq!(observations.len(), 1);
+        assert_eq!(
+            observations[0].provider().map(ProviderKind::as_str),
+            Some("openai"),
+            "第二候选的容量拒绝不能覆盖最后一次真实 attempt 的 Provider"
+        );
+        assert_eq!(observations[0].outcome(), RequestObservationOutcome::Failed);
+        assert_eq!(observations[0].upstream_status_code(), Some(503));
+        assert_eq!(observations[0].retry_after_ms(), Some(750));
+        assert_observation_scope(&observations[0]);
+    });
+}
+
+#[test]
+fn routing_external_effect_stops_a_not_sent_provider_retry() {
+    block_on(async {
+        let openai = Arc::new(ObservationProvider {
+            name: "openai",
+            behavior: ObservationProviderBehavior::RetryableFailure,
+            calls: AtomicUsize::new(0),
+        });
+        let xai = Arc::new(ObservationProvider {
+            name: "xai",
+            behavior: ObservationProviderBehavior::CompleteWithUsage,
+            calls: AtomicUsize::new(0),
+        });
+        let provider_extensions = ProviderExtensionIndex::new(
+            ProviderRegistry::new([
+                openai.clone() as Arc<dyn Provider>,
+                xai.clone() as Arc<dyn Provider>,
+            ])
+            .unwrap(),
+        );
+        let generation =
+            super::extensions::register(&provider_extensions, "routing-effect", vec![]);
+        let policy_index = RequestPolicyExtensionIndex::default();
+        let _policy_owner = policy_index
+            .register(generation.id().clone(), Arc::new(EffectObservingPolicy))
+            .unwrap();
+        let observer_index = RequestObserverExtensionIndex::default();
+        let observer = Arc::new(RecordingRequestObserver::default());
+        let _observer_owner = observer_index
+            .register(generation.id().clone(), observer.clone())
+            .unwrap();
+        let service = DefaultExecutionService::new(
+            RuntimeSnapshotHandle::new(fallback_observation_snapshot(generation)),
+            Arc::new(TrackingExecutionStore::default()),
+            provider_extensions.registry(),
+            Arc::new(Admissions::default()),
+            Arc::new(UnusedCircuits),
+            Arc::new(UnusedContinuation),
+            Arc::new(RecordingClientApiKeyUsage::default()),
+        )
+        .with_request_policies(policy_index)
+        .with_request_observers(observer_index);
+        let mut started = service
+            .start(request(&service, ClientTransport::HttpJson))
+            .await
+            .unwrap();
+        assert!(matches!(
+            started.session.collect_uncommitted().await,
+            Err(EngineError::Provider(error))
+                if error.kind() == ProviderErrorKind::Transport
+        ));
+        started.session.detach_finalize().await;
+
+        assert_eq!(openai.calls.load(Ordering::SeqCst), 1);
+        assert_eq!(xai.calls.load(Ordering::SeqCst), 0);
+        let observations = observer.observations.lock().unwrap();
+        assert_eq!(observations.len(), 1);
+        assert_eq!(observations[0].send_state(), UpstreamSendState::Ambiguous);
+        assert_eq!(observations[0].attempt_count(), 1);
+    });
+}
+
+#[test]
+fn final_observation_is_emitted_once_for_success_rejection_and_detached_cancellation() {
+    block_on(async {
+        let (service, observer, _owner) =
+            observation_service(ObservationProviderBehavior::CompleteWithUsage, false);
+        let mut started = service
+            .start(request(&service, ClientTransport::HttpJson))
+            .await
+            .unwrap();
+        assert_eq!(
+            started.session.collect_uncommitted().await.unwrap().len(),
+            4
+        );
+        started.session.commit_downstream(Some(200)).await.unwrap();
+        started.session.detach_finalize().await;
+        {
+            let observations = observer.observations.lock().unwrap();
+            assert_eq!(observations.len(), 1);
+            assert_eq!(
+                observations[0].account_id().map(ProviderAccountId::as_str),
+                Some("acct_openai")
+            );
+            assert_eq!(
+                observations[0]
+                    .upstream_model()
+                    .map(UpstreamModelId::as_str),
+                Some("gpt-start")
+            );
+            assert_eq!(observations[0].response_model(), Some("gpt-reported"));
+            assert_eq!(observations[0].service_tier(), Some("priority"));
+            assert_eq!(
+                observations[0].outcome(),
+                RequestObservationOutcome::Succeeded
+            );
+            assert_eq!(observations[0].usage().total_tokens, Some(18));
+            assert_eq!(observations[0].attempt_count(), 1);
+            assert_eq!(observations[0].cost().status(), CostEstimateStatus::Known);
+            assert_eq!(
+                observations[0].cost().source(),
+                CostSource::ProviderReported
+            );
+            assert_eq!(
+                observations[0]
+                    .cost()
+                    .total()
+                    .map(|money| money.amount().canonical()),
+                Some("0.0123".to_owned())
+            );
+            assert!(observations[0].timings().latency_ms.is_some());
+            assert_observation_scope(&observations[0]);
+        }
+
+        let (service, observer, _owner) =
+            observation_service(ObservationProviderBehavior::CompleteWithUsage, true);
+        assert!(matches!(
+            service.start(request(&service, ClientTransport::HttpJson)).await,
+            Err(error) if error.kind() == GatewayErrorKind::RateLimited
+        ));
+        {
+            let observations = observer.observations.lock().unwrap();
+            assert_eq!(observations.len(), 1);
+            assert_eq!(
+                observations[0].outcome(),
+                RequestObservationOutcome::Rejected
+            );
+            assert!(observations[0].provider().is_none());
+            assert_eq!(observations[0].attempt_count(), 0);
+            assert_observation_scope(&observations[0]);
+        }
+
+        let (service, observer, _owner) =
+            observation_service(ObservationProviderBehavior::CompleteWithUsage, false);
+        let started = service
+            .start(request(&service, ClientTransport::HttpJson))
+            .await
+            .unwrap();
+        started.session.detach_finalize().await;
+        let observations = observer.observations.lock().unwrap();
+        assert_eq!(observations.len(), 1);
+        assert_eq!(
+            observations[0].outcome(),
+            RequestObservationOutcome::Cancelled
+        );
+        assert!(observations[0].provider().is_none());
+        assert_eq!(observations[0].attempt_count(), 0);
+        assert_observation_scope(&observations[0]);
+    });
+}
+
+fn assert_observation_scope(observation: &RequestObservation) {
+    assert_eq!(
+        observation.client_key_id().map(ClientApiKeyId::as_str),
+        Some("key_start_test")
+    );
+    assert_eq!(
+        observation
+            .account_group_ids()
+            .iter()
+            .map(AccountGroupId::as_str)
+            .collect::<Vec<_>>(),
+        vec![
+            "grp_11111111111111111111111111111111",
+            "grp_22222222222222222222222222222222",
+        ],
+        "冻结观察范围必须保留禁用但已绑定的账号组"
+    );
+}
+
 #[async_trait]
 impl Provider for ChargedProvider {
     fn name(&self) -> &'static str {
@@ -511,7 +2435,7 @@ impl Provider for ChargedProvider {
     }
 
     async fn execute(
-        &self,
+        self: Arc<Self>,
         request: ProviderRequest,
         context: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
@@ -821,11 +2745,20 @@ fn settlement_failure_keeps_provider_error_and_releases_concurrency_once() {
 use async_trait::async_trait;
 use bytes::Bytes;
 use futures::{channel::oneshot, executor::block_on, future::BoxFuture};
-use gateway_core::account::{AccountSelectionPolicy, ProviderAccountId, RotationStrategy};
+use gateway_core::account::{
+    AccountCandidate, AccountEligibilityPolicy, AccountModelAccess, AccountModelAccessMode,
+    AccountRuntimeSignals, AccountSelectionContext, AccountSelectionPolicy, AccountWeight,
+    CredentialRevision, CredentialState, ProviderAccount, ProviderAccountId, QuotaState,
+    RotationStrategy,
+};
 use gateway_core::engine::admission::{
     ClientAdmissionDecision, ClientAdmissionError, ClientAdmissionPort, ClientAdmissionRecovery,
     ClientAdmissionRequest, ClientAdmissionRestoreResult,
 };
+use gateway_core::engine::authentication::{
+    ClientAuthenticationRequest, FrontendAuthenticationDecision, FrontendAuthenticationError,
+    FrontendAuthenticationExtensionIndex, FrontendAuthenticationPlan,
+};
 use gateway_core::engine::continuation::{
     NativeContinuationPin, NativeContinuationPort, NativeContinuationStoreError, PreviousResponseId,
 };
@@ -835,10 +2768,20 @@ use gateway_core::engine::execution::{
     ProviderCircuitError, ProviderCircuitPort, StartExecution, StartProviderExecution,
     provider_failure_affects_circuit,
 };
+use gateway_core::engine::extensions::ProviderExtensionIndex;
+use gateway_core::engine::nested::NestedModelExecutionRequest;
+use gateway_core::engine::observation::{
+    RequestObservation, RequestObservationOutcome, RequestObserverExtensionIndex,
+    RequestObserverPlan, WebSocketResponseObservation,
+};
+use gateway_core::engine::policy::{
+    AccountPolicyError, AccountScheduleDecision, AccountScheduleInput, ModelRouteDecision,
+    ModelRouteInput, RequestPolicyExtensionIndex, RequestPolicyFault, RequestPolicyPlan,
+};
 use gateway_core::engine::probe::{AccountProbe, AccountProbeErrorSource, AccountProbeRequest};
 use gateway_core::engine::provider::{
-    Provider, ProviderCallMetadata, ProviderRegistry, ProviderRequest, ProviderRequestObservation,
-    ProviderStream,
+    NativeResponseTranslator, Provider, ProviderCallMetadata, ProviderRegistry, ProviderRequest,
+    ProviderRequestObservation, ProviderStream,
 };
 use gateway_core::engine::{
     AttemptContext, AttemptRecord, CommitRequirement, EngineError, ExecutionOutcome,
@@ -849,21 +2792,27 @@ use gateway_core::error::{
     ClientVisibleUpstreamResponse, GatewayErrorKind, ProviderError, ProviderErrorKind, StoreError,
     StoreErrorKind,
 };
-use gateway_core::event::{GatewayEvent, ProviderEvent, ResponseMeta};
-use gateway_core::metering::{Decimal, ProviderReportedCost};
+use gateway_core::event::{GatewayEvent, ProtocolWireEvent, ProviderEvent, ResponseMeta};
+use gateway_core::metering::{
+    CostEstimateStatus, CostSource, Decimal, ProviderReportedCost, Usage,
+};
 use gateway_core::operation::{
     GenerateRequest, ImageRequest, ImageRequestKind, Operation, OperationKind, ProtocolPayload,
-    RawJsonPayload,
+    ProviderHttpMethod, ProviderHttpRequest, RawHttpPayload, RawJsonPayload, TokenCountRequest,
 };
 use gateway_core::policy::{ClientApiKeyId, ClientPolicy, PlaintextClientApiKey, RateLimits};
 use gateway_core::routing::{
-    ClientRoutingScope, ConfigRevision, FrozenAccountScope, ModelCapabilities,
+    AccountGroupId, ClientRoutingScope, ConfigRevision, FrozenAccountScope, ModelCapabilities,
     ProviderCatalogGeneration, ProviderKind, ProviderModel, ProviderModelCapabilities,
-    PublicModelId, RuntimeAccount, RuntimeAccountDirectory, RuntimeSnapshot, UpstreamModelId,
+    PublicModelId, RoutingGroupSnapshot, RuntimeAccount, RuntimeAccountDirectory, RuntimeSnapshot,
+    UpstreamModelId,
+};
+use gateway_core::runtime::{
+    RuntimeSnapshotHandle,
+    extensions::{ExtensionSetId, ExtensionSetLease, ExtensionSetReference},
 };
-use gateway_core::runtime::RuntimeSnapshotHandle;
 use gateway_core::upstream::{UpstreamSendState, UpstreamTransport};
-use serde_json::json;
+use serde_json::{Value, json};
 
 #[test]
 fn only_provider_attributable_failures_should_affect_circuit() {
@@ -898,12 +2847,15 @@ fn account_probe_should_not_write_to_the_persistent_execution_store() {
         Arc::new(RecordingClientApiKeyUsage::default()),
     );
 
-    let error = block_on(service.probe(AccountProbeRequest {
-        account_id: ProviderAccountId::new("acct_probe").expect("account ID"),
-        provider_kind: ProviderKind::new("openai").expect("provider kind"),
-        upstream_model: UpstreamModelId::new("gpt-probe").expect("model ID"),
-        operation: probe_operation(),
-    }))
+    let error = block_on(service.probe(
+        AccountProbeRequest {
+            account_id: ProviderAccountId::new("acct_probe").expect("account ID"),
+            provider_kind: ProviderKind::new("openai").expect("provider kind"),
+            upstream_model: UpstreamModelId::new("gpt-probe").expect("model ID"),
+            operation: probe_operation(),
+        },
+        None,
+    ))
     .expect_err("empty Provider registry should stop the probe after it starts");
 
     assert_eq!(error.kind(), GatewayErrorKind::NoAvailableProvider);
@@ -927,12 +2879,15 @@ fn probe_failures_should_be_observable_without_a_model_request_row() {
         Arc::new(RecordingClientApiKeyUsage::default()),
     );
 
-    let error = block_on(service.probe(AccountProbeRequest {
-        account_id: ProviderAccountId::new("acct_probe").expect("account ID"),
-        provider_kind: ProviderKind::new("openai").expect("provider kind"),
-        upstream_model: UpstreamModelId::new("gpt-probe").expect("model ID"),
-        operation: probe_operation(),
-    }))
+    let error = block_on(service.probe(
+        AccountProbeRequest {
+            account_id: ProviderAccountId::new("acct_probe").expect("account ID"),
+            provider_kind: ProviderKind::new("openai").expect("provider kind"),
+            upstream_model: UpstreamModelId::new("gpt-probe").expect("model ID"),
+            operation: probe_operation(),
+        },
+        None,
+    ))
     .expect_err("the provider rejects every probe");
 
     assert_eq!(error.kind(), GatewayErrorKind::UpstreamUnavailable);
@@ -970,12 +2925,15 @@ fn provider_local_probe_failure_should_remain_distinct_from_upstream() {
         Arc::new(RecordingClientApiKeyUsage::default()),
     );
 
-    let error = block_on(service.probe(AccountProbeRequest {
-        account_id: ProviderAccountId::new("acct_probe").expect("account ID"),
-        provider_kind: ProviderKind::new("openai").expect("provider kind"),
-        upstream_model: UpstreamModelId::new("gpt-probe").expect("model ID"),
-        operation: probe_operation(),
-    }))
+    let error = block_on(service.probe(
+        AccountProbeRequest {
+            account_id: ProviderAccountId::new("acct_probe").expect("account ID"),
+            provider_kind: ProviderKind::new("openai").expect("provider kind"),
+            upstream_model: UpstreamModelId::new("gpt-probe").expect("model ID"),
+            operation: probe_operation(),
+        },
+        None,
+    ))
     .expect_err("the Provider rejects the probe before sending it");
 
     assert_eq!(error.source(), AccountProbeErrorSource::Provider);
@@ -983,6 +2941,47 @@ fn provider_local_probe_failure_should_remain_distinct_from_upstream() {
     assert!(error.upstream_response().is_none());
 }
 
+#[test]
+fn diagnostic_probe_does_not_apply_data_plane_account_model_policy() {
+    let provider = ProviderKind::new("openai").expect("provider");
+    let account_id = ProviderAccountId::new("acct_probe").expect("account");
+    let snapshot = probe_snapshot().with_account_directory(Arc::new(RuntimeAccountDirectory::new(
+        BTreeMap::from([(
+            account_id.clone(),
+            RuntimeAccount::new(provider.clone(), BTreeSet::new()).with_model_access(
+                AccountModelAccess::new(
+                    AccountModelAccessMode::Denylist,
+                    vec!["gpt-probe".to_owned()],
+                )
+                .expect("model policy"),
+            ),
+        )]),
+    )));
+    let service = DefaultExecutionService::new(
+        RuntimeSnapshotHandle::new(snapshot),
+        Arc::new(TrackingExecutionStore::default()),
+        ProviderRegistry::new([Arc::new(LocalFailingProvider) as Arc<dyn Provider>])
+            .expect("providers"),
+        Arc::new(UnusedAdmissions),
+        Arc::new(UnusedCircuits),
+        Arc::new(UnusedContinuation),
+        Arc::new(RecordingClientApiKeyUsage::default()),
+    );
+
+    let error = block_on(service.probe(
+        AccountProbeRequest {
+            account_id,
+            provider_kind: provider,
+            upstream_model: UpstreamModelId::new("gpt-probe").expect("model"),
+            operation: probe_operation(),
+        },
+        None,
+    ))
+    .expect_err("the diagnostic reaches the selected Provider");
+
+    assert_eq!(error.source(), AccountProbeErrorSource::Provider);
+}
+
 #[test]
 fn probe_observation_store_failure_preserves_the_provider_error() {
     let store = Arc::new(TrackingExecutionStore {
@@ -1001,12 +3000,15 @@ fn probe_observation_store_failure_preserves_the_provider_error() {
         Arc::new(RecordingClientApiKeyUsage::default()),
     );
 
-    let error = block_on(service.probe(AccountProbeRequest {
-        account_id: ProviderAccountId::new("acct_probe").expect("account ID"),
-        provider_kind: ProviderKind::new("openai").expect("provider kind"),
-        upstream_model: UpstreamModelId::new("gpt-probe").expect("model ID"),
-        operation: probe_operation(),
-    }))
+    let error = block_on(service.probe(
+        AccountProbeRequest {
+            account_id: ProviderAccountId::new("acct_probe").expect("account ID"),
+            provider_kind: ProviderKind::new("openai").expect("provider kind"),
+            upstream_model: UpstreamModelId::new("gpt-probe").expect("model ID"),
+            operation: probe_operation(),
+        },
+        None,
+    ))
     .expect_err("the provider error must survive observation failure");
 
     assert_eq!(error.kind(), GatewayErrorKind::UpstreamUnavailable);
@@ -1067,7 +3069,7 @@ impl Provider for NativeCatalogProvider {
         ))
     }
     async fn execute(
-        &self,
+        self: Arc<Self>,
         _: ProviderRequest,
         _: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
@@ -1137,7 +3139,7 @@ impl Provider for FailingProvider {
     }
 
     async fn execute(
-        &self,
+        self: Arc<Self>,
         _request: ProviderRequest,
         _context: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
@@ -1171,7 +3173,7 @@ impl Provider for LocalFailingProvider {
     }
 
     async fn execute(
-        &self,
+        self: Arc<Self>,
         _: ProviderRequest,
         _: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
@@ -1210,7 +3212,7 @@ impl Provider for ColdFailingProvider {
     }
 
     async fn execute(
-        &self,
+        self: Arc<Self>,
         request: ProviderRequest,
         _: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
@@ -1273,6 +3275,33 @@ fn client_key_verification_should_not_record_client_key_usage() {
     assert!(usage.recorded().is_empty());
 }
 
+#[test]
+fn request_verification_should_apply_entry_authentication_without_recording_key_usage() {
+    block_on(async {
+        let usage = Arc::new(RecordingClientApiKeyUsage::default());
+        let service = DefaultExecutionService::new(
+            RuntimeSnapshotHandle::new(client_snapshot()),
+            Arc::new(TrackingExecutionStore::default()),
+            ProviderRegistry::default(),
+            Arc::new(UnusedAdmissions),
+            Arc::new(UnusedCircuits),
+            Arc::new(UnusedContinuation),
+            usage.clone(),
+        );
+
+        let client = service
+            .verify_request(
+                ClientAuthenticationRequest::bearer("sk_usage_test")
+                    .expect("client authentication request"),
+            )
+            .await
+            .expect("request verification");
+
+        assert_eq!(client.policy().key_id().as_str(), "key_usage_test");
+        assert!(usage.recorded().is_empty());
+    });
+}
+
 #[test]
 fn provider_endpoint_should_persist_its_real_v1_endpoint() {
     assert_provider_endpoint_observation(None);
@@ -1308,6 +3337,7 @@ fn assert_provider_endpoint_observation(model: Option<&str>) {
     let mut started = block_on(service.start_provider_endpoint(StartProviderExecution {
         client,
         provider: ProviderKind::new("openai").expect("provider"),
+        upstream_model: None,
         operation,
         metadata: ExecutionRequestMetadata {
             protocol: "openai".to_owned(),
@@ -1991,7 +4021,7 @@ impl Provider for QueuedAccountProvider {
     }
 
     async fn execute(
-        &self,
+        self: Arc<Self>,
         _: ProviderRequest,
         context: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
diff --git a/backend/crates/gateway-core/tests/engine/extensions.rs b/backend/crates/gateway-core/tests/engine/extensions.rs
new file mode 100644
index 000000000..8e583c7f5
--- /dev/null
+++ b/backend/crates/gateway-core/tests/engine/extensions.rs
@@ -0,0 +1,116 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use gateway_core::{
+    engine::{
+        AttemptContext,
+        extensions::ProviderExtensionIndex,
+        provider::{Provider, ProviderRegistry, ProviderRequest, ProviderStream, RegistryError},
+    },
+    error::ProviderError,
+    routing::{
+        ProviderCatalogGeneration, ProviderCatalogPort, ProviderKind, ProviderModelCapabilities,
+    },
+    runtime::extensions::{ExtensionSetId, ExtensionSetLease, ExtensionSetReference},
+};
+
+struct Generation(Arc<ProviderRegistry>);
+
+impl ExtensionSetLease for Generation {
+    fn is_ready(&self) -> bool {
+        !self.0.is_empty()
+    }
+}
+
+pub(super) fn register(
+    index: &ProviderExtensionIndex,
+    id: &str,
+    providers: Vec<Arc<dyn Provider>>,
+) -> ExtensionSetReference {
+    let id = ExtensionSetId::new(id.into()).unwrap();
+    let registry = index.register(id.clone(), providers).unwrap();
+    ExtensionSetReference::new(id, Arc::new(Generation(registry)))
+}
+
+struct VersionedProvider {
+    name: String,
+    version: u64,
+}
+
+#[async_trait]
+impl Provider for VersionedProvider {
+    fn name(&self) -> &str {
+        &self.name
+    }
+    fn catalog_generation(&self) -> ProviderCatalogGeneration {
+        ProviderCatalogGeneration::new(self.version)
+    }
+    async fn query_model_capabilities(
+        &self,
+    ) -> Result<Vec<ProviderModelCapabilities>, ProviderError> {
+        Ok(vec![])
+    }
+    async fn execute(
+        self: Arc<Self>,
+        _: ProviderRequest,
+        _: AttemptContext,
+    ) -> Result<ProviderStream, ProviderError> {
+        panic!("目录验证不应启动执行")
+    }
+}
+
+fn provider(name: &str, version: u64) -> Arc<dyn Provider> {
+    Arc::new(VersionedProvider {
+        name: name.into(),
+        version,
+    })
+}
+
+#[test]
+fn generations_resolve_owned_identities_and_keep_only_inflight_versions_alive() {
+    let index =
+        ProviderExtensionIndex::new(ProviderRegistry::new([provider("native", 1)]).unwrap());
+    let registry = index.registry();
+    let old = register(&index, "old", vec![provider("dynamic", 1)]);
+    let current = register(&index, "current", vec![provider("dynamic", 2)]);
+    let kind = ProviderKind::new("dynamic").unwrap();
+    let inflight = registry.for_extensions(Some(&old)).unwrap();
+    drop(old);
+    assert_eq!(inflight.catalog_generations()[&kind].get(), 1);
+    assert_eq!(
+        registry
+            .for_extensions(Some(&current))
+            .unwrap()
+            .catalog_generations()[&kind]
+            .get(),
+        2
+    );
+    assert!(inflight.contains(&ProviderKind::new("native").unwrap()));
+    assert!(registry.for_extensions(None).is_err());
+    drop(inflight);
+    // 原 ID 可再次登记证明索引没有强引用，且不会把旧 ID 偷换为 current。
+    assert!(
+        index
+            .register(ExtensionSetId::new("old".into()).unwrap(), [])
+            .is_ok()
+    );
+}
+
+#[test]
+fn preparation_rejects_native_identity_collisions_and_live_generation_replacement() {
+    let index =
+        ProviderExtensionIndex::new(ProviderRegistry::new([provider("native", 1)]).unwrap());
+    let id = ExtensionSetId::new("candidate".into()).unwrap();
+    assert!(matches!(
+        index.register(id.clone(), [provider("native", 2)]),
+        Err(RegistryError::Duplicate { .. })
+    ));
+    let generation = index
+        .register(id.clone(), [provider("dynamic", 1)])
+        .unwrap();
+    assert!(matches!(
+        index.register(id, [provider("dynamic", 2)]),
+        Err(RegistryError::DuplicateGeneration)
+    ));
+    drop(generation);
+}
diff --git a/backend/crates/gateway-core/tests/engine/middleware.rs b/backend/crates/gateway-core/tests/engine/middleware.rs
new file mode 100644
index 000000000..6cd9b9377
--- /dev/null
+++ b/backend/crates/gateway-core/tests/engine/middleware.rs
@@ -0,0 +1,450 @@
+use std::num::NonZeroU32;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::time::{Duration, SystemTime};
+
+use bytes::Bytes;
+use futures::future::BoxFuture;
+use futures::{StreamExt, stream};
+use gateway_core::account::ProviderAccountId;
+use gateway_core::account::scope::AccountGroupId;
+use gateway_core::engine::ModelRequestId;
+use gateway_core::engine::execution::ClientTransport;
+use gateway_core::engine::extensions::ExtensionCallScope;
+use gateway_core::engine::middleware::{
+    FrozenMiddlewarePlan, MiddlewareAuthority, MiddlewareBody, MiddlewareContext, MiddlewareError,
+    MiddlewareExtensionIndex, MiddlewareFrame, MiddlewareHeader, MiddlewareMount, MiddlewareNext,
+    MiddlewarePlan, MiddlewareRequest, MiddlewareResponse, MiddlewareTarget,
+};
+use gateway_core::engine::provider::{
+    ProviderCallMetadata, ProviderMiddlewareTerminal, ProviderStream, execute_attempt_middleware,
+};
+use gateway_core::error::{ProviderError, ProviderErrorKind};
+use gateway_core::event::{GatewayEvent, ProtocolWireEvent, ProviderEvent, ResponseMeta};
+use gateway_core::identity::ProviderKind;
+use gateway_core::lifecycle::CancellationToken;
+use gateway_core::operation::{GenerateRequest, Operation, OperationKind, ProtocolPayload};
+use gateway_core::policy::ClientApiKeyId;
+use gateway_core::routing::UpstreamModelId;
+use gateway_core::runtime::extensions::{ExtensionSetId, ExtensionSetLease, ExtensionSetReference};
+use gateway_core::upstream::{UpstreamSendState, UpstreamTransport};
+use serde_json::{Value, json};
+
+#[derive(Debug)]
+struct RewritingPlan {
+    calls: Arc<AtomicUsize>,
+}
+
+impl MiddlewarePlan for RewritingPlan {
+    fn handle(
+        &self,
+        context: MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        assert_eq!(context.mount(), MiddlewareMount::Attempt);
+        assert_eq!(context.attempt_index(), NonZeroU32::new(1));
+        assert_eq!(context.operation(), Some(OperationKind::Generate));
+        self.calls.fetch_add(1, Ordering::SeqCst);
+        Box::pin(async move {
+            let (protocol, headers, body) = request.into_parts();
+            let mut body: Value =
+                serde_json::from_slice(&body).map_err(|_| MiddlewareError::Fault)?;
+            body["input"] = json!("rewritten by middleware");
+            let response = next
+                .run(MiddlewareRequest::new(
+                    protocol,
+                    headers,
+                    Bytes::from(serde_json::to_vec(&body).map_err(|_| MiddlewareError::Fault)?),
+                ))
+                .await?;
+            let (protocol, status, headers, body, envelope) = response.into_parts();
+            let response = MiddlewareResponse::new(
+                protocol,
+                status,
+                headers,
+                Box::new(RewritingBody { inner: body }),
+            );
+            Ok(match envelope {
+                Some(envelope) => response.with_envelope(envelope),
+                None => response,
+            })
+        })
+    }
+}
+
+struct RewritingBody {
+    inner: Box<dyn MiddlewareBody>,
+}
+
+impl MiddlewareBody for RewritingBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async move {
+            let Some(frame) = self.inner.next_frame().await? else {
+                return Ok(None);
+            };
+            let (bytes, framing, terminal, envelope) = frame.into_parts();
+            let mut body: Value =
+                serde_json::from_slice(&bytes).map_err(|_| MiddlewareError::Fault)?;
+            body["middleware"] = json!(true);
+            let frame = MiddlewareFrame::new(
+                Bytes::from(serde_json::to_vec(&body).map_err(|_| MiddlewareError::Fault)?),
+                framing,
+                terminal,
+            );
+            Ok(Some(match envelope {
+                Some(envelope) => frame.with_envelope(envelope),
+                None => frame,
+            }))
+        })
+    }
+
+    fn commit_downstream(
+        &mut self,
+        client_status_code: Option<u16>,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        self.inner.commit_downstream(client_status_code)
+    }
+
+    fn record_client_status(
+        &mut self,
+        client_status_code: u16,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        self.inner.record_client_status(client_status_code)
+    }
+
+    fn is_finalized(&self) -> bool {
+        self.inner.is_finalized()
+    }
+
+    fn close(self: Box<Self>) -> BoxFuture<'static, ()> {
+        let Self { inner } = *self;
+        inner.close()
+    }
+}
+
+#[derive(Debug)]
+struct ReadyGeneration;
+
+impl ExtensionSetLease for ReadyGeneration {
+    fn is_ready(&self) -> bool {
+        true
+    }
+}
+
+fn context() -> MiddlewareContext {
+    MiddlewareContext::new(
+        MiddlewareTarget {
+            request_id: ModelRequestId::new("req_middleware_owned_next").unwrap(),
+            mount: MiddlewareMount::Attempt,
+            attempt_index: NonZeroU32::new(1),
+            operation: Some(OperationKind::Generate),
+            endpoint: "/v1/responses".to_owned(),
+            transport: ClientTransport::HttpJson,
+            provider: Some(ProviderKind::new("openai").unwrap()),
+            model: Some("gpt-test".to_owned()),
+            account_id: Some(ProviderAccountId::new("acct_middleware").unwrap()),
+        },
+        MiddlewareAuthority {
+            client_key_id: ClientApiKeyId::new("key_middleware").unwrap(),
+            account_group_ids: Arc::<[AccountGroupId]>::from([]),
+            cancellation: CancellationToken::new(),
+            deadline: SystemTime::now() + Duration::from_secs(5),
+            extension_scope: ExtensionCallScope::default(),
+            execution_effects: None,
+        },
+    )
+}
+
+fn operation() -> Operation {
+    Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "openai",
+            json!({"model":"gpt-test","input":"original"})
+                .as_object()
+                .unwrap()
+                .clone(),
+        )
+        .unwrap(),
+    ))
+}
+
+#[test]
+fn attempt_middleware_consumes_owned_next_once_and_preserves_host_envelopes() {
+    futures::executor::block_on(async {
+        let plan_calls = Arc::new(AtomicUsize::new(0));
+        let terminal_calls = Arc::new(AtomicUsize::new(0));
+        let index = MiddlewareExtensionIndex::default();
+        let id = ExtensionSetId::new("middleware-generation".to_owned()).unwrap();
+        let reference = ExtensionSetReference::new(id.clone(), Arc::new(ReadyGeneration));
+        let owner = index
+            .register(
+                id.clone(),
+                Arc::new(RewritingPlan {
+                    calls: Arc::clone(&plan_calls),
+                }),
+            )
+            .unwrap();
+        assert!(
+            index
+                .register(
+                    id,
+                    Arc::new(RewritingPlan {
+                        calls: Arc::new(AtomicUsize::new(0)),
+                    }),
+                )
+                .is_err(),
+            "同一发布代次不能静默替换中间件计划",
+        );
+        let plan = index.resolve(&reference).unwrap();
+
+        let terminal: ProviderMiddlewareTerminal = {
+            let terminal_calls = Arc::clone(&terminal_calls);
+            Box::new(move |operation, headers| {
+                terminal_calls.fetch_add(1, Ordering::SeqCst);
+                Box::pin(async move {
+                    assert!(headers.is_empty());
+                    let Operation::Generate(request) = operation else {
+                        panic!("middleware fixture expects generate operation")
+                    };
+                    assert_eq!(
+                        request.protocol_payload().body()["input"],
+                        "rewritten by middleware",
+                    );
+                    let response = ResponseMeta::new("response-middleware", "gpt-test");
+                    let event = |kind: &str, fact| {
+                        ProviderEvent::canonical_with_wire(
+                            vec![fact],
+                            ProtocolWireEvent::json(
+                                "openai",
+                                Some(kind.to_owned()),
+                                json!({"type":kind}),
+                            )
+                            .unwrap(),
+                        )
+                    };
+                    let metadata = ProviderCallMetadata::new(
+                        ProviderKind::new("openai").unwrap(),
+                        UpstreamModelId::new("gpt-test").unwrap(),
+                        ProviderAccountId::new("acct_middleware").unwrap(),
+                        UpstreamTransport::new("http_json").unwrap(),
+                    );
+                    Ok(ProviderStream::new(
+                        metadata,
+                        stream::iter([
+                            Ok(event(
+                                "response.created",
+                                GatewayEvent::Started(response.clone()),
+                            )),
+                            Ok(event(
+                                "response.completed",
+                                GatewayEvent::Completed(response),
+                            )),
+                        ]),
+                        (),
+                    ))
+                })
+            })
+        };
+
+        let mut stream = execute_attempt_middleware(
+            Some(&plan),
+            context(),
+            operation(),
+            ClientTransport::HttpJson,
+            terminal,
+        )
+        .await
+        .unwrap();
+        let mut events = Vec::new();
+        while let Some(event) = stream.next().await {
+            events.push(event.unwrap());
+        }
+
+        assert_eq!(plan_calls.load(Ordering::SeqCst), 1);
+        assert_eq!(terminal_calls.load(Ordering::SeqCst), 1);
+        assert_eq!(stream.metadata().provider().as_str(), "openai");
+        assert_eq!(events.len(), 2);
+        assert!(events.iter().all(|event| {
+            event
+                .wire_event()
+                .and_then(ProtocolWireEvent::raw_json_body)
+                .and_then(|body| serde_json::from_slice::<Value>(body).ok())
+                .is_some_and(|body| body["middleware"] == json!(true))
+        }));
+        assert!(matches!(
+            events[0].canonical_facts(),
+            [GatewayEvent::Started(_)]
+        ));
+        assert!(matches!(
+            events[1].canonical_facts(),
+            [GatewayEvent::Completed(_)]
+        ));
+
+        drop(owner);
+    });
+}
+
+#[derive(Debug)]
+struct AddingHeaderPlan {
+    headers: Vec<MiddlewareHeader>,
+}
+
+impl MiddlewarePlan for AddingHeaderPlan {
+    fn handle(
+        &self,
+        _context: MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        let added_headers = self.headers.clone();
+        Box::pin(async move {
+            let (protocol, mut headers, body) = request.into_parts();
+            headers.extend(added_headers);
+            next.run(MiddlewareRequest::new(protocol, headers, body))
+                .await
+        })
+    }
+}
+
+fn header_plan(generation: &str, headers: Vec<MiddlewareHeader>) -> FrozenMiddlewarePlan {
+    FrozenMiddlewarePlan::new(
+        Arc::new(AddingHeaderPlan { headers }),
+        ExtensionSetReference::new(
+            ExtensionSetId::new(generation.to_owned()).unwrap(),
+            Arc::new(ReadyGeneration),
+        ),
+    )
+}
+
+fn empty_provider_stream() -> ProviderStream {
+    ProviderStream::new(
+        ProviderCallMetadata::new(
+            ProviderKind::new("openai").unwrap(),
+            UpstreamModelId::new("gpt-test").unwrap(),
+            ProviderAccountId::new("acct_middleware").unwrap(),
+            UpstreamTransport::new("http_json").unwrap(),
+        ),
+        stream::empty(),
+        (),
+    )
+}
+
+#[test]
+fn attempt_passthrough_preserves_parsed_wire_for_every_client_transport() {
+    futures::executor::block_on(async {
+        for transport in [
+            ClientTransport::HttpJson,
+            ClientTransport::HttpSse,
+            ClientTransport::WebSocket,
+        ] {
+            let plan = header_plan("middleware-passthrough", Vec::new());
+            let payload = json!({"type":"response.completed","response":{"id":"resp_passthrough","status":"completed","output":[]}});
+            let wire = ProtocolWireEvent::json(
+                "openai",
+                Some("response.completed".to_owned()),
+                payload.clone(),
+            )
+            .unwrap();
+            let terminal: ProviderMiddlewareTerminal = Box::new(move |_, _| {
+                Box::pin(async move {
+                    Ok(ProviderStream::new(
+                        empty_provider_stream().metadata().clone(),
+                        stream::iter([Ok(ProviderEvent::wire(wire))]),
+                        (),
+                    ))
+                })
+            });
+            let mut result = execute_attempt_middleware(
+                Some(&plan),
+                context(),
+                operation(),
+                transport,
+                terminal,
+            )
+            .await
+            .unwrap();
+            let event = result.next().await.unwrap().unwrap();
+            let wire = event.wire_event().unwrap();
+            assert!(wire.has_json_data(), "{transport:?} 必须保留客户端终态语义");
+            assert_eq!(wire.data(), &payload);
+        }
+    });
+}
+
+#[test]
+fn attempt_middleware_forwards_business_headers_but_rejects_authentication_headers() {
+    futures::executor::block_on(async {
+        let allowed_calls = Arc::new(AtomicUsize::new(0));
+        let allowed_terminal: ProviderMiddlewareTerminal = {
+            let allowed_calls = Arc::clone(&allowed_calls);
+            Box::new(move |_operation, headers| {
+                allowed_calls.fetch_add(1, Ordering::SeqCst);
+                Box::pin(async move {
+                    assert_eq!(headers.len(), 2);
+                    assert!(
+                        headers
+                            .iter()
+                            .all(|header| header.name() == "x-business-context")
+                    );
+                    assert_eq!(headers[0].value().as_ref(), b"tenant-public");
+                    assert_eq!(headers[1].value().as_ref(), b"trace-public");
+                    Ok(empty_provider_stream())
+                })
+            })
+        };
+        let allowed = header_plan(
+            "middleware-business-header",
+            vec![
+                MiddlewareHeader::new("x-business-context", Bytes::from_static(b"tenant-public")),
+                MiddlewareHeader::new("x-business-context", Bytes::from_static(b"trace-public")),
+            ],
+        );
+
+        execute_attempt_middleware(
+            Some(&allowed),
+            context(),
+            operation(),
+            ClientTransport::HttpJson,
+            allowed_terminal,
+        )
+        .await
+        .unwrap();
+        assert_eq!(allowed_calls.load(Ordering::SeqCst), 1);
+
+        let rejected_calls = Arc::new(AtomicUsize::new(0));
+        let rejected_terminal: ProviderMiddlewareTerminal = {
+            let rejected_calls = Arc::clone(&rejected_calls);
+            Box::new(move |_operation, _headers| {
+                rejected_calls.fetch_add(1, Ordering::SeqCst);
+                Box::pin(async {
+                    Err(ProviderError::new(
+                        ProviderErrorKind::Unavailable,
+                        UpstreamSendState::NotSent,
+                    ))
+                })
+            })
+        };
+        let rejected = header_plan(
+            "middleware-authentication-header",
+            vec![MiddlewareHeader::new(
+                "authorization",
+                Bytes::from_static(b"Bearer forbidden"),
+            )],
+        );
+
+        let error = execute_attempt_middleware(
+            Some(&rejected),
+            context(),
+            operation(),
+            ClientTransport::HttpJson,
+            rejected_terminal,
+        )
+        .await
+        .err()
+        .expect("protected headers must fail before the Provider terminal");
+        assert_eq!(error.kind(), ProviderErrorKind::Protocol);
+        assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+        assert_eq!(rejected_calls.load(Ordering::SeqCst), 0);
+    });
+}
diff --git a/backend/crates/gateway-core/tests/engine/mod.rs b/backend/crates/gateway-core/tests/engine/mod.rs
index e761fc07d..77f636625 100644
--- a/backend/crates/gateway-core/tests/engine/mod.rs
+++ b/backend/crates/gateway-core/tests/engine/mod.rs
@@ -2,6 +2,9 @@ mod admission;
 mod continuation;
 mod coordinator;
 mod execution;
+mod extensions;
+mod middleware;
+mod policy;
 mod probe;
 mod provider;
 
diff --git a/backend/crates/gateway-core/tests/engine/policy.rs b/backend/crates/gateway-core/tests/engine/policy.rs
new file mode 100644
index 000000000..f460ce7d6
--- /dev/null
+++ b/backend/crates/gateway-core/tests/engine/policy.rs
@@ -0,0 +1,189 @@
+use std::{
+    collections::BTreeSet,
+    num::NonZeroU32,
+    sync::Arc,
+    time::{Duration, SystemTime},
+};
+
+use futures::{executor::block_on, future::BoxFuture};
+use gateway_core::{
+    account::{
+        AccountCandidate, AccountEligibilityPolicy, AccountRuntimeSignals, AccountSelectionContext,
+        AccountSelectionPolicy, AccountWeight, CredentialRevision, CredentialState,
+        PreferredAccountSelection, ProviderAccount, ProviderAccountId, QuotaState,
+        RotationStrategy,
+    },
+    engine::{
+        ModelRequestId,
+        policy::{
+            AccountPolicyError, AccountScheduleDecision, AccountScheduleInput, ModelRouteDecision,
+            ModelRouteInput, RequestPolicyContext, RequestPolicyFault, RequestPolicyPlan,
+        },
+    },
+    policy::ClientApiKeyId,
+    routing::ProviderKind,
+    runtime::extensions::{ExtensionSetId, ExtensionSetLease, ExtensionSetReference},
+};
+
+#[derive(Debug)]
+struct FixedScheduler(Option<&'static str>);
+
+impl RequestPolicyPlan for FixedScheduler {
+    fn route_model(
+        &self,
+        _: ModelRouteInput,
+    ) -> BoxFuture<'static, Result<ModelRouteDecision, RequestPolicyFault>> {
+        Box::pin(async { Ok(ModelRouteDecision::Unhandled) })
+    }
+
+    fn schedule_account(
+        &self,
+        _: AccountScheduleInput,
+    ) -> BoxFuture<'static, Result<AccountScheduleDecision, RequestPolicyFault>> {
+        let decision = self.0.map_or(AccountScheduleDecision::Delegate, |id| {
+            AccountScheduleDecision::Pick(account_id(id))
+        });
+        Box::pin(async move { Ok(decision) })
+    }
+}
+
+struct Lease;
+impl ExtensionSetLease for Lease {
+    fn is_ready(&self) -> bool {
+        true
+    }
+}
+
+fn account_id(id: &str) -> ProviderAccountId {
+    ProviderAccountId::new(id.to_owned()).unwrap()
+}
+
+fn candidate(id: &str) -> AccountCandidate {
+    AccountCandidate {
+        account: ProviderAccount::new(
+            account_id(id),
+            ProviderKind::new("openai").unwrap(),
+            id.into(),
+            None,
+            "test".into(),
+            CredentialRevision::new(1).unwrap(),
+            None,
+        )
+        .with_account_facts(
+            true,
+            CredentialState::Ready,
+            QuotaState::unknown(),
+            None,
+            None,
+        )
+        .with_scheduling(None, AccountWeight::new(100).unwrap()),
+        signals: AccountRuntimeSignals {
+            in_flight: 0,
+            last_started_at: None,
+            quota_reset_at: None,
+            quota_remaining_rank: None,
+            cooldown: None,
+            failure_rate_basis_points: None,
+            first_output_latency_ms: None,
+        },
+    }
+}
+
+fn policy(choice: Option<&'static str>) -> RequestPolicyContext {
+    RequestPolicyContext::new(
+        Arc::new(FixedScheduler(choice)),
+        ExtensionSetReference::new(
+            ExtensionSetId::new("scheduler-test".into()).unwrap(),
+            Arc::new(Lease),
+        ),
+        ModelRequestId::new("req_scheduler").unwrap(),
+        ClientApiKeyId::new("scheduler-key").unwrap(),
+        vec![],
+    )
+}
+
+fn context() -> AccountSelectionContext {
+    AccountSelectionContext {
+        policy: AccountSelectionPolicy::new(
+            RotationStrategy::Sticky,
+            NonZeroU32::new(2).unwrap(),
+            Duration::ZERO,
+        ),
+        now: SystemTime::now(),
+        excluded_accounts: BTreeSet::new(),
+        preferred_account: Some(account_id("acct_a")),
+        preferred_account_overrides_weight: true,
+        round_robin_cursor: 0,
+        eligibility: AccountEligibilityPolicy::Enforce,
+        account_scope: None,
+    }
+}
+
+#[test]
+fn scheduler_can_override_soft_affinity_and_reports_the_override() {
+    block_on(async {
+        let candidates = [candidate("acct_a"), candidate("acct_b")];
+        let selected = policy(Some("acct_b"))
+            .select_account(
+                NonZeroU32::new(1).unwrap(),
+                &ProviderKind::new("openai").unwrap(),
+                Some("demo-model"),
+                &candidates,
+                &context(),
+            )
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(
+            (
+                selected.candidate().account.id().as_str(),
+                selected.preferred()
+            ),
+            ("acct_b", PreferredAccountSelection::OverriddenByPolicy)
+        );
+    });
+}
+
+#[test]
+fn delegated_scheduler_keeps_builtin_affinity() {
+    block_on(async {
+        let candidates = [candidate("acct_a"), candidate("acct_b")];
+        let selected = policy(None)
+            .select_account(
+                NonZeroU32::new(1).unwrap(),
+                &ProviderKind::new("openai").unwrap(),
+                None,
+                &candidates,
+                &context(),
+            )
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(
+            (
+                selected.candidate().account.id().as_str(),
+                selected.preferred()
+            ),
+            ("acct_a", PreferredAccountSelection::Hit)
+        );
+    });
+}
+
+#[test]
+fn scheduler_cannot_select_outside_the_hard_bound_candidate_pool() {
+    block_on(async {
+        let candidates = [candidate("acct_a"), candidate("acct_b")];
+        let mut context = context();
+        context.excluded_accounts.insert(account_id("acct_b"));
+        let result = policy(Some("acct_b"))
+            .select_account(
+                NonZeroU32::new(1).unwrap(),
+                &ProviderKind::new("openai").unwrap(),
+                None,
+                &candidates,
+                &context,
+            )
+            .await;
+        assert!(matches!(result, Err(AccountPolicyError::Fault)));
+    });
+}
diff --git a/backend/crates/gateway-core/tests/engine/provider.rs b/backend/crates/gateway-core/tests/engine/provider.rs
index baa8a1f78..e43edc54b 100644
--- a/backend/crates/gateway-core/tests/engine/provider.rs
+++ b/backend/crates/gateway-core/tests/engine/provider.rs
@@ -49,7 +49,7 @@ impl Provider for NamedProvider {
     }
 
     async fn execute(
-        &self,
+        self: Arc<Self>,
         _request: ProviderRequest,
         _context: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
@@ -127,7 +127,7 @@ impl Provider for CatalogProvider {
     }
 
     async fn execute(
-        &self,
+        self: Arc<Self>,
         _: ProviderRequest,
         _: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
diff --git a/backend/crates/gateway-core/tests/event.rs b/backend/crates/gateway-core/tests/event.rs
index f9a7a0c83..eb2d4c55d 100644
--- a/backend/crates/gateway-core/tests/event.rs
+++ b/backend/crates/gateway-core/tests/event.rs
@@ -88,6 +88,16 @@ fn protocol_wire_event_should_preserve_raw_json_body_without_parsing_it() {
     assert_eq!(wire.into_raw_json_body(), Some(raw));
 }
 
+#[test]
+fn protocol_wire_event_should_preserve_raw_http_body_without_json_encoding() {
+    let raw = Bytes::from_static(b"\0opaque-http-body\xff");
+    let wire =
+        ProtocolWireEvent::raw_http_body("provider-http", raw.clone()).expect("raw HTTP event");
+
+    assert_eq!(wire.raw_http_body_bytes(), Some(&raw));
+    assert_eq!(wire.into_raw_http_body(), Some(raw));
+}
+
 #[test]
 fn validator_should_accept_started_content_delta_completed_sequence() {
     let mut validator = EventSequenceValidator::new();
diff --git a/backend/crates/gateway-core/tests/lifecycle.rs b/backend/crates/gateway-core/tests/lifecycle.rs
index 923573519..a606b1955 100644
--- a/backend/crates/gateway-core/tests/lifecycle.rs
+++ b/backend/crates/gateway-core/tests/lifecycle.rs
@@ -1,6 +1,7 @@
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
 
+use futures::{FutureExt as _, pin_mut};
 use gateway_core::lifecycle::CancellationToken;
 
 #[test]
@@ -10,6 +11,36 @@ fn cancellation_token_should_wake_current_state() {
 
     assert!(token.is_cancelled());
 }
+
+#[test]
+fn child_cancellation_inherits_parent_without_cancelling_parent() {
+    futures::executor::block_on(async {
+        let parent = CancellationToken::new();
+        let child = parent.child_token();
+        child.cancel();
+
+        child.cancelled().await;
+        assert!(child.is_cancelled());
+        assert!(!parent.is_cancelled());
+    });
+}
+
+#[test]
+fn parent_cancellation_wakes_nested_descendants() {
+    futures::executor::block_on(async {
+        let parent = CancellationToken::new();
+        let child = parent.child_token();
+        let grandchild = child.child_token();
+        let waiting = grandchild.cancelled();
+        pin_mut!(waiting);
+        assert!(waiting.as_mut().now_or_never().is_none());
+
+        parent.cancel();
+        waiting.await;
+        assert!(child.is_cancelled());
+        assert!(grandchild.is_cancelled());
+    });
+}
 use gateway_core::lifecycle::{ConnectionDraining, ConnectionGuard, ConnectionLifecycle};
 
 #[derive(Default)]
diff --git a/backend/crates/gateway-core/tests/operation/mod.rs b/backend/crates/gateway-core/tests/operation/mod.rs
index c206d69c0..e9b287c10 100644
--- a/backend/crates/gateway-core/tests/operation/mod.rs
+++ b/backend/crates/gateway-core/tests/operation/mod.rs
@@ -1,7 +1,9 @@
 use bytes::Bytes;
 use gateway_core::operation::{
     Feature, GenerateRequest, ImageRequest, ImageRequestKind, Operation, OperationKind,
-    ProtocolPayload, ProviderSessionState, RawJsonPayload, StandaloneSearchRequest,
+    ProtocolPayload, ProviderHttpHeader, ProviderHttpMethod, ProviderHttpRequest,
+    ProviderSessionState, RawHttpPayload, RawJsonPayload, StandaloneSearchRequest,
+    TokenCountRequest,
 };
 use serde_json::{Map, Value, json};
 
@@ -69,6 +71,138 @@ fn capability_requirements_should_read_known_openai_fields_without_rewriting_bod
     );
 }
 
+#[test]
+fn middleware_protocol_change_keeps_source_capability_facts_without_interpreting_target_json() {
+    let operation = Operation::Generate(generate(json!({
+        "model":"gpt-test",
+        "input":[{"type":"message","role":"user","content":[{
+            "type":"input_image","image_url":"https://example.invalid/image.png"
+        }]}],
+        "tools":[{"type":"function","name":"lookup"}],
+        "reasoning":{"effort":"future-level"},
+        "text":{"format":{"type":"json_schema","name":"result","schema":{}}},
+        "previous_response_id":"resp_previous",
+        "max_output_tokens":1024
+    })));
+    let source_requirements = operation.capability_requirements();
+    let translated = operation
+        .replace_middleware_wire(
+            "openai_chat_completions",
+            Bytes::from_static(
+                br#"{"model":"gpt-test","messages":[{"role":"user","content":"hello"}],"max_completion_tokens":1024}"#,
+            ),
+        )
+        .expect("direct translation");
+
+    assert_eq!(translated.protocol(), "openai_chat_completions");
+    assert_eq!(translated.capability_requirements(), source_requirements);
+    let replaced = translated
+        .replace_protocol_wire(
+            Some(Bytes::from_static(
+                br#"{"model":"gpt-test","messages":[{"role":"user","content":"enriched"}]}"#,
+            )),
+            Map::new(),
+        )
+        .expect("post-translation processing");
+    assert_eq!(replaced.capability_requirements(), source_requirements);
+}
+
+#[test]
+fn native_encoding_keeps_admission_context_and_session_after_optional_translation() {
+    let context = Map::from_iter([("conversation_id".to_owned(), json!("conversation"))]);
+    let session = ProviderSessionState::new(
+        "xai",
+        Map::from_iter([("session_id".to_owned(), json!("session"))]),
+    )
+    .unwrap();
+    let request = GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "openai",
+            json!({"input":"hello", "max_output_tokens":64, "reasoning":{"effort":"high"}})
+                .as_object()
+                .unwrap()
+                .clone(),
+        )
+        .unwrap()
+        .with_context(context.clone()),
+    )
+    .with_provider_session_state(session.clone());
+    let original = Operation::Generate(request.clone());
+    let translated = original
+        .clone()
+        .replace_middleware_wire("native-input", Bytes::from_static(br#"{"prompt":"hello"}"#))
+        .unwrap();
+    let Operation::Generate(translated) = translated else {
+        panic!("generate request");
+    };
+
+    for (request, target) in [(request, "openai"), (translated, "xai")] {
+        let body = Map::from_iter([("native_prompt".to_owned(), json!("encoded"))]);
+        let encoded = request
+            .with_native_encoded_body(target, body.clone())
+            .unwrap();
+        assert_eq!(encoded.protocol_payload().protocol(), target);
+        assert_eq!(encoded.protocol_payload().body(), &body);
+        assert_eq!(encoded.protocol_payload().context(), &context);
+        assert_eq!(encoded.provider_session_state("xai"), Some(&session));
+        let operation = Operation::Generate(encoded);
+        assert_eq!(
+            operation.capability_requirements(),
+            original.capability_requirements()
+        );
+        assert!(
+            operation
+                .replace_middleware_wire("another", Bytes::from_static(b"{}"))
+                .is_err()
+        );
+    }
+}
+
+#[test]
+fn native_encoding_rejects_invalid_protocol_names() {
+    for name in ["", "invalid\nprotocol"] {
+        assert!(
+            generate(json!({"input":"hello"}))
+                .with_native_encoded_body(name, Map::new())
+                .is_err()
+        );
+    }
+}
+
+#[test]
+fn middleware_processing_recomputes_requirements_but_protocol_change_is_direct_once() {
+    let operation = Operation::Generate(generate(json!({
+        "model":"gpt-test",
+        "input":"hello"
+    })));
+    let enriched = operation
+        .replace_middleware_wire(
+            "openai",
+            Bytes::from_static(br#"{"model":"gpt-test","input":"hello","max_output_tokens":64}"#),
+        )
+        .expect("same-protocol middleware processing");
+    assert_eq!(
+        enriched.capability_requirements().requested_output_tokens(),
+        Some(64)
+    );
+    let translated = enriched
+        .replace_middleware_wire(
+            "openai_chat_completions",
+            Bytes::from_static(
+                br#"{"model":"gpt-test","messages":[{"role":"user","content":"hello"}],"max_completion_tokens":64}"#,
+            ),
+        )
+        .expect("first direct translation");
+    assert!(
+        translated
+            .replace_middleware_wire(
+                "anthropic_messages",
+                Bytes::from_static(br#"{"model":"gpt-test","messages":[]}"#),
+            )
+            .is_err()
+    );
+}
+
 #[test]
 fn prompt_cache_and_image_generation_should_be_read_from_raw_body() {
     let request = generate(json!({
@@ -128,13 +262,138 @@ fn operation_kind_should_remain_stable() {
         )
         .expect("OpenAI search payload"),
     ));
+    let count = Operation::CountTokens(TokenCountRequest::from_raw_json(
+        RawJsonPayload::new("token-count", Bytes::from_static(br#"{"input":"hello"}"#))
+            .expect("token count payload"),
+    ));
+    let provider_http = Operation::ProviderHttp(
+        ProviderHttpRequest::new(
+            "inspect",
+            ProviderHttpMethod::Post,
+            Some("mode=future".to_owned()),
+            vec![ProviderHttpHeader::new(
+                "x-opaque",
+                Bytes::from_static(b"private-header"),
+            )],
+            RawHttpPayload::new("provider-http", Bytes::from_static(b"private-body"))
+                .expect("provider HTTP payload"),
+        )
+        .expect("provider HTTP request"),
+    );
 
     assert_eq!(generate.kind(), OperationKind::Generate);
     assert_eq!(image.kind(), OperationKind::GenerateImage);
     assert_eq!(search.kind(), OperationKind::Search);
+    assert_eq!(count.kind(), OperationKind::CountTokens);
+    assert_eq!(provider_http.kind(), OperationKind::ProviderHttp);
     assert_eq!(OperationKind::Search.as_str(), "search");
+    assert_eq!(OperationKind::CountTokens.as_str(), "count_tokens");
+    assert_eq!(OperationKind::ProviderHttp.as_str(), "provider_http");
     assert!(image.image_generation_requested());
     assert!(!search.image_generation_requested());
+    assert!(!format!("{provider_http:?}").contains("private-header"));
+    assert!(!format!("{provider_http:?}").contains("private-body"));
+}
+
+#[test]
+fn provider_http_should_reject_urls_controls_and_unbounded_headers() {
+    let payload =
+        || RawHttpPayload::new("provider-http", Bytes::new()).expect("provider HTTP payload");
+    assert!(
+        ProviderHttpRequest::new(
+            "https://example.invalid/models",
+            ProviderHttpMethod::Get,
+            None,
+            Vec::new(),
+            payload(),
+        )
+        .is_err()
+    );
+    assert!(
+        ProviderHttpRequest::new(
+            "models",
+            ProviderHttpMethod::Get,
+            Some("ok=1\r\ninjected=1".to_owned()),
+            Vec::new(),
+            payload(),
+        )
+        .is_err()
+    );
+    assert!(
+        ProviderHttpRequest::new(
+            "models",
+            ProviderHttpMethod::Get,
+            None,
+            vec![ProviderHttpHeader::new(
+                "x-large",
+                Bytes::from(vec![b'x'; 8 * 1024 + 1]),
+            )],
+            payload(),
+        )
+        .is_err()
+    );
+}
+
+#[test]
+fn provider_http_wire_replacement_keeps_frozen_target_and_validates_typed_headers() {
+    let operation = Operation::ProviderHttp(
+        ProviderHttpRequest::new(
+            "inspect",
+            ProviderHttpMethod::Post,
+            Some("mode=stable".to_owned()),
+            vec![ProviderHttpHeader::new(
+                "x-original",
+                Bytes::from_static(b"old"),
+            )],
+            RawHttpPayload::new("provider-http", Bytes::from_static(b"old-body"))
+                .expect("provider HTTP payload"),
+        )
+        .expect("provider HTTP request"),
+    );
+    assert!(
+        operation
+            .clone()
+            .replace_provider_http_wire(
+                None,
+                Map::new(),
+                vec![ProviderHttpHeader::new(
+                    "x-invalid",
+                    Bytes::from_static(b"line\r\nbreak"),
+                )],
+            )
+            .is_err()
+    );
+    let replacement = operation
+        .replace_provider_http_wire(
+            Some(Bytes::from_static(&[0x00, 0xff, b'n', b'e', b'w'])),
+            Map::from_iter([("connection_fact".to_owned(), json!("kept"))]),
+            vec![
+                ProviderHttpHeader::new("x-repeat", Bytes::from_static(&[0xff, 0xfe])),
+                ProviderHttpHeader::new("x-repeat", Bytes::from_static(b"two")),
+            ],
+        )
+        .expect("typed Provider HTTP replacement");
+    let Operation::ProviderHttp(request) = replacement else {
+        panic!("operation kind changed")
+    };
+    assert_eq!(request.endpoint(), "inspect");
+    assert_eq!(request.method(), ProviderHttpMethod::Post);
+    assert_eq!(request.query(), Some("mode=stable"));
+    assert_eq!(
+        request.payload().body().as_ref(),
+        &[0x00, 0xff, b'n', b'e', b'w']
+    );
+    assert_eq!(request.payload().context()["connection_fact"], "kept");
+    assert_eq!(request.headers().len(), 2);
+    assert_eq!(request.headers()[0].value().as_ref(), &[0xff, 0xfe]);
+    assert_eq!(request.headers()[1].value().as_ref(), b"two");
+
+    let generate = Operation::Generate(generate(json!({"model":"gpt-test"})));
+    assert!(
+        generate
+            .replace_provider_http_wire(None, Map::new(), Vec::new())
+            .is_err()
+    );
 }
 
 #[test]
diff --git a/backend/crates/gateway-core/tests/routing/mod.rs b/backend/crates/gateway-core/tests/routing/mod.rs
index 19ca6aed8..28dac1b51 100644
--- a/backend/crates/gateway-core/tests/routing/mod.rs
+++ b/backend/crates/gateway-core/tests/routing/mod.rs
@@ -7,7 +7,8 @@ use bytes::Bytes;
 use gateway_core::account::{AccountSelectionPolicy, ProviderAccountId, RotationStrategy};
 use gateway_core::operation::{
     CapabilityRequirements, Feature, GenerateRequest, ImageRequest, ImageRequestKind, Operation,
-    OperationKind, ProtocolPayload, RawJsonPayload,
+    OperationKind, ProtocolPayload, ProviderHttpMethod, ProviderHttpRequest, RawHttpPayload,
+    RawJsonPayload, TokenCountRequest,
 };
 use gateway_core::policy::{ClientApiKeyId, ClientPolicy, PlaintextClientApiKey, RateLimits};
 use gateway_core::routing::{
@@ -443,6 +444,31 @@ fn empty_account_scope_should_not_be_misreported_as_model_not_found() {
     assert_eq!(error, gateway_core::error::RoutingError::EmptyAccountScope);
 }
 
+#[test]
+fn forced_provider_does_not_bypass_an_empty_key_account_scope() {
+    let snapshot = snapshot();
+    let empty_scope = Arc::new(FrozenAccountScope::new(
+        Arc::new(RuntimeAccountDirectory::default()),
+        ClientRoutingScope::all_accounts(),
+    ));
+    let error = snapshot
+        .plan(
+            &PublicModelId::new("gpt-5.5").expect("model"),
+            &operation(),
+            empty_scope,
+            &RoutingContext {
+                required_provider: Some(ProviderKind::new("openai").expect("provider")),
+                ..RoutingContext::default()
+            },
+        )
+        .expect_err("a forced Provider is not an account authorization");
+
+    assert!(matches!(
+        error,
+        gateway_core::error::RoutingError::NoCapableProvider { .. }
+    ));
+}
+
 #[test]
 fn provider_endpoint_plan_should_not_consult_or_publish_the_text_model_catalog() {
     let snapshot = snapshot();
@@ -453,6 +479,7 @@ fn provider_endpoint_plan_should_not_consult_or_publish_the_text_model_catalog()
     let plan = snapshot
         .plan_provider_endpoint(
             &provider,
+            None,
             &image_operation(),
             snapshot.all_account_scope(),
             &RoutingContext::default(),
@@ -473,6 +500,7 @@ fn provider_endpoint_plan_should_still_respect_circuit_filtering() {
     let error = snapshot
         .plan_provider_endpoint(
             &provider,
+            None,
             &image_operation(),
             snapshot.all_account_scope(),
             &RoutingContext {
@@ -488,6 +516,109 @@ fn provider_endpoint_plan_should_still_respect_circuit_filtering() {
     ));
 }
 
+#[test]
+fn token_count_endpoint_should_require_exact_model_capability_and_scope() {
+    let provider = ProviderKind::new("openai").expect("provider");
+    let model = UpstreamModelId::new("gpt-5.5").expect("model");
+    let operation = Operation::CountTokens(TokenCountRequest::from_raw_json(
+        RawJsonPayload::new("token-count", Bytes::from_static(br#"{"input":"hello"}"#))
+            .expect("token count payload"),
+    ));
+    let unsupported = snapshot()
+        .plan_provider_endpoint(
+            &provider,
+            Some(&model),
+            &operation,
+            account_scope(),
+            &RoutingContext::default(),
+        )
+        .expect_err("generate-only model cannot count tokens");
+    assert!(matches!(
+        unsupported,
+        gateway_core::error::RoutingError::UnsupportedProviderEndpoint { .. }
+    ));
+
+    let capabilities = ModelCapabilities::new(
+        BTreeSet::from([OperationKind::Generate, OperationKind::CountTokens]),
+        Some(16_000),
+    );
+    let capable = RuntimeSnapshot::new(
+        ConfigRevision::new(1).expect("revision"),
+        scheduling(),
+        vec![provider.clone()],
+        vec![ProviderModel::new(
+            provider.clone(),
+            model.clone(),
+            capabilities,
+        )],
+        Vec::new(),
+    )
+    .expect("snapshot")
+    .with_account_directory(account_directory());
+    let plan = capable
+        .plan_provider_endpoint(
+            &provider,
+            Some(&model),
+            &operation,
+            capable.all_account_scope(),
+            &RoutingContext::default(),
+        )
+        .expect("declared token counter");
+    assert_eq!(plan.operation(), OperationKind::CountTokens);
+    assert_eq!(plan.candidates()[0].upstream_model(), Some(&model));
+    assert!(
+        capable
+            .plan_provider_endpoint(
+                &provider,
+                None,
+                &operation,
+                capable.all_account_scope(),
+                &RoutingContext::default(),
+            )
+            .is_err(),
+        "token counting cannot drop the model binding"
+    );
+}
+
+#[test]
+fn provider_http_endpoint_should_be_provider_scoped_without_a_model_binding() {
+    let snapshot = snapshot();
+    let provider = ProviderKind::new("openai").expect("provider");
+    let operation = Operation::ProviderHttp(
+        ProviderHttpRequest::new(
+            "models",
+            ProviderHttpMethod::Get,
+            None,
+            Vec::new(),
+            RawHttpPayload::new("provider-http", Bytes::new()).expect("HTTP payload"),
+        )
+        .expect("provider HTTP operation"),
+    );
+    let plan = snapshot
+        .plan_provider_endpoint(
+            &provider,
+            None,
+            &operation,
+            snapshot.all_account_scope(),
+            &RoutingContext::default(),
+        )
+        .expect("provider endpoint");
+    assert_eq!(plan.candidates()[0].provider(), &provider);
+    assert_eq!(plan.candidates()[0].upstream_model(), None);
+    assert!(
+        snapshot
+            .plan_provider_endpoint(
+                &provider,
+                Some(&UpstreamModelId::new("gpt-5.5").expect("model")),
+                &operation,
+                snapshot.all_account_scope(),
+                &RoutingContext::default(),
+            )
+            .is_err(),
+        "raw provider HTTP cannot smuggle a model binding"
+    );
+}
+
 #[test]
 fn unmapped_model_should_pass_through_unchanged() {
     let snapshot = RuntimeSnapshot::new(
@@ -657,7 +788,10 @@ fn alias_should_only_be_available_from_a_provider_with_its_mapped_model() {
 
 #[test]
 fn account_model_access_filters_catalog_and_aliases_using_the_whole_frozen_pool() {
-    use gateway_core::account::{AccountModelAccess, AccountModelAccessMode};
+    use gateway_core::{
+        account::{AccountModelAccess, AccountModelAccessMode},
+        error::RoutingError,
+    };
     let provider = ProviderKind::new("openai").expect("provider");
     let restricted =
         AccountModelAccess::new(AccountModelAccessMode::Denylist, vec!["gpt-5.5".to_owned()])
@@ -667,7 +801,10 @@ fn account_model_access_filters_catalog_and_aliases_using_the_whole_frozen_pool(
         RuntimeAccount::new(provider.clone(), BTreeSet::new())
             .with_model_access(restricted.clone()),
     )])));
-    let old_scope = FrozenAccountScope::new(directory, ClientRoutingScope::all_accounts());
+    let old_scope = Arc::new(FrozenAccountScope::new(
+        directory,
+        ClientRoutingScope::all_accounts(),
+    ));
     let snapshot = snapshot();
     assert_eq!(
         snapshot
@@ -681,6 +818,15 @@ fn account_model_access_filters_catalog_and_aliases_using_the_whole_frozen_pool(
         &PublicModelId::new("gpt-5.4").expect("alias"),
         &old_scope
     ));
+    assert!(matches!(
+        snapshot.plan(
+            &PublicModelId::new("gpt-5.4").expect("alias"),
+            &operation(),
+            old_scope.clone(),
+            &RoutingContext::default(),
+        ),
+        Err(RoutingError::NoCapableProvider { .. })
+    ));
     let new_scope = FrozenAccountScope::new(
         Arc::new(RuntimeAccountDirectory::new(BTreeMap::from([
             (
diff --git a/backend/crates/gateway-core/tests/routing/snapshot.rs b/backend/crates/gateway-core/tests/routing/snapshot.rs
index 330076c80..6291769e0 100644
--- a/backend/crates/gateway-core/tests/routing/snapshot.rs
+++ b/backend/crates/gateway-core/tests/routing/snapshot.rs
@@ -17,6 +17,10 @@ use gateway_core::routing::{
     ProviderCatalogPort, ProviderCatalogUnavailable, ProviderKind, ProviderModelCapabilities,
     PublicModelId, UpstreamModelId,
 };
+use gateway_core::runtime::extensions::{
+    ExtensionPreparationError, ExtensionPreparationPort, ExtensionSetId, ExtensionSetLease,
+    ExtensionSetReference,
+};
 
 #[derive(Clone)]
 struct TestSnapshotStore {
@@ -44,11 +48,69 @@ impl SnapshotStorePort for TestSnapshotStore {
     }
 }
 
+struct SequencedSnapshotStore {
+    facts: Vec<SnapshotFacts>,
+    loads: AtomicUsize,
+    current_revision: ConfigRevision,
+}
+
+impl SnapshotStorePort for SequencedSnapshotStore {
+    fn load_snapshot_facts(&self) -> BoxFuture<'_, Result<SnapshotFacts, SnapshotStoreError>> {
+        Box::pin(async move {
+            let index = self.loads.fetch_add(1, Ordering::SeqCst);
+            Ok(self.facts[index.min(self.facts.len() - 1)].clone())
+        })
+    }
+
+    fn current_config_revision(&self) -> BoxFuture<'_, Result<ConfigRevision, SnapshotStoreError>> {
+        Box::pin(async move { Ok(self.current_revision) })
+    }
+}
+
 struct PublishingCatalog {
     generation: AtomicU64,
     queries: AtomicUsize,
 }
 
+struct TestExtensionLease {
+    drops: Arc<AtomicUsize>,
+}
+
+impl Drop for TestExtensionLease {
+    fn drop(&mut self) {
+        self.drops.fetch_add(1, Ordering::SeqCst);
+    }
+}
+
+impl ExtensionSetLease for TestExtensionLease {
+    fn is_ready(&self) -> bool {
+        true
+    }
+}
+
+struct CountingExtensionPreparation {
+    prepares: AtomicUsize,
+    drops: Arc<AtomicUsize>,
+}
+
+impl ExtensionPreparationPort for CountingExtensionPreparation {
+    fn prepare(
+        &self,
+        _: ConfigRevision,
+    ) -> BoxFuture<'_, Result<ExtensionSetReference, ExtensionPreparationError>> {
+        let sequence = self.prepares.fetch_add(1, Ordering::SeqCst) + 1;
+        let lease = Arc::new(TestExtensionLease {
+            drops: Arc::clone(&self.drops),
+        });
+        Box::pin(async move {
+            Ok(ExtensionSetReference::new(
+                ExtensionSetId::new(format!("prepared-{sequence}")).unwrap(),
+                lease,
+            ))
+        })
+    }
+}
+
 enum TestCatalog {
     NoProviders,
     Unavailable,
@@ -172,6 +234,101 @@ fn compiler_accepts_unlimited_default_account_concurrency() {
     );
 }
 
+#[test]
+fn withdrawn_provider_keeps_accounts_without_becoming_a_route_or_expanding_group_scope() {
+    use gateway_core::{
+        account::ProviderAccountId,
+        error::RoutingError,
+        routing::{AccountGroupId, RoutingContext},
+    };
+
+    let retired = ProviderKind::new("retired").unwrap();
+    let retired_account = ProviderAccountId::new("acct_retired").unwrap();
+    let active_account = ProviderAccountId::new("acct_active").unwrap();
+    let group = AccountGroupId::new("grp_00000000000000000000000000000001").unwrap();
+    let model = PublicModelId::new("listed-model").unwrap();
+    for restricted in [false, true] {
+        let facts = SnapshotFacts::new(
+            revision(1),
+            revision(1),
+            SnapshotSettingsFacts::new(
+                3,
+                0,
+                "smart",
+                BTreeMap::from([("alias".into(), "listed-model".into())]),
+                None,
+                None,
+            ),
+            vec![SnapshotClientPolicyFacts::new(
+                ClientApiKeyId::new("key_retired").unwrap(),
+                PlaintextClientApiKey::new("sk_retired_test").unwrap(),
+                if restricted {
+                    vec![group.clone()]
+                } else {
+                    vec![]
+                },
+                RateLimits::unlimited(),
+            )],
+            vec![SnapshotAccountGroupFacts::new(
+                group.clone(),
+                "Retired".into(),
+                true,
+            )],
+            vec![
+                SnapshotProviderAccountFacts::new(retired_account.clone(), "retired"),
+                SnapshotProviderAccountFacts::new(active_account.clone(), "alpha"),
+            ],
+            vec![SnapshotAccountGroupMemberFacts::new(
+                group.clone(),
+                retired_account.clone(),
+            )],
+        );
+        let snapshot = block_on(
+            RuntimeSnapshotCompiler::new(
+                Arc::new(TestSnapshotStore::new(Ok(facts))),
+                Arc::new(TestCatalog::Discovery),
+            )
+            .compile(),
+        )
+        .unwrap();
+        let scope = snapshot
+            .client_policies()
+            .next()
+            .unwrap()
+            .account_scope()
+            .clone();
+        assert!(scope.allows(&retired_account));
+        assert_eq!(scope.allows(&active_account), !restricted);
+        assert!(snapshot.public_models_for_provider(&retired).is_empty());
+        let plan = snapshot.plan(
+            &model,
+            &super::operation(),
+            scope.clone(),
+            &Default::default(),
+        );
+        if restricted {
+            assert!(matches!(plan, Err(RoutingError::NoCapableProvider { .. })));
+            assert!(snapshot.public_models_for_scope(&scope).is_empty());
+        } else {
+            let plan = plan.unwrap();
+            assert_eq!(plan.candidates().len(), 1);
+            assert_eq!(plan.candidates()[0].provider().as_str(), "alpha");
+        }
+        let forced = RoutingContext {
+            required_provider: Some(retired.clone()),
+            ..Default::default()
+        };
+        assert!(matches!(
+            snapshot.plan(&model, &super::operation(), scope.clone(), &forced),
+            Err(RoutingError::NoCapableProvider { .. })
+        ));
+        assert!(matches!(
+            snapshot.plan_provider_endpoint(&retired, None, &super::operation(), scope, &forced),
+            Err(RoutingError::NoCapableProviderEndpoint { .. })
+        ));
+    }
+}
+
 #[test]
 fn routing_plans_share_frozen_pricing_after_a_new_snapshot_is_published() {
     use gateway_core::{metering::PricingOverrides, runtime::RuntimeSnapshotHandle};
@@ -238,6 +395,12 @@ fn discovery_catalog_should_not_reject_an_unlisted_model() {
     );
     let snapshot = block_on(compiler.compile()).expect("compile discovery catalog");
     let provider = ProviderKind::new("alpha").expect("provider");
+    let snapshot = snapshot.with_account_directory(Arc::new(
+        gateway_core::routing::RuntimeAccountDirectory::new(BTreeMap::from([(
+            gateway_core::account::ProviderAccountId::new("acct_discovery").expect("account"),
+            gateway_core::routing::RuntimeAccount::new(provider.clone(), Default::default()),
+        )])),
+    ));
     let model = PublicModelId::new("unknown-upstream-model").expect("model");
     assert!(snapshot.contains_public_model_for_provider(&model, &provider));
     snapshot
@@ -313,6 +476,68 @@ fn compiler_retries_when_provider_publishes_catalog_during_compilation() {
     );
 }
 
+#[test]
+fn catalog_stability_retry_reuses_and_retains_extensions_for_the_same_revision() {
+    let catalog = Arc::new(PublishingCatalog {
+        generation: AtomicU64::new(0),
+        queries: AtomicUsize::new(0),
+    });
+    let drops = Arc::new(AtomicUsize::new(0));
+    let extensions = Arc::new(CountingExtensionPreparation {
+        prepares: AtomicUsize::new(0),
+        drops: Arc::clone(&drops),
+    });
+    let compiler = RuntimeSnapshotCompiler::new(
+        Arc::new(TestSnapshotStore::new(Ok(facts(3, 3)))),
+        catalog.clone(),
+    )
+    .with_extensions(extensions.clone());
+
+    let snapshot = block_on(compiler.compile()).expect("stable catalog snapshot");
+
+    assert_eq!(catalog.queries.load(Ordering::SeqCst), 2);
+    assert_eq!(
+        extensions.prepares.load(Ordering::SeqCst),
+        1,
+        "catalog generation retry must not prepare a second extension set"
+    );
+    assert_eq!(snapshot.extensions().unwrap().id().as_str(), "prepared-1");
+    assert_eq!(drops.load(Ordering::SeqCst), 0);
+    drop(snapshot);
+    assert_eq!(drops.load(Ordering::SeqCst), 1);
+}
+
+#[test]
+fn catalog_stability_retry_reprepares_extensions_after_revision_change() {
+    let catalog = Arc::new(PublishingCatalog {
+        generation: AtomicU64::new(0),
+        queries: AtomicUsize::new(0),
+    });
+    let drops = Arc::new(AtomicUsize::new(0));
+    let extensions = Arc::new(CountingExtensionPreparation {
+        prepares: AtomicUsize::new(0),
+        drops: Arc::clone(&drops),
+    });
+    let compiler = RuntimeSnapshotCompiler::new(
+        Arc::new(SequencedSnapshotStore {
+            facts: vec![facts(1, 1), facts(2, 2)],
+            loads: AtomicUsize::new(0),
+            current_revision: revision(2),
+        }),
+        catalog,
+    )
+    .with_extensions(extensions.clone());
+
+    let snapshot = block_on(compiler.compile()).expect("new revision snapshot");
+
+    assert_eq!(snapshot.revision(), revision(2));
+    assert_eq!(snapshot.extensions().unwrap().id().as_str(), "prepared-2");
+    assert_eq!(extensions.prepares.load(Ordering::SeqCst), 2);
+    assert_eq!(drops.load(Ordering::SeqCst), 1);
+    drop(snapshot);
+    assert_eq!(drops.load(Ordering::SeqCst), 2);
+}
+
 #[test]
 fn compiler_should_freeze_valid_client_min_versions() {
     let store = Arc::new(TestSnapshotStore::new(Ok(facts_with_min_versions(
diff --git a/backend/crates/gateway-core/tests/runtime/extensions.rs b/backend/crates/gateway-core/tests/runtime/extensions.rs
new file mode 100644
index 000000000..eb9b79044
--- /dev/null
+++ b/backend/crates/gateway-core/tests/runtime/extensions.rs
@@ -0,0 +1,111 @@
+use std::sync::{
+    Arc,
+    atomic::{AtomicBool, AtomicUsize, Ordering},
+};
+
+use gateway_core::runtime::{
+    RuntimeSnapshotHandle,
+    extensions::{ExtensionSetId, ExtensionSetLease, ExtensionSetReference},
+};
+
+struct Lease {
+    ready: Arc<AtomicBool>,
+    dropped: Arc<AtomicUsize>,
+}
+impl ExtensionSetLease for Lease {
+    fn is_ready(&self) -> bool {
+        self.ready.load(Ordering::SeqCst)
+    }
+}
+impl Drop for Lease {
+    fn drop(&mut self) {
+        self.dropped.fetch_add(1, Ordering::SeqCst);
+    }
+}
+
+#[test]
+fn publication_holds_the_generation_until_its_last_inflight_snapshot_is_released() {
+    let dropped = Arc::new(AtomicUsize::new(0));
+    let lease = Arc::new(Lease {
+        ready: Arc::new(AtomicBool::new(true)),
+        dropped: Arc::clone(&dropped),
+    });
+    let reference =
+        ExtensionSetReference::new(ExtensionSetId::new("generation-one".into()).unwrap(), lease);
+    let handle =
+        RuntimeSnapshotHandle::new(super::empty_snapshot(1).with_extensions(Some(reference)));
+    let inflight = handle.acquire().unwrap();
+    handle.publish(super::empty_snapshot(2));
+    assert_eq!(
+        inflight.extensions().unwrap().id().as_str(),
+        "generation-one"
+    );
+    assert!(handle.acquire().unwrap().extensions().is_none());
+    assert_eq!(dropped.load(Ordering::SeqCst), 0);
+    drop(inflight);
+    assert_eq!(dropped.load(Ordering::SeqCst), 1);
+}
+
+#[test]
+fn failed_generation_blocks_new_requests_without_destroying_an_inflight_reference() {
+    let dropped = Arc::new(AtomicUsize::new(0));
+    let ready = Arc::new(AtomicBool::new(true));
+    let lease = Arc::new(Lease {
+        ready: Arc::clone(&ready),
+        dropped: Arc::clone(&dropped),
+    });
+    let handle = RuntimeSnapshotHandle::new(super::empty_snapshot(1).with_extensions(Some(
+        ExtensionSetReference::new(ExtensionSetId::new("generation-one".into()).unwrap(), lease),
+    )));
+    let inflight = handle.acquire().unwrap();
+    ready.store(false, Ordering::SeqCst);
+    assert!(handle.acquire().is_err());
+    let diagnostic = handle
+        .snapshot_for_diagnostics()
+        .expect("unready publication remains observable to the control plane");
+    assert_eq!(diagnostic.revision().get(), 1);
+    assert_eq!(
+        diagnostic.extensions().unwrap().id().as_str(),
+        "generation-one"
+    );
+    drop(diagnostic);
+    assert_eq!(
+        inflight.extensions().unwrap().id().as_str(),
+        "generation-one"
+    );
+    handle.suspend();
+    assert_eq!(dropped.load(Ordering::SeqCst), 0);
+    drop(inflight);
+    assert_eq!(dropped.load(Ordering::SeqCst), 1);
+}
+
+#[test]
+fn an_isolated_extension_fault_keeps_new_requests_and_host_health_available() {
+    use gateway_core::health::{HealthProbe, HealthState};
+    struct IsolatedFault;
+    impl ExtensionSetLease for IsolatedFault {
+        fn is_ready(&self) -> bool {
+            false
+        }
+        fn can_serve(&self) -> bool {
+            true
+        }
+    }
+    let reference = ExtensionSetReference::new(
+        ExtensionSetId::new("isolated-fault".into()).unwrap(),
+        Arc::new(IsolatedFault),
+    );
+    assert!(!reference.is_ready());
+    let handle =
+        RuntimeSnapshotHandle::new(super::empty_snapshot(1).with_extensions(Some(reference)));
+    assert!(handle.acquire().is_ok());
+    assert!(matches!(
+        futures::executor::block_on(handle.check()),
+        HealthState::Healthy
+    ));
+    handle.suspend();
+    assert!(
+        handle.acquire().is_err(),
+        "unconfirmed host configuration still fails closed"
+    );
+}
diff --git a/backend/crates/gateway-core/tests/runtime/mod.rs b/backend/crates/gateway-core/tests/runtime/mod.rs
index a24ad5797..73827728b 100644
--- a/backend/crates/gateway-core/tests/runtime/mod.rs
+++ b/backend/crates/gateway-core/tests/runtime/mod.rs
@@ -1,4 +1,5 @@
 use std::collections::BTreeMap;
+mod extensions;
 use std::num::NonZeroU32;
 use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
 use std::sync::{Arc, Mutex};
@@ -187,6 +188,72 @@ fn publisher_should_suspend_but_still_notify_after_committed_refresh_failure() {
     );
 }
 
+#[test]
+fn deferred_commit_during_refresh_should_retry_the_latest_revision_without_reentry() {
+    block_on(async {
+        let (release, gate) = oneshot::channel();
+        let store = Arc::new(TestSnapshotStore::new(Ok(facts(1, 1))));
+        *store.next_load.lock().expect("load gate lock") = Some(gate);
+        let handle = RuntimeSnapshotHandle::default();
+        let subscriptions = Arc::new(TestSnapshotSubscriptions::default());
+        let publisher = RuntimeSnapshotPublisher::new(
+            Arc::new(compiler(store.clone())),
+            handle.clone(),
+            subscriptions.clone(),
+        );
+
+        let mut refresh = Box::pin(publisher.refresh());
+        assert!(futures::poll!(refresh.as_mut()).is_pending());
+        *store.facts.lock().expect("facts lock") = Ok(facts(2, 2));
+        *store.current_revision.lock().expect("revision lock") = Ok(revision(2));
+        publisher.publish_committed_deferred(revision(2)).await;
+        release
+            .send(Ok(facts(1, 1)))
+            .expect("release initial facts read");
+
+        assert_eq!(refresh.await.expect("coalesced refresh"), revision(2));
+        assert_eq!(store.loads.load(Ordering::SeqCst), 2);
+        assert_eq!(handle.revision(), Some(revision(2)));
+        assert_eq!(
+            *subscriptions.published.lock().expect("published lock"),
+            vec![revision(2)],
+        );
+    });
+}
+
+#[test]
+fn deferred_commit_at_refresh_completion_should_not_lose_the_next_publication() {
+    block_on(async {
+        let (release, gate) = oneshot::channel();
+        let store = Arc::new(TestSnapshotStore::new(Ok(facts(2, 2))));
+        let handle = RuntimeSnapshotHandle::default();
+        let subscriptions = Arc::new(TestSnapshotSubscriptions {
+            next_publish: Mutex::new(Some(gate)),
+            ..TestSnapshotSubscriptions::default()
+        });
+        let publisher = RuntimeSnapshotPublisher::new(
+            Arc::new(compiler(store.clone())),
+            handle.clone(),
+            subscriptions.clone(),
+        );
+
+        let mut first = publisher.publish_committed_deferred(revision(2));
+        assert!(futures::poll!(first.as_mut()).is_pending());
+        assert_eq!(handle.revision(), Some(revision(2)));
+        *store.facts.lock().expect("facts lock") = Ok(facts(3, 3));
+        *store.current_revision.lock().expect("revision lock") = Ok(revision(3));
+        publisher.publish_committed_deferred(revision(3)).await;
+        release.send(()).expect("release revision notification");
+        first.await;
+
+        assert_eq!(handle.revision(), Some(revision(3)));
+        assert_eq!(
+            *subscriptions.published.lock().expect("published lock"),
+            vec![revision(2), revision(3)],
+        );
+    });
+}
+
 #[test]
 fn snapshot_ports_and_control_should_remain_object_safe() {
     fn accept_store(_: &dyn SnapshotStorePort) {}
diff --git a/backend/crates/gateway-host/Cargo.toml b/backend/crates/gateway-host/Cargo.toml
index 0fcccf3f4..7312ad5c0 100644
--- a/backend/crates/gateway-host/Cargo.toml
+++ b/backend/crates/gateway-host/Cargo.toml
@@ -9,6 +9,8 @@ autotests = false
 
 [dependencies]
 async-trait = "0.1.89"
+base64 = "0.23.0"
+bytes = "1.11.1"
 axum = { version = "0.8.9", default-features = false, features = ["http1", "tokio"] }
 chrono = { version = "0.4.45", features = ["clock", "serde"] }
 config = { version = "0.15.23", default-features = false, features = ["yaml"] }
@@ -17,16 +19,27 @@ futures = "0.3.32"
 gateway-admin = { path = "../gateway-admin" }
 gateway-core = { path = "../gateway-core" }
 hex = "0.4.3"
+http = "1.4.0"
+http-body-util = "0.1.3"
+hyper = { version = "=1.11.1", default-features = false }
+hyper-rustls = { version = "=0.27.7", default-features = false, features = ["http1", "http2", "tls12"] }
+hyper-util = { version = "0.1.20", features = ["client-legacy", "client-proxy", "http1", "http2", "tokio"] }
+ipnet = "2.11.0"
+percent-encoding = "2.3.2"
 reqwest = { version = "=0.12.28", default-features = false, features = ["json", "stream", "rustls-tls-native-roots", "socks"] }
+rustls = { version = "=0.23.45", default-features = false, features = ["aws_lc_rs", "std", "tls12"] }
+rustls-native-certs = "=0.8.3"
 scraper = "0.27.0"
 semver = "1.0.27"
+secrecy = "0.10.3"
 serde = { version = "1.0.228", features = ["derive"] }
 serde_ignored = "0.1.14"
 serde_json = "1.0.150"
 sha2 = "0.11.0"
 tar = "0.4.44"
 thiserror = "2.0.18"
-tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt", "signal", "time", "sync", "net"] }
+tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt", "signal", "time", "sync", "net", "process", "io-util"] }
+tower-service = "0.3.3"
 tracing = "0.1.44"
 tracing-appender = "0.2.5"
 tracing-subscriber = { version = "0.3.23", features = ["env-filter", "json"] }
@@ -36,10 +49,18 @@ filetime = "0.2.27"
 tempfile = "3.27.0"
 tokio = { version = "1.52.3", default-features = false, features = ["rt-multi-thread", "test-util"] }
 wiremock = "0.6.5"
+tokio-rustls = { version = "=0.26.4", default-features = false }
 
 [[test]]
 name = "main"
 path = "tests/main.rs"
 
+[[bin]]
+name = "gateway-host-process-worker"
+path = "tests/support/process_worker.rs"
+test = false
+bench = false
+doc = false
+
 [lints]
 workspace = true
diff --git a/backend/crates/gateway-host/src/command_line.rs b/backend/crates/gateway-host/src/command_line.rs
new file mode 100644
index 000000000..312e0221d
--- /dev/null
+++ b/backend/crates/gateway-host/src/command_line.rs
@@ -0,0 +1,19 @@
+//! CLI 不进入 HTTP serve，也必须接收终止信号；资源退出时停止监听任务。
+
+use gateway_core::lifecycle::CancellationToken;
+
+pub(crate) struct SignalGuard(tokio::task::JoinHandle<()>);
+
+impl SignalGuard {
+    pub(crate) fn start(cancellation: CancellationToken) -> Self {
+        Self(tokio::spawn(async move {
+            crate::serve::wait_for_shutdown(&cancellation).await;
+        }))
+    }
+}
+
+impl Drop for SignalGuard {
+    fn drop(&mut self) {
+        self.0.abort();
+    }
+}
diff --git a/backend/crates/gateway-host/src/lib.rs b/backend/crates/gateway-host/src/lib.rs
index 20291b645..28a2afb57 100644
--- a/backend/crates/gateway-host/src/lib.rs
+++ b/backend/crates/gateway-host/src/lib.rs
@@ -1,9 +1,14 @@
 //! 网关进程与操作系统能力：配置发现、日志、任务、自更新与 serve/drain。
 
 pub mod client_distribution;
+mod command_line;
 pub mod config;
 mod logging;
+pub mod official_plugins;
+pub mod outbound;
+pub mod plugin_distribution;
 pub mod pricing;
+pub mod process;
 pub mod proxy_probe;
 pub mod serve;
 pub mod system_update;
@@ -13,7 +18,8 @@ use std::sync::Arc;
 
 use axum::Router;
 use gateway_admin::ports::{
-    client_distribution::ClientDistributionResolver, system::SystemOperations,
+    client_distribution::ClientDistributionResolver, plugin_release::OfficialPluginReleaseFiles,
+    system::SystemOperations,
 };
 use gateway_core::health::{HealthProbe, WorkerHealthSource};
 use gateway_core::lifecycle::CancellationToken;
@@ -37,10 +43,18 @@ pub struct HostBundle {
     workers: WorkerSupervisor,
     system: Arc<ProcessSystemOperations>,
     client_distribution: Arc<RgAdguardClientDistribution>,
+    official_plugins: Arc<official_plugins::FileOfficialPluginRelease>,
+    command_signal: Option<command_line::SignalGuard>,
 }
 
 /// 在启动其他包之前初始化进程级能力。
 pub async fn initialize(config: HostConfig) -> Result<HostBundle, HostError> {
+    let official_plugins = Arc::new(official_plugins::FileOfficialPluginRelease::new(
+        config
+            .system_update
+            .official_plugins_dir()
+            .map_err(|_| HostError::OfficialPluginRelease)?,
+    ));
     let log_guard = initialize_logging(&config.logging)?;
     let cancellation = CancellationToken::new();
     let connections = Arc::new(ConnectionTracker::new(cancellation.clone()));
@@ -58,9 +72,19 @@ pub async fn initialize(config: HostConfig) -> Result<HostBundle, HostError> {
         workers,
         system,
         client_distribution,
+        official_plugins,
+        command_signal: None,
     })
 }
 
+/// CLI 的 stdout/stderr 属于命令结果；宿主诊断只保留已配置的文件日志。
+pub async fn initialize_command_line(mut config: HostConfig) -> Result<HostBundle, HostError> {
+    config.logging.stdout = false;
+    let mut host = initialize(config).await?;
+    host.command_signal = Some(command_line::SignalGuard::start(host.cancellation()));
+    Ok(host)
+}
+
 impl HostBundle {
     /// 向启动控制台报告一个组装阶段已就绪。
     pub fn report_startup_ready(&self, service: &'static str) {
@@ -83,6 +107,23 @@ impl HostBundle {
         self.client_distribution.clone()
     }
 
+    /// 返回与当前可执行文件一同部署的只读官方插件发行目录。
+    #[must_use]
+    pub fn official_plugin_release_files(&self) -> Arc<dyn OfficialPluginReleaseFiles> {
+        self.official_plugins.clone()
+    }
+
+    /// 身份来自构建脚本写入二进制的常量，不采信运行时配置或环境覆盖。
+    #[must_use]
+    pub fn official_plugin_release_identity(
+        &self,
+    ) -> gateway_admin::model::plugins::official::OfficialPluginReleaseIdentity {
+        gateway_admin::model::plugins::official::OfficialPluginReleaseIdentity {
+            gateway_version: env!("CPR_VERSION").to_owned(),
+            gateway_git_sha: env!("CPR_GIT_SHA").to_owned(),
+        }
+    }
+
     #[must_use]
     pub fn proxy_probe<E>(
         &self,
@@ -134,6 +175,14 @@ impl HostBundle {
         self.workers
             .shutdown(self.config.worker_shutdown_timeout())
             .await;
+        match &result {
+            Ok(()) => {
+                tracing::info!(target: "gateway_shutdown", pid = std::process::id(), "HTTP 服务与后台任务已停止")
+            }
+            Err(error) => {
+                tracing::error!(target: "gateway_shutdown", pid = std::process::id(), %error, "HTTP 服务异常停止，后台任务已清理")
+            }
+        }
         result?;
         Ok(())
     }
@@ -147,4 +196,6 @@ pub enum HostError {
     Workers(#[from] workers::WorkerStartError),
     #[error(transparent)]
     Serve(#[from] serve::ServeError),
+    #[error("官方插件发行目录不可用")]
+    OfficialPluginRelease,
 }
diff --git a/backend/crates/gateway-host/src/logging/mod.rs b/backend/crates/gateway-host/src/logging/mod.rs
index cf5018703..9a8b58fc3 100644
--- a/backend/crates/gateway-host/src/logging/mod.rs
+++ b/backend/crates/gateway-host/src/logging/mod.rs
@@ -197,7 +197,7 @@ fn stdout_filter_directive(directive: &str, persistent_log_enabled: bool) -> Str
     if !persistent_log_enabled {
         format!("{directive},{OAUTH_RECOVERY_LOG_TARGET}=off,{REQUEST_DUMP_LOG_TARGET}=off")
     } else {
-        "off,gateway_startup=info".to_owned()
+        "off,gateway_startup=info,gateway_shutdown=info".to_owned()
     }
 }
 
diff --git a/backend/crates/gateway-host/src/official_plugins.rs b/backend/crates/gateway-host/src/official_plugins.rs
new file mode 100644
index 000000000..238c9ba4b
--- /dev/null
+++ b/backend/crates/gateway-host/src/official_plugins.rs
@@ -0,0 +1,136 @@
+//! 随宿主发行的官方插件文件只读入口。
+
+use std::{
+    fs,
+    io::Read as _,
+    path::{Component, Path, PathBuf},
+    sync::Arc,
+};
+
+use async_trait::async_trait;
+use gateway_admin::ports::plugin_release::{
+    OfficialPluginReleaseFiles, OfficialPluginReleaseReadError, OfficialPluginReleaseReadErrorKind,
+};
+
+const MANIFEST_FILE_NAME: &str = "plugin-release-manifest.json";
+const MAXIMUM_MANIFEST_BYTES: usize = 256 * 1024;
+const MAXIMUM_ARTIFACT_BYTES: usize = 32 * 1024 * 1024;
+
+/// 目录与宿主二进制一同部署和替换；`sealed` 本身不被当作密码学签名。
+pub struct FileOfficialPluginRelease {
+    directory: PathBuf,
+}
+
+impl FileOfficialPluginRelease {
+    #[must_use]
+    pub fn new(directory: PathBuf) -> Self {
+        Self { directory }
+    }
+}
+
+#[async_trait]
+impl OfficialPluginReleaseFiles for FileOfficialPluginRelease {
+    async fn manifest(&self) -> Result<Option<Arc<[u8]>>, OfficialPluginReleaseReadError> {
+        let directory = self.directory.clone();
+        tokio::task::spawn_blocking(move || {
+            let Some(path) = release_file(&directory, MANIFEST_FILE_NAME, true)? else {
+                return Ok(None);
+            };
+            read_bounded(&path, MAXIMUM_MANIFEST_BYTES).map(Some)
+        })
+        .await
+        .map_err(|_| unavailable())?
+    }
+
+    async fn artifact(&self, file_name: &str) -> Result<Arc<[u8]>, OfficialPluginReleaseReadError> {
+        if !valid_file_name(file_name) {
+            return Err(invalid());
+        }
+        let directory = self.directory.clone();
+        let file_name = file_name.to_owned();
+        tokio::task::spawn_blocking(move || {
+            let path = release_file(&directory, &file_name, false)?.ok_or_else(not_found)?;
+            read_bounded(&path, MAXIMUM_ARTIFACT_BYTES)
+        })
+        .await
+        .map_err(|_| unavailable())?
+    }
+}
+
+fn release_file(
+    directory: &Path,
+    file_name: &str,
+    manifest: bool,
+) -> Result<Option<PathBuf>, OfficialPluginReleaseReadError> {
+    let Some(parent) = directory.parent() else {
+        return Err(invalid());
+    };
+    let parent_metadata = match fs::symlink_metadata(parent) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound && manifest => return Ok(None),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Err(not_found()),
+        Err(_) => return Err(unavailable()),
+    };
+    if parent_metadata.file_type().is_symlink() || !parent_metadata.is_dir() {
+        return Err(invalid());
+    }
+    let directory_metadata = match fs::symlink_metadata(directory) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound && manifest => return Ok(None),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Err(not_found()),
+        Err(_) => return Err(unavailable()),
+    };
+    if directory_metadata.file_type().is_symlink() || !directory_metadata.is_dir() {
+        return Err(invalid());
+    }
+    let path = directory.join(file_name);
+    let metadata = match fs::symlink_metadata(&path) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound && manifest => return Ok(None),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Err(not_found()),
+        Err(_) => return Err(unavailable()),
+    };
+    if metadata.file_type().is_symlink() || !metadata.is_file() {
+        return Err(invalid());
+    }
+    Ok(Some(path))
+}
+
+fn read_bounded(path: &Path, maximum: usize) -> Result<Arc<[u8]>, OfficialPluginReleaseReadError> {
+    let file = fs::File::open(path).map_err(|_| unavailable())?;
+    let metadata = file.metadata().map_err(|_| unavailable())?;
+    if !metadata.is_file() || metadata.len() > u64::try_from(maximum).unwrap_or(u64::MAX) {
+        return Err(invalid());
+    }
+    let limit = u64::try_from(maximum).unwrap_or(u64::MAX).saturating_add(1);
+    let mut bytes = Vec::new();
+    file.take(limit)
+        .read_to_end(&mut bytes)
+        .map_err(|_| unavailable())?;
+    if bytes.len() > maximum {
+        return Err(invalid());
+    }
+    Ok(bytes.into())
+}
+
+fn valid_file_name(value: &str) -> bool {
+    !value.is_empty()
+        && Path::new(value).components().count() == 1
+        && matches!(
+            Path::new(value).components().next(),
+            Some(Component::Normal(_))
+        )
+        && Path::new(value).file_name().and_then(|name| name.to_str()) == Some(value)
+}
+
+fn invalid() -> OfficialPluginReleaseReadError {
+    OfficialPluginReleaseReadError::new(OfficialPluginReleaseReadErrorKind::Invalid)
+}
+
+fn not_found() -> OfficialPluginReleaseReadError {
+    OfficialPluginReleaseReadError::new(OfficialPluginReleaseReadErrorKind::NotFound)
+}
+
+fn unavailable() -> OfficialPluginReleaseReadError {
+    OfficialPluginReleaseReadError::new(OfficialPluginReleaseReadErrorKind::Unavailable)
+}
diff --git a/backend/crates/gateway-host/src/outbound/connector.rs b/backend/crates/gateway-host/src/outbound/connector.rs
new file mode 100644
index 000000000..bfe85d72d
--- /dev/null
+++ b/backend/crates/gateway-host/src/outbound/connector.rs
@@ -0,0 +1,240 @@
+use std::{
+    net::SocketAddr,
+    pin::Pin,
+    sync::Arc,
+    task::{Context, Poll},
+    time::Duration,
+};
+
+use base64::Engine as _;
+use futures::future::BoxFuture;
+use gateway_core::account::OutboundProxy;
+use http::{HeaderValue, Uri};
+use hyper_rustls::{HttpsConnector, HttpsConnectorBuilder, MaybeHttpsStream};
+use hyper_util::{
+    client::legacy::connect::{
+        Connected, HttpConnector,
+        proxy::{SocksV5, Tunnel},
+    },
+    rt::TokioIo,
+};
+use rustls::{ClientConfig, RootCertStore, pki_types::CertificateDer};
+use tokio::net::TcpStream;
+use tower_service::Service;
+
+use super::HttpError;
+
+type Socket = TokioIo<TcpStream>;
+type ProxySocket = MaybeHttpsStream<Socket>;
+
+pub(super) struct Connection {
+    socket: ProxySocket,
+    forward_proxy: bool,
+}
+
+impl hyper_util::client::legacy::connect::Connection for Connection {
+    fn connected(&self) -> Connected {
+        self.socket.connected().proxy(self.forward_proxy)
+    }
+}
+
+impl hyper::rt::Read for Connection {
+    fn poll_read(
+        mut self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buffer: hyper::rt::ReadBufCursor<'_>,
+    ) -> Poll<std::io::Result<()>> {
+        Pin::new(&mut self.socket).poll_read(cx, buffer)
+    }
+}
+
+impl hyper::rt::Write for Connection {
+    fn poll_write(
+        mut self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buffer: &[u8],
+    ) -> Poll<std::io::Result<usize>> {
+        Pin::new(&mut self.socket).poll_write(cx, buffer)
+    }
+    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
+        Pin::new(&mut self.socket).poll_flush(cx)
+    }
+    fn poll_shutdown(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
+        Pin::new(&mut self.socket).poll_shutdown(cx)
+    }
+    fn is_write_vectored(&self) -> bool {
+        self.socket.is_write_vectored()
+    }
+    fn poll_write_vectored(
+        mut self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buffers: &[std::io::IoSlice<'_>],
+    ) -> Poll<std::io::Result<usize>> {
+        Pin::new(&mut self.socket).poll_write_vectored(cx, buffers)
+    }
+}
+
+#[derive(Clone)]
+pub(super) struct Connector {
+    addresses: Arc<[SocketAddr]>,
+    proxy: Option<OutboundProxy>,
+    proxy_tls: Arc<ClientConfig>,
+}
+
+impl Connector {
+    pub(super) fn new(
+        addresses: Vec<SocketAddr>,
+        proxy: Option<OutboundProxy>,
+        tls: Arc<ClientConfig>,
+    ) -> Self {
+        Self {
+            addresses: addresses.into(),
+            proxy,
+            proxy_tls: tls,
+        }
+    }
+
+    async fn connect(self, destination: Uri) -> Result<ProxySocket, HttpError> {
+        let Some(proxy) = self.proxy else {
+            return TcpStream::connect(self.addresses.as_ref())
+                .await
+                .map(|stream| MaybeHttpsStream::Http(TokioIo::new(stream)))
+                .map_err(|_| HttpError::invalid("connect"));
+        };
+        let proxy_url =
+            reqwest::Url::parse(proxy.expose_url()).map_err(|_| HttpError::invalid("proxy"))?;
+        let proxy_uri: Uri = proxy
+            .endpoint()
+            .parse()
+            .map_err(|_| HttpError::invalid("proxy"))?;
+        let credentials = proxy_credentials(&proxy_url)?;
+        let mut http = HttpConnector::new();
+        http.enforce_http(false);
+        http.set_connect_timeout(Some(Duration::from_secs(10)));
+        if matches!(proxy_url.scheme(), "http" | "https") {
+            let mut connector = https(http, self.proxy_tls.as_ref().clone(), false);
+            if destination.scheme_str() == Some("http") {
+                return connector
+                    .call(proxy_uri)
+                    .await
+                    .map_err(|_| HttpError::invalid("proxy connect"));
+            }
+            let mut tunnel = Tunnel::new(proxy_uri, connector);
+            if let Some((username, password)) = credentials {
+                tunnel = tunnel.with_auth(basic_auth(&username, &password)?);
+            }
+            for address in self.addresses.iter() {
+                let pinned = address_uri(destination.scheme_str().unwrap_or("https"), *address)?;
+                if let Ok(stream) = tunnel.call(pinned).await {
+                    return Ok(stream);
+                }
+            }
+        } else {
+            let mut socks = SocksV5::new(proxy_uri, http);
+            if let Some((username, password)) = credentials {
+                socks = socks.with_auth(username, password);
+            }
+            for address in self.addresses.iter() {
+                let pinned = address_uri(destination.scheme_str().unwrap_or("http"), *address)?;
+                if let Ok(stream) = socks.call(pinned).await {
+                    return Ok(MaybeHttpsStream::Http(stream));
+                }
+            }
+        }
+        Err(HttpError::invalid("proxy tunnel"))
+    }
+}
+
+impl Service<Uri> for Connector {
+    type Response = Connection;
+    type Error = HttpError;
+    type Future = BoxFuture<'static, Result<Self::Response, Self::Error>>;
+
+    fn poll_ready(&mut self, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
+        Poll::Ready(Ok(()))
+    }
+
+    fn call(&mut self, uri: Uri) -> Self::Future {
+        let connector = self.clone();
+        let forward_proxy = uri.scheme_str() == Some("http")
+            && connector
+                .proxy
+                .as_ref()
+                .is_some_and(|proxy| proxy.expose_url().starts_with("http"));
+        Box::pin(async move {
+            let socket = tokio::time::timeout(Duration::from_secs(10), connector.connect(uri))
+                .await
+                .map_err(|_| HttpError::invalid("connect timeout"))??;
+            Ok(Connection {
+                socket,
+                forward_proxy,
+            })
+        })
+    }
+}
+
+pub(super) fn https<C>(connector: C, tls: ClientConfig, http2: bool) -> HttpsConnector<C> {
+    let builder = HttpsConnectorBuilder::new()
+        .with_tls_config(tls)
+        .https_or_http()
+        .enable_http1();
+    if http2 {
+        builder.enable_http2().wrap_connector(connector)
+    } else {
+        builder.wrap_connector(connector)
+    }
+}
+
+pub(super) fn address_uri(scheme: &str, address: SocketAddr) -> Result<Uri, HttpError> {
+    format!("{scheme}://{address}")
+        .parse()
+        .map_err(|_| HttpError::invalid("address URI"))
+}
+
+pub(super) fn basic_auth(username: &str, password: &str) -> Result<HeaderValue, HttpError> {
+    let value = base64::engine::general_purpose::STANDARD.encode(format!("{username}:{password}"));
+    let mut value = HeaderValue::from_str(&format!("Basic {value}"))
+        .map_err(|_| HttpError::invalid("proxy credentials"))?;
+    value.set_sensitive(true);
+    Ok(value)
+}
+
+pub(super) fn proxy_credentials(
+    proxy: &reqwest::Url,
+) -> Result<Option<(String, String)>, HttpError> {
+    if proxy.username().is_empty() && proxy.password().is_none() {
+        return Ok(None);
+    }
+    let decode = |value: &str| {
+        percent_encoding::percent_decode_str(value)
+            .decode_utf8()
+            .map(|value| value.into_owned())
+            .map_err(|_| HttpError::invalid("proxy credentials"))
+    };
+    Ok(Some((
+        decode(proxy.username())?,
+        decode(proxy.password().unwrap_or(""))?,
+    )))
+}
+
+pub(super) fn tls(additional_roots: Vec<Vec<u8>>) -> Result<Arc<ClientConfig>, HttpError> {
+    let mut roots = RootCertStore::empty();
+    let certificates = rustls_native_certs::load_native_certs();
+    roots.add_parsable_certificates(certificates.certs);
+    for certificate in additional_roots {
+        roots
+            .add(CertificateDer::from(certificate))
+            .map_err(|_| HttpError::invalid("root certificate"))?;
+    }
+    if roots.is_empty() {
+        return Err(HttpError::invalid("trust roots"));
+    }
+    let tls = ClientConfig::builder_with_provider(Arc::new(
+        rustls::crypto::aws_lc_rs::default_provider(),
+    ))
+    .with_safe_default_protocol_versions()
+    .map_err(|_| HttpError::invalid("TLS versions"))?
+    .with_root_certificates(roots)
+    .with_no_client_auth();
+    Ok(Arc::new(tls))
+}
diff --git a/backend/crates/gateway-host/src/outbound/http.rs b/backend/crates/gateway-host/src/outbound/http.rs
new file mode 100644
index 000000000..293e2505b
--- /dev/null
+++ b/backend/crates/gateway-host/src/outbound/http.rs
@@ -0,0 +1,361 @@
+use std::{
+    collections::HashMap,
+    sync::{Arc, Mutex},
+    time::Duration,
+};
+
+use bytes::Bytes;
+use gateway_core::{account::OutboundProxy, upstream::UpstreamSendState};
+use http_body_util::{BodyExt as _, Full};
+use hyper_util::{client::legacy::Client, rt::TokioExecutor};
+use reqwest::{
+    Method, Url,
+    header::{HeaderMap, HeaderName, HeaderValue},
+};
+use tokio::{
+    sync::{OwnedSemaphorePermit, Semaphore},
+    time::Instant,
+};
+
+use super::{
+    connector::{self, Connector},
+    network::{self, DnsResolver, NetworkPolicy, SystemResolver},
+};
+
+type ManagedClient = Client<hyper_rustls::HttpsConnector<Connector>, Full<Bytes>>;
+
+#[derive(Clone, PartialEq, Eq, Hash)]
+struct ClientKey {
+    origin: String,
+    addresses: Vec<std::net::SocketAddr>,
+    proxy: Option<OutboundProxy>,
+    scope: Option<String>,
+}
+
+pub struct HttpRequest {
+    pub method: String,
+    pub url: String,
+    pub headers: Vec<(String, Vec<u8>)>,
+    pub body: Vec<u8>,
+}
+
+pub struct HttpResponse {
+    pub status: u16,
+    pub headers: Vec<(String, Vec<u8>)>,
+    pub body: HttpBody,
+}
+
+pub struct HttpBody {
+    response: hyper::body::Incoming,
+    pending: Bytes,
+    received: usize,
+    deadline: Instant,
+    _permit: OwnedSemaphorePermit,
+}
+
+#[derive(Debug, thiserror::Error)]
+#[error("managed HTTP operation failed: {reason}")]
+pub struct HttpError {
+    reason: &'static str,
+    kind: HttpErrorKind,
+    pub send_state: UpstreamSendState,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum HttpErrorKind {
+    InvalidRequest,
+    AddressDenied,
+    Dns,
+    Timeout,
+    Transport,
+    Capacity,
+    Response,
+}
+
+impl HttpError {
+    pub const fn kind(&self) -> HttpErrorKind {
+        self.kind
+    }
+
+    /// 固定诊断分类，不包含网址、请求头、正文或底层错误中的凭据。
+    pub const fn reason(&self) -> &'static str {
+        self.reason
+    }
+
+    pub(super) fn invalid(reason: &'static str) -> Self {
+        Self {
+            reason,
+            kind: HttpErrorKind::InvalidRequest,
+            send_state: UpstreamSendState::NotSent,
+        }
+    }
+    pub(super) fn with_kind(mut self, kind: HttpErrorKind) -> Self {
+        self.kind = kind;
+        self
+    }
+
+    fn sent(reason: &'static str) -> Self {
+        Self {
+            reason,
+            kind: HttpErrorKind::Response,
+            send_state: UpstreamSendState::Sent,
+        }
+    }
+}
+
+pub struct HttpClient {
+    clients: Mutex<HashMap<ClientKey, ManagedClient>>,
+    requests: Arc<Semaphore>,
+    resolver: Arc<dyn DnsResolver>,
+    tls: Arc<rustls::ClientConfig>,
+}
+
+impl HttpClient {
+    pub fn new() -> Result<Self, HttpError> {
+        Self::with_root_certificates(vec![])
+    }
+
+    pub fn with_root_certificates(additional: Vec<Vec<u8>>) -> Result<Self, HttpError> {
+        Ok(Self {
+            clients: Mutex::new(HashMap::new()),
+            requests: Arc::new(Semaphore::new(128)),
+            resolver: Arc::new(SystemResolver),
+            tls: connector::tls(additional)?,
+        })
+    }
+
+    #[must_use]
+    pub fn with_resolver(mut self, resolver: Arc<dyn DnsResolver>) -> Self {
+        self.resolver = resolver;
+        self
+    }
+
+    fn client(&self, key: ClientKey) -> ManagedClient {
+        let mut clients = self
+            .clients
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if let Some(client) = clients.get(&key) {
+            return client.clone();
+        }
+        let connector = Connector::new(key.addresses.clone(), key.proxy.clone(), self.tls.clone());
+        let connector = connector::https(connector, self.tls.as_ref().clone(), true);
+        let client = Client::builder(TokioExecutor::new())
+            .pool_max_idle_per_host(4)
+            .http1_max_buf_size(64 * 1024)
+            .retry_canceled_requests(false)
+            .build(connector);
+        // 淘汰缓存不影响已借出的 Client 或在途 body。
+        if clients.len() >= 64 {
+            clients.clear();
+        }
+        clients.insert(key, client.clone());
+        client
+    }
+
+    pub async fn open(
+        &self,
+        request: HttpRequest,
+        proxy: Option<&OutboundProxy>,
+        network: &NetworkPolicy,
+        timeout: Duration,
+    ) -> Result<HttpResponse, HttpError> {
+        self.open_scoped(request, proxy, network, timeout, None)
+            .await
+    }
+
+    /// 为同一代理端点上的不同管理身份隔离连接池；scope 不得包含 secret。
+    pub async fn open_scoped(
+        &self,
+        request: HttpRequest,
+        proxy: Option<&OutboundProxy>,
+        network: &NetworkPolicy,
+        timeout: Duration,
+        scope: Option<&str>,
+    ) -> Result<HttpResponse, HttpError> {
+        if request.body.len() > 16 * 1024 * 1024
+            || request.headers.len() > 128
+            || timeout.is_zero()
+            || timeout > Duration::from_secs(120)
+            || scope.is_some_and(|scope| {
+                scope.is_empty() || scope.len() > 256 || scope.chars().any(char::is_control)
+            })
+        {
+            return Err(HttpError::invalid("request limits"));
+        }
+        let url = Url::parse(&request.url).map_err(|_| HttpError::invalid("URL"))?;
+        if !matches!(url.scheme(), "http" | "https")
+            || !url.username().is_empty()
+            || url.password().is_some()
+            || url.fragment().is_some()
+            || url.host_str().is_none()
+            || url.port_or_known_default().is_none_or(|port| port == 0)
+        {
+            return Err(HttpError::invalid("URL"));
+        }
+        let method = Method::from_bytes(request.method.as_bytes())
+            .map_err(|_| HttpError::invalid("method"))?;
+        if matches!(method, Method::CONNECT | Method::TRACE) {
+            return Err(HttpError::invalid("method"));
+        }
+        let mut headers = HeaderMap::new();
+        let mut header_bytes = 0;
+        for (name, value) in request.headers {
+            header_bytes += name.len() + value.len();
+            let name = HeaderName::from_bytes(name.as_bytes())
+                .map_err(|_| HttpError::invalid("header"))?;
+            if header_bytes > 32 * 1024
+                || matches!(
+                    name.as_str(),
+                    "host"
+                        | "connection"
+                        | "content-length"
+                        | "transfer-encoding"
+                        | "proxy-authorization"
+                        | "upgrade"
+                        | "te"
+                        | "trailer"
+                )
+            {
+                return Err(HttpError::invalid("header"));
+            }
+            headers.append(
+                name,
+                HeaderValue::from_bytes(&value).map_err(|_| HttpError::invalid("header"))?,
+            );
+        }
+        let permit = self
+            .requests
+            .clone()
+            .try_acquire_owned()
+            .map_err(|_| HttpError::invalid("capacity").with_kind(HttpErrorKind::Capacity))?;
+        let deadline = Instant::now() + timeout;
+        let addresses =
+            tokio::time::timeout_at(deadline, network::resolve(&self.resolver, &url, network))
+                .await
+                .map_err(|_| {
+                    HttpError::invalid("DNS deadline").with_kind(HttpErrorKind::Timeout)
+                })??;
+        let client = self.client(ClientKey {
+            origin: url.origin().ascii_serialization(),
+            addresses: addresses.clone(),
+            proxy: proxy.cloned(),
+            scope: scope.map(str::to_owned),
+        });
+        let mut uri: http::Uri = url
+            .as_str()
+            .parse()
+            .map_err(|_| HttpError::invalid("URL"))?;
+        let authority = uri
+            .authority()
+            .ok_or_else(|| HttpError::invalid("host"))?
+            .as_str();
+        headers.insert(
+            http::header::HOST,
+            HeaderValue::from_str(authority).map_err(|_| HttpError::invalid("host"))?,
+        );
+        if url.scheme() == "http"
+            && let Some(proxy) = proxy.filter(|proxy| proxy.expose_url().starts_with("http"))
+        {
+            // 正向代理接收数字地址的绝对 URI；Host 保留原始域名，禁止代理再次解析目标。
+            let address = addresses
+                .first()
+                .ok_or_else(|| HttpError::invalid("address"))?;
+            let mut parts = uri.into_parts();
+            parts.authority = Some(
+                address
+                    .to_string()
+                    .parse()
+                    .map_err(|_| HttpError::invalid("address"))?,
+            );
+            uri = http::Uri::from_parts(parts).map_err(|_| HttpError::invalid("URL"))?;
+            let proxy = Url::parse(proxy.expose_url()).map_err(|_| HttpError::invalid("proxy"))?;
+            if let Some((username, password)) = connector::proxy_credentials(&proxy)? {
+                headers.insert(
+                    http::header::PROXY_AUTHORIZATION,
+                    connector::basic_auth(&username, &password)?,
+                );
+            }
+        }
+        let mut outgoing = http::Request::new(Full::new(Bytes::from(request.body)));
+        *outgoing.method_mut() = method;
+        *outgoing.uri_mut() = uri;
+        *outgoing.headers_mut() = headers;
+        let response = tokio::time::timeout_at(deadline, client.request(outgoing))
+            .await
+            .map_err(|_| HttpError {
+                reason: "request deadline",
+                kind: HttpErrorKind::Timeout,
+                send_state: UpstreamSendState::Ambiguous,
+            })?
+            .map_err(|error| HttpError {
+                reason: "transport",
+                kind: HttpErrorKind::Transport,
+                send_state: if error.is_connect() {
+                    UpstreamSendState::NotSent
+                } else {
+                    UpstreamSendState::Ambiguous
+                },
+            })?;
+        let status = response.status().as_u16();
+        let headers: Vec<_> = response
+            .headers()
+            .iter()
+            .map(|(name, value)| (name.to_string(), value.as_bytes().to_vec()))
+            .collect();
+        if headers
+            .iter()
+            .map(|(name, value)| name.len() + value.len())
+            .sum::<usize>()
+            > 32 * 1024
+        {
+            return Err(HttpError::sent("response headers"));
+        }
+        Ok(HttpResponse {
+            status,
+            headers,
+            body: HttpBody {
+                response: response.into_body(),
+                pending: Bytes::new(),
+                received: 0,
+                deadline,
+                _permit: permit,
+            },
+        })
+    }
+}
+
+impl HttpBody {
+    pub async fn read(&mut self, maximum: usize) -> Result<Option<Bytes>, HttpError> {
+        if maximum == 0 || maximum > 64 * 1024 {
+            return Err(HttpError::sent("read size"));
+        }
+        loop {
+            // 已缓冲的数据和就绪帧也受同一期限约束，慢读者不能无限续用 HTTP 资源。
+            if Instant::now() >= self.deadline {
+                return Err(HttpError::sent("response deadline").with_kind(HttpErrorKind::Timeout));
+            }
+            if !self.pending.is_empty() {
+                return Ok(Some(self.pending.split_to(maximum.min(self.pending.len()))));
+            }
+            self.pending = match tokio::time::timeout_at(self.deadline, self.response.frame()).await
+            {
+                Ok(Some(Ok(frame))) => match frame.into_data() {
+                    Ok(chunk) => chunk,
+                    Err(_) => continue,
+                },
+                Ok(None) => return Ok(None),
+                Ok(Some(Err(_))) => return Err(HttpError::sent("response body")),
+                Err(_) => {
+                    return Err(
+                        HttpError::sent("response deadline").with_kind(HttpErrorKind::Timeout)
+                    );
+                }
+            };
+            self.received = self.received.saturating_add(self.pending.len());
+            if self.received > 32 * 1024 * 1024 {
+                return Err(HttpError::sent("response size"));
+            }
+        }
+    }
+}
diff --git a/backend/crates/gateway-host/src/outbound/mod.rs b/backend/crates/gateway-host/src/outbound/mod.rs
new file mode 100644
index 000000000..1d4993755
--- /dev/null
+++ b/backend/crates/gateway-host/src/outbound/mod.rs
@@ -0,0 +1,8 @@
+//! 受管 HTTP 资源；调用授权属于上层，Host 负责出站、容量、期限和流回收。
+
+mod connector;
+mod http;
+mod network;
+
+pub use http::{HttpBody, HttpClient, HttpError, HttpErrorKind, HttpRequest, HttpResponse};
+pub use network::{DnsResolver, NetworkPolicy};
diff --git a/backend/crates/gateway-host/src/outbound/network.rs b/backend/crates/gateway-host/src/outbound/network.rs
new file mode 100644
index 000000000..12327d7cb
--- /dev/null
+++ b/backend/crates/gateway-host/src/outbound/network.rs
@@ -0,0 +1,134 @@
+use std::{
+    net::{IpAddr, SocketAddr},
+    sync::Arc,
+};
+
+use futures::future::BoxFuture;
+use ipnet::IpNet;
+
+use super::{HttpError, HttpErrorKind};
+
+/// 默认仅允许公网；额外地址段来自明确授权，不由请求或 DNS 回应扩大。
+#[derive(Clone, Default)]
+pub struct NetworkPolicy {
+    additional: Vec<IpNet>,
+}
+
+impl NetworkPolicy {
+    pub fn new(networks: &[String]) -> Result<Self, HttpError> {
+        if networks.len() > 32 {
+            return Err(HttpError::invalid("network limits"));
+        }
+        let additional = networks
+            .iter()
+            .map(|network| {
+                network
+                    .parse()
+                    .map_err(|_| HttpError::invalid("network range"))
+            })
+            .collect::<Result<_, _>>()?;
+        Ok(Self { additional })
+    }
+
+    #[must_use]
+    pub fn permits(&self, address: IpAddr) -> bool {
+        let address = match address {
+            IpAddr::V6(address) => address
+                .to_ipv4_mapped()
+                .map_or(IpAddr::V6(address), IpAddr::V4),
+            other => other,
+        };
+        public_address(address)
+            || self
+                .additional
+                .iter()
+                .any(|network| network.contains(&address))
+    }
+}
+
+/// DNS 只产出候选地址；连接层只使用通过授权检查的地址，不再次解析目标域名。
+pub trait DnsResolver: Send + Sync {
+    fn resolve(
+        &self,
+        host: String,
+        port: u16,
+    ) -> BoxFuture<'static, std::io::Result<Vec<SocketAddr>>>;
+}
+
+pub(super) struct SystemResolver;
+
+impl DnsResolver for SystemResolver {
+    fn resolve(
+        &self,
+        host: String,
+        port: u16,
+    ) -> BoxFuture<'static, std::io::Result<Vec<SocketAddr>>> {
+        Box::pin(async move {
+            let addresses = tokio::net::lookup_host((host, port)).await?;
+            Ok(addresses.take(65).collect())
+        })
+    }
+}
+
+pub(super) async fn resolve(
+    resolver: &Arc<dyn DnsResolver>,
+    url: &reqwest::Url,
+    policy: &NetworkPolicy,
+) -> Result<Vec<SocketAddr>, HttpError> {
+    let host = url
+        .host_str()
+        .ok_or_else(|| HttpError::invalid("URL host"))?
+        .trim_matches(['[', ']']);
+    let port = url
+        .port_or_known_default()
+        .ok_or_else(|| HttpError::invalid("URL port"))?;
+    let mut addresses = if let Ok(ip) = host.parse() {
+        vec![SocketAddr::new(ip, port)]
+    } else {
+        resolver
+            .resolve(host.into(), port)
+            .await
+            .map_err(|_| HttpError::invalid("DNS resolution").with_kind(HttpErrorKind::Dns))?
+    };
+    if addresses.is_empty() || addresses.len() > 64 {
+        return Err(HttpError::invalid("DNS answer limits").with_kind(HttpErrorKind::Dns));
+    }
+    if addresses
+        .iter()
+        .any(|address| address.port() != port || !policy.permits(address.ip()))
+    {
+        return Err(HttpError::invalid("network address not authorized")
+            .with_kind(HttpErrorKind::AddressDenied));
+    }
+    addresses.sort();
+    addresses.dedup();
+    Ok(addresses)
+}
+
+fn public_address(address: IpAddr) -> bool {
+    match address {
+        IpAddr::V4(ip) => {
+            let [a, b, c, _] = ip.octets();
+            !ip.is_private()
+                && !ip.is_loopback()
+                && !ip.is_link_local()
+                && !ip.is_broadcast()
+                && !ip.is_documentation()
+                && a != 0
+                && a < 224
+                && !(a == 100 && (64..=127).contains(&b))
+                && !(a == 192 && b == 0 && c == 0)
+                && !(a == 192 && b == 88 && c == 99)
+                && !(a == 198 && (b == 18 || b == 19))
+        }
+        IpAddr::V6(ip) => {
+            let segments = ip.segments();
+            // 只默认开放全球单播；隧道、文档与协议专用地址均需显式授予。
+            segments[0] & 0xe000 == 0x2000
+                && !(segments[0] == 0x2001 && segments[1] < 0x0200)
+                && !(segments[0] == 0x2001 && segments[1] == 0x0db8)
+                && segments[0] != 0x2002
+                && !(segments[0] == 0x3fff && segments[1] < 0x1000)
+        }
+    }
+}
diff --git a/backend/crates/gateway-host/src/plugin_distribution/github.rs b/backend/crates/gateway-host/src/plugin_distribution/github.rs
new file mode 100644
index 000000000..14b350193
--- /dev/null
+++ b/backend/crates/gateway-host/src/plugin_distribution/github.rs
@@ -0,0 +1,326 @@
+use std::{
+    sync::Arc,
+    time::{Duration, Instant},
+};
+
+use chrono::Utc;
+use gateway_admin::model::{
+    AdminError,
+    plugins::{
+        PluginSource,
+        distribution::{
+            DownloadPurpose, GithubReleaseQuery, PluginDistributionEgress, PluginRelease,
+            ReleaseAsset, SourceCredential,
+        },
+    },
+};
+use reqwest::Url;
+use serde::Deserialize;
+use tokio::sync::Mutex;
+
+use super::{
+    HttpPluginDistribution, MAX_METADATA_BYTES, credential_ids, http, source_error, validate_digest,
+};
+
+#[derive(Clone)]
+pub(super) struct CachedRelease {
+    result: Result<ResolvedRelease, AdminError>,
+    until: Instant,
+}
+
+#[derive(Clone)]
+pub(super) struct ResolvedRelease {
+    pub(super) view: PluginRelease,
+    assets: Vec<GitHubAsset>,
+}
+
+#[derive(Deserialize)]
+struct GitHubRelease {
+    tag_name: String,
+    name: Option<String>,
+    draft: bool,
+    prerelease: bool,
+    assets: Vec<GitHubAsset>,
+}
+
+#[derive(Clone, Deserialize)]
+struct GitHubAsset {
+    id: u64,
+    name: String,
+    size: u64,
+    digest: Option<String>,
+}
+
+impl HttpPluginDistribution {
+    pub(super) async fn release(
+        &self,
+        mut query: GithubReleaseQuery,
+        credentials: &[SourceCredential],
+        egress: Option<&PluginDistributionEgress>,
+    ) -> Result<ResolvedRelease, AdminError> {
+        validate_repository(&query.repository)?;
+        query.repository.make_ascii_lowercase();
+        let url = self.release_url(&query)?;
+        let key = format!(
+            "{}:{}:{}:{}",
+            url,
+            query.allow_prerelease,
+            http::scope_key(&url, DownloadPurpose::Metadata, credentials)?,
+            egress.map_or_else(|| "direct".to_owned(), PluginDistributionEgress::cache_key)
+        );
+        let slot = {
+            let mut entries = self.queries.lock().await;
+            if entries.len() >= 64 {
+                entries.retain(|_, slot| {
+                    Arc::strong_count(slot) > 1
+                        || slot.try_lock().map_or(true, |entry| {
+                            entry
+                                .as_ref()
+                                .is_some_and(|entry| entry.until > Instant::now())
+                        })
+                });
+            }
+            if entries.len() >= 64 && !entries.contains_key(&key) {
+                return Err(AdminError::unavailable("插件来源查询缓存已满，请稍后重试"));
+            }
+            entries
+                .entry(key)
+                .or_insert_with(|| Arc::new(Mutex::new(None)))
+                .clone()
+        };
+        tokio::time::timeout(Duration::from_secs(60), async {
+            // 同一来源共用锁和结果；取消请求释放锁，下一位查询者可重新发起。
+            let mut cached = slot.lock().await;
+            if let Some(entry) = cached.as_ref().filter(|entry| entry.until > Instant::now()) {
+                return entry.result.clone();
+            }
+            let _permit = self
+                .concurrency
+                .acquire()
+                .await
+                .map_err(|_| source_error())?;
+            let result = self.fetch_release(url, query, credentials, egress).await;
+            let ttl = if result.is_ok() {
+                Duration::from_secs(3600)
+            } else {
+                Duration::from_secs(30)
+            };
+            *cached = Some(CachedRelease {
+                result: result.clone(),
+                until: Instant::now() + ttl,
+            });
+            result
+        })
+        .await
+        .map_err(|_| AdminError::bad_gateway("GitHub Release 查询超时"))?
+    }
+
+    fn release_url(&self, query: &GithubReleaseQuery) -> Result<Url, AdminError> {
+        let mut url = self.api_base.clone();
+        {
+            let mut path = url.path_segments_mut().map_err(|_| source_error())?;
+            path.pop_if_empty().push("repos");
+            for segment in query.repository.split('/') {
+                path.push(segment);
+            }
+            path.push("releases");
+            if let Some(tag) = &query.tag {
+                if tag.is_empty() || tag.len() > 256 || tag.chars().any(char::is_control) {
+                    return Err(AdminError::invalid("GitHub tag 不合法"));
+                }
+                path.push("tags").push(tag);
+            } else {
+                path.push("latest");
+            }
+        }
+        Ok(url)
+    }
+
+    async fn fetch_release(
+        &self,
+        url: Url,
+        query: GithubReleaseQuery,
+        credentials: &[SourceCredential],
+        egress: Option<&PluginDistributionEgress>,
+    ) -> Result<ResolvedRelease, AdminError> {
+        let bytes = self
+            .downloads
+            .get(
+                url,
+                DownloadPurpose::Metadata,
+                credentials,
+                MAX_METADATA_BYTES,
+                true,
+                egress,
+            )
+            .await?;
+        let release: GitHubRelease = serde_json::from_slice(&bytes).map_err(|_| source_error())?;
+        if release.draft
+            || (release.prerelease && !query.allow_prerelease)
+            || release.tag_name.is_empty()
+            || release.tag_name.len() > 256
+            || release.tag_name.chars().any(char::is_control)
+            || release.assets.len() > 256
+            || query
+                .tag
+                .as_ref()
+                .is_some_and(|tag| *tag != release.tag_name)
+        {
+            return Err(AdminError::invalid(
+                "Release 的版本或发布状态与选择不符；预发行版需要显式选择",
+            ));
+        }
+        let mut names = std::collections::BTreeSet::new();
+        for asset in &release.assets {
+            if asset.id == 0
+                || asset.name.is_empty()
+                || asset.name.len() > 256
+                || asset.name.contains(['/', '\\'])
+                || asset.name.chars().any(char::is_control)
+                || !names.insert(&asset.name)
+            {
+                return Err(AdminError::invalid("GitHub Release 产物描述不合法"));
+            }
+        }
+        let queried_at = Utc::now();
+        Ok(ResolvedRelease {
+            view: PluginRelease {
+                repository: query.repository,
+                tag: release.tag_name,
+                name: release.name.unwrap_or_default().chars().take(256).collect(),
+                prerelease: release.prerelease,
+                assets: release
+                    .assets
+                    .iter()
+                    .map(|asset| ReleaseAsset {
+                        name: asset.name.clone(),
+                        size: asset.size,
+                        sha256: asset_digest(asset),
+                    })
+                    .collect(),
+                queried_at,
+                expires_at: queried_at + chrono::Duration::hours(1),
+            },
+            assets: release.assets,
+        })
+    }
+
+    pub(super) async fn resolve_asset(
+        &self,
+        query: GithubReleaseQuery,
+        asset: String,
+        expected: Option<String>,
+        credentials: &[SourceCredential],
+        egress: Option<&PluginDistributionEgress>,
+    ) -> Result<(Url, Option<String>, PluginSource, bool), AdminError> {
+        let release = self.release(query, credentials, egress).await?;
+        let selected = release
+            .assets
+            .iter()
+            .find(|candidate| candidate.name == asset)
+            .ok_or_else(|| AdminError::not_found("Release 不包含指定产物"))?;
+        if selected.size == 0 || selected.size > super::MAX_ARCHIVE_BYTES as u64 {
+            return Err(AdminError::invalid("插件包大小不合法"));
+        }
+        let source_digest = asset_digest(selected);
+        let digest = if let Some(expected) = expected {
+            validate_digest(&expected)?;
+            if source_digest
+                .as_ref()
+                .is_some_and(|source| *source != expected)
+            {
+                return Err(AdminError::invalid("输入摘要与 GitHub 产物摘要不一致"));
+            }
+            Some(expected)
+        } else if let Some(digest) = source_digest {
+            Some(digest)
+        } else if let Some(checksums) = release
+            .assets
+            .iter()
+            .find(|asset| asset.name == "checksums.txt")
+        {
+            let _permit = self
+                .concurrency
+                .acquire()
+                .await
+                .map_err(|_| source_error())?;
+            let bytes = self
+                .downloads
+                .get(
+                    self.asset_url(&release.view.repository, checksums.id)?,
+                    DownloadPurpose::Artifact,
+                    credentials,
+                    MAX_METADATA_BYTES,
+                    true,
+                    egress,
+                )
+                .await?;
+            Some(checksum_for(&bytes, &asset)?)
+        } else {
+            None
+        };
+        let url = self.asset_url(&release.view.repository, selected.id)?;
+        let source = PluginSource::Github {
+            repository: release.view.repository,
+            tag: release.view.tag,
+            asset,
+            credential_ids: credential_ids(credentials),
+            outbound_proxy: egress.map(|egress| egress.source.clone()),
+        };
+        Ok((url, digest, source, true))
+    }
+
+    fn asset_url(&self, repository: &str, id: u64) -> Result<Url, AdminError> {
+        self.api_base
+            .join(&format!("repos/{repository}/releases/assets/{id}"))
+            .map_err(|_| source_error())
+    }
+}
+
+fn asset_digest(asset: &GitHubAsset) -> Option<String> {
+    asset
+        .digest
+        .as_deref()
+        .and_then(|value| value.strip_prefix("sha256:"))
+        .filter(|digest| validate_digest(digest).is_ok())
+        .map(str::to_owned)
+}
+
+pub(super) fn validate_repository(repository: &str) -> Result<(), AdminError> {
+    let parts: Vec<_> = repository.split('/').collect();
+    if parts.len() != 2
+        || parts.iter().any(|part| {
+            part.is_empty()
+                || part.len() > 100
+                || *part == "."
+                || *part == ".."
+                || !part
+                    .bytes()
+                    .all(|byte| byte.is_ascii_alphanumeric() || b"-_.".contains(&byte))
+        })
+    {
+        return Err(AdminError::invalid("GitHub 仓库需要 owner/repository 格式"));
+    }
+    Ok(())
+}
+
+fn checksum_for(bytes: &[u8], asset: &str) -> Result<String, AdminError> {
+    let text = std::str::from_utf8(bytes).map_err(|_| source_error())?;
+    let mut found = None;
+    for line in text.lines() {
+        let mut fields = line.split_whitespace();
+        let Some(digest) = fields.next() else {
+            continue;
+        };
+        let Some(name) = fields.next() else { continue };
+        if name.trim_start_matches('*') == asset {
+            validate_digest(digest)?;
+            if fields.next().is_some() || found.replace(digest.to_owned()).is_some() {
+                return Err(AdminError::invalid(
+                    "checksums.txt 包含重复或不合法的目标摘要",
+                ));
+            }
+        }
+    }
+    found.ok_or_else(|| AdminError::invalid("checksums.txt 缺少目标产物摘要"))
+}
diff --git a/backend/crates/gateway-host/src/plugin_distribution/http.rs b/backend/crates/gateway-host/src/plugin_distribution/http.rs
new file mode 100644
index 000000000..b31f2b101
--- /dev/null
+++ b/backend/crates/gateway-host/src/plugin_distribution/http.rs
@@ -0,0 +1,345 @@
+use std::{
+    collections::HashMap,
+    sync::Arc,
+    time::{Duration, Instant, SystemTime, UNIX_EPOCH},
+};
+
+use gateway_admin::model::{
+    AdminError, AdminErrorKind,
+    plugins::distribution::{
+        DownloadPurpose, PluginDistributionEgress, SourceAuthentication, SourceCredential,
+    },
+};
+use reqwest::{
+    Url,
+    header::{HeaderName, HeaderValue},
+};
+use secrecy::ExposeSecret as _;
+use sha2::{Digest as _, Sha256};
+use tokio::sync::Mutex;
+
+use super::source_error;
+use crate::outbound::{HttpClient, HttpRequest, NetworkPolicy};
+
+pub(super) struct Downloads {
+    client: Arc<HttpClient>,
+    network: NetworkPolicy,
+    rate_limits: Mutex<HashMap<String, Instant>>,
+}
+
+impl Downloads {
+    pub(super) fn new(client: Arc<HttpClient>, network: NetworkPolicy) -> Self {
+        Self {
+            client,
+            network,
+            rate_limits: Mutex::new(HashMap::new()),
+        }
+    }
+
+    pub(super) async fn get(
+        &self,
+        mut url: Url,
+        purpose: DownloadPurpose,
+        credentials: &[SourceCredential],
+        limit: usize,
+        github_api: bool,
+        egress: Option<&PluginDistributionEgress>,
+    ) -> Result<Vec<u8>, AdminError> {
+        for redirect in 0..=5 {
+            validate_url(&url)?;
+            let egress_key =
+                egress.map_or_else(|| "direct".to_owned(), PluginDistributionEgress::cache_key);
+            let scope = format!("{}:{egress_key}", scope_key(&url, purpose, credentials)?);
+            {
+                let mut rates = self.rate_limits.lock().await;
+                rates.retain(|_, until| *until > Instant::now());
+                if let Some(until) = rates.get(&scope) {
+                    return Err(rate_error(
+                        until
+                            .saturating_duration_since(Instant::now())
+                            .as_secs()
+                            .max(1),
+                    ));
+                }
+                if rates.len() >= 256 {
+                    return Err(AdminError::unavailable("插件来源退避列表已满，请稍后重试"));
+                }
+            }
+            let mut headers = vec![(
+                "user-agent".to_owned(),
+                b"codex-proxy-rs-plugin-distribution".to_vec(),
+            )];
+            if github_api {
+                headers.extend([
+                    (
+                        "accept".to_owned(),
+                        if purpose == DownloadPurpose::Metadata {
+                            b"application/vnd.github+json".to_vec()
+                        } else {
+                            b"application/octet-stream".to_vec()
+                        },
+                    ),
+                    ("x-github-api-version".to_owned(), b"2022-11-28".to_vec()),
+                ]);
+            }
+            if let Some(credential) = matching_credential(&url, purpose, credentials)? {
+                let (name, value) = authentication_header(&credential.authentication)?;
+                headers.push((name.to_string(), value.as_bytes().to_vec()));
+            }
+            let mut response = self
+                .client
+                .open_scoped(
+                    HttpRequest {
+                        method: "GET".to_owned(),
+                        url: url.to_string(),
+                        headers,
+                        body: vec![],
+                    },
+                    egress.map(|egress| &egress.proxy),
+                    &self.network,
+                    Duration::from_secs(30),
+                    Some(&egress_key),
+                )
+                .await
+                .map_err(|_| source_error())?;
+            if let Some(delay) = rate_delay(response.status, &response.headers) {
+                let mut rates = self.rate_limits.lock().await;
+                // 限流项有界；超出时拒绝新查询，不淘汰仍然有效的退避。
+                if rates.len() < 256 || rates.contains_key(&scope) {
+                    rates.insert(scope, Instant::now() + delay);
+                }
+                return Err(rate_error(delay.as_secs()));
+            }
+            if (300..400).contains(&response.status) {
+                if redirect == 5 {
+                    return Err(source_error());
+                }
+                let location = response
+                    .headers
+                    .iter()
+                    .find(|(name, _)| name.eq_ignore_ascii_case("location"))
+                    .and_then(|(_, value)| std::str::from_utf8(value).ok())
+                    .ok_or_else(source_error)?;
+                let next = url.join(location).map_err(|_| source_error())?;
+                if url.scheme() == "https" && next.scheme() != "https" {
+                    return Err(source_error());
+                }
+                // 不继承上一次请求的头；下一跳从授权列表重新匹配，包括同域的路径变化。
+                url = next;
+                continue;
+            }
+            if !(200..300).contains(&response.status) {
+                return Err(source_error());
+            }
+            if header(&response.headers, "content-length")
+                .and_then(|value| std::str::from_utf8(value).ok())
+                .and_then(|value| value.parse::<u64>().ok())
+                .is_some_and(|length| length > limit as u64)
+            {
+                return Err(AdminError::invalid("插件来源响应超过大小限制"));
+            }
+            let mut body = Vec::new();
+            while let Some(chunk) = response
+                .body
+                .read(64 * 1024)
+                .await
+                .map_err(|_| source_error())?
+            {
+                if chunk.len() > limit.saturating_sub(body.len()) {
+                    return Err(AdminError::invalid("插件来源响应超过大小限制"));
+                }
+                body.extend_from_slice(&chunk);
+            }
+            return Ok(body);
+        }
+        Err(source_error())
+    }
+}
+
+pub(super) fn source_url(value: &str) -> Result<Url, AdminError> {
+    let url = Url::parse(value).map_err(|_| AdminError::invalid("插件来源 URL 不合法"))?;
+    validate_url(&url)?;
+    if url.query().is_some() {
+        return Err(AdminError::invalid(
+            "插件来源 URL 不接受查询参数，请使用独立下载凭据",
+        ));
+    }
+    Ok(url)
+}
+
+fn validate_url(url: &Url) -> Result<(), AdminError> {
+    let loopback = url.host_str().is_some_and(|host| {
+        host == "localhost"
+            || host
+                .parse::<std::net::IpAddr>()
+                .is_ok_and(|ip| ip.is_loopback())
+    });
+    if url.as_str().len() > 4096
+        || url.host_str().is_none()
+        || !url.username().is_empty()
+        || url.password().is_some()
+        || url.fragment().is_some()
+        || !(url.scheme() == "https" || (url.scheme() == "http" && loopback))
+    {
+        return Err(AdminError::invalid(
+            "插件来源需要 HTTPS，且不能在 URL 中包含凭据或片段",
+        ));
+    }
+    Ok(())
+}
+
+pub(super) fn validate_credential(credential: &SourceCredential) -> Result<(), AdminError> {
+    let info = &credential.info;
+    let origin = source_url(&info.origin)?;
+    if origin.path() != "/"
+        || info.name.trim().is_empty()
+        || info.name.len() > 128
+        || !info.path_prefix.starts_with('/')
+        || info.path_prefix.len() > 1024
+        || info.path_prefix.contains(['?', '#', '%', '\\'])
+        || info
+            .path_prefix
+            .split('/')
+            .any(|part| part == "." || part == "..")
+        || info.purposes.is_empty()
+        || info.purposes.len() > 2
+        || (info.purposes.len() == 2 && info.purposes[0] == info.purposes[1])
+    {
+        return Err(AdminError::invalid("下载凭据的目标、路径或用途不合法"));
+    }
+    authentication_header(&credential.authentication)?;
+    Ok(())
+}
+
+fn matching_credential<'a>(
+    url: &Url,
+    purpose: DownloadPurpose,
+    credentials: &'a [SourceCredential],
+) -> Result<Option<&'a SourceCredential>, AdminError> {
+    let mut selected = None;
+    for credential in credentials {
+        validate_credential(credential)?;
+        let origin = source_url(&credential.info.origin)?;
+        let prefix = credential.info.path_prefix.trim_end_matches('/');
+        if url.origin() == origin.origin()
+            && credential.info.purposes.contains(&purpose)
+            && (prefix.is_empty()
+                || url.path() == prefix
+                || url
+                    .path()
+                    .strip_prefix(prefix)
+                    .is_some_and(|suffix| suffix.starts_with('/')))
+        {
+            if selected.is_some() {
+                return Err(AdminError::invalid("下载凭据的授权范围重叠"));
+            }
+            selected = Some(credential);
+        }
+    }
+    Ok(selected)
+}
+
+pub(super) fn scope_key(
+    url: &Url,
+    purpose: DownloadPurpose,
+    credentials: &[SourceCredential],
+) -> Result<String, AdminError> {
+    let mut digest = Sha256::new();
+    digest.update(url.origin().ascii_serialization());
+    if let Some(credential) = matching_credential(url, purpose, credentials)? {
+        let (name, value) = authentication_header(&credential.authentication)?;
+        digest.update(name.as_str());
+        digest.update(value.as_bytes());
+    }
+    Ok(hex::encode(digest.finalize()))
+}
+
+fn authentication_header(
+    authentication: &SourceAuthentication,
+) -> Result<(HeaderName, HeaderValue), AdminError> {
+    use base64::Engine as _;
+    let (name, raw) = match authentication {
+        SourceAuthentication::Github { token } | SourceAuthentication::Bearer { token } => {
+            if token.expose_secret().trim().is_empty() {
+                return Err(AdminError::invalid("下载 token 不能为空"));
+            }
+            (
+                "authorization".to_owned(),
+                format!("Bearer {}", token.expose_secret()),
+            )
+        }
+        SourceAuthentication::Basic { username, password } => {
+            if username.contains(':') || username.len() > 256 {
+                return Err(AdminError::invalid("Basic 用户名不合法"));
+            }
+            (
+                "authorization".to_owned(),
+                format!(
+                    "Basic {}",
+                    base64::engine::general_purpose::STANDARD
+                        .encode(format!("{username}:{}", password.expose_secret()))
+                ),
+            )
+        }
+        SourceAuthentication::Header { name, value } => {
+            (name.to_ascii_lowercase(), value.expose_secret().to_owned())
+        }
+    };
+    if raw.trim().is_empty()
+        || raw.len() > 8192
+        || !(name == "authorization"
+            || (name.starts_with("x-")
+                && !name.starts_with("x-forwarded-")
+                && name != "x-http-method-override"))
+    {
+        return Err(AdminError::invalid("下载鉴权头不合法"));
+    }
+    let name = HeaderName::from_bytes(name.as_bytes())
+        .map_err(|_| AdminError::invalid("下载鉴权头不合法"))?;
+    let mut value =
+        HeaderValue::from_str(&raw).map_err(|_| AdminError::invalid("下载鉴权值不合法"))?;
+    value.set_sensitive(true);
+    Ok((name, value))
+}
+
+fn header<'a>(headers: &'a [(String, Vec<u8>)], name: &str) -> Option<&'a [u8]> {
+    headers
+        .iter()
+        .find(|(candidate, _)| candidate.eq_ignore_ascii_case(name))
+        .map(|(_, value)| value.as_slice())
+}
+
+fn rate_delay(status: u16, headers: &[(String, Vec<u8>)]) -> Option<Duration> {
+    if ![403, 429].contains(&status) {
+        return None;
+    }
+    let retry = header(headers, "retry-after")
+        .and_then(|value| std::str::from_utf8(value).ok())
+        .and_then(|value| value.parse::<u64>().ok());
+    let remaining =
+        header(headers, "x-ratelimit-remaining").and_then(|value| std::str::from_utf8(value).ok());
+    let reset = (remaining == Some("0"))
+        .then(|| {
+            header(headers, "x-ratelimit-reset")
+                .and_then(|value| std::str::from_utf8(value).ok())
+                .and_then(|value| value.parse::<u64>().ok())
+        })
+        .flatten();
+    let now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs();
+    Some(Duration::from_secs(
+        retry
+            .or_else(|| reset.map(|until| until.saturating_sub(now)))
+            .unwrap_or(60)
+            .clamp(1, 86400),
+    ))
+}
+
+fn rate_error(seconds: u64) -> AdminError {
+    AdminError::new(
+        AdminErrorKind::RateLimited,
+        format!("插件来源限流，请在 {seconds} 秒后重试"),
+    )
+}
diff --git a/backend/crates/gateway-host/src/plugin_distribution/mod.rs b/backend/crates/gateway-host/src/plugin_distribution/mod.rs
new file mode 100644
index 000000000..c709d0665
--- /dev/null
+++ b/backend/crates/gateway-host/src/plugin_distribution/mod.rs
@@ -0,0 +1,201 @@
+//! 插件来源查询和受控下载；不解析插件包，不持有数据库或管理事务。
+
+mod github;
+mod http;
+
+use std::{collections::HashMap, sync::Arc, time::Duration};
+
+use crate::outbound::{HttpClient, NetworkPolicy};
+use async_trait::async_trait;
+use gateway_admin::{
+    model::{
+        AdminError,
+        plugins::{
+            PluginSource,
+            distribution::{
+                DownloadedPlugin, GithubReleaseQuery, PluginDistributionEgress, PluginRelease,
+                RemotePluginLocation, SourceCredential,
+            },
+        },
+    },
+    ports::plugins::PluginDistribution,
+};
+use reqwest::Url;
+use sha2::{Digest as _, Sha256};
+use tokio::sync::{Mutex, Semaphore};
+
+use self::{github::CachedRelease, http::Downloads};
+
+const MAX_ARCHIVE_BYTES: usize = 32 * 1024 * 1024;
+const MAX_METADATA_BYTES: usize = 1024 * 1024;
+
+/// 插件分发服务复用宿主受控 HTTP；缓存与限流不会跨出站身份共享。
+pub struct HttpPluginDistribution {
+    downloads: Downloads,
+    api_base: Url,
+    queries: Mutex<HashMap<String, Arc<Mutex<Option<CachedRelease>>>>>,
+    concurrency: Semaphore,
+}
+
+impl HttpPluginDistribution {
+    pub fn new(http: Arc<HttpClient>) -> Result<Self, AdminError> {
+        Self::with_transport("https://api.github.com/", http, source_network()?)
+    }
+
+    /// 测试可注入受限网络；生产来源由管理员显式配置，因此保持既有内外网可达范围。
+    pub fn with_transport(
+        api_base: &str,
+        http: Arc<HttpClient>,
+        network: NetworkPolicy,
+    ) -> Result<Self, AdminError> {
+        let api_base = http::source_url(api_base)?;
+        Ok(Self {
+            downloads: Downloads::new(http, network),
+            api_base,
+            queries: Mutex::new(HashMap::new()),
+            concurrency: Semaphore::new(2),
+        })
+    }
+
+    async fn download_inner(
+        &self,
+        location: RemotePluginLocation,
+        credentials: Vec<SourceCredential>,
+        egress: Option<&PluginDistributionEgress>,
+    ) -> Result<DownloadedPlugin, AdminError> {
+        let (url, expected, source, github_api) = match location {
+            RemotePluginLocation::Url { url, sha256 } => {
+                if let Some(digest) = &sha256 {
+                    validate_digest(digest)?;
+                }
+                let parsed = http::source_url(&url)?;
+                (
+                    parsed,
+                    sha256,
+                    PluginSource::Url {
+                        url,
+                        credential_ids: credential_ids(&credentials),
+                        outbound_proxy: egress.map(|egress| egress.source.clone()),
+                    },
+                    false,
+                )
+            }
+            RemotePluginLocation::Github {
+                repository,
+                tag,
+                asset,
+                allow_prerelease,
+                sha256,
+            } => {
+                self.resolve_asset(
+                    GithubReleaseQuery {
+                        repository,
+                        tag: Some(tag),
+                        allow_prerelease,
+                    },
+                    asset,
+                    sha256,
+                    &credentials,
+                    egress,
+                )
+                .await?
+            }
+        };
+        let _permit = self
+            .concurrency
+            .acquire()
+            .await
+            .map_err(|_| source_error())?;
+        let archive = self
+            .downloads
+            .get(
+                url,
+                gateway_admin::model::plugins::distribution::DownloadPurpose::Artifact,
+                &credentials,
+                MAX_ARCHIVE_BYTES,
+                github_api,
+                egress,
+            )
+            .await?;
+        let sha256 = hex::encode(Sha256::digest(&archive));
+        if expected.is_some_and(|expected| sha256 != expected) {
+            return Err(AdminError::invalid("插件下载包的 SHA-256 与来源预期不一致"));
+        }
+        Ok(DownloadedPlugin {
+            archive: archive.into(),
+            sha256,
+            source,
+        })
+    }
+}
+
+#[async_trait]
+impl PluginDistribution for HttpPluginDistribution {
+    fn validate_source(
+        &self,
+        source: &gateway_admin::model::plugins::distribution::PluginUpdateSource,
+    ) -> Result<(), AdminError> {
+        use gateway_admin::model::plugins::distribution::PluginUpdateSource;
+        match source {
+            PluginUpdateSource::Builtin | PluginUpdateSource::Upload => Ok(()),
+            PluginUpdateSource::Url { url } => http::source_url(url).map(|_| ()),
+            PluginUpdateSource::Github { repository } => github::validate_repository(repository),
+        }
+    }
+    fn validate_credential(&self, credential: &SourceCredential) -> Result<(), AdminError> {
+        http::validate_credential(credential)
+    }
+
+    async fn query_release(
+        &self,
+        query: GithubReleaseQuery,
+        credentials: Vec<SourceCredential>,
+        egress: Option<PluginDistributionEgress>,
+    ) -> Result<PluginRelease, AdminError> {
+        Ok(self
+            .release(query, &credentials, egress.as_ref())
+            .await?
+            .view)
+    }
+
+    async fn download(
+        &self,
+        location: RemotePluginLocation,
+        credentials: Vec<SourceCredential>,
+        egress: Option<PluginDistributionEgress>,
+    ) -> Result<DownloadedPlugin, AdminError> {
+        tokio::time::timeout(
+            Duration::from_secs(120),
+            self.download_inner(location, credentials, egress.as_ref()),
+        )
+        .await
+        .map_err(|_| AdminError::bad_gateway("插件下载超时，请重试"))?
+    }
+}
+
+fn source_network() -> Result<NetworkPolicy, AdminError> {
+    NetworkPolicy::new(&["0.0.0.0/0".into(), "::/0".into()]).map_err(|_| source_error())
+}
+
+fn credential_ids(credentials: &[SourceCredential]) -> Vec<String> {
+    credentials
+        .iter()
+        .map(|credential| credential.info.id.clone())
+        .collect()
+}
+
+fn source_error() -> AdminError {
+    AdminError::bad_gateway("插件来源请求失败，请检查来源与下载授权后重试")
+}
+
+fn validate_digest(value: &str) -> Result<(), AdminError> {
+    if value.len() == 64
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+    {
+        Ok(())
+    } else {
+        Err(AdminError::invalid("需要小写十六进制 SHA-256 摘要"))
+    }
+}
diff --git a/backend/crates/gateway-host/src/process.rs b/backend/crates/gateway-host/src/process.rs
new file mode 100644
index 000000000..d827f9f13
--- /dev/null
+++ b/backend/crates/gateway-host/src/process.rs
@@ -0,0 +1,157 @@
+//! 受管子进程的创建、退出通知与回收，不解释插件或其他业务协议。
+
+use std::{num::NonZeroUsize, path::PathBuf, process::Stdio, sync::Arc};
+
+use tokio::{
+    io::AsyncReadExt as _,
+    process::{ChildStdin, ChildStdout, Command},
+    sync::{Semaphore, watch},
+};
+
+pub struct ProcessSpec {
+    pub executable: PathBuf,
+    pub directory: PathBuf,
+    pub maximum_stderr_bytes: usize,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProcessExit {
+    Exited(Option<i32>),
+    Stopped,
+    StderrLimit,
+    Failed,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+pub enum ProcessStartError {
+    #[error("managed process capacity exhausted")]
+    Capacity,
+    #[error("managed process could not be started ({kind:?}, OS {os_code:?})")]
+    Spawn {
+        kind: std::io::ErrorKind,
+        os_code: Option<i32>,
+    },
+    #[error("managed process pipes unavailable")]
+    Pipes,
+}
+
+/// 组合根提供共享监督入口，容量直到子进程被回收后才归还。
+pub struct ProcessSupervisor {
+    slots: Arc<Semaphore>,
+}
+
+impl Default for ProcessSupervisor {
+    fn default() -> Self {
+        Self {
+            slots: Arc::new(Semaphore::new(128)),
+        }
+    }
+}
+
+impl ProcessSupervisor {
+    #[must_use]
+    pub fn new(maximum_processes: NonZeroUsize) -> Self {
+        Self {
+            slots: Arc::new(Semaphore::new(maximum_processes.get())),
+        }
+    }
+
+    pub fn spawn(&self, spec: ProcessSpec) -> Result<ProcessConnection, ProcessStartError> {
+        let slot = self
+            .slots
+            .clone()
+            .try_acquire_owned()
+            .map_err(|_| ProcessStartError::Capacity)?;
+        spawn_process(spec, slot)
+    }
+}
+
+/// 通信资源和监督控制分离；最后一个控制引用释放时也必须回收进程。
+pub struct ProcessConnection {
+    pub input: ChildStdin,
+    pub output: ChildStdout,
+    pub control: ProcessControl,
+}
+
+#[derive(Clone)]
+pub struct ProcessControl {
+    stop: watch::Sender<bool>,
+    exit: watch::Receiver<Option<ProcessExit>>,
+}
+
+impl ProcessControl {
+    pub fn stop(&self) {
+        self.stop.send_replace(true);
+    }
+
+    pub async fn exited(&self) -> ProcessExit {
+        let mut exit = self.exit.clone();
+        loop {
+            if let Some(result) = *exit.borrow_and_update() {
+                return result;
+            }
+            if exit.changed().await.is_err() {
+                return ProcessExit::Failed;
+            }
+        }
+    }
+}
+
+/// 可信原生程序仍拥有当前 OS 用户权限；清空环境和独立进程不等于安全沙箱。
+fn spawn_process(
+    spec: ProcessSpec,
+    slot: tokio::sync::OwnedSemaphorePermit,
+) -> Result<ProcessConnection, ProcessStartError> {
+    let mut child = Command::new(&spec.executable)
+        .current_dir(&spec.directory)
+        .env_clear()
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .kill_on_drop(true)
+        .spawn()
+        // 只保留错误类别与 OS 编号，不把进程路径、环境或输出带入诊断。
+        .map_err(|error| ProcessStartError::Spawn {
+            kind: error.kind(),
+            os_code: error.raw_os_error(),
+        })?;
+    let input = child.stdin.take().ok_or(ProcessStartError::Pipes)?;
+    let output = child.stdout.take().ok_or(ProcessStartError::Pipes)?;
+    let mut stderr = child.stderr.take().ok_or(ProcessStartError::Pipes)?;
+    let (stop, mut stopped) = watch::channel(false);
+    let (exit_sender, exit) = watch::channel(None);
+    tokio::spawn(async move {
+        let mut stderr_total = 0usize;
+        let mut buffer = [0; 4096];
+        let mut stderr_open = true;
+        let reason = loop {
+            tokio::select! {
+                biased;
+                _ = stopped.changed() => break ProcessExit::Stopped,
+                result = child.wait() => break result.map_or(ProcessExit::Failed, |status| ProcessExit::Exited(status.code())),
+                result = stderr.read(&mut buffer), if stderr_open => {
+                    match result {
+                        Ok(0) => stderr_open = false,
+                        Ok(size) => {
+                            stderr_total = stderr_total.saturating_add(size);
+                            if stderr_total > spec.maximum_stderr_bytes { break ProcessExit::StderrLimit; }
+                        }
+                        Err(_) => break ProcessExit::Failed,
+                    }
+                }
+            }
+        };
+        // stderr 是不可信诊断，不写宿主日志；业务日志必须经过有界脱敏接口。
+        if !matches!(reason, ProcessExit::Exited(_)) {
+            let _ = child.kill().await;
+        }
+        let _ = child.wait().await;
+        drop(slot);
+        exit_sender.send_replace(Some(reason));
+    });
+    Ok(ProcessConnection {
+        input,
+        output,
+        control: ProcessControl { stop, exit },
+    })
+}
diff --git a/backend/crates/gateway-host/src/serve.rs b/backend/crates/gateway-host/src/serve.rs
index 590b8fa75..4ef3ae10d 100644
--- a/backend/crates/gateway-host/src/serve.rs
+++ b/backend/crates/gateway-host/src/serve.rs
@@ -145,7 +145,7 @@ pub(crate) async fn serve_router(
     let listener = bind_listener(&format!("{host}:{port}"))
         .await
         .map_err(ServeError::Bind)?;
-    tracing::info!(target: "gateway_startup", host, port, "网关开始监听");
+    tracing::info!(target: "gateway_startup", pid = std::process::id(), host, port, "网关开始监听");
 
     let shutdown_cancellation = cancellation.clone();
     let shutdown_connections = Arc::clone(&connections);
@@ -194,31 +194,44 @@ pub(crate) async fn serve_router(
     Ok(())
 }
 
-async fn wait_for_shutdown(cancellation: &CancellationToken) {
+pub(crate) async fn wait_for_shutdown(cancellation: &CancellationToken) {
+    let interrupt = async {
+        match tokio::signal::ctrl_c().await {
+            Ok(()) => "sigint",
+            Err(error) => {
+                tracing::warn!(target: "gateway_shutdown", %error, "中断信号监听失败");
+                "interrupt_listener_error"
+            }
+        }
+    };
     #[cfg(unix)]
-    {
+    let reason = {
         let terminate = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate());
         match terminate {
             Ok(mut terminate) => {
                 tokio::select! {
-                    _ = tokio::signal::ctrl_c() => {}
-                    _ = terminate.recv() => {}
-                    () = cancellation.cancelled() => return,
+                    reason = interrupt => reason,
+                    signal = terminate.recv() => {
+                        if signal.is_some() { "sigterm" } else { "terminate_listener_closed" }
+                    }
+                    () = cancellation.cancelled() => "internal_cancellation",
                 }
             }
-            Err(_) => {
+            Err(error) => {
+                tracing::warn!(target: "gateway_shutdown", %error, "终止信号监听注册失败，仅监听中断与内部关闭请求");
                 tokio::select! {
-                    _ = tokio::signal::ctrl_c() => {}
-                    () = cancellation.cancelled() => return,
+                    reason = interrupt => reason,
+                    () = cancellation.cancelled() => "internal_cancellation",
                 }
             }
         }
-    }
+    };
     #[cfg(not(unix))]
-    tokio::select! {
-        _ = tokio::signal::ctrl_c() => {}
-        () = cancellation.cancelled() => return,
-    }
+    let reason = tokio::select! {
+        reason = interrupt => reason,
+        () = cancellation.cancelled() => "internal_cancellation",
+    };
+    tracing::info!(target: "gateway_shutdown", pid = std::process::id(), reason, "收到关闭请求");
     cancellation.cancel();
 }
 
diff --git a/backend/crates/gateway-host/src/system_update/archive.rs b/backend/crates/gateway-host/src/system_update/archive.rs
index daed31847..5b43053e5 100644
--- a/backend/crates/gateway-host/src/system_update/archive.rs
+++ b/backend/crates/gateway-host/src/system_update/archive.rs
@@ -1,5 +1,6 @@
 //! Release tar.gz 安全解包与制品归一化。
 
+use std::collections::BTreeSet;
 use std::fs;
 use std::path::{Component, Path, PathBuf};
 
@@ -13,6 +14,7 @@ const MAX_ARCHIVE_FILES: usize = 20_000;
 pub(crate) struct ExtractedRelease {
     pub(crate) binary_path: PathBuf,
     pub(crate) web_dist_dir: Option<PathBuf>,
+    pub(crate) official_plugins_dir: PathBuf,
 }
 
 pub(crate) fn extract_release(
@@ -25,8 +27,11 @@ pub(crate) fn extract_release(
     let mut archive = tar::Archive::new(decoder);
     let binary_path = temp_dir.join(APP_BINARY_NAME);
     let web_dist_dir = temp_dir.join("web-dist");
+    let official_plugins_dir = temp_dir.join("official-plugins");
     let mut found_binary = false;
     let mut found_web = false;
+    let mut found_official_manifest = false;
+    let mut official_files = BTreeSet::new();
     let mut extracted_size = 0_u64;
     let mut file_count = 0_usize;
 
@@ -43,7 +48,13 @@ pub(crate) fn extract_release(
         if unsafe_archive_path(&path) {
             return Err(invalid("release archive contains an unsafe path"));
         }
+        let official_relative = official_plugin_relative_path(&path)?;
         if !entry.header().entry_type().is_file() {
+            if official_relative.is_some() {
+                return Err(invalid(
+                    "release archive contains a non-file official plugin asset",
+                ));
+            }
             continue;
         }
         file_count = file_count.saturating_add(1);
@@ -62,6 +73,29 @@ pub(crate) fn extract_release(
             found_binary = true;
             continue;
         }
+        if let Some(relative) = official_relative {
+            if !official_files.insert(relative.clone()) {
+                return Err(invalid(
+                    "release archive contains a duplicate official plugin asset",
+                ));
+            }
+            fs::create_dir_all(&official_plugins_dir).map_err(|error| {
+                internal(format!("failed to create official plugin dir: {error}"))
+            })?;
+            let target = official_plugins_dir.join(&relative);
+            entry.unpack(&target).map_err(|error| {
+                internal(format!("failed to extract official plugin asset: {error}"))
+            })?;
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt as _;
+                fs::set_permissions(&target, fs::Permissions::from_mode(0o444)).map_err(
+                    |error| internal(format!("failed to protect official plugin asset: {error}")),
+                )?;
+            }
+            found_official_manifest |= relative == Path::new("plugin-release-manifest.json");
+            continue;
+        }
         if let Some(relative) = web_dist_relative_path(&path) {
             if relative.as_os_str().is_empty() {
                 continue;
@@ -81,6 +115,11 @@ pub(crate) fn extract_release(
     if !found_binary {
         return Err(invalid("release archive does not contain codex-proxy-rs"));
     }
+    if !found_official_manifest {
+        return Err(invalid(
+            "release archive does not contain the official plugin manifest",
+        ));
+    }
     #[cfg(unix)]
     {
         use std::os::unix::fs::PermissionsExt as _;
@@ -90,6 +129,7 @@ pub(crate) fn extract_release(
     Ok(ExtractedRelease {
         binary_path,
         web_dist_dir: found_web.then_some(web_dist_dir),
+        official_plugins_dir,
     })
 }
 
@@ -125,3 +165,43 @@ fn web_dist_relative_path(path: &Path) -> Option<PathBuf> {
     }
     None
 }
+
+fn official_plugin_relative_path(path: &Path) -> Result<Option<PathBuf>, OperationError> {
+    let components = path
+        .components()
+        .filter_map(|component| match component {
+            Component::Normal(value) => Some(value),
+            _ => None,
+        })
+        .collect::<Vec<_>>();
+    for index in 0..components.len() {
+        if components[index] != "plugins"
+            || components
+                .get(index + 1)
+                .is_none_or(|value| *value != "official")
+        {
+            continue;
+        }
+        let relative = &components[index + 2..];
+        if relative.is_empty() {
+            return Ok(None);
+        }
+        if relative.len() != 1 {
+            return Err(invalid(
+                "release archive contains a nested official plugin asset",
+            ));
+        }
+        let file_name = relative[0];
+        let is_manifest = file_name == "plugin-release-manifest.json";
+        let is_archive = file_name
+            .to_str()
+            .is_some_and(|value| value.ends_with(".tar.gz"));
+        if !is_manifest && !is_archive {
+            return Err(invalid(
+                "release archive contains an unexpected official plugin asset",
+            ));
+        }
+        return Ok(Some(PathBuf::from(file_name)));
+    }
+    Ok(None)
+}
diff --git a/backend/crates/gateway-host/src/system_update/mod.rs b/backend/crates/gateway-host/src/system_update/mod.rs
index c101d6543..7bc1ece9d 100644
--- a/backend/crates/gateway-host/src/system_update/mod.rs
+++ b/backend/crates/gateway-host/src/system_update/mod.rs
@@ -21,7 +21,8 @@ use gateway_admin::model::system::{
     SystemUpdateEventLevel, SystemUpdateStatus, SystemVersion,
 };
 use gateway_admin::ports::system::{
-    SystemOperationError, SystemOperationErrorKind, SystemOperations, SystemUpdateEventStream,
+    SystemOperationError, SystemOperationErrorKind, SystemOperations, SystemUpdateCandidate,
+    SystemUpdateEventStream, SystemUpdatePreflight,
 };
 use gateway_core::lifecycle::CancellationToken;
 use serde::Deserialize;
@@ -40,13 +41,15 @@ use self::state::{
     OperationFileLock, UpdateOperation, UpdateTempDir, finish, operation_id, read_status,
     recover_interrupted, set_running,
 };
-use self::swap::{replace_release_files, rollback_release};
+use self::swap::{replace_release_files, rollback_official_plugins_dir, rollback_release};
 
 pub use self::release::validate_download_url;
 
 const APP_BINARY_NAME: &str = "codex-proxy-rs";
 const DEFAULT_GITHUB_API_BASE: &str = "https://api.github.com/repos";
 const DEFAULT_UPDATE_REPOSITORY: &str = "zyycn/codex-proxy-rs";
+const OFFICIAL_PLUGIN_MANIFEST: &str = "plugin-release-manifest.json";
+const MAX_OFFICIAL_PLUGIN_MANIFEST_SIZE: u64 = 256 * 1024;
 
 type OperationError = SystemOperationError;
 
@@ -205,6 +208,15 @@ impl SystemUpdateConfig {
             .map_err(|error| internal(format!("failed to resolve executable: {error}")))
     }
 
+    pub(crate) fn official_plugins_dir(&self) -> Result<PathBuf, OperationError> {
+        let executable = self.executable_path()?;
+        let parent = executable
+            .parent()
+            .filter(|path| !path.as_os_str().is_empty())
+            .ok_or_else(|| internal("failed to resolve official plugin release directory"))?;
+        Ok(parent.join("plugins").join("official"))
+    }
+
     pub(crate) fn web_dist_dir(&self) -> Result<&Path, OperationError> {
         self.web_dist_dir
             .as_deref()
@@ -238,6 +250,7 @@ impl ProcessSystemOperations {
     fn start_update(
         &self,
         target_version: Option<String>,
+        preflight: Arc<dyn SystemUpdatePreflight>,
     ) -> Result<SystemOperationAccepted, OperationError> {
         let operation_lock = Arc::clone(&self.operation_lock)
             .try_lock_owned()
@@ -282,7 +295,7 @@ impl ProcessSystemOperations {
             let result = tokio::select! {
                 biased;
                 () = service.cancellation.cancelled() => Err(conflict("服务关闭，更新已中断")),
-                result = service.perform_update_inner(&target, &operation_id) => result,
+                result = service.perform_update_inner(&target, &operation_id, preflight.as_ref()) => result,
             };
             if let Err(error) = operation.complete(&result) {
                 tracing::warn!(error = %error, "系统更新终态落盘失败");
@@ -308,6 +321,7 @@ impl ProcessSystemOperations {
         &self,
         target: &str,
         operation_id: &str,
+        preflight: &dyn SystemUpdatePreflight,
     ) -> Result<(), OperationError> {
         let repository = self
             .config
@@ -338,7 +352,8 @@ impl ProcessSystemOperations {
             Some("prepare"),
             format!("准备更新到 v{target}"),
         );
-        self.install_release(&release, target, operation_id).await
+        self.install_release(&release, target, operation_id, preflight)
+            .await
     }
 
     async fn install_release(
@@ -346,6 +361,7 @@ impl ProcessSystemOperations {
         release: &release::GitHubRelease,
         version: &str,
         operation_id: &str,
+        preflight: &dyn SystemUpdatePreflight,
     ) -> Result<(), OperationError> {
         self.events.info(
             Some(operation_id),
@@ -413,6 +429,23 @@ impl ProcessSystemOperations {
         let extracted = extract_release(&archive_path, temp.path())?;
         self.events
             .success(Some(operation_id), Some("extract"), "更新包解压完成");
+        let release_manifest = read_release_manifest(&extracted.official_plugins_dir)?;
+        let candidate = SystemUpdateCandidate {
+            target_version: version.to_owned(),
+            release_manifest: release_manifest.clone(),
+        };
+        self.events.info(
+            Some(operation_id),
+            Some("preflight"),
+            "正在检查启用插件与目标版本的兼容性",
+        );
+        let plugin_revision = preflight.validate(candidate).await?;
+        preflight.confirm_revision(plugin_revision).await?;
+        self.events.success(
+            Some(operation_id),
+            Some("preflight"),
+            "启用插件兼容性检查通过",
+        );
         self.events
             .info(Some(operation_id), Some("replace"), "正在替换应用文件");
         replace_release_files(
@@ -420,6 +453,15 @@ impl ProcessSystemOperations {
             self.config.web_dist_dir()?,
             extracted,
         )?;
+        let mut applied = AppliedReleaseGuard::new(&self.config);
+        let applied_manifest = read_release_manifest(&self.config.official_plugins_dir()?)?;
+        if applied_manifest.as_ref() != release_manifest.as_ref() {
+            return Err(applied.rollback(conflict("已应用的更新候选与预检候选不一致")));
+        }
+        if let Err(error) = preflight.confirm_revision(plugin_revision).await {
+            return Err(applied.rollback(error));
+        }
+        applied.commit();
         self.events
             .success(Some(operation_id), Some("replace"), "应用文件替换完成");
         Ok(())
@@ -478,8 +520,9 @@ impl SystemOperations for ProcessSystemOperations {
     async fn perform_update(
         &self,
         target_version: Option<String>,
+        preflight: Arc<dyn SystemUpdatePreflight>,
     ) -> Result<SystemOperationAccepted, OperationError> {
-        self.start_update(target_version)
+        self.start_update(target_version, preflight)
     }
 
     async fn update_status(&self) -> Result<SystemUpdateStatus, OperationError> {
@@ -492,7 +535,10 @@ impl SystemOperations for ProcessSystemOperations {
         read_status(&self.config.update_state_file, &self.config.version)
     }
 
-    async fn rollback(&self) -> Result<SystemOperationAccepted, OperationError> {
+    async fn rollback(
+        &self,
+        preflight: Arc<dyn SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, OperationError> {
         let _operation = self
             .operation_lock
             .try_lock()
@@ -502,6 +548,18 @@ impl SystemOperations for ProcessSystemOperations {
         }
         let operation_id = operation_id("rollback");
         let file_lock = OperationFileLock::acquire(&self.config.update_lock_file)?;
+        let target_version = read_status(&self.config.update_state_file, &self.config.version)?
+            .previous_version
+            .ok_or_else(|| conflict("没有可用于回滚的上一版本"))?;
+        let release_manifest =
+            read_release_manifest(&rollback_official_plugins_dir(&self.config)?)?;
+        let plugin_revision = preflight
+            .validate(SystemUpdateCandidate {
+                target_version,
+                release_manifest: Arc::clone(&release_manifest),
+            })
+            .await?;
+        preflight.confirm_revision(plugin_revision).await?;
         set_running(
             &self.config.update_state_file,
             &operation_id,
@@ -509,7 +567,26 @@ impl SystemOperations for ProcessSystemOperations {
             None,
             &self.config.version,
         )?;
-        let result = rollback_release(&self.config);
+        let result = match rollback_release(&self.config) {
+            Ok(()) => {
+                let mut applied = AppliedReleaseGuard::new(&self.config);
+                let result = match read_release_manifest(&self.config.official_plugins_dir()?) {
+                    Ok(manifest) if manifest.as_ref() == release_manifest.as_ref() => {
+                        preflight.confirm_revision(plugin_revision).await
+                    }
+                    Ok(_) => Err(conflict("已应用的回滚候选与预检候选不一致")),
+                    Err(error) => Err(error),
+                };
+                match result {
+                    Ok(()) => {
+                        applied.commit();
+                        Ok(())
+                    }
+                    Err(error) => Err(applied.rollback(error)),
+                }
+            }
+            Err(error) => Err(error),
+        };
         finish(
             &self.config.update_state_file,
             &operation_id,
@@ -566,6 +643,63 @@ impl SystemOperations for ProcessSystemOperations {
     }
 }
 
+fn read_release_manifest(directory: &Path) -> Result<Arc<[u8]>, OperationError> {
+    let path = directory.join(OFFICIAL_PLUGIN_MANIFEST);
+    let metadata = fs::symlink_metadata(&path)
+        .map_err(|error| invalid(format!("official plugin manifest is unavailable: {error}")))?;
+    if !metadata.file_type().is_file() || metadata.file_type().is_symlink() {
+        return Err(invalid("official plugin manifest is not a regular file"));
+    }
+    if metadata.len() == 0 || metadata.len() > MAX_OFFICIAL_PLUGIN_MANIFEST_SIZE {
+        return Err(invalid("official plugin manifest size is invalid"));
+    }
+    fs::read(path)
+        .map(Arc::<[u8]>::from)
+        .map_err(|error| invalid(format!("official plugin manifest cannot be read: {error}")))
+}
+
+fn restore_applied_release(config: &SystemUpdateConfig, cause: OperationError) -> OperationError {
+    match rollback_release(config) {
+        Ok(()) => cause,
+        Err(error) => internal(format!(
+            "release verification failed and restoring the previous files failed: {error}"
+        )),
+    }
+}
+
+struct AppliedReleaseGuard<'a> {
+    config: &'a SystemUpdateConfig,
+    armed: bool,
+}
+
+impl<'a> AppliedReleaseGuard<'a> {
+    const fn new(config: &'a SystemUpdateConfig) -> Self {
+        Self {
+            config,
+            armed: true,
+        }
+    }
+
+    const fn commit(&mut self) {
+        self.armed = false;
+    }
+
+    fn rollback(mut self, cause: OperationError) -> OperationError {
+        self.armed = false;
+        restore_applied_release(self.config, cause)
+    }
+}
+
+impl Drop for AppliedReleaseGuard<'_> {
+    fn drop(&mut self) {
+        if self.armed
+            && let Err(error) = rollback_release(self.config)
+        {
+            tracing::error!(error = %error, "系统发行物临界区取消后的恢复失败");
+        }
+    }
+}
+
 fn base_update_detail(
     config: &SystemUpdateConfig,
     unsupported_reason: Option<String>,
diff --git a/backend/crates/gateway-host/src/system_update/swap.rs b/backend/crates/gateway-host/src/system_update/swap.rs
index 007e26a5a..292ee8b8b 100644
--- a/backend/crates/gateway-host/src/system_update/swap.rs
+++ b/backend/crates/gateway-host/src/system_update/swap.rs
@@ -13,12 +13,54 @@ pub(crate) fn replace_release_files(
     web_dist: &Path,
     extracted: ExtractedRelease,
 ) -> Result<(), OperationError> {
+    let official_plugins = official_plugins_dir(executable)?;
+    if !official_plugins.exists() {
+        fs::create_dir_all(&official_plugins).map_err(|error| {
+            internal(format!(
+                "failed to prepare official plugin rollback directory: {error}"
+            ))
+        })?;
+    }
+    let official_backup = backup_path_for(&official_plugins);
+    replace_dir(
+        &official_plugins,
+        &official_backup,
+        &extracted.official_plugins_dir,
+        "official plugin assets",
+    )?;
+    if let Err(error) = protect_official_plugins(&official_plugins) {
+        let mut rollback = Vec::new();
+        collect_rollback_error(
+            &mut rollback,
+            "restore official plugin assets",
+            restore_dir(&official_plugins, &official_backup),
+        );
+        return Err(error_with_rollback(
+            "failed to protect official plugin assets",
+            error,
+            rollback,
+        ));
+    }
+
     let web_backup = backup_path_for(web_dist);
-    let web_replaced = if let Some(new_web) = extracted.web_dist_dir {
-        replace_dir(web_dist, &web_backup, &new_web)?;
-        true
-    } else {
-        false
+    let web_replaced = match extracted.web_dist_dir {
+        Some(new_web) => {
+            if let Err(error) = replace_dir(web_dist, &web_backup, &new_web, "web assets") {
+                let mut rollback = Vec::new();
+                collect_rollback_error(
+                    &mut rollback,
+                    "restore official plugin assets",
+                    restore_dir(&official_plugins, &official_backup),
+                );
+                return Err(error_with_rollback(
+                    "failed to replace web assets",
+                    error,
+                    rollback,
+                ));
+            }
+            true
+        }
+        None => false,
     };
 
     let binary_backup = backup_path_for(executable);
@@ -33,6 +75,11 @@ pub(crate) fn replace_release_files(
                 restore_dir(web_dist, &web_backup),
             );
         }
+        collect_rollback_error(
+            &mut rollback,
+            "restore official plugin assets",
+            restore_dir(&official_plugins, &official_backup),
+        );
         return Err(error_with_rollback(
             "failed to remove old binary backup",
             error,
@@ -48,6 +95,11 @@ pub(crate) fn replace_release_files(
                 restore_dir(web_dist, &web_backup),
             );
         }
+        collect_rollback_error(
+            &mut rollback,
+            "restore official plugin assets",
+            restore_dir(&official_plugins, &official_backup),
+        );
         return Err(error_with_rollback("binary backup failed", error, rollback));
     }
     if let Err(error) = move_file(&extracted.binary_path, executable) {
@@ -71,6 +123,11 @@ pub(crate) fn replace_release_files(
                 restore_dir(web_dist, &web_backup),
             );
         }
+        collect_rollback_error(
+            &mut rollback,
+            "restore official plugin assets",
+            restore_dir(&official_plugins, &official_backup),
+        );
         return Err(error_with_rollback(
             "binary replace failed",
             error,
@@ -102,29 +159,74 @@ pub(crate) fn rollback_release(config: &SystemUpdateConfig) -> Result<(), Operat
         );
         return Err(error_with_rollback("web rollback failed", error, rollback));
     }
+    let official_plugins = config.official_plugins_dir()?;
+    let official_backup = backup_path_for(&official_plugins);
+    if official_backup.exists()
+        && let Err(error) = swap_dir(&official_plugins, &official_backup)
+    {
+        let mut rollback = Vec::new();
+        if web_backup.exists() {
+            collect_rollback_error(
+                &mut rollback,
+                "restore web assets after official plugin rollback failure",
+                swap_dir(web_dist, &web_backup),
+            );
+        }
+        collect_rollback_error(
+            &mut rollback,
+            "restore binary after official plugin rollback failure",
+            swap_file(&executable, &binary_backup),
+        );
+        return Err(error_with_rollback(
+            "official plugin rollback failed",
+            error,
+            rollback,
+        ));
+    }
     Ok(())
 }
 
-fn replace_dir(current: &Path, backup: &Path, replacement: &Path) -> Result<(), OperationError> {
+pub(crate) fn rollback_official_plugins_dir(
+    config: &SystemUpdateConfig,
+) -> Result<PathBuf, OperationError> {
+    config
+        .official_plugins_dir()
+        .map(|directory| backup_path_for(&directory))
+}
+
+fn official_plugins_dir(executable: &Path) -> Result<PathBuf, OperationError> {
+    executable
+        .parent()
+        .filter(|path| !path.as_os_str().is_empty())
+        .map(|path| path.join("plugins").join("official"))
+        .ok_or_else(|| internal("failed to resolve official plugin release directory"))
+}
+
+fn replace_dir(
+    current: &Path,
+    backup: &Path,
+    replacement: &Path,
+    label: &'static str,
+) -> Result<(), OperationError> {
     if backup.exists() {
-        fs::remove_dir_all(backup)
-            .map_err(|error| internal(format!("failed to remove old web backup: {error}")))?;
+        remove_dir_all(backup)
+            .map_err(|error| internal(format!("failed to remove old {label} backup: {error}")))?;
     }
     if current.exists() {
         move_dir(current, backup)
-            .map_err(|error| internal(format!("failed to backup web assets: {error}")))?;
+            .map_err(|error| internal(format!("failed to backup {label}: {error}")))?;
     }
     if let Err(error) = move_dir(replacement, current) {
         let mut rollback = Vec::new();
         if backup.exists() {
             collect_rollback_error(
                 &mut rollback,
-                "restore previous web assets",
+                "restore previous directory contents",
                 restore_dir(current, backup),
             );
         }
         return Err(error_with_rollback(
-            "failed to replace web assets",
+            "failed to replace directory contents",
             error,
             rollback,
         ));
@@ -166,7 +268,7 @@ fn swap_dir(current: &Path, backup: &Path) -> io::Result<()> {
     }
     let swap = swap_path_for(current);
     if swap.exists() {
-        fs::remove_dir_all(&swap)?;
+        remove_dir_all(&swap)?;
     }
     move_dir(current, &swap)?;
     if let Err(error) = move_dir(backup, current) {
@@ -184,7 +286,7 @@ fn swap_dir(current: &Path, backup: &Path) -> io::Result<()> {
 
 fn restore_dir(current: &Path, backup: &Path) -> io::Result<()> {
     if current.exists() {
-        fs::remove_dir_all(current)?;
+        remove_dir_all(current)?;
     }
     if backup.exists() {
         move_dir(backup, current)?;
@@ -211,16 +313,65 @@ fn move_dir(from: &Path, to: &Path) -> io::Result<()> {
         Ok(()) => Ok(()),
         Err(error) if error.kind() == io::ErrorKind::CrossesDevices => {
             if let Err(copy_error) = copy_dir_all(from, to) {
-                let _ = fs::remove_dir_all(to);
+                let _ = remove_dir_all(to);
                 return Err(copy_error);
             }
-            fs::remove_dir_all(from)
+            remove_dir_all(from)
         }
-        Err(error) => Err(error),
+        Err(error) => Err(io::Error::new(
+            error.kind(),
+            format!("directory rename failed: {error}"),
+        )),
     }
 }
 
+#[cfg(unix)]
+fn protect_official_plugins(path: &Path) -> io::Result<()> {
+    use std::os::unix::fs::PermissionsExt as _;
+
+    fs::set_permissions(path, fs::Permissions::from_mode(0o555))
+}
+
+#[cfg(not(unix))]
+fn protect_official_plugins(_path: &Path) -> io::Result<()> {
+    Ok(())
+}
+
+fn remove_dir_all(path: &Path) -> io::Result<()> {
+    #[cfg(unix)]
+    make_directories_writable(path)?;
+    fs::remove_dir_all(path)
+}
+
+#[cfg(unix)]
+fn make_directories_writable(path: &Path) -> io::Result<()> {
+    use std::os::unix::fs::PermissionsExt as _;
+
+    let metadata = fs::symlink_metadata(path)?;
+    if !metadata.is_dir() || metadata.file_type().is_symlink() {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidData,
+            "release directory contains an unsupported file type",
+        ));
+    }
+    fs::set_permissions(path, fs::Permissions::from_mode(0o700))?;
+    for entry in fs::read_dir(path)? {
+        let entry = entry?;
+        let file_type = entry.file_type()?;
+        if file_type.is_dir() {
+            make_directories_writable(&entry.path())?;
+        } else if !file_type.is_file() {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidData,
+                "release directory contains an unsupported file type",
+            ));
+        }
+    }
+    Ok(())
+}
+
 fn copy_dir_all(from: &Path, to: &Path) -> io::Result<()> {
+    let permissions = fs::metadata(from)?.permissions();
     fs::create_dir_all(to)?;
     for entry in fs::read_dir(from)? {
         let entry = entry?;
@@ -238,6 +389,7 @@ fn copy_dir_all(from: &Path, to: &Path) -> io::Result<()> {
             ));
         }
     }
+    fs::set_permissions(to, permissions)?;
     Ok(())
 }
 
diff --git a/backend/crates/gateway-host/tests/logging/mod.rs b/backend/crates/gateway-host/tests/logging/mod.rs
index db72be4f9..eeed6d4e9 100644
--- a/backend/crates/gateway-host/tests/logging/mod.rs
+++ b/backend/crates/gateway-host/tests/logging/mod.rs
@@ -151,6 +151,48 @@ fn sensitive_file_logging_is_separate_and_overrides_global_log_level() {
     assert!(!application_log.contains(REQUEST_DUMP_SECRET));
 }
 
+#[test]
+fn shutdown_logs_remain_visible_on_stdout_with_file_logging_enabled() {
+    const MARKER: &str = "shutdown-reason-test";
+    if env::var_os(CHILD_PROCESS_ENV).is_some() {
+        let mut config = logging_config(
+            PathBuf::from(env::var_os(LOG_DIRECTORY_ENV).unwrap()),
+            false,
+        );
+        config.logging.stdout = true;
+        with_logging(config, || {
+            tracing::info!(target: "gateway_shutdown", reason = "sigterm", marker = MARKER);
+            tracing::info!(target: APPLICATION_LOG_TARGET, marker = APPLICATION_LOG_MARKER);
+        });
+        return;
+    }
+
+    let directory = tempfile::tempdir().unwrap();
+    let output = Command::new(env::current_exe().unwrap())
+        .args([
+            "--exact",
+            "logging::shutdown_logs_remain_visible_on_stdout_with_file_logging_enabled",
+            "--nocapture",
+        ])
+        .env(CHILD_PROCESS_ENV, "1")
+        .env(LOG_DIRECTORY_ENV, directory.path())
+        .env("RUST_LOG", "info")
+        .output()
+        .unwrap();
+    assert!(
+        output.status.success(),
+        "{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(stdout.contains(MARKER));
+    assert!(stdout.contains("sigterm"));
+    assert!(!stdout.contains(APPLICATION_LOG_MARKER));
+    let application_log = read_log_file_set(directory.path(), APPLICATION_LOG_FILE_PREFIX);
+    assert!(application_log.contains(MARKER));
+    assert!(application_log.contains(APPLICATION_LOG_MARKER));
+}
+
 #[test]
 fn oauth_recovery_switch_controls_only_its_dedicated_file() {
     const OAUTH_ENABLED_ENV: &str = "CPR_LOGGING_TEST_OAUTH_ENABLED";
diff --git a/backend/crates/gateway-host/tests/main.rs b/backend/crates/gateway-host/tests/main.rs
index f99f3a2dd..ffff276ae 100644
--- a/backend/crates/gateway-host/tests/main.rs
+++ b/backend/crates/gateway-host/tests/main.rs
@@ -1,8 +1,13 @@
 mod client_distribution;
 mod config;
 mod logging;
+mod official_plugins;
+mod outbound;
+mod plugin_distribution;
 mod pricing;
+mod process;
 mod proxy_probe;
 mod serve;
+mod support;
 mod system_update;
 mod workers;
diff --git a/backend/crates/gateway-host/tests/official_plugins.rs b/backend/crates/gateway-host/tests/official_plugins.rs
new file mode 100644
index 000000000..923dc8e5f
--- /dev/null
+++ b/backend/crates/gateway-host/tests/official_plugins.rs
@@ -0,0 +1,94 @@
+use std::fs;
+
+use gateway_admin::ports::plugin_release::{
+    OfficialPluginReleaseFiles as _, OfficialPluginReleaseReadErrorKind,
+};
+use gateway_host::official_plugins::FileOfficialPluginRelease;
+
+#[tokio::test]
+async fn release_files_are_absent_or_read_from_one_flat_bounded_directory() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let directory = temp.path().join("plugins/official");
+    let source = FileOfficialPluginRelease::new(directory.clone());
+    assert!(source.manifest().await.expect("absent manifest").is_none());
+
+    fs::create_dir_all(&directory).expect("release directory");
+    fs::write(directory.join("plugin-release-manifest.json"), b"manifest").expect("manifest");
+    fs::write(directory.join("example.tar.gz"), b"archive").expect("archive");
+    assert_eq!(
+        source.manifest().await.expect("manifest").unwrap().as_ref(),
+        b"manifest"
+    );
+    assert_eq!(
+        source
+            .artifact("example.tar.gz")
+            .await
+            .expect("archive")
+            .as_ref(),
+        b"archive"
+    );
+    assert_eq!(
+        source
+            .artifact("../example.tar.gz")
+            .await
+            .expect_err("path escape")
+            .kind(),
+        OfficialPluginReleaseReadErrorKind::Invalid
+    );
+}
+
+#[tokio::test]
+async fn release_files_reject_symlinks_and_oversized_manifests() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let directory = temp.path().join("official");
+    fs::create_dir_all(&directory).expect("release directory");
+    let source = FileOfficialPluginRelease::new(directory.clone());
+    fs::write(
+        directory.join("plugin-release-manifest.json"),
+        vec![b'x'; 256 * 1024 + 1],
+    )
+    .expect("large manifest");
+    assert_eq!(
+        source
+            .manifest()
+            .await
+            .expect_err("oversized manifest")
+            .kind(),
+        OfficialPluginReleaseReadErrorKind::Invalid
+    );
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::symlink;
+
+        let target = temp.path().join("target.tar.gz");
+        fs::write(&target, b"archive").expect("target");
+        symlink(&target, directory.join("linked.tar.gz")).expect("symlink");
+        assert_eq!(
+            source
+                .artifact("linked.tar.gz")
+                .await
+                .expect_err("symlink")
+                .kind(),
+            OfficialPluginReleaseReadErrorKind::Invalid
+        );
+
+        let release_target = temp.path().join("release-target");
+        fs::create_dir(&release_target).expect("release target");
+        fs::write(
+            release_target.join("plugin-release-manifest.json"),
+            b"manifest",
+        )
+        .expect("target manifest");
+        let release_link = temp.path().join("release-link");
+        symlink(&release_target, &release_link).expect("release directory symlink");
+        assert_eq!(
+            FileOfficialPluginRelease::new(release_link)
+                .manifest()
+                .await
+                .expect_err("release directory symlink")
+                .kind(),
+            OfficialPluginReleaseReadErrorKind::Invalid
+        );
+    }
+}
diff --git a/backend/crates/gateway-host/tests/outbound/connector.rs b/backend/crates/gateway-host/tests/outbound/connector.rs
new file mode 100644
index 000000000..9eef1f5cc
--- /dev/null
+++ b/backend/crates/gateway-host/tests/outbound/connector.rs
@@ -0,0 +1,144 @@
+use std::{sync::Arc, time::Duration};
+
+use gateway_core::{account::OutboundProxy, upstream::UpstreamSendState};
+use gateway_host::outbound::{HttpClient, HttpRequest, NetworkPolicy};
+
+use crate::support::network::{FixedDns, Mode, ROOT, Server};
+
+fn request(port: u16, secure: bool) -> HttpRequest {
+    HttpRequest {
+        method: "GET".into(),
+        url: format!(
+            "{}://upstream.test:{port}/query?value=1",
+            if secure { "https" } else { "http" }
+        ),
+        headers: vec![],
+        body: vec![],
+    }
+}
+
+fn network() -> NetworkPolicy {
+    NetworkPolicy::new(&["127.0.0.0/8".into(), "::1/128".into()]).unwrap()
+}
+
+#[tokio::test]
+async fn pinned_connections_preserve_host_and_sni_for_direct_and_authenticated_proxies() {
+    for proxy_kind in ["direct", "http", "https", "socks5", "socks5h"] {
+        for secure in [false, true] {
+            let mut upstream = Server::start(Mode::Origin, secure, "127.0.0.1:0").await;
+            let mut proxy = match proxy_kind {
+                "direct" => None,
+                "http" | "https" => {
+                    Some(Server::start(Mode::HttpProxy, proxy_kind == "https", "127.0.0.1:0").await)
+                }
+                _ => Some(Server::start(Mode::Socks, false, "127.0.0.1:0").await),
+            };
+            let route = proxy.as_ref().map(|proxy| {
+                OutboundProxy::parse(&format!(
+                    "{proxy_kind}://user:p%40ss@localhost:{}",
+                    proxy.address.port()
+                ))
+                .unwrap()
+            });
+            let client = HttpClient::with_root_certificates(vec![ROOT.to_vec()])
+                .unwrap()
+                .with_resolver(Arc::new(FixedDns(upstream.address.ip())));
+            let mut response = client
+                .open(
+                    request(upstream.address.port(), secure),
+                    route.as_ref(),
+                    &network(),
+                    Duration::from_secs(3),
+                )
+                .await
+                .unwrap_or_else(|error| panic!("{proxy_kind}, tls={secure}: {error:?}"));
+            assert_eq!(response.status, 200);
+            assert_eq!(response.body.read(64).await.unwrap().unwrap(), "secured");
+            assert!(response.body.read(64).await.unwrap().is_none());
+            let observation = upstream.next().await;
+            assert!(
+                observation
+                    .head
+                    .starts_with("GET /query?value=1 HTTP/1.1\r\n")
+            );
+            assert!(observation.head.to_ascii_lowercase().contains(&format!(
+                "host: upstream.test:{}\r\n",
+                upstream.address.port()
+            )));
+            assert!(
+                !observation
+                    .head
+                    .to_ascii_lowercase()
+                    .contains("proxy-authorization")
+            );
+            assert_eq!(
+                observation.sni.as_deref(),
+                secure.then_some("upstream.test")
+            );
+            if let Some(proxy) = &mut proxy {
+                let observation = proxy.next().await;
+                assert_eq!(observation.target, Some(upstream.address));
+                if proxy_kind.starts_with("http") {
+                    assert!(
+                        observation
+                            .head
+                            .to_ascii_lowercase()
+                            .contains("proxy-authorization: basic dxnlcjpwqhnz\r\n")
+                    );
+                    assert_eq!(
+                        observation.sni.as_deref(),
+                        (proxy_kind == "https").then_some("localhost")
+                    );
+                } else {
+                    assert_eq!(
+                        observation.authentication,
+                        Some(("user".into(), "p@ss".into()))
+                    );
+                }
+            }
+        }
+    }
+}
+
+#[tokio::test]
+async fn pinning_never_disables_certificate_or_hostname_validation() {
+    for trusted in [false, true] {
+        let upstream = Server::start(Mode::Origin, true, "127.0.0.1:0").await;
+        let client =
+            HttpClient::with_root_certificates(if trusted { vec![ROOT.to_vec()] } else { vec![] })
+                .unwrap()
+                .with_resolver(Arc::new(FixedDns(upstream.address.ip())));
+        let mut request = request(upstream.address.port(), true);
+        if trusted {
+            request.url = request.url.replace("upstream.test", "different.test");
+        }
+        let error = client
+            .open(request, None, &network(), Duration::from_secs(3))
+            .await
+            .err()
+            .unwrap();
+        assert_eq!(error.send_state, UpstreamSendState::NotSent);
+    }
+}
+
+#[tokio::test]
+async fn socks_pins_ipv6_without_sending_a_bracketed_hostname() {
+    let mut upstream = Server::start(Mode::Origin, false, "[::1]:0").await;
+    let mut proxy = Server::start(Mode::Socks, false, "127.0.0.1:0").await;
+    let route = OutboundProxy::parse(&format!("socks5h://user:pass@{}", proxy.address)).unwrap();
+    let client = HttpClient::new()
+        .unwrap()
+        .with_resolver(Arc::new(FixedDns(upstream.address.ip())));
+    let response = client
+        .open(
+            request(upstream.address.port(), false),
+            Some(&route),
+            &network(),
+            Duration::from_secs(3),
+        )
+        .await
+        .unwrap();
+    assert_eq!(response.status, 200);
+    assert_eq!(proxy.next().await.target, Some(upstream.address));
+    assert!(upstream.next().await.head.starts_with("GET /query"));
+}
diff --git a/backend/crates/gateway-host/tests/outbound/http.rs b/backend/crates/gateway-host/tests/outbound/http.rs
new file mode 100644
index 000000000..02179311d
--- /dev/null
+++ b/backend/crates/gateway-host/tests/outbound/http.rs
@@ -0,0 +1,228 @@
+use std::time::Duration;
+
+use gateway_core::{account::OutboundProxy, upstream::UpstreamSendState};
+use gateway_host::outbound::{HttpClient, HttpErrorKind, HttpRequest, NetworkPolicy};
+use wiremock::{Mock, MockServer, ResponseTemplate, matchers::any};
+
+fn request(url: String) -> HttpRequest {
+    HttpRequest {
+        method: "GET".into(),
+        url,
+        headers: vec![],
+        body: vec![],
+    }
+}
+
+fn local_network() -> NetworkPolicy {
+    NetworkPolicy::new(&["127.0.0.0/8".into(), "::1/128".into()]).unwrap()
+}
+
+#[tokio::test]
+async fn managed_http_does_not_follow_redirects_or_fall_back_from_proxy() {
+    let server = MockServer::start().await;
+    Mock::given(any())
+        .respond_with(
+            ResponseTemplate::new(302).insert_header("location", "http://unresolvable.invalid/"),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+    let client = HttpClient::new().unwrap();
+    let response = client
+        .open(
+            request(server.uri()),
+            None,
+            &local_network(),
+            Duration::from_secs(2),
+        )
+        .await
+        .unwrap();
+    assert_eq!(response.status, 302);
+    drop(response);
+    let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+    let proxy =
+        OutboundProxy::parse(&format!("http://{}", listener.local_addr().unwrap())).unwrap();
+    drop(listener);
+    let error = client
+        .open(
+            request(server.uri()),
+            Some(&proxy),
+            &local_network(),
+            Duration::from_secs(2),
+        )
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.send_state, UpstreamSendState::NotSent);
+    assert_eq!(error.kind(), HttpErrorKind::Transport);
+}
+
+#[tokio::test]
+async fn managed_http_caps_chunks_and_recovers_capacity_after_body_drop() {
+    let server = MockServer::start().await;
+    Mock::given(any())
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(vec![42; 300_000]))
+        .mount(&server)
+        .await;
+    let client = HttpClient::new().unwrap();
+    let mut response = client
+        .open(
+            request(server.uri()),
+            None,
+            &local_network(),
+            Duration::from_secs(5),
+        )
+        .await
+        .unwrap();
+    let mut size = 0;
+    while let Some(chunk) = response.body.read(1003).await.unwrap() {
+        assert!(chunk.len() <= 1003);
+        assert!(chunk.iter().all(|byte| *byte == 42));
+        size += chunk.len();
+    }
+    assert_eq!(size, 300_000);
+    drop(response);
+    let mut bodies = Vec::new();
+    for _ in 0..128 {
+        bodies.push(
+            client
+                .open(
+                    request(server.uri()),
+                    None,
+                    &local_network(),
+                    Duration::from_secs(5),
+                )
+                .await
+                .unwrap(),
+        );
+    }
+    assert_eq!(
+        client
+            .open(
+                request(server.uri()),
+                None,
+                &local_network(),
+                Duration::from_secs(5)
+            )
+            .await
+            .err()
+            .unwrap()
+            .send_state,
+        UpstreamSendState::NotSent
+    );
+    bodies.pop();
+    assert!(
+        client
+            .open(
+                request(server.uri()),
+                None,
+                &local_network(),
+                Duration::from_secs(5)
+            )
+            .await
+            .is_ok()
+    );
+}
+
+#[tokio::test]
+async fn managed_http_deadline_and_invalid_headers_preserve_send_facts() {
+    let server = MockServer::start().await;
+    Mock::given(any())
+        .respond_with(ResponseTemplate::new(200).set_delay(Duration::from_millis(300)))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let client = HttpClient::new().unwrap();
+    let mut invalid = request(server.uri());
+    invalid
+        .headers
+        .push(("proxy-authorization".into(), b"secret-test-only".to_vec()));
+    let error = client
+        .open(invalid, None, &local_network(), Duration::from_secs(2))
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.send_state, UpstreamSendState::NotSent);
+    assert_eq!(error.kind(), HttpErrorKind::InvalidRequest);
+    assert!(!format!("{error:?}").contains("secret-test-only"));
+    let error = client
+        .open(
+            request(server.uri()),
+            None,
+            &local_network(),
+            Duration::from_millis(100),
+        )
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.send_state, UpstreamSendState::Ambiguous);
+    assert_eq!(error.kind(), HttpErrorKind::Timeout);
+}
+
+#[tokio::test]
+async fn buffered_body_cannot_extend_the_request_deadline() {
+    let server = MockServer::start().await;
+    Mock::given(any())
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(vec![42; 1024]))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let client = HttpClient::new().unwrap();
+    let mut response = client
+        .open(
+            request(server.uri()),
+            None,
+            &local_network(),
+            Duration::from_millis(300),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        response.body.read(1).await.unwrap().unwrap().as_ref(),
+        &[42]
+    );
+    // 上游已返回整块数据，插件延迟读取也不能绕过调用期限。
+    tokio::time::sleep(Duration::from_millis(320)).await;
+    let error = response.body.read(1).await.unwrap_err();
+    assert_eq!(error.send_state, UpstreamSendState::Sent);
+    assert_eq!(error.kind(), HttpErrorKind::Timeout);
+}
+
+#[tokio::test]
+async fn cancelling_dns_releases_the_request_slot_without_starting_http() {
+    use std::sync::Arc;
+
+    use futures::future::BoxFuture;
+    use gateway_host::outbound::DnsResolver;
+
+    struct PendingDns;
+    impl DnsResolver for PendingDns {
+        fn resolve(
+            &self,
+            _: String,
+            _: u16,
+        ) -> BoxFuture<'static, std::io::Result<Vec<std::net::SocketAddr>>> {
+            Box::pin(std::future::pending())
+        }
+    }
+
+    let client = HttpClient::new()
+        .unwrap()
+        .with_resolver(Arc::new(PendingDns));
+    // 超过总并发容量，逐次取消仍不能积累占用。
+    for _ in 0..129 {
+        assert!(
+            tokio::time::timeout(
+                Duration::from_millis(1),
+                client.open(
+                    request("https://pending.invalid/".into()),
+                    None,
+                    &NetworkPolicy::default(),
+                    Duration::from_secs(1),
+                ),
+            )
+            .await
+            .is_err()
+        );
+    }
+}
diff --git a/backend/crates/gateway-host/tests/outbound/mod.rs b/backend/crates/gateway-host/tests/outbound/mod.rs
new file mode 100644
index 000000000..083c5c23e
--- /dev/null
+++ b/backend/crates/gateway-host/tests/outbound/mod.rs
@@ -0,0 +1,3 @@
+mod connector;
+mod http;
+mod network;
diff --git a/backend/crates/gateway-host/tests/outbound/network.rs b/backend/crates/gateway-host/tests/outbound/network.rs
new file mode 100644
index 000000000..7bdecb04a
--- /dev/null
+++ b/backend/crates/gateway-host/tests/outbound/network.rs
@@ -0,0 +1,255 @@
+use std::{
+    net::SocketAddr,
+    sync::{
+        Arc,
+        atomic::{AtomicUsize, Ordering},
+    },
+    time::Duration,
+};
+
+use futures::future::BoxFuture;
+use gateway_core::upstream::UpstreamSendState;
+use gateway_host::outbound::{DnsResolver, HttpClient, HttpErrorKind, HttpRequest, NetworkPolicy};
+use wiremock::{Mock, MockServer, ResponseTemplate, matchers::any};
+
+use crate::support::network::FixedDns;
+
+#[test]
+fn private_special_and_mapped_addresses_require_explicit_ranges() {
+    let policy = NetworkPolicy::default();
+    for ip in [
+        "0.0.0.0",
+        "10.0.0.1",
+        "100.64.0.1",
+        "127.0.0.1",
+        "169.254.169.254",
+        "172.16.0.1",
+        "192.168.0.1",
+        "192.0.2.1",
+        "198.18.0.1",
+        "198.51.100.1",
+        "203.0.113.1",
+        "224.0.0.1",
+        "240.0.0.1",
+        "255.255.255.255",
+        "::",
+        "::1",
+        "::ffff:127.0.0.1",
+        "fc00::1",
+        "fe80::1",
+        "ff02::1",
+        "64:ff9b::7f00:1",
+        "2001:db8::1",
+        "2002:7f00:1::",
+        "3fff::1",
+    ] {
+        assert!(
+            !policy.permits(ip.parse().unwrap()),
+            "unexpected public address: {ip}"
+        );
+    }
+    for ip in [
+        "1.1.1.1",
+        "8.8.8.8",
+        "2606:4700:4700::1111",
+        "2001:4860:4860::8888",
+    ] {
+        assert!(policy.permits(ip.parse().unwrap()));
+    }
+    let granted = NetworkPolicy::new(&["127.0.0.1/32".into(), "fd12:3456::/32".into()]).unwrap();
+    assert!(granted.permits("::ffff:127.0.0.1".parse().unwrap()));
+    assert!(granted.permits("fd12:3456::1234".parse().unwrap()));
+    assert!(!granted.permits("127.0.0.2".parse().unwrap()));
+    assert!(NetworkPolicy::new(&["*".into()]).is_err());
+}
+
+struct ChangingDns {
+    calls: Arc<AtomicUsize>,
+    mixed: bool,
+}
+
+impl DnsResolver for ChangingDns {
+    fn resolve(
+        &self,
+        _: String,
+        port: u16,
+    ) -> BoxFuture<'static, std::io::Result<Vec<SocketAddr>>> {
+        let call = self.calls.fetch_add(1, Ordering::SeqCst);
+        let addresses = if self.mixed {
+            vec![
+                SocketAddr::from(([127, 0, 0, 1], port)),
+                SocketAddr::from(([127, 0, 0, 2], port)),
+            ]
+        } else {
+            vec![SocketAddr::from((
+                [127, 0, 0, if call == 0 { 1 } else { 2 }],
+                port,
+            ))]
+        };
+        Box::pin(async move { Ok(addresses) })
+    }
+}
+
+fn request(url: String) -> HttpRequest {
+    HttpRequest {
+        method: "GET".into(),
+        url,
+        headers: vec![],
+        body: vec![],
+    }
+}
+
+#[tokio::test]
+async fn dns_is_pinned_and_revalidated_even_when_a_pooled_connection_exists() {
+    let server = MockServer::start().await;
+    Mock::given(any())
+        .respond_with(ResponseTemplate::new(200).set_body_string("authorized"))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let calls = Arc::new(AtomicUsize::new(0));
+    let client = HttpClient::new()
+        .unwrap()
+        .with_resolver(Arc::new(ChangingDns {
+            calls: calls.clone(),
+            mixed: false,
+        }));
+    let network = NetworkPolicy::new(&["127.0.0.1/32".into()]).unwrap();
+    let url = format!("http://dns-rebinding.invalid:{}/", server.address().port());
+    let mut response = client
+        .open(request(url.clone()), None, &network, Duration::from_secs(3))
+        .await
+        .unwrap();
+    assert_eq!(
+        response.body.read(1024).await.unwrap().unwrap(),
+        "authorized"
+    );
+    assert!(response.body.read(1024).await.unwrap().is_none());
+    drop(response);
+    let error = client
+        .open(request(url), None, &network, Duration::from_secs(3))
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.send_state, UpstreamSendState::NotSent);
+    assert_eq!(error.kind(), HttpErrorKind::AddressDenied);
+    assert_eq!(calls.load(Ordering::SeqCst), 2);
+}
+
+#[tokio::test]
+async fn mixed_dns_answers_and_implicit_loopback_access_are_rejected_before_http() {
+    let server = MockServer::start().await;
+    Mock::given(any())
+        .respond_with(ResponseTemplate::new(200))
+        .expect(0)
+        .mount(&server)
+        .await;
+    let calls = Arc::new(AtomicUsize::new(0));
+    let client = HttpClient::new()
+        .unwrap()
+        .with_resolver(Arc::new(ChangingDns { calls, mixed: true }));
+    let network = NetworkPolicy::new(&["127.0.0.1/32".into()]).unwrap();
+    let error = client
+        .open(
+            request(format!("http://mixed.invalid:{}/", server.address().port())),
+            None,
+            &network,
+            Duration::from_secs(2),
+        )
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.send_state, UpstreamSendState::NotSent);
+    let error = client
+        .open(
+            request(server.uri()),
+            None,
+            &NetworkPolicy::default(),
+            Duration::from_secs(2),
+        )
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.send_state, UpstreamSendState::NotSent);
+}
+
+struct SlowDns;
+impl DnsResolver for SlowDns {
+    fn resolve(&self, _: String, _: u16) -> BoxFuture<'static, std::io::Result<Vec<SocketAddr>>> {
+        Box::pin(async {
+            tokio::time::sleep(Duration::from_secs(10)).await;
+            Ok(vec![])
+        })
+    }
+}
+
+#[tokio::test]
+async fn dns_consumes_the_same_deadline_and_timeout_is_not_sent() {
+    let client = HttpClient::new().unwrap().with_resolver(Arc::new(SlowDns));
+    let error = tokio::time::timeout(
+        Duration::from_secs(1),
+        client.open(
+            request("https://slow.invalid/".into()),
+            None,
+            &NetworkPolicy::default(),
+            Duration::from_millis(20),
+        ),
+    )
+    .await
+    .unwrap()
+    .err()
+    .unwrap();
+    assert_eq!(error.send_state, UpstreamSendState::NotSent);
+    assert_eq!(error.kind(), HttpErrorKind::Timeout);
+}
+
+#[tokio::test]
+async fn fake_ip_and_private_dns_answers_stay_denied_without_leaking_the_url() {
+    for ip in ["198.18.0.23", "127.0.0.1", "169.254.169.254", "10.0.0.1"] {
+        let client = HttpClient::new()
+            .unwrap()
+            .with_resolver(Arc::new(FixedDns(ip.parse().unwrap())));
+        let error = client
+            .open(
+                request("https://example.invalid/private?token=do-not-log".into()),
+                None,
+                &NetworkPolicy::default(),
+                Duration::from_secs(1),
+            )
+            .await
+            .err()
+            .unwrap();
+        assert_eq!(error.kind(), HttpErrorKind::AddressDenied);
+        assert_eq!(error.send_state, UpstreamSendState::NotSent);
+        assert_eq!(error.reason(), "network address not authorized");
+        assert!(!format!("{error:?} {error}").contains("do-not-log"));
+    }
+}
+
+struct FailingDns;
+
+impl DnsResolver for FailingDns {
+    fn resolve(&self, _: String, _: u16) -> BoxFuture<'static, std::io::Result<Vec<SocketAddr>>> {
+        Box::pin(async { Err(std::io::Error::other("resolver details must not escape")) })
+    }
+}
+
+#[tokio::test]
+async fn dns_failures_are_distinct_from_address_denials_and_transport_errors() {
+    let client = HttpClient::new()
+        .unwrap()
+        .with_resolver(Arc::new(FailingDns));
+    let error = client
+        .open(
+            request("https://example.invalid/".into()),
+            None,
+            &NetworkPolicy::default(),
+            Duration::from_secs(1),
+        )
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), HttpErrorKind::Dns);
+    assert_eq!(error.send_state, UpstreamSendState::NotSent);
+    assert!(!format!("{error:?} {error}").contains("resolver details"));
+}
diff --git a/backend/crates/gateway-host/tests/plugin_distribution/github.rs b/backend/crates/gateway-host/tests/plugin_distribution/github.rs
new file mode 100644
index 000000000..e72861e18
--- /dev/null
+++ b/backend/crates/gateway-host/tests/plugin_distribution/github.rs
@@ -0,0 +1,290 @@
+use gateway_admin::{
+    model::{
+        AdminErrorKind,
+        plugins::distribution::{
+            DownloadPurpose, GithubReleaseQuery, RemotePluginLocation, SourceAuthentication,
+        },
+    },
+    ports::plugins::PluginDistribution,
+};
+use serde_json::json;
+use wiremock::{Mock, MockServer, ResponseTemplate, matchers::path};
+
+use super::{credential_with, digest, transport};
+
+fn query(tag: Option<&str>) -> GithubReleaseQuery {
+    GithubReleaseQuery {
+        repository: "example/plugins".into(),
+        tag: tag.map(str::to_owned),
+        allow_prerelease: false,
+    }
+}
+
+fn release() -> serde_json::Value {
+    json!({"tag_name":"v1.0.0","name":"Plugin","draft":false,"prerelease":false,"assets":[{"id":1,"name":"example_1.0.0_linux_x86_64.tar.gz","size":7,"digest":format!("sha256:{}",digest(b"package"))}]})
+}
+
+#[tokio::test]
+async fn release_without_published_checksum_can_be_previewed_with_a_computed_digest() {
+    let server = MockServer::start().await;
+    let mut metadata = release();
+    metadata["assets"][0]["digest"] = serde_json::Value::Null;
+    Mock::given(path("/repos/example/plugins/releases/tags/v1.0.0"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(metadata))
+        .mount(&server)
+        .await;
+    Mock::given(path("/repos/example/plugins/releases/assets/1"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(b"package"))
+        .mount(&server)
+        .await;
+    let downloaded = transport(&server)
+        .download(
+            RemotePluginLocation::Github {
+                repository: "example/plugins".into(),
+                tag: "v1.0.0".into(),
+                asset: "example_1.0.0_linux_x86_64.tar.gz".into(),
+                allow_prerelease: false,
+                sha256: None,
+            },
+            vec![],
+            None,
+        )
+        .await
+        .unwrap();
+    assert_eq!(downloaded.sha256, digest(b"package"));
+}
+
+#[tokio::test]
+async fn github_credentials_authenticate_release_metadata_requests() {
+    let server = MockServer::start().await;
+    Mock::given(path("/repos/example/plugins/releases/latest"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(release()))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let mut credential = credential_with(
+        &server,
+        "/repos/example/plugins",
+        SourceAuthentication::Github {
+            token: "test-github-token".into(),
+        },
+    );
+    credential.info.purposes = vec![DownloadPurpose::Metadata];
+
+    transport(&server)
+        .query_release(query(None), vec![credential], None)
+        .await
+        .unwrap();
+
+    let requests = server.received_requests().await.unwrap();
+    assert_eq!(
+        requests[0].headers.get("authorization").unwrap(),
+        "Bearer test-github-token"
+    );
+}
+
+#[tokio::test]
+async fn concurrent_queries_share_a_single_fetch_and_return_cache_times() {
+    let server = MockServer::start().await;
+    Mock::given(path("/repos/example/plugins/releases/latest"))
+        .respond_with(
+            ResponseTemplate::new(200)
+                .set_body_json(release())
+                .set_delay(std::time::Duration::from_millis(30)),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+    let distribution = transport(&server);
+    let results = futures::future::join_all(
+        (0..20).map(|_| distribution.query_release(query(None), vec![], None)),
+    )
+    .await;
+    let first = results[0].as_ref().unwrap();
+    for result in &results {
+        let result = result.as_ref().unwrap();
+        assert_eq!(result.tag, "v1.0.0");
+        assert_eq!(result.queried_at, first.queried_at);
+        assert_eq!((result.expires_at - result.queried_at).num_seconds(), 3600);
+    }
+}
+
+#[tokio::test]
+async fn rate_limit_applies_to_other_repositories_using_the_same_identity_and_egress() {
+    let server = MockServer::start().await;
+    Mock::given(path("/repos/example/plugins/releases/latest"))
+        .respond_with(ResponseTemplate::new(429).insert_header("retry-after", "60"))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let distribution = transport(&server);
+    let failure = distribution
+        .query_release(query(None), vec![], None)
+        .await
+        .unwrap_err();
+    assert_eq!(failure.kind(), AdminErrorKind::RateLimited);
+    let mut another = query(None);
+    another.repository = "another/plugin".into();
+    assert_eq!(
+        distribution
+            .query_release(another, vec![], None)
+            .await
+            .unwrap_err()
+            .kind(),
+        AdminErrorKind::RateLimited
+    );
+    assert_eq!(
+        distribution
+            .query_release(query(None), vec![], None)
+            .await
+            .unwrap_err(),
+        failure
+    );
+    assert_eq!(server.received_requests().await.unwrap().len(), 1);
+}
+
+#[tokio::test]
+async fn pre_releases_require_an_explicit_choice_and_mismatched_tags_are_rejected() {
+    let server = MockServer::start().await;
+    let mut preview = release();
+    preview["prerelease"] = true.into();
+    Mock::given(path("/repos/example/plugins/releases/tags/v1.0.0"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(preview))
+        .expect(2)
+        .mount(&server)
+        .await;
+    let distribution = transport(&server);
+    assert!(
+        distribution
+            .query_release(query(Some("v1.0.0")), vec![], None)
+            .await
+            .is_err()
+    );
+    let mut explicit = query(Some("v1.0.0"));
+    explicit.allow_prerelease = true;
+    assert!(
+        distribution
+            .query_release(explicit, vec![], None)
+            .await
+            .unwrap()
+            .prerelease
+    );
+    Mock::given(path("/repos/example/plugins/releases/tags/v2.0.0"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(release()))
+        .mount(&server)
+        .await;
+    assert!(
+        distribution
+            .query_release(query(Some("v2.0.0")), vec![], None)
+            .await
+            .is_err()
+    );
+}
+
+#[tokio::test]
+async fn releases_without_asset_digest_use_exact_checksum_file_entry() {
+    let server = MockServer::start().await;
+    let mut metadata = release();
+    metadata["assets"][0]["digest"] = serde_json::Value::Null;
+    metadata["assets"]
+        .as_array_mut()
+        .unwrap()
+        .push(json!({"id":2,"name":"checksums.txt","size":200}));
+    Mock::given(path("/repos/example/plugins/releases/tags/v1.0.0"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(metadata))
+        .mount(&server)
+        .await;
+    Mock::given(path("/repos/example/plugins/releases/assets/2"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(format!(
+            "{}  example_1.0.0_linux_x86_64.tar.gz\n",
+            digest(b"package")
+        )))
+        .mount(&server)
+        .await;
+    Mock::given(path("/repos/example/plugins/releases/assets/1"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(b"package"))
+        .mount(&server)
+        .await;
+    let downloaded = transport(&server)
+        .download(
+            RemotePluginLocation::Github {
+                repository: "example/plugins".into(),
+                tag: "v1.0.0".into(),
+                asset: "example_1.0.0_linux_x86_64.tar.gz".into(),
+                allow_prerelease: false,
+                sha256: None,
+            },
+            vec![],
+            None,
+        )
+        .await
+        .unwrap();
+    assert_eq!(&*downloaded.archive, b"package");
+    assert_eq!(downloaded.sha256, digest(b"package"));
+}
+
+#[tokio::test]
+async fn oversized_metadata_is_rejected_before_json_parsing() {
+    let server = MockServer::start().await;
+    Mock::given(path("/repos/example/plugins/releases/latest"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(vec![b' '; 1024 * 1024 + 1]))
+        .mount(&server)
+        .await;
+    assert!(
+        transport(&server)
+            .query_release(query(None), vec![], None)
+            .await
+            .is_err()
+    );
+}
+
+#[tokio::test]
+#[ignore = "实际访问 GitHub 公共仓库；通过 --ignored 显式运行"]
+async fn live_github_resolves_latest_then_pins_the_same_release() {
+    let distribution = gateway_host::plugin_distribution::HttpPluginDistribution::new(
+        std::sync::Arc::new(gateway_host::outbound::HttpClient::new().unwrap()),
+    )
+    .unwrap();
+    let mut query = GithubReleaseQuery {
+        repository: "cli/cli".into(),
+        tag: None,
+        allow_prerelease: false,
+    };
+    let latest = distribution
+        .query_release(query.clone(), vec![], None)
+        .await
+        .unwrap();
+    assert!(!latest.prerelease);
+    assert!(!latest.assets.is_empty());
+    query.tag = Some(latest.tag.clone());
+    let pinned = distribution
+        .query_release(query, vec![], None)
+        .await
+        .unwrap();
+    assert_eq!(pinned.tag, latest.tag);
+    let checksums = pinned
+        .assets
+        .iter()
+        .find(|asset| asset.name.ends_with("checksums.txt"))
+        .unwrap();
+    let expected = checksums
+        .sha256
+        .clone()
+        .expect("GitHub Release checksum asset must have a published digest");
+    let downloaded = distribution
+        .download(
+            RemotePluginLocation::Github {
+                repository: pinned.repository,
+                tag: pinned.tag,
+                asset: checksums.name.clone(),
+                allow_prerelease: false,
+                sha256: Some(expected.clone()),
+            },
+            vec![],
+            None,
+        )
+        .await
+        .unwrap();
+    assert_eq!(downloaded.sha256, expected);
+    assert!(!downloaded.archive.is_empty());
+}
diff --git a/backend/crates/gateway-host/tests/plugin_distribution/http.rs b/backend/crates/gateway-host/tests/plugin_distribution/http.rs
new file mode 100644
index 000000000..3d748ff24
--- /dev/null
+++ b/backend/crates/gateway-host/tests/plugin_distribution/http.rs
@@ -0,0 +1,296 @@
+use gateway_admin::{
+    model::plugins::distribution::{RemotePluginLocation, SourceAuthentication},
+    ports::plugins::PluginDistribution,
+};
+use wiremock::{
+    Mock, MockServer, ResponseTemplate,
+    matchers::{method, path},
+};
+
+use super::{credential, credential_with, digest, transport};
+
+#[tokio::test]
+async fn url_preview_computes_digest_and_confirmation_rejects_replaced_content() {
+    let server = MockServer::start().await;
+    Mock::given(path("/plugin.tar.gz"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(b"package"))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let distribution = transport(&server);
+    let url = format!("{}/plugin.tar.gz", server.uri());
+    let preview = distribution
+        .download(
+            RemotePluginLocation::Url {
+                url: url.clone(),
+                sha256: None,
+            },
+            vec![],
+            None,
+        )
+        .await
+        .unwrap();
+    assert_eq!(preview.sha256, digest(b"package"));
+
+    server.reset().await;
+    Mock::given(path("/plugin.tar.gz"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(b"replaced"))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let result = distribution
+        .download(
+            RemotePluginLocation::Url {
+                url,
+                sha256: Some(preview.sha256),
+            },
+            vec![],
+            None,
+        )
+        .await;
+    assert!(result.is_err());
+}
+
+#[tokio::test]
+async fn basic_credentials_attach_the_expected_authorization_header() {
+    let server = MockServer::start().await;
+    Mock::given(path("/private/plugin"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(b"package"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    transport(&server)
+        .download(
+            RemotePluginLocation::Url {
+                url: format!("{}/private/plugin", server.uri()),
+                sha256: Some(digest(b"package")),
+            },
+            vec![credential_with(
+                &server,
+                "/private",
+                SourceAuthentication::Basic {
+                    username: "test-user".into(),
+                    password: "test-password".into(),
+                },
+            )],
+            None,
+        )
+        .await
+        .unwrap();
+
+    let requests = server.received_requests().await.unwrap();
+    assert_eq!(
+        requests[0].headers.get("authorization").unwrap(),
+        "Basic dGVzdC11c2VyOnRlc3QtcGFzc3dvcmQ="
+    );
+}
+
+#[tokio::test]
+async fn custom_credentials_attach_only_the_declared_safe_header() {
+    let server = MockServer::start().await;
+    Mock::given(path("/private/plugin"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(b"package"))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    transport(&server)
+        .download(
+            RemotePluginLocation::Url {
+                url: format!("{}/private/plugin", server.uri()),
+                sha256: Some(digest(b"package")),
+            },
+            vec![credential_with(
+                &server,
+                "/private",
+                SourceAuthentication::Header {
+                    name: "X-Plugin-Token".into(),
+                    value: "test-header-value".into(),
+                },
+            )],
+            None,
+        )
+        .await
+        .unwrap();
+
+    let requests = server.received_requests().await.unwrap();
+    assert_eq!(
+        requests[0].headers.get("x-plugin-token").unwrap(),
+        "test-header-value"
+    );
+    assert!(!requests[0].headers.contains_key("authorization"));
+}
+
+#[tokio::test]
+async fn url_download_verifies_external_digest_and_rejects_mismatch() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/plugin.tar.gz"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(b"package"))
+        .expect(2)
+        .mount(&server)
+        .await;
+    let distribution = transport(&server);
+    let result = distribution
+        .download(
+            RemotePluginLocation::Url {
+                url: format!("{}/plugin.tar.gz", server.uri()),
+                sha256: Some(digest(b"package")),
+            },
+            vec![],
+            None,
+        )
+        .await
+        .unwrap();
+    assert_eq!(&*result.archive, b"package");
+    assert!(
+        distribution
+            .download(
+                RemotePluginLocation::Url {
+                    url: format!("{}/plugin.tar.gz", server.uri()),
+                    sha256: Some("0".repeat(64))
+                },
+                vec![],
+                None,
+            )
+            .await
+            .is_err()
+    );
+}
+
+#[tokio::test]
+async fn redirects_recheck_both_origin_and_path_before_attaching_credentials() {
+    let first = MockServer::start().await;
+    let second = MockServer::start().await;
+    Mock::given(path("/private/plugin"))
+        .respond_with(
+            ResponseTemplate::new(302)
+                .insert_header("location", format!("{}/public/plugin", first.uri())),
+        )
+        .expect(1)
+        .mount(&first)
+        .await;
+    Mock::given(path("/public/plugin"))
+        .respond_with(
+            ResponseTemplate::new(302)
+                .insert_header("location", format!("{}/private/plugin", second.uri())),
+        )
+        .expect(1)
+        .mount(&first)
+        .await;
+    Mock::given(path("/private/plugin"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(b"package"))
+        .expect(1)
+        .mount(&second)
+        .await;
+    transport(&first)
+        .download(
+            RemotePluginLocation::Url {
+                url: format!("{}/private/plugin", first.uri()),
+                sha256: Some(digest(b"package")),
+            },
+            vec![credential(&first, "/private")],
+            None,
+        )
+        .await
+        .unwrap();
+    let requests = first.received_requests().await.unwrap();
+    assert_eq!(
+        requests[0].headers.get("authorization").unwrap(),
+        "Bearer test-token"
+    );
+    assert!(!requests[1].headers.contains_key("authorization"));
+    assert!(
+        !second.received_requests().await.unwrap()[0]
+            .headers
+            .contains_key("authorization")
+    );
+}
+
+#[tokio::test]
+async fn credentials_are_applied_only_to_granted_purpose_and_unambiguous_scope() {
+    use gateway_admin::model::plugins::distribution::DownloadPurpose;
+    let server = MockServer::start().await;
+    Mock::given(path("/package"))
+        .respond_with(ResponseTemplate::new(200).set_body_bytes(b"package"))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let mut metadata_only = credential(&server, "/");
+    metadata_only.info.purposes = vec![DownloadPurpose::Metadata];
+    let location = RemotePluginLocation::Url {
+        url: format!("{}/package", server.uri()),
+        sha256: Some(digest(b"package")),
+    };
+    let distribution = transport(&server);
+    distribution
+        .download(location.clone(), vec![metadata_only], None)
+        .await
+        .unwrap();
+    assert!(
+        !server.received_requests().await.unwrap()[0]
+            .headers
+            .contains_key("authorization")
+    );
+    assert!(
+        distribution
+            .download(
+                location,
+                vec![credential(&server, "/"), credential(&server, "/package")],
+                None,
+            )
+            .await
+            .is_err()
+    );
+}
+
+#[tokio::test]
+async fn source_urls_cannot_persist_inline_credentials_or_non_https_remote_targets() {
+    let server = MockServer::start().await;
+    let distribution = transport(&server);
+    for url in [
+        "https://user:password@example.com/plugin",
+        "https://example.com/plugin?token=secret",
+        "http://example.com/plugin",
+        "file:///etc/passwd",
+    ] {
+        assert!(
+            distribution
+                .download(
+                    RemotePluginLocation::Url {
+                        url: url.into(),
+                        sha256: Some("0".repeat(64))
+                    },
+                    vec![],
+                    None,
+                )
+                .await
+                .is_err()
+        );
+    }
+    assert!(server.received_requests().await.unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn redirect_cycles_are_bounded() {
+    let server = MockServer::start().await;
+    Mock::given(path("/loop"))
+        .respond_with(ResponseTemplate::new(302).insert_header("location", "/loop"))
+        .expect(6)
+        .mount(&server)
+        .await;
+    assert!(
+        transport(&server)
+            .download(
+                RemotePluginLocation::Url {
+                    url: format!("{}/loop", server.uri()),
+                    sha256: Some("0".repeat(64))
+                },
+                vec![],
+                None,
+            )
+            .await
+            .is_err()
+    );
+}
diff --git a/backend/crates/gateway-host/tests/plugin_distribution/lifecycle.rs b/backend/crates/gateway-host/tests/plugin_distribution/lifecycle.rs
new file mode 100644
index 000000000..fb48f41ab
--- /dev/null
+++ b/backend/crates/gateway-host/tests/plugin_distribution/lifecycle.rs
@@ -0,0 +1,251 @@
+use std::{
+    sync::{
+        Arc,
+        atomic::{AtomicUsize, Ordering},
+    },
+    time::Duration,
+};
+
+use gateway_admin::{
+    model::{
+        AdminErrorKind,
+        plugins::distribution::{DownloadPurpose, GithubReleaseQuery},
+    },
+    ports::plugins::PluginDistribution,
+};
+use serde_json::json;
+use wiremock::{Mock, MockServer, ResponseTemplate, matchers::path};
+
+use super::{credential, digest, transport};
+
+fn query(repository: &str) -> GithubReleaseQuery {
+    GithubReleaseQuery {
+        repository: repository.into(),
+        tag: None,
+        allow_prerelease: false,
+    }
+}
+
+fn release() -> serde_json::Value {
+    json!({
+        "tag_name":"v1.0.0", "draft":false, "prerelease":false,
+        "assets":[{
+            "id":1, "name":"example_1.0.0_linux_x86_64.tar.gz", "size":7,
+            "digest":format!("sha256:{}", digest(b"package"))
+        }]
+    })
+}
+
+async fn wait_for_requests(server: &MockServer, count: usize) {
+    tokio::time::timeout(Duration::from_secs(2), async {
+        while server.received_requests().await.unwrap().len() < count {
+            tokio::time::sleep(Duration::from_millis(5)).await;
+        }
+    })
+    .await
+    .expect("查询必须实际到达受控来源");
+}
+
+#[tokio::test]
+async fn cancelling_the_fetch_owner_releases_the_shared_slot_for_the_next_query() {
+    let server = MockServer::start().await;
+    let calls = Arc::new(AtomicUsize::new(0));
+    let response_calls = calls.clone();
+    Mock::given(path("/repos/example/plugins/releases/latest"))
+        .respond_with(move |_: &wiremock::Request| {
+            let response = ResponseTemplate::new(200).set_body_json(release());
+            if response_calls.fetch_add(1, Ordering::SeqCst) == 0 {
+                response.set_delay(Duration::from_secs(30))
+            } else {
+                response
+            }
+        })
+        .expect(2)
+        .mount(&server)
+        .await;
+    let distribution = Arc::new(transport(&server));
+    let first_distribution = distribution.clone();
+    let first = tokio::spawn(async move {
+        first_distribution
+            .query_release(query("example/plugins"), vec![], None)
+            .await
+    });
+    // 以来源确实收到请求为屏障，避免只取消尚未执行的任务而误报释放成功。
+    wait_for_requests(&server, 1).await;
+    first.abort();
+    assert!(first.await.unwrap_err().is_cancelled());
+
+    let recovered = tokio::time::timeout(
+        Duration::from_secs(2),
+        distribution.query_release(query("example/plugins"), vec![], None),
+    )
+    .await
+    .expect("取消不能留下占用的同源查询锁或下载容量")
+    .unwrap();
+    assert_eq!(recovered.tag, "v1.0.0");
+    assert_eq!(calls.load(Ordering::SeqCst), 2);
+    let cached = distribution
+        .query_release(query("example/plugins"), vec![], None)
+        .await
+        .unwrap();
+    assert_eq!(cached.queried_at, recovered.queried_at);
+    assert_eq!(calls.load(Ordering::SeqCst), 2);
+}
+
+#[tokio::test]
+async fn cancelling_a_cache_waiter_does_not_cancel_or_poison_the_fetch_owner() {
+    let server = MockServer::start().await;
+    Mock::given(path("/repos/example/plugins/releases/latest"))
+        .respond_with(
+            ResponseTemplate::new(200)
+                .set_body_json(release())
+                .set_delay(Duration::from_millis(500)),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+    let distribution = Arc::new(transport(&server));
+    let first_distribution = distribution.clone();
+    let first = tokio::spawn(async move {
+        first_distribution
+            .query_release(query("example/plugins"), vec![], None)
+            .await
+    });
+    wait_for_requests(&server, 1).await;
+    let waiter = distribution.query_release(query("example/plugins"), vec![], None);
+    // timeout 会实际轮询等待者再取消；不会只中止一个未调度的 spawn。
+    assert!(
+        tokio::time::timeout(Duration::from_millis(25), waiter)
+            .await
+            .is_err()
+    );
+    let first = tokio::time::timeout(Duration::from_secs(2), first)
+        .await
+        .unwrap()
+        .unwrap()
+        .unwrap();
+    let cached = distribution
+        .query_release(query("example/plugins"), vec![], None)
+        .await
+        .unwrap();
+    assert_eq!(cached.queried_at, first.queried_at);
+    assert_eq!(server.received_requests().await.unwrap().len(), 1);
+}
+
+#[tokio::test]
+async fn cancelling_all_active_queries_releases_the_bounded_download_capacity() {
+    let server = MockServer::start().await;
+    for repository in ["first/plugin", "second/plugin"] {
+        Mock::given(path(format!("/repos/{repository}/releases/latest")))
+            .respond_with(
+                ResponseTemplate::new(200)
+                    .set_body_json(release())
+                    .set_delay(Duration::from_secs(30)),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+    }
+    Mock::given(path("/repos/recovered/plugin/releases/latest"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(release()))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let distribution = Arc::new(transport(&server));
+    let mut active = Vec::new();
+    for repository in ["first/plugin", "second/plugin"] {
+        let distribution = distribution.clone();
+        active.push(tokio::spawn(async move {
+            distribution
+                .query_release(query(repository), vec![], None)
+                .await
+        }));
+    }
+    wait_for_requests(&server, 2).await;
+    assert!(
+        tokio::time::timeout(
+            Duration::from_millis(25),
+            distribution.query_release(query("recovered/plugin"), vec![], None),
+        )
+        .await
+        .is_err()
+    );
+    assert_eq!(server.received_requests().await.unwrap().len(), 2);
+    for task in &active {
+        task.abort();
+    }
+    for task in active {
+        assert!(task.await.unwrap_err().is_cancelled());
+    }
+    let recovered = tokio::time::timeout(
+        Duration::from_secs(2),
+        distribution.query_release(query("recovered/plugin"), vec![], None),
+    )
+    .await
+    .expect("取消必须归还全局下载容量，等待者取消也不能污染缓存")
+    .unwrap();
+    assert_eq!(recovered.tag, "v1.0.0");
+    assert_eq!(server.received_requests().await.unwrap().len(), 3);
+}
+
+#[tokio::test]
+async fn rate_limit_expiry_releases_the_identity_without_reusing_a_failure_cache_entry() {
+    let server = MockServer::start().await;
+    Mock::given(path("/repos/limited/plugin/releases/latest"))
+        .respond_with(ResponseTemplate::new(429).insert_header("retry-after", "1"))
+        .expect(1)
+        .mount(&server)
+        .await;
+    Mock::given(path("/repos/recovered/plugin/releases/latest"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(release()))
+        .expect(1)
+        .mount(&server)
+        .await;
+    Mock::given(path("/repos/authorized/plugin/releases/latest"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(release()))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let distribution = transport(&server);
+    assert_eq!(
+        distribution
+            .query_release(query("limited/plugin"), vec![], None)
+            .await
+            .unwrap_err()
+            .kind(),
+        AdminErrorKind::RateLimited
+    );
+    assert_eq!(
+        distribution
+            .query_release(query("blocked/plugin"), vec![], None)
+            .await
+            .unwrap_err()
+            .kind(),
+        AdminErrorKind::RateLimited
+    );
+    assert_eq!(server.received_requests().await.unwrap().len(), 1);
+
+    let mut authorized = credential(&server, "/repos");
+    authorized.info.purposes = vec![DownloadPurpose::Metadata];
+    distribution
+        .query_release(query("authorized/plugin"), vec![authorized], None)
+        .await
+        .unwrap();
+    // 同一查询另有失败缓存；改用尚未查询的仓库，只验证共享身份退避的真实到期。
+    tokio::time::sleep(Duration::from_millis(1100)).await;
+    let recovered = distribution
+        .query_release(query("recovered/plugin"), vec![], None)
+        .await
+        .unwrap();
+    assert_eq!(recovered.tag, "v1.0.0");
+    assert_eq!(server.received_requests().await.unwrap().len(), 3);
+    assert_eq!(
+        distribution
+            .query_release(query("limited/plugin"), vec![], None)
+            .await
+            .unwrap_err()
+            .kind(),
+        AdminErrorKind::RateLimited
+    );
+    assert_eq!(server.received_requests().await.unwrap().len(), 3);
+}
diff --git a/backend/crates/gateway-host/tests/plugin_distribution/mod.rs b/backend/crates/gateway-host/tests/plugin_distribution/mod.rs
new file mode 100644
index 000000000..83e7b1078
--- /dev/null
+++ b/backend/crates/gateway-host/tests/plugin_distribution/mod.rs
@@ -0,0 +1,53 @@
+mod github;
+mod http;
+mod lifecycle;
+
+use std::sync::Arc;
+
+use gateway_admin::model::plugins::distribution::{
+    DownloadPurpose, SourceAuthentication, SourceCredential, SourceCredentialInfo,
+};
+use gateway_host::plugin_distribution::HttpPluginDistribution;
+use sha2::{Digest as _, Sha256};
+use wiremock::MockServer;
+
+fn transport(server: &MockServer) -> HttpPluginDistribution {
+    HttpPluginDistribution::with_transport(
+        &format!("{}/", server.uri()),
+        Arc::new(gateway_host::outbound::HttpClient::new().unwrap()),
+        gateway_host::outbound::NetworkPolicy::new(&["127.0.0.0/8".into(), "::1/128".into()])
+            .unwrap(),
+    )
+    .unwrap()
+}
+
+fn digest(body: &[u8]) -> String {
+    hex::encode(Sha256::digest(body))
+}
+
+fn credential(server: &MockServer, prefix: &str) -> SourceCredential {
+    credential_with(
+        server,
+        prefix,
+        SourceAuthentication::Bearer {
+            token: "test-token".into(),
+        },
+    )
+}
+
+fn credential_with(
+    server: &MockServer,
+    prefix: &str,
+    authentication: SourceAuthentication,
+) -> SourceCredential {
+    SourceCredential {
+        info: SourceCredentialInfo {
+            id: "test-credential".into(),
+            name: "Test".into(),
+            origin: server.uri(),
+            path_prefix: prefix.into(),
+            purposes: vec![DownloadPurpose::Metadata, DownloadPurpose::Artifact],
+        },
+        authentication,
+    }
+}
diff --git a/backend/crates/gateway-host/tests/process.rs b/backend/crates/gateway-host/tests/process.rs
new file mode 100644
index 000000000..40e1eda25
--- /dev/null
+++ b/backend/crates/gateway-host/tests/process.rs
@@ -0,0 +1,148 @@
+#[cfg(unix)]
+use gateway_host::process::{ProcessExit, ProcessSpec, ProcessStartError, ProcessSupervisor};
+
+#[cfg(unix)]
+fn worker(directory: &std::path::Path, mode: &str) -> ProcessSpec {
+    let executable = env!("CARGO_BIN_EXE_gateway-host-process-worker").into();
+    std::fs::write(directory.join("mode"), mode).unwrap();
+    ProcessSpec {
+        executable,
+        directory: directory.to_owned(),
+        maximum_stderr_bytes: 128,
+    }
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn stopping_a_real_child_waits_for_reaping() {
+    let directory = tempfile::tempdir().unwrap();
+    let supervisor = ProcessSupervisor::new(std::num::NonZeroUsize::new(1).unwrap());
+    let process = supervisor.spawn(worker(directory.path(), "wait")).unwrap();
+    assert!(matches!(
+        supervisor.spawn(worker(directory.path(), "wait")),
+        Err(ProcessStartError::Capacity)
+    ));
+    process.control.stop();
+    let exit = tokio::time::timeout(std::time::Duration::from_secs(3), process.control.exited())
+        .await
+        .unwrap();
+    assert_eq!(exit, ProcessExit::Stopped);
+    let replacement = supervisor.spawn(worker(directory.path(), "wait")).unwrap();
+    replacement.control.stop();
+    assert_eq!(replacement.control.exited().await, ProcessExit::Stopped);
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn unbounded_stderr_is_stopped_without_retaining_its_content() {
+    let directory = tempfile::tempdir().unwrap();
+    let supervisor = ProcessSupervisor::new(std::num::NonZeroUsize::new(1).unwrap());
+    let process = supervisor
+        .spawn(worker(directory.path(), "stderr"))
+        .unwrap();
+    let exit = tokio::time::timeout(std::time::Duration::from_secs(3), process.control.exited())
+        .await
+        .unwrap();
+    assert_eq!(exit, ProcessExit::StderrLimit);
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn failed_spawn_preserves_safe_cause_and_returns_capacity() {
+    let directory = tempfile::tempdir().unwrap();
+    let supervisor = ProcessSupervisor::new(std::num::NonZeroUsize::new(1).unwrap());
+    let mut missing = worker(directory.path(), "wait");
+    missing.executable = directory.path().join("private-test-only-executable");
+    let error = supervisor.spawn(missing).err().unwrap();
+    assert!(matches!(
+        error,
+        ProcessStartError::Spawn {
+            kind: std::io::ErrorKind::NotFound,
+            os_code: Some(_),
+        }
+    ));
+    assert!(!format!("{error:?} {error}").contains("private-test-only-executable"));
+    let process = supervisor.spawn(worker(directory.path(), "wait")).unwrap();
+    process.control.stop();
+    assert_eq!(process.control.exited().await, ProcessExit::Stopped);
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn busy_and_blocked_children_can_be_stopped_and_reaped() {
+    use tokio::io::AsyncReadExt as _;
+
+    for mode in ["busy", "stdin", "stdout"] {
+        let directory = tempfile::tempdir().unwrap();
+        let supervisor = ProcessSupervisor::new(std::num::NonZeroUsize::new(1).unwrap());
+        let mut process = supervisor.spawn(worker(directory.path(), mode)).unwrap();
+        let ready =
+            tokio::time::timeout(std::time::Duration::from_secs(3), process.output.read_u8())
+                .await
+                .unwrap()
+                .unwrap();
+        assert_eq!(ready, b'R');
+        // 就绪后保留输入句柄且不再读取输出，确保测试的是运行中的死循环或阻塞 I/O。
+        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+        assert!(!directory.path().join("unblocked").exists());
+        process.control.stop();
+        let exit =
+            tokio::time::timeout(std::time::Duration::from_secs(3), process.control.exited())
+                .await
+                .unwrap();
+        assert_eq!(exit, ProcessExit::Stopped, "mode: {mode}");
+        let replacement = supervisor.spawn(worker(directory.path(), "wait")).unwrap();
+        replacement.control.stop();
+        assert_eq!(replacement.control.exited().await, ProcessExit::Stopped);
+    }
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn abnormal_exit_is_observed_and_returns_process_capacity() {
+    let directory = tempfile::tempdir().unwrap();
+    let supervisor = ProcessSupervisor::new(std::num::NonZeroUsize::new(1).unwrap());
+    let process = supervisor.spawn(worker(directory.path(), "exit")).unwrap();
+    let exit = tokio::time::timeout(std::time::Duration::from_secs(3), process.control.exited())
+        .await
+        .unwrap();
+    assert_eq!(exit, ProcessExit::Exited(Some(23)));
+    let replacement = supervisor.spawn(worker(directory.path(), "wait")).unwrap();
+    replacement.control.stop();
+    assert_eq!(replacement.control.exited().await, ProcessExit::Stopped);
+}
+
+#[cfg(target_os = "linux")]
+#[tokio::test]
+async fn allocation_failure_in_a_bounded_child_returns_process_capacity() {
+    use std::os::unix::fs::PermissionsExt as _;
+    use tokio::io::AsyncReadExt as _;
+
+    let directory = tempfile::tempdir().unwrap();
+    let supervisor = ProcessSupervisor::new(std::num::NonZeroUsize::new(1).unwrap());
+    let mut spec = worker(directory.path(), "allocate");
+    let executable = spec.executable.to_str().unwrap().replace('\'', "'\\''");
+    let wrapper = directory.path().join("bounded-worker");
+    // 地址空间上限和禁用 core dump 仅保护测试机，不宣称生产监督器已施加 OS 内存隔离。
+    std::fs::write(
+        &wrapper,
+        format!("#!/bin/sh\nset -eu\nulimit -c 0\nulimit -v 65536\nexec '{executable}'\n"),
+    )
+    .unwrap();
+    std::fs::set_permissions(&wrapper, std::fs::Permissions::from_mode(0o700)).unwrap();
+    spec.executable = wrapper;
+    let mut process = supervisor.spawn(spec).unwrap();
+    let ready = tokio::time::timeout(std::time::Duration::from_secs(3), process.output.read_u8())
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(ready, b'R');
+    let exit = tokio::time::timeout(std::time::Duration::from_secs(3), process.control.exited())
+        .await
+        .unwrap();
+    assert_eq!(exit, ProcessExit::Exited(None));
+    assert!(!directory.path().join("allocation-succeeded").exists());
+    let replacement = supervisor.spawn(worker(directory.path(), "wait")).unwrap();
+    replacement.control.stop();
+    assert_eq!(replacement.control.exited().await, ProcessExit::Stopped);
+}
diff --git a/backend/crates/gateway-host/tests/support/certificates/root.der b/backend/crates/gateway-host/tests/support/certificates/root.der
new file mode 100644
index 000000000..2ebc54c34
Binary files /dev/null and b/backend/crates/gateway-host/tests/support/certificates/root.der differ
diff --git a/backend/crates/gateway-host/tests/support/certificates/server-key.der b/backend/crates/gateway-host/tests/support/certificates/server-key.der
new file mode 100644
index 000000000..d6acd9f51
Binary files /dev/null and b/backend/crates/gateway-host/tests/support/certificates/server-key.der differ
diff --git a/backend/crates/gateway-host/tests/support/certificates/server.der b/backend/crates/gateway-host/tests/support/certificates/server.der
new file mode 100644
index 000000000..4c4fdcae0
Binary files /dev/null and b/backend/crates/gateway-host/tests/support/certificates/server.der differ
diff --git a/backend/crates/gateway-host/tests/support/mod.rs b/backend/crates/gateway-host/tests/support/mod.rs
new file mode 100644
index 000000000..a61610bd4
--- /dev/null
+++ b/backend/crates/gateway-host/tests/support/mod.rs
@@ -0,0 +1 @@
+pub mod network;
diff --git a/backend/crates/gateway-host/tests/support/network.rs b/backend/crates/gateway-host/tests/support/network.rs
new file mode 100644
index 000000000..772bc089b
--- /dev/null
+++ b/backend/crates/gateway-host/tests/support/network.rs
@@ -0,0 +1,245 @@
+use std::{
+    io,
+    net::{IpAddr, SocketAddr},
+    sync::Arc,
+    time::Duration,
+};
+
+use futures::future::BoxFuture;
+use gateway_host::outbound::DnsResolver;
+use tokio::{
+    io::{AsyncRead, AsyncReadExt as _, AsyncWrite, AsyncWriteExt as _},
+    net::{TcpListener, TcpStream},
+    sync::mpsc,
+    task::{JoinHandle, JoinSet},
+};
+use tokio_rustls::TlsAcceptor;
+
+pub const ROOT: &[u8] = include_bytes!("certificates/root.der");
+
+pub struct FixedDns(pub IpAddr);
+impl DnsResolver for FixedDns {
+    fn resolve(&self, _: String, port: u16) -> BoxFuture<'static, io::Result<Vec<SocketAddr>>> {
+        let address = SocketAddr::new(self.0, port);
+        Box::pin(async move { Ok(vec![address]) })
+    }
+}
+
+#[derive(Debug)]
+pub struct Observation {
+    pub head: String,
+    pub sni: Option<String>,
+    pub target: Option<SocketAddr>,
+    pub authentication: Option<(String, String)>,
+}
+
+#[derive(Clone, Copy)]
+pub enum Mode {
+    Origin,
+    HttpProxy,
+    Socks,
+}
+
+pub struct Server {
+    pub address: SocketAddr,
+    received: mpsc::UnboundedReceiver<Observation>,
+    task: JoinHandle<()>,
+}
+
+impl Drop for Server {
+    fn drop(&mut self) {
+        self.task.abort();
+    }
+}
+
+impl Server {
+    pub async fn start(mode: Mode, tls: bool, bind: &str) -> Self {
+        let listener = TcpListener::bind(bind).await.unwrap();
+        let address = listener.local_addr().unwrap();
+        let (sender, received) = mpsc::unbounded_channel();
+        let acceptor = tls.then(tls_acceptor);
+        let task = tokio::spawn(async move {
+            let mut connections = JoinSet::new();
+            loop {
+                tokio::select! {
+                    result = listener.accept() => {
+                        let (stream, _) = result.unwrap();
+                        let acceptor = acceptor.clone();
+                        let sender = sender.clone();
+                        connections.spawn(async move {
+                            let (stream, sni): (Box<dyn Socket>, _) = if let Some(acceptor) = acceptor {
+                                let Ok(stream) = acceptor.accept(stream).await else { return; };
+                                let sni = stream.get_ref().1.server_name().map(str::to_owned);
+                                (Box::new(stream), sni)
+                            } else { (Box::new(stream), None) };
+                            let result = tokio::time::timeout(Duration::from_secs(5), serve(stream, sni, mode, sender)).await;
+                            if let Ok(Err(error)) = result { assert!(matches!(error.kind(), io::ErrorKind::UnexpectedEof | io::ErrorKind::ConnectionReset | io::ErrorKind::BrokenPipe), "fixture transport failed: {error}"); }
+                        });
+                    }
+                    result = connections.join_next(), if !connections.is_empty() => { result.unwrap().unwrap(); }
+                }
+            }
+        });
+        Self {
+            address,
+            received,
+            task,
+        }
+    }
+
+    pub async fn next(&mut self) -> Observation {
+        tokio::time::timeout(Duration::from_secs(3), self.received.recv())
+            .await
+            .unwrap()
+            .unwrap()
+    }
+}
+
+trait Socket: AsyncRead + AsyncWrite + Unpin + Send {}
+impl<T: AsyncRead + AsyncWrite + Unpin + Send> Socket for T {}
+
+async fn serve(
+    mut stream: Box<dyn Socket>,
+    sni: Option<String>,
+    mode: Mode,
+    observations: mpsc::UnboundedSender<Observation>,
+) -> io::Result<()> {
+    if matches!(mode, Mode::Socks) {
+        return socks(stream, observations).await;
+    }
+    let head = read_head(&mut stream).await?;
+    if matches!(mode, Mode::Origin) {
+        observations
+            .send(Observation {
+                head,
+                sni,
+                target: None,
+                authentication: None,
+            })
+            .unwrap();
+        stream
+            .write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 7\r\nConnection: close\r\n\r\nsecured")
+            .await?;
+        return stream.shutdown().await;
+    }
+    let mut first = head.lines().next().unwrap().split_whitespace();
+    let method = first.next().unwrap();
+    let uri: http::Uri = first.next().unwrap().parse().unwrap();
+    let target: SocketAddr = uri
+        .authority()
+        .unwrap()
+        .as_str()
+        .parse()
+        .expect("proxy must receive an IP, not a hostname");
+    observations
+        .send(Observation {
+            head: head.clone(),
+            sni,
+            target: Some(target),
+            authentication: None,
+        })
+        .unwrap();
+    let mut upstream = TcpStream::connect(target).await?;
+    if method == "CONNECT" {
+        stream
+            .write_all(b"HTTP/1.1 200 Connection established\r\n\r\n")
+            .await?;
+    } else {
+        let path = uri.path_and_query().map_or("/", |path| path.as_str());
+        let mut forwarded = format!("{method} {path} HTTP/1.1\r\n");
+        for header in head.lines().skip(1).filter(|line| {
+            !line.is_empty()
+                && !line
+                    .to_ascii_lowercase()
+                    .starts_with("proxy-authorization:")
+        }) {
+            forwarded.push_str(header);
+            forwarded.push_str("\r\n");
+        }
+        forwarded.push_str("\r\n");
+        upstream.write_all(forwarded.as_bytes()).await?;
+    }
+    tokio::io::copy_bidirectional(&mut stream, &mut upstream).await?;
+    Ok(())
+}
+
+async fn read_head(stream: &mut Box<dyn Socket>) -> io::Result<String> {
+    let mut bytes = Vec::new();
+    while !bytes.ends_with(b"\r\n\r\n") {
+        bytes.push(stream.read_u8().await?);
+        assert!(bytes.len() <= 8192);
+    }
+    Ok(String::from_utf8(bytes).unwrap())
+}
+
+async fn socks(
+    mut stream: Box<dyn Socket>,
+    observations: mpsc::UnboundedSender<Observation>,
+) -> io::Result<()> {
+    assert_eq!(stream.read_u8().await?, 5);
+    let mut methods = vec![0; stream.read_u8().await? as usize];
+    stream.read_exact(&mut methods).await?;
+    assert!(methods.contains(&2));
+    stream.write_all(&[5, 2]).await?;
+    assert_eq!(stream.read_u8().await?, 1);
+    let mut username = vec![0; stream.read_u8().await? as usize];
+    stream.read_exact(&mut username).await?;
+    let mut password = vec![0; stream.read_u8().await? as usize];
+    stream.read_exact(&mut password).await?;
+    stream.write_all(&[1, 0]).await?;
+    let mut prefix = [0; 4];
+    stream.read_exact(&mut prefix).await?;
+    assert_eq!(&prefix[..3], &[5, 1, 0]);
+    let ip = match prefix[3] {
+        1 => {
+            let mut bytes = [0; 4];
+            stream.read_exact(&mut bytes).await?;
+            IpAddr::from(bytes)
+        }
+        4 => {
+            let mut bytes = [0; 16];
+            stream.read_exact(&mut bytes).await?;
+            IpAddr::from(bytes)
+        }
+        _ => panic!("SOCKS proxy received an unpinned hostname"),
+    };
+    let target = SocketAddr::new(ip, stream.read_u16().await?);
+    observations
+        .send(Observation {
+            head: String::new(),
+            sni: None,
+            target: Some(target),
+            authentication: Some((
+                String::from_utf8(username).unwrap(),
+                String::from_utf8(password).unwrap(),
+            )),
+        })
+        .unwrap();
+    let mut upstream = TcpStream::connect(target).await?;
+    stream.write_all(&[5, 0, 0, 1, 127, 0, 0, 1, 0, 0]).await?;
+    tokio::io::copy_bidirectional(&mut stream, &mut upstream).await?;
+    Ok(())
+}
+
+fn tls_acceptor() -> TlsAcceptor {
+    use rustls::{
+        ServerConfig,
+        pki_types::{CertificateDer, PrivateKeyDer, PrivatePkcs8KeyDer},
+    };
+    let config = ServerConfig::builder_with_provider(Arc::new(
+        rustls::crypto::aws_lc_rs::default_provider(),
+    ))
+    .with_safe_default_protocol_versions()
+    .unwrap()
+    .with_no_client_auth()
+    .with_single_cert(
+        vec![CertificateDer::from(
+            include_bytes!("certificates/server.der").to_vec(),
+        )],
+        PrivateKeyDer::Pkcs8(PrivatePkcs8KeyDer::from(
+            include_bytes!("certificates/server-key.der").to_vec(),
+        )),
+    )
+    .unwrap();
+    TlsAcceptor::from(Arc::new(config))
+}
diff --git a/backend/crates/gateway-host/tests/support/process_worker.rs b/backend/crates/gateway-host/tests/support/process_worker.rs
new file mode 100644
index 000000000..172e06c23
--- /dev/null
+++ b/backend/crates/gateway-host/tests/support/process_worker.rs
@@ -0,0 +1,44 @@
+//! Host 进程监督测试的 Rust 子进程，不依赖脚本解释器。
+
+use std::{
+    io::{Read as _, Write as _},
+    time::Duration,
+};
+
+fn main() {
+    let mode = std::fs::read_to_string("mode").unwrap();
+    if mode == "stderr" {
+        std::io::stderr().write_all(&[b'x'; 4096]).unwrap();
+    }
+    if matches!(
+        mode.as_str(),
+        "busy" | "stdin" | "stdout" | "exit" | "allocate"
+    ) {
+        std::io::stdout().write_all(b"R").unwrap();
+        std::io::stdout().flush().unwrap();
+    }
+    match mode.as_str() {
+        "busy" => loop {
+            std::hint::spin_loop();
+        },
+        "stdin" => {
+            std::io::stdin().read_exact(&mut [0; 1]).unwrap();
+            std::fs::write("unblocked", b"stdin").unwrap();
+        }
+        "stdout" => {
+            // 测试端不消费此正文，超过管道容量后必须由监督器终止，而不是等待写入完成。
+            std::io::stdout()
+                .write_all(&vec![b'x'; 8 * 1024 * 1024])
+                .unwrap();
+            std::fs::write("unblocked", b"stdout").unwrap();
+        }
+        "exit" => std::process::exit(23),
+        "allocate" => {
+            // 仅供测试包装器在严格地址空间上限内触发真实分配失败，不能无保护地运行此模式。
+            std::hint::black_box(vec![b'x'; 64 * 1024 * 1024]);
+            std::fs::write("allocation-succeeded", b"unexpected").unwrap();
+        }
+        _ => {}
+    }
+    std::thread::sleep(Duration::from_secs(60));
+}
diff --git a/backend/crates/gateway-host/tests/system_update/mod.rs b/backend/crates/gateway-host/tests/system_update/mod.rs
index 585b5e2c5..88f246564 100644
--- a/backend/crates/gateway-host/tests/system_update/mod.rs
+++ b/backend/crates/gateway-host/tests/system_update/mod.rs
@@ -1,16 +1,25 @@
 use std::fs;
 use std::path::PathBuf;
-use std::sync::Arc;
+use std::sync::{
+    Arc,
+    atomic::{AtomicUsize, Ordering},
+};
 use std::time::Duration;
 
 use filetime::FileTime;
 use flate2::{Compression, write::GzEncoder};
 use futures::StreamExt as _;
-use gateway_admin::model::system::{
-    SystemOperationAccepted, SystemOperationKind, SystemOperationStatus, SystemUpdateEventLevel,
-    SystemUpdateStatus,
+use gateway_admin::model::{
+    Revision,
+    system::{
+        SystemOperationAccepted, SystemOperationKind, SystemOperationStatus,
+        SystemUpdateEventLevel, SystemUpdateStatus,
+    },
+};
+use gateway_admin::ports::system::{
+    SystemOperationError, SystemOperationErrorKind, SystemOperations, SystemUpdateCandidate,
+    SystemUpdatePreflight,
 };
-use gateway_admin::ports::system::{SystemOperationErrorKind, SystemOperations};
 use gateway_core::lifecycle::CancellationToken;
 use gateway_host::system_update::{
     ProcessSystemOperations, SystemUpdateConfig, validate_download_url,
@@ -23,6 +32,118 @@ use wiremock::{Mock, MockServer, ResponseTemplate};
 const TARGET_VERSION: &str = "1.9.9";
 const CROSS_MAJOR_VERSION: &str = "2.0.0";
 
+struct AllowingUpdatePreflight;
+
+#[async_trait::async_trait]
+impl SystemUpdatePreflight for AllowingUpdatePreflight {
+    async fn validate(&self, _: SystemUpdateCandidate) -> Result<Revision, SystemOperationError> {
+        Revision::new(1).map_err(|_| {
+            SystemOperationError::new(SystemOperationErrorKind::Internal, "invalid test revision")
+        })
+    }
+
+    async fn confirm_revision(&self, _: Revision) -> Result<(), SystemOperationError> {
+        Ok(())
+    }
+}
+
+#[async_trait::async_trait]
+trait TestSystemUpdate {
+    async fn perform_test_update(
+        &self,
+        target: Option<String>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError>;
+}
+
+#[async_trait::async_trait]
+impl TestSystemUpdate for ProcessSystemOperations {
+    async fn perform_test_update(
+        &self,
+        target: Option<String>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError> {
+        SystemOperations::perform_update(self, target, Arc::new(AllowingUpdatePreflight)).await
+    }
+}
+
+struct ChangingRevisionPreflight {
+    confirmations: AtomicUsize,
+}
+
+#[async_trait::async_trait]
+impl SystemUpdatePreflight for ChangingRevisionPreflight {
+    async fn validate(
+        &self,
+        candidate: SystemUpdateCandidate,
+    ) -> Result<Revision, SystemOperationError> {
+        assert_eq!(candidate.target_version, TARGET_VERSION);
+        assert_eq!(candidate.release_manifest.as_ref(), b"new-manifest");
+        Ok(Revision::new(7).expect("revision"))
+    }
+
+    async fn confirm_revision(&self, _: Revision) -> Result<(), SystemOperationError> {
+        if self.confirmations.fetch_add(1, Ordering::SeqCst) == 0 {
+            Ok(())
+        } else {
+            Err(SystemOperationError::new(
+                SystemOperationErrorKind::Conflict,
+                "fixture revision changed",
+            ))
+        }
+    }
+}
+
+struct ChangingRollbackRevisionPreflight {
+    confirmations: AtomicUsize,
+}
+
+#[async_trait::async_trait]
+impl SystemUpdatePreflight for ChangingRollbackRevisionPreflight {
+    async fn validate(
+        &self,
+        candidate: SystemUpdateCandidate,
+    ) -> Result<Revision, SystemOperationError> {
+        assert_eq!(candidate.target_version, "1.0.0");
+        assert_eq!(candidate.release_manifest.as_ref(), b"old-manifest");
+        Ok(Revision::new(11).expect("revision"))
+    }
+
+    async fn confirm_revision(&self, _: Revision) -> Result<(), SystemOperationError> {
+        if self.confirmations.fetch_add(1, Ordering::SeqCst) == 0 {
+            Ok(())
+        } else {
+            Err(SystemOperationError::new(
+                SystemOperationErrorKind::Conflict,
+                "fixture revision changed",
+            ))
+        }
+    }
+}
+
+struct BlockingRollbackPreflight {
+    confirmations: AtomicUsize,
+    reached_after_swap: Arc<tokio::sync::Notify>,
+}
+
+#[async_trait::async_trait]
+impl SystemUpdatePreflight for BlockingRollbackPreflight {
+    async fn validate(
+        &self,
+        candidate: SystemUpdateCandidate,
+    ) -> Result<Revision, SystemOperationError> {
+        assert_eq!(candidate.target_version, "1.0.0");
+        assert_eq!(candidate.release_manifest.as_ref(), b"old-manifest");
+        Ok(Revision::new(13).expect("revision"))
+    }
+
+    async fn confirm_revision(&self, _: Revision) -> Result<(), SystemOperationError> {
+        if self.confirmations.fetch_add(1, Ordering::SeqCst) == 0 {
+            return Ok(());
+        }
+        self.reached_after_swap.notify_one();
+        std::future::pending().await
+    }
+}
+
 #[tokio::test]
 async fn restart_should_not_shutdown_when_replacement_spawn_fails() {
     let fixture = Fixture::new();
@@ -106,7 +227,7 @@ async fn restart_should_conflict_while_another_system_operation_is_running() {
         let service = Arc::clone(&service);
         async move {
             service
-                .perform_update(Some(TARGET_VERSION.to_owned()))
+                .perform_test_update(Some(TARGET_VERSION.to_owned()))
                 .await
         }
     });
@@ -142,14 +263,35 @@ async fn rollback_should_restore_binary_web_and_version_state() {
         )
         .await;
     let service = fixture.service(&server);
+    let updated = complete_update(&service, TARGET_VERSION).await;
     assert_eq!(
-        complete_update(&service, TARGET_VERSION)
-            .await
-            .operation
-            .status,
-        SystemOperationStatus::Succeeded
+        updated.operation.status,
+        SystemOperationStatus::Succeeded,
+        "{updated:?}"
     );
-    service.rollback().await.expect("rollback");
+    assert_eq!(
+        fs::read(fixture.official().join("plugin-release-manifest.json")).expect("manifest"),
+        b"new-manifest"
+    );
+    assert!(fixture.official().join("new-plugin.tar.gz").is_file());
+    assert!(!fixture.official().join("old-plugin.tar.gz").exists());
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt as _;
+
+        assert_eq!(
+            fs::metadata(fixture.official())
+                .expect("official directory")
+                .permissions()
+                .mode()
+                & 0o777,
+            0o555
+        );
+    }
+    service
+        .rollback(Arc::new(AllowingUpdatePreflight))
+        .await
+        .expect("rollback");
 
     assert_eq!(
         fs::read(fixture.executable()).expect("binary"),
@@ -159,6 +301,15 @@ async fn rollback_should_restore_binary_web_and_version_state() {
         fs::read(fixture.web().join("index.html")).expect("web"),
         b"old-web"
     );
+    assert_eq!(
+        fs::read(fixture.official().join("plugin-release-manifest.json")).expect("manifest"),
+        b"old-manifest"
+    );
+    assert_eq!(
+        fs::read(fixture.official().join("old-plugin.tar.gz")).expect("old plugin"),
+        b"old-plugin"
+    );
+    assert!(!fixture.official().join("new-plugin.tar.gz").exists());
     assert_eq!(
         service
             .update_status()
@@ -168,6 +319,175 @@ async fn rollback_should_restore_binary_web_and_version_state() {
             .status,
         SystemOperationStatus::Succeeded
     );
+    assert_eq!(
+        complete_update(&service, TARGET_VERSION)
+            .await
+            .operation
+            .status,
+        SystemOperationStatus::Succeeded,
+        "第二次更新必须能清理只读的官方目录备份"
+    );
+    assert_eq!(
+        fs::read(fixture.official().join("plugin-release-manifest.json")).expect("manifest"),
+        b"new-manifest"
+    );
+}
+
+#[tokio::test]
+async fn update_should_restore_all_files_when_plugin_revision_changes_during_swap() {
+    let server = MockServer::start().await;
+    let fixture = Fixture::new();
+    fixture
+        .mount_release(
+            &server,
+            TARGET_VERSION,
+            ArchiveKind::Safe,
+            ChecksumKind::Valid,
+        )
+        .await;
+    let service = fixture.service(&server);
+    SystemOperations::perform_update(
+        &service,
+        Some(TARGET_VERSION.to_owned()),
+        Arc::new(ChangingRevisionPreflight {
+            confirmations: AtomicUsize::new(0),
+        }),
+    )
+    .await
+    .expect("update accepted");
+
+    let status = wait_for_update(&service).await;
+    assert_eq!(status.operation.status, SystemOperationStatus::Failed);
+    assert_eq!(
+        fs::read(fixture.executable()).expect("binary"),
+        b"old-binary"
+    );
+    assert_eq!(
+        fs::read(fixture.web().join("index.html")).expect("web"),
+        b"old-web"
+    );
+    assert_eq!(
+        fs::read(fixture.official().join("plugin-release-manifest.json")).expect("manifest"),
+        b"old-manifest"
+    );
+    assert!(fixture.official().join("old-plugin.tar.gz").is_file());
+    assert!(!fixture.official().join("new-plugin.tar.gz").exists());
+}
+
+#[tokio::test]
+async fn rollback_should_restore_current_release_when_plugin_revision_changes_during_swap() {
+    let server = MockServer::start().await;
+    let fixture = Fixture::new();
+    fixture
+        .mount_release(
+            &server,
+            TARGET_VERSION,
+            ArchiveKind::Safe,
+            ChecksumKind::Valid,
+        )
+        .await;
+    let service = fixture.service(&server);
+    assert_eq!(
+        complete_update(&service, TARGET_VERSION)
+            .await
+            .operation
+            .status,
+        SystemOperationStatus::Succeeded
+    );
+
+    let error = service
+        .rollback(Arc::new(ChangingRollbackRevisionPreflight {
+            confirmations: AtomicUsize::new(0),
+        }))
+        .await
+        .expect_err("revision changed after rollback swap");
+
+    assert_eq!(error.kind(), SystemOperationErrorKind::Conflict);
+    assert_eq!(
+        fs::read(fixture.executable()).expect("binary"),
+        b"new-binary"
+    );
+    assert_eq!(
+        fs::read(fixture.web().join("index.html")).expect("web"),
+        b"new-web"
+    );
+    assert_eq!(
+        fs::read(fixture.official().join("plugin-release-manifest.json")).expect("manifest"),
+        b"new-manifest"
+    );
+    assert_eq!(
+        service
+            .update_status()
+            .await
+            .expect("status")
+            .operation
+            .status,
+        SystemOperationStatus::Failed
+    );
+}
+
+#[tokio::test]
+async fn cancelled_rollback_should_restore_current_release_after_the_swap() {
+    let server = MockServer::start().await;
+    let fixture = Fixture::new();
+    fixture
+        .mount_release(
+            &server,
+            TARGET_VERSION,
+            ArchiveKind::Safe,
+            ChecksumKind::Valid,
+        )
+        .await;
+    let service = fixture.service(&server);
+    assert_eq!(
+        complete_update(&service, TARGET_VERSION)
+            .await
+            .operation
+            .status,
+        SystemOperationStatus::Succeeded
+    );
+    let reached_after_swap = Arc::new(tokio::sync::Notify::new());
+    let task_service = service.clone();
+    let task_reached = Arc::clone(&reached_after_swap);
+    let task = tokio::spawn(async move {
+        task_service
+            .rollback(Arc::new(BlockingRollbackPreflight {
+                confirmations: AtomicUsize::new(0),
+                reached_after_swap: task_reached,
+            }))
+            .await
+    });
+    tokio::time::timeout(Duration::from_secs(5), reached_after_swap.notified())
+        .await
+        .expect("post-swap confirmation reached");
+    task.abort();
+    assert!(
+        task.await
+            .expect_err("rollback task cancelled")
+            .is_cancelled()
+    );
+
+    assert_eq!(
+        fs::read(fixture.executable()).expect("binary"),
+        b"new-binary"
+    );
+    assert_eq!(
+        fs::read(fixture.web().join("index.html")).expect("web"),
+        b"new-web"
+    );
+    assert_eq!(
+        fs::read(fixture.official().join("plugin-release-manifest.json")).expect("manifest"),
+        b"new-manifest"
+    );
+    assert_eq!(
+        service
+            .update_status()
+            .await
+            .expect("recovered status")
+            .operation
+            .status,
+        SystemOperationStatus::Failed
+    );
 }
 
 #[tokio::test]
@@ -413,7 +733,7 @@ async fn update_should_reject_cross_channel_targets_before_fetching_or_replacing
         let service = ProcessSystemOperations::new(CancellationToken::new(), config);
 
         let error = service
-            .perform_update(Some(target.to_owned()))
+            .perform_test_update(Some(target.to_owned()))
             .await
             .expect_err("cross-channel update");
         assert_eq!(error.kind(), SystemOperationErrorKind::Conflict);
@@ -529,7 +849,7 @@ async fn update_detail_should_keep_current_release_notes_without_allowing_reinst
         assert!(!service.version().await.expect("version").has_update);
 
         let error = service
-            .perform_update(Some(current.to_owned()))
+            .perform_test_update(Some(current.to_owned()))
             .await
             .expect_err("current release must not be installed again");
         assert_eq!(error.kind(), SystemOperationErrorKind::Conflict);
@@ -809,7 +1129,7 @@ async fn update_should_reject_cross_major_target_before_fetching_release() {
     );
 
     let error = service
-        .perform_update(Some(CROSS_MAJOR_VERSION.to_owned()))
+        .perform_test_update(Some(CROSS_MAJOR_VERSION.to_owned()))
         .await
         .expect_err("cross-major target must be rejected");
     assert_eq!(error.kind(), SystemOperationErrorKind::Conflict);
@@ -827,7 +1147,7 @@ async fn update_events_should_close_after_terminal_update_log() {
     let service = ProcessSystemOperations::new(CancellationToken::new(), config);
     let mut events = service.update_events();
     let _ = service
-        .perform_update(Some(TARGET_VERSION.to_owned()))
+        .perform_test_update(Some(TARGET_VERSION.to_owned()))
         .await;
     let first = events.next().await.expect("terminal event");
 
@@ -843,7 +1163,7 @@ async fn update_events_should_open_authenticated_sse_stream() {
     let service = ProcessSystemOperations::new(CancellationToken::new(), config);
     let mut stream = service.update_events();
     let _ = service
-        .perform_update(Some(TARGET_VERSION.to_owned()))
+        .perform_test_update(Some(TARGET_VERSION.to_owned()))
         .await;
 
     assert!(stream.next().await.is_some());
@@ -878,8 +1198,24 @@ async fn update_events_should_preserve_complete_release_stage_sequence() {
     assert_eq!(
         steps,
         [
-            "release", "prepare", "asset", "asset", "verify", "prepare", "download", "download",
-            "download", "checksum", "checksum", "extract", "extract", "replace", "replace", "done",
+            "release",
+            "prepare",
+            "asset",
+            "asset",
+            "verify",
+            "prepare",
+            "download",
+            "download",
+            "download",
+            "checksum",
+            "checksum",
+            "extract",
+            "extract",
+            "preflight",
+            "preflight",
+            "replace",
+            "replace",
+            "done",
         ]
     );
 }
@@ -1028,6 +1364,29 @@ async fn update_should_reject_release_archive_with_unsafe_path() {
     );
 }
 
+#[tokio::test]
+async fn update_should_require_a_flat_regular_official_plugin_bundle() {
+    for archive_kind in [
+        ArchiveKind::MissingOfficialManifest,
+        ArchiveKind::NestedOfficialAsset,
+        ArchiveKind::OfficialSymlink,
+    ] {
+        let server = MockServer::start().await;
+        let fixture = Fixture::new();
+        fixture
+            .mount_release(&server, TARGET_VERSION, archive_kind, ChecksumKind::Valid)
+            .await;
+
+        assert_eq!(
+            complete_update(&fixture.service(&server), TARGET_VERSION)
+                .await
+                .operation
+                .status,
+            SystemOperationStatus::Failed,
+        );
+    }
+}
+
 #[tokio::test]
 async fn update_should_reject_untrusted_github_api_base() {
     let fixture = Fixture::new();
@@ -1036,7 +1395,7 @@ async fn update_should_reject_untrusted_github_api_base() {
         fixture.config("https://api.github.example/repos"),
     );
     let error = service
-        .perform_update(Some(TARGET_VERSION.to_owned()))
+        .perform_test_update(Some(TARGET_VERSION.to_owned()))
         .await
         .expect_err("untrusted API rejected");
 
@@ -1127,7 +1486,10 @@ async fn update_and_rollback_should_use_the_default_api_asset_directory() {
         b"new-web"
     );
 
-    service.rollback().await.expect("rollback");
+    service
+        .rollback(Arc::new(AllowingUpdatePreflight))
+        .await
+        .expect("rollback");
     assert_eq!(
         fs::read(fixture.executable()).expect("binary"),
         b"old-binary"
@@ -1198,6 +1560,12 @@ async fn update_should_restore_web_assets_when_binary_backup_fails() {
         fs::read(fixture.web().join("index.html")).expect("web"),
         b"old-web"
     );
+    assert_eq!(
+        fs::read(fixture.official().join("plugin-release-manifest.json")).expect("manifest"),
+        b"old-manifest"
+    );
+    assert!(fixture.official().join("old-plugin.tar.gz").is_file());
+    assert!(!fixture.official().join("new-plugin.tar.gz").exists());
 }
 
 #[tokio::test]
@@ -1273,7 +1641,7 @@ async fn accepted_update_should_survive_a_lost_http_response() {
             let accepted = Arc::clone(&handler_accepted);
             async move {
                 service
-                    .perform_update(Some(TARGET_VERSION.to_owned()))
+                    .perform_test_update(Some(TARGET_VERSION.to_owned()))
                     .await
                     .expect("accepted");
                 accepted.notify_one();
@@ -1311,7 +1679,7 @@ async fn accepted_update_should_survive_a_lost_http_response() {
     );
     assert_eq!(
         service
-            .perform_update(Some(TARGET_VERSION.to_owned()))
+            .perform_test_update(Some(TARGET_VERSION.to_owned()))
             .await
             .expect_err("duplicate update")
             .kind(),
@@ -1319,7 +1687,7 @@ async fn accepted_update_should_survive_a_lost_http_response() {
     );
     assert_eq!(
         service
-            .rollback()
+            .rollback(Arc::new(AllowingUpdatePreflight))
             .await
             .expect_err("rollback during update")
             .kind(),
@@ -1335,7 +1703,7 @@ async fn accepted_update_should_survive_a_lost_http_response() {
     assert!(!fixture.lock().exists());
     assert_eq!(
         service
-            .perform_update(Some(TARGET_VERSION.to_owned()))
+            .perform_test_update(Some(TARGET_VERSION.to_owned()))
             .await
             .expect_err("restart required")
             .kind(),
@@ -1373,7 +1741,7 @@ async fn host_shutdown_should_finish_an_accepted_update_and_release_its_lock() {
     );
     // 在后台任务第一次 poll 之前触发关闭，覆盖受理后的生命周期交接。
     service
-        .perform_update(Some(TARGET_VERSION.to_owned()))
+        .perform_test_update(Some(TARGET_VERSION.to_owned()))
         .await
         .expect("accepted");
     cancellation.cancel();
@@ -1396,7 +1764,7 @@ fn dropped_update_task_should_persist_failure_even_before_its_first_poll() {
         .build()
         .expect("runtime");
     runtime
-        .block_on(service.perform_update(Some(TARGET_VERSION.to_owned())))
+        .block_on(service.perform_test_update(Some(TARGET_VERSION.to_owned())))
         .expect("accepted");
     drop(runtime);
     let status: serde_json::Value =
@@ -1443,7 +1811,7 @@ async fn terminal_event_should_only_be_visible_after_status_is_persisted() {
     let service = fixture.service(&upstream);
     let mut events = service.update_events();
     let SystemOperationAccepted::Update { operation_id, .. } = service
-        .perform_update(Some(TARGET_VERSION.to_owned()))
+        .perform_test_update(Some(TARGET_VERSION.to_owned()))
         .await
         .expect("accepted")
     else {
@@ -1482,7 +1850,7 @@ async fn wait_for_update(service: &ProcessSystemOperations) -> SystemUpdateStatu
 
 async fn complete_update(service: &ProcessSystemOperations, target: &str) -> SystemUpdateStatus {
     let SystemOperationAccepted::Update { operation_id, .. } = service
-        .perform_update(Some(target.to_owned()))
+        .perform_test_update(Some(target.to_owned()))
         .await
         .expect("update accepted")
     else {
@@ -1507,6 +1875,13 @@ impl Fixture {
         fixture.write_executable("old-binary");
         fs::create_dir_all(fixture.web()).expect("web dir");
         fs::write(fixture.web().join("index.html"), "old-web").expect("web");
+        fs::create_dir_all(fixture.official()).expect("official plugin dir");
+        fs::write(
+            fixture.official().join("plugin-release-manifest.json"),
+            "old-manifest",
+        )
+        .expect("manifest");
+        fs::write(fixture.official().join("old-plugin.tar.gz"), "old-plugin").expect("plugin");
         fixture
     }
 
@@ -1518,6 +1893,10 @@ impl Fixture {
         self.root.path().join("web/dist")
     }
 
+    fn official(&self) -> PathBuf {
+        self.root.path().join("plugins/official")
+    }
+
     fn state(&self) -> PathBuf {
         self.root.path().join("update-state.json")
     }
@@ -1648,6 +2027,9 @@ impl Fixture {
 enum ArchiveKind {
     Safe,
     UnsafePath,
+    MissingOfficialManifest,
+    NestedOfficialAsset,
+    OfficialSymlink,
 }
 
 #[derive(Clone, Copy)]
@@ -1662,13 +2044,53 @@ fn release_archive(kind: ArchiveKind) -> Vec<u8> {
     let mut tar = Builder::new(encoder);
     append_file(&mut tar, "codex-proxy-rs", b"new-binary", false);
     append_file(&mut tar, "web/dist/index.html", b"new-web", false);
+    if !matches!(kind, ArchiveKind::MissingOfficialManifest) {
+        append_file(
+            &mut tar,
+            "plugins/official/plugin-release-manifest.json",
+            b"new-manifest",
+            false,
+        );
+    }
+    append_file(
+        &mut tar,
+        "plugins/official/new-plugin.tar.gz",
+        b"new-plugin",
+        false,
+    );
     if matches!(kind, ArchiveKind::UnsafePath) {
         append_file(&mut tar, "safe", b"escape", true);
     }
+    if matches!(kind, ArchiveKind::NestedOfficialAsset) {
+        append_file(
+            &mut tar,
+            "plugins/official/nested/plugin.tar.gz",
+            b"nested",
+            false,
+        );
+    }
+    if matches!(kind, ArchiveKind::OfficialSymlink) {
+        append_symlink(
+            &mut tar,
+            "plugins/official/linked.tar.gz",
+            "../outside.tar.gz",
+        );
+    }
     let encoder = tar.into_inner().expect("tar");
     encoder.finish().expect("gzip")
 }
 
+fn append_symlink(tar: &mut Builder<GzEncoder<Vec<u8>>>, name: &str, target: &str) {
+    let mut header = Header::new_gnu();
+    header.set_entry_type(EntryType::Symlink);
+    header.set_mode(0o777);
+    header.set_size(0);
+    header.set_path(name).expect("path");
+    header.set_link_name(target).expect("link target");
+    header.set_cksum();
+    tar.append(&header, std::io::empty()).expect("append link");
+}
+
 fn append_file(tar: &mut Builder<GzEncoder<Vec<u8>>>, name: &str, data: &[u8], unsafe_path: bool) {
     let mut header = Header::new_gnu();
     header.set_entry_type(EntryType::Regular);
diff --git a/backend/crates/gateway-plugin/runtime/Cargo.toml b/backend/crates/gateway-plugin/runtime/Cargo.toml
new file mode 100644
index 000000000..df0bb621b
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/Cargo.toml
@@ -0,0 +1,64 @@
+[package]
+name = "gateway-plugin-runtime"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+rust-version.workspace = true
+autotests = false
+
+[dependencies]
+async-trait = "0.1.89"
+base64 = "0.23.0"
+bytes = "1.11.1"
+chrono = { version = "0.4.44", default-features = false, features = ["clock"] }
+flate2 = "1.1.9"
+futures = "0.3.32"
+gateway-admin = { path = "../../gateway-admin" }
+gateway-core = { path = "../../gateway-core" }
+gateway-host = { path = "../../gateway-host" }
+gateway-plugin-sdk = { path = "../sdk", features = ["io"] }
+gateway-protocol = { path = "../../gateway-protocol" }
+hex = "0.4.3"
+image = { version = "0.25.8", default-features = false, features = ["bmp", "gif", "ico", "jpeg", "png", "webp"] }
+jsonschema = { version = "0.56.0", default-features = false }
+roxmltree = "0.21.1"
+semver = "1.0.27"
+secrecy = "0.10.3"
+serde = "1.0.228"
+serde_json = "1.0.150"
+sha2 = "0.11.0"
+tar = "0.4.44"
+tempfile = "3.27.0"
+thiserror = "2.0.18"
+tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt", "sync", "time", "io-util", "io-std"] }
+tracing = "0.1.44"
+uuid = { version = "1.23.3", features = ["v4"] }
+url = "2.5.8"
+
+[dev-dependencies]
+wiremock = "0.6.5"
+gateway-store = { path = "../../gateway-store" }
+sqlx = { version = "0.9.0", default-features = false, features = ["runtime-tokio", "tls-rustls", "postgres"] }
+tokio = { version = "1.52.3", default-features = false, features = ["rt-multi-thread", "test-util"] }
+
+[[bin]]
+name = "gateway-plugin-test-worker"
+path = "tests/support/worker.rs"
+test = false
+bench = false
+doc = false
+
+[[test]]
+name = "main"
+path = "tests/main.rs"
+
+[[bin]]
+name = "gateway-plugin-test-middleware"
+path = "tests/support/middleware.rs"
+test = false
+bench = false
+doc = false
+
+[lints]
+workspace = true
diff --git a/backend/crates/gateway-plugin/runtime/build.rs b/backend/crates/gateway-plugin/runtime/build.rs
new file mode 100644
index 000000000..f8eab7648
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/build.rs
@@ -0,0 +1,14 @@
+fn main() {
+    println!("cargo::rerun-if-changed=build.rs");
+    // 测试插件会反复装包和解包；调试段不参与协议行为，不能让它放大每个用例的 I/O。
+    // 仅调整两个测试子进程，宿主和测试入口仍保留完整调试信息。
+    let target_os = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    if matches!(target_os.as_str(), "linux" | "macos") {
+        for binary in [
+            "gateway-plugin-test-worker",
+            "gateway-plugin-test-middleware",
+        ] {
+            println!("cargo::rustc-link-arg-bin={binary}=-Wl,-S");
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json b/backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json
new file mode 100644
index 000000000..647748da2
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json
@@ -0,0 +1,31 @@
+{
+  "schema_version": 1,
+  "manifest_schema_versions": [3],
+  "protocol_versions": [4],
+  "capabilities": [
+    { "capability": "models", "versions": [1] },
+    { "capability": "authentication", "versions": [1] },
+    { "capability": "frontend_authentication", "versions": [1] },
+    { "capability": "scheduler", "versions": [1] },
+    { "capability": "model_router", "versions": [1] },
+    { "capability": "executor", "versions": [1] },
+    { "capability": "middleware", "versions": [1] },
+    { "capability": "request_lifecycle", "versions": [1] },
+    { "capability": "web_socket_observer", "versions": [1] },
+    { "capability": "usage", "versions": [1] },
+    { "capability": "command_line", "versions": [1] },
+    { "capability": "management", "versions": [1] },
+    { "capability": "quota", "versions": [1] },
+    { "capability": "request_profile", "versions": [1] },
+    { "capability": "account_management", "versions": [1] },
+    { "capability": "billing", "versions": [1] },
+    { "capability": "maintenance", "versions": [1] }
+  ],
+  "permissions": [
+    "network",
+    "models",
+    "accounts",
+    "requests",
+    "public_endpoints"
+  ]
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/command_line/duration.rs b/backend/crates/gateway-plugin/runtime/src/adapter/command_line/duration.rs
new file mode 100644
index 000000000..17311a40c
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/command_line/duration.rs
@@ -0,0 +1,58 @@
+//! CLI duration 使用精确十进制纳秒，不经浮点转换或平台宽度截断。
+
+pub(super) fn parse(value: &str) -> Option<i64> {
+    let (negative, mut remaining) = match value.as_bytes().first()? {
+        b'-' => (true, &value[1..]),
+        b'+' => (false, &value[1..]),
+        _ => (false, value),
+    };
+    if remaining == "0" {
+        return Some(0);
+    }
+    let mut total = 0u128;
+    let mut parts = 0;
+    while !remaining.is_empty() {
+        let end =
+            remaining.find(|character: char| !character.is_ascii_digit() && character != '.')?;
+        let number = &remaining[..end];
+        remaining = &remaining[end..];
+        let (unit, multiplier) = [
+            ("ns", 1u128),
+            ("us", 1_000),
+            ("µs", 1_000),
+            ("ms", 1_000_000),
+            ("s", 1_000_000_000),
+            ("m", 60_000_000_000),
+            ("h", 3_600_000_000_000),
+        ]
+        .into_iter()
+        .find(|(unit, _)| remaining.starts_with(unit))?;
+        remaining = &remaining[unit.len()..];
+        let (whole, fraction) = number.split_once('.').unwrap_or((number, ""));
+        if whole.is_empty() && fraction.is_empty() || fraction.len() > 9 {
+            return None;
+        }
+        let whole = if whole.is_empty() {
+            0
+        } else {
+            whole.parse::<u128>().ok()?
+        };
+        let fraction = if fraction.is_empty() {
+            0
+        } else {
+            let numerator = fraction.parse::<u128>().ok()?.checked_mul(multiplier)?;
+            let denominator = 10u128.checked_pow(u32::try_from(fraction.len()).ok()?)?;
+            if numerator % denominator != 0 {
+                return None;
+            }
+            numerator / denominator
+        };
+        total = total.checked_add(whole.checked_mul(multiplier)?.checked_add(fraction)?)?;
+        parts += 1;
+    }
+    if parts == 0 {
+        return None;
+    }
+    let signed = i128::try_from(total).ok()?;
+    i64::try_from(if negative { -signed } else { signed }).ok()
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/command_line/execution.rs b/backend/crates/gateway-plugin/runtime/src/adapter/command_line/execution.rs
new file mode 100644
index 000000000..a554781c3
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/command_line/execution.rs
@@ -0,0 +1,140 @@
+use gateway_admin::model::AdminError;
+use gateway_core::lifecycle::CancellationToken;
+use gateway_plugin_sdk::{Stage, call::management::CommandResult};
+
+use super::{
+    PluginCommand, PluginCommandError, PluginCommandOutput, PluginCommandSession, parameters,
+};
+use crate::{RpcError, RpcLimits};
+
+const MAXIMUM_OUTPUT_BYTES: usize = 64 * 1024;
+
+impl PluginCommandSession {
+    pub async fn execute(
+        &self,
+        instance_id: &str,
+        name: &str,
+        arguments: &[String],
+    ) -> Result<PluginCommandOutput, PluginCommandError> {
+        self.execute_cancellable(instance_id, name, arguments, &CancellationToken::new())
+            .await
+    }
+
+    pub async fn execute_cancellable(
+        &self,
+        instance_id: &str,
+        name: &str,
+        arguments: &[String],
+        cancellation: &CancellationToken,
+    ) -> Result<PluginCommandOutput, PluginCommandError> {
+        let command = self.find(instance_id, name)?;
+        let invocation = parameters::parse(&command.descriptor, arguments)?;
+        let snapshot = self
+            .store
+            .load_instances()
+            .await
+            .map_err(|_| AdminError::unavailable("无法复核插件命令授权"))?;
+        if !snapshot.instances.iter().any(|instance| {
+            instance.id == command.instance_id
+                && instance.enabled
+                && instance.trusted_process
+                && instance.revision == command.revision
+                && instance.artifact_sha256 == command.artifact_sha256
+        }) {
+            return Err(AdminError::conflict("插件命令配置或授权已变化，请重新读取命令").into());
+        }
+        let payload = serde_json::to_vec(&invocation)
+            .map_err(|_| AdminError::invalid("插件命令参数无法编码"))?;
+        if payload.len() > self.limits.maximum_frame_bytes.saturating_sub(4096) {
+            return Err(AdminError::invalid("插件命令参数超过帧预算").into());
+        }
+        let mut saved_accounts = 0;
+        let result = tokio::select! {
+            biased;
+            () = cancellation.cancelled() => Ok(Err("调用已取消")),
+            result = tokio::time::timeout(
+                self.limits.maximum_call_timeout,
+                command.execute(payload, self.limits, &mut saved_accounts),
+            ) => result,
+        };
+        match result {
+            Ok(Ok(output)) => Ok(output),
+            // 一旦执行已开始，账号/私有状态回调也可能提交；仅 HTTP 未发送不能证明无副作用。
+            Ok(Err(reason)) => Err(PluginCommandError::Incomplete {
+                saved_accounts,
+                reason,
+            }),
+            Err(_) => Err(PluginCommandError::Incomplete {
+                saved_accounts,
+                reason: "超过命令总期限",
+            }),
+        }
+    }
+}
+
+impl PluginCommand {
+    async fn execute(
+        &self,
+        payload: Vec<u8>,
+        limits: RpcLimits,
+        saved_accounts: &mut usize,
+    ) -> Result<PluginCommandOutput, &'static str> {
+        let mut context = self
+            .session
+            .context(Stage::CommandLine, limits.maximum_call_timeout);
+        context.request_id = Some(uuid::Uuid::new_v4().to_string());
+        let scope = self
+            .callbacks
+            .prepare_command_line(&context)
+            .map_err(|_| "回调授权上下文无效")?;
+        let reply = self
+            .session
+            .call(
+                "command_line.execute",
+                context.clone(),
+                serde_json::json!({}),
+                payload,
+            )
+            .await
+            .map_err(rpc_failure)?;
+        if reply.result != serde_json::json!({}) || reply.payload.len() > limits.maximum_frame_bytes
+        {
+            return Err("结果信封无效");
+        }
+        let result: CommandResult =
+            serde_json::from_slice(&reply.payload).map_err(|_| "结果数据无效")?;
+        if result.stdout.len() > MAXIMUM_OUTPUT_BYTES
+            || result.stderr.len() > MAXIMUM_OUTPUT_BYTES
+            || result.accounts.len() > 32
+        {
+            return Err("结果大小或账号范围无效");
+        }
+        if result.exit_code == 0 {
+            for account in result.accounts {
+                self.callbacks
+                    .save_command_account(&context, &scope, account)
+                    .await
+                    .map_err(|_| "账号提交未确认")?;
+                *saved_accounts += 1;
+            }
+        }
+        Ok(PluginCommandOutput {
+            stdout: result.stdout,
+            stderr: result.stderr,
+            exit_code: result.exit_code,
+            saved_accounts: *saved_accounts,
+        })
+    }
+}
+
+fn rpc_failure(error: RpcError) -> &'static str {
+    match error {
+        RpcError::Timeout => "插件响应超时",
+        RpcError::Cancelled => "调用已取消",
+        RpcError::Closed | RpcError::Start(_) => "插件进程不可用",
+        RpcError::Handshake | RpcError::Protocol => "插件协议错误",
+        RpcError::Capacity => "插件调用容量不足",
+        RpcError::Context => "调用上下文无效",
+        RpcError::Remote(_) => "插件拒绝命令",
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/command_line/mod.rs b/backend/crates/gateway-plugin/runtime/src/adapter/command_line/mod.rs
new file mode 100644
index 000000000..92606a38a
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/command_line/mod.rs
@@ -0,0 +1,128 @@
+mod duration;
+mod execution;
+mod parameters;
+mod registration;
+
+pub(crate) use registration::prepare;
+
+use std::sync::Arc;
+
+use gateway_admin::{
+    model::{AdminError, Revision},
+    ports::plugins::PluginStore,
+};
+use gateway_core::runtime::extensions::ExtensionSetReference;
+use gateway_plugin_sdk::call::management::CommandDescriptor;
+
+use crate::{RpcLimits, RpcSession, callback::PluginCallbacks};
+
+pub(crate) struct PluginCommand {
+    instance_id: String,
+    artifact_sha256: String,
+    revision: Revision,
+    descriptor: CommandDescriptor,
+    session: Arc<RpcSession>,
+    callbacks: Arc<PluginCallbacks>,
+}
+
+/// 命令列表与执行共同保活已准备集合；这里不维护另一份当前代次。
+pub struct PluginCommandSession {
+    _reference: ExtensionSetReference,
+    commands: Vec<Arc<PluginCommand>>,
+    sessions: Vec<Arc<RpcSession>>,
+    store: Arc<dyn PluginStore>,
+    limits: RpcLimits,
+}
+
+/// 输出只交付显式 CLI 调用方，不作为诊断内容。
+pub struct PluginCommandOutput {
+    pub stdout: String,
+    pub stderr: String,
+    pub exit_code: u8,
+    pub saved_accounts: usize,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum PluginCommandError {
+    #[error(transparent)]
+    Invalid(#[from] AdminError),
+    #[error(
+        "插件命令未完整完成（{reason}），已确认保存 {saved_accounts} 个账号，其余副作用结果未知；请核对后再决定是否重试"
+    )]
+    Incomplete {
+        saved_accounts: usize,
+        reason: &'static str,
+    },
+}
+
+impl PluginCommandSession {
+    pub(crate) fn new(
+        reference: ExtensionSetReference,
+        commands: Vec<Arc<PluginCommand>>,
+        sessions: Vec<Arc<RpcSession>>,
+        store: Arc<dyn PluginStore>,
+        limits: RpcLimits,
+    ) -> Self {
+        Self {
+            _reference: reference,
+            commands,
+            sessions,
+            store,
+            limits,
+        }
+    }
+
+    /// CLI 专属终止入口；调用方不能将该集合同时发布给运行中的 HTTP 网关。
+    /// 包括未声明命令、但为候选校验而启动的进程，全部回收后才允许退出主 Runtime。
+    pub async fn shutdown(self) {
+        for session in &self.sessions {
+            session.quiesce();
+        }
+        futures::future::join_all(
+            self.sessions
+                .iter()
+                .map(|session| session.shutdown(std::time::Duration::from_secs(1))),
+        )
+        .await;
+    }
+
+    pub fn help(
+        &self,
+        instance_id: Option<&str>,
+        name: Option<&str>,
+    ) -> Result<String, AdminError> {
+        if let (Some(instance_id), Some(name)) = (instance_id, name) {
+            let command = self.find(instance_id, name)?;
+            return Ok(format!(
+                "用法: codex-proxy-rs plugin {instance_id} {name} [参数]\n{}",
+                parameters::help(&command.descriptor)
+            ));
+        }
+        let mut output = String::from("用法: codex-proxy-rs plugin <实例 ID> <命令> [参数]\n\n");
+        let mut found = false;
+        for command in &self.commands {
+            if instance_id.is_none_or(|id| id == command.instance_id) {
+                found = true;
+                output.push_str(&format!(
+                    "  {} {}  {}\n",
+                    command.instance_id, command.descriptor.name, command.descriptor.description
+                ));
+            }
+        }
+        if !found && instance_id.is_some() {
+            return Err(AdminError::not_found("插件实例没有可用命令"));
+        }
+        if !found {
+            output.push_str("没有已启用的插件命令\n");
+        }
+        Ok(output)
+    }
+
+    fn find(&self, instance_id: &str, name: &str) -> Result<&PluginCommand, AdminError> {
+        self.commands
+            .iter()
+            .find(|command| command.instance_id == instance_id && command.descriptor.name == name)
+            .map(AsRef::as_ref)
+            .ok_or_else(|| AdminError::not_found("插件命令不存在或未启用"))
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/command_line/parameters.rs b/backend/crates/gateway-plugin/runtime/src/adapter/command_line/parameters.rs
new file mode 100644
index 000000000..6bd786cff
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/command_line/parameters.rs
@@ -0,0 +1,178 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use gateway_admin::model::AdminError;
+use gateway_plugin_sdk::call::management::{
+    CommandDescriptor, CommandInvocation, CommandParameterType, CommandValue,
+};
+
+const MAXIMUM_ARGUMENT_BYTES: usize = 64 * 1024;
+
+pub(super) fn validate(command: &CommandDescriptor) -> Result<(), AdminError> {
+    let mut names = BTreeSet::new();
+    if !identifier(&command.name)
+        || matches!(
+            command.name.as_str(),
+            "help" | "version" | "serve" | "plugin"
+        )
+        || !description(&command.description)
+        || command.parameters.len() > 64
+    {
+        return Err(AdminError::invalid("插件命令描述不合法"));
+    }
+    for parameter in &command.parameters {
+        if !identifier(&parameter.name)
+            || matches!(parameter.name.as_str(), "help" | "version")
+            || !description(&parameter.description)
+            || !names.insert(&parameter.name)
+            || parameter.default.as_ref().is_some_and(|value| {
+                !matches_type(value, parameter.value_type)
+                    || parameter.required
+                    || matches!(value, CommandValue::String(value) if value.len() > MAXIMUM_ARGUMENT_BYTES)
+            })
+        {
+            return Err(AdminError::invalid("插件命令参数、默认值或名称冲突"));
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn parse(
+    command: &CommandDescriptor,
+    arguments: &[String],
+) -> Result<CommandInvocation, AdminError> {
+    if arguments.len() > 128
+        || arguments
+            .iter()
+            .try_fold(0usize, |size, argument| size.checked_add(argument.len()))
+            .is_none_or(|size| size > MAXIMUM_ARGUMENT_BYTES)
+    {
+        return Err(AdminError::invalid("插件命令参数超过大小限制"));
+    }
+    let mut values = BTreeMap::new();
+    let mut arguments = arguments.iter().peekable();
+    while let Some(argument) = arguments.next() {
+        let argument = argument.strip_prefix("--").ok_or_else(invalid_argument)?;
+        let (name, inline) = argument
+            .split_once('=')
+            .map_or((argument, None), |(name, value)| (name, Some(value)));
+        let parameter = command
+            .parameters
+            .iter()
+            .find(|parameter| parameter.name == name)
+            .ok_or_else(invalid_argument)?;
+        if values.contains_key(name) {
+            return Err(invalid_argument());
+        }
+        let value = if parameter.value_type == CommandParameterType::Bool && inline.is_none() {
+            CommandValue::Bool(true)
+        } else {
+            let text = inline
+                .or_else(|| arguments.next().map(String::as_str))
+                .ok_or_else(invalid_argument)?;
+            parse_value(text, parameter.value_type).ok_or_else(invalid_argument)?
+        };
+        values.insert(name.to_owned(), value);
+    }
+    for parameter in &command.parameters {
+        if !values.contains_key(&parameter.name) {
+            if let Some(default) = &parameter.default {
+                values.insert(parameter.name.clone(), default.clone());
+            } else if parameter.required {
+                return Err(AdminError::invalid(format!(
+                    "缺少必填插件参数 --{}",
+                    parameter.name
+                )));
+            }
+        }
+    }
+    Ok(CommandInvocation {
+        name: command.name.clone(),
+        arguments: values,
+    })
+}
+
+pub(super) fn help(command: &CommandDescriptor) -> String {
+    let mut output = format!("{}\n", command.description);
+    for parameter in &command.parameters {
+        let value_type = match parameter.value_type {
+            CommandParameterType::Bool => "bool",
+            CommandParameterType::String => "string",
+            CommandParameterType::Int => "int",
+            CommandParameterType::Int64 => "int64",
+            CommandParameterType::Float64 => "float64",
+            CommandParameterType::Duration => "duration",
+        };
+        output.push_str(&format!(
+            "  --{} <{}>  {}",
+            parameter.name, value_type, parameter.description
+        ));
+        if parameter.required {
+            output.push_str(" [必填]");
+        }
+        if let Some(value) = &parameter.default {
+            output.push_str(" [默认: ");
+            if parameter.sensitive {
+                output.push_str("已隐藏");
+            } else if let Ok(value) = serde_json::to_value(value) {
+                output.push_str(&value["value"].to_string());
+                if parameter.value_type == CommandParameterType::Duration {
+                    output.push_str("ns");
+                }
+            }
+            output.push(']');
+        }
+        output.push('\n');
+    }
+    output.push_str("  --help  仅显示帮助，不执行命令\n");
+    output
+}
+
+fn parse_value(value: &str, kind: CommandParameterType) -> Option<CommandValue> {
+    Some(match kind {
+        CommandParameterType::Bool => CommandValue::Bool(match value {
+            "true" => true,
+            "false" => false,
+            _ => return None,
+        }),
+        CommandParameterType::String => CommandValue::String(value.to_owned()),
+        CommandParameterType::Int => CommandValue::Int(value.parse().ok()?),
+        CommandParameterType::Int64 => CommandValue::Int64(value.parse().ok()?),
+        CommandParameterType::Float64 => {
+            let number: f64 = value.parse().ok()?;
+            if !number.is_finite() {
+                return None;
+            }
+            CommandValue::Float64(number)
+        }
+        CommandParameterType::Duration => CommandValue::Duration(super::duration::parse(value)?),
+    })
+}
+
+fn matches_type(value: &CommandValue, kind: CommandParameterType) -> bool {
+    match (value, kind) {
+        (CommandValue::Bool(_), CommandParameterType::Bool)
+        | (CommandValue::String(_), CommandParameterType::String)
+        | (CommandValue::Int(_), CommandParameterType::Int)
+        | (CommandValue::Int64(_), CommandParameterType::Int64)
+        | (CommandValue::Duration(_), CommandParameterType::Duration) => true,
+        (CommandValue::Float64(value), CommandParameterType::Float64) => value.is_finite(),
+        _ => false,
+    }
+}
+
+fn identifier(value: &str) -> bool {
+    (1..=64).contains(&value.len())
+        && value.as_bytes()[0].is_ascii_lowercase()
+        && value.bytes().all(|byte| {
+            byte.is_ascii_lowercase() || byte.is_ascii_digit() || matches!(byte, b'-' | b'_')
+        })
+}
+
+fn description(value: &str) -> bool {
+    !value.trim().is_empty() && value.len() <= 1024 && !value.chars().any(char::is_control)
+}
+
+fn invalid_argument() -> AdminError {
+    // 不回显用户参数；即使未声明 sensitive，参数也可能包含凭据。
+    AdminError::invalid("插件命令参数未知、重复、缺值或类型不正确；请查看 --help")
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/command_line/registration.rs b/backend/crates/gateway-plugin/runtime/src/adapter/command_line/registration.rs
new file mode 100644
index 000000000..24d036482
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/command_line/registration.rs
@@ -0,0 +1,57 @@
+use super::{PluginCommand, parameters};
+use crate::{RpcSession, callback::PluginCallbacks};
+use gateway_admin::model::{AdminError, plugins::instances::PluginInstance};
+use gateway_plugin_sdk::{Capability, Manifest, Stage, call::management::CommandRegistration};
+use std::{sync::Arc, time::Duration};
+
+const MAXIMUM_REGISTRATION_BYTES: usize = 64 * 1024;
+
+pub(crate) async fn prepare(
+    instance: &PluginInstance,
+    manifest: &Manifest,
+    session: Arc<RpcSession>,
+    callbacks: Arc<PluginCallbacks>,
+) -> Result<Vec<Arc<PluginCommand>>, AdminError> {
+    let Some(declaration) = manifest.contributes.get(&Capability::CommandLine) else {
+        return Ok(Vec::new());
+    };
+    if declaration.stages != [Stage::CommandLine] {
+        return Err(AdminError::invalid("命令行能力必须声明 command_line 阶段"));
+    }
+    let reply = session
+        .call(
+            "command_line.register",
+            session.context(Stage::Registration, Duration::from_secs(5)),
+            serde_json::json!({}),
+            Vec::new(),
+        )
+        .await
+        .map_err(|_| AdminError::invalid("插件命令注册失败"))?;
+    if reply.result != serde_json::json!({}) || reply.payload.len() > MAXIMUM_REGISTRATION_BYTES {
+        return Err(AdminError::invalid("插件命令注册信封无效或过大"));
+    }
+    let registration: CommandRegistration = serde_json::from_slice(&reply.payload)
+        .map_err(|_| AdminError::invalid("插件命令注册数据无效"))?;
+    if registration.commands.is_empty() || registration.commands.len() > 32 {
+        return Err(AdminError::invalid("每个插件须注册 1 至 32 个命令"));
+    }
+    let mut names = std::collections::BTreeSet::new();
+    registration
+        .commands
+        .into_iter()
+        .map(|descriptor| {
+            parameters::validate(&descriptor)?;
+            if !names.insert(descriptor.name.clone()) {
+                return Err(AdminError::invalid("插件命令名重复"));
+            }
+            Ok(Arc::new(PluginCommand {
+                instance_id: instance.id.clone(),
+                artifact_sha256: instance.artifact_sha256.clone(),
+                revision: instance.revision,
+                descriptor,
+                session: session.clone(),
+                callbacks: callbacks.clone(),
+            }))
+        })
+        .collect()
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/frontend_authentication.rs b/backend/crates/gateway-plugin/runtime/src/adapter/frontend_authentication.rs
new file mode 100644
index 000000000..074a1e6c4
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/frontend_authentication.rs
@@ -0,0 +1,254 @@
+use std::{collections::BTreeMap, sync::Arc, time::Duration};
+
+use futures::future::BoxFuture;
+use gateway_admin::model::{
+    AdminError,
+    plugins::instances::{
+        PluginCapabilityBinding, PluginFailurePolicy, PluginFrontendIdentityBinding, PluginInstance,
+    },
+};
+use gateway_core::{
+    engine::authentication::{
+        ClientAuthenticationRequest, FrontendAuthenticationDecision, FrontendAuthenticationError,
+        FrontendAuthenticationPlan,
+    },
+    policy::ClientApiKeyId,
+};
+use gateway_plugin_sdk::{
+    Capability, Manifest, Stage,
+    call::frontend_authentication::{
+        FrontendAuthenticationIdentifier, FrontendAuthenticationRequest,
+        FrontendAuthenticationResult,
+    },
+};
+
+use crate::{RpcSession, callback::PluginCallbacks};
+
+const IDENTIFIER_TIMEOUT: Duration = Duration::from_secs(5);
+
+pub(crate) struct FrontendAuthenticationEntry {
+    identities: BTreeMap<String, ClientApiKeyId>,
+    exclusive: bool,
+    invocation: Option<(Arc<RpcSession>, Arc<PluginCallbacks>)>,
+}
+
+pub(crate) async fn prepare_entry(
+    manifest: &Manifest,
+    bindings: &[PluginCapabilityBinding],
+    session: Arc<RpcSession>,
+    callbacks: Arc<PluginCallbacks>,
+) -> Result<Option<FrontendAuthenticationEntry>, AdminError> {
+    let Some(compiled) = compile_binding(manifest, bindings)? else {
+        return Ok(None);
+    };
+    let reply = session
+        .call(
+            "frontend_auth.identifier",
+            session.context(Stage::Registration, IDENTIFIER_TIMEOUT),
+            serde_json::json!({}),
+            Vec::new(),
+        )
+        .await
+        .map_err(|_| AdminError::invalid("插件入口认证器注册失败"))?;
+    if !reply.payload.is_empty() {
+        return Err(AdminError::invalid("插件入口认证器注册结果无效"));
+    }
+    let identifier: FrontendAuthenticationIdentifier = serde_json::from_value(reply.result)
+        .map_err(|_| AdminError::invalid("插件入口认证器注册结果无效"))?;
+    if !valid_identifier(&identifier.identifier) {
+        return Err(AdminError::invalid("插件入口认证器标识无效"));
+    }
+    Ok(Some(FrontendAuthenticationEntry {
+        identities: compiled.identities,
+        exclusive: compiled.binding.failure_policy == PluginFailurePolicy::Reject,
+        invocation: Some((session, callbacks)),
+    }))
+}
+
+/// 认证器恢复失败仍占据认证入口，不能静默改走其他认证路径。
+pub(crate) fn unavailable_entry(instance: &PluginInstance) -> Option<FrontendAuthenticationEntry> {
+    instance
+        .bindings
+        .iter()
+        .find(|binding| binding.stage == "authentication")
+        .map(|binding| FrontendAuthenticationEntry {
+            identities: BTreeMap::new(),
+            exclusive: binding.failure_policy == PluginFailurePolicy::Reject,
+            invocation: None,
+        })
+}
+
+pub(crate) fn validate_bindings(
+    manifest: &Manifest,
+    bindings: &[PluginCapabilityBinding],
+) -> Result<(), AdminError> {
+    compile_binding(manifest, bindings).map(drop)
+}
+
+struct CompiledBinding<'a> {
+    binding: &'a PluginCapabilityBinding,
+    identities: BTreeMap<String, ClientApiKeyId>,
+}
+
+fn compile_binding<'a>(
+    manifest: &Manifest,
+    bindings: &'a [PluginCapabilityBinding],
+) -> Result<Option<CompiledBinding<'a>>, AdminError> {
+    let mut selected = None;
+    for binding in bindings {
+        if crate::contribution::resolve(manifest, binding)?.capability
+            != Capability::FrontendAuthentication
+        {
+            continue;
+        }
+        if selected.replace(binding).is_some() {
+            return Err(AdminError::invalid(
+                "同一插件实例的入口认证能力只能绑定一次",
+            ));
+        }
+    }
+    let Some(binding) = selected else {
+        return Ok(None);
+    };
+    let stage: Stage = serde_json::from_value(serde_json::Value::String(binding.stage.clone()))
+        .map_err(|_| AdminError::invalid("插件入口认证阶段无效"))?;
+    if stage != Stage::Authentication
+        || !matches!(
+            &binding.failure_policy,
+            PluginFailurePolicy::Reject | PluginFailurePolicy::Delegate
+        )
+        || !binding.client_key_ids.is_empty()
+        || !binding.account_group_ids.is_empty()
+        || !binding.provider_ids.is_empty()
+        || !binding.models.is_empty()
+    {
+        return Err(AdminError::invalid(
+            "入口认证绑定必须使用 authentication 与 reject/delegate",
+        ));
+    }
+    Ok(Some(CompiledBinding {
+        binding,
+        identities: compile_identities(&binding.identity_bindings)?,
+    }))
+}
+
+fn compile_identities(
+    bindings: &[PluginFrontendIdentityBinding],
+) -> Result<BTreeMap<String, ClientApiKeyId>, AdminError> {
+    if bindings.is_empty() || bindings.len() > 256 {
+        return Err(AdminError::invalid("入口认证身份映射不能为空或超过上限"));
+    }
+    let mut identities = BTreeMap::new();
+    for binding in bindings {
+        if binding.principal.trim() != binding.principal
+            || binding.principal.is_empty()
+            || binding.principal.len() > 256
+            || binding.principal.chars().any(char::is_control)
+        {
+            return Err(AdminError::invalid("入口认证 principal 无效"));
+        }
+        let key = ClientApiKeyId::new(binding.client_key_id.clone())
+            .map_err(|_| AdminError::invalid("入口认证 Client Key ID 无效"))?;
+        if identities.insert(binding.principal.clone(), key).is_some() {
+            return Err(AdminError::invalid("入口认证 principal 重复"));
+        }
+    }
+    Ok(identities)
+}
+
+fn valid_identifier(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 128
+        && value.as_bytes()[0].is_ascii_lowercase()
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || b"-_".contains(&byte))
+}
+
+pub(crate) struct PluginFrontendAuthenticationPlan {
+    entry: FrontendAuthenticationEntry,
+    timeout: Duration,
+}
+
+impl PluginFrontendAuthenticationPlan {
+    pub(crate) fn compile(
+        mut entries: Vec<FrontendAuthenticationEntry>,
+        maximum_call_timeout: Duration,
+    ) -> Result<Option<Arc<Self>>, AdminError> {
+        match entries.len() {
+            0 => Ok(None),
+            1 => Ok(Some(Arc::new(Self {
+                entry: entries.pop().expect("one entry was checked"),
+                timeout: maximum_call_timeout.min(Duration::from_secs(30)),
+            }))),
+            _ => Err(AdminError::invalid("同一发布集合只能启用一个入口认证插件")),
+        }
+    }
+}
+
+impl FrontendAuthenticationPlan for PluginFrontendAuthenticationPlan {
+    fn authenticate<'a>(
+        &'a self,
+        request: &'a ClientAuthenticationRequest,
+    ) -> BoxFuture<'a, Result<FrontendAuthenticationDecision, FrontendAuthenticationError>> {
+        Box::pin(async move {
+            let (session, callbacks) = self
+                .entry
+                .invocation
+                .as_ref()
+                .ok_or(FrontendAuthenticationError)?;
+            let context = session.context(Stage::Authentication, self.timeout);
+            let _scope = callbacks
+                .prepare_frontend_authentication(&context)
+                .map_err(|_| FrontendAuthenticationError)?;
+            let input = FrontendAuthenticationRequest {
+                authorization: request.authorization().to_owned(),
+            };
+            let reply = session
+                .call(
+                    "frontend_auth.authenticate",
+                    context,
+                    serde_json::json!({}),
+                    serde_json::to_vec(&input).map_err(|_| FrontendAuthenticationError)?,
+                )
+                .await
+                .map_err(|_| FrontendAuthenticationError)?;
+            if reply.result != serde_json::json!({}) {
+                return Err(FrontendAuthenticationError);
+            }
+            let result: FrontendAuthenticationResult =
+                serde_json::from_slice(&reply.payload).map_err(|_| FrontendAuthenticationError)?;
+            match result {
+                FrontendAuthenticationResult::Authenticated { principal }
+                    if valid_principal(&principal) =>
+                {
+                    Ok(FrontendAuthenticationDecision::Authenticated { principal })
+                }
+                FrontendAuthenticationResult::Authenticated { .. } => {
+                    Err(FrontendAuthenticationError)
+                }
+                FrontendAuthenticationResult::NotMatched {} => {
+                    Ok(FrontendAuthenticationDecision::NotMatched)
+                }
+                FrontendAuthenticationResult::Rejected {} => {
+                    Ok(FrontendAuthenticationDecision::Rejected)
+                }
+            }
+        })
+    }
+
+    fn client_key_id(&self, principal: &str) -> Option<ClientApiKeyId> {
+        self.entry.identities.get(principal).cloned()
+    }
+
+    fn exclusive(&self) -> bool {
+        self.entry.exclusive
+    }
+}
+
+fn valid_principal(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 256
+        && value.trim() == value
+        && !value.chars().any(char::is_control)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/management/callback.rs b/backend/crates/gateway-plugin/runtime/src/adapter/management/callback.rs
new file mode 100644
index 000000000..5efac75e6
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/management/callback.rs
@@ -0,0 +1,198 @@
+use std::time::Duration;
+
+use chrono::Utc;
+use gateway_admin::model::{
+    AdminError,
+    auth::{AdminPrincipal, AdminRequestContext},
+    plugins::management::{
+        PluginManagementCallbackTicket, PluginManagementRequest, PluginManagementResponse,
+        PluginManagementTarget, StartPluginManagementCallback,
+    },
+};
+use gateway_core::{
+    account::OpaqueProviderData,
+    provider_ports::{
+        NewOAuthPendingFlow, OAuthPendingBinding, OAuthPendingClaimOutcome,
+        OAuthPendingConsumeOutcome, OAuthPendingFlowPort, OAuthPendingPutOutcome,
+    },
+    routing::ProviderKind,
+};
+use gateway_plugin_sdk::{Stage, call::management::ManagementRequest};
+use serde::{Deserialize, Serialize};
+use sha2::{Digest as _, Sha256};
+
+use super::ManagementEntry;
+use crate::RpcLimits;
+
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct CallbackState {
+    target: PluginManagementTarget,
+    path: String,
+    expires_at_ms: i64,
+    owner_digest: String,
+}
+
+impl ManagementEntry {
+    pub(crate) async fn start_callback(
+        &self,
+        store: &dyn OAuthPendingFlowPort,
+        command: StartPluginManagementCallback,
+        context: &AdminRequestContext,
+    ) -> Result<PluginManagementCallbackTicket, AdminError> {
+        if !(1..=600).contains(&command.ttl_seconds)
+            || !self
+                .view
+                .callbacks
+                .iter()
+                .any(|callback| callback.path == command.path)
+        {
+            return Err(AdminError::invalid(
+                "插件登录回调未注册或期限不在 1 至 600 秒内",
+            ));
+        }
+        let flow = uuid::Uuid::new_v4().simple().to_string();
+        let mut owner = Sha256::new();
+        // state 中的 owner 为随机且不可反查管理员的摘要；实际身份仅来自已验证的 Admin 上下文。
+        owner.update(uuid::Uuid::new_v4().as_bytes());
+        match &context.principal {
+            AdminPrincipal::Session { admin_user_id } => {
+                owner.update(b"admin-session:");
+                owner.update(admin_user_id.as_bytes());
+            }
+            AdminPrincipal::ApiKey => owner.update(b"admin-api-key"),
+        }
+        owner.update(self.view.target.instance_id.as_bytes());
+        owner.update(command.path.as_bytes());
+        let owner = hex::encode(owner.finalize());
+        let expires_at_ms = Utc::now().timestamp_millis() + i64::from(command.ttl_seconds) * 1000;
+        let payload = serde_json::to_value(CallbackState {
+            target: self.view.target.clone(),
+            path: command.path,
+            expires_at_ms,
+            owner_digest: owner.clone(),
+        })
+        .map_err(|_| unavailable())?;
+        let payload = serde_json::from_value(payload).map_err(|_| unavailable())?;
+        let pending = NewOAuthPendingFlow::try_new(
+            namespace(&self.view.target)?,
+            binding(&flow)?,
+            binding(&owner)?,
+            Duration::from_secs(u64::from(command.ttl_seconds)),
+            OpaqueProviderData::new(payload),
+        )
+        .map_err(|_| unavailable())?;
+        if store
+            .put_if_absent(pending)
+            .await
+            .map_err(|_| unavailable())?
+            != OAuthPendingPutOutcome::Stored
+        {
+            return Err(unavailable());
+        }
+        Ok(PluginManagementCallbackTicket {
+            state: format!("{flow}.{owner}"),
+            expires_at_ms,
+        })
+    }
+
+    pub(crate) async fn callback(
+        &self,
+        store: &dyn OAuthPendingFlowPort,
+        state: &str,
+        request: PluginManagementRequest,
+        limits: RpcLimits,
+    ) -> Result<PluginManagementResponse, AdminError> {
+        let descriptor = self
+            .view
+            .callbacks
+            .iter()
+            .find(|callback| callback.path == request.path)
+            .ok_or_else(invalid_state)?;
+        if request.method != "GET"
+            || !request.body.is_empty()
+            || request.content_type.is_some()
+            || request.query.len() > 8192
+            || request.query.bytes().any(|byte| byte.is_ascii_control())
+        {
+            return Err(AdminError::invalid("插件登录回调请求无效"));
+        }
+        let (flow, owner) = state
+            .split_once('.')
+            .filter(|(flow, owner)| {
+                flow.len() == 32
+                    && owner.len() == 64
+                    && flow
+                        .bytes()
+                        .chain(owner.bytes())
+                        .all(|byte| byte.is_ascii_hexdigit())
+            })
+            .ok_or_else(invalid_state)?;
+        let flow = binding(flow)?;
+        let owner = binding(owner)?;
+        let claim = binding(&uuid::Uuid::new_v4().simple().to_string())?;
+        let namespace = namespace(&self.view.target)?;
+        let payload = match store
+            .claim_if_owner(&namespace, &flow, &owner, &claim, Duration::from_secs(30))
+            .await
+            .map_err(|_| unavailable())?
+        {
+            OAuthPendingClaimOutcome::Claimed(payload) => payload,
+            _ => return Err(invalid_state()),
+        };
+        // 在任何插件执行之前消耗 state；崩溃或响应丢失不得重放登录回调。
+        if store
+            .consume_claim(&namespace, &flow, &owner, &claim)
+            .await
+            .map_err(|_| unavailable())?
+            != OAuthPendingConsumeOutcome::Consumed
+        {
+            return Err(invalid_state());
+        }
+        let stored: CallbackState =
+            serde_json::from_value(serde_json::Value::Object(payload.into_inner()))
+                .map_err(|_| invalid_state())?;
+        if stored.target != self.view.target
+            || stored.path != request.path
+            || stored.expires_at_ms <= Utc::now().timestamp_millis()
+            || stored.owner_digest != owner.expose_to_store()
+        {
+            return Err(invalid_state());
+        }
+        let mut context = self
+            .session
+            .context(Stage::PublicManagement, limits.maximum_call_timeout);
+        context.request_id = Some(request.request_id);
+        let params = serde_json::to_value(ManagementRequest {
+            method: request.method,
+            path: request.path,
+            query: request.query,
+            content_type: None,
+        })
+        .map_err(|_| unavailable())?;
+        let reply = self
+            .session
+            .call("management.callback", context, params, Vec::new())
+            .await
+            .map_err(|_| {
+                AdminError::unavailable("插件登录回调未完成；state 已消费，请重新发起登录")
+            })?;
+        super::decode_response(reply, &descriptor.response_content_types, limits)
+    }
+}
+
+fn namespace(target: &PluginManagementTarget) -> Result<ProviderKind, AdminError> {
+    ProviderKind::new(format!("plugin-management-{}", target.instance_id))
+        .map_err(|_| unavailable())
+}
+
+fn binding(value: &str) -> Result<OAuthPendingBinding, AdminError> {
+    OAuthPendingBinding::try_new(value).map_err(|_| invalid_state())
+}
+
+fn invalid_state() -> AdminError {
+    AdminError::invalid("插件登录 state 无效、已过期或已消费")
+}
+fn unavailable() -> AdminError {
+    AdminError::unavailable("插件登录回调状态暂不可用")
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/management/mod.rs b/backend/crates/gateway-plugin/runtime/src/adapter/management/mod.rs
new file mode 100644
index 000000000..c33b83f08
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/management/mod.rs
@@ -0,0 +1,128 @@
+mod callback;
+mod registration;
+mod validation;
+
+use std::{collections::BTreeMap, sync::Arc};
+
+use gateway_admin::model::{
+    AdminError,
+    plugins::management::{
+        PluginManagementRequest, PluginManagementResponse, PluginManagementView,
+    },
+};
+use gateway_plugin_sdk::{
+    Stage,
+    call::management::{ManagementRequest, ManagementResponse, ManagementRoute},
+};
+
+use crate::{RpcLimits, RpcReply, RpcSession, callback::PluginCallbacks};
+
+pub(crate) use registration::prepare;
+
+pub(crate) const MAXIMUM_BODY_BYTES: usize = 1024 * 1024;
+
+pub(crate) struct ManagementEntry {
+    pub(crate) view: PluginManagementView,
+    pub(crate) models_authorized: bool,
+    routes: Vec<ManagementRoute>,
+    resources: BTreeMap<String, Arc<[u8]>>,
+    session: Arc<RpcSession>,
+    callbacks: Arc<PluginCallbacks>,
+}
+
+impl ManagementEntry {
+    pub(crate) fn resource(
+        &self,
+        path: &str,
+        public: bool,
+    ) -> Result<PluginManagementResponse, AdminError> {
+        let resource = self
+            .view
+            .resources
+            .iter()
+            .find(|resource| resource.path == path && (!public || resource.public))
+            .ok_or_else(|| AdminError::not_found("插件资源不存在"))?;
+        let body = self
+            .resources
+            .get(path)
+            .ok_or_else(|| AdminError::not_found("插件资源不存在"))?;
+        Ok(PluginManagementResponse {
+            status: 200,
+            content_type: resource.content_type.clone(),
+            body: body.clone(),
+        })
+    }
+
+    pub(crate) async fn handle(
+        &self,
+        request: PluginManagementRequest,
+        limits: RpcLimits,
+    ) -> Result<PluginManagementResponse, AdminError> {
+        let route = self
+            .routes
+            .iter()
+            .find(|route| route.method == request.method && route.path == request.path)
+            .ok_or_else(|| AdminError::not_found("插件管理路由不存在"))?;
+        let maximum_body = MAXIMUM_BODY_BYTES.min(limits.maximum_frame_bytes.saturating_sub(4096));
+        if request.body.len() > maximum_body
+            || request.query.len() > 8192
+            || request.query.bytes().any(|byte| byte.is_ascii_control())
+            || request
+                .content_type
+                .as_ref()
+                .is_some_and(|value| !route.request_content_types.contains(value))
+            || (!request.body.is_empty() && request.content_type.is_none())
+            || (matches!(route.method.as_str(), "GET" | "HEAD") && !request.body.is_empty())
+        {
+            return Err(AdminError::invalid("插件管理请求正文或内容类型无效"));
+        }
+        let params = serde_json::to_value(ManagementRequest {
+            method: request.method,
+            path: request.path,
+            query: request.query,
+            content_type: request.content_type,
+        })
+        .map_err(|_| AdminError::invalid("插件管理请求无法编码"))?;
+        let mut context = self
+            .session
+            .context(Stage::Management, limits.maximum_call_timeout);
+        context.request_id = Some(request.request_id);
+        let _scope = self
+            .callbacks
+            .prepare_management(&context, None)
+            .map_err(|_| AdminError::invalid("插件管理回调范围无效"))?;
+        let reply = self
+            .session
+            .call("management.handle", context, params, request.body)
+            .await
+            .map_err(|_| {
+                AdminError::unavailable("插件管理调用未完成；副作用可能已发生，请查询后再重试")
+            })?;
+        decode_response(reply, &route.response_content_types, limits)
+    }
+}
+
+// 受保护 API 与公开回调共用响应合同，公开入口不能因采用另一阶段而放宽输出边界。
+fn decode_response(
+    reply: RpcReply,
+    allowed_content_types: &[String],
+    limits: RpcLimits,
+) -> Result<PluginManagementResponse, AdminError> {
+    let response: ManagementResponse = serde_json::from_value(reply.result)
+        .map_err(|_| AdminError::unavailable("插件管理响应元数据无效"))?;
+    if !(200..=599).contains(&response.status)
+        || !allowed_content_types.contains(&response.content_type)
+        || reply.payload.len()
+            > MAXIMUM_BODY_BYTES.min(limits.maximum_frame_bytes.saturating_sub(4096))
+        || (matches!(response.status, 204 | 304) && !reply.payload.is_empty())
+    {
+        return Err(AdminError::unavailable(
+            "插件管理响应状态、内容类型或正文无效",
+        ));
+    }
+    Ok(PluginManagementResponse {
+        status: response.status,
+        content_type: response.content_type,
+        body: reply.payload.into(),
+    })
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/management/registration.rs b/backend/crates/gateway-plugin/runtime/src/adapter/management/registration.rs
new file mode 100644
index 000000000..a6740076b
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/management/registration.rs
@@ -0,0 +1,153 @@
+use std::{collections::BTreeMap, sync::Arc, time::Duration};
+
+use gateway_admin::model::{
+    AdminError,
+    plugins::{
+        instances::PluginInstance,
+        management::{
+            PluginManagementPage, PluginManagementResource, PluginManagementRoute,
+            PluginManagementTarget, PluginManagementView,
+        },
+    },
+};
+use gateway_plugin_sdk::{Capability, Stage, call::management::ManagementRegistration};
+
+use crate::{RpcSession, ValidatedPackage, callback::PluginCallbacks};
+
+use super::{MAXIMUM_BODY_BYTES, ManagementEntry, validation};
+
+pub(crate) async fn prepare(
+    instance: &PluginInstance,
+    package: &ValidatedPackage,
+    session: Arc<RpcSession>,
+    callbacks: Arc<PluginCallbacks>,
+) -> Result<Option<ManagementEntry>, AdminError> {
+    let manifest = package.manifest();
+    let Some(declaration) = manifest.contributes.get(&Capability::Management) else {
+        return Ok(None);
+    };
+    if declaration.stages != [Stage::Management] {
+        return Err(AdminError::invalid("管理扩展必须声明 management 阶段"));
+    }
+    let reply = session
+        .call(
+            "management.register",
+            session.context(Stage::Registration, Duration::from_secs(5)),
+            serde_json::json!({}),
+            Vec::new(),
+        )
+        .await
+        .map_err(|_| AdminError::invalid("插件管理扩展注册失败"))?;
+    if reply.result != serde_json::json!({}) || reply.payload.len() > 64 * 1024 {
+        return Err(AdminError::invalid("插件管理注册信封无效或过大"));
+    }
+    let registration: ManagementRegistration = serde_json::from_slice(&reply.payload)
+        .map_err(|_| AdminError::invalid("插件管理声明无效"))?;
+    validation::registration(&registration)?;
+    if !registration.callbacks.is_empty()
+        && !instance
+            .grants
+            .iter()
+            .any(|grant| grant.permission == "public_endpoints")
+    {
+        return Err(AdminError::invalid(
+            "公开登录回调需要显式 public_endpoints 授权",
+        ));
+    }
+    let mut resources = BTreeMap::new();
+    let mut resource_views = Vec::new();
+    let mut total = 0usize;
+    for resource in registration.resources {
+        let content_type = manifest
+            .resources
+            .get(&resource.path)
+            .filter(|value| validation::content_type(value))
+            .ok_or_else(|| AdminError::invalid("管理资源未在包清单声明有效内容类型"))?;
+        if resource.public
+            && !instance
+                .grants
+                .iter()
+                .any(|grant| grant.permission == "public_endpoints")
+        {
+            return Err(AdminError::invalid(
+                "公开资源需要显式 public_endpoints 授权",
+            ));
+        }
+        let bytes = package
+            .resource(&resource.path)
+            .ok_or_else(|| AdminError::invalid("管理资源不在已校验制品中"))?;
+        total = total.saturating_add(bytes.len());
+        if bytes.len() > MAXIMUM_BODY_BYTES || total > 8 * MAXIMUM_BODY_BYTES {
+            return Err(AdminError::invalid("插件管理资源超过单项或总大小限制"));
+        }
+        resources.insert(resource.path.clone(), Arc::from(bytes));
+        resource_views.push(PluginManagementResource {
+            path: resource.path,
+            content_type: content_type.clone(),
+            public: resource.public,
+        });
+    }
+    for page in &registration.pages {
+        if !resource_views.iter().any(|resource| {
+            resource.path == page.entry
+                && matches!(
+                    resource.content_type.as_str(),
+                    "text/html" | "text/html; charset=utf-8"
+                )
+        }) {
+            return Err(AdminError::invalid("插件页面入口必须为 HTML 资源"));
+        }
+    }
+    let routes = registration.routes;
+    let view = PluginManagementView {
+        callbacks: registration
+            .callbacks
+            .into_iter()
+            .map(
+                |callback| gateway_admin::model::plugins::management::PluginManagementCallback {
+                    path: callback.path,
+                    response_content_types: callback.response_content_types,
+                },
+            )
+            .collect(),
+        target: PluginManagementTarget {
+            instance_id: instance.id.clone(),
+            artifact_sha256: instance.artifact_sha256.clone(),
+            revision: instance.revision.get(),
+        },
+        name: instance.name.clone(),
+        configuration_schema: manifest.configuration_schema.clone(),
+        routes: routes
+            .iter()
+            .map(|route| PluginManagementRoute {
+                method: route.method.clone(),
+                path: route.path.clone(),
+                request_content_types: route.request_content_types.clone(),
+                response_content_types: route.response_content_types.clone(),
+            })
+            .collect(),
+        resources: resource_views,
+        pages: registration
+            .pages
+            .into_iter()
+            .map(|page| PluginManagementPage {
+                id: page.id,
+                title: page.title,
+                description: page.description,
+                entry: page.entry,
+                icon: page.icon,
+            })
+            .collect(),
+    };
+    Ok(Some(ManagementEntry {
+        view,
+        models_authorized: instance
+            .grants
+            .iter()
+            .any(|grant| grant.permission == "models"),
+        routes,
+        resources,
+        session,
+        callbacks,
+    }))
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/management/validation.rs b/backend/crates/gateway-plugin/runtime/src/adapter/management/validation.rs
new file mode 100644
index 000000000..05ee8e02c
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/management/validation.rs
@@ -0,0 +1,104 @@
+use std::collections::BTreeSet;
+
+use gateway_admin::model::AdminError;
+use gateway_plugin_sdk::call::management::ManagementRegistration;
+
+pub(super) fn registration(value: &ManagementRegistration) -> Result<(), AdminError> {
+    if value.routes.len() > 64
+        || value.resources.len() > 128
+        || value.pages.len() > 16
+        || value.callbacks.len() > 16
+        || (value.routes.is_empty() && value.resources.is_empty() && value.callbacks.is_empty())
+    {
+        return Err(AdminError::invalid("插件管理声明为空或超过条数限制"));
+    }
+    let mut routes = BTreeSet::new();
+    for route in &value.routes {
+        if !matches!(
+            route.method.as_str(),
+            "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE"
+        ) || !path(&route.path)
+            || !routes.insert((&route.method, &route.path))
+            || route.request_content_types.len() > 16
+            || route.response_content_types.is_empty()
+            || route.response_content_types.len() > 16
+            || !content_types(&route.request_content_types)
+            || !content_types(&route.response_content_types)
+        {
+            return Err(AdminError::invalid("插件管理路由声明无效或重复"));
+        }
+    }
+    let mut resources = BTreeSet::new();
+    let mut callbacks = BTreeSet::new();
+    for callback in &value.callbacks {
+        if !path(&callback.path)
+            || !callbacks.insert(&callback.path)
+            || callback.response_content_types.is_empty()
+            || callback.response_content_types.len() > 16
+            || !content_types(&callback.response_content_types)
+        {
+            return Err(AdminError::invalid("插件登录回调路径或内容类型无效"));
+        }
+    }
+    for resource in &value.resources {
+        if !path(&resource.path) || !resources.insert(&resource.path) {
+            return Err(AdminError::invalid("插件资源路径无效或重复"));
+        }
+    }
+    let mut pages = BTreeSet::new();
+    for page in &value.pages {
+        if !path(&page.id)
+            || page.id.contains('/')
+            || page.id.len() > 64
+            || !pages.insert(&page.id)
+            || page.title.is_empty()
+            || page.title.len() > 128
+            || page.title.chars().any(char::is_control)
+            || page.description.as_ref().is_some_and(|description| {
+                description.trim().is_empty()
+                    || description.len() > 512
+                    || description.chars().any(char::is_control)
+            })
+            || !resources.contains(&page.entry)
+            || page
+                .icon
+                .as_ref()
+                .is_some_and(|icon| !resources.contains(icon))
+        {
+            return Err(AdminError::invalid(
+                "插件页面标识、标题、说明或资源引用无效",
+            ));
+        }
+    }
+    Ok(())
+}
+
+fn content_types(values: &[String]) -> bool {
+    values.iter().collect::<BTreeSet<_>>().len() == values.len()
+        && values.iter().all(|value| content_type(value))
+}
+
+pub(super) fn content_type(value: &str) -> bool {
+    let mime = value.strip_suffix("; charset=utf-8").unwrap_or(value);
+    value.len() <= 128
+        && mime.split_once('/').is_some_and(|(kind, subtype)| {
+            [kind, subtype].iter().all(|part| {
+                !part.is_empty()
+                    && part
+                        .bytes()
+                        .all(|byte| byte.is_ascii_alphanumeric() || b"!#$&^_.+-".contains(&byte))
+            })
+        })
+}
+
+fn path(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 512
+        && value.split('/').all(|part| {
+            !part.is_empty()
+                && !matches!(part, "." | "..")
+                && part
+                    .bytes()
+                    .all(|byte| byte.is_ascii_alphanumeric() || b"._-".contains(&byte))
+        })
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/mod.rs b/backend/crates/gateway-plugin/runtime/src/adapter/mod.rs
new file mode 100644
index 000000000..54ea71f94
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/mod.rs
@@ -0,0 +1,7 @@
+pub(super) mod command_line;
+pub(super) mod frontend_authentication;
+pub(super) mod management;
+pub(super) mod observer;
+pub(super) mod policy;
+pub(super) mod provider;
+pub(super) mod scope;
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/observer.rs b/backend/crates/gateway-plugin/runtime/src/adapter/observer.rs
new file mode 100644
index 000000000..24ec2b64e
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/observer.rs
@@ -0,0 +1,657 @@
+use std::{
+    collections::BTreeMap,
+    sync::{Arc, Mutex},
+    time::{Duration, SystemTime, UNIX_EPOCH},
+};
+
+use gateway_admin::model::{
+    AdminError,
+    plugins::instances::{PluginCapabilityBinding, PluginFailurePolicy},
+};
+use gateway_core::{
+    engine::observation::{
+        RequestObservation, RequestObservationOutcome, RequestObserverPlan,
+        WebSocketResponseObservation,
+    },
+    metering::{CostEstimateStatus, CostSource},
+    runtime::extensions::ExtensionSetReference,
+    upstream::UpstreamSendState,
+};
+use gateway_plugin_sdk::{
+    Capability, Manifest, Permission, SendState, Stage,
+    call::{
+        observation::ObserveWebSocketResponse,
+        policy::{
+            ObserveRequest, RequestCost, RequestCostSource, RequestCostStatus, RequestFailure,
+            RequestMoney, RequestOutcome, RequestTerminal, RequestTimings, RequestUsage,
+        },
+    },
+};
+use tokio::sync::{OwnedSemaphorePermit, Semaphore, mpsc};
+
+use crate::{RpcSession, adapter::scope::BindingScope};
+
+const OBSERVATION_TIMEOUT: Duration = Duration::from_secs(2);
+const OBSERVATION_ENVELOPE_RESERVE: usize = 16 * 1024;
+const MAX_WEBSOCKET_EVENT_TYPE_BYTES: usize = 256;
+
+pub(crate) struct ObserverEntry {
+    order: i32,
+    plugin_id: String,
+    instance_id: String,
+    session: Arc<RpcSession>,
+    callbacks: Arc<crate::callback::PluginCallbacks>,
+    lifecycle: Option<BindingScope>,
+    usage: Option<BindingScope>,
+    websocket: Option<BindingScope>,
+    requests_authorized: bool,
+}
+
+impl ObserverEntry {
+    fn subscriptions(&self, observation: &RequestObservation) -> (bool, bool) {
+        (
+            self.lifecycle
+                .as_ref()
+                .is_some_and(|scope| scope.matches_observation(observation)),
+            self.usage
+                .as_ref()
+                .is_some_and(|scope| scope.matches_observation(observation)),
+        )
+    }
+}
+
+struct CompiledBindings {
+    order: i32,
+    lifecycle: Option<BindingScope>,
+    usage: Option<BindingScope>,
+    websocket: Option<BindingScope>,
+}
+
+fn compile_bindings(
+    manifest: &Manifest,
+    bindings: &[PluginCapabilityBinding],
+) -> Result<Option<CompiledBindings>, AdminError> {
+    let mut lifecycle = None;
+    let mut usage = None;
+    let mut websocket = None;
+    let mut order = None;
+    for binding in bindings {
+        let capability = crate::contribution::resolve(manifest, binding)?.capability;
+        if !matches!(
+            capability,
+            Capability::RequestLifecycle | Capability::Usage | Capability::WebSocketObserver
+        ) {
+            continue;
+        }
+        let stage: Stage = serde_json::from_value(serde_json::Value::String(binding.stage.clone()))
+            .map_err(|_| AdminError::invalid("插件观察阶段无效"))?;
+        if stage != Stage::Observation || binding.failure_policy != PluginFailurePolicy::Observe {
+            return Err(AdminError::invalid(
+                "请求生命周期、用量与 WebSocket 观察绑定必须使用 observation/observe",
+            ));
+        }
+        if order.is_some_and(|existing| existing != binding.order) {
+            return Err(AdminError::invalid(
+                "同一实例的请求生命周期、用量与 WebSocket 观察绑定必须使用相同顺序",
+            ));
+        }
+        order = Some(binding.order);
+        let scope = BindingScope::compile(binding)?;
+        match capability {
+            Capability::RequestLifecycle => lifecycle = Some(scope),
+            Capability::Usage => usage = Some(scope),
+            Capability::WebSocketObserver => websocket = Some(scope),
+            _ => unreachable!("capability was filtered above"),
+        }
+    }
+    Ok(order.map(|order| CompiledBindings {
+        order,
+        lifecycle,
+        usage,
+        websocket,
+    }))
+}
+
+pub(crate) fn validate_bindings(
+    manifest: &Manifest,
+    bindings: &[PluginCapabilityBinding],
+) -> Result<(), AdminError> {
+    compile_bindings(manifest, bindings).map(drop)
+}
+
+pub(crate) fn compile_entry(
+    manifest: &Manifest,
+    plugin_id: &str,
+    instance_id: &str,
+    bindings: &[PluginCapabilityBinding],
+    permissions: &[Permission],
+    session: Arc<RpcSession>,
+    callbacks: Arc<crate::callback::PluginCallbacks>,
+) -> Result<Option<ObserverEntry>, AdminError> {
+    Ok(
+        compile_bindings(manifest, bindings)?.map(|compiled| ObserverEntry {
+            order: compiled.order,
+            plugin_id: plugin_id.to_owned(),
+            instance_id: instance_id.to_owned(),
+            session,
+            callbacks,
+            lifecycle: compiled.lifecycle,
+            usage: compiled.usage,
+            websocket: compiled.websocket,
+            requests_authorized: permissions.contains(&Permission::Requests),
+        }),
+    )
+}
+
+pub(crate) struct PluginObserverPlan {
+    entries: Arc<[ObserverEntry]>,
+    slots: Arc<Semaphore>,
+    websocket_worker_slots: Arc<Semaphore>,
+    websocket_payload_slots: Arc<Semaphore>,
+    websocket_queues: Arc<Mutex<BTreeMap<String, mpsc::Sender<QueuedWebSocketObservation>>>>,
+    websocket_queue_capacity: usize,
+    maximum_websocket_payload_bytes: usize,
+    timeout: Duration,
+}
+
+struct QueuedWebSocketObservation {
+    observation: WebSocketResponseObservation,
+    payload: Arc<[u8]>,
+    entry_indexes: Vec<usize>,
+    _payload_slot: OwnedSemaphorePermit,
+}
+
+impl PluginObserverPlan {
+    pub(crate) fn compile(
+        mut entries: Vec<ObserverEntry>,
+        maximum_calls: usize,
+        maximum_call_timeout: Duration,
+        maximum_frame_bytes: usize,
+    ) -> Option<Arc<Self>> {
+        if entries.is_empty() {
+            return None;
+        }
+        entries.sort_by(|left, right| {
+            (left.order, &left.plugin_id, &left.instance_id).cmp(&(
+                right.order,
+                &right.plugin_id,
+                &right.instance_id,
+            ))
+        });
+        let maximum_websocket_payload_bytes = maximum_frame_bytes
+            .saturating_sub(OBSERVATION_ENVELOPE_RESERVE.min(maximum_frame_bytes));
+        Some(Arc::new(Self {
+            entries: entries.into(),
+            slots: Arc::new(Semaphore::new(maximum_calls)),
+            websocket_worker_slots: Arc::new(Semaphore::new(maximum_calls)),
+            websocket_payload_slots: Arc::new(Semaphore::new(
+                maximum_websocket_payload_bytes.max(1),
+            )),
+            websocket_queues: Arc::new(Mutex::new(BTreeMap::new())),
+            websocket_queue_capacity: maximum_calls.clamp(1, 256),
+            maximum_websocket_payload_bytes,
+            timeout: maximum_call_timeout.min(OBSERVATION_TIMEOUT),
+        }))
+    }
+
+    fn close_websocket_queue(&self, request_id: &str) {
+        self.websocket_queues
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .remove(request_id);
+    }
+}
+
+impl RequestObserverPlan for PluginObserverPlan {
+    fn dispatch_websocket_response(
+        &self,
+        generation: ExtensionSetReference,
+        observation: WebSocketResponseObservation,
+    ) {
+        let entry_indexes = self
+            .entries
+            .iter()
+            .enumerate()
+            .filter_map(|(index, entry)| {
+                (!observation.suppresses_plugin(&entry.instance_id))
+                    .then_some(entry)
+                    .and_then(|entry| entry.websocket.as_ref())
+                    .is_some_and(|scope| scope.matches_websocket_observation(&observation))
+                    .then_some(index)
+            })
+            .collect::<Vec<_>>();
+        if entry_indexes.is_empty() {
+            return;
+        }
+        let include_payload = entry_indexes
+            .iter()
+            .any(|index| self.entries[*index].requests_authorized);
+        let payload = if include_payload {
+            match websocket_payload(&observation) {
+                Ok(payload) => payload,
+                Err(()) => {
+                    tracing::warn!(
+                        request_id = observation.request_id().as_str(),
+                        sequence = observation.sequence(),
+                        "插件 WebSocket 响应观察编码失败，已丢弃"
+                    );
+                    return;
+                }
+            }
+        } else {
+            Vec::new()
+        };
+        if payload.len() > self.maximum_websocket_payload_bytes {
+            tracing::warn!(
+                request_id = observation.request_id().as_str(),
+                sequence = observation.sequence(),
+                payload_bytes = payload.len(),
+                "插件 WebSocket 响应观察载荷超过上限，已丢弃"
+            );
+            return;
+        }
+        let Ok(payload_permits) = u32::try_from(payload.len().max(1)) else {
+            return;
+        };
+        let Ok(payload_slot) = self
+            .websocket_payload_slots
+            .clone()
+            .try_acquire_many_owned(payload_permits)
+        else {
+            tracing::warn!(
+                request_id = observation.request_id().as_str(),
+                sequence = observation.sequence(),
+                "插件 WebSocket 响应观察载荷队列已满，已丢弃"
+            );
+            return;
+        };
+        let Ok(handle) = tokio::runtime::Handle::try_current() else {
+            tracing::warn!(
+                request_id = observation.request_id().as_str(),
+                "插件 WebSocket 响应观察缺少异步运行时，已丢弃"
+            );
+            return;
+        };
+        let request_id = observation.request_id().as_str().to_owned();
+        let Some(sender) = self.websocket_sender(&handle, &request_id, generation) else {
+            tracing::warn!(request_id, "插件 WebSocket 响应观察并发已满，已丢弃");
+            return;
+        };
+        let sequence = observation.sequence();
+        if sender
+            .try_send(QueuedWebSocketObservation {
+                observation,
+                payload: payload.into(),
+                entry_indexes,
+                _payload_slot: payload_slot,
+            })
+            .is_err()
+        {
+            tracing::warn!(
+                request_id,
+                sequence,
+                "插件 WebSocket 响应观察事件队列已满，已丢弃"
+            );
+        }
+    }
+
+    fn dispatch(&self, generation: ExtensionSetReference, observation: RequestObservation) {
+        self.close_websocket_queue(observation.request_id().as_str());
+        if !self.entries.iter().any(|entry| {
+            !observation.suppresses_plugin(&entry.instance_id)
+                && entry.subscriptions(&observation) != (false, false)
+        }) {
+            return;
+        }
+        let Ok(handle) = tokio::runtime::Handle::try_current() else {
+            tracing::warn!(
+                request_id = observation.request_id().as_str(),
+                "插件终态观察缺少异步运行时，已丢弃"
+            );
+            return;
+        };
+        let Ok(slot) = self.slots.clone().try_acquire_owned() else {
+            tracing::warn!(
+                request_id = observation.request_id().as_str(),
+                "插件终态观察并发已满，已丢弃"
+            );
+            return;
+        };
+        let entries = Arc::clone(&self.entries);
+        let timeout = self.timeout;
+        handle.spawn(async move {
+            let _generation = generation;
+            let _slot = slot;
+            for entry in entries.iter() {
+                if observation.suppresses_plugin(&entry.instance_id) {
+                    continue;
+                }
+                let (lifecycle, usage) = entry.subscriptions(&observation);
+                if !lifecycle && !usage {
+                    continue;
+                }
+                let request = wire_observation(&observation, lifecycle, usage);
+                let Ok(payload) = serde_json::to_vec(&request) else {
+                    tracing::warn!(
+                        plugin_id = entry.plugin_id,
+                        instance_id = entry.instance_id,
+                        request_id = observation.request_id().as_str(),
+                        "插件终态观察编码失败"
+                    );
+                    continue;
+                };
+                let mut context = entry.session.context(Stage::Observation, timeout);
+                context.request_id = Some(observation.request_id().as_str().to_owned());
+                let Ok(_scope) = entry
+                    .callbacks
+                    .prepare_observation(&context, observation.extension_scope().clone())
+                else {
+                    continue;
+                };
+                match entry
+                    .session
+                    .call(
+                        "policy.observe_request",
+                        context,
+                        serde_json::json!({}),
+                        payload,
+                    )
+                    .await
+                {
+                    Ok(reply)
+                        if reply.payload.is_empty()
+                            && (reply.result.is_null()
+                                || reply
+                                    .result
+                                    .as_object()
+                                    .is_some_and(serde_json::Map::is_empty)) => {}
+                    Ok(_) => tracing::warn!(
+                        plugin_id = entry.plugin_id,
+                        instance_id = entry.instance_id,
+                        request_id = observation.request_id().as_str(),
+                        "插件终态观察返回了无效结果"
+                    ),
+                    Err(error) => tracing::warn!(
+                        plugin_id = entry.plugin_id,
+                        instance_id = entry.instance_id,
+                        request_id = observation.request_id().as_str(),
+                        %error,
+                        "插件终态观察失败"
+                    ),
+                }
+            }
+        });
+    }
+}
+
+impl PluginObserverPlan {
+    fn websocket_sender(
+        &self,
+        handle: &tokio::runtime::Handle,
+        request_id: &str,
+        generation: ExtensionSetReference,
+    ) -> Option<mpsc::Sender<QueuedWebSocketObservation>> {
+        let mut queues = self
+            .websocket_queues
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if let Some(sender) = queues.get(request_id) {
+            return Some(sender.clone());
+        }
+        let worker_slot = self
+            .websocket_worker_slots
+            .clone()
+            .try_acquire_owned()
+            .ok()?;
+        let (sender, receiver) = mpsc::channel(self.websocket_queue_capacity);
+        queues.insert(request_id.to_owned(), sender.clone());
+        let entries = Arc::clone(&self.entries);
+        let timeout = self.timeout;
+        handle.spawn(dispatch_websocket_queue(
+            entries,
+            timeout,
+            generation,
+            worker_slot,
+            receiver,
+        ));
+        Some(sender)
+    }
+}
+
+async fn dispatch_websocket_queue(
+    entries: Arc<[ObserverEntry]>,
+    timeout: Duration,
+    generation: ExtensionSetReference,
+    worker_slot: OwnedSemaphorePermit,
+    mut receiver: mpsc::Receiver<QueuedWebSocketObservation>,
+) {
+    let _generation = generation;
+    let _worker_slot = worker_slot;
+    while let Some(queued) = receiver.recv().await {
+        for index in queued.entry_indexes.iter().copied() {
+            let entry = &entries[index];
+            let include_payload = entry.requests_authorized && !queued.payload.is_empty();
+            let request = ObserveWebSocketResponse {
+                event_id: queued.observation.event_id().to_owned(),
+                request_id: queued.observation.request_id().as_str().to_owned(),
+                config_revision: queued.observation.config_revision().get(),
+                operation: queued.observation.operation().as_str().to_owned(),
+                protocol: queued.observation.wire().protocol().to_owned(),
+                provider: queued.observation.provider().as_str().to_owned(),
+                attempt_index: queued.observation.attempt_index().get(),
+                sequence: queued.observation.sequence(),
+                payload_included: include_payload,
+                requested_model: queued
+                    .observation
+                    .requested_model()
+                    .map(|model| model.as_str().to_owned()),
+                account_id: Some(queued.observation.account_id().as_str().to_owned()),
+                event_type: include_payload
+                    .then(|| queued.observation.wire().event_type())
+                    .flatten()
+                    .filter(|event_type| safe_websocket_event_type(event_type))
+                    .map(str::to_owned),
+            };
+            let mut context = entry.session.context(Stage::Observation, timeout);
+            context.request_id = Some(queued.observation.request_id().as_str().to_owned());
+            let Ok(_scope) = entry
+                .callbacks
+                .prepare_observation(&context, queued.observation.extension_scope().clone())
+            else {
+                continue;
+            };
+            let result = entry
+                .session
+                .call(
+                    "websocket.response_event",
+                    context,
+                    match serde_json::to_value(request) {
+                        Ok(request) => request,
+                        Err(_) => {
+                            tracing::warn!(
+                                plugin_id = entry.plugin_id,
+                                instance_id = entry.instance_id,
+                                request_id = queued.observation.request_id().as_str(),
+                                "插件 WebSocket 响应观察元数据编码失败"
+                            );
+                            continue;
+                        }
+                    },
+                    if include_payload {
+                        queued.payload.to_vec()
+                    } else {
+                        Vec::new()
+                    },
+                )
+                .await;
+            match result {
+                Ok(reply)
+                    if reply.payload.is_empty()
+                        && (reply.result.is_null()
+                            || reply
+                                .result
+                                .as_object()
+                                .is_some_and(serde_json::Map::is_empty)) => {}
+                Ok(_) => tracing::warn!(
+                    plugin_id = entry.plugin_id,
+                    instance_id = entry.instance_id,
+                    request_id = queued.observation.request_id().as_str(),
+                    "插件 WebSocket 响应观察返回了无效结果"
+                ),
+                Err(error) => tracing::warn!(
+                    plugin_id = entry.plugin_id,
+                    instance_id = entry.instance_id,
+                    request_id = queued.observation.request_id().as_str(),
+                    %error,
+                    "插件 WebSocket 响应观察失败"
+                ),
+            }
+        }
+    }
+}
+
+fn websocket_payload(observation: &WebSocketResponseObservation) -> Result<Vec<u8>, ()> {
+    if let Some(raw) = observation.wire().raw_json_body() {
+        return Ok(raw.to_vec());
+    }
+    if observation.wire().has_json_data() {
+        return serde_json::to_vec(observation.wire().data()).map_err(|_| ());
+    }
+    Ok(Vec::new())
+}
+
+fn safe_websocket_event_type(event_type: &str) -> bool {
+    !event_type.is_empty()
+        && event_type.len() <= MAX_WEBSOCKET_EVENT_TYPE_BYTES
+        && !event_type.chars().any(char::is_control)
+}
+
+fn wire_observation(
+    observation: &RequestObservation,
+    include_lifecycle: bool,
+    include_usage: bool,
+) -> ObserveRequest {
+    ObserveRequest {
+        event_id: observation.event_id().to_owned(),
+        request_id: observation.request_id().as_str().to_owned(),
+        config_revision: observation.config_revision().get(),
+        operation: observation.operation().as_str().to_owned(),
+        client_key_id: observation
+            .client_key_id()
+            .map(|key| key.as_str().to_owned()),
+        account_id: observation
+            .account_id()
+            .map(|account| account.as_str().to_owned()),
+        upstream_model: observation
+            .upstream_model()
+            .map(|model| model.as_str().to_owned()),
+        response_model: observation.response_model().map(str::to_owned),
+        service_tier: observation.service_tier().map(str::to_owned),
+        requested_model: observation
+            .requested_model()
+            .map(|model| model.as_str().to_owned()),
+        provider: observation
+            .provider()
+            .map(|provider| provider.as_str().to_owned()),
+        completed_at_ms: millis_since_epoch(observation.completed_at()),
+        terminal: include_lifecycle.then(|| RequestTerminal {
+            outcome: wire_outcome(observation.outcome()),
+            send_state: wire_send_state(observation.send_state()),
+            attempt_count: observation.attempt_count(),
+            client_status_code: observation.client_status_code(),
+            error_code: observation
+                .error_kind()
+                .map(|error| error.as_str().to_owned()),
+        }),
+        usage: include_usage.then(|| {
+            let usage = observation.usage();
+            RequestUsage {
+                input_tokens: usage.input_tokens,
+                output_tokens: usage.output_tokens,
+                cached_tokens: usage.cached_tokens,
+                cache_write_tokens: usage.cache_write_tokens,
+                reasoning_tokens: usage.reasoning_tokens,
+                image_input_tokens: usage.image_input_tokens,
+                image_output_tokens: usage.image_output_tokens,
+                total_tokens: usage.total_tokens,
+                cost: Some(wire_cost(observation)),
+                timings: Some(wire_timings(observation)),
+                failure: wire_failure(observation),
+            }
+        }),
+    }
+}
+
+fn wire_outcome(outcome: RequestObservationOutcome) -> RequestOutcome {
+    match outcome {
+        RequestObservationOutcome::Succeeded => RequestOutcome::Succeeded,
+        RequestObservationOutcome::Failed => RequestOutcome::Failed,
+        RequestObservationOutcome::Rejected => RequestOutcome::Rejected,
+        RequestObservationOutcome::Cancelled => RequestOutcome::Cancelled,
+        RequestObservationOutcome::Incomplete => RequestOutcome::Incomplete,
+    }
+}
+
+fn wire_send_state(send_state: UpstreamSendState) -> SendState {
+    match send_state {
+        UpstreamSendState::NotSent => SendState::NotSent,
+        UpstreamSendState::Sent => SendState::Sent,
+        UpstreamSendState::Ambiguous => SendState::Ambiguous,
+    }
+}
+
+fn wire_cost(observation: &RequestObservation) -> RequestCost {
+    let cost = observation.cost();
+    RequestCost {
+        status: match cost.status() {
+            CostEstimateStatus::Known => RequestCostStatus::Known,
+            CostEstimateStatus::Unknown => RequestCostStatus::Unknown,
+        },
+        source: match cost.source() {
+            CostSource::ProviderReported => RequestCostSource::ProviderReported,
+            CostSource::Calculated => RequestCostSource::Calculated,
+            CostSource::Unavailable => RequestCostSource::Unavailable,
+        },
+        total: cost.total().map(|total| RequestMoney {
+            amount: total.amount().canonical(),
+            currency: total.currency().as_str().to_owned(),
+        }),
+    }
+}
+
+fn wire_timings(observation: &RequestObservation) -> RequestTimings {
+    let timings = observation.timings();
+    RequestTimings {
+        transport_decision_wait_ms: timings.transport_decision_wait_ms,
+        connect_ms: timings.connect_ms,
+        headers_ms: timings.headers_ms,
+        first_event_ms: timings.first_event_ms,
+        first_reasoning_ms: timings.first_reasoning_ms,
+        first_text_ms: timings.first_text_ms,
+        first_token_ms: timings.first_token_ms,
+        provider_processing_ms: timings.provider_processing_ms,
+        latency_ms: timings.latency_ms,
+    }
+}
+
+fn wire_failure(observation: &RequestObservation) -> Option<RequestFailure> {
+    (observation.outcome() != RequestObservationOutcome::Succeeded).then(|| RequestFailure {
+        outcome: wire_outcome(observation.outcome()),
+        send_state: wire_send_state(observation.send_state()),
+        attempt_count: observation.attempt_count(),
+        client_status_code: observation.client_status_code(),
+        upstream_status_code: observation.upstream_status_code(),
+        error_code: observation
+            .error_kind()
+            .map(|error| error.as_str().to_owned()),
+        retry_after_ms: observation.retry_after_ms(),
+    })
+}
+
+fn millis_since_epoch(time: SystemTime) -> u64 {
+    time.duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis()
+        .try_into()
+        .unwrap_or(u64::MAX)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/policy/middleware.rs b/backend/crates/gateway-plugin/runtime/src/adapter/policy/middleware.rs
new file mode 100644
index 000000000..5759efc6c
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/policy/middleware.rs
@@ -0,0 +1,623 @@
+use std::{
+    sync::{Arc, Mutex},
+    time::{Duration, SystemTime},
+};
+
+use bytes::Bytes;
+use futures::future::BoxFuture;
+use gateway_admin::model::plugins::instances::PluginFailurePolicy;
+use gateway_core::engine::middleware::{
+    MiddlewareBody, MiddlewareContext, MiddlewareError, MiddlewareFrame, MiddlewareFraming,
+    MiddlewareMount, MiddlewareNext, MiddlewarePlan, MiddlewareRequest, MiddlewareResponse,
+};
+use gateway_plugin_sdk::{
+    ErrorCode, SendState, Stage,
+    call::middleware::{
+        HANDLE_METHOD, MiddlewareBodyDisposition, MiddlewareBodyFrame,
+        MiddlewareMount as WireMiddlewareMount, MiddlewareRequestHead, MiddlewareResponseHead,
+        MiddlewareTransport as WireMiddlewareTransport,
+    },
+};
+use gateway_protocol::openai::sse::parse_sse_events;
+
+use crate::{
+    RpcError, RpcStream,
+    callback::{MiddlewareBodyAuthority, MiddlewareCompletionBody, MiddlewareInvocation},
+};
+
+use super::{MiddlewareEntry, PluginRequestPolicyPlan};
+
+const MAXIMUM_MAPPED_FRAMES_PER_SOURCE: usize = 64;
+const MAXIMUM_MAPPED_BYTES_PER_SOURCE: usize = 8 * 1024 * 1024;
+
+impl MiddlewarePlan for PluginRequestPolicyPlan {
+    fn handle(
+        &self,
+        context: MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        let applicable = self
+            .middleware
+            .iter()
+            .enumerate()
+            .filter_map(|(index, entry)| {
+                (entry.mount == context.mount()
+                    && !context.extension_scope().contains(&entry.instance_id)
+                    && entry.scope.matches_processing(
+                        context.client_key_id(),
+                        context.account_group_ids(),
+                        context.provider(),
+                        context.model(),
+                    ))
+                .then_some(index)
+            })
+            .collect::<Vec<_>>();
+        Box::new(MiddlewareChainNext {
+            entries: Arc::clone(&self.middleware),
+            applicable: applicable.into(),
+            index: 0,
+            context,
+            terminal: Some(next),
+            timeout: self.middleware_timeout,
+            maximum_payload_bytes: self.maximum_payload_bytes,
+        })
+        .run(request)
+    }
+}
+
+struct MiddlewareChainNext {
+    entries: Arc<[MiddlewareEntry]>,
+    applicable: Arc<[usize]>,
+    index: usize,
+    context: MiddlewareContext,
+    terminal: Option<Box<dyn MiddlewareNext>>,
+    timeout: Duration,
+    maximum_payload_bytes: usize,
+}
+
+impl MiddlewareNext for MiddlewareChainNext {
+    fn run(
+        mut self: Box<Self>,
+        request: MiddlewareRequest,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        Box::pin(async move {
+            let Some(entry_index) = self.applicable.get(self.index).copied() else {
+                return self
+                    .terminal
+                    .take()
+                    .ok_or(MiddlewareError::InvalidState)?
+                    .run(request)
+                    .await;
+            };
+            let next = Box::new(Self {
+                entries: Arc::clone(&self.entries),
+                applicable: Arc::clone(&self.applicable),
+                index: self.index + 1,
+                context: self.context.clone(),
+                terminal: self.terminal.take(),
+                timeout: self.timeout,
+                maximum_payload_bytes: self.maximum_payload_bytes,
+            });
+            invoke_middleware(
+                &self.entries[entry_index],
+                self.context,
+                request,
+                next,
+                self.timeout,
+                self.maximum_payload_bytes,
+            )
+            .await
+        })
+    }
+}
+
+async fn invoke_middleware(
+    entry: &MiddlewareEntry,
+    context: MiddlewareContext,
+    request: MiddlewareRequest,
+    next: Box<dyn MiddlewareNext>,
+    maximum_timeout: Duration,
+    maximum_payload_bytes: usize,
+) -> Result<MiddlewareResponse, MiddlewareError> {
+    let Some(invocation_ports) = &entry.invocation else {
+        return if entry.failure_policy
+            == gateway_admin::model::plugins::instances::PluginFailurePolicy::Delegate
+        {
+            next.run(request).await
+        } else {
+            Err(MiddlewareError::Fault)
+        };
+    };
+    let remaining = context
+        .deadline()
+        .duration_since(SystemTime::now())
+        .map_err(|_| MiddlewareError::Fault)?
+        .min(maximum_timeout);
+    if remaining.is_zero() || context.cancellation().is_cancelled() {
+        return Err(MiddlewareError::Fault);
+    }
+    let invocation = MiddlewareInvocation::new(&context, request, next, entry.requests_authorized);
+    let (protocol, headers, body_visible, payload) = match invocation.request_projection() {
+        Ok(projection) => projection,
+        Err(_) => return recover_invalid(entry, &invocation).await,
+    };
+    if payload.len() > maximum_payload_bytes {
+        return recover_invalid(entry, &invocation).await;
+    }
+    let mut call_context = invocation_ports.session.context(
+        match entry.mount {
+            MiddlewareMount::Request => Stage::Request,
+            MiddlewareMount::Attempt => Stage::Attempt,
+        },
+        remaining,
+    );
+    call_context.request_id = Some(context.request_id().as_str().to_owned());
+    call_context.attempt_id = context
+        .attempt_index()
+        .map(|index| format!("{}:{index}", context.request_id().as_str()));
+    call_context.account_id = context
+        .account_id()
+        .map(|account| account.as_str().to_owned());
+    let _network_scope = context
+        .execution_effects()
+        .map(|effects| {
+            invocation_ports
+                .callbacks
+                .prepare_data_plane(&call_context, effects)
+        })
+        .transpose()
+        .map_err(|_| MiddlewareError::Fault)?;
+    let _binding = invocation_ports.callbacks.bind_middleware(
+        call_context.resource_scope_id.clone(),
+        Arc::clone(&invocation),
+    )?;
+    let head = MiddlewareRequestHead {
+        request_id: context.request_id().as_str().to_owned(),
+        mount: match context.mount() {
+            MiddlewareMount::Request => WireMiddlewareMount::Request,
+            MiddlewareMount::Attempt => WireMiddlewareMount::Attempt,
+        },
+        attempt_index: context.attempt_index().map(std::num::NonZeroU32::get),
+        operation: context.operation().map_or_else(
+            || "query".to_owned(),
+            |operation| operation.as_str().to_owned(),
+        ),
+        protocol,
+        endpoint: context.endpoint().to_owned(),
+        transport: wire_transport(context.transport()),
+        provider: context
+            .provider()
+            .map(|provider| provider.as_str().to_owned()),
+        model: context.model().map(str::to_owned),
+        account_id: context
+            .account_id()
+            .map(|account| account.as_str().to_owned()),
+        headers,
+        body_visible,
+    };
+    let stream = tokio::select! {
+        biased;
+        () = context.cancellation().cancelled() => return Err(MiddlewareError::Fault),
+        result = invocation_ports.session.call_stream(
+            HANDLE_METHOD,
+            call_context,
+            serde_json::to_value(head).map_err(|_| MiddlewareError::InvalidState)?,
+            payload,
+        ) => match result {
+            Ok(stream) => stream,
+            Err(error) => return recover_rpc(entry, &invocation, error).await,
+        }
+    };
+    if !stream.initial.payload.is_empty() {
+        drop(stream);
+        return recover_invalid(entry, &invocation).await;
+    }
+    let response: MiddlewareResponseHead =
+        match serde_json::from_value(stream.initial.result.clone()) {
+            Ok(response) => response,
+            Err(_) => {
+                drop(stream);
+                return recover_invalid(entry, &invocation).await;
+            }
+        };
+    let completion = match invocation.resolve_response(response).await {
+        Ok(completion) => completion,
+        Err(error) => {
+            drop(stream);
+            return Err(error);
+        }
+    };
+    let body: Box<dyn MiddlewareBody> = match completion.body {
+        MiddlewareCompletionBody::PassThrough(body) => {
+            drain_empty_stream(stream, &invocation).await?;
+            body
+        }
+        MiddlewareCompletionBody::Empty => {
+            drain_empty_stream(stream, &invocation).await?;
+            Box::new(EmptyMiddlewareBody)
+        }
+        MiddlewareCompletionBody::Stream {
+            framing,
+            downstream,
+        } => Box::new(PluginMiddlewareBody {
+            stream: Some(stream),
+            framing,
+            terminal_seen: false,
+            next_source_id: 0,
+            active_source: None,
+            active_output_count: 0,
+            active_output_bytes: 0,
+            pending_transformed: false,
+            downstream_error: invocation.downstream_error_slot(),
+            downstream,
+            _invocation: Arc::clone(&invocation),
+        }),
+    };
+    let response = MiddlewareResponse::new(
+        completion.protocol,
+        completion.status,
+        completion.headers,
+        body,
+    );
+    Ok(match completion.envelope {
+        Some(envelope) => response.with_envelope(envelope),
+        None => response,
+    })
+}
+
+async fn recover_rpc(
+    entry: &MiddlewareEntry,
+    invocation: &MiddlewareInvocation,
+    error: RpcError,
+) -> Result<MiddlewareResponse, MiddlewareError> {
+    if let Some(error) = invocation.take_downstream_error() {
+        return Err(error);
+    }
+    let rejected = matches!(
+        &error,
+        RpcError::Remote(fault) if fault.code == ErrorCode::Rejected
+    );
+    let delegate_safe = !rejected
+        && !matches!(
+            &error,
+            RpcError::Remote(fault) if fault.send_state != SendState::NotSent
+        );
+    if delegate_safe
+        && entry.failure_policy == PluginFailurePolicy::Delegate
+        && let Some((next, request)) = invocation.take_delegate()
+    {
+        tracing::warn!(
+            plugin_id = entry.plugin_id,
+            instance_id = entry.instance_id,
+            "插件中间件在调用 next 前失败，按绑定委托下游"
+        );
+        return next.run(request).await;
+    }
+    if rejected {
+        Err(MiddlewareError::Rejected)
+    } else {
+        Err(MiddlewareError::Fault)
+    }
+}
+
+async fn recover_invalid(
+    entry: &MiddlewareEntry,
+    invocation: &MiddlewareInvocation,
+) -> Result<MiddlewareResponse, MiddlewareError> {
+    if entry.failure_policy == PluginFailurePolicy::Delegate
+        && let Some((next, request)) = invocation.take_delegate()
+    {
+        tracing::warn!(
+            plugin_id = entry.plugin_id,
+            instance_id = entry.instance_id,
+            "插件中间件在调用 next 前返回无效结果，按绑定委托下游"
+        );
+        next.run(request).await
+    } else {
+        Err(MiddlewareError::InvalidState)
+    }
+}
+
+async fn drain_empty_stream(
+    mut stream: RpcStream,
+    invocation: &MiddlewareInvocation,
+) -> Result<(), MiddlewareError> {
+    match stream.next().await {
+        Ok(None) => invocation.take_downstream_error().map_or(Ok(()), Err),
+        Ok(Some(_)) => Err(MiddlewareError::InvalidState),
+        Err(_) => invocation
+            .take_downstream_error()
+            .map_or(Err(MiddlewareError::Fault), Err),
+    }
+}
+
+struct EmptyMiddlewareBody;
+
+impl MiddlewareBody for EmptyMiddlewareBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async { Ok(None) })
+    }
+
+    fn close(self: Box<Self>) -> BoxFuture<'static, ()> {
+        Box::pin(async {})
+    }
+}
+
+struct PluginMiddlewareBody {
+    stream: Option<RpcStream>,
+    framing: MiddlewareFraming,
+    terminal_seen: bool,
+    next_source_id: u64,
+    active_source: Option<u64>,
+    active_output_count: usize,
+    active_output_bytes: usize,
+    pending_transformed: bool,
+    downstream_error: Arc<Mutex<Option<MiddlewareError>>>,
+    downstream: Option<MiddlewareBodyAuthority>,
+    _invocation: Arc<MiddlewareInvocation>,
+}
+
+impl MiddlewareBody for PluginMiddlewareBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async move {
+            if let Some(error) = take_error(&self.downstream_error) {
+                self.stream.take();
+                return Err(error);
+            }
+            loop {
+                let Some(stream) = self.stream.as_mut() else {
+                    return Ok(None);
+                };
+                let chunk = match stream.next().await {
+                    Ok(chunk) => chunk,
+                    Err(_) => {
+                        self.stream.take();
+                        return Err(
+                            take_error(&self.downstream_error).unwrap_or(MiddlewareError::Fault)
+                        );
+                    }
+                };
+                let Some(chunk) = chunk else {
+                    self.stream.take();
+                    if self.active_source.is_some()
+                        || self.pending_transformed
+                        || match &self.downstream {
+                            Some(downstream) => downstream.has_pending_sources().await,
+                            None => false,
+                        }
+                    {
+                        return Err(MiddlewareError::InvalidState);
+                    }
+                    return take_error(&self.downstream_error).map_or(Ok(None), Err);
+                };
+                if self.terminal_seen {
+                    self.stream.take();
+                    return Err(MiddlewareError::InvalidState);
+                }
+                let wire_frame = MiddlewareBodyFrame::decode(&chunk)
+                    .map_err(|_| MiddlewareError::InvalidState)?;
+                let source_id = wire_frame.source_id();
+                let disposition = wire_frame.disposition();
+                if !matches!(disposition, MiddlewareBodyDisposition::Drop)
+                    && !valid_plugin_frame(self.framing, &wire_frame.payload)
+                {
+                    return Err(MiddlewareError::InvalidState);
+                }
+                let frame = match (&self.downstream, disposition) {
+                    (None, MiddlewareBodyDisposition::Standalone) => Some(
+                        MiddlewareFrame::new(
+                            Bytes::from(wire_frame.payload),
+                            self.framing,
+                            wire_frame.terminal,
+                        )
+                        .with_transformed(true),
+                    ),
+                    (Some(_), MiddlewareBodyDisposition::Standalone) | (None, _) => {
+                        return Err(MiddlewareError::InvalidState);
+                    }
+                    (Some(downstream), MiddlewareBodyDisposition::Only)
+                    | (Some(downstream), MiddlewareBodyDisposition::Drop) => {
+                        if self.active_source.is_some()
+                            || source_id != self.next_source_id.saturating_add(1)
+                            || wire_frame.payload.len() > MAXIMUM_MAPPED_BYTES_PER_SOURCE
+                        {
+                            return Err(MiddlewareError::InvalidState);
+                        }
+                        self.next_source_id = source_id;
+                        downstream
+                            .resolve_source_output(
+                                source_id,
+                                disposition,
+                                Bytes::from(wire_frame.payload),
+                            )
+                            .await?
+                    }
+                    (Some(downstream), MiddlewareBodyDisposition::First) => {
+                        if self.active_source.is_some()
+                            || source_id != self.next_source_id.saturating_add(1)
+                            || wire_frame.payload.len() > MAXIMUM_MAPPED_BYTES_PER_SOURCE
+                        {
+                            return Err(MiddlewareError::InvalidState);
+                        }
+                        self.active_source = Some(source_id);
+                        self.active_output_count = 1;
+                        self.active_output_bytes = wire_frame.payload.len();
+                        downstream
+                            .resolve_source_output(
+                                source_id,
+                                disposition,
+                                Bytes::from(wire_frame.payload),
+                            )
+                            .await?
+                    }
+                    (Some(downstream), MiddlewareBodyDisposition::More) => {
+                        self.active_output_count = self
+                            .active_output_count
+                            .checked_add(1)
+                            .ok_or(MiddlewareError::InvalidState)?;
+                        self.active_output_bytes = self
+                            .active_output_bytes
+                            .checked_add(wire_frame.payload.len())
+                            .ok_or(MiddlewareError::InvalidState)?;
+                        if self.active_source != Some(source_id)
+                            || self.active_output_count > MAXIMUM_MAPPED_FRAMES_PER_SOURCE
+                            || self.active_output_bytes > MAXIMUM_MAPPED_BYTES_PER_SOURCE
+                        {
+                            return Err(MiddlewareError::InvalidState);
+                        }
+                        downstream
+                            .resolve_source_output(
+                                source_id,
+                                disposition,
+                                Bytes::from(wire_frame.payload),
+                            )
+                            .await?
+                    }
+                    (Some(downstream), MiddlewareBodyDisposition::Last) => {
+                        self.active_output_count = self
+                            .active_output_count
+                            .checked_add(1)
+                            .ok_or(MiddlewareError::InvalidState)?;
+                        self.active_output_bytes = self
+                            .active_output_bytes
+                            .checked_add(wire_frame.payload.len())
+                            .ok_or(MiddlewareError::InvalidState)?;
+                        if self.active_source != Some(source_id)
+                            || self.active_output_count > MAXIMUM_MAPPED_FRAMES_PER_SOURCE
+                            || self.active_output_bytes > MAXIMUM_MAPPED_BYTES_PER_SOURCE
+                        {
+                            return Err(MiddlewareError::InvalidState);
+                        }
+                        self.active_source = None;
+                        self.active_output_count = 0;
+                        self.active_output_bytes = 0;
+                        self.next_source_id = source_id;
+                        downstream
+                            .resolve_source_output(
+                                source_id,
+                                disposition,
+                                Bytes::from(wire_frame.payload),
+                            )
+                            .await?
+                    }
+                };
+                if disposition == MiddlewareBodyDisposition::Drop {
+                    self.pending_transformed = true;
+                    if let Some(frame) = frame {
+                        return Ok(Some(frame.with_transformed(true)));
+                    }
+                    continue;
+                }
+                let mut frame = frame.ok_or(MiddlewareError::InvalidState)?;
+                if self.pending_transformed {
+                    frame = frame.with_transformed(true);
+                    self.pending_transformed = false;
+                }
+                if frame.terminal() {
+                    if self.active_source.is_some()
+                        || match &self.downstream {
+                            Some(downstream) => downstream.has_pending_sources().await,
+                            None => false,
+                        }
+                    {
+                        self.stream.take();
+                        return Err(MiddlewareError::InvalidState);
+                    }
+                    self.terminal_seen = true;
+                    let terminal = stream.next().await;
+                    self.stream.take();
+                    validate_terminal_end(terminal, &self.downstream_error)?;
+                }
+                return Ok(Some(frame));
+            }
+        })
+    }
+
+    fn commit_downstream(
+        &mut self,
+        client_status_code: Option<u16>,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        Box::pin(async move {
+            match &self.downstream {
+                Some(downstream) => downstream.commit_downstream(client_status_code).await,
+                None => Ok(()),
+            }
+        })
+    }
+
+    fn record_client_status(
+        &mut self,
+        client_status_code: u16,
+    ) -> BoxFuture<'_, Result<(), MiddlewareError>> {
+        Box::pin(async move {
+            match &self.downstream {
+                Some(downstream) => downstream.record_client_status(client_status_code).await,
+                None => Ok(()),
+            }
+        })
+    }
+
+    fn is_finalized(&self) -> bool {
+        self.downstream
+            .as_ref()
+            .is_none_or(MiddlewareBodyAuthority::is_finalized)
+    }
+
+    fn close(mut self: Box<Self>) -> BoxFuture<'static, ()> {
+        self.stream.take();
+        Box::pin(async {})
+    }
+}
+
+fn take_error(slot: &Mutex<Option<MiddlewareError>>) -> Option<MiddlewareError> {
+    slot.lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+        .take()
+}
+
+fn validate_terminal_end(
+    terminal: Result<Option<Vec<u8>>, RpcError>,
+    downstream_error: &Mutex<Option<MiddlewareError>>,
+) -> Result<(), MiddlewareError> {
+    // 只有插件在终帧后继续输出才属于状态无效；RPC 传输失败保持为调用故障，
+    // 两条失败路径都不能覆盖已经记录的下游域错误。
+    match terminal {
+        Ok(None) => Ok(()),
+        Ok(Some(_)) => Err(take_error(downstream_error).unwrap_or(MiddlewareError::InvalidState)),
+        Err(_) => Err(take_error(downstream_error).unwrap_or(MiddlewareError::Fault)),
+    }
+}
+
+const fn wire_transport(
+    transport: gateway_core::engine::execution::ClientTransport,
+) -> WireMiddlewareTransport {
+    match transport {
+        gateway_core::engine::execution::ClientTransport::HttpJson => {
+            WireMiddlewareTransport::HttpJson
+        }
+        gateway_core::engine::execution::ClientTransport::HttpSse => {
+            WireMiddlewareTransport::HttpSse
+        }
+        gateway_core::engine::execution::ClientTransport::WebSocket => {
+            WireMiddlewareTransport::WebSocket
+        }
+        gateway_core::engine::execution::ClientTransport::InternalProbe
+        | gateway_core::engine::execution::ClientTransport::InternalPlugin => {
+            WireMiddlewareTransport::Internal
+        }
+    }
+}
+
+fn valid_plugin_frame(framing: MiddlewareFraming, bytes: &[u8]) -> bool {
+    match framing {
+        MiddlewareFraming::JsonDocument => {
+            serde_json::from_slice::<serde::de::IgnoredAny>(bytes).is_ok()
+        }
+        MiddlewareFraming::SseEvent => {
+            (bytes.ends_with(b"\n\n") || bytes.ends_with(b"\r\n\r\n"))
+                && std::str::from_utf8(bytes).is_ok_and(|event| parse_sse_events(event).is_ok())
+        }
+        MiddlewareFraming::RawBytes => true,
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/policy/mod.rs b/backend/crates/gateway-plugin/runtime/src/adapter/policy/mod.rs
new file mode 100644
index 000000000..939b88f49
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/policy/mod.rs
@@ -0,0 +1,327 @@
+mod middleware;
+mod route_schedule;
+
+use std::{fmt, sync::Arc, time::Duration};
+
+use gateway_admin::model::{
+    AdminError,
+    plugins::instances::{PluginCapabilityBinding, PluginFailurePolicy, PluginInstance},
+};
+use gateway_core::engine::middleware::MiddlewareMount;
+use gateway_plugin_sdk::{Capability, Manifest, Permission, Stage};
+
+use crate::{RpcSession, adapter::scope::BindingScope, callback::PluginCallbacks};
+
+const POLICY_TIMEOUT: Duration = Duration::from_secs(2);
+
+pub(crate) enum PolicyEntry {
+    Router(ModelRouterEntry),
+    Scheduler(AccountSchedulerEntry),
+    Middleware(MiddlewareEntry),
+}
+
+#[derive(Clone)]
+struct PolicyInvocation {
+    session: Arc<RpcSession>,
+    callbacks: Arc<PluginCallbacks>,
+}
+
+pub(crate) struct ModelRouterEntry {
+    order: i32,
+    plugin_id: String,
+    instance_id: String,
+    invocation: Option<PolicyInvocation>,
+    scope: BindingScope,
+    failure_policy: PluginFailurePolicy,
+    requests_authorized: bool,
+}
+
+pub(crate) struct AccountSchedulerEntry {
+    plugin_id: String,
+    instance_id: String,
+    invocation: Option<PolicyInvocation>,
+    scope: BindingScope,
+    failure_policy: PluginFailurePolicy,
+    requests_authorized: bool,
+}
+
+pub(crate) struct MiddlewareEntry {
+    order: i32,
+    plugin_id: String,
+    instance_id: String,
+    mount: MiddlewareMount,
+    invocation: Option<PolicyInvocation>,
+    scope: BindingScope,
+    failure_policy: PluginFailurePolicy,
+    requests_authorized: bool,
+}
+
+pub(crate) fn validate_bindings(
+    manifest: &Manifest,
+    bindings: &[PluginCapabilityBinding],
+) -> Result<(), AdminError> {
+    let mut has_router = false;
+    let mut has_scheduler = false;
+    let mut middleware_stages = std::collections::BTreeSet::new();
+    for binding in bindings {
+        let capability = crate::contribution::resolve(manifest, binding)?.capability;
+        if !matches!(
+            capability,
+            Capability::ModelRouter | Capability::Scheduler | Capability::Middleware
+        ) {
+            continue;
+        }
+        let stage: Stage = serde_json::from_value(serde_json::Value::String(binding.stage.clone()))
+            .map_err(|_| AdminError::invalid("插件请求阶段无效"))?;
+        if !matches!(
+            binding.failure_policy,
+            PluginFailurePolicy::Reject | PluginFailurePolicy::Delegate
+        ) {
+            return Err(AdminError::invalid("数据面绑定的故障策略无效"));
+        }
+        match capability {
+            Capability::ModelRouter => {
+                if std::mem::replace(&mut has_router, true) || stage != Stage::Routing {
+                    return Err(AdminError::invalid(
+                        "同一插件实例的模型路由能力只能绑定一次且必须使用 routing 阶段",
+                    ));
+                }
+            }
+            Capability::Scheduler => {
+                if std::mem::replace(&mut has_scheduler, true) || stage != Stage::Scheduling {
+                    return Err(AdminError::invalid(
+                        "同一插件实例的账号调度能力只能绑定一次且必须使用 scheduling 阶段",
+                    ));
+                }
+            }
+            Capability::Middleware => {
+                if !matches!(stage, Stage::Request | Stage::Attempt)
+                    || !middleware_stages.insert(stage)
+                {
+                    return Err(AdminError::invalid(
+                        "同一插件实例的中间件只能在 request/attempt 各绑定一次",
+                    ));
+                }
+            }
+            _ => unreachable!("capability was filtered above"),
+        }
+        let scope = BindingScope::compile(binding)?;
+        if (capability == Capability::ModelRouter
+            || (capability == Capability::Middleware && stage == Stage::Request))
+            && scope.has_provider_condition()
+        {
+            return Err(AdminError::invalid(
+                "Provider 尚未冻结的阶段不能绑定 Provider 条件",
+            ));
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn compile_entries(
+    manifest: &Manifest,
+    instance_id: &str,
+    bindings: &[PluginCapabilityBinding],
+    permissions: &[Permission],
+    session: Arc<RpcSession>,
+    callbacks: Arc<PluginCallbacks>,
+) -> Result<Vec<PolicyEntry>, AdminError> {
+    validate_bindings(manifest, bindings)?;
+    let plugin_id = manifest
+        .plugin_id()
+        .map_err(|_| AdminError::invalid("插件身份无效"))?;
+    let invocation = PolicyInvocation { session, callbacks };
+    bindings
+        .iter()
+        .filter_map(|binding| {
+            let capability = match crate::contribution::resolve(manifest, binding) {
+                Ok(contribution) => contribution.capability,
+                Err(error) => return Some(Err(error)),
+            };
+            matches!(
+                capability,
+                Capability::ModelRouter | Capability::Scheduler | Capability::Middleware
+            )
+            .then(|| {
+                compile_entry(
+                    &plugin_id,
+                    instance_id,
+                    binding,
+                    capability,
+                    Some(invocation.clone()),
+                    permissions.contains(&Permission::Requests),
+                )
+            })
+        })
+        .collect()
+}
+
+/// 已保存绑定的阶段是宿主合同；进程不可用时仍保留相同范围和故障策略。
+pub(crate) fn unavailable_entries(
+    instance: &PluginInstance,
+) -> Result<Vec<PolicyEntry>, AdminError> {
+    instance
+        .bindings
+        .iter()
+        .filter_map(|binding| {
+            let capability = match binding.stage.as_str() {
+                "routing" => Capability::ModelRouter,
+                "scheduling" => Capability::Scheduler,
+                "request" | "attempt" => Capability::Middleware,
+                _ => return None,
+            };
+            Some(compile_entry(
+                binding
+                    .contribution
+                    .rsplit_once('.')
+                    .map_or(binding.contribution.as_str(), |(plugin, _)| plugin),
+                &instance.id,
+                binding,
+                capability,
+                None,
+                false,
+            ))
+        })
+        .collect()
+}
+
+fn compile_entry(
+    plugin_id: &str,
+    instance_id: &str,
+    binding: &PluginCapabilityBinding,
+    capability: Capability,
+    invocation: Option<PolicyInvocation>,
+    requests_authorized: bool,
+) -> Result<PolicyEntry, AdminError> {
+    let scope = BindingScope::compile(binding)?;
+    Ok(match capability {
+        Capability::ModelRouter => PolicyEntry::Router(ModelRouterEntry {
+            order: binding.order,
+            plugin_id: plugin_id.to_owned(),
+            instance_id: instance_id.to_owned(),
+            invocation,
+            scope,
+            failure_policy: binding.failure_policy.clone(),
+            requests_authorized,
+        }),
+        Capability::Scheduler => PolicyEntry::Scheduler(AccountSchedulerEntry {
+            plugin_id: plugin_id.to_owned(),
+            instance_id: instance_id.to_owned(),
+            invocation,
+            scope,
+            failure_policy: binding.failure_policy.clone(),
+            requests_authorized,
+        }),
+        Capability::Middleware => PolicyEntry::Middleware(MiddlewareEntry {
+            order: binding.order,
+            plugin_id: plugin_id.to_owned(),
+            instance_id: instance_id.to_owned(),
+            mount: match binding.stage.as_str() {
+                "request" => MiddlewareMount::Request,
+                "attempt" => MiddlewareMount::Attempt,
+                _ => return Err(AdminError::invalid("插件中间件阶段无效")),
+            },
+            invocation,
+            scope,
+            failure_policy: binding.failure_policy.clone(),
+            requests_authorized,
+        }),
+        _ => return Err(AdminError::invalid("插件请求策略能力无效")),
+    })
+}
+
+pub(crate) struct PluginRequestPolicyPlan {
+    routers: Arc<[ModelRouterEntry]>,
+    schedulers: Arc<[AccountSchedulerEntry]>,
+    middleware: Arc<[MiddlewareEntry]>,
+    policy_timeout: Duration,
+    middleware_timeout: Duration,
+    maximum_payload_bytes: usize,
+}
+
+impl fmt::Debug for PluginRequestPolicyPlan {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("PluginRequestPolicyPlan")
+            .field("router_count", &self.routers.len())
+            .field("scheduler_count", &self.schedulers.len())
+            .field("middleware_count", &self.middleware.len())
+            .finish_non_exhaustive()
+    }
+}
+
+impl PluginRequestPolicyPlan {
+    pub(crate) fn compile(
+        entries: Vec<PolicyEntry>,
+        maximum_call_timeout: Duration,
+        maximum_frame_bytes: usize,
+    ) -> Result<Option<Arc<Self>>, AdminError> {
+        let mut routers = Vec::new();
+        let mut schedulers = Vec::new();
+        let mut middleware = Vec::new();
+        for entry in entries {
+            match entry {
+                PolicyEntry::Router(entry) => routers.push(entry),
+                PolicyEntry::Scheduler(entry) => schedulers.push(entry),
+                PolicyEntry::Middleware(entry) => middleware.push(entry),
+            }
+        }
+        if routers.is_empty() && schedulers.is_empty() && middleware.is_empty() {
+            return Ok(None);
+        }
+        routers.sort_by(|left, right| {
+            (left.order, &left.plugin_id, &left.instance_id).cmp(&(
+                right.order,
+                &right.plugin_id,
+                &right.instance_id,
+            ))
+        });
+        for (index, left) in schedulers.iter().enumerate() {
+            if schedulers[index + 1..]
+                .iter()
+                .any(|right| left.scope.overlaps(&right.scope))
+            {
+                return Err(AdminError::invalid("账号调度绑定作用范围重叠"));
+            }
+        }
+        middleware.sort_by(|left, right| {
+            (
+                mount_order(left.mount),
+                left.order,
+                &left.plugin_id,
+                &left.instance_id,
+            )
+                .cmp(&(
+                    mount_order(right.mount),
+                    right.order,
+                    &right.plugin_id,
+                    &right.instance_id,
+                ))
+        });
+        Ok(Some(Arc::new(Self {
+            routers: routers.into(),
+            schedulers: schedulers.into(),
+            middleware: middleware.into(),
+            policy_timeout: maximum_call_timeout.min(POLICY_TIMEOUT),
+            middleware_timeout: maximum_call_timeout,
+            maximum_payload_bytes: maximum_frame_bytes,
+        })))
+    }
+
+    #[must_use]
+    pub(crate) fn has_request_policy(&self) -> bool {
+        !self.routers.is_empty() || !self.schedulers.is_empty()
+    }
+
+    #[must_use]
+    pub(crate) fn has_middleware(&self) -> bool {
+        !self.middleware.is_empty()
+    }
+}
+
+const fn mount_order(mount: MiddlewareMount) -> u8 {
+    match mount {
+        MiddlewareMount::Request => 0,
+        MiddlewareMount::Attempt => 1,
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/policy/route_schedule.rs b/backend/crates/gateway-plugin/runtime/src/adapter/policy/route_schedule.rs
new file mode 100644
index 000000000..4e684a8b1
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/policy/route_schedule.rs
@@ -0,0 +1,489 @@
+use std::{
+    io,
+    time::{Duration, SystemTime, UNIX_EPOCH},
+};
+
+use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64};
+use futures::future::BoxFuture;
+use gateway_core::{
+    account::ProviderAccountId,
+    engine::policy::{
+        AccountScheduleDecision, AccountScheduleInput, ModelRouteDecision, ModelRouteInput,
+        RequestPolicyFault, RequestPolicyPlan,
+    },
+    identity::ProviderKind,
+    operation::{Operation, ProviderHttpHeader},
+    routing::PublicModelId,
+};
+use gateway_plugin_sdk::{
+    Stage,
+    call::policy::{
+        AccountScheduleCandidate as WireAccountScheduleCandidate,
+        AccountScheduleDecision as WireAccountScheduleDecision,
+        AccountScheduleRequest as WireAccountScheduleRequest,
+        ModelRouteDecision as WireModelRouteDecision, ModelRouteRequest, PolicyHeader,
+    },
+};
+
+use super::{AccountSchedulerEntry, ModelRouterEntry, PluginRequestPolicyPlan};
+
+const MAX_HEADERS: usize = 128;
+const MAX_HEADER_NAME_BYTES: usize = 128;
+const MAX_HEADER_VALUE_BYTES: usize = 16 * 1024;
+const MAX_HEADER_TOTAL_BYTES: usize = 64 * 1024;
+const OPAQUE_HEADERS_KEY: &str = "opaque_request_headers";
+
+impl RequestPolicyPlan for PluginRequestPolicyPlan {
+    fn route_model(
+        &self,
+        input: ModelRouteInput,
+    ) -> BoxFuture<'static, Result<ModelRouteDecision, RequestPolicyFault>> {
+        let routers = std::sync::Arc::clone(&self.routers);
+        let timeout = self.policy_timeout;
+        let maximum_payload_bytes = self.maximum_payload_bytes;
+        Box::pin(async move {
+            for entry in routers.iter().filter(|entry| {
+                !input.suppresses_plugin(&entry.instance_id) && entry.scope.matches_route(&input)
+            }) {
+                let result = route_with_entry(entry, &input, timeout, maximum_payload_bytes).await;
+                match result {
+                    Ok(ModelRouteDecision::Unhandled) => continue,
+                    Ok(decision) => return Ok(decision),
+                    Err(())
+                        if entry.failure_policy
+                            == gateway_admin::model::plugins::instances::PluginFailurePolicy::Delegate =>
+                    {
+                        tracing::warn!(
+                            plugin_id = entry.plugin_id,
+                            instance_id = entry.instance_id,
+                            request_id = input.request_id().as_str(),
+                            "插件模型路由失败，按绑定委托后续策略"
+                        );
+                    }
+                    Err(()) => return Err(RequestPolicyFault),
+                }
+            }
+            Ok(ModelRouteDecision::Unhandled)
+        })
+    }
+
+    fn schedule_account(
+        &self,
+        input: AccountScheduleInput,
+    ) -> BoxFuture<'static, Result<AccountScheduleDecision, RequestPolicyFault>> {
+        let schedulers = std::sync::Arc::clone(&self.schedulers);
+        let timeout = self.policy_timeout;
+        Box::pin(async move {
+            let Some(entry) = schedulers.iter().find(|entry| {
+                !input.suppresses_plugin(&entry.instance_id) && entry.scope.matches_schedule(&input)
+            }) else {
+                return Ok(AccountScheduleDecision::Delegate);
+            };
+            match schedule_with_entry(entry, &input, timeout).await {
+                Ok(decision) => Ok(decision),
+                Err(())
+                    if entry.failure_policy
+                        == gateway_admin::model::plugins::instances::PluginFailurePolicy::Delegate =>
+                {
+                    tracing::warn!(
+                        plugin_id = entry.plugin_id,
+                        instance_id = entry.instance_id,
+                        request_id = input.request_id().as_str(),
+                        "插件账号调度失败，按绑定委托内置策略"
+                    );
+                    Ok(AccountScheduleDecision::Delegate)
+                }
+                Err(()) => Err(RequestPolicyFault),
+            }
+        })
+    }
+}
+
+async fn route_with_entry(
+    entry: &ModelRouterEntry,
+    input: &ModelRouteInput,
+    timeout: Duration,
+    maximum_payload_bytes: usize,
+) -> Result<ModelRouteDecision, ()> {
+    let invocation = entry.invocation.as_ref().ok_or(())?;
+    let projection = operation_projection(input.operation())?;
+    let payload = if entry.requests_authorized {
+        projection.body.to_bytes(maximum_payload_bytes)?
+    } else {
+        Vec::new()
+    };
+    let headers = if entry.requests_authorized {
+        project_request_headers(input.operation(), projection.context)?
+    } else {
+        Vec::new()
+    };
+    let request = ModelRouteRequest {
+        request_id: input.request_id().as_str().to_owned(),
+        operation: input.operation().kind().as_str().to_owned(),
+        protocol: projection.protocol.to_owned(),
+        model: input.requested_model().as_str().to_owned(),
+        available_providers: input
+            .available_providers()
+            .iter()
+            .map(|provider| provider.as_str().to_owned())
+            .collect(),
+        headers,
+    };
+    let mut context = invocation.session.context(Stage::Routing, timeout);
+    context.request_id = Some(input.request_id().as_str().to_owned());
+    let _network_scope = invocation
+        .callbacks
+        .prepare_data_plane(&context, input.execution_effects())
+        .map_err(|_| ())?;
+    let reply = invocation
+        .session
+        .call(
+            "policy.route_model",
+            context,
+            serde_json::to_value(request).map_err(|_| ())?,
+            payload,
+        )
+        .await
+        .map_err(|_| ())?;
+    if !reply.payload.is_empty() {
+        return Err(());
+    }
+    let decision: WireModelRouteDecision = serde_json::from_value(reply.result).map_err(|_| ())?;
+    match decision {
+        WireModelRouteDecision::Unhandled => Ok(ModelRouteDecision::Unhandled),
+        WireModelRouteDecision::Reject => Ok(ModelRouteDecision::Reject),
+        WireModelRouteDecision::Route { provider, model } => {
+            if provider.is_none() && model.is_none() {
+                return Err(());
+            }
+            let provider = provider
+                .map(|provider| ProviderKind::new(provider).map_err(|_| ()))
+                .transpose()?;
+            if provider
+                .as_ref()
+                .is_some_and(|provider| !input.available_providers().contains(provider))
+            {
+                return Err(());
+            }
+            let model = model
+                .map(|model| PublicModelId::new(model).map_err(|_| ()))
+                .transpose()?;
+            Ok(ModelRouteDecision::Route { provider, model })
+        }
+    }
+}
+
+async fn schedule_with_entry(
+    entry: &AccountSchedulerEntry,
+    input: &AccountScheduleInput,
+    timeout: Duration,
+) -> Result<AccountScheduleDecision, ()> {
+    let invocation = entry.invocation.as_ref().ok_or(())?;
+    let highest_weight = input
+        .candidates()
+        .iter()
+        .map(gateway_core::engine::policy::AccountScheduleCandidate::weight)
+        .max()
+        .ok_or(())?;
+    let visible = input
+        .candidates()
+        .iter()
+        .filter(|candidate| entry.requests_authorized || candidate.weight() == highest_weight)
+        .collect::<Vec<_>>();
+    let request = WireAccountScheduleRequest {
+        request_id: input.request_id().as_str().to_owned(),
+        attempt_index: input.attempt_index().get(),
+        provider: input.provider().as_str().to_owned(),
+        model: input.model().map(str::to_owned),
+        candidates: visible
+            .iter()
+            .map(|candidate| WireAccountScheduleCandidate {
+                account_id: candidate.account_id().as_str().to_owned(),
+                weight: candidate.weight(),
+                in_flight: candidate.in_flight(),
+                maximum_concurrency: candidate.maximum_concurrency(),
+                last_started_at_ms: system_time_millis(candidate.last_started_at()),
+                quota_reset_at_ms: system_time_millis(candidate.quota_reset_at()),
+                quota_remaining_rank: candidate.quota_remaining_rank(),
+                failure_rate_basis_points: candidate.failure_rate_basis_points(),
+                first_output_latency_ms: candidate.first_output_latency_ms(),
+            })
+            .collect(),
+    };
+    let mut context = invocation.session.context(Stage::Scheduling, timeout);
+    context.request_id = Some(input.request_id().as_str().to_owned());
+    context.attempt_id = Some(format!(
+        "{}:{}",
+        input.request_id().as_str(),
+        input.attempt_index()
+    ));
+    let _network_scope = invocation
+        .callbacks
+        .prepare_data_plane(&context, input.execution_effects())
+        .map_err(|_| ())?;
+    let reply = invocation
+        .session
+        .call(
+            "policy.schedule_account",
+            context,
+            serde_json::to_value(request).map_err(|_| ())?,
+            Vec::new(),
+        )
+        .await
+        .map_err(|_| ())?;
+    if !reply.payload.is_empty() {
+        return Err(());
+    }
+    let decision: WireAccountScheduleDecision =
+        serde_json::from_value(reply.result).map_err(|_| ())?;
+    match decision {
+        WireAccountScheduleDecision::Delegate => Ok(AccountScheduleDecision::Delegate),
+        WireAccountScheduleDecision::Reject => Ok(AccountScheduleDecision::Reject),
+        WireAccountScheduleDecision::Pick { account_id } => {
+            let account_id = ProviderAccountId::new(account_id).map_err(|_| ())?;
+            if !visible
+                .iter()
+                .any(|candidate| candidate.account_id() == &account_id)
+            {
+                return Err(());
+            }
+            Ok(AccountScheduleDecision::Pick(account_id))
+        }
+    }
+}
+
+struct OperationProjection<'a> {
+    protocol: &'a str,
+    body: OperationBody<'a>,
+    context: &'a serde_json::Map<String, serde_json::Value>,
+}
+
+enum OperationBody<'a> {
+    Object(&'a serde_json::Map<String, serde_json::Value>),
+    Raw(&'a [u8]),
+}
+
+impl OperationBody<'_> {
+    fn to_bytes(&self, maximum: usize) -> Result<Vec<u8>, ()> {
+        match self {
+            Self::Raw(body) if body.len() <= maximum => Ok(body.to_vec()),
+            Self::Raw(_) => Err(()),
+            Self::Object(body) => {
+                let mut writer = LimitedWriter::new(maximum);
+                serde_json::to_writer(&mut writer, body).map_err(|_| ())?;
+                Ok(writer.into_inner())
+            }
+        }
+    }
+}
+
+fn operation_projection(operation: &Operation) -> Result<OperationProjection<'_>, ()> {
+    Ok(match operation {
+        Operation::Generate(request) => {
+            let payload = request.protocol_payload();
+            OperationProjection {
+                protocol: payload.protocol(),
+                body: OperationBody::Object(payload.body()),
+                context: payload.context(),
+            }
+        }
+        Operation::GenerateImage(request) => {
+            let payload = request.payload();
+            OperationProjection {
+                protocol: payload.protocol(),
+                body: OperationBody::Raw(payload.body().as_ref()),
+                context: payload.context(),
+            }
+        }
+        Operation::Search(request) => {
+            let payload = request.payload();
+            OperationProjection {
+                protocol: payload.protocol(),
+                body: OperationBody::Raw(payload.body().as_ref()),
+                context: payload.context(),
+            }
+        }
+        Operation::CountTokens(request) => {
+            let payload = request.payload();
+            OperationProjection {
+                protocol: payload.protocol(),
+                body: OperationBody::Raw(payload.body().as_ref()),
+                context: payload.context(),
+            }
+        }
+        Operation::ProviderHttp(request) => {
+            let payload = request.payload();
+            OperationProjection {
+                protocol: payload.protocol(),
+                body: OperationBody::Raw(payload.body().as_ref()),
+                context: payload.context(),
+            }
+        }
+        _ => return Err(()),
+    })
+}
+
+fn project_request_headers(
+    operation: &Operation,
+    context: &serde_json::Map<String, serde_json::Value>,
+) -> Result<Vec<PolicyHeader>, ()> {
+    match operation {
+        Operation::ProviderHttp(request) => project_provider_http_headers(request.headers()),
+        _ => project_headers(context),
+    }
+}
+
+fn project_provider_http_headers(headers: &[ProviderHttpHeader]) -> Result<Vec<PolicyHeader>, ()> {
+    if headers.len() > MAX_HEADERS {
+        return Err(());
+    }
+    let mut projected = Vec::with_capacity(headers.len());
+    let mut total_bytes = 0_usize;
+    for header in headers {
+        let name = normalized_header_name(header.name())?;
+        let value_base64 = BASE64.encode(header.value());
+        if value_base64.len() > MAX_HEADER_VALUE_BYTES {
+            return Err(());
+        }
+        total_bytes = total_bytes
+            .checked_add(name.len())
+            .and_then(|total| total.checked_add(value_base64.len()))
+            .ok_or(())?;
+        if total_bytes > MAX_HEADER_TOTAL_BYTES {
+            return Err(());
+        }
+        if sensitive_or_identity_header(&name) {
+            continue;
+        }
+        projected.push(PolicyHeader { name, value_base64 });
+    }
+    Ok(projected)
+}
+
+fn project_headers(
+    context: &serde_json::Map<String, serde_json::Value>,
+) -> Result<Vec<PolicyHeader>, ()> {
+    let Some(value) = context.get(OPAQUE_HEADERS_KEY) else {
+        return Ok(Vec::new());
+    };
+    let entries = value.as_array().ok_or(())?;
+    if entries.len() > MAX_HEADERS {
+        return Err(());
+    }
+    let mut projected = Vec::with_capacity(entries.len());
+    let mut total_bytes = 0_usize;
+    for entry in entries {
+        let pair = entry.as_array().filter(|pair| pair.len() == 2).ok_or(())?;
+        let name = pair[0].as_str().ok_or(())?;
+        let value_base64 = pair[1].as_str().ok_or(())?;
+        if name.is_empty()
+            || name.len() > MAX_HEADER_NAME_BYTES
+            || !name
+                .bytes()
+                .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
+            || value_base64.len() > MAX_HEADER_VALUE_BYTES
+            || value_base64.len() % 4 != 0
+            || !value_base64
+                .bytes()
+                .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'+' | b'/' | b'='))
+        {
+            return Err(());
+        }
+        total_bytes = total_bytes
+            .checked_add(name.len())
+            .and_then(|total| total.checked_add(value_base64.len()))
+            .ok_or(())?;
+        if total_bytes > MAX_HEADER_TOTAL_BYTES {
+            return Err(());
+        }
+        if sensitive_or_identity_header(name) {
+            continue;
+        }
+        projected.push(PolicyHeader {
+            name: name.to_owned(),
+            value_base64: value_base64.to_owned(),
+        });
+    }
+    Ok(projected)
+}
+
+fn normalized_header_name(name: &str) -> Result<String, ()> {
+    let name = name.trim().to_ascii_lowercase();
+    if name.is_empty()
+        || name.len() > MAX_HEADER_NAME_BYTES
+        || !name
+            .bytes()
+            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
+    {
+        return Err(());
+    }
+    Ok(name)
+}
+
+fn sensitive_or_identity_header(name: &str) -> bool {
+    name.contains("auth")
+        || name.contains("credential")
+        || name.contains("secret")
+        || name.contains("token")
+        || name.contains("cookie")
+        || name.contains("session")
+        || name.contains("conversation")
+        || name.contains("thread")
+        || name.contains("account")
+        || name.contains("organization")
+        || name.contains("project")
+        || name.contains("tenant")
+        || name.contains("principal")
+        || name.contains("identity")
+        || name.contains("user-id")
+        || name.ends_with("-key")
+        || name.ends_with("_key")
+}
+
+fn system_time_millis(value: Option<SystemTime>) -> Option<u64> {
+    value?
+        .duration_since(UNIX_EPOCH)
+        .ok()?
+        .as_millis()
+        .try_into()
+        .ok()
+}
+
+struct LimitedWriter {
+    bytes: Vec<u8>,
+    maximum: usize,
+}
+
+impl LimitedWriter {
+    fn new(maximum: usize) -> Self {
+        Self {
+            bytes: Vec::new(),
+            maximum,
+        }
+    }
+
+    fn into_inner(self) -> Vec<u8> {
+        self.bytes
+    }
+}
+
+impl io::Write for LimitedWriter {
+    fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
+        if self
+            .bytes
+            .len()
+            .checked_add(bytes.len())
+            .is_none_or(|length| length > self.maximum)
+        {
+            return Err(io::Error::other(
+                "request body exceeds plugin payload limit",
+            ));
+        }
+        self.bytes.extend_from_slice(bytes);
+        Ok(bytes.len())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/administration.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/administration.rs
new file mode 100644
index 000000000..ba98e2154
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/administration.rs
@@ -0,0 +1,274 @@
+use std::time::Duration;
+
+use async_trait::async_trait;
+use gateway_admin::{
+    model::{
+        observability::{CalculatedBillingBreakdown, DashboardWireProfile, ProviderBillingInput},
+        provider_credentials::{
+            AuthorizationStarted, CompleteAuthorization, ConsumeProviderResetCredit,
+            PollAuthorization, PrepareAuthorization, PrepareCredentialImport,
+            PrepareCredentialRefresh, PrepareCredentialRotation, PreparedAuthorizationCommit,
+            PreparedAuthorizationPoll, PreparedCredentialImport, PreparedCredentialRotation,
+            ProviderExport, ProviderExportCredentialInput, ProviderModels, ProviderProfileAvatar,
+            ProviderProfileStatistics, ProviderQuota, ProviderQuotaRequest,
+            ProviderResetCreditResult, ProviderResetCredits, ProviderSubscription,
+        },
+    },
+    ports::provider::{ProviderAdmin, ProviderAdminError, ProviderAdminErrorKind},
+};
+use gateway_core::{
+    account::ProviderAccountId,
+    operation::{GenerateRequest, Operation, ProtocolPayload},
+    routing::{ProviderKind, UpstreamModelId},
+};
+use gateway_plugin_sdk::Stage;
+
+use super::PluginProvider;
+
+#[async_trait]
+impl ProviderAdmin for PluginProvider {
+    fn pricing_catalog(&self) -> gateway_admin::model::pricing::ProviderPricingCatalog {
+        self.pricing.clone().unwrap_or_default()
+    }
+
+    fn provider_kind(&self) -> &ProviderKind {
+        &self.kind
+    }
+
+    fn credential_capabilities(
+        &self,
+    ) -> gateway_admin::model::provider_capabilities::ProviderCredentialCapabilities {
+        PluginProvider::credential_capabilities(self)
+    }
+
+    fn account_capabilities(
+        &self,
+        _account_id: &ProviderAccountId,
+        _authentication_kind: &str,
+    ) -> gateway_admin::model::provider_capabilities::ProviderAccountCapabilities {
+        use gateway_admin::model::provider_capabilities::ProviderAccountCapabilities;
+        use gateway_plugin_sdk::call::provider::account::AccountOperation;
+        ProviderAccountCapabilities {
+            quota: self.quota_enabled,
+            quota_refresh: self.quota_enabled,
+            profile: self.account_operations.contains(&AccountOperation::Profile),
+            subscription: self
+                .account_operations
+                .contains(&AccountOperation::Subscription),
+            avatar: self.account_operations.contains(&AccountOperation::Avatar),
+            reset_credits: self
+                .account_operations
+                .contains(&AccountOperation::ResetCredits),
+            consume_reset_credit: self
+                .account_operations
+                .contains(&AccountOperation::ConsumeResetCredit),
+        }
+    }
+
+    fn client_profile_options(
+        &self,
+    ) -> Result<gateway_core::account::OpaqueProviderData, ProviderAdminError> {
+        self.request_profiles
+            .as_ref()
+            .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))?
+            .options()
+    }
+
+    fn default_client_profile(&self) -> Option<gateway_core::account::OpaqueProviderData> {
+        self.request_profiles
+            .as_ref()
+            .map(super::request_profile::PreparedRequestProfiles::default_configuration)
+    }
+
+    fn preview_client_profile(
+        &self,
+        configuration: &gateway_core::account::OpaqueProviderData,
+    ) -> Result<gateway_core::account::OpaqueProviderData, ProviderAdminError> {
+        self.request_profiles
+            .as_ref()
+            .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))?
+            .preview(configuration)
+    }
+
+    async fn account_unavailable(&self, account_id: &ProviderAccountId) {
+        self.catalog.invalidate(std::slice::from_ref(account_id));
+        self.invalidate_unavailable(account_id).await;
+    }
+
+    async fn account_facts_changed(&self, account_ids: &[ProviderAccountId]) {
+        self.catalog.invalidate(account_ids);
+        self.invalidate_facts(account_ids).await;
+    }
+
+    async fn connection_test_operation(
+        &self,
+        model: &UpstreamModelId,
+        input: &str,
+    ) -> Result<Operation, ProviderAdminError> {
+        let reply = self
+            .session
+            .call(
+                "provider.connection_test",
+                self.session
+                    .context(Stage::Configuration, Duration::from_secs(5)),
+                serde_json::json!({"model":model.as_str(),"input":input}),
+                vec![],
+            )
+            .await
+            .map_err(|_| unavailable())?;
+        let probe: gateway_plugin_sdk::call::provider::ProbeOperation =
+            serde_json::from_value(reply.result).map_err(|_| invalid())?;
+        if !reply.payload.is_empty() || !self.input_formats.contains(&probe.protocol) {
+            return Err(invalid());
+        }
+        let payload =
+            ProtocolPayload::json_object(probe.protocol, probe.body).map_err(|_| invalid())?;
+        Ok(Operation::Generate(GenerateRequest::from_protocol_payload(
+            payload,
+        )))
+    }
+
+    fn dashboard_wire_profile(&self) -> Option<DashboardWireProfile> {
+        self.request_profiles
+            .as_ref()
+            .and_then(|profiles| profiles.dashboard(None))
+    }
+
+    fn configured_wire_profile(
+        &self,
+        configuration: &gateway_core::account::OpaqueProviderData,
+    ) -> Option<DashboardWireProfile> {
+        self.request_profiles
+            .as_ref()
+            .and_then(|profiles| profiles.dashboard(Some(configuration)))
+    }
+
+    fn calculated_billing(
+        &self,
+        _input: &ProviderBillingInput,
+    ) -> Result<Option<CalculatedBillingBreakdown>, ProviderAdminError> {
+        // 插件费用明细只能从请求落库的冻结快照恢复；当前代次价目不能重算历史请求。
+        Ok(None)
+    }
+
+    async fn models(
+        &self,
+        account_id: &ProviderAccountId,
+        refresh: bool,
+    ) -> Result<ProviderModels, ProviderAdminError> {
+        self.account_models(account_id, refresh).await
+    }
+
+    async fn prepare_import(
+        &self,
+        command: PrepareCredentialImport,
+    ) -> Result<PreparedCredentialImport, ProviderAdminError> {
+        self.import_credentials(command).await
+    }
+    async fn start_authorization(
+        &self,
+        command: PrepareAuthorization,
+    ) -> Result<AuthorizationStarted, ProviderAdminError> {
+        self.start_login(command).await
+    }
+    async fn poll_authorization(
+        &self,
+        command: PollAuthorization,
+    ) -> Result<PreparedAuthorizationPoll, ProviderAdminError> {
+        self.poll_login(command).await
+    }
+    async fn complete_authorization(
+        &self,
+        _command: CompleteAuthorization,
+    ) -> Result<PreparedAuthorizationCommit, ProviderAdminError> {
+        Err(unsupported())
+    }
+    async fn prepare_rotation(
+        &self,
+        command: PrepareCredentialRotation,
+    ) -> Result<PreparedCredentialRotation, ProviderAdminError> {
+        self.rotate_credentials(command.account, Some(command.provider_material))
+            .await
+    }
+    async fn prepare_refresh(
+        &self,
+        command: PrepareCredentialRefresh,
+    ) -> Result<PreparedCredentialRotation, ProviderAdminError> {
+        self.rotate_credentials(command.account, None).await
+    }
+    async fn account_configuration(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<
+        Option<gateway_admin::model::provider_credentials::ProviderDocument>,
+        ProviderAdminError,
+    > {
+        self.connection_configuration(account_id).await
+    }
+    async fn quota(
+        &self,
+        request: ProviderQuotaRequest,
+    ) -> Result<ProviderQuota, ProviderAdminError> {
+        self.account_quota(request).await
+    }
+    fn quota_forecast_observation(
+        &self,
+        document: &gateway_admin::model::provider_credentials::ProviderDocument,
+        window: &gateway_admin::model::provider_credentials::ProviderQuotaWindow,
+    ) -> Option<gateway_admin::model::quota_forecast_sampling::QuotaForecastObservation> {
+        self.quota_enabled
+            .then(|| super::forecast::observation(document, window))
+            .flatten()
+    }
+    async fn export_credentials(
+        &self,
+        credentials: Vec<ProviderExportCredentialInput>,
+    ) -> Result<ProviderExport, ProviderAdminError> {
+        self.export_credentials_document(credentials).await
+    }
+
+    async fn profile_statistics(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, ProviderAdminError> {
+        self.account_profile(account_id).await
+    }
+
+    async fn subscription(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<Option<ProviderSubscription>, ProviderAdminError> {
+        self.account_subscription(account_id).await
+    }
+
+    async fn profile_avatar(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileAvatar, ProviderAdminError> {
+        self.account_avatar(account_id).await
+    }
+
+    async fn reset_credits(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<ProviderResetCredits, ProviderAdminError> {
+        self.query_reset_credits(account_id).await
+    }
+
+    async fn consume_reset_credit(
+        &self,
+        command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, ProviderAdminError> {
+        self.redeem_reset_credit(command).await
+    }
+}
+
+pub(super) fn unsupported() -> ProviderAdminError {
+    ProviderAdminError::new(ProviderAdminErrorKind::Unsupported)
+}
+pub(super) fn invalid() -> ProviderAdminError {
+    ProviderAdminError::new(ProviderAdminErrorKind::Invalid)
+}
+pub(super) fn unavailable() -> ProviderAdminError {
+    ProviderAdminError::new(ProviderAdminErrorKind::Unavailable)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/authorization.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/authorization.rs
new file mode 100644
index 000000000..fa16a2cbe
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/authorization.rs
@@ -0,0 +1,386 @@
+//! 登录只准备凭据事实；临时状态归宿主加密存储，账号提交与审计仍归 Admin。
+
+use std::{sync::Arc, time::Duration};
+
+use super::management::ProviderOperation;
+use async_trait::async_trait;
+use chrono::Utc;
+use gateway_admin::{
+    model::{
+        AdminError,
+        provider_credentials::{
+            AuthorizationCommitGuard, AuthorizationMutationTarget, AuthorizationOwner,
+            AuthorizationOwnerBinding, AuthorizationStarted, PendingAuthorizationMutation,
+            PollAuthorization, PrepareAuthorization, PreparedAuthorizationCommit,
+            PreparedAuthorizationCredential, PreparedAuthorizationPoll,
+        },
+    },
+    ports::provider::{ProviderAdminError, ProviderAdminErrorKind},
+};
+use gateway_core::{
+    account::OpaqueProviderData,
+    provider_ports::{
+        NewOAuthPendingFlow, OAuthPendingBinding, OAuthPendingClaimOutcome,
+        OAuthPendingConsumeOutcome, OAuthPendingFlowPort, OAuthPendingPutOutcome,
+        OAuthPendingReleaseOutcome,
+    },
+    routing::ProviderKind,
+};
+use gateway_plugin_sdk::call::auth::{
+    CredentialOperation, LoginPoll, LoginPollResult, LoginStart, LoginStarted,
+};
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+
+use super::{
+    PluginProvider,
+    administration::{invalid, unavailable, unsupported},
+    rotation::CredentialChange,
+};
+
+const CLAIM_TTL: Duration = Duration::from_secs(120);
+const MAX_STATE_BYTES: usize = 64 * 1024;
+
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct StoredLogin {
+    version: u32,
+    binding: String,
+    expires_at_ms: i64,
+    mutation: Map<String, Value>,
+    state: Map<String, Value>,
+}
+
+impl PluginProvider {
+    fn authorize_login(
+        &self,
+        pending: &PendingAuthorizationMutation,
+    ) -> Result<(), ProviderAdminError> {
+        if !self
+            .credential_operations
+            .contains(&CredentialOperation::Login)
+        {
+            return Err(unsupported());
+        }
+        if pending.provider_kind() != &self.kind {
+            return Err(invalid());
+        }
+        Ok(())
+    }
+
+    pub(super) async fn start_login(
+        &self,
+        command: PrepareAuthorization,
+    ) -> Result<AuthorizationStarted, ProviderAdminError> {
+        let PrepareAuthorization { pending, input } = command;
+        self.authorize_login(&pending)?;
+        self.validate_credential_input(CredentialOperation::Login, &input)?;
+        let login_input = input.into_provider_data().into_inner();
+        let (input, account) = match pending.target() {
+            AuthorizationMutationTarget::Create { name } => (
+                LoginStart {
+                    name: Some(name.clone()),
+                    account_id: None,
+                    input: login_input,
+                },
+                None,
+            ),
+            AuthorizationMutationTarget::Reauthorize { account_id } => {
+                let credential = self.load_management_credential(account_id).await?;
+                (
+                    LoginStart {
+                        name: None,
+                        account_id: Some(account_id.as_str().into()),
+                        input: login_input,
+                    },
+                    Some(credential.account),
+                )
+            }
+        };
+        let call = self.management_call(
+            ProviderOperation::Login,
+            account.as_ref(),
+            pending.outbound_proxy().cloned(),
+        )?;
+        let started: LoginStarted = call.invoke("provider.login.start", &input).await?;
+        let expires_at = chrono::DateTime::from_timestamp_millis(started.expires_at_ms)
+            .ok_or_else(|| call.invalid_result())?;
+        let ttl = (expires_at - Utc::now())
+            .to_std()
+            .map_err(|_| call.invalid_result())?;
+        let url = url::Url::parse(&started.authorization_url).map_err(|_| call.invalid_result())?;
+        if ttl.is_zero()
+            || ttl > Duration::from_secs(30 * 60)
+            || started.authorization_url.len() > 8192
+            || !matches!(url.scheme(), "http" | "https")
+            || url.host_str().is_none()
+            || !url.username().is_empty()
+            || url.password().is_some()
+            || serde_json::to_vec(&started.state)
+                .map_err(|_| call.invalid_result())?
+                .len()
+                > MAX_STATE_BYTES
+        {
+            return Err(call.invalid_result());
+        }
+        let flow_id = uuid::Uuid::new_v4().to_string();
+        let owner = owner_binding(pending.owner_binding())?;
+        let stored = StoredLogin {
+            version: 1,
+            binding: self.authorization_binding.clone(),
+            expires_at_ms: started.expires_at_ms,
+            mutation: pending.to_storage_v1(),
+            state: started.state,
+        };
+        let payload = serde_json::from_value(serde_json::to_value(stored).map_err(|_| invalid())?)
+            .map_err(|_| invalid())?;
+        let flow = NewOAuthPendingFlow::try_new(
+            self.kind.clone(),
+            binding(&flow_id)?,
+            owner,
+            ttl,
+            OpaqueProviderData::new(payload),
+        )
+        .map_err(|_| invalid())?;
+        if self
+            .ports
+            .oauth_pending()
+            .put_if_absent(flow)
+            .await
+            .inspect_err(|error| {
+                tracing::warn!(provider = self.kind.as_str(), error = ?error, "插件登录状态写入失败");
+            })
+            .map_err(|_| unavailable())?
+            != OAuthPendingPutOutcome::Stored
+        {
+            tracing::warn!(provider = self.kind.as_str(), "插件登录状态标识冲突");
+            return Err(unavailable());
+        }
+        Ok(AuthorizationStarted {
+            flow_id,
+            authorization_url: started.authorization_url,
+            expires_at,
+        })
+    }
+
+    pub(super) async fn poll_login(
+        &self,
+        command: PollAuthorization,
+    ) -> Result<PreparedAuthorizationPoll, ProviderAdminError> {
+        if !self
+            .credential_operations
+            .contains(&CredentialOperation::Login)
+        {
+            return Err(unsupported());
+        }
+        if command
+            .callback_url
+            .as_ref()
+            .is_some_and(|url| url.len() > 64 * 1024)
+        {
+            return Err(invalid());
+        }
+        let claim = Claim {
+            store: self.ports.oauth_pending(),
+            provider: self.kind.clone(),
+            flow: binding(&command.flow_id)?,
+            owner: owner_binding(&AuthorizationOwnerBinding::from_context(&command.context))?,
+            token: binding(&uuid::Uuid::new_v4().to_string())?,
+        };
+        let payload = match claim
+            .store
+            .claim_if_owner(
+                &claim.provider,
+                &claim.flow,
+                &claim.owner,
+                &claim.token,
+                CLAIM_TTL,
+            )
+            .await
+            .map_err(|_| unavailable())?
+        {
+            OAuthPendingClaimOutcome::Claimed(payload) => payload,
+            OAuthPendingClaimOutcome::NotFound => {
+                return Err(ProviderAdminError::new(ProviderAdminErrorKind::NotFound));
+            }
+            OAuthPendingClaimOutcome::OwnerMismatch => return Err(invalid()),
+            OAuthPendingClaimOutcome::InProgress => {
+                return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+            }
+        };
+        let guard = LoginGuard(Some(claim));
+        let result = self.poll_claimed(payload, &command).await;
+        match result {
+            Ok(PreparedAuthorizationPoll::Complete(prepared)) => {
+                Ok(PreparedAuthorizationPoll::Complete(Box::new(
+                    prepared.with_authorization_guard(Box::new(guard)),
+                )))
+            }
+            result => {
+                // Pending、验证失败和上游错误都显式释放；取消由 Drop 尽力回收，TTL 负责崩溃恢复。
+                Box::new(guard).abort().await.map_err(|_| unavailable())?;
+                result
+            }
+        }
+    }
+
+    async fn poll_claimed(
+        &self,
+        payload: OpaqueProviderData,
+        command: &PollAuthorization,
+    ) -> Result<PreparedAuthorizationPoll, ProviderAdminError> {
+        let stored: StoredLogin =
+            serde_json::from_value(Value::Object(payload.into_inner())).map_err(|_| invalid())?;
+        if stored.version != 1
+            || stored.binding != self.authorization_binding
+            || stored.expires_at_ms <= Utc::now().timestamp_millis()
+        {
+            return Err(invalid());
+        }
+        let pending = PendingAuthorizationMutation::from_storage_v1(Value::Object(stored.mutation))
+            .map_err(|_| invalid())?;
+        if !pending.owner_binding().matches_context(&command.context) {
+            return Err(invalid());
+        }
+        self.authorize_login(&pending)?;
+        let locked = match pending.target() {
+            AuthorizationMutationTarget::Create { .. } => None,
+            AuthorizationMutationTarget::Reauthorize { account_id } => {
+                Some(self.lock_credential(account_id).await?)
+            }
+        };
+        let call = self.management_call(
+            ProviderOperation::Login,
+            locked.as_ref().map(|(credential, _)| &credential.account),
+            pending.outbound_proxy().cloned(),
+        )?;
+        let reply: LoginPollResult = call
+            .invoke(
+                "provider.login.poll",
+                &LoginPoll {
+                    state: stored.state,
+                    callback_url: command.callback_url.clone(),
+                },
+            )
+            .await?;
+        if stored.expires_at_ms <= Utc::now().timestamp_millis() {
+            return Err(call.invalid_result());
+        }
+        let accounts = match reply {
+            LoginPollResult::Pending { retry_after_ms } => {
+                if retry_after_ms == 0 || retry_after_ms > 300_000 {
+                    return Err(call.invalid_result());
+                }
+                return Ok(PreparedAuthorizationPoll::Pending {
+                    retry_after: Duration::from_millis(retry_after_ms),
+                });
+            }
+            LoginPollResult::Complete { accounts } => accounts,
+        };
+        let credential = if let Some((current, guard)) = locked {
+            if accounts.len() != 1 {
+                return Err(call.invalid_result());
+            }
+            let facts = accounts
+                .into_iter()
+                .next()
+                .ok_or_else(|| call.invalid_result())?;
+            PreparedAuthorizationCredential::Reauthorize(Box::new(
+                self.prepare_changed_credential(
+                    current.account,
+                    facts,
+                    CredentialChange::Reauthorize,
+                    guard,
+                )
+                .map_err(|_| call.invalid_result())?,
+            ))
+        } else {
+            PreparedAuthorizationCredential::Create(
+                self.prepare_created_credentials(accounts, pending.outbound_proxy().cloned())
+                    .map_err(|_| call.invalid_result())?,
+            )
+        };
+        Ok(PreparedAuthorizationPoll::Complete(Box::new(
+            PreparedAuthorizationCommit::new(pending, credential),
+        )))
+    }
+}
+
+fn binding(value: &str) -> Result<OAuthPendingBinding, ProviderAdminError> {
+    OAuthPendingBinding::try_new(value).map_err(|_| invalid())
+}
+
+fn owner_binding(
+    owner: &AuthorizationOwnerBinding,
+) -> Result<OAuthPendingBinding, ProviderAdminError> {
+    binding(&match owner.owner() {
+        AuthorizationOwner::AdminSession { admin_user_id } => {
+            format!("admin_session:{admin_user_id}")
+        }
+        AuthorizationOwner::AdminApiKey => "admin_api_key".into(),
+        AuthorizationOwner::System => "system".into(),
+    })
+}
+
+struct Claim {
+    store: Arc<dyn OAuthPendingFlowPort>,
+    provider: ProviderKind,
+    flow: OAuthPendingBinding,
+    owner: OAuthPendingBinding,
+    token: OAuthPendingBinding,
+}
+
+impl Claim {
+    async fn release(&self) -> Result<(), AdminError> {
+        match self
+            .store
+            .release_claim(&self.provider, &self.flow, &self.owner, &self.token)
+            .await
+        {
+            Ok(OAuthPendingReleaseOutcome::Released | OAuthPendingReleaseOutcome::NotFound) => {
+                Ok(())
+            }
+            _ => Err(AdminError::unavailable("插件登录状态释放失败")),
+        }
+    }
+}
+
+struct LoginGuard(Option<Claim>);
+
+#[async_trait]
+impl AuthorizationCommitGuard for LoginGuard {
+    async fn commit(mut self: Box<Self>) -> Result<(), AdminError> {
+        let claim = self
+            .0
+            .take()
+            .ok_or_else(|| AdminError::internal("插件登录状态缺失"))?;
+        match claim
+            .store
+            .consume_claim(&claim.provider, &claim.flow, &claim.owner, &claim.token)
+            .await
+        {
+            Ok(OAuthPendingConsumeOutcome::Consumed) => Ok(()),
+            _ => Err(AdminError::unavailable("插件登录状态结算失败")),
+        }
+    }
+
+    async fn abort(mut self: Box<Self>) -> Result<(), AdminError> {
+        self.0
+            .take()
+            .ok_or_else(|| AdminError::internal("插件登录状态缺失"))?
+            .release()
+            .await
+    }
+}
+
+impl Drop for LoginGuard {
+    fn drop(&mut self) {
+        if let Some(claim) = self.0.take()
+            && let Ok(runtime) = tokio::runtime::Handle::try_current()
+        {
+            runtime.spawn(async move {
+                let _ = claim.release().await;
+            });
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/billing.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/billing.rs
new file mode 100644
index 000000000..9dfcfa150
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/billing.rs
@@ -0,0 +1,219 @@
+use std::collections::BTreeMap;
+
+use gateway_admin::model::{AdminError, pricing::ProviderPricingCatalog};
+use gateway_core::{
+    metering::{
+        CalculatedCost, CalculatedCostAmounts, CalculatedCostBreakdown, CalculatedCostRates,
+        CurrencyCode, Decimal, ModelPriceOverride, Money, TokenPriceOverride, Usage,
+    },
+    routing::UpstreamModelId,
+};
+use gateway_plugin_sdk::{
+    Capability, Manifest, Stage,
+    call::provider::billing::{BillingDescriptor, PriceBand},
+};
+
+pub(super) fn prepare(
+    descriptor: Option<BillingDescriptor>,
+    manifest: &Manifest,
+) -> Result<Option<ProviderPricingCatalog>, AdminError> {
+    let declaration = manifest.contributes.get(&Capability::Billing);
+    if declaration.is_some() != descriptor.is_some()
+        || declaration.is_some_and(|declaration| !declaration.stages.contains(&Stage::Execution))
+    {
+        return Err(AdminError::invalid("插件计价数据与能力声明不符"));
+    }
+    let Some(BillingDescriptor::TokenV1 { prices }) = descriptor else {
+        return Ok(None);
+    };
+    if prices.len() > 4096 {
+        return Err(AdminError::invalid("插件价目超过模型数量限制"));
+    }
+    let mut catalog = BTreeMap::new();
+    for (model, bands) in prices {
+        UpstreamModelId::new(model.clone())
+            .map_err(|_| AdminError::invalid("插件价目模型 ID 无效"))?;
+        if !bands.contains_key(&PriceBand::Standard) {
+            return Err(AdminError::invalid("插件价目必须包含完整标准档"));
+        }
+        let bands = bands
+            .into_iter()
+            .map(|(band, prices)| {
+                Ok((
+                    band_name(band).to_owned(),
+                    TokenPriceOverride {
+                        input: prices.input.try_into().map_err(AdminError::invalid)?,
+                        output: prices.output.try_into().map_err(AdminError::invalid)?,
+                        cache_read: prices.cache_read.try_into().map_err(AdminError::invalid)?,
+                        cache_write: prices.cache_write.try_into().map_err(AdminError::invalid)?,
+                    },
+                ))
+            })
+            .collect::<Result<_, AdminError>>()?;
+        catalog.insert(
+            model,
+            ModelPriceOverride {
+                multiplier_bps: 10_000,
+                bands,
+            },
+        );
+    }
+    Ok(Some(catalog))
+}
+
+/// 一次 attempt 只复制实际发送模型的价格；在途不读取新配置或新插件规则。
+pub(super) struct BillingPlan {
+    enabled: bool,
+    price: Option<ModelPriceOverride>,
+}
+
+impl BillingPlan {
+    pub(super) fn new(
+        defaults: Option<&ProviderPricingCatalog>,
+        model: Option<&str>,
+        overrides: Option<&ProviderPricingCatalog>,
+    ) -> Self {
+        let price = model.and_then(|model| {
+            let mut price = defaults.and_then(|prices| prices.get(model)).cloned();
+            if let Some(custom) = overrides.and_then(|prices| prices.get(model)) {
+                let price = price.get_or_insert_with(|| ModelPriceOverride {
+                    multiplier_bps: 10_000,
+                    bands: BTreeMap::new(),
+                });
+                price.multiplier_bps = custom.multiplier_bps;
+                price.bands.extend(custom.bands.clone());
+            }
+            price
+        });
+        Self {
+            enabled: defaults.is_some(),
+            price,
+        }
+    }
+
+    pub(super) fn enabled(&self) -> bool {
+        self.enabled
+    }
+
+    pub(super) fn calculate(&self, usage: &Usage, band: PriceBand) -> Option<CalculatedCost> {
+        let price = self.price.as_ref()?;
+        let long = matches!(
+            band,
+            PriceBand::LongStandard | PriceBand::LongFast | PriceBand::LongFlex
+        );
+        let standard = price
+            .bands
+            .get(if long { "long_standard" } else { "standard" })?;
+        let selected = price.bands.get(band_name(band))?;
+        // token_v1 明确分摊输入与缓存；缺少数量、不一致或存在单独图像计费时不能补零估算。
+        let input = usage.input_tokens?;
+        let output = usage.output_tokens?;
+        let read = usage.cached_tokens?;
+        let write = usage.cache_write_tokens?;
+        if usage.image_input_tokens.is_some_and(|count| count > 0)
+            || usage.image_output_tokens.is_some_and(|count| count > 0)
+        {
+            return None;
+        }
+        let uncached = input.checked_sub(read)?.checked_sub(write)?;
+        let amounts = token_amounts(selected, uncached, output, read, write)?;
+        let standard = token_amounts(standard, uncached, output, read, write)?.total()?;
+        let total = amounts.total()?;
+        let multiplier_percent = if standard == 0 {
+            100
+        } else {
+            u32::try_from(
+                total
+                    .checked_mul(100)?
+                    .checked_add(standard / 2)?
+                    .checked_div(standard)?,
+            )
+            .ok()?
+        };
+        let service_tier = match band {
+            PriceBand::Standard | PriceBand::LongStandard => "default",
+            PriceBand::Fast | PriceBand::LongFast => "priority",
+            PriceBand::Flex | PriceBand::LongFlex => "flex",
+        };
+        CalculatedCostBreakdown::new(
+            CalculatedCostAmounts::new(
+                money(amounts.input)?,
+                money(amounts.output)?,
+                money(amounts.read)?,
+                money(amounts.write)?,
+                money(standard)?,
+                money(total)?,
+            ),
+            CalculatedCostRates::new(
+                money(selected.input.ticks_per_token().checked_mul(1_000_000)?)?,
+                money(selected.output.ticks_per_token().checked_mul(1_000_000)?)?,
+                money(
+                    selected
+                        .cache_read
+                        .ticks_per_token()
+                        .checked_mul(1_000_000)?,
+                )?,
+                money(
+                    selected
+                        .cache_write
+                        .ticks_per_token()
+                        .checked_mul(1_000_000)?,
+                )?,
+            ),
+            Some(service_tier.into()),
+            multiplier_percent,
+        )
+        .with_long_context_billing(long)
+        .with_custom_multiplier(price.multiplier_bps)
+        .map(|breakdown| breakdown.calculated_cost())
+    }
+}
+
+struct TokenAmounts {
+    input: u128,
+    output: u128,
+    read: u128,
+    write: u128,
+}
+
+impl TokenAmounts {
+    fn total(&self) -> Option<u128> {
+        self.input
+            .checked_add(self.output)?
+            .checked_add(self.read)?
+            .checked_add(self.write)
+    }
+}
+
+fn token_amounts(
+    prices: &TokenPriceOverride,
+    input: u64,
+    output: u64,
+    read: u64,
+    write: u64,
+) -> Option<TokenAmounts> {
+    Some(TokenAmounts {
+        input: u128::from(input).checked_mul(prices.input.ticks_per_token())?,
+        output: u128::from(output).checked_mul(prices.output.ticks_per_token())?,
+        read: u128::from(read).checked_mul(prices.cache_read.ticks_per_token())?,
+        write: u128::from(write).checked_mul(prices.cache_write.ticks_per_token())?,
+    })
+}
+
+fn money(ticks: u128) -> Option<Money> {
+    Some(Money::new(
+        Decimal::from_scaled(ticks).ok()?,
+        CurrencyCode::new("USD").ok()?,
+    ))
+}
+
+fn band_name(band: PriceBand) -> &'static str {
+    match band {
+        PriceBand::Standard => "standard",
+        PriceBand::Fast => "fast",
+        PriceBand::Flex => "flex",
+        PriceBand::LongStandard => "long_standard",
+        PriceBand::LongFast => "long_fast",
+        PriceBand::LongFlex => "long_flex",
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/capabilities.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/capabilities.rs
new file mode 100644
index 000000000..9e7bc4f59
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/capabilities.rs
@@ -0,0 +1,111 @@
+//! 表单 schema 在准备代次时编译；调用时只校验当前代次的输入，不解析外部引用。
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use gateway_admin::{
+    model::{
+        AdminError,
+        provider_capabilities::{
+            AuthorizationCompletion, ProviderCredentialCapabilities, ProviderLoginCapability,
+        },
+        provider_credentials::ProviderDocument,
+    },
+    ports::provider::ProviderAdminError,
+};
+use gateway_plugin_sdk::call::auth::CredentialOperation;
+use serde_json::{Value, json};
+
+use super::{PluginProvider, administration::invalid};
+
+pub(super) struct CredentialInput {
+    schema: Value,
+    validator: jsonschema::Validator,
+}
+
+pub(super) fn prepare_inputs(
+    operations: &BTreeSet<CredentialOperation>,
+    mut schemas: BTreeMap<CredentialOperation, Value>,
+) -> Result<BTreeMap<CredentialOperation, CredentialInput>, AdminError> {
+    if schemas.keys().any(|operation| {
+        !operations.contains(operation)
+            || !matches!(
+                operation,
+                CredentialOperation::Import
+                    | CredentialOperation::Rotate
+                    | CredentialOperation::Login
+            )
+    }) {
+        return Err(AdminError::invalid("凭据表单只能描述已声明的输入操作"));
+    }
+    let mut inputs = BTreeMap::new();
+    for operation in operations.iter().copied().filter(|operation| {
+        matches!(
+            operation,
+            CredentialOperation::Import | CredentialOperation::Rotate | CredentialOperation::Login
+        )
+    }) {
+        let schema = schemas.remove(&operation).unwrap_or_else(|| {
+            json!({
+                "type": "object",
+                "additionalProperties": operation != CredentialOperation::Login,
+            })
+        });
+        if schema.get("type").and_then(Value::as_str) != Some("object")
+            || serde_json::to_vec(&schema).map_or(true, |encoded| encoded.len() > 64 * 1024)
+        {
+            return Err(AdminError::invalid(
+                "凭据表单 schema 必须描述对象且不超过 64 KiB",
+            ));
+        }
+        let validator = jsonschema::options()
+            .offline()
+            .with_pattern_options(jsonschema::PatternOptions::fancy_regex().backtrack_limit(20_000))
+            .build(&schema)
+            .map_err(|_| AdminError::invalid("凭据表单 schema 无效或引用外部资源"))?;
+        inputs.insert(operation, CredentialInput { schema, validator });
+    }
+    Ok(inputs)
+}
+
+impl PluginProvider {
+    pub(super) fn credential_capabilities(&self) -> ProviderCredentialCapabilities {
+        let schema = |operation| {
+            self.credential_inputs
+                .get(&operation)
+                .map(|input| input.schema.clone())
+        };
+        ProviderCredentialCapabilities {
+            import: schema(CredentialOperation::Import),
+            login: schema(CredentialOperation::Login).map(|input_schema| ProviderLoginCapability {
+                input_schema,
+                completion: AuthorizationCompletion::Poll,
+            }),
+            refresh: self
+                .credential_operations
+                .contains(&CredentialOperation::Refresh),
+            export: self
+                .credential_operations
+                .contains(&CredentialOperation::Export),
+        }
+    }
+
+    pub(super) fn validate_credential_input(
+        &self,
+        operation: CredentialOperation,
+        document: &ProviderDocument,
+    ) -> Result<(), ProviderAdminError> {
+        let input = self
+            .credential_inputs
+            .get(&operation)
+            .ok_or_else(super::administration::unsupported)?;
+        let value = Value::Object(document.expose_to_provider().expose_to_provider().clone());
+        if operation == CredentialOperation::Login
+            && serde_json::to_vec(&value).map_or(true, |encoded| encoded.len() > 64 * 1024)
+            || !input.validator.is_valid(&value)
+        {
+            // 校验错误可能携带输入值；仅返回稳定分类，不能把错误正文写入日志或响应。
+            return Err(invalid());
+        }
+        Ok(())
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/account.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/account.rs
new file mode 100644
index 000000000..8ac517a17
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/account.rs
@@ -0,0 +1,238 @@
+use super::super::management::ProviderOperation;
+use super::super::{
+    PluginProvider,
+    administration::{invalid, unavailable},
+    management::{ManagementOrigin, account_request},
+};
+use super::{
+    QUERY_TIMEOUT,
+    cache::{self, CachedModels},
+    descriptor,
+};
+use gateway_admin::{
+    model::provider_credentials::{ProviderModel, ProviderModels},
+    ports::provider::{ProviderAdminError, ProviderAdminErrorKind},
+};
+use gateway_core::account::{
+    CredentialState, LoadedCredential, ProviderAccount, ProviderAccountId,
+};
+use gateway_plugin_sdk::call::{auth::CredentialFacts, provider::models::AccountModels};
+use std::{sync::Arc, time::Duration};
+
+impl PluginProvider {
+    pub(in super::super) async fn account_models(
+        &self,
+        id: &ProviderAccountId,
+        refresh: bool,
+    ) -> Result<ProviderModels, ProviderAdminError> {
+        self.account_models_from(id, refresh, ManagementOrigin::Interactive)
+            .await
+    }
+
+    pub(in super::super) async fn account_models_from(
+        &self,
+        id: &ProviderAccountId,
+        refresh: bool,
+        origin: ManagementOrigin<'_>,
+    ) -> Result<ProviderModels, ProviderAdminError> {
+        let account = self
+            .ports
+            .accounts()
+            .get_account(id)
+            .await
+            .map_err(|_| unavailable())?
+            .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::NotFound))?;
+        if !self.catalog_account_allowed(&account) {
+            return Err(invalid());
+        }
+        let (models, observed_at) = if self.catalog.discovers_accounts() {
+            let result = self
+                .discover_account_models_from(
+                    &account,
+                    refresh,
+                    cache::Publication::Account,
+                    origin,
+                )
+                .await?;
+            (
+                self.catalog
+                    .for_account(&result.catalog)
+                    .into_values()
+                    .collect::<Vec<_>>(),
+                Some(result.observed_at),
+            )
+        } else {
+            (self.catalog.static_models.clone(), None)
+        };
+        Ok(ProviderModels {
+            models: models
+                .into_iter()
+                .map(|model| {
+                    let model = descriptor::compile(&model).map_err(|_| invalid())?;
+                    Ok(ProviderModel {
+                        id: model.upstream_model().clone(),
+                        name: model.upstream_model().as_str().to_owned(),
+                    })
+                })
+                .collect::<Result<_, ProviderAdminError>>()?,
+            observed_at,
+        })
+    }
+
+    pub(super) fn catalog_account_allowed(&self, account: &ProviderAccount) -> bool {
+        account.provider() == &self.kind
+    }
+
+    pub(super) async fn discover_account_models(
+        &self,
+        account: &ProviderAccount,
+        refresh: bool,
+        publication: cache::Publication,
+    ) -> Result<Arc<CachedModels>, ProviderAdminError> {
+        self.discover_account_models_from(
+            account,
+            refresh,
+            publication,
+            ManagementOrigin::Interactive,
+        )
+        .await
+    }
+
+    async fn discover_account_models_from(
+        &self,
+        account: &ProviderAccount,
+        refresh: bool,
+        publication: cache::Publication,
+        origin: ManagementOrigin<'_>,
+    ) -> Result<Arc<CachedModels>, ProviderAdminError> {
+        self.ensure_provider(account.provider())?;
+        let discovery = self.catalog.discovery.as_ref().ok_or_else(invalid)?;
+        if !refresh && let Some(cached) = self.catalog.cache.read(account) {
+            return Ok(cached);
+        }
+        let started = std::time::Instant::now();
+        let mut stage = "refresh_lock";
+        let query = async {
+            let lock = self.catalog.cache.refresh_lock(account)?;
+            let guard = lock.lock().await;
+            if !refresh && let Some(cached) = self.catalog.cache.read(account) {
+                return Ok(cached);
+            }
+            let account_invalidation_token = self.catalog.cache.account_invalidation_token();
+            stage = "credential";
+            let credential = self.load_management_credential(account.id()).await?;
+            if !cache::same_identity(account, &credential.account) {
+                return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+            }
+            let call = self.management_call_from(
+                ProviderOperation::Models,
+                Some(&credential.account),
+                credential.account.outbound_proxy().cloned(),
+                origin,
+            )?;
+            // 单飞锁按凭据版本区分；回调保存新凭据不会阻塞新版本的目录查询。
+            stage = "rpc";
+            let mut result: AccountModels = call
+                .invoke("provider.models", &account_request(&credential))
+                .await?;
+            stage = "validate";
+            descriptor::validate(&result.models).map_err(|_| call.invalid_result())?;
+            if self.catalog.for_account(&result).len() > 4096 {
+                return Err(call.invalid_result());
+            }
+            let prepared_facts = result.prepared_account_facts.take();
+            if let Some(facts) = prepared_facts
+                && !same_credential_facts(&credential, &facts)
+            {
+                // 写入前释放账号 single-flight；Store revision CAS 仍是写入权威。
+                drop(guard);
+                let saved = call
+                    .save_discovered_facts(&credential.account, facts)
+                    .await?;
+                self.catalog
+                    .invalidate(std::slice::from_ref(&saved.account_id));
+                self.invalidate_facts(std::slice::from_ref(&saved.account_id))
+                    .await;
+                let current = self
+                    .ports
+                    .accounts()
+                    .get_account(account.id())
+                    .await
+                    .map_err(|_| unavailable())?
+                    .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::Conflict))?;
+                if &saved.account_id != current.id()
+                    || saved.credential_revision.get() != current.revision().get()
+                    || current.provider() != credential.account.provider()
+                    || current.authentication_kind() != credential.account.authentication_kind()
+                    || current.upstream_user_id() != credential.account.upstream_user_id()
+                    || current.upstream_account_id() != credential.account.upstream_account_id()
+                    || current.outbound_proxy() != credential.account.outbound_proxy()
+                {
+                    return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+                }
+                // 本次模型结果由旧凭据查询得到，不能换绑到新 revision 后发布。
+                // 失效代次会让 Core 的稳定性重试重新使用已提交的凭据查询。
+                return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+            }
+            stage = "recheck_account";
+            let current = self
+                .ports
+                .accounts()
+                .get_account(account.id())
+                .await
+                .map_err(|_| unavailable())?;
+            let Some(current) = current else {
+                return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+            };
+            if !cache::same_identity(account, &current) {
+                return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+            }
+            stage = "publish";
+            self.catalog.cache.publish(
+                current,
+                result,
+                Duration::from_secs(u64::from(discovery.cache_ttl_seconds)),
+                account_invalidation_token,
+                publication,
+            )
+        };
+        let result = tokio::time::timeout(QUERY_TIMEOUT, query).await;
+        let timed_out = result.is_err();
+        result
+            .map_err(|_| unavailable())
+            .and_then(|result| result)
+            .inspect_err(|error| {
+                // 目录允许部分账号失败；在错误被合并前保留失败阶段，不记录模型正文或凭据。
+                tracing::warn!(
+                    provider = self.kind.as_str(),
+                    account_id = account.id().as_str(),
+                    stage,
+                    timed_out,
+                    elapsed_ms = started.elapsed().as_millis() as u64,
+                    kind = ?error.kind(),
+                    "插件账号模型查询失败"
+                );
+            })
+    }
+}
+
+fn same_credential_facts(credential: &LoadedCredential, facts: &CredentialFacts) -> bool {
+    let account = &credential.account;
+    account.credential_state() == CredentialState::Ready
+        && account.last_error_reason().is_none()
+        && account.last_error_message().is_none()
+        && facts.name == account.name()
+        && facts.authentication_kind == account.authentication_kind()
+        && &facts.material == credential.credential.expose_to_provider()
+        && facts.email.as_deref() == account.email()
+        && facts.upstream_user_id.as_deref() == account.upstream_user_id()
+        && facts.upstream_account_id.as_deref() == account.upstream_account_id()
+        && facts.plan_type.as_deref() == account.plan_type()
+        && facts.has_refresh_token == account.has_refresh_token()
+        && facts.access_token_expires_at_ms == timestamp_millis(account.access_token_expires_at())
+        && facts.next_refresh_at_ms == timestamp_millis(account.next_refresh_at())
+}
+
+fn timestamp_millis(value: Option<std::time::SystemTime>) -> Option<i64> {
+    value.map(|value| chrono::DateTime::<chrono::Utc>::from(value).timestamp_millis())
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/cache.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/cache.rs
new file mode 100644
index 000000000..f160c29c1
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/cache.rs
@@ -0,0 +1,280 @@
+use std::{
+    collections::BTreeMap,
+    sync::{Arc, Mutex, Weak},
+    time::Duration,
+};
+
+use chrono::{DateTime, Utc};
+use gateway_admin::ports::provider::{ProviderAdminError, ProviderAdminErrorKind};
+use gateway_core::{
+    account::{ProviderAccount, ProviderAccountId},
+    routing::ProviderCatalogGeneration,
+};
+use gateway_plugin_sdk::call::provider::{ModelDescriptor, models::AccountModels};
+use tokio::time::Instant;
+
+use super::super::administration::unavailable;
+
+const MAX_ENTRIES: usize = 256;
+const MAX_BYTES: usize = 8 * 1024 * 1024;
+const MAX_REFRESHES: usize = 64;
+
+type AccountRefreshLocks = BTreeMap<(ProviderAccountId, u64), Weak<tokio::sync::Mutex<()>>>;
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub(super) enum Publication {
+    Directory,
+    Account,
+}
+
+struct CachedDirectory {
+    models: Arc<BTreeMap<String, ModelDescriptor>>,
+    expires: Instant,
+    bytes: usize,
+}
+
+pub(super) struct CachedModels {
+    pub(super) account: ProviderAccount,
+    pub(super) catalog: AccountModels,
+    pub(super) observed_at: DateTime<Utc>,
+    expires: Instant,
+    bytes: usize,
+}
+
+#[derive(Default)]
+pub(super) struct CatalogCache {
+    state: Mutex<CacheState>,
+    refreshes: Mutex<AccountRefreshLocks>,
+    pub(super) directory_refresh: tokio::sync::Mutex<()>,
+}
+
+#[derive(Default)]
+struct CacheState {
+    generation: u64,
+    account_invalidation_token: u64,
+    directory_revision: u64,
+    entries: BTreeMap<ProviderAccountId, Arc<CachedModels>>,
+    directory: Option<CachedDirectory>,
+}
+
+impl CacheState {
+    fn expire(&mut self) {
+        self.entries
+            .retain(|_, value| value.expires > Instant::now());
+        // 账号缓存只是有限容量的查询加速器；淘汰不能让大账号目录永远无法稳定。
+        if self
+            .directory
+            .as_ref()
+            .is_some_and(|directory| directory.expires <= Instant::now())
+        {
+            self.invalidate_directory();
+        }
+    }
+
+    fn invalidate_directory(&mut self) {
+        self.directory = None;
+        self.directory_revision = self.directory_revision.saturating_add(1);
+        self.generation = self.generation.saturating_add(1);
+    }
+
+    fn reserve(&mut self, bytes: usize, maximum_entries: usize) -> Result<(), ProviderAdminError> {
+        while self.entries.len() > maximum_entries
+            || self
+                .entries
+                .values()
+                .map(|entry| entry.bytes)
+                .sum::<usize>()
+                + bytes
+                > MAX_BYTES
+        {
+            let Some(oldest) = self
+                .entries
+                .iter()
+                .min_by_key(|(_, entry)| entry.expires)
+                .map(|(id, _)| id.clone())
+            else {
+                return Err(unavailable());
+            };
+            self.entries.remove(&oldest);
+        }
+        Ok(())
+    }
+}
+
+impl CatalogCache {
+    pub(super) fn generation(&self) -> ProviderCatalogGeneration {
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        state.expire();
+        ProviderCatalogGeneration::new(state.generation)
+    }
+
+    pub(super) fn read(&self, account: &ProviderAccount) -> Option<Arc<CachedModels>> {
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        state.expire();
+        state
+            .entries
+            .get(account.id())
+            .filter(|entry| same_identity(&entry.account, account))
+            .cloned()
+    }
+
+    pub(super) fn invalidate(&self, accounts: &[ProviderAccountId]) {
+        if accounts.is_empty() {
+            return;
+        }
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        for account in accounts {
+            state.entries.remove(account);
+        }
+        // 即使缓存尚未写入，也要阻止正在查询的旧事实在失效之后重新发布。
+        state.account_invalidation_token = state.account_invalidation_token.saturating_add(1);
+        state.invalidate_directory();
+    }
+
+    pub(super) fn account_invalidation_token(&self) -> u64 {
+        self.state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .account_invalidation_token
+    }
+
+    pub(super) fn directory(&self) -> Option<Arc<BTreeMap<String, ModelDescriptor>>> {
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        state.expire();
+        state
+            .directory
+            .as_ref()
+            .map(|directory| Arc::clone(&directory.models))
+    }
+
+    pub(super) fn directory_revision(&self) -> u64 {
+        self.state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .directory_revision
+    }
+
+    pub(super) fn publish_directory(
+        &self,
+        models: BTreeMap<String, ModelDescriptor>,
+        ttl: Duration,
+        directory_revision: u64,
+    ) -> Result<Arc<BTreeMap<String, ModelDescriptor>>, ProviderAdminError> {
+        let bytes = serde_json::to_vec(&models)
+            .map_err(|_| unavailable())?
+            .len();
+        if bytes > MAX_BYTES {
+            return Err(unavailable());
+        }
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if state.directory_revision != directory_revision {
+            return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+        }
+        state.reserve(bytes, MAX_ENTRIES)?;
+        let models = Arc::new(models);
+        state.directory = Some(CachedDirectory {
+            models: Arc::clone(&models),
+            expires: Instant::now() + ttl,
+            bytes,
+        });
+        state.generation = state.generation.saturating_add(1);
+        Ok(models)
+    }
+
+    pub(super) fn refresh_lock(
+        &self,
+        account: &ProviderAccount,
+    ) -> Result<Arc<tokio::sync::Mutex<()>>, ProviderAdminError> {
+        let mut refreshes = self
+            .refreshes
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        refreshes.retain(|_, lock| lock.strong_count() > 0);
+        // 同一凭据版本合并查询；回调轮换凭据后，新版本不能等待仍在执行的旧 RPC。
+        let key = (account.id().clone(), account.revision().get());
+        if let Some(lock) = refreshes.get(&key).and_then(Weak::upgrade) {
+            return Ok(lock);
+        }
+        if refreshes.len() >= MAX_REFRESHES {
+            return Err(unavailable());
+        }
+        let lock = Arc::new(tokio::sync::Mutex::new(()));
+        refreshes.insert(key, Arc::downgrade(&lock));
+        Ok(lock)
+    }
+
+    pub(super) fn publish(
+        &self,
+        account: ProviderAccount,
+        catalog: AccountModels,
+        ttl: Duration,
+        account_invalidation_token: u64,
+        publication: Publication,
+    ) -> Result<Arc<CachedModels>, ProviderAdminError> {
+        let bytes = serde_json::to_vec(&catalog)
+            .map_err(|_| unavailable())?
+            .len();
+        if bytes > MAX_BYTES {
+            return Err(unavailable());
+        }
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        state.expire();
+        if state.account_invalidation_token != account_invalidation_token {
+            return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+        }
+        let unchanged = state.entries.get(account.id()).is_some_and(|entry| {
+            same_identity(&entry.account, &account) && entry.catalog == catalog
+        });
+        state.entries.remove(account.id());
+        if !unchanged && publication == Publication::Account {
+            // 管理刷新与客户端发现可改变正在准备的全局目录；拒绝覆盖这类并发新事实。
+            state.invalidate_directory();
+        }
+        // 以到期时间淘汰可重建目录，不保存凭据；单实例有独立的条目数和总字节预算。
+        let directory_bytes = state
+            .directory
+            .as_ref()
+            .map_or(0, |directory| directory.bytes);
+        state.reserve(bytes + directory_bytes, MAX_ENTRIES - 1)?;
+        let entry = Arc::new(CachedModels {
+            account,
+            catalog,
+            observed_at: Utc::now(),
+            expires: Instant::now() + ttl,
+            bytes,
+        });
+        state
+            .entries
+            .insert(entry.account.id().clone(), entry.clone());
+        Ok(entry)
+    }
+}
+
+pub(super) fn same_identity(left: &ProviderAccount, right: &ProviderAccount) -> bool {
+    left.id() == right.id()
+        && left.provider() == right.provider()
+        && left.revision() == right.revision()
+        && left.authentication_kind() == right.authentication_kind()
+        && left.upstream_user_id() == right.upstream_user_id()
+        && left.upstream_account_id() == right.upstream_account_id()
+        && left.plan_type() == right.plan_type()
+        && left.outbound_proxy() == right.outbound_proxy()
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/descriptor.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/descriptor.rs
new file mode 100644
index 000000000..86475a034
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/descriptor.rs
@@ -0,0 +1,100 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use gateway_admin::model::AdminError;
+use gateway_core::{
+    operation::{Feature, OperationKind},
+    routing::{ModelCapabilities, ProviderModelCapabilities, SupportLevel, UpstreamModelId},
+};
+use gateway_plugin_sdk::call::provider::{
+    ModelDescriptor, ModelFeature, OperationKind as WireOperation,
+};
+
+pub(super) fn validate(models: &[ModelDescriptor]) -> Result<(), AdminError> {
+    if models.len() > 4096 {
+        return Err(AdminError::invalid("插件模型目录超过 4096 项"));
+    }
+    let mut identities = BTreeSet::new();
+    for model in models {
+        UpstreamModelId::new(model.id.clone())
+            .map_err(|_| AdminError::invalid("插件模型 ID 无效"))?;
+        if !identities.insert(&model.id)
+            || model.operations.is_empty()
+            || model.operations.iter().collect::<BTreeSet<_>>().len() != model.operations.len()
+            || model
+                .operations
+                .iter()
+                .any(|operation| matches!(operation, WireOperation::ProviderHttp))
+            || model.features.iter().collect::<BTreeSet<_>>().len() != model.features.len()
+            || model.maximum_output_tokens == Some(0)
+        {
+            return Err(AdminError::invalid("插件模型能力重复、为空或上限无效"));
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn compile(model: &ModelDescriptor) -> Result<ProviderModelCapabilities, AdminError> {
+    let operations = model
+        .operations
+        .iter()
+        .map(|operation| match operation {
+            WireOperation::Generate => Ok(OperationKind::Generate),
+            WireOperation::GenerateImage => Ok(OperationKind::GenerateImage),
+            WireOperation::Search => Ok(OperationKind::Search),
+            WireOperation::CountTokens => Ok(OperationKind::CountTokens),
+            WireOperation::ProviderHttp => {
+                Err(AdminError::invalid("Provider HTTP 不能声明为模型操作"))
+            }
+        })
+        .collect::<Result<BTreeSet<_>, _>>()?;
+    let mut capabilities = ModelCapabilities::new(operations, model.maximum_output_tokens);
+    for feature in &model.features {
+        capabilities = capabilities.with_feature(
+            match feature {
+                ModelFeature::Tools => Feature::Tools,
+                ModelFeature::Vision => Feature::Vision,
+                ModelFeature::Reasoning => Feature::Reasoning,
+                ModelFeature::JsonSchema => Feature::JsonSchema,
+                ModelFeature::NativeContinuation => Feature::NativeContinuation,
+            },
+            SupportLevel::Native,
+        );
+    }
+    Ok(ProviderModelCapabilities::new(
+        UpstreamModelId::new(model.id.clone())
+            .map_err(|_| AdminError::invalid("插件模型 ID 无效"))?,
+        capabilities,
+    ))
+}
+
+/// 全局目录只合并可路由能力；实际选号必须再次匹配单个账号的完整声明。
+pub(super) fn union(
+    target: &mut BTreeMap<String, ModelDescriptor>,
+    models: impl IntoIterator<Item = ModelDescriptor>,
+) -> Result<(), AdminError> {
+    for model in models {
+        match target.entry(model.id.clone()) {
+            std::collections::btree_map::Entry::Vacant(entry) => {
+                entry.insert(model);
+            }
+            std::collections::btree_map::Entry::Occupied(mut entry) => {
+                let previous = entry.get_mut();
+                previous.operations.extend(model.operations);
+                previous.operations.sort();
+                previous.operations.dedup();
+                previous.features.extend(model.features);
+                previous.features.sort();
+                previous.features.dedup();
+                previous.maximum_output_tokens =
+                    match (previous.maximum_output_tokens, model.maximum_output_tokens) {
+                        (Some(left), Some(right)) => Some(left.max(right)),
+                        _ => None,
+                    };
+            }
+        }
+        if target.len() > 4096 {
+            return Err(AdminError::invalid("合并模型目录超过 4096 项"));
+        }
+    }
+    Ok(())
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/directory.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/directory.rs
new file mode 100644
index 000000000..21a94f9c9
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/directory.rs
@@ -0,0 +1,154 @@
+use super::super::PluginProvider;
+use super::{CATALOG_TIMEOUT, cache, catalog_error, descriptor};
+use futures::{StreamExt as _, stream};
+use gateway_core::{
+    account::AccountStatus, error::ProviderError, routing::ProviderModelCapabilities,
+};
+use gateway_plugin_sdk::call::provider::ModelDescriptor;
+use std::{
+    collections::BTreeMap,
+    sync::Arc,
+    time::{Duration, SystemTime},
+};
+
+impl PluginProvider {
+    pub(in super::super) async fn discover_model_capabilities(
+        &self,
+    ) -> Result<Vec<ProviderModelCapabilities>, ProviderError> {
+        let query = async {
+            if let Some(models) = self.catalog.cache.directory() {
+                return Ok(models);
+            }
+            let _guard = self.catalog.cache.directory_refresh.lock().await;
+            if let Some(models) = self.catalog.cache.directory() {
+                return Ok(models);
+            }
+            let directory_revision = self.catalog.cache.directory_revision();
+            let models = self.discover_model_catalog(None).await?;
+            if let Some(discovery) = &self.catalog.discovery {
+                self.catalog
+                    .cache
+                    .publish_directory(
+                        models,
+                        Duration::from_secs(u64::from(discovery.cache_ttl_seconds)),
+                        directory_revision,
+                    )
+                    .map_err(|_| catalog_error())
+            } else {
+                Ok(Arc::new(models))
+            }
+        };
+        tokio::time::timeout(CATALOG_TIMEOUT, query)
+            .await
+            .map_err(|_| catalog_error())??
+            .values()
+            .map(|model| descriptor::compile(model).map_err(|_| catalog_error()))
+            .collect()
+    }
+
+    pub(in super::super) async fn discover_client_catalog(
+        &self,
+        scope: &gateway_core::account::scope::FrozenAccountScope,
+    ) -> Result<
+        Vec<gateway_core::routing::ProviderModelDescriptor>,
+        gateway_core::routing::ProviderCatalogUnavailable,
+    > {
+        use gateway_core::routing::{
+            ModelPresentation, ProviderCatalogUnavailable, ProviderModelContent,
+            ProviderModelDescriptor, UpstreamModelId,
+        };
+        use gateway_plugin_sdk::call::provider::ModelFeature;
+        self.discover_model_catalog(Some(scope))
+            .await
+            .map_err(|_| ProviderCatalogUnavailable)?
+            .into_values()
+            .map(|model| {
+                Ok(ProviderModelDescriptor {
+                    model: UpstreamModelId::new(model.id.clone())
+                        .map_err(|_| ProviderCatalogUnavailable)?,
+                    content: ProviderModelContent::Adapted(
+                        ModelPresentation::new(Some(model.id), None)
+                            .with_image_input(model.features.contains(&ModelFeature::Vision))
+                            .with_agent_tools(model.features.contains(&ModelFeature::Tools), false),
+                    ),
+                })
+            })
+            .collect()
+    }
+
+    async fn discover_model_catalog(
+        &self,
+        scope: Option<&gateway_core::account::scope::FrozenAccountScope>,
+    ) -> Result<BTreeMap<String, ModelDescriptor>, ProviderError> {
+        let query = async {
+            let mut models = BTreeMap::new();
+            if scope.is_none() {
+                descriptor::union(&mut models, self.catalog.static_models.clone())
+                    .map_err(|_| catalog_error())?;
+            }
+            if self.catalog.discovers_accounts() {
+                let mut accounts = self
+                    .ports
+                    .accounts()
+                    .list_for_provider(&self.kind)
+                    .await
+                    .map_err(|_| catalog_error())?;
+                accounts.retain(|account| {
+                    matches!(
+                        account.status_projection(SystemTime::now(), None).status,
+                        AccountStatus::Normal | AccountStatus::QuotaExhausted
+                    ) && self.catalog_account_allowed(account)
+                        && scope.is_none_or(|scope| scope.allows(account.id()))
+                });
+                if accounts.len() > 4096 {
+                    return Err(catalog_error());
+                }
+                accounts.sort_by(|left, right| left.id().cmp(right.id()));
+                let mut results = stream::iter(accounts)
+                    .map(|account| async move {
+                        self.discover_account_models(
+                            &account,
+                            false,
+                            if scope.is_none() {
+                                cache::Publication::Directory
+                            } else {
+                                cache::Publication::Account
+                            },
+                        )
+                        .await
+                    })
+                    .buffered(4);
+                let mut failed = false;
+                let mut succeeded = false;
+                while let Some(result) = results.next().await {
+                    match result {
+                        Ok(result) => {
+                            succeeded = true;
+                            descriptor::union(
+                                &mut models,
+                                self.catalog
+                                    .for_account(&result.catalog)
+                                    .into_values()
+                                    .filter(|model| {
+                                        scope.is_none_or(|scope| {
+                                            scope.allows_model(result.account.id(), &model.id)
+                                        })
+                                    }),
+                            )
+                            .map_err(|_| catalog_error())?;
+                        }
+                        Err(_) => failed = true,
+                    }
+                }
+                // 空目录和所有账号读取失败是不同事实，不能把故障解释成没有模型。
+                if failed && !succeeded && models.is_empty() {
+                    return Err(catalog_error());
+                }
+            }
+            Ok(models)
+        };
+        tokio::time::timeout(CATALOG_TIMEOUT, query)
+            .await
+            .map_err(|_| catalog_error())?
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/mod.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/mod.rs
new file mode 100644
index 000000000..429bfda28
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/mod.rs
@@ -0,0 +1,116 @@
+mod account;
+mod cache;
+mod descriptor;
+mod directory;
+mod selection;
+
+use cache::CatalogCache;
+use gateway_admin::model::AdminError;
+use gateway_core::{
+    account::ProviderAccountId,
+    error::{ProviderError, ProviderErrorKind},
+    routing::ProviderCatalogGeneration,
+    upstream::UpstreamSendState,
+};
+use gateway_plugin_sdk::{
+    Capability, Manifest, Stage,
+    call::provider::{
+        ModelDescriptor,
+        models::{AccountModels, ModelDiscovery},
+    },
+};
+use std::{collections::BTreeMap, time::Duration};
+
+const QUERY_TIMEOUT: Duration = Duration::from_secs(10);
+const CATALOG_TIMEOUT: Duration = Duration::from_secs(20);
+
+pub(super) struct ModelCatalog {
+    static_models: Vec<ModelDescriptor>,
+    discovery: Option<ModelDiscovery>,
+    cache: CatalogCache,
+}
+
+impl ModelCatalog {
+    pub(super) fn prepare(
+        models: Vec<ModelDescriptor>,
+        discovery: Option<ModelDiscovery>,
+        manifest: &Manifest,
+    ) -> Result<Self, AdminError> {
+        descriptor::validate(&models)?;
+        if let Some(discovery) = &discovery
+            && (!(1..=3600).contains(&discovery.cache_ttl_seconds)
+                || (!discovery.include_static && !models.is_empty())
+                || !manifest
+                    .contributes
+                    .get(&Capability::Models)
+                    .is_some_and(|declaration| declaration.stages.contains(&Stage::Management)))
+        {
+            return Err(AdminError::invalid(
+                "账号模型发现需要有效缓存时长及 models/management 声明",
+            ));
+        }
+        Ok(Self {
+            static_models: models,
+            discovery,
+            cache: CatalogCache::default(),
+        })
+    }
+
+    pub(super) fn generation(&self) -> ProviderCatalogGeneration {
+        self.cache.generation()
+    }
+
+    pub(super) fn discovers_accounts(&self) -> bool {
+        self.discovery.is_some()
+    }
+
+    pub(super) fn invalidate(&self, accounts: &[ProviderAccountId]) {
+        self.cache.invalidate(accounts);
+    }
+
+    fn for_account(&self, discovered: &AccountModels) -> BTreeMap<String, ModelDescriptor> {
+        let mut models: BTreeMap<_, _> = if self
+            .discovery
+            .as_ref()
+            .is_some_and(|discovery| discovery.include_static)
+        {
+            self.static_models
+                .iter()
+                .map(|model| (model.id.clone(), model.clone()))
+                .collect()
+        } else {
+            BTreeMap::new()
+        };
+        models.extend(
+            discovered
+                .models
+                .iter()
+                .map(|model| (model.id.clone(), model.clone())),
+        );
+        models
+    }
+
+    fn account_model<'a>(
+        &'a self,
+        discovered: &'a AccountModels,
+        id: &str,
+    ) -> Option<&'a ModelDescriptor> {
+        discovered
+            .models
+            .iter()
+            .find(|model| model.id == id)
+            .or_else(|| {
+                self.discovery
+                    .as_ref()
+                    .filter(|discovery| discovery.include_static)
+                    .and_then(|_| self.static_models.iter().find(|model| model.id == id))
+            })
+    }
+}
+
+fn catalog_error() -> ProviderError {
+    ProviderError::new(
+        ProviderErrorKind::ProviderInfrastructureUnavailable,
+        UpstreamSendState::NotSent,
+    )
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/selection.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/selection.rs
new file mode 100644
index 000000000..1ee13231b
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/catalog/selection.rs
@@ -0,0 +1,72 @@
+use super::super::{PluginProvider, administration::invalid};
+use super::{cache, catalog_error, descriptor};
+use futures::{StreamExt as _, stream};
+use gateway_admin::ports::provider::ProviderAdminError;
+use gateway_core::{
+    account::{AccountStatus, ProviderAccount},
+    engine::AttemptContext,
+    error::{ProviderError, ProviderErrorKind},
+    operation::CapabilityRequirements,
+    upstream::UpstreamSendState,
+};
+use std::time::SystemTime;
+
+impl PluginProvider {
+    pub(in super::super) async fn filter_model_accounts(
+        &self,
+        accounts: Vec<ProviderAccount>,
+        model: Option<&str>,
+        requirements: &CapabilityRequirements,
+        context: &AttemptContext,
+    ) -> Result<Vec<ProviderAccount>, ProviderError> {
+        let Some(model) = model.filter(|_| self.catalog.discovers_accounts()) else {
+            return Ok(accounts);
+        };
+        let remaining = context
+            .deadline()
+            .duration_since(SystemTime::now())
+            .map_err(|_| {
+                ProviderError::new(ProviderErrorKind::Timeout, UpstreamSendState::NotSent)
+            })?;
+        let query = async {
+            let mut results = stream::iter(accounts.into_iter().filter(|account| {
+                context.is_diagnostic_required_account()
+                    || account.status_projection(SystemTime::now(), None).status
+                        == AccountStatus::Normal
+            }))
+            .map(|account| async move {
+                let catalog = self
+                    .discover_account_models(&account, false, cache::Publication::Account)
+                    .await?;
+                let allowed = match self.catalog.account_model(&catalog.catalog, model) {
+                    Some(model) => descriptor::compile(model)
+                        .map_err(|_| invalid())?
+                        .capabilities()
+                        .match_requirements(requirements)
+                        .is_some(),
+                    None => !catalog.catalog.exhaustive,
+                };
+                Ok::<_, ProviderAdminError>(allowed.then_some(account))
+            })
+            .buffered(4);
+            let mut eligible = Vec::new();
+            let mut failed = false;
+            while let Some(result) = results.next().await {
+                match result {
+                    Ok(Some(account)) => eligible.push(account),
+                    Ok(None) => {}
+                    Err(_) => failed = true,
+                }
+            }
+            if failed && eligible.is_empty() {
+                return Err(catalog_error());
+            }
+            Ok(eligible)
+        };
+        tokio::select! {
+            biased;
+            _ = context.cancellation().cancelled() => Err(ProviderError::new(ProviderErrorKind::Cancelled, UpstreamSendState::NotSent)),
+            result = tokio::time::timeout(remaining, query) => result.map_err(|_| ProviderError::new(ProviderErrorKind::Timeout, UpstreamSendState::NotSent))?,
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/configuration.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/configuration.rs
new file mode 100644
index 000000000..3f981eba4
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/configuration.rs
@@ -0,0 +1,220 @@
+//! 账号连接设置只读投影；凭据原文仅进入获授权的插件调用，响应只接受声明字段。
+
+use std::{collections::BTreeSet, time::Duration};
+
+use gateway_admin::{
+    model::{AdminError, provider_credentials::ProviderDocument},
+    ports::provider::{ProviderAdminError, ProviderAdminErrorKind},
+};
+use gateway_core::{account::OpaqueProviderData, account::ProviderAccountId};
+use gateway_plugin_sdk::{
+    Stage,
+    call::{
+        auth::CredentialOperation,
+        provider::account::{AccountConfiguration, AccountConfigurationDescriptor},
+    },
+};
+use serde_json::{Map, Value, json};
+
+use super::{
+    PluginProvider,
+    administration::invalid,
+    management::{account_request, map_read_error},
+};
+
+const MAXIMUM_PUBLIC_FIELDS: usize = 64;
+const MAXIMUM_FIELD_BYTES: usize = 128;
+const MAXIMUM_CONFIGURATION_BYTES: usize = 64 * 1024;
+const INDIRECT_OR_DYNAMIC_SCHEMA_KEYS: [&str; 16] = [
+    "$ref",
+    "$dynamicRef",
+    "$recursiveRef",
+    "allOf",
+    "anyOf",
+    "oneOf",
+    "not",
+    "if",
+    "then",
+    "else",
+    "dependentSchemas",
+    "dependencies",
+    "patternProperties",
+    "unevaluatedProperties",
+    "unevaluatedItems",
+    "contentSchema",
+];
+
+pub(super) struct PreparedAccountConfiguration {
+    public_fields: BTreeSet<String>,
+    validator: jsonschema::Validator,
+}
+
+impl PreparedAccountConfiguration {
+    pub(super) fn prepare(
+        descriptor: Option<AccountConfigurationDescriptor>,
+        credential_operations: &BTreeSet<CredentialOperation>,
+        rotate_schema: Option<&Value>,
+    ) -> Result<Option<Self>, AdminError> {
+        let Some(descriptor) = descriptor else {
+            return Ok(None);
+        };
+        if !credential_operations.contains(&CredentialOperation::Rotate)
+            || descriptor.public_fields.is_empty()
+            || descriptor.public_fields.len() > MAXIMUM_PUBLIC_FIELDS
+        {
+            return Err(AdminError::invalid(
+                "账号连接设置必须绑定已声明的凭据轮换操作",
+            ));
+        }
+        let field_count = descriptor.public_fields.len();
+        let public_fields = descriptor
+            .public_fields
+            .into_iter()
+            .collect::<BTreeSet<_>>();
+        if public_fields.len() != field_count
+            || public_fields.iter().any(|field| {
+                field.is_empty()
+                    || field.len() > MAXIMUM_FIELD_BYTES
+                    || field.chars().any(char::is_control)
+            })
+        {
+            return Err(AdminError::invalid("账号连接设置公开字段无效或重复"));
+        }
+        let rotate_schema = rotate_schema
+            .filter(|schema| safe_configuration_root(schema))
+            .ok_or_else(|| AdminError::invalid("账号连接设置需要显式安全的轮换 schema"))?;
+        let properties = rotate_schema
+            .get("properties")
+            .and_then(Value::as_object)
+            .ok_or_else(|| AdminError::invalid("账号连接设置需要显式的轮换字段 schema"))?;
+        let mut projected = Map::new();
+        for field in &public_fields {
+            let schema = properties
+                .get(field)
+                .filter(|schema| safe_public_property(schema))
+                .ok_or_else(|| AdminError::invalid("账号连接设置公开字段 schema 不安全"))?;
+            projected.insert(field.clone(), schema.clone());
+        }
+        let schema = json!({
+            "type": "object",
+            "properties": projected,
+            "additionalProperties": false,
+        });
+        let validator = jsonschema::options()
+            .offline()
+            .with_pattern_options(jsonschema::PatternOptions::fancy_regex().backtrack_limit(20_000))
+            .build(&schema)
+            .map_err(|_| AdminError::invalid("账号连接设置公开字段 schema 无效"))?;
+        Ok(Some(Self {
+            public_fields,
+            validator,
+        }))
+    }
+
+    fn validate(&self, values: &Map<String, Value>) -> bool {
+        values
+            .keys()
+            .all(|field| self.public_fields.contains(field))
+            && serde_json::to_vec(values)
+                .is_ok_and(|encoded| encoded.len() <= MAXIMUM_CONFIGURATION_BYTES)
+            && self.validator.is_valid(&Value::Object(values.clone()))
+    }
+}
+
+impl PluginProvider {
+    pub(super) async fn connection_configuration(
+        &self,
+        id: &ProviderAccountId,
+    ) -> Result<Option<ProviderDocument>, ProviderAdminError> {
+        let Some(projection) = &self.account_configuration else {
+            return Ok(None);
+        };
+        let credential = self.load_management_credential(id).await?;
+        if credential.account.id() != id || credential.account.provider() != &self.kind {
+            return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+        }
+        let mut context = self
+            .session
+            .context(Stage::Configuration, Duration::from_secs(5));
+        context.account_id = Some(id.as_str().to_owned());
+        context.credential_revision = Some(credential.account.revision().get());
+        let payload = serde_json::to_vec(&account_request(&credential)).map_err(|_| invalid())?;
+        let reply = self
+            .session
+            .call(
+                "provider.account_configuration",
+                context,
+                serde_json::json!({}),
+                payload,
+            )
+            .await
+            .map_err(map_read_error)?;
+        if reply.result != serde_json::json!({}) {
+            return Err(ProviderAdminError::new(ProviderAdminErrorKind::BadGateway));
+        }
+        let result: AccountConfiguration = serde_json::from_slice(&reply.payload)
+            .map_err(|_| ProviderAdminError::new(ProviderAdminErrorKind::BadGateway))?;
+        if !projection.validate(&result.values) {
+            return Err(ProviderAdminError::new(ProviderAdminErrorKind::BadGateway));
+        }
+        self.ensure_management_identity(&credential.account).await?;
+        Ok(Some(ProviderDocument::new(OpaqueProviderData::new(
+            result.values,
+        ))))
+    }
+}
+
+fn safe_public_property(schema: &Value) -> bool {
+    let Some(object) = schema.as_object() else {
+        return false;
+    };
+    let scalar_type = object.get("type").and_then(Value::as_str);
+    if !matches!(
+        scalar_type,
+        Some("string" | "number" | "integer" | "boolean")
+    ) || object.get("writeOnly") == Some(&Value::Bool(true))
+        || object.get("readOnly") == Some(&Value::Bool(true))
+        || object.get("format").and_then(Value::as_str) == Some("password")
+    {
+        return false;
+    }
+    !contains_key_recursive(schema, &INDIRECT_OR_DYNAMIC_SCHEMA_KEYS)
+        && !contains_sensitive_marker_recursive(schema)
+}
+
+fn safe_configuration_root(schema: &Value) -> bool {
+    let Some(object) = schema.as_object() else {
+        return false;
+    };
+    object.get("type").and_then(Value::as_str) == Some("object")
+        && object.get("writeOnly") != Some(&Value::Bool(true))
+        && object.get("readOnly") != Some(&Value::Bool(true))
+        && object.get("format").and_then(Value::as_str) != Some("password")
+        && !INDIRECT_OR_DYNAMIC_SCHEMA_KEYS
+            .iter()
+            .any(|key| object.contains_key(*key))
+}
+
+fn contains_key_recursive(value: &Value, keys: &[&str]) -> bool {
+    match value {
+        Value::Object(object) => object.iter().any(|(key, value)| {
+            keys.contains(&key.as_str()) || contains_key_recursive(value, keys)
+        }),
+        Value::Array(values) => values
+            .iter()
+            .any(|value| contains_key_recursive(value, keys)),
+        _ => false,
+    }
+}
+
+fn contains_sensitive_marker_recursive(value: &Value) -> bool {
+    match value {
+        Value::Object(object) => {
+            object.get("writeOnly") == Some(&Value::Bool(true))
+                || object.get("format").and_then(Value::as_str) == Some("password")
+                || object.values().any(contains_sensitive_marker_recursive)
+        }
+        Value::Array(values) => values.iter().any(contains_sensitive_marker_recursive),
+        _ => false,
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/continuation.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/continuation.rs
new file mode 100644
index 000000000..adc1d15e0
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/continuation.rs
@@ -0,0 +1,289 @@
+use std::{
+    collections::BTreeSet,
+    sync::{
+        Arc,
+        atomic::{AtomicBool, Ordering},
+    },
+};
+
+use gateway_admin::model::AdminError;
+use gateway_core::{
+    error::{
+        ContinuationFailure, ContinuationRecoveryDisposition, ProviderError, ProviderErrorKind,
+    },
+    operation::ProviderSessionState,
+    upstream::UpstreamSendState,
+};
+use gateway_plugin_sdk::call::provider::{ContinuationStateDescriptor, SessionUpdate};
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+
+const MAX_PAYLOAD_BYTES: usize = 64 * 1024;
+const MAX_FORMAT_BYTES: usize = 64;
+const MAX_READABLE_VERSIONS: usize = 32;
+
+#[derive(Clone)]
+pub(super) struct PreparedContinuationState {
+    format: String,
+    write_version: u32,
+    readable_versions: BTreeSet<u32>,
+}
+
+impl PreparedContinuationState {
+    pub(super) fn prepare(
+        descriptor: Option<ContinuationStateDescriptor>,
+    ) -> Result<Option<Self>, AdminError> {
+        let Some(descriptor) = descriptor else {
+            return Ok(None);
+        };
+        let format_is_valid = !descriptor.format.is_empty()
+            && descriptor.format.len() <= MAX_FORMAT_BYTES
+            && descriptor.format != "."
+            && descriptor.format != ".."
+            && descriptor
+                .format
+                .bytes()
+                .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.'));
+        let readable_versions = descriptor
+            .readable_versions
+            .iter()
+            .copied()
+            .collect::<BTreeSet<_>>();
+        if !format_is_valid
+            || descriptor.write_version == 0
+            || descriptor.readable_versions.is_empty()
+            || descriptor.readable_versions.len() > MAX_READABLE_VERSIONS
+            || readable_versions.len() != descriptor.readable_versions.len()
+            || readable_versions.contains(&0)
+            || !readable_versions.contains(&descriptor.write_version)
+        {
+            return Err(AdminError::invalid("插件续写状态兼容声明无效"));
+        }
+        Ok(Some(Self {
+            format: descriptor.format,
+            write_version: descriptor.write_version,
+            readable_versions,
+        }))
+    }
+
+    fn accepts(&self, state: &StoredContinuationState) -> bool {
+        self.format == state.format && self.readable_versions.contains(&state.version)
+    }
+
+    fn stored(&self) -> StoredContinuationState {
+        StoredContinuationState {
+            format: self.format.clone(),
+            version: self.write_version,
+        }
+    }
+}
+
+#[derive(Clone)]
+pub(super) struct ContinuationIdentity {
+    provider: String,
+    authorization: String,
+    continuation_authorization: String,
+    continuation_state: Option<PreparedContinuationState>,
+    pub(super) owner: String,
+    pub(super) issued: Arc<AtomicBool>,
+}
+
+pub(super) enum InterpreterTarget {
+    Current { previous_owner: Option<String> },
+    Retired { owner: String },
+}
+
+/// 绑定来自已选择的账号与已发布实例，插件只能提供 opaque payload。
+#[derive(Clone)]
+pub(super) struct SessionBinding {
+    identity: ContinuationIdentity,
+    account_id: String,
+    credential_revision: u64,
+}
+
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct StoredSessionBinding {
+    provider: String,
+    account_id: String,
+    credential_revision: u64,
+    authorization: String,
+    continuation_authorization: String,
+    execution_owner: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    continuation_state: Option<StoredContinuationState>,
+}
+
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct StoredContinuationState {
+    format: String,
+    version: u32,
+}
+
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Checkpoint {
+    binding: StoredSessionBinding,
+    payload: Map<String, Value>,
+}
+
+impl ContinuationIdentity {
+    pub(super) fn prepare(
+        provider: String,
+        authorization: String,
+        continuation_authorization: String,
+        descriptor: Option<ContinuationStateDescriptor>,
+        owner: String,
+    ) -> Result<Self, AdminError> {
+        Ok(Self {
+            provider,
+            authorization,
+            continuation_authorization,
+            continuation_state: PreparedContinuationState::prepare(descriptor)?,
+            owner,
+            issued: Arc::new(AtomicBool::new(false)),
+        })
+    }
+
+    pub(super) fn interpreter_target(
+        &self,
+        state: Option<&ProviderSessionState>,
+    ) -> Result<InterpreterTarget, ProviderError> {
+        let Some(state) = state else {
+            return Ok(InterpreterTarget::Current {
+                previous_owner: None,
+            });
+        };
+        let checkpoint = parse_checkpoint(state)?;
+        if state.provider() != self.provider
+            || checkpoint.binding.provider != self.provider
+            || checkpoint.binding.continuation_authorization != self.continuation_authorization
+            || !valid_owner(&checkpoint.binding.execution_owner)
+            || !bounded(state.payload())
+        {
+            return Err(invalid_checkpoint());
+        }
+        if self.can_interpret(&checkpoint.binding) {
+            return Ok(InterpreterTarget::Current {
+                previous_owner: (checkpoint.binding.execution_owner != self.owner)
+                    .then_some(checkpoint.binding.execution_owner),
+            });
+        }
+        if checkpoint.binding.execution_owner == self.owner {
+            return Err(invalid_checkpoint());
+        }
+        Ok(InterpreterTarget::Retired {
+            owner: checkpoint.binding.execution_owner,
+        })
+    }
+
+    pub(super) fn bind_account(
+        &self,
+        account_id: String,
+        credential_revision: u64,
+    ) -> SessionBinding {
+        SessionBinding {
+            identity: self.clone(),
+            account_id,
+            credential_revision,
+        }
+    }
+
+    pub(super) fn matches_authority(&self, other: &Self) -> bool {
+        self.provider == other.provider
+            && self.continuation_authorization == other.continuation_authorization
+    }
+
+    fn can_interpret(&self, stored: &StoredSessionBinding) -> bool {
+        match (&self.continuation_state, &stored.continuation_state) {
+            (None, None) => self.authorization == stored.authorization,
+            (Some(current), Some(stored)) => current.accepts(stored),
+            _ => false,
+        }
+    }
+}
+
+impl SessionBinding {
+    pub(super) fn restore(
+        &self,
+        state: Option<&ProviderSessionState>,
+    ) -> Result<Option<Map<String, Value>>, ProviderError> {
+        let Some(state) = state else {
+            return Ok(None);
+        };
+        let checkpoint = parse_checkpoint(state)?;
+        if state.provider() != self.identity.provider
+            || checkpoint.binding.provider != self.identity.provider
+            || self.account_id != checkpoint.binding.account_id
+            || self.credential_revision != checkpoint.binding.credential_revision
+            || self.identity.continuation_authorization
+                != checkpoint.binding.continuation_authorization
+            || !self.identity.can_interpret(&checkpoint.binding)
+            || !valid_owner(&checkpoint.binding.execution_owner)
+            || !bounded(state.payload())
+        {
+            return Err(invalid_checkpoint());
+        }
+        Ok(Some(checkpoint.payload))
+    }
+
+    pub(super) fn capture(
+        &self,
+        update: SessionUpdate,
+    ) -> Result<ProviderSessionState, ProviderError> {
+        let Value::Object(payload) = serde_json::to_value(Checkpoint {
+            binding: self.stored(),
+            payload: update.payload,
+        })
+        .map_err(|_| super::execution::stream_protocol_error())?
+        else {
+            return Err(super::execution::stream_protocol_error());
+        };
+        if !bounded(&payload) {
+            return Err(super::execution::stream_protocol_error());
+        }
+        let state = ProviderSessionState::new(self.identity.provider.clone(), payload)
+            .map_err(|_| super::execution::stream_protocol_error())?;
+        self.identity.issued.store(true, Ordering::Release);
+        Ok(state)
+    }
+
+    fn stored(&self) -> StoredSessionBinding {
+        StoredSessionBinding {
+            provider: self.identity.provider.clone(),
+            account_id: self.account_id.clone(),
+            credential_revision: self.credential_revision,
+            authorization: self.identity.authorization.clone(),
+            continuation_authorization: self.identity.continuation_authorization.clone(),
+            execution_owner: self.identity.owner.clone(),
+            continuation_state: self
+                .identity
+                .continuation_state
+                .as_ref()
+                .map(PreparedContinuationState::stored),
+        }
+    }
+}
+
+fn parse_checkpoint(state: &ProviderSessionState) -> Result<Checkpoint, ProviderError> {
+    serde_json::from_value(Value::Object(state.payload().clone())).map_err(|_| invalid_checkpoint())
+}
+
+fn valid_owner(owner: &str) -> bool {
+    uuid::Uuid::parse_str(owner).is_ok()
+}
+
+fn bounded(payload: &Map<String, Value>) -> bool {
+    serde_json::to_vec(payload).is_ok_and(|bytes| bytes.len() <= MAX_PAYLOAD_BYTES)
+}
+
+pub(super) fn invalid_checkpoint() -> ProviderError {
+    // 不能在凭据轮换、授权变更或账号替换后静默丢状态并重发；由客户端显式开新链。
+    ProviderError::new(
+        ProviderErrorKind::InvalidRequest,
+        UpstreamSendState::NotSent,
+    )
+    .with_continuation_failure(ContinuationFailure::HistoryUnavailable)
+    .with_continuation_recovery_disposition(ContinuationRecoveryDisposition::ClientReplayRequired)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/credentials.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/credentials.rs
new file mode 100644
index 000000000..d0c3257a0
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/credentials.rs
@@ -0,0 +1,186 @@
+use super::management::ProviderOperation;
+use chrono::{DateTime, Utc};
+use gateway_admin::{
+    model::provider_credentials::{
+        PrepareCredentialImport, PreparedCredentialCreate, PreparedCredentialImport,
+        ProviderDocument, ProviderExport, ProviderExportCredentialInput,
+    },
+    ports::provider::ProviderAdminError,
+};
+use gateway_core::account::{
+    CredentialState, OpaqueProviderData, OutboundProxy, ProviderAccountId,
+};
+use gateway_plugin_sdk::Stage;
+use gateway_plugin_sdk::call::auth::{
+    CredentialFacts, CredentialOperation, ExportCredential, ImportedCredentials,
+};
+
+use super::{
+    PluginProvider,
+    administration::{invalid, unavailable, unsupported},
+};
+
+impl PluginProvider {
+    pub(super) async fn import_credentials(
+        &self,
+        command: PrepareCredentialImport,
+    ) -> Result<PreparedCredentialImport, ProviderAdminError> {
+        if !self
+            .credential_operations
+            .contains(&CredentialOperation::Import)
+        {
+            return Err(unsupported());
+        }
+        self.validate_credential_input(CredentialOperation::Import, &command.document)?;
+        let call = self.management_call(
+            ProviderOperation::Import,
+            None,
+            command.default_outbound_proxy.clone(),
+        )?;
+        let imported: ImportedCredentials = call
+            .invoke(
+                "provider.credentials.import",
+                command.document.expose_to_provider().expose_to_provider(),
+            )
+            .await?;
+        let credentials = self
+            .prepare_created_credentials(imported.accounts, command.default_outbound_proxy)
+            .map_err(|_| call.invalid_result())?;
+        Ok(PreparedCredentialImport {
+            provider_kind: self.kind.clone(),
+            credentials,
+        })
+    }
+
+    pub(super) fn prepare_created_credentials(
+        &self,
+        accounts: Vec<CredentialFacts>,
+        proxy: Option<OutboundProxy>,
+    ) -> Result<Vec<PreparedCredentialCreate>, ProviderAdminError> {
+        if accounts.is_empty() || accounts.len() > 200 {
+            return Err(invalid());
+        }
+        let mut credentials = Vec::with_capacity(accounts.len());
+        for facts in accounts {
+            validate_facts(&facts)?;
+            let access_token_expires_at = timestamp(facts.access_token_expires_at_ms)?;
+            let next_refresh_at = timestamp(facts.next_refresh_at_ms)?;
+            credentials.push(PreparedCredentialCreate {
+                model_access: None,
+                outbound_proxy: proxy.clone(),
+                account_id: ProviderAccountId::new(format!(
+                    "acct_{}",
+                    uuid::Uuid::new_v4().simple()
+                ))
+                .map_err(|_| invalid())?,
+                provider_kind: self.kind.clone(),
+                name: facts.name,
+                email: facts.email,
+                upstream_user_id: facts.upstream_user_id,
+                upstream_account_id: facts.upstream_account_id,
+                plan_type: facts.plan_type,
+                authentication_kind: facts.authentication_kind,
+                provider_material: ProviderDocument::new(OpaqueProviderData::new(facts.material)),
+                has_refresh_token: facts.has_refresh_token,
+                access_token_expires_at,
+                next_refresh_at,
+                enabled: true,
+                credential_state: CredentialState::Ready,
+                credential_observed_at: Utc::now(),
+            });
+        }
+        Ok(credentials)
+    }
+
+    pub(super) async fn export_credentials_document(
+        &self,
+        credentials: Vec<ProviderExportCredentialInput>,
+    ) -> Result<ProviderExport, ProviderAdminError> {
+        if !self
+            .credential_operations
+            .contains(&CredentialOperation::Export)
+        {
+            return Err(unsupported());
+        }
+        if credentials.is_empty() || credentials.len() > 200 {
+            return Err(invalid());
+        }
+        let mut account_ids = Vec::with_capacity(credentials.len());
+        let mut documents = Vec::with_capacity(credentials.len());
+        for credential in credentials {
+            let account = credential.account;
+            self.ensure_provider(&account.provider_kind)?;
+            account_ids.push(ProviderAccountId::new(account.id.clone()).map_err(|_| invalid())?);
+            documents.push(ExportCredential {
+                account_id: account.id,
+                credential_revision: account.credential_revision.get(),
+                facts: CredentialFacts {
+                    name: account.name,
+                    authentication_kind: account.authentication_kind,
+                    material: credential
+                        .provider_material
+                        .into_provider_data()
+                        .into_inner(),
+                    email: account.email,
+                    upstream_user_id: account.upstream_user_id,
+                    upstream_account_id: account.upstream_account_id,
+                    plan_type: account.plan_type,
+                    has_refresh_token: account.has_refresh_token,
+                    access_token_expires_at_ms: account
+                        .access_token_expires_at
+                        .map(|time| time.timestamp_millis()),
+                    next_refresh_at_ms: account.next_refresh_at.map(|time| time.timestamp_millis()),
+                },
+            });
+        }
+        let reply = self
+            .session
+            .call(
+                "provider.credentials.export",
+                self.session
+                    .context(Stage::Management, Duration::from_secs(30)),
+                serde_json::json!({}),
+                serde_json::to_vec(&documents).map_err(|_| invalid())?,
+            )
+            .await
+            .map_err(|_| unavailable())?;
+        if reply.result != serde_json::json!({}) {
+            return Err(invalid());
+        }
+        let document = serde_json::from_slice(&reply.payload).map_err(|_| invalid())?;
+        Ok(ProviderExport {
+            provider_kind: self.kind.clone(),
+            account_ids,
+            document: ProviderDocument::new(OpaqueProviderData::new(document)),
+        })
+    }
+}
+
+pub(crate) fn validate_facts(facts: &CredentialFacts) -> Result<(), ProviderAdminError> {
+    let valid_text = |value: &str, maximum: usize| {
+        !value.trim().is_empty() && value.len() <= maximum && !value.chars().any(char::is_control)
+    };
+    if !valid_text(&facts.name, 200)
+        || !valid_text(&facts.authentication_kind, 64)
+        || [
+            &facts.email,
+            &facts.upstream_user_id,
+            &facts.upstream_account_id,
+            &facts.plan_type,
+        ]
+        .into_iter()
+        .flatten()
+        .any(|value| !valid_text(value, 1024))
+        || facts.material.is_empty()
+    {
+        return Err(invalid());
+    }
+    Ok(())
+}
+
+pub(crate) fn timestamp(value: Option<i64>) -> Result<Option<DateTime<Utc>>, ProviderAdminError> {
+    value
+        .map(|value| DateTime::from_timestamp_millis(value).ok_or_else(invalid))
+        .transpose()
+}
+use std::time::Duration;
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/drain.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/drain.rs
new file mode 100644
index 000000000..6186ac7aa
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/drain.rs
@@ -0,0 +1,364 @@
+use std::{
+    collections::BTreeMap,
+    sync::{Arc, Mutex, Weak},
+    time::Instant,
+};
+
+use futures::{StreamExt as _, stream};
+use gateway_admin::model::AdminError;
+
+use super::PluginProvider;
+use crate::generation::ContinuationDrainConfig;
+
+pub(crate) struct ContinuationDrain {
+    config: ContinuationDrainConfig,
+    state: Mutex<DrainState>,
+}
+
+#[derive(Default)]
+struct DrainState {
+    entries: BTreeMap<String, DrainEntry>,
+    next_sequence: u64,
+    reaper_running: bool,
+}
+
+enum DrainEntry {
+    Active {
+        provider: Weak<PluginProvider>,
+        superseded: bool,
+    },
+    Retired {
+        provider: Arc<PluginProvider>,
+        instance_id: String,
+        deadline: Instant,
+        sequence: u64,
+    },
+}
+
+impl ContinuationDrain {
+    pub(crate) fn new(config: ContinuationDrainConfig) -> Arc<Self> {
+        Arc::new(Self {
+            config,
+            state: Mutex::new(DrainState::default()),
+        })
+    }
+
+    pub(super) fn register(
+        self: &Arc<Self>,
+        provider: &Arc<PluginProvider>,
+    ) -> Result<(), AdminError> {
+        let mut state = lock(&self.state);
+        state.entries.retain(|_, entry| match entry {
+            DrainEntry::Active { provider, .. } => provider.strong_count() > 0,
+            DrainEntry::Retired { .. } => true,
+        });
+        if state.entries.contains_key(&provider.continuation.owner) {
+            return Err(AdminError::internal("插件续写执行 owner 冲突"));
+        }
+        state.entries.insert(
+            provider.continuation.owner.clone(),
+            DrainEntry::Active {
+                provider: Arc::downgrade(provider),
+                superseded: false,
+            },
+        );
+        Ok(())
+    }
+
+    pub(super) fn resolve(&self, owner: &str) -> Option<Arc<PluginProvider>> {
+        let now = Instant::now();
+        let mut state = lock(&self.state);
+        let mut shutdown = take_expired(&mut state, now);
+        let provider = match state.entries.get(owner) {
+            Some(DrainEntry::Active { provider, .. }) => provider.upgrade(),
+            Some(DrainEntry::Retired { provider, .. }) => Some(Arc::clone(provider)),
+            None => None,
+        }
+        .filter(|provider| provider.session.is_ready());
+        if provider.is_none() {
+            if let Some(DrainEntry::Retired { provider, .. }) = state.entries.remove(owner) {
+                shutdown.push(provider);
+            } else {
+                state.entries.remove(owner);
+            }
+        }
+        drop(state);
+        shutdown_detached(shutdown);
+        provider
+    }
+
+    /// 当前解释器已经接管该 owner 的全部同版本检查点，不再为它保留旧进程。
+    pub(super) fn supersede(&self, owner: &str) {
+        let mut state = lock(&self.state);
+        let shutdown = match state.entries.get_mut(owner) {
+            Some(DrainEntry::Active { superseded, .. }) => {
+                *superseded = true;
+                None
+            }
+            Some(DrainEntry::Retired { .. }) => match state.entries.remove(owner) {
+                Some(DrainEntry::Retired { provider, .. }) => Some(provider),
+                _ => None,
+            },
+            None => None,
+        };
+        drop(state);
+        shutdown_detached(shutdown.into_iter().collect());
+    }
+
+    /// 代次撤下时同步转移 owner，避免发布与下一次续写之间出现空窗。
+    pub(super) fn retire(self: &Arc<Self>, provider: Arc<PluginProvider>) -> bool {
+        let now = Instant::now();
+        let owner = provider.continuation.owner.clone();
+        let mut state = lock(&self.state);
+        let mut shutdown = take_expired(&mut state, now);
+        let superseded = matches!(
+            state.entries.get(&owner),
+            Some(DrainEntry::Active {
+                superseded: true,
+                ..
+            })
+        );
+        state.entries.remove(&owner);
+        if !provider
+            .continuation
+            .issued
+            .load(std::sync::atomic::Ordering::Acquire)
+            || superseded
+            || !provider.session.is_ready()
+        {
+            drop(state);
+            shutdown_detached(shutdown);
+            return false;
+        }
+
+        let sequence = state.next_sequence;
+        state.next_sequence = state.next_sequence.saturating_add(1);
+        state.entries.insert(
+            owner.clone(),
+            DrainEntry::Retired {
+                instance_id: provider.instance_id.clone(),
+                provider,
+                deadline: now.checked_add(self.config.retention).unwrap_or(now),
+                sequence,
+            },
+        );
+        shutdown.extend(trim_to_limits(&mut state, self.config));
+        let retained = state.entries.contains_key(&owner);
+        let start_reaper = retained && !state.reaper_running;
+        if start_reaper {
+            state.reaper_running = true;
+        }
+        drop(state);
+        shutdown_detached(shutdown);
+        if start_reaper {
+            self.start_reaper();
+        }
+        retained
+    }
+
+    /// 新制品占用进程槽前先完成到期回收；未到期 owner 仍受 Supervisor 硬容量约束。
+    pub(crate) async fn reap_expired(&self) {
+        let providers = take_expired(&mut lock(&self.state), Instant::now());
+        shutdown(providers).await;
+    }
+
+    /// Runtime 终止时只借用已有 owner 索引收集进程，不建立第二份生命周期权威。
+    pub(crate) fn sessions(&self) -> Vec<Arc<crate::RpcSession>> {
+        lock(&self.state)
+            .entries
+            .values()
+            .filter_map(|entry| match entry {
+                DrainEntry::Active { provider, .. } => provider.upgrade(),
+                DrainEntry::Retired { provider, .. } => Some(Arc::clone(provider)),
+            })
+            .map(|provider| Arc::clone(&provider.session))
+            .collect()
+    }
+
+    /// 按实例统计仍可恢复的旧 continuation；不暴露 owner 或任何会话状态内容。
+    pub(crate) fn retained_by_instance(&self) -> BTreeMap<String, u32> {
+        let now = Instant::now();
+        let mut retained = BTreeMap::<String, u32>::new();
+        for entry in lock(&self.state).entries.values() {
+            if let DrainEntry::Retired {
+                instance_id,
+                deadline,
+                ..
+            } = entry
+                && *deadline > now
+            {
+                let count = retained.entry(instance_id.clone()).or_default();
+                *count = count.saturating_add(1);
+            }
+        }
+        retained
+    }
+
+    /// 仅在所有已收集会话确认退出后释放保活引用；重复调用保持幂等。
+    pub(crate) fn finish_shutdown(&self) {
+        let entries = {
+            let mut state = lock(&self.state);
+            state.reaper_running = false;
+            std::mem::take(&mut state.entries)
+        };
+        drop(entries);
+    }
+
+    fn start_reaper(self: &Arc<Self>) {
+        let Ok(runtime) = tokio::runtime::Handle::try_current() else {
+            lock(&self.state).reaper_running = false;
+            return;
+        };
+        let weak = Arc::downgrade(self);
+        runtime.spawn(async move {
+            loop {
+                let Some(registry) = weak.upgrade() else {
+                    return;
+                };
+                let Some(delay) = registry.next_reap_delay() else {
+                    return;
+                };
+                drop(registry);
+                tokio::time::sleep(delay).await;
+                let Some(registry) = weak.upgrade() else {
+                    return;
+                };
+                registry.reap_expired().await;
+            }
+        });
+    }
+
+    fn next_reap_delay(&self) -> Option<std::time::Duration> {
+        let mut state = lock(&self.state);
+        let next = state
+            .entries
+            .values()
+            .filter_map(|entry| match entry {
+                DrainEntry::Retired { deadline, .. } => Some(*deadline),
+                DrainEntry::Active { .. } => None,
+            })
+            .min();
+        match next {
+            Some(deadline) => Some(deadline.saturating_duration_since(Instant::now())),
+            None => {
+                state.reaper_running = false;
+                None
+            }
+        }
+    }
+}
+
+impl Drop for ContinuationDrain {
+    fn drop(&mut self) {
+        let state = self
+            .state
+            .get_mut()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let providers = std::mem::take(&mut state.entries)
+            .into_values()
+            .filter_map(|entry| match entry {
+                DrainEntry::Retired { provider, .. } => Some(provider),
+                DrainEntry::Active { .. } => None,
+            })
+            .collect();
+        shutdown_detached(providers);
+    }
+}
+
+fn take_expired(state: &mut DrainState, now: Instant) -> Vec<Arc<PluginProvider>> {
+    let mut expired = Vec::new();
+    for (owner, entry) in std::mem::take(&mut state.entries) {
+        match entry {
+            DrainEntry::Active { provider, .. } if provider.strong_count() == 0 => {}
+            DrainEntry::Retired {
+                provider, deadline, ..
+            } if deadline <= now => expired.push(provider),
+            entry => {
+                state.entries.insert(owner, entry);
+            }
+        }
+    }
+    expired
+}
+
+fn trim_to_limits(
+    state: &mut DrainState,
+    config: ContinuationDrainConfig,
+) -> Vec<Arc<PluginProvider>> {
+    let mut remove = Vec::new();
+    let mut by_instance = BTreeMap::<String, Vec<(u64, String)>>::new();
+    let mut all = Vec::new();
+    for (owner, entry) in &state.entries {
+        if let DrainEntry::Retired {
+            instance_id,
+            sequence,
+            ..
+        } = entry
+        {
+            by_instance
+                .entry(instance_id.clone())
+                .or_default()
+                .push((*sequence, owner.clone()));
+            all.push((*sequence, owner.clone()));
+        }
+    }
+    for entries in by_instance.values_mut() {
+        entries.sort();
+        let excess = entries
+            .len()
+            .saturating_sub(config.maximum_per_instance.get());
+        remove.extend(entries.iter().take(excess).map(|(_, owner)| owner.clone()));
+    }
+    all.sort();
+    let remaining = all.len().saturating_sub(remove.len());
+    let global_excess = remaining.saturating_sub(config.maximum_generations.get());
+    let removed = remove
+        .iter()
+        .cloned()
+        .collect::<std::collections::BTreeSet<_>>();
+    remove.extend(
+        all.into_iter()
+            .filter(|(_, owner)| !removed.contains(owner))
+            .take(global_excess)
+            .map(|(_, owner)| owner),
+    );
+    remove.sort();
+    remove.dedup();
+    remove
+        .into_iter()
+        .filter_map(|owner| match state.entries.remove(&owner) {
+            Some(DrainEntry::Retired { provider, .. }) => Some(provider),
+            _ => None,
+        })
+        .collect()
+}
+
+fn shutdown_detached(providers: Vec<Arc<PluginProvider>>) {
+    if providers.is_empty() {
+        return;
+    }
+    for provider in &providers {
+        provider.session.quiesce();
+    }
+    if let Ok(runtime) = tokio::runtime::Handle::try_current() {
+        runtime.spawn(shutdown(providers));
+    }
+}
+
+async fn shutdown(providers: Vec<Arc<PluginProvider>>) {
+    stream::iter(providers)
+        .for_each_concurrent(Some(8), |provider| async move {
+            provider.session.quiesce();
+            provider
+                .session
+                .shutdown(std::time::Duration::from_secs(1))
+                .await;
+        })
+        .await;
+}
+
+fn lock<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
+    mutex
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/canonical.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/canonical.rs
new file mode 100644
index 000000000..8ea08b780
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/canonical.rs
@@ -0,0 +1,116 @@
+use gateway_core::{
+    error::ProviderError,
+    event::{
+        ContentItem, ContentKind, FinishReason, GatewayEvent, ReasoningDelta, ResponseMeta,
+        TextDelta, ToolCallDelta,
+    },
+    metering::{Decimal, ProviderReportedCost, Usage},
+};
+use gateway_plugin_sdk::call::provider::{
+    CanonicalEvent, ContentKind as WireContentKind, FinishReason as WireFinishReason,
+};
+
+use super::protocol_error;
+
+pub(super) fn append(
+    event: CanonicalEvent,
+    billing: &super::super::billing::BillingPlan,
+    facts: &mut Vec<GatewayEvent>,
+) -> Result<(), ProviderError> {
+    if let CanonicalEvent::BillableUsage { usage, band } = event {
+        if !billing.enabled() {
+            return Err(protocol_error());
+        }
+        let usage = normalized_usage(usage);
+        let cost = billing.calculate(&usage, band);
+        facts.push(GatewayEvent::Usage(usage));
+        if let Some(cost) = cost {
+            facts.push(GatewayEvent::CalculatedCost(cost));
+        }
+        return Ok(());
+    }
+    let event = match event {
+        CanonicalEvent::Started { id, model } => GatewayEvent::Started(metadata(id, model)?),
+        CanonicalEvent::Completed { id, model, reason } => {
+            GatewayEvent::Completed(metadata(id, model)?.with_finish_reason(match reason {
+                WireFinishReason::Stop => FinishReason::Stop,
+                WireFinishReason::Length => FinishReason::Length,
+                WireFinishReason::ToolCall => FinishReason::ToolCall,
+                WireFinishReason::ContentFilter => FinishReason::ContentFilter,
+                WireFinishReason::Other => FinishReason::Other,
+            }))
+        }
+        CanonicalEvent::ContentAdded { index, kind } => {
+            GatewayEvent::ContentAdded(ContentItem::new(
+                index,
+                match kind {
+                    WireContentKind::Text => ContentKind::Text,
+                    WireContentKind::Reasoning => ContentKind::Reasoning,
+                    WireContentKind::ToolCall => ContentKind::ToolCall,
+                    WireContentKind::Image => ContentKind::Image,
+                    WireContentKind::Audio => ContentKind::Audio,
+                },
+            ))
+        }
+        CanonicalEvent::TextDelta { index, text } => GatewayEvent::TextDelta(TextDelta {
+            content_index: index,
+            text,
+        }),
+        CanonicalEvent::ReasoningDelta { index, text } => {
+            GatewayEvent::ReasoningDelta(ReasoningDelta {
+                content_index: index,
+                text,
+            })
+        }
+        CanonicalEvent::ToolCallDelta {
+            index,
+            id,
+            name,
+            arguments,
+        } => GatewayEvent::ToolCallDelta(ToolCallDelta {
+            content_index: index,
+            call_id: id,
+            name,
+            arguments_delta: arguments,
+        }),
+        CanonicalEvent::Usage { usage } => GatewayEvent::Usage(normalized_usage(usage)),
+        CanonicalEvent::ProviderCost { amount, currency } => {
+            if currency != "USD" {
+                return Err(protocol_error());
+            }
+            let amount: Decimal = amount.parse().map_err(|_| protocol_error())?;
+            GatewayEvent::ProviderCost(
+                ProviderReportedCost::from_usd_ticks(amount.scaled())
+                    .map_err(|_| protocol_error())?,
+            )
+        }
+        CanonicalEvent::BillableUsage { .. } => {
+            return Err(protocol_error());
+        }
+    };
+    facts.push(event);
+    Ok(())
+}
+
+fn normalized_usage(usage: gateway_plugin_sdk::call::provider::Usage) -> Usage {
+    Usage {
+        input_tokens: usage.input_tokens,
+        output_tokens: usage.output_tokens,
+        cached_tokens: usage.cached_tokens,
+        cache_write_tokens: usage.cache_write_tokens,
+        reasoning_tokens: usage.reasoning_tokens,
+        image_input_tokens: usage.image_input_tokens,
+        image_output_tokens: usage.image_output_tokens,
+        total_tokens: usage.total_tokens,
+    }
+}
+
+fn metadata(id: String, model: Option<String>) -> Result<ResponseMeta, ProviderError> {
+    if id.is_empty() || id.len() > 512 {
+        return Err(protocol_error());
+    }
+    Ok(match model {
+        Some(model) => ResponseMeta::new(id, model),
+        None => ResponseMeta::for_provider_endpoint(id),
+    })
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/failure.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/failure.rs
new file mode 100644
index 000000000..c44b67e31
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/failure.rs
@@ -0,0 +1,66 @@
+use std::time::Duration;
+
+use gateway_core::{
+    error::{ClientVisibleUpstreamResponse, ProviderError, ProviderErrorKind},
+    event::ProviderResponseObservation,
+    upstream::{OpaqueUpstreamValue, UpstreamSendState},
+};
+use gateway_plugin_sdk::call::provider::{ExecutionFailure, ExecutionFailureKind};
+
+use super::{super::execution::send_watermark, protocol_error};
+
+pub(super) fn decode(
+    failure: ExecutionFailure,
+    observation: Option<&ProviderResponseObservation>,
+    observed: UpstreamSendState,
+) -> Result<ProviderError, ProviderError> {
+    let kind = match failure.kind {
+        ExecutionFailureKind::InvalidRequest => ProviderErrorKind::InvalidRequest,
+        ExecutionFailureKind::Unsupported => ProviderErrorKind::Unsupported,
+        ExecutionFailureKind::Authentication => ProviderErrorKind::Unauthorized,
+        ExecutionFailureKind::PermissionDenied => ProviderErrorKind::PermissionDenied,
+        ExecutionFailureKind::RateLimited => ProviderErrorKind::RateLimited,
+        ExecutionFailureKind::QuotaExhausted => ProviderErrorKind::QuotaExhausted,
+        ExecutionFailureKind::Unavailable => ProviderErrorKind::Unavailable,
+        ExecutionFailureKind::Protocol => ProviderErrorKind::Protocol,
+        ExecutionFailureKind::Timeout => ProviderErrorKind::Timeout,
+        ExecutionFailureKind::Cancelled => ProviderErrorKind::Cancelled,
+    };
+    let mut error = ProviderError::new(kind, send_watermark(observed, failure.send_state));
+    if let Some(code) = failure.code {
+        error = error.with_upstream_code(OpaqueUpstreamValue::new(code));
+    }
+    if let Some(delay) = failure.retry_after_ms {
+        error = error.with_retry_after(Duration::from_millis(delay));
+    }
+    if let Some(observation) = observation {
+        if let Some(status) = observation.status_code() {
+            error = error.with_status(status);
+        }
+        if let Some(id) = observation.request_id() {
+            error = error.with_upstream_request_id(id.clone());
+        }
+    }
+    if let Some(response) = failure.response {
+        if !(400..=599).contains(&response.status)
+            || response.body.len() > 64 * 1024
+            || response.content_type.as_ref().is_some_and(|value| {
+                value.len() > 256 || value.iter().any(|byte| !(32..127).contains(byte))
+            })
+        {
+            return Err(protocol_error());
+        }
+        let response = ClientVisibleUpstreamResponse::new(
+            response.status,
+            response.content_type,
+            response.body.into(),
+        )
+        .with_headers(
+            observation
+                .map(|value| value.client_headers().to_vec())
+                .unwrap_or_default(),
+        );
+        error = error.with_client_visible_upstream_response(response);
+    }
+    Ok(error)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/mod.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/mod.rs
new file mode 100644
index 000000000..f4051bcae
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/mod.rs
@@ -0,0 +1,106 @@
+mod canonical;
+mod failure;
+mod observation;
+mod wire;
+
+use std::collections::BTreeSet;
+
+use gateway_core::{
+    error::{ProviderError, ProviderErrorKind},
+    event::{GatewayEvent, ProviderEvent},
+    upstream::{UpstreamSendState, UpstreamTransport},
+};
+use gateway_plugin_sdk::call::provider::ExecutionEvent;
+
+use super::{billing::BillingPlan, execution::stream_protocol_error as protocol_error};
+
+pub(super) fn decode(
+    bytes: &[u8],
+    formats: &BTreeSet<String>,
+    billing: &BillingPlan,
+    transport: &UpstreamTransport,
+    binding: &super::continuation::SessionBinding,
+    observed: UpstreamSendState,
+) -> Result<ProviderEvent, ProviderError> {
+    match decode_payload(bytes, formats, billing, transport, binding, observed)
+        .map_err(|_| ProviderError::new(ProviderErrorKind::Protocol, observed))?
+    {
+        Decoded::Event(event) => Ok(event),
+        Decoded::Failure(error) => Err(error),
+    }
+}
+
+enum Decoded {
+    Event(ProviderEvent),
+    Failure(ProviderError),
+}
+
+fn decode_payload(
+    bytes: &[u8],
+    formats: &BTreeSet<String>,
+    billing: &BillingPlan,
+    transport: &UpstreamTransport,
+    binding: &super::continuation::SessionBinding,
+    observed: UpstreamSendState,
+) -> Result<Decoded, ProviderError> {
+    let event = ExecutionEvent::decode(bytes).map_err(|_| protocol_error())?;
+    if event.facts.len() > 64 || (!event.facts.is_empty() && !formats.contains("canonical")) {
+        return Err(protocol_error());
+    }
+    let mut facts = Vec::with_capacity(event.facts.len());
+    for fact in event.facts {
+        canonical::append(fact, billing, &mut facts)?;
+    }
+    let wire = event
+        .wire
+        .map(|wire| wire::decode(wire, formats))
+        .transpose()?;
+    let raw_http_body = wire
+        .as_ref()
+        .is_some_and(|value| value.raw_http_body_bytes().is_some());
+    let mut observation = event
+        .observation
+        .map(|value| observation::decode(value, transport, raw_http_body))
+        .transpose()?;
+    // 续写检查点必须与终态事实原子交付，Core 才能以实际 response ID 保存账号 pin。
+    if event.session_update.is_some() && !matches!(facts.last(), Some(GatewayEvent::Completed(_))) {
+        return Err(protocol_error());
+    }
+    if event.failure.is_some()
+        && (event.session_update.is_some()
+            || facts
+                .iter()
+                .any(|fact| matches!(fact, GatewayEvent::Completed(_))))
+    {
+        return Err(protocol_error());
+    }
+    let failure = event
+        .failure
+        .map(|value| failure::decode(value, observation.as_ref(), observed))
+        .transpose()?;
+    let mut result = match wire {
+        Some(wire) => ProviderEvent::canonical_with_wire(facts, wire),
+        None => {
+            let mut facts = facts.into_iter();
+            if let Some(first) = facts.next() {
+                facts.fold(ProviderEvent::canonical(first), ProviderEvent::with_fact)
+            } else if let Some(observation) = observation.take() {
+                ProviderEvent::observation(observation)
+            } else if let Some(error) = failure {
+                return Ok(Decoded::Failure(error));
+            } else {
+                return Err(protocol_error());
+            }
+        }
+    };
+    if let Some(observation) = observation {
+        result.attach_observation(observation);
+    }
+    if let Some(update) = event.session_update {
+        result.attach_session_update(binding.capture(update)?);
+    }
+    Ok(match failure {
+        Some(error) => Decoded::Failure(error.with_atomic_client_events(vec![result])),
+        None => Decoded::Event(result),
+    })
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/observation.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/observation.rs
new file mode 100644
index 000000000..537342cb7
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/observation.rs
@@ -0,0 +1,101 @@
+use gateway_core::{
+    error::ProviderError,
+    event::{
+        ProviderResponseHeader, ProviderResponseObservation, ProviderResponseTimings,
+        UpstreamHttpVersion,
+    },
+    upstream::{OpaqueUpstreamValue, UpstreamTransport},
+};
+use gateway_plugin_sdk::call::provider::{HttpVersion, ResponseObservation};
+use gateway_protocol::openai::response_header_is_forwardable;
+
+use super::protocol_error;
+
+pub(super) fn decode(
+    value: ResponseObservation,
+    transport: &UpstreamTransport,
+    raw_http_body: bool,
+) -> Result<ProviderResponseObservation, ProviderError> {
+    if value
+        .status
+        .is_some_and(|status| !(100..=599).contains(&status))
+        || value.client_headers.len() > 64
+    {
+        return Err(protocol_error());
+    }
+    let mut header_bytes = 0usize;
+    let headers = value
+        .client_headers
+        .into_iter()
+        .map(|header| {
+            header_bytes = header_bytes
+                .saturating_add(header.name.len())
+                .saturating_add(header.value.len());
+            if header_bytes > 16 * 1024
+                || header.name.is_empty()
+                || header.name.len() > 256
+                || !header
+                    .name
+                    .bytes()
+                    .all(|byte| byte.is_ascii_alphanumeric() || b"!#$%&'*+-.^_`|~".contains(&byte))
+                // 原始 HTTP 操作仍由 API owner 重建 Content-Length，并继续拒绝
+                // 敏感/逐跳响应头；这里只允许与同一 RawBody 原子交付的媒体类型。
+                || (!response_header_is_forwardable(&header.name, &[])
+                    && !(raw_http_body && header.name.eq_ignore_ascii_case("content-type")))
+                || header
+                    .value
+                    .iter()
+                    .any(|byte| *byte == 127 || (*byte < 32 && *byte != b'\t'))
+            {
+                return Err(protocol_error());
+            }
+            Ok(ProviderResponseHeader::new(
+                header.name,
+                header.value.into(),
+            ))
+        })
+        .collect::<Result<Vec<_>, _>>()?;
+    let timings = value.timings;
+    let mut result = ProviderResponseObservation::new(transport.clone())
+        .with_client_headers(headers)
+        .with_timings(ProviderResponseTimings {
+            transport_decision_wait_ms: timings.transport_decision_wait_ms,
+            connect_ms: timings.connect_ms,
+            headers_ms: timings.headers_ms,
+            first_event_ms: timings.first_event_ms,
+            first_reasoning_ms: timings.first_reasoning_ms,
+            first_text_ms: timings.first_text_ms,
+            first_token_ms: timings.first_token_ms,
+            provider_processing_ms: timings.provider_processing_ms,
+        });
+    if let Some(status) = value.status {
+        result = result.with_status_code(status);
+    }
+    if let Some(request_id) = value.request_id {
+        result = result.with_request_id(OpaqueUpstreamValue::new(request_id));
+    }
+    if let Some(tier) = value.service_tier {
+        result = result
+            .try_with_service_tier(tier)
+            .map_err(|_| protocol_error())?;
+    }
+    if let Some(model) = value.response_model {
+        result = result.with_upstream_response_model_if_valid(&model);
+        if result.upstream_response_model().is_none() {
+            return Err(protocol_error());
+        }
+    }
+    if let Some(version) = value.http_version {
+        result = result.with_http_version(match version {
+            HttpVersion::Http09 => UpstreamHttpVersion::Http09,
+            HttpVersion::Http10 => UpstreamHttpVersion::Http10,
+            HttpVersion::Http11 => UpstreamHttpVersion::Http11,
+            HttpVersion::Http2 => UpstreamHttpVersion::Http2,
+            HttpVersion::Http3 => UpstreamHttpVersion::Http3,
+        });
+    }
+    if let Some(forecast) = value.quota_forecast {
+        result = result.with_provider_metadata(super::super::forecast::metadata(forecast)?);
+    }
+    Ok(result)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/wire.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/wire.rs
new file mode 100644
index 000000000..51b448d67
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/events/wire.rs
@@ -0,0 +1,83 @@
+use std::collections::BTreeSet;
+
+use gateway_core::{error::ProviderError, event::ProtocolWireEvent};
+use gateway_plugin_sdk::call::provider::{WireEvent, WirePayload};
+use gateway_protocol::openai::sse::{parse_sse_events, sse_frame_end};
+
+use super::protocol_error;
+
+pub(super) fn decode(
+    wire: WireEvent,
+    formats: &BTreeSet<String>,
+) -> Result<ProtocolWireEvent, ProviderError> {
+    if !formats.contains(&wire.protocol) {
+        return Err(protocol_error());
+    }
+    let result = match wire.payload {
+        WirePayload::Json {
+            event,
+            data,
+            id,
+            retry,
+            raw_sse,
+        } => {
+            if event
+                .as_ref()
+                .is_some_and(|value| value.contains(['\r', '\n', '\0']))
+                || id
+                    .as_ref()
+                    .is_some_and(|value| value.contains(['\r', '\n', '\0']))
+            {
+                return Err(protocol_error());
+            }
+            if let Some(raw) = raw_sse {
+                validate_frame(&raw)?;
+                let parsed =
+                    parse_sse_events(std::str::from_utf8(&raw).map_err(|_| protocol_error())?)
+                        .map_err(|_| protocol_error())?;
+                let [parsed] = parsed.as_slice() else {
+                    return Err(protocol_error());
+                };
+                let parsed_data: serde_json::Value =
+                    serde_json::from_str(&parsed.data).map_err(|_| protocol_error())?;
+                if parsed.event != event
+                    || parsed.id != id
+                    || parsed.retry != retry
+                    || parsed_data != data
+                {
+                    return Err(protocol_error());
+                }
+                ProtocolWireEvent::json_with_raw_sse_metadata(
+                    wire.protocol,
+                    event,
+                    data,
+                    raw.into(),
+                    id,
+                    retry,
+                )
+            } else {
+                ProtocolWireEvent::json_with_sse_metadata(wire.protocol, event, data, id, retry)
+            }
+        }
+        WirePayload::RawSse { frame } => {
+            validate_frame(&frame)?;
+            ProtocolWireEvent::raw_sse(wire.protocol, frame.into())
+        }
+        WirePayload::RawJson { body } => {
+            serde_json::from_slice::<serde_json::Value>(&body).map_err(|_| protocol_error())?;
+            ProtocolWireEvent::raw_json(wire.protocol, body.into())
+        }
+        WirePayload::RawBody { body } => {
+            ProtocolWireEvent::raw_http_body(wire.protocol, body.into())
+        }
+    };
+    result.map_err(|_| protocol_error())
+}
+
+fn validate_frame(frame: &[u8]) -> Result<(), ProviderError> {
+    // 复用协议 owner 的边界定义；不允许合帧或把未结束片段交给客户端加工器。
+    if frame.is_empty() || sse_frame_end(frame) != Some(frame.len()) {
+        return Err(protocol_error());
+    }
+    Ok(())
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/execution.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/execution.rs
new file mode 100644
index 000000000..ea3bc873a
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/execution.rs
@@ -0,0 +1,439 @@
+use std::{
+    sync::Arc,
+    time::{Duration, SystemTime},
+};
+
+use super::{PluginProvider, events};
+use crate::{RpcError, RpcSession, RpcStream};
+use futures::{StreamExt as _, stream};
+use gateway_core::{
+    engine::{
+        AttemptContext,
+        provider::{
+            Provider, ProviderCallMetadata, ProviderMiddlewareTerminal, ProviderRequest,
+            ProviderStream,
+        },
+    },
+    error::{ProviderError, ProviderErrorKind},
+    operation::{Operation, ProviderHttpMethod as CoreProviderHttpMethod},
+    upstream::{UpstreamSendState, UpstreamTransport},
+};
+use gateway_plugin_sdk::{
+    CallContext, Stage,
+    call::provider::{
+        ExecutePrepared, ExecutionInput, OperationKind, PrepareExecution, PreparedExecution,
+        ProviderHttpHeader, ProviderHttpMethod, ProviderHttpRequest,
+    },
+};
+
+impl PluginProvider {
+    pub(super) async fn prepare_execution(
+        self: Arc<Self>,
+        request: ProviderRequest,
+        attempt: AttemptContext,
+    ) -> Result<ProviderStream, ProviderError> {
+        if attempt.extension_scope().contains(&self.instance_id) {
+            return Err(ProviderError::new(
+                ProviderErrorKind::PermissionDenied,
+                UpstreamSendState::NotSent,
+            ));
+        }
+        if let Operation::ProviderHttp(http) = request.operation()
+            && !self
+                .http_endpoints
+                .get(http.endpoint())
+                .is_some_and(|methods| methods.contains(&wire_http_method(http.method())))
+        {
+            return Err(ProviderError::new(
+                ProviderErrorKind::Unsupported,
+                UpstreamSendState::NotSent,
+            ));
+        }
+        let continuation_state = request
+            .operation()
+            .provider_session_state(self.kind.as_str())
+            .cloned();
+        match self
+            .continuation
+            .interpreter_target(continuation_state.as_ref())?
+        {
+            super::continuation::InterpreterTarget::Current { previous_owner } => {
+                if let (Some(owner), Some(drain)) =
+                    (previous_owner, self.continuation_drain.upgrade())
+                {
+                    drain.supersede(&owner);
+                }
+            }
+            super::continuation::InterpreterTarget::Retired { owner } => {
+                let retired = self
+                    .continuation_drain
+                    .upgrade()
+                    .and_then(|drain| drain.resolve(&owner))
+                    .filter(|provider| {
+                        provider.instance_id == self.instance_id
+                            && provider.kind == self.kind
+                            && provider.continuation.matches_authority(&self.continuation)
+                    })
+                    .ok_or_else(super::continuation::invalid_checkpoint)?;
+                return Provider::execute(retired, request, attempt).await;
+            }
+        }
+        let model = request
+            .candidate()
+            .upstream_model()
+            .map(|model| model.as_str().to_owned());
+        let billing = super::billing::BillingPlan::new(
+            self.pricing.as_ref(),
+            model.as_deref(),
+            attempt.pricing().get(self.kind.as_str()),
+        );
+        let (credential, lease) = self
+            .select_account(
+                model.as_deref(),
+                &request.operation().capability_requirements(),
+                &attempt,
+            )
+            .await?;
+        let middleware_operation = request.operation().clone();
+        let middleware_provider = self.kind.clone();
+        let middleware_model = model.clone();
+        let middleware_account = credential.account.id().clone();
+        let provider = Arc::clone(&self);
+        let terminal_attempt = attempt.clone();
+        let terminal: ProviderMiddlewareTerminal = Box::new(move |processed, headers| {
+            Box::pin(async move {
+                let headers = headers
+                    .into_iter()
+                    .map(|header| {
+                        let (name, value) = header.into_parts();
+                        ProviderHttpHeader {
+                            name,
+                            value: value.to_vec(),
+                        }
+                    })
+                    .collect();
+                let (protocol, operation, body, context, http_request) = match &processed {
+                    Operation::Generate(generate) => {
+                        let payload = generate.protocol_payload();
+                        (
+                            payload.protocol(),
+                            OperationKind::Generate,
+                            serde_json::to_vec(payload.body()).map_err(|_| protocol_error())?,
+                            payload.context(),
+                            None,
+                        )
+                    }
+                    Operation::GenerateImage(image) => {
+                        let payload = image.payload();
+                        (
+                            payload.protocol(),
+                            OperationKind::GenerateImage,
+                            payload.body().to_vec(),
+                            payload.context(),
+                            None,
+                        )
+                    }
+                    Operation::Search(search) => {
+                        let payload = search.payload();
+                        (
+                            payload.protocol(),
+                            OperationKind::Search,
+                            payload.body().to_vec(),
+                            payload.context(),
+                            None,
+                        )
+                    }
+                    Operation::CountTokens(count) => {
+                        let payload = count.payload();
+                        (
+                            payload.protocol(),
+                            OperationKind::CountTokens,
+                            payload.body().to_vec(),
+                            payload.context(),
+                            None,
+                        )
+                    }
+                    Operation::ProviderHttp(http) => {
+                        let payload = http.payload();
+                        (
+                            payload.protocol(),
+                            OperationKind::ProviderHttp,
+                            payload.body().to_vec(),
+                            payload.context(),
+                            Some(ProviderHttpRequest {
+                                endpoint: http.endpoint().to_owned(),
+                                method: wire_http_method(http.method()),
+                                query: http.query().map(str::to_owned),
+                                headers: http
+                                    .headers()
+                                    .iter()
+                                    .map(|header| ProviderHttpHeader {
+                                        name: header.name().to_owned(),
+                                        value: header.value().to_vec(),
+                                    })
+                                    .collect(),
+                            }),
+                        )
+                    }
+                    _ => {
+                        return Err(ProviderError::new(
+                            ProviderErrorKind::Unsupported,
+                            UpstreamSendState::NotSent,
+                        ));
+                    }
+                };
+                if !provider
+                    .input_formats
+                    .iter()
+                    .any(|format| format == protocol)
+                {
+                    return Err(ProviderError::new(
+                        ProviderErrorKind::Unsupported,
+                        UpstreamSendState::NotSent,
+                    ));
+                }
+                let binding = provider.continuation.bind_account(
+                    credential.account.id().as_str().into(),
+                    credential.account.revision().get(),
+                );
+                let provider_session_state = binding.restore(continuation_state.as_ref())?;
+                let mut context_call = provider
+                    .session
+                    .context(Stage::Attempt, remaining(&terminal_attempt)?);
+                context_call.request_id = Some(terminal_attempt.request_id().as_str().into());
+                context_call.attempt_id = Some(format!(
+                    "{}:{}",
+                    terminal_attempt.request_id(),
+                    terminal_attempt.attempt_index()
+                ));
+                context_call.account_id = Some(credential.account.id().as_str().into());
+                context_call.credential_revision = Some(credential.account.revision().get());
+                let scope = provider
+                    .callbacks
+                    .prepare_execution(&context_call, credential.account.outbound_proxy().cloned())
+                    .map_err(|_| protocol_error())?;
+                let params = PrepareExecution {
+                    protocol: protocol.into(),
+                    operation,
+                    model: model.clone(),
+                    account_id: credential.account.id().as_str().into(),
+                    credential_revision: credential.account.revision().get(),
+                    credential: credential.credential.expose_to_provider().clone(),
+                    context: context.clone(),
+                    request_profile: terminal_attempt.request_profile().map(|profile| {
+                        serde_json::Value::Object(profile.expose_to_provider().clone())
+                    }),
+                    headers,
+                    provider_session_state,
+                    http_request,
+                };
+                let reply = provider
+                    .session
+                    .call(
+                        "provider.prepare",
+                        context_call.clone(),
+                        serde_json::json!({}),
+                        ExecutionInput {
+                            request: params,
+                            body,
+                        }
+                        .encode()
+                        .map_err(|_| protocol_error())?,
+                    )
+                    .await
+                    .map_err(|error| rpc_error(error, UpstreamSendState::NotSent))?;
+                let prepared: PreparedExecution =
+                    serde_json::from_value(reply.result).map_err(|_| protocol_error())?;
+                if !reply.payload.is_empty()
+                    || prepared.token.is_empty()
+                    || prepared.token.len() > 256
+                {
+                    return Err(protocol_error());
+                }
+                let prepared_call = PreparedCall {
+                    session: Arc::clone(&provider.session),
+                    context: context_call.clone(),
+                    token: prepared.token.clone(),
+                };
+                let transport =
+                    UpstreamTransport::new(prepared.transport).map_err(|_| protocol_error())?;
+                let metadata = match request.candidate().upstream_model() {
+                    Some(model) => ProviderCallMetadata::new(
+                        provider.kind.clone(),
+                        model.clone(),
+                        credential.account.id().clone(),
+                        transport.clone(),
+                    ),
+                    None => ProviderCallMetadata::for_provider_endpoint(
+                        provider.kind.clone(),
+                        credential.account.id().clone(),
+                        transport.clone(),
+                    ),
+                };
+                let session = Arc::clone(&provider.session);
+                let output_formats = provider.output_formats.clone();
+                let execution_scope = scope.clone();
+                // 只在 Core 记录 attempt 后首次 poll 时激活；准备调用不具备 HTTP/模型回调权限。
+                let open = stream::once(async move {
+                    context_call.stage = Stage::Execution;
+                    context_call.timeout_ms = remaining(&terminal_attempt)?
+                        .as_millis()
+                        .min(u128::from(u64::MAX))
+                        as u64;
+                    let params = serde_json::to_value(ExecutePrepared {
+                        token: prepared.token,
+                    })
+                    .map_err(|_| protocol_error())?;
+                    execution_scope.activate();
+                    let stream = session
+                        .call_stream("provider.execute", context_call, params, vec![])
+                        .await
+                        .map_err(|error| rpc_error(error, execution_scope.send_state()))?;
+                    if stream.initial.result != serde_json::json!({"stream":true})
+                        || !stream.initial.payload.is_empty()
+                    {
+                        return Err(ProviderError::new(
+                            ProviderErrorKind::Protocol,
+                            execution_scope.send_state(),
+                        ));
+                    }
+                    Ok((stream, billing))
+                })
+                .map(move |opened| {
+                    let formats = output_formats.clone();
+                    let scope = scope.clone();
+                    let transport = transport.clone();
+                    let binding = binding.clone();
+                    stream::try_unfold(
+                        (opened, formats, scope, transport, binding),
+                        |(opened, formats, scope, transport, binding)| async move {
+                            let (mut stream, billing): (RpcStream, super::billing::BillingPlan) =
+                                opened?;
+                            match stream
+                                .next()
+                                .await
+                                .map_err(|error| rpc_error(error, scope.send_state()))?
+                            {
+                                Some(bytes) => Ok(Some((
+                                    events::decode(
+                                        &bytes,
+                                        &formats,
+                                        &billing,
+                                        &transport,
+                                        &binding,
+                                        scope.send_state(),
+                                    )?,
+                                    (Ok((stream, billing)), formats, scope, transport, binding),
+                                ))),
+                                None => Ok(None),
+                            }
+                        },
+                    )
+                })
+                .flatten();
+                Ok(ProviderStream::new(metadata, open, (lease, prepared_call))
+                    .with_account_feedback(provider.ports.account_feedback()))
+            })
+        });
+        attempt
+            .execute_middleware(
+                middleware_operation,
+                middleware_provider,
+                middleware_model,
+                middleware_account,
+                terminal,
+            )
+            .await
+    }
+}
+
+fn remaining(attempt: &AttemptContext) -> Result<Duration, ProviderError> {
+    attempt
+        .deadline()
+        .duration_since(SystemTime::now())
+        .ok()
+        .filter(|duration| !duration.is_zero())
+        .map(|duration| duration.min(Duration::from_secs(120)))
+        .ok_or_else(|| ProviderError::new(ProviderErrorKind::Timeout, UpstreamSendState::NotSent))
+}
+
+const fn wire_http_method(method: CoreProviderHttpMethod) -> ProviderHttpMethod {
+    match method {
+        CoreProviderHttpMethod::Get => ProviderHttpMethod::Get,
+        CoreProviderHttpMethod::Post => ProviderHttpMethod::Post,
+    }
+}
+
+pub(super) fn protocol_error() -> ProviderError {
+    ProviderError::new(ProviderErrorKind::Protocol, UpstreamSendState::NotSent)
+}
+
+pub(super) fn stream_protocol_error() -> ProviderError {
+    ProviderError::new(ProviderErrorKind::Protocol, UpstreamSendState::Ambiguous)
+}
+
+struct PreparedCall {
+    session: Arc<RpcSession>,
+    context: CallContext,
+    token: String,
+}
+
+impl Drop for PreparedCall {
+    fn drop(&mut self) {
+        // 冷流可能从未激活；显式释放对端准备句柄，账号租约由外层独立归还。
+        if let Ok(runtime) = tokio::runtime::Handle::try_current() {
+            let session = self.session.clone();
+            let mut context = self.context.clone();
+            context.timeout_ms = 1_000;
+            let params = serde_json::json!({"token":self.token});
+            runtime.spawn(async move {
+                let _ = session
+                    .call("provider.discard", context, params, vec![])
+                    .await;
+            });
+        }
+    }
+}
+
+fn rpc_error(error: RpcError, observed: UpstreamSendState) -> ProviderError {
+    use gateway_plugin_sdk::ErrorCode;
+    match error {
+        RpcError::Remote(fault) => {
+            let kind = match fault.code {
+                ErrorCode::Unsupported => ProviderErrorKind::Unsupported,
+                ErrorCode::Rejected | ErrorCode::InvalidInput | ErrorCode::PermissionDenied => {
+                    ProviderErrorKind::InvalidRequest
+                }
+                ErrorCode::Timeout => ProviderErrorKind::Timeout,
+                ErrorCode::Cancelled => ProviderErrorKind::Cancelled,
+                _ => ProviderErrorKind::Unavailable,
+            };
+            let state = send_watermark(observed, fault.send_state);
+            let error = ProviderError::new(kind, state);
+            match fault.http_status {
+                Some(status) => error.with_status(status),
+                None => error,
+            }
+        }
+        RpcError::Timeout => ProviderError::new(ProviderErrorKind::Timeout, observed),
+        RpcError::Protocol | RpcError::Context => {
+            ProviderError::new(ProviderErrorKind::Protocol, observed)
+        }
+        _ => ProviderError::new(ProviderErrorKind::Unavailable, observed),
+    }
+}
+
+pub(super) fn send_watermark(
+    observed: UpstreamSendState,
+    reported: gateway_plugin_sdk::SendState,
+) -> UpstreamSendState {
+    use gateway_plugin_sdk::SendState;
+    // 宿主事实不可回退；控制面 fault 与执行失败封套共用同一单调上界。
+    match (observed, reported) {
+        (UpstreamSendState::Sent, _) | (_, SendState::Sent) => UpstreamSendState::Sent,
+        (UpstreamSendState::Ambiguous, _) | (_, SendState::Ambiguous) => {
+            UpstreamSendState::Ambiguous
+        }
+        _ => UpstreamSendState::NotSent,
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/forecast.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/forecast.rs
new file mode 100644
index 000000000..62369730e
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/forecast.rs
@@ -0,0 +1,109 @@
+use std::collections::BTreeSet;
+
+use chrono::{DateTime, Utc};
+use gateway_admin::model::{
+    provider_credentials::{
+        ProviderDocument, ProviderQuotaWindow, ProviderQuotaWindowRole, QuotaLocalUsageAttribution,
+    },
+    quota_forecast_sampling::QuotaForecastObservation,
+};
+use gateway_core::{error::ProviderError, event::ProviderResponseMetadata};
+use gateway_plugin_sdk::call::provider::quota::{QuotaForecast, QuotaWindowRole};
+
+use super::execution::stream_protocol_error;
+
+const METADATA_KEY: &str = "plugin_quota_forecast_v1";
+
+pub(super) fn metadata(value: QuotaForecast) -> Result<ProviderResponseMetadata, ProviderError> {
+    validate(&value).ok_or_else(stream_protocol_error)?;
+    let json = serde_json::to_string(&serde_json::json!({METADATA_KEY: value}))
+        .map_err(|_| stream_protocol_error())?;
+    ProviderResponseMetadata::new(json).ok_or_else(stream_protocol_error)
+}
+
+/// 历史解释只消费已落库的稳定事实，不调用当前插件或读取当前额度后反推历史。
+pub(super) fn observation(
+    document: &ProviderDocument,
+    window: &ProviderQuotaWindow,
+) -> Option<QuotaForecastObservation> {
+    if window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide {
+        return None;
+    }
+    let value: QuotaForecast = serde_json::from_value(
+        document
+            .expose_to_provider()
+            .expose_to_provider()
+            .get(METADATA_KEY)?
+            .clone(),
+    )
+    .ok()?;
+    validate(&value)?;
+    let observed = value.windows.iter().find(|candidate| {
+        candidate.account_wide
+            && candidate.key == window.key
+            && candidate.group == window.group
+            && candidate.limit_id == window.limit_id
+            && same_role(candidate.role, window.role)
+            && Some(candidate.window_seconds) == window.window_seconds
+            && candidate.used_percent <= 100.0
+    })?;
+    Some(QuotaForecastObservation {
+        used_percent: observed.used_percent,
+        reset_at: DateTime::<Utc>::from_timestamp_millis(observed.reset_at_ms)?,
+        plan_type: value.plan_type,
+    })
+}
+
+fn validate(value: &QuotaForecast) -> Option<()> {
+    if value.windows.is_empty()
+        || value.windows.len() > 64
+        || value
+            .plan_type
+            .as_deref()
+            .is_some_and(|value| !valid_text(value))
+    {
+        return None;
+    }
+    let mut keys = BTreeSet::new();
+    for window in &value.windows {
+        if !keys.insert(&window.key)
+            || !valid_text(&window.key)
+            || !valid_text(&window.group)
+            || window
+                .limit_id
+                .as_deref()
+                .is_some_and(|value| !valid_text(value))
+            || window.window_seconds == 0
+            || i64::try_from(window.window_seconds).is_err()
+            || !window.used_percent.is_finite()
+            || window.used_percent < 0.0
+            || DateTime::<Utc>::from_timestamp_millis(window.reset_at_ms).is_none()
+        {
+            return None;
+        }
+    }
+    Some(())
+}
+
+fn valid_text(value: &str) -> bool {
+    !value.trim().is_empty() && value.len() <= 1024 && !value.chars().any(char::is_control)
+}
+
+fn same_role(left: Option<QuotaWindowRole>, right: Option<ProviderQuotaWindowRole>) -> bool {
+    matches!(
+        (left, right),
+        (None, None)
+            | (
+                Some(QuotaWindowRole::Primary),
+                Some(ProviderQuotaWindowRole::Primary)
+            )
+            | (
+                Some(QuotaWindowRole::Secondary),
+                Some(ProviderQuotaWindowRole::Secondary)
+            )
+            | (
+                Some(QuotaWindowRole::Monthly),
+                Some(ProviderQuotaWindowRole::Monthly)
+            )
+    )
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/invalidation.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/invalidation.rs
new file mode 100644
index 000000000..404b262a7
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/invalidation.rs
@@ -0,0 +1,88 @@
+use std::{collections::BTreeSet, time::Duration};
+
+use gateway_core::account::ProviderAccountId;
+use gateway_plugin_sdk::{
+    Stage,
+    call::provider::account::{AccountInvalidation, AccountOperation},
+};
+use tokio::time::Instant;
+
+use super::PluginProvider;
+
+const TIMEOUT: Duration = Duration::from_secs(2);
+const BATCH_SIZE: usize = 256;
+
+impl PluginProvider {
+    pub(super) async fn invalidate_unavailable(&self, account: &ProviderAccountId) {
+        if !self
+            .account_operations
+            .contains(&AccountOperation::Unavailable)
+        {
+            return;
+        }
+        let _ = self
+            .send_invalidation(
+                &AccountInvalidation::Unavailable {
+                    account_id: account.as_str().to_owned(),
+                },
+                Instant::now() + TIMEOUT,
+            )
+            .await;
+    }
+
+    pub(super) async fn invalidate_facts(&self, accounts: &[ProviderAccountId]) {
+        if !self
+            .account_operations
+            .contains(&AccountOperation::FactsChanged)
+        {
+            return;
+        }
+        // 一轮固定总预算，不能让账号数量把已经提交的管理请求拖成无界等待。
+        let deadline = Instant::now() + TIMEOUT;
+        let accounts: BTreeSet<_> = accounts.iter().collect();
+        let mut accounts = accounts.into_iter();
+        loop {
+            let account_ids: Vec<_> = accounts
+                .by_ref()
+                .take(BATCH_SIZE)
+                .map(|account| account.as_str().to_owned())
+                .collect();
+            if account_ids.is_empty()
+                || !self
+                    .send_invalidation(&AccountInvalidation::FactsChanged { account_ids }, deadline)
+                    .await
+            {
+                return;
+            }
+        }
+    }
+
+    async fn send_invalidation(&self, event: &AccountInvalidation, deadline: Instant) -> bool {
+        let remaining = deadline.saturating_duration_since(Instant::now());
+        if remaining.is_zero() {
+            tracing::warn!(provider = self.kind.as_str(), "插件账号失效通知总预算耗尽");
+            return false;
+        }
+        let Ok(payload) = serde_json::to_vec(event) else {
+            return false;
+        };
+        // 只发送变更身份，凭据仍需通过独立的账号回调读取。
+        let call = self.session.call(
+            "provider.account_changed",
+            self.session.context(Stage::Observation, remaining),
+            serde_json::json!({}),
+            payload,
+        );
+        let completed = matches!(
+            tokio::time::timeout_at(deadline, call).await,
+            Ok(Ok(reply)) if reply.result == serde_json::json!({}) && reply.payload.is_empty()
+        );
+        if !completed {
+            tracing::warn!(
+                provider = self.kind.as_str(),
+                "插件账号失效通知未完成，已提交账号事实保持不变"
+            );
+        }
+        completed
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/maintenance.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/maintenance.rs
new file mode 100644
index 000000000..770d866d8
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/maintenance.rs
@@ -0,0 +1,279 @@
+//! 宿主维护只复用已声明的 Provider 操作，不接受插件自定义任务名或周期。
+
+use super::management::ProviderOperation;
+use gateway_admin::{
+    model::{
+        AdminError, MutationActor, MutationContext,
+        accounts::AccountRecord,
+        plugins::instances::{PluginCapabilityBinding, PluginFailurePolicy},
+        provider_credentials::{
+            PluginAccountSaveReason, PreparedPluginAccountSave, ProviderQuotaRequest,
+        },
+    },
+    ports::{
+        plugin_accounts::PluginAccountAccess,
+        provider::{ProviderAdmin, ProviderAdminError},
+    },
+};
+use gateway_core::{
+    account::{CredentialState, ProviderAccountId},
+    task::WorkerKind,
+};
+use gateway_plugin_sdk::{Capability, Manifest, Stage, call::auth::CredentialOperation};
+use std::time::{Duration, SystemTime};
+
+use super::{PluginProvider, administration::invalid, management::ManagementOrigin};
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum MaintenanceKind {
+    Credentials,
+    Quota,
+    Models,
+    RequestProfiles,
+}
+
+impl MaintenanceKind {
+    pub(crate) const ALL: [Self; 4] = [
+        Self::Credentials,
+        Self::Quota,
+        Self::Models,
+        Self::RequestProfiles,
+    ];
+
+    pub(crate) const fn worker(self) -> (WorkerKind, &'static str, Duration) {
+        match self {
+            Self::Credentials => (
+                WorkerKind::OAuthRefresh,
+                "plugin-credentials",
+                Duration::from_secs(30),
+            ),
+            Self::Quota => (
+                WorkerKind::QuotaCatalogHealth,
+                "plugin-quota",
+                Duration::from_secs(300),
+            ),
+            Self::Models => (
+                WorkerKind::QuotaCatalogHealth,
+                "plugin-models",
+                Duration::from_secs(300),
+            ),
+            Self::RequestProfiles => (
+                WorkerKind::QuotaCatalogHealth,
+                "plugin-request-profiles",
+                Duration::from_secs(3600),
+            ),
+        }
+    }
+}
+
+impl PluginProvider {
+    pub(crate) fn maintenance_enabled(
+        &self,
+        manifest: &Manifest,
+        bindings: &[PluginCapabilityBinding],
+    ) -> Result<bool, AdminError> {
+        let mut selected = None;
+        for binding in bindings {
+            if crate::contribution::resolve(manifest, binding)?.capability
+                == Capability::Maintenance
+                && selected.replace(binding).is_some()
+            {
+                return Err(AdminError::invalid("同一插件实例的维护贡献项只能绑定一次"));
+            }
+        }
+        let Some(binding) = selected else {
+            return Ok(false);
+        };
+        if binding.stage != "maintenance"
+            || binding.failure_policy != PluginFailurePolicy::Reject
+            || binding.order != 0
+            || !binding.client_key_ids.is_empty()
+            || !binding.account_group_ids.is_empty()
+            || !binding.models.is_empty()
+            || (!binding.provider_ids.is_empty() && binding.provider_ids != [self.kind.as_str()])
+            || !manifest
+                .contributes
+                .get(&Capability::Maintenance)
+                .is_some_and(|declaration| declaration.stages == [Stage::Maintenance])
+            || !MaintenanceKind::ALL
+                .into_iter()
+                .any(|kind| self.supports_maintenance(kind))
+        {
+            return Err(AdminError::invalid(
+                "维护绑定需要 maintenance 阶段、宿主管理范围及可用的 Provider 维护操作",
+            ));
+        }
+        Ok(true)
+    }
+
+    pub(crate) fn supports_maintenance(&self, kind: MaintenanceKind) -> bool {
+        match kind {
+            MaintenanceKind::Credentials => self
+                .credential_operations
+                .contains(&CredentialOperation::Refresh),
+            MaintenanceKind::Quota => self.quota_enabled,
+            MaintenanceKind::Models => self.catalog.discovers_accounts(),
+            MaintenanceKind::RequestProfiles => {
+                self.request_profile_refresh_enabled && self.request_profiles.is_some()
+            }
+        }
+    }
+
+    pub(crate) async fn maintain_account(
+        &self,
+        kind: MaintenanceKind,
+        account: AccountRecord,
+        accounts: &dyn PluginAccountAccess,
+        task_id: &str,
+    ) -> Result<(), ProviderAdminError> {
+        // 禁用账号不由维护任务自行启用；过期 AT 仍可用 RT 刷新，但不使用它查询额度或目录。
+        if !account.enabled
+            || !(account.credential_state == CredentialState::Ready
+                || (kind == MaintenanceKind::Credentials
+                    && account.credential_state == CredentialState::Expired))
+            || account.provider_kind != self.kind
+        {
+            return Ok(());
+        }
+        let id = ProviderAccountId::new(account.id.clone()).map_err(|_| invalid())?;
+        let origin = ManagementOrigin::Maintenance {
+            task_id,
+            credential_revision: Some(account.credential_revision.get()),
+        };
+        match kind {
+            MaintenanceKind::Credentials => {
+                if !account.has_refresh_token {
+                    return Ok(());
+                }
+                let policy = self
+                    .ports
+                    .runtime_policy()
+                    .load_refresh_policy()
+                    .await
+                    .map_err(|_| super::administration::unavailable())?;
+                let now = SystemTime::now();
+                let due = account.next_refresh_at.map_or_else(
+                    || {
+                        account
+                            .access_token_expires_at
+                            .is_some_and(|expiry| policy.is_refresh_due(expiry.into(), now))
+                    },
+                    |next| SystemTime::from(next) <= now,
+                );
+                if !due {
+                    return Ok(());
+                }
+                let authentication_kind = account.authentication_kind.clone();
+                let prepared = self.rotate_credentials_from(account, None, origin).await?;
+                let (facts, guard) = prepared.into_parts();
+                // guard 保持全局刷新容量与账号 revision 租约，直到 Admin 原子提交和审计结束。
+                let saved = accounts
+                    .save(
+                        PreparedPluginAccountSave::Replace {
+                            facts,
+                            authentication_kind,
+                            reason: PluginAccountSaveReason::Maintenance,
+                        },
+                        &MutationContext {
+                            actor: MutationActor::System,
+                            request_id: task_id.to_owned(),
+                        },
+                    )
+                    .await;
+                guard.finish();
+                let saved = saved.map_err(super::management::map_account_save_error)?;
+                self.account_facts_changed(std::slice::from_ref(&saved.account_id))
+                    .await;
+            }
+            MaintenanceKind::Quota => {
+                self.account_quota_from(
+                    ProviderQuotaRequest {
+                        account_id: id,
+                        refresh: true,
+                        rolling_usage: None,
+                    },
+                    origin,
+                )
+                .await?;
+            }
+            MaintenanceKind::Models => {
+                self.account_models_from(&id, true, origin).await?;
+            }
+            MaintenanceKind::RequestProfiles => return Err(invalid()),
+        }
+        Ok(())
+    }
+
+    pub(crate) async fn restore_request_profiles(&self) -> Result<(), AdminError> {
+        let Some(profiles) = self
+            .request_profiles
+            .as_ref()
+            .filter(|_| self.request_profile_refresh_enabled)
+        else {
+            return Ok(());
+        };
+        let cached = self
+            .ports
+            .artifact_profiles()
+            .read(&self.kind, &self.profile_cache_key())
+            .await
+            .map_err(|_| AdminError::unavailable("插件版本资料缓存读取失败"))?;
+        if let Some(cached) = cached {
+            let refresh = serde_json::from_value(serde_json::Value::Object(
+                cached.profile().expose_to_provider().clone(),
+            ))
+            .map_err(|_| AdminError::invalid("插件版本资料缓存无效"))?;
+            profiles.apply_refresh(refresh, &self.kind)?;
+        }
+        Ok(())
+    }
+
+    pub(crate) async fn maintain_request_profiles(
+        &self,
+        task_id: &str,
+    ) -> Result<(), ProviderAdminError> {
+        use gateway_core::{account::OpaqueProviderData, provider_ports::ProviderArtifactProfile};
+        use gateway_plugin_sdk::call::provider::RequestProfileRefresh;
+        let profiles = self.request_profiles.as_ref().ok_or_else(invalid)?;
+        let call = self.management_call_from(
+            ProviderOperation::Profile,
+            None,
+            None,
+            ManagementOrigin::Maintenance {
+                task_id,
+                credential_revision: None,
+            },
+        )?;
+        let refresh: RequestProfileRefresh = call
+            .invoke("provider.request_profiles.refresh", &serde_json::json!({}))
+            .await?;
+        profiles
+            .validate_refresh(&refresh, &self.kind)
+            .map_err(|_| call.invalid_result())?;
+        let value = serde_json::to_value(&refresh).map_err(|_| invalid())?;
+        let object = value.as_object().cloned().ok_or_else(invalid)?;
+        let cache = self.ports.artifact_profiles();
+        cache
+            .replace_if_newer(
+                ProviderArtifactProfile::new(
+                    self.kind.clone(),
+                    self.profile_cache_key(),
+                    refresh.sequence,
+                    SystemTime::now(),
+                    OpaqueProviderData::new(object),
+                ),
+                Duration::from_secs(30 * 24 * 3600),
+            )
+            .await
+            .map_err(|_| super::administration::unavailable())?;
+        // 多宿主竞争时重读胜出的序号；一次请求已冻结的解析结果不受后续发布影响。
+        self.restore_request_profiles()
+            .await
+            .map_err(|_| call.invalid_result())
+    }
+
+    fn profile_cache_key(&self) -> String {
+        // 制品、实例配置与授权均参与指纹；旧插件轮次不可能覆盖新版本的资料。
+        format!("plugin-{}", self.authorization_binding)
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/management.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/management.rs
new file mode 100644
index 000000000..2bf1e83b5
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/management.rs
@@ -0,0 +1,311 @@
+use std::{sync::Arc, time::Duration};
+
+use gateway_admin::{
+    model::{AdminError, AdminErrorKind},
+    ports::provider::{ProviderAdminError, ProviderAdminErrorKind},
+};
+use gateway_core::{
+    account::{
+        CredentialState, LoadedCredential, OutboundProxy, ProviderAccount, ProviderAccountId,
+    },
+    routing::ProviderKind,
+    upstream::UpstreamSendState,
+};
+use gateway_plugin_sdk::{CallContext, ErrorCode, SendState, Stage};
+use serde::{Serialize, de::DeserializeOwned};
+
+use super::{
+    PluginProvider,
+    administration::{invalid, unavailable},
+};
+use crate::{RpcError, callback::NetworkScope};
+
+/// 业务调用的副作用分类，不作为安装授权或资源白名单。
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub(super) enum ProviderOperation {
+    Import,
+    Rotate,
+    Refresh,
+    Login,
+    Quota,
+    Models,
+    Profile,
+    ResetCredits,
+    ConsumeResetCredit,
+}
+
+#[derive(Clone, Copy)]
+pub(super) enum ManagementOrigin<'a> {
+    Interactive,
+    Maintenance {
+        task_id: &'a str,
+        credential_revision: Option<u64>,
+    },
+}
+
+/// 管理调用独立持有网络范围；账号和代理来自宿主，不接受插件覆盖。
+pub(super) struct ManagementCall<'a> {
+    provider: &'a PluginProvider,
+    context: CallContext,
+    pub(super) scope: Arc<NetworkScope>,
+    operation: ProviderOperation,
+}
+
+impl PluginProvider {
+    // 只读投影与不可逆操作共用身份边界；调用方决定失配意味着冲突还是结果未知。
+    pub(super) async fn ensure_management_identity(
+        &self,
+        account: &ProviderAccount,
+    ) -> Result<(), ProviderAdminError> {
+        let current = self
+            .ports
+            .accounts()
+            .get_account(account.id())
+            .await
+            .map_err(|_| unavailable())?;
+        if !current.is_some_and(|current| {
+            current.provider() == account.provider()
+                && current.revision() == account.revision()
+                && current.upstream_account_id() == account.upstream_account_id()
+                && current.upstream_user_id() == account.upstream_user_id()
+        }) {
+            return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+        }
+        Ok(())
+    }
+
+    pub(super) fn ensure_provider(&self, kind: &ProviderKind) -> Result<(), ProviderAdminError> {
+        if kind != &self.kind {
+            return Err(invalid());
+        }
+        Ok(())
+    }
+
+    pub(super) async fn load_management_credential(
+        &self,
+        id: &ProviderAccountId,
+    ) -> Result<LoadedCredential, ProviderAdminError> {
+        let account = self
+            .ports
+            .accounts()
+            .get_account(id)
+            .await
+            .map_err(|_| unavailable())?
+            .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::NotFound))?;
+        self.ensure_provider(account.provider())?;
+        self.ports
+            .accounts()
+            .load_credential(id, account.revision())
+            .await
+            .map_err(|error| {
+                ProviderAdminError::new(match error.kind() {
+                    gateway_core::error::StoreErrorKind::Conflict => {
+                        ProviderAdminErrorKind::Conflict
+                    }
+                    _ => ProviderAdminErrorKind::Unavailable,
+                })
+            })
+    }
+
+    pub(super) fn management_call(
+        &self,
+        operation: ProviderOperation,
+        account: Option<&ProviderAccount>,
+        proxy: Option<OutboundProxy>,
+    ) -> Result<ManagementCall<'_>, ProviderAdminError> {
+        self.management_call_from(operation, account, proxy, ManagementOrigin::Interactive)
+    }
+
+    pub(super) fn management_call_from(
+        &self,
+        operation: ProviderOperation,
+        account: Option<&ProviderAccount>,
+        proxy: Option<OutboundProxy>,
+        origin: ManagementOrigin<'_>,
+    ) -> Result<ManagementCall<'_>, ProviderAdminError> {
+        let (stage, request_id) = match origin {
+            ManagementOrigin::Interactive => (Stage::Management, None),
+            ManagementOrigin::Maintenance {
+                task_id,
+                credential_revision,
+            } => {
+                // 分页列举后账号可能被停用或冻结；按派发前重新装载的账号再校验一次。
+                if account.is_some_and(|account| {
+                    !account.enabled()
+                        || !(account.credential_state() == CredentialState::Ready
+                            || (operation == ProviderOperation::Refresh
+                                && account.credential_state() == CredentialState::Expired))
+                }) || credential_revision.is_some_and(|expected| {
+                    account.is_none_or(|account| account.revision().get() != expected)
+                }) {
+                    return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+                }
+                (Stage::Maintenance, Some(task_id.to_owned()))
+            }
+        };
+        let mut context = self.session.context(stage, Duration::from_secs(30));
+        context.request_id = request_id;
+        if let Some(account) = account {
+            context.account_id = Some(account.id().as_str().into());
+            context.credential_revision = Some(account.revision().get());
+        }
+        let scope = self
+            .callbacks
+            .prepare_management(&context, proxy)
+            .map_err(|_| invalid())?;
+        Ok(ManagementCall {
+            provider: self,
+            context,
+            scope,
+            operation,
+        })
+    }
+}
+
+impl ManagementCall<'_> {
+    fn mutating(&self) -> bool {
+        matches!(
+            self.operation,
+            ProviderOperation::Import
+                | ProviderOperation::Rotate
+                | ProviderOperation::Refresh
+                | ProviderOperation::Login
+                | ProviderOperation::ConsumeResetCredit
+        )
+    }
+
+    pub(super) async fn invoke_stream<T: DeserializeOwned>(
+        &self,
+        method: &str,
+        input: &impl Serialize,
+    ) -> Result<(T, crate::RpcStream), ProviderAdminError> {
+        let payload = serde_json::to_vec(input).map_err(|_| invalid())?;
+        let stream = self
+            .provider
+            .session
+            .call_stream(method, self.context.clone(), serde_json::json!({}), payload)
+            .await
+            .inspect_err(|error| self.record_rpc_failure(method, error))
+            .map_err(|error| self.map_error(error))?;
+        if !stream.initial.payload.is_empty() {
+            return Err(self.invalid_result());
+        }
+        let metadata = serde_json::from_value(stream.initial.result.clone())
+            .map_err(|_| self.invalid_result())?;
+        Ok((metadata, stream))
+    }
+
+    pub(super) async fn invoke<T: DeserializeOwned>(
+        &self,
+        method: &str,
+        input: &impl Serialize,
+    ) -> Result<T, ProviderAdminError> {
+        let payload = serde_json::to_vec(input).map_err(|_| invalid())?;
+        let reply = self
+            .provider
+            .session
+            .call(method, self.context.clone(), serde_json::json!({}), payload)
+            .await
+            .inspect_err(|error| self.record_rpc_failure(method, error))
+            .map_err(|error| self.map_error(error))?;
+        if reply.result != serde_json::json!({}) {
+            return Err(self.invalid_result());
+        }
+        serde_json::from_slice(&reply.payload).map_err(|_| self.invalid_result())
+    }
+
+    fn record_rpc_failure(&self, method: &str, error: &RpcError) {
+        // RpcError/PluginFault 的 Debug 只保留分类，不展开插件正文、凭据或 fault.message。
+        tracing::warn!(
+            provider = self.provider.kind.as_str(),
+            instance_id = self.context.instance_id,
+            generation = self.context.generation,
+            method,
+            error = ?error,
+            "插件管理 RPC 失败"
+        );
+    }
+
+    pub(super) async fn save_discovered_facts(
+        &self,
+        account: &ProviderAccount,
+        facts: gateway_plugin_sdk::call::auth::CredentialFacts,
+    ) -> Result<
+        gateway_admin::model::provider_credentials::PluginAccountSaveResult,
+        ProviderAdminError,
+    > {
+        self.provider
+            .callbacks
+            .save_discovered_facts(&self.context, &self.scope, account, facts)
+            .await
+            .map_err(map_account_save_error)
+    }
+
+    pub(super) fn invalid_result(&self) -> ProviderAdminError {
+        ProviderAdminError::new(
+            if self.operation == ProviderOperation::ConsumeResetCredit
+                || (self.mutating() && self.scope.send_state() != UpstreamSendState::NotSent)
+            {
+                ProviderAdminErrorKind::Ambiguous
+            } else {
+                ProviderAdminErrorKind::BadGateway
+            },
+        )
+    }
+
+    fn map_error(&self, error: RpcError) -> ProviderAdminError {
+        let sent = self.scope.send_state() != UpstreamSendState::NotSent
+            || matches!(&error, RpcError::Remote(error) if error.send_state != SendState::NotSent);
+        // 不可逆消费的对端消失或协议损坏时，即使没有观察到 HTTP，也不能证明消费未执行。
+        let uncertain_consumption = self.operation == ProviderOperation::ConsumeResetCredit
+            && matches!(
+                &error,
+                RpcError::Closed | RpcError::Protocol | RpcError::Timeout | RpcError::Cancelled
+            );
+        if self.mutating() && (sent || uncertain_consumption) {
+            return ProviderAdminError::new(ProviderAdminErrorKind::Ambiguous);
+        }
+        map_read_error(error)
+    }
+}
+
+pub(super) fn map_read_error(error: RpcError) -> ProviderAdminError {
+    ProviderAdminError::new(match error {
+        RpcError::Remote(error) => match error.code {
+            ErrorCode::InvalidInput | ErrorCode::Rejected | ErrorCode::PermissionDenied => {
+                ProviderAdminErrorKind::Invalid
+            }
+            ErrorCode::Unsupported => ProviderAdminErrorKind::Unsupported,
+            ErrorCode::Conflict => ProviderAdminErrorKind::Conflict,
+            ErrorCode::Uncertain => ProviderAdminErrorKind::Ambiguous,
+            _ => ProviderAdminErrorKind::Unavailable,
+        },
+        _ => ProviderAdminErrorKind::Unavailable,
+    })
+}
+
+pub(super) fn map_account_save_error(error: AdminError) -> ProviderAdminError {
+    ProviderAdminError::new(match error.kind() {
+        AdminErrorKind::Invalid | AdminErrorKind::Unauthorized | AdminErrorKind::Forbidden => {
+            ProviderAdminErrorKind::Invalid
+        }
+        AdminErrorKind::NotFound => ProviderAdminErrorKind::NotFound,
+        AdminErrorKind::Conflict => ProviderAdminErrorKind::Conflict,
+        AdminErrorKind::BadGateway => ProviderAdminErrorKind::BadGateway,
+        AdminErrorKind::UpstreamResultUnknown => ProviderAdminErrorKind::Ambiguous,
+        AdminErrorKind::Unavailable | AdminErrorKind::RateLimited => {
+            ProviderAdminErrorKind::Unavailable
+        }
+        AdminErrorKind::Internal => ProviderAdminErrorKind::Internal,
+    })
+}
+
+pub(super) fn account_request(
+    credential: &LoadedCredential,
+) -> gateway_plugin_sdk::call::provider::account::AccountRequest {
+    gateway_plugin_sdk::call::provider::account::AccountRequest {
+        account_id: credential.account.id().as_str().into(),
+        credential_revision: credential.account.revision().get(),
+        credential: credential.credential.expose_to_provider().clone(),
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/mod.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/mod.rs
new file mode 100644
index 000000000..1c27fc03d
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/mod.rs
@@ -0,0 +1,327 @@
+mod administration;
+mod authorization;
+mod billing;
+mod capabilities;
+mod catalog;
+mod configuration;
+mod continuation;
+mod credentials;
+mod drain;
+mod events;
+mod execution;
+mod forecast;
+mod invalidation;
+mod maintenance;
+mod management;
+mod profile;
+mod quota;
+mod request_profile;
+mod reset_credits;
+mod rotation;
+mod selection;
+
+pub(crate) use credentials::{timestamp as credential_timestamp, validate_facts};
+pub(crate) use drain::ContinuationDrain;
+pub(crate) use maintenance::MaintenanceKind;
+
+use std::{
+    collections::BTreeSet,
+    sync::{Arc, Weak},
+};
+
+use async_trait::async_trait;
+use gateway_admin::model::{AdminError, plugins::instances::PluginPermissionGrant};
+use gateway_core::{
+    account::ProviderAccountId,
+    concurrency::ConcurrencyWaitQueue,
+    engine::{
+        AttemptContext,
+        provider::{Provider, ProviderRequest, ProviderStream},
+    },
+    error::ProviderError,
+    provider_ports::ProviderStorePorts,
+    routing::{ProviderCatalogGeneration, ProviderKind, ProviderModelCapabilities},
+};
+use gateway_plugin_sdk::{
+    Capability, Manifest,
+    call::auth::CredentialOperation,
+    call::provider::{ProviderDescriptor, ProviderHttpMethod},
+};
+
+use crate::{RpcSession, callback::PluginCallbacks};
+
+pub(crate) struct ProviderInstanceBinding {
+    instance_id: String,
+    authorization: String,
+    continuation_authorization: String,
+    continuation_owner: String,
+    continuation_drain: Weak<drain::ContinuationDrain>,
+}
+
+impl ProviderInstanceBinding {
+    pub(crate) fn new(
+        instance_id: String,
+        authorization: String,
+        continuation_authorization: String,
+        continuation_drain: Weak<drain::ContinuationDrain>,
+    ) -> Self {
+        Self {
+            instance_id,
+            authorization,
+            continuation_authorization,
+            continuation_owner: uuid::Uuid::new_v4().to_string(),
+            continuation_drain,
+        }
+    }
+}
+
+pub(crate) struct PluginProvider {
+    kind: ProviderKind,
+    instance_id: String,
+    catalog: catalog::ModelCatalog,
+    exhaustive: bool,
+    pricing: Option<gateway_admin::model::pricing::ProviderPricingCatalog>,
+    input_formats: Arc<[String]>,
+    output_formats: BTreeSet<String>,
+    session: Arc<RpcSession>,
+    callbacks: Arc<PluginCallbacks>,
+    ports: ProviderStorePorts,
+    credential_operations: BTreeSet<CredentialOperation>,
+    account_operations: BTreeSet<gateway_plugin_sdk::call::provider::account::AccountOperation>,
+    credential_inputs:
+        std::collections::BTreeMap<CredentialOperation, capabilities::CredentialInput>,
+    account_configuration: Option<configuration::PreparedAccountConfiguration>,
+    request_profiles: Option<request_profile::PreparedRequestProfiles>,
+    request_profile_refresh_enabled: bool,
+    http_endpoints: std::collections::BTreeMap<String, BTreeSet<ProviderHttpMethod>>,
+    quota_enabled: bool,
+    authorization_binding: String,
+    continuation: continuation::ContinuationIdentity,
+    continuation_drain: Weak<drain::ContinuationDrain>,
+    waiting: ConcurrencyWaitQueue<ProviderAccountId>,
+}
+
+impl PluginProvider {
+    pub(crate) fn prepare(
+        descriptor: ProviderDescriptor,
+        binding: ProviderInstanceBinding,
+        manifest: &Manifest,
+        grants: &[PluginPermissionGrant],
+        session: Arc<RpcSession>,
+        ports: ProviderStorePorts,
+        callbacks: Arc<PluginCallbacks>,
+    ) -> Result<Self, AdminError> {
+        let kind = ProviderKind::new(descriptor.id)
+            .map_err(|_| AdminError::invalid("插件 Provider ID 无效"))?;
+        let authorization_binding = binding.authorization.clone();
+        let continuation = continuation::ContinuationIdentity::prepare(
+            kind.as_str().to_owned(),
+            binding.authorization,
+            binding.continuation_authorization,
+            descriptor.continuation_state,
+            binding.continuation_owner,
+        )?;
+        let request_profiles =
+            request_profile::PreparedRequestProfiles::prepare(descriptor.request_profiles, &kind)?;
+        let request_profile_refresh_enabled = manifest
+            .contributes
+            .get(&Capability::RequestProfile)
+            .is_some_and(|declaration| {
+                declaration
+                    .stages
+                    .contains(&gateway_plugin_sdk::Stage::Maintenance)
+            });
+        if request_profile_refresh_enabled && request_profiles.is_none() {
+            return Err(AdminError::invalid("版本资料维护需要注册初始请求画像目录"));
+        }
+        let http_endpoints = prepare_http_endpoints(descriptor.http_endpoints)?;
+        let executor = manifest
+            .contributes
+            .get(&Capability::Executor)
+            .ok_or_else(|| AdminError::invalid("Provider 未声明执行能力"))?;
+        if !grants.iter().any(|grant| grant.permission == "accounts") {
+            return Err(AdminError::invalid("Provider 执行需要账号访问权限"));
+        }
+        let credential_operations: BTreeSet<_> =
+            descriptor.credential_operations.iter().copied().collect();
+        let authentication = manifest
+            .contributes
+            .contains_key(&Capability::Authentication);
+        if credential_operations.len() != descriptor.credential_operations.len()
+            || authentication == credential_operations.is_empty()
+        {
+            return Err(AdminError::invalid("插件凭据操作与认证能力声明不符"));
+        }
+        let account_operations: BTreeSet<_> =
+            descriptor.account_operations.iter().copied().collect();
+        let account_management = manifest.contributes.get(&Capability::AccountManagement);
+        if account_operations.len() != descriptor.account_operations.len()
+            || account_management.is_some() == account_operations.is_empty()
+            || account_management.is_some_and(|declaration| {
+                account_operations.iter().any(|operation| {
+                    use gateway_plugin_sdk::{Stage, call::provider::account::AccountOperation};
+                    let stage = match operation {
+                        AccountOperation::Unavailable | AccountOperation::FactsChanged => {
+                            Stage::Observation
+                        }
+                        _ => Stage::Management,
+                    };
+                    !declaration.stages.contains(&stage)
+                })
+            })
+        {
+            return Err(AdminError::invalid("插件账号操作与管理能力声明不符"));
+        }
+        let account_configuration = configuration::PreparedAccountConfiguration::prepare(
+            descriptor.account_configuration,
+            &credential_operations,
+            descriptor
+                .credential_input_schemas
+                .get(&CredentialOperation::Rotate),
+        )?;
+        let credential_inputs = capabilities::prepare_inputs(
+            &credential_operations,
+            descriptor.credential_input_schemas,
+        )?;
+        let input_formats = executor
+            .input_formats
+            .iter()
+            .cloned()
+            .collect::<BTreeSet<_>>();
+        if descriptor.models.len() > 4096
+            || executor.input_formats.is_empty()
+            || input_formats.len() != executor.input_formats.len()
+            || executor.output_formats.is_empty()
+        {
+            return Err(AdminError::invalid("Provider 模型目录或协议声明不合法"));
+        }
+        let pricing = billing::prepare(descriptor.billing, manifest)?;
+        let catalog = catalog::ModelCatalog::prepare(
+            descriptor.models,
+            descriptor.model_discovery,
+            manifest,
+        )?;
+        Ok(Self {
+            kind,
+            instance_id: binding.instance_id,
+            continuation,
+            continuation_drain: binding.continuation_drain,
+            catalog,
+            exhaustive: descriptor.exhaustive,
+            pricing,
+            input_formats: executor.input_formats.clone().into(),
+            output_formats: executor.output_formats.iter().cloned().collect(),
+            session,
+            callbacks,
+            ports,
+            credential_operations,
+            account_operations,
+            credential_inputs,
+            account_configuration,
+            request_profiles,
+            request_profile_refresh_enabled,
+            http_endpoints,
+            quota_enabled: manifest.contributes.contains_key(&Capability::Quota),
+            authorization_binding,
+            waiting: ConcurrencyWaitQueue::default(),
+        })
+    }
+
+    pub(crate) fn register_continuation(self: &Arc<Self>) -> Result<(), AdminError> {
+        self.continuation_drain
+            .upgrade()
+            .ok_or_else(|| AdminError::unavailable("插件续写执行注册表不可用"))?
+            .register(self)
+    }
+
+    pub(crate) fn retire_continuation(self: &Arc<Self>) -> bool {
+        self.continuation_drain
+            .upgrade()
+            .is_some_and(|drain| drain.retire(Arc::clone(self)))
+    }
+}
+
+fn prepare_http_endpoints(
+    endpoints: Vec<gateway_plugin_sdk::call::provider::ProviderHttpEndpoint>,
+) -> Result<std::collections::BTreeMap<String, BTreeSet<ProviderHttpMethod>>, AdminError> {
+    if endpoints.len() > 64 {
+        return Err(AdminError::invalid("插件 HTTP 端点超过 64 项"));
+    }
+    let mut prepared = std::collections::BTreeMap::new();
+    for endpoint in endpoints {
+        let valid_id = !endpoint.id.is_empty()
+            && endpoint.id.len() <= 64
+            && endpoint.id != "."
+            && endpoint.id != ".."
+            && endpoint
+                .id
+                .bytes()
+                .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.'));
+        let methods = endpoint.methods.iter().copied().collect::<BTreeSet<_>>();
+        if !valid_id
+            || methods.is_empty()
+            || methods.len() != endpoint.methods.len()
+            || prepared.insert(endpoint.id, methods).is_some()
+        {
+            return Err(AdminError::invalid("插件 HTTP 端点声明无效或重复"));
+        }
+    }
+    Ok(prepared)
+}
+
+#[async_trait]
+impl Provider for PluginProvider {
+    fn resolve_request_profile(
+        &self,
+        configuration: &gateway_core::account::OpaqueProviderData,
+    ) -> Result<gateway_core::account::OpaqueProviderData, ProviderError> {
+        match &self.request_profiles {
+            Some(profiles) => profiles.resolve(configuration),
+            None => Err(request_profile::invalid_request_profile()),
+        }
+    }
+    fn default_request_profile(
+        &self,
+    ) -> Result<Option<gateway_core::account::OpaqueProviderData>, ProviderError> {
+        Ok(self
+            .request_profiles
+            .as_ref()
+            .map(request_profile::PreparedRequestProfiles::default_resolved))
+    }
+    fn name(&self) -> &str {
+        self.kind.as_str()
+    }
+    fn catalog_generation(&self) -> ProviderCatalogGeneration {
+        self.catalog.generation()
+    }
+    fn model_catalog_is_exhaustive(&self) -> bool {
+        // 账号目录会随授权与上游事实变化，全局缺项不能替代单账号的完整目录判断。
+        self.exhaustive && !self.catalog.discovers_accounts()
+    }
+    async fn query_model_capabilities(
+        &self,
+    ) -> Result<Vec<ProviderModelCapabilities>, ProviderError> {
+        self.discover_model_capabilities().await
+    }
+    async fn query_client_model_catalog(
+        &self,
+        scope: &gateway_core::account::scope::FrozenAccountScope,
+        _protocol: &str,
+        _client_version: &str,
+    ) -> Result<
+        Option<Vec<gateway_core::routing::ProviderModelDescriptor>>,
+        gateway_core::routing::ProviderCatalogUnavailable,
+    > {
+        if !self.catalog.discovers_accounts() {
+            return Ok(None);
+        }
+        self.discover_client_catalog(scope).await.map(Some)
+    }
+    async fn execute(
+        self: Arc<Self>,
+        request: ProviderRequest,
+        context: AttemptContext,
+    ) -> Result<ProviderStream, ProviderError> {
+        self.prepare_execution(request, context).await
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/profile.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/profile.rs
new file mode 100644
index 000000000..2d68525ec
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/profile.rs
@@ -0,0 +1,266 @@
+use std::{collections::BTreeSet, sync::Arc};
+
+use super::management::ProviderOperation;
+use chrono::{DateTime, NaiveDate, Utc};
+use gateway_admin::{
+    model::provider_credentials::{
+        ProviderProfileActivityInsights, ProviderProfileAvatar, ProviderProfileAvatarStreamError,
+        ProviderProfileDailyUsage, ProviderProfileInvocation, ProviderProfileStatistics,
+        ProviderProfileStatisticsSummary, ProviderSubscription,
+    },
+    ports::provider::{ProviderAdminError, ProviderAdminErrorKind},
+};
+use gateway_core::account::{LoadedCredential, ProviderAccountId};
+use gateway_plugin_sdk::call::provider::account::{self as wire, AccountOperation};
+
+use super::{PluginProvider, administration::unsupported, management::account_request};
+
+const MAX_PROFILE_ITEMS: usize = 4096;
+const MAX_PROFILE_TEXT_BYTES: usize = 1024;
+
+impl PluginProvider {
+    async fn profile_credential(
+        &self,
+        id: &ProviderAccountId,
+        operation: AccountOperation,
+    ) -> Result<LoadedCredential, ProviderAdminError> {
+        if !self.account_operations.contains(&operation) {
+            return Err(unsupported());
+        }
+        self.load_management_credential(id).await
+    }
+
+    pub(super) async fn account_subscription(
+        &self,
+        id: &ProviderAccountId,
+    ) -> Result<Option<ProviderSubscription>, ProviderAdminError> {
+        let credential = self
+            .profile_credential(id, AccountOperation::Subscription)
+            .await?;
+        let call = self.management_call(
+            ProviderOperation::Profile,
+            Some(&credential.account),
+            credential.account.outbound_proxy().cloned(),
+        )?;
+        let result: Option<wire::Subscription> = call
+            .invoke("provider.subscription", &account_request(&credential))
+            .await?;
+        self.ensure_management_identity(&credential.account).await?;
+        result.map(subscription).transpose()
+    }
+
+    pub(super) async fn account_profile(
+        &self,
+        id: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, ProviderAdminError> {
+        let credential = self
+            .profile_credential(id, AccountOperation::Profile)
+            .await?;
+        let call = self.management_call(
+            ProviderOperation::Profile,
+            Some(&credential.account),
+            credential.account.outbound_proxy().cloned(),
+        )?;
+        let result: wire::Profile = call
+            .invoke("provider.profile", &account_request(&credential))
+            .await?;
+        self.ensure_management_identity(&credential.account).await?;
+        if result.image_url.is_some()
+            && !self.account_operations.contains(&AccountOperation::Avatar)
+        {
+            return Err(invalid_result());
+        }
+        profile(result)
+    }
+
+    pub(super) async fn account_avatar(
+        &self,
+        id: &ProviderAccountId,
+    ) -> Result<ProviderProfileAvatar, ProviderAdminError> {
+        let credential = self
+            .profile_credential(id, AccountOperation::Avatar)
+            .await?;
+        let call = self.management_call(
+            ProviderOperation::Profile,
+            Some(&credential.account),
+            credential.account.outbound_proxy().cloned(),
+        )?;
+        let (metadata, stream): (wire::Avatar, _) = call
+            .invoke_stream("provider.avatar", &account_request(&credential))
+            .await?;
+        for header in [metadata.content_type.as_deref(), metadata.etag.as_deref()]
+            .into_iter()
+            .flatten()
+        {
+            if header.len() > MAX_PROFILE_TEXT_BYTES
+                || !header.bytes().all(|byte| (0x20..=0x7e).contains(&byte))
+            {
+                return Err(invalid_result());
+            }
+        }
+        self.ensure_management_identity(&credential.account).await?;
+        let length = metadata.content_length;
+        let body = futures::stream::try_unfold(
+            (stream, Arc::clone(&call.scope), 0_u64),
+            move |(mut stream, scope, received)| async move {
+                match stream
+                    .next()
+                    .await
+                    .map_err(|_| ProviderProfileAvatarStreamError)?
+                {
+                    Some(bytes) => {
+                        let received = received
+                            .checked_add(bytes.len() as u64)
+                            .ok_or(ProviderProfileAvatarStreamError)?;
+                        if length.is_some_and(|length| received > length) {
+                            return Err(ProviderProfileAvatarStreamError);
+                        }
+                        Ok(Some((bytes.into(), (stream, scope, received))))
+                    }
+                    None if length.is_none_or(|length| received == length) => Ok(None),
+                    None => Err(ProviderProfileAvatarStreamError),
+                }
+            },
+        );
+        Ok(ProviderProfileAvatar {
+            content_type: metadata.content_type,
+            content_length: metadata.content_length,
+            etag: metadata.etag,
+            body: Box::pin(body),
+        })
+    }
+}
+
+fn subscription(value: wire::Subscription) -> Result<ProviderSubscription, ProviderAdminError> {
+    let starts_at = value.starts_at_ms.map(timestamp).transpose()?;
+    let expires_at = timestamp(value.expires_at_ms)?;
+    if starts_at.is_some_and(|start| start > expires_at) {
+        return Err(invalid_result());
+    }
+    Ok(ProviderSubscription {
+        starts_at,
+        expires_at,
+        will_renew: value.will_renew,
+        billing_period: text(value.billing_period)?,
+        billing_currency: text(value.billing_currency)?,
+        observed_at: timestamp(value.observed_at_ms)?,
+    })
+}
+
+fn profile(value: wire::Profile) -> Result<ProviderProfileStatistics, ProviderAdminError> {
+    let image_url = text(value.image_url)?;
+    if let Some(source) = &image_url {
+        let url = url::Url::parse(source).map_err(|_| invalid_result())?;
+        if !matches!(url.scheme(), "http" | "https")
+            || url.host_str().is_none()
+            || !url.username().is_empty()
+            || url.password().is_some()
+        {
+            return Err(invalid_result());
+        }
+    }
+    let daily_usage = value
+        .daily_usage
+        .map(|values| {
+            if values.len() > MAX_PROFILE_ITEMS {
+                return Err(invalid_result());
+            }
+            let mut dates = BTreeSet::new();
+            values
+                .into_iter()
+                .map(|value| {
+                    let date = NaiveDate::parse_from_str(&value.date, "%Y-%m-%d")
+                        .map_err(|_| invalid_result())?;
+                    if value.date.len() != 10
+                        || date.to_string() != value.date
+                        || !dates.insert(date)
+                    {
+                        return Err(invalid_result());
+                    }
+                    Ok(ProviderProfileDailyUsage {
+                        date,
+                        tokens: value.tokens,
+                    })
+                })
+                .collect::<Result<Vec<_>, ProviderAdminError>>()
+        })
+        .transpose()?;
+    let insights = value.activity_insights;
+    let invocations = insights
+        .invocations
+        .map(|values| {
+            if values.len() > MAX_PROFILE_ITEMS {
+                return Err(invalid_result());
+            }
+            values
+                .into_iter()
+                .map(|value| {
+                    validate_text(&value.invocation_type)?;
+                    if value.invocation_type.is_empty() {
+                        return Err(invalid_result());
+                    }
+                    Ok(ProviderProfileInvocation {
+                        invocation_type: value.invocation_type,
+                        plugin_id: text(value.plugin_id)?,
+                        plugin_name: text(value.plugin_name)?,
+                        skill_id: text(value.skill_id)?,
+                        skill_name: text(value.skill_name)?,
+                        usage_count: value.usage_count,
+                    })
+                })
+                .collect::<Result<Vec<_>, ProviderAdminError>>()
+        })
+        .transpose()?;
+    Ok(ProviderProfileStatistics {
+        display_name: text(value.display_name)?,
+        username: text(value.username)?,
+        image_url,
+        has_stats_error: value.has_stats_error,
+        summary: ProviderProfileStatisticsSummary {
+            total_text_tokens: value.summary.total_text_tokens,
+            peak_tokens: value.summary.peak_tokens,
+            longest_task_duration_ms: value.summary.longest_task_duration_ms,
+            current_streak_days: value.summary.current_streak_days,
+            longest_streak_days: value.summary.longest_streak_days,
+        },
+        daily_usage,
+        activity_insights: ProviderProfileActivityInsights {
+            fast_mode_percent: percent(insights.fast_mode_percent)?,
+            reasoning_effort: text(insights.reasoning_effort)?,
+            reasoning_effort_percent: percent(insights.reasoning_effort_percent)?,
+            skills_explored: insights.skills_explored,
+            total_skills_used: insights.total_skills_used,
+            total_threads: insights.total_threads,
+            invocations,
+        },
+    })
+}
+
+fn text(value: Option<String>) -> Result<Option<String>, ProviderAdminError> {
+    if let Some(value) = &value {
+        validate_text(value)?;
+    }
+    Ok(value)
+}
+
+fn validate_text(value: &str) -> Result<(), ProviderAdminError> {
+    if value.len() > MAX_PROFILE_TEXT_BYTES || value.chars().any(char::is_control) {
+        return Err(invalid_result());
+    }
+    Ok(())
+}
+
+fn percent(value: Option<f64>) -> Result<Option<f64>, ProviderAdminError> {
+    if value.is_some_and(|value| !value.is_finite() || !(0.0..=100.0).contains(&value)) {
+        return Err(invalid_result());
+    }
+    Ok(value)
+}
+
+fn timestamp(value: i64) -> Result<DateTime<Utc>, ProviderAdminError> {
+    DateTime::from_timestamp_millis(value).ok_or_else(invalid_result)
+}
+
+fn invalid_result() -> ProviderAdminError {
+    ProviderAdminError::new(ProviderAdminErrorKind::BadGateway)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/quota.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/quota.rs
new file mode 100644
index 000000000..050d0466d
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/quota.rs
@@ -0,0 +1,239 @@
+use std::{collections::BTreeSet, time::SystemTime};
+
+use super::management::ProviderOperation;
+use chrono::{DateTime, Utc};
+use gateway_admin::{
+    model::provider_credentials::{
+        ProviderDocument, ProviderQuota, ProviderQuotaRequest, ProviderQuotaWindow,
+        ProviderQuotaWindowRole, QuotaLocalUsageAttribution,
+    },
+    ports::provider::{ProviderAdminError, ProviderAdminErrorKind},
+};
+use gateway_core::account::{
+    OpaqueProviderData, QuotaEvidence, QuotaObservation, QuotaState, QuotaWriteOutcome,
+};
+use gateway_plugin_sdk::call::provider::quota::{self as wire, QuotaAccess};
+
+use super::{
+    PluginProvider,
+    administration::{invalid, unavailable, unsupported},
+    credentials::timestamp,
+    management::ManagementOrigin,
+};
+
+impl PluginProvider {
+    pub(super) async fn account_quota(
+        &self,
+        request: ProviderQuotaRequest,
+    ) -> Result<ProviderQuota, ProviderAdminError> {
+        self.account_quota_from(request, ManagementOrigin::Interactive)
+            .await
+    }
+
+    pub(super) async fn account_quota_from(
+        &self,
+        request: ProviderQuotaRequest,
+        origin: ManagementOrigin<'_>,
+    ) -> Result<ProviderQuota, ProviderAdminError> {
+        if !self.quota_enabled {
+            return Err(unsupported());
+        }
+        let store = self.ports.accounts();
+        let account = store
+            .get_account(&request.account_id)
+            .await
+            .map_err(|_| unavailable())?
+            .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::NotFound))?;
+        self.ensure_provider(account.provider())?;
+        let observation = if request.refresh {
+            let credential = self.load_management_credential(&request.account_id).await?;
+            // 按发起时间排序，迟到响应不能覆盖后来发起并已提交的额度观察。
+            // 持久化事实采用 PostgreSQL 的微秒精度，首次返回与恢复后的投影保持一致。
+            let observed_at = DateTime::from_timestamp_micros(Utc::now().timestamp_micros())
+                .ok_or_else(unavailable)?
+                .into();
+            let call = self.management_call_from(
+                ProviderOperation::Quota,
+                Some(&credential.account),
+                credential.account.outbound_proxy().cloned(),
+                origin,
+            )?;
+            let quota: wire::Quota = call
+                .invoke(
+                    "provider.quota",
+                    &serde_json::json!({
+                        "account_id":credential.account.id().as_str(),
+                        "credential_revision":credential.account.revision().get(),
+                        "credential":credential.credential.expose_to_provider(),
+                    }),
+                )
+                .await?;
+            validate(&quota).map_err(|_| call.invalid_result())?;
+            let state =
+                quota_state(&quota.access, observed_at).map_err(|_| call.invalid_result())?;
+            let plan_type = quota.plan_type.clone();
+            let value = serde_json::to_value(&quota).map_err(|_| invalid())?;
+            let observation = QuotaObservation {
+                account_id: request.account_id,
+                expected_revision: credential.account.revision(),
+                quota: OpaqueProviderData::new(
+                    serde_json::json!({"plugin_quota_v1":value})
+                        .as_object()
+                        .cloned()
+                        .ok_or_else(invalid)?,
+                ),
+                plan_type,
+                observed_at,
+                state,
+            };
+            if store
+                .compare_and_swap_quota(observation.clone())
+                .await
+                .map_err(|_| unavailable())?
+                != QuotaWriteOutcome::Updated
+            {
+                return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+            }
+            Some(observation)
+        } else {
+            store
+                .get_quotas(std::slice::from_ref(&request.account_id))
+                .await
+                .map_err(|_| unavailable())?
+                .into_iter()
+                .find(|observation| {
+                    observation.account_id == request.account_id
+                        && observation.expected_revision == account.revision()
+                })
+        };
+        let Some(observation) = observation else {
+            return Ok(ProviderQuota {
+                plan_type: None,
+                observed_at: None,
+                refresh_token_expires_at: None,
+                windows: vec![],
+                limit_reached: false,
+                provider_data: None,
+            });
+        };
+        let quota: wire::Quota = serde_json::from_value(
+            observation
+                .quota
+                .expose_to_provider()
+                .get("plugin_quota_v1")
+                .cloned()
+                .ok_or_else(invalid)?,
+        )
+        .map_err(|_| invalid())?;
+        validate(&quota)?;
+        present(quota, DateTime::<Utc>::from(observation.observed_at))
+    }
+}
+
+fn validate(quota: &wire::Quota) -> Result<(), ProviderAdminError> {
+    let valid_text = |value: &str| {
+        !value.trim().is_empty() && value.len() <= 1024 && !value.chars().any(char::is_control)
+    };
+    if quota.windows.len() > 64
+        || quota
+            .plan_type
+            .as_ref()
+            .is_some_and(|plan| !valid_text(plan))
+    {
+        return Err(invalid());
+    }
+    timestamp(quota.refresh_token_expires_at_ms)?;
+    let mut keys = BTreeSet::new();
+    for window in &quota.windows {
+        if !keys.insert(&window.key)
+            || ![&window.key, &window.group, &window.label]
+                .into_iter()
+                .all(|value| valid_text(value))
+            || [&window.limit_id, &window.limit_name]
+                .into_iter()
+                .flatten()
+                .any(|value| !valid_text(value))
+            || window.window_seconds == Some(0)
+            || window
+                .used_percent
+                .is_some_and(|value| !value.is_finite() || value < 0.0)
+        {
+            return Err(invalid());
+        }
+        timestamp(window.reset_at_ms)?;
+    }
+    quota_state(&quota.access, SystemTime::now())?;
+    Ok(())
+}
+
+fn quota_state(
+    access: &QuotaAccess,
+    observed_at: SystemTime,
+) -> Result<QuotaState, ProviderAdminError> {
+    Ok(match access {
+        QuotaAccess::Unknown => QuotaState::observed_unknown(observed_at),
+        QuotaAccess::Allowed => QuotaState::allowed(observed_at),
+        QuotaAccess::Exhausted {
+            evidence,
+            reset_at_ms,
+        } => QuotaState::exhausted(
+            match evidence {
+                wire::QuotaEvidence::ProviderDenied => QuotaEvidence::ProviderDenied,
+                wire::QuotaEvidence::AccountLimitReached => QuotaEvidence::AccountLimitReached,
+                wire::QuotaEvidence::UsageLimitReached => QuotaEvidence::UsageLimitReached,
+                wire::QuotaEvidence::PaymentRequired => QuotaEvidence::PaymentRequired,
+            },
+            observed_at,
+            timestamp(*reset_at_ms)?.map(Into::into),
+        ),
+    })
+}
+
+fn present(
+    quota: wire::Quota,
+    observed_at: DateTime<Utc>,
+) -> Result<ProviderQuota, ProviderAdminError> {
+    let limit_reached = matches!(quota.access, QuotaAccess::Exhausted { .. })
+        || quota.windows.iter().any(|window| window.limit_reached);
+    let windows = quota
+        .windows
+        .into_iter()
+        .map(|window| {
+            Ok(ProviderQuotaWindow {
+                key: window.key,
+                group: window.group,
+                label: window.label,
+                limit_id: window.limit_id,
+                limit_name: window.limit_name,
+                role: window.role.map(|role| match role {
+                    wire::QuotaWindowRole::Primary => ProviderQuotaWindowRole::Primary,
+                    wire::QuotaWindowRole::Secondary => ProviderQuotaWindowRole::Secondary,
+                    wire::QuotaWindowRole::Monthly => ProviderQuotaWindowRole::Monthly,
+                }),
+                local_usage_attribution: if window.account_wide {
+                    QuotaLocalUsageAttribution::AccountWide
+                } else {
+                    QuotaLocalUsageAttribution::Unavailable
+                },
+                window_seconds: window.window_seconds,
+                used_percent: window.used_percent,
+                reset_at: timestamp(window.reset_at_ms)?,
+                limit_reached: window.limit_reached,
+                local_usage: None,
+                provider_data: window
+                    .provider_data
+                    .map(|value| ProviderDocument::new(OpaqueProviderData::new(value))),
+            })
+        })
+        .collect::<Result<_, ProviderAdminError>>()?;
+    Ok(ProviderQuota {
+        plan_type: quota.plan_type,
+        observed_at: Some(observed_at),
+        refresh_token_expires_at: timestamp(quota.refresh_token_expires_at_ms)?,
+        windows,
+        limit_reached,
+        provider_data: quota
+            .provider_data
+            .map(|value| ProviderDocument::new(OpaqueProviderData::new(value))),
+    })
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/request_profile.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/request_profile.rs
new file mode 100644
index 000000000..788dc31d3
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/request_profile.rs
@@ -0,0 +1,476 @@
+//! 请求画像在准备和版本刷新时校验；同步路径读取本地目录快照，已解析请求不随刷新变化。
+
+use std::{
+    collections::BTreeSet,
+    sync::{Arc, RwLock},
+};
+
+use chrono::{DateTime, Utc};
+use gateway_admin::{
+    model::{
+        AdminError,
+        observability::{
+            DashboardDesktopRelease, DashboardWireAttribute, DashboardWireProfile,
+            DashboardWireTarget, DesktopReleaseStatus,
+        },
+    },
+    ports::provider::{ProviderAdminError, ProviderAdminErrorKind},
+};
+use gateway_core::{
+    account::OpaqueProviderData,
+    error::{ProviderError, ProviderErrorKind},
+    routing::ProviderKind,
+    upstream::UpstreamSendState,
+};
+use gateway_plugin_sdk::call::provider::{
+    RequestProfileDescriptor, RequestProfileOption, RequestProfilePresentation,
+    RequestProfileRelease, RequestProfileReleaseStatus,
+};
+use serde_json::{Map, Value, json};
+use sha2::{Digest as _, Sha256};
+
+const MAXIMUM_OPTIONS: usize = 128;
+const MAXIMUM_DOCUMENT_BYTES: usize = 64 * 1024;
+const MAXIMUM_ID_BYTES: usize = 64;
+const MAXIMUM_LABEL_BYTES: usize = 128;
+const MAXIMUM_DESCRIPTION_BYTES: usize = 1024;
+const MAXIMUM_PRESENTATION_TEXT_BYTES: usize = 4096;
+const MAXIMUM_ATTRIBUTES: usize = 64;
+
+pub(super) struct PreparedRequestProfiles {
+    current: RwLock<Arc<ProfileDirectory>>,
+}
+
+struct ProfileDirectory {
+    sequence: u64,
+    fingerprint: [u8; 32],
+    default: usize,
+    options: Vec<PreparedRequestProfile>,
+}
+
+struct PreparedRequestProfile {
+    option: RequestProfileOption,
+    presentation: DashboardWireProfile,
+}
+
+impl PreparedRequestProfiles {
+    pub(super) fn prepare(
+        descriptor: Option<RequestProfileDescriptor>,
+        provider: &ProviderKind,
+    ) -> Result<Option<Self>, AdminError> {
+        descriptor
+            .map(|descriptor| {
+                ProfileDirectory::prepare_descriptor(descriptor, provider).map(|directory| Self {
+                    current: RwLock::new(Arc::new(directory)),
+                })
+            })
+            .transpose()
+    }
+
+    fn snapshot(&self) -> Arc<ProfileDirectory> {
+        self.current
+            .read()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .clone()
+    }
+
+    pub(super) fn apply_refresh(
+        &self,
+        refresh: gateway_plugin_sdk::call::provider::RequestProfileRefresh,
+        provider: &ProviderKind,
+    ) -> Result<(), AdminError> {
+        let next = ProfileDirectory::prepare_refresh(refresh, provider)?;
+        let mut current = self
+            .current
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        next.validate_successor(&current)?;
+        if next.sequence > current.sequence {
+            *current = Arc::new(next);
+        }
+        Ok(())
+    }
+
+    pub(super) fn validate_refresh(
+        &self,
+        refresh: &gateway_plugin_sdk::call::provider::RequestProfileRefresh,
+        provider: &ProviderKind,
+    ) -> Result<(), AdminError> {
+        ProfileDirectory::prepare_refresh(refresh.clone(), provider)?
+            .validate_successor(&self.snapshot())
+    }
+
+    pub(super) fn resolve(
+        &self,
+        configuration: &OpaqueProviderData,
+    ) -> Result<OpaqueProviderData, ProviderError> {
+        self.snapshot().resolve(configuration)
+    }
+    pub(super) fn default_resolved(&self) -> OpaqueProviderData {
+        self.snapshot().default_resolved()
+    }
+    pub(super) fn default_configuration(&self) -> OpaqueProviderData {
+        self.snapshot().default_configuration()
+    }
+    pub(super) fn options(&self) -> Result<OpaqueProviderData, ProviderAdminError> {
+        self.snapshot().options()
+    }
+    pub(super) fn preview(
+        &self,
+        configuration: &OpaqueProviderData,
+    ) -> Result<OpaqueProviderData, ProviderAdminError> {
+        self.snapshot().preview(configuration)
+    }
+    pub(super) fn dashboard(
+        &self,
+        configuration: Option<&OpaqueProviderData>,
+    ) -> Option<DashboardWireProfile> {
+        self.snapshot().dashboard(configuration)
+    }
+}
+
+impl ProfileDirectory {
+    fn prepare_refresh(
+        refresh: gateway_plugin_sdk::call::provider::RequestProfileRefresh,
+        provider: &ProviderKind,
+    ) -> Result<Self, AdminError> {
+        if refresh.sequence == 0
+            || refresh.sequence
+                > gateway_plugin_sdk::call::provider::RequestProfileRefresh::MAX_SEQUENCE
+            || serde_json::to_vec(&refresh)
+                .map_err(|_| invalid_descriptor())?
+                .len()
+                > gateway_plugin_sdk::call::provider::RequestProfileRefresh::MAX_BYTES
+        {
+            return Err(invalid_descriptor());
+        }
+        let mut next = Self::prepare_descriptor(refresh.profiles, provider)?;
+        next.sequence = refresh.sequence;
+        Ok(next)
+    }
+
+    fn validate_successor(&self, current: &Self) -> Result<(), AdminError> {
+        // 版本刷新不能移除用户已保存的选项、改变配置语义或偷偷改默认选择。
+        if self.default_configuration() != current.default_configuration()
+            || self.options.len() != current.options.len()
+            || current.options.iter().any(|previous| {
+                !self.options.iter().any(|candidate| {
+                    candidate.option.id == previous.option.id
+                        && candidate.option.configuration == previous.option.configuration
+                })
+            })
+        {
+            return Err(invalid_descriptor());
+        }
+        if self.sequence == current.sequence && self.fingerprint != current.fingerprint {
+            return Err(invalid_descriptor());
+        }
+        Ok(())
+    }
+    fn prepare_descriptor(
+        descriptor: RequestProfileDescriptor,
+        provider: &ProviderKind,
+    ) -> Result<Self, AdminError> {
+        if descriptor.options.is_empty() || descriptor.options.len() > MAXIMUM_OPTIONS {
+            return Err(invalid_descriptor());
+        }
+        validate_document(&descriptor.default_configuration)?;
+        let fingerprint =
+            Sha256::digest(serde_json::to_vec(&descriptor).map_err(|_| invalid_descriptor())?)
+                .into();
+        let mut ids = BTreeSet::new();
+        let mut configurations = Vec::<Map<String, Value>>::new();
+        let mut options = Vec::with_capacity(descriptor.options.len());
+        for option in descriptor.options {
+            validate_identifier(&option.id)?;
+            validate_text(&option.label, MAXIMUM_LABEL_BYTES, false)?;
+            if let Some(description) = &option.description {
+                validate_text(description, MAXIMUM_DESCRIPTION_BYTES, true)?;
+            }
+            validate_document(&option.configuration)?;
+            validate_document(&option.resolved)?;
+            if !ids.insert(option.id.clone())
+                || configurations
+                    .iter()
+                    .any(|configuration| configuration == &option.configuration)
+            {
+                return Err(invalid_descriptor());
+            }
+            configurations.push(option.configuration.clone());
+            let presentation = presentation(provider, &option.presentation)?;
+            options.push(PreparedRequestProfile {
+                option,
+                presentation,
+            });
+        }
+        let defaults = options
+            .iter()
+            .enumerate()
+            .filter(|(_, option)| option.option.configuration == descriptor.default_configuration)
+            .map(|(index, _)| index)
+            .collect::<Vec<_>>();
+        let [default] = defaults.as_slice() else {
+            return Err(invalid_descriptor());
+        };
+        Ok(Self {
+            sequence: 0,
+            fingerprint,
+            default: *default,
+            options,
+        })
+    }
+
+    pub(super) fn resolve(
+        &self,
+        configuration: &OpaqueProviderData,
+    ) -> Result<OpaqueProviderData, ProviderError> {
+        self.find(configuration)
+            .map(|profile| OpaqueProviderData::new(profile.option.resolved.clone()))
+            .ok_or_else(invalid_request_profile)
+    }
+
+    #[must_use]
+    pub(super) fn default_resolved(&self) -> OpaqueProviderData {
+        OpaqueProviderData::new(self.options[self.default].option.resolved.clone())
+    }
+
+    #[must_use]
+    pub(super) fn default_configuration(&self) -> OpaqueProviderData {
+        OpaqueProviderData::new(self.options[self.default].option.configuration.clone())
+    }
+
+    pub(super) fn options(&self) -> Result<OpaqueProviderData, ProviderAdminError> {
+        let presets = self
+            .options
+            .iter()
+            .map(|profile| {
+                json!({
+                    "id": profile.option.id,
+                    "label": profile.option.label,
+                    "description": profile.option.description,
+                    "configuration": profile.option.configuration,
+                })
+            })
+            .collect::<Vec<_>>();
+        object(json!({
+            "presets": presets,
+            "defaultConfiguration": self.options[self.default].option.configuration,
+        }))
+    }
+
+    pub(super) fn preview(
+        &self,
+        configuration: &OpaqueProviderData,
+    ) -> Result<OpaqueProviderData, ProviderAdminError> {
+        let profile = self.find(configuration).ok_or_else(invalid_admin_profile)?;
+        let presentation = &profile.presentation;
+        object(json!({
+            "configuration": profile.option.configuration,
+            "product": presentation.product,
+            "version": presentation.version,
+            "build": presentation.build,
+            "target": {
+                "osType": presentation.target.os_type,
+                "osVersion": presentation.target.os_version,
+                "arch": presentation.target.arch,
+                "terminal": presentation.target.terminal,
+            },
+            "userAgent": presentation.user_agent,
+            "attributes": presentation.attributes.iter().map(|attribute| json!({
+                "label": attribute.label,
+                "value": attribute.value,
+            })).collect::<Vec<_>>(),
+            "verifiedAt": presentation.verified_at,
+            "release": presentation.release.as_ref().map(release_view),
+        }))
+    }
+
+    #[must_use]
+    pub(super) fn dashboard(
+        &self,
+        configuration: Option<&OpaqueProviderData>,
+    ) -> Option<DashboardWireProfile> {
+        configuration
+            .and_then(|configuration| self.find(configuration))
+            .or_else(|| configuration.is_none().then(|| &self.options[self.default]))
+            .map(|profile| profile.presentation.clone())
+    }
+
+    fn find(&self, configuration: &OpaqueProviderData) -> Option<&PreparedRequestProfile> {
+        self.options
+            .iter()
+            .find(|profile| &profile.option.configuration == configuration.expose_to_provider())
+    }
+}
+
+fn presentation(
+    provider: &ProviderKind,
+    value: &RequestProfilePresentation,
+) -> Result<DashboardWireProfile, AdminError> {
+    for text in [
+        &value.product,
+        &value.version,
+        &value.target.os_type,
+        &value.target.os_version,
+        &value.target.arch,
+        &value.target.terminal,
+        &value.user_agent,
+    ] {
+        validate_text(text, MAXIMUM_PRESENTATION_TEXT_BYTES, false)?;
+    }
+    if let Some(build) = &value.build {
+        validate_text(build, MAXIMUM_PRESENTATION_TEXT_BYTES, true)?;
+    }
+    if value.attributes.len() > MAXIMUM_ATTRIBUTES {
+        return Err(invalid_descriptor());
+    }
+    let attributes = value
+        .attributes
+        .iter()
+        .map(|attribute| {
+            validate_text(&attribute.label, MAXIMUM_LABEL_BYTES, false)?;
+            validate_text(&attribute.value, MAXIMUM_PRESENTATION_TEXT_BYTES, true)?;
+            Ok(DashboardWireAttribute {
+                label: attribute.label.clone(),
+                value: attribute.value.clone(),
+            })
+        })
+        .collect::<Result<Vec<_>, AdminError>>()?;
+    Ok(DashboardWireProfile {
+        provider: provider.as_str().to_owned(),
+        product: value.product.clone(),
+        version: value.version.clone(),
+        build: value.build.clone(),
+        target: DashboardWireTarget {
+            os_type: value.target.os_type.clone(),
+            os_version: value.target.os_version.clone(),
+            arch: value.target.arch.clone(),
+            terminal: value.target.terminal.clone(),
+        },
+        user_agent: value.user_agent.clone(),
+        attributes,
+        verified_at: value.verified_at_ms.map(timestamp).transpose()?,
+        release: value.release.as_ref().map(release).transpose()?,
+    })
+}
+
+fn release(value: &RequestProfileRelease) -> Result<DashboardDesktopRelease, AdminError> {
+    for text in [
+        value.latest_version.as_deref(),
+        value.latest_build.as_deref(),
+        value.minimum_system_version.as_deref(),
+        value.hardware_requirements.as_deref(),
+        value.error.as_deref(),
+    ]
+    .into_iter()
+    .flatten()
+    {
+        validate_text(text, MAXIMUM_PRESENTATION_TEXT_BYTES, true)?;
+    }
+    if let Some(source) = &value.download_url {
+        validate_text(source, MAXIMUM_PRESENTATION_TEXT_BYTES, false)?;
+        let url = url::Url::parse(source).map_err(|_| invalid_descriptor())?;
+        if !matches!(url.scheme(), "http" | "https")
+            || url.host_str().is_none()
+            || !url.username().is_empty()
+            || url.password().is_some()
+        {
+            return Err(invalid_descriptor());
+        }
+    }
+    Ok(DashboardDesktopRelease {
+        status: match value.status {
+            RequestProfileReleaseStatus::Unchecked => DesktopReleaseStatus::Unchecked,
+            RequestProfileReleaseStatus::Current => DesktopReleaseStatus::Current,
+            RequestProfileReleaseStatus::UpdateAvailable => DesktopReleaseStatus::UpdateAvailable,
+            RequestProfileReleaseStatus::Failed => DesktopReleaseStatus::Failed,
+        },
+        checked_at: value.checked_at_ms.map(timestamp).transpose()?,
+        latest_version: value.latest_version.clone(),
+        latest_build: value.latest_build.clone(),
+        published_at: value.published_at_ms.map(timestamp).transpose()?,
+        minimum_system_version: value.minimum_system_version.clone(),
+        hardware_requirements: value.hardware_requirements.clone(),
+        download_url: value.download_url.clone(),
+        download_size: value.download_size,
+        signature_present: value.signature_present,
+        error: value.error.clone(),
+    })
+}
+
+fn release_view(value: &DashboardDesktopRelease) -> Value {
+    json!({
+        "status": match value.status {
+            DesktopReleaseStatus::Unchecked => "unchecked",
+            DesktopReleaseStatus::Current => "current",
+            DesktopReleaseStatus::UpdateAvailable => "update_available",
+            DesktopReleaseStatus::Failed => "failed",
+        },
+        "checkedAt": value.checked_at,
+        "latestVersion": value.latest_version,
+        "latestBuild": value.latest_build,
+        "publishedAt": value.published_at,
+        "minimumSystemVersion": value.minimum_system_version,
+        "hardwareRequirements": value.hardware_requirements,
+        "downloadUrl": value.download_url,
+        "downloadSize": value.download_size,
+        "signaturePresent": value.signature_present,
+        "error": value.error,
+    })
+}
+
+fn timestamp(value: i64) -> Result<DateTime<Utc>, AdminError> {
+    DateTime::from_timestamp_millis(value).ok_or_else(invalid_descriptor)
+}
+
+fn validate_identifier(value: &str) -> Result<(), AdminError> {
+    validate_text(value, MAXIMUM_ID_BYTES, false)?;
+    if !value
+        .bytes()
+        .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.'))
+    {
+        return Err(invalid_descriptor());
+    }
+    Ok(())
+}
+
+fn validate_document(value: &Map<String, Value>) -> Result<(), AdminError> {
+    if serde_json::to_vec(value).map_or(true, |encoded| encoded.len() > MAXIMUM_DOCUMENT_BYTES) {
+        return Err(invalid_descriptor());
+    }
+    Ok(())
+}
+
+fn validate_text(value: &str, maximum: usize, allow_empty: bool) -> Result<(), AdminError> {
+    if value.len() > maximum
+        || (!allow_empty && value.is_empty())
+        || value.trim() != value
+        || value.chars().any(char::is_control)
+    {
+        return Err(invalid_descriptor());
+    }
+    Ok(())
+}
+
+fn object(value: Value) -> Result<OpaqueProviderData, ProviderAdminError> {
+    value
+        .as_object()
+        .cloned()
+        .map(OpaqueProviderData::new)
+        .ok_or_else(invalid_admin_profile)
+}
+
+fn invalid_descriptor() -> AdminError {
+    AdminError::invalid("插件请求画像描述不合法")
+}
+
+pub(super) fn invalid_request_profile() -> ProviderError {
+    ProviderError::new(
+        ProviderErrorKind::InvalidRequest,
+        UpstreamSendState::NotSent,
+    )
+}
+
+fn invalid_admin_profile() -> ProviderAdminError {
+    ProviderAdminError::new(ProviderAdminErrorKind::Invalid)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/reset_credits.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/reset_credits.rs
new file mode 100644
index 000000000..65fb5d39e
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/reset_credits.rs
@@ -0,0 +1,166 @@
+use std::collections::BTreeSet;
+
+use super::management::ProviderOperation;
+use gateway_admin::{
+    model::provider_credentials::{
+        ConsumeProviderResetCredit, ProviderResetCredit, ProviderResetCreditResult,
+        ProviderResetCredits,
+    },
+    ports::provider::{ProviderAdminError, ProviderAdminErrorKind},
+};
+use gateway_core::account::ProviderAccountId;
+use gateway_plugin_sdk::{
+    call::provider::account::AccountOperation, call::provider::reset_credits as wire,
+};
+
+use super::{
+    PluginProvider,
+    administration::{invalid, unsupported},
+    management::account_request,
+};
+
+impl PluginProvider {
+    pub(super) async fn query_reset_credits(
+        &self,
+        id: &ProviderAccountId,
+    ) -> Result<ProviderResetCredits, ProviderAdminError> {
+        if !self
+            .account_operations
+            .contains(&AccountOperation::ResetCredits)
+        {
+            return Err(unsupported());
+        }
+        let credential = self.load_management_credential(id).await?;
+        let call = self.management_call(
+            ProviderOperation::ResetCredits,
+            Some(&credential.account),
+            credential.account.outbound_proxy().cloned(),
+        )?;
+        let reply: wire::Reply<wire::Credits> = call
+            .invoke("provider.reset_credits", &account_request(&credential))
+            .await?;
+        self.ensure_management_identity(&credential.account).await?;
+        let result = completed(reply)?;
+        if result.credits.len() > 4096 {
+            return Err(bad_result());
+        }
+        let credits = result
+            .credits
+            .into_iter()
+            .map(credit)
+            .collect::<Result<Vec<_>, _>>()?;
+        let mut ids = BTreeSet::new();
+        if credits.iter().any(|credit| !ids.insert(&credit.id)) {
+            return Err(bad_result());
+        }
+        Ok(ProviderResetCredits {
+            available_count: result.available_count,
+            credits,
+        })
+    }
+
+    pub(super) async fn redeem_reset_credit(
+        &self,
+        command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, ProviderAdminError> {
+        if !self
+            .account_operations
+            .contains(&AccountOperation::ConsumeResetCredit)
+        {
+            return Err(unsupported());
+        }
+        if command.redeem_request_id.get_version() != Some(uuid::Version::Random)
+            || command
+                .credit_id
+                .as_ref()
+                .is_some_and(|id| !valid_text(id) || id.trim().is_empty())
+        {
+            return Err(invalid());
+        }
+        let credential = self.load_management_credential(&command.account_id).await?;
+        let call = self.management_call(
+            ProviderOperation::ConsumeResetCredit,
+            Some(&credential.account),
+            credential.account.outbound_proxy().cloned(),
+        )?;
+        let reply: wire::Reply<wire::ConsumeResult> = call
+            .invoke(
+                "provider.consume_reset_credit",
+                &wire::ConsumeRequest {
+                    account: account_request(&credential),
+                    credit_id: command.credit_id.clone(),
+                    redeem_request_id: command.redeem_request_id.hyphenated().to_string(),
+                },
+            )
+            .await?;
+        // 消费后身份变化不能作为安全失败交给前端重新生成幂等键，也不能写回新账号的额度。
+        self.ensure_management_identity(&credential.account)
+            .await
+            .map_err(|_| ambiguous())?;
+        let result = completed(reply)?;
+        if !valid_text(&result.code) || result.code.trim().is_empty() {
+            return Err(ambiguous());
+        }
+        let credit = result
+            .credit
+            .map(credit)
+            .transpose()
+            .map_err(|_| ambiguous())?;
+        if command
+            .credit_id
+            .as_ref()
+            .zip(credit.as_ref())
+            .is_some_and(|(requested, returned)| requested != &returned.id)
+        {
+            return Err(ambiguous());
+        }
+        Ok(ProviderResetCreditResult {
+            code: result.code,
+            credit,
+        })
+    }
+}
+
+fn completed<T>(reply: wire::Reply<T>) -> Result<T, ProviderAdminError> {
+    match reply {
+        wire::Reply::Completed(result) => Ok(result),
+        wire::Reply::CredentialRefreshRequired => Err(ProviderAdminError::new(
+            ProviderAdminErrorKind::CredentialRefreshRequired,
+        )),
+        wire::Reply::Rejected => Err(bad_result()),
+    }
+}
+
+fn credit(value: wire::Credit) -> Result<ProviderResetCredit, ProviderAdminError> {
+    if value.id.trim().is_empty()
+        || !valid_text(&value.id)
+        || [&value.status, &value.title, &value.reset_type]
+            .into_iter()
+            .flatten()
+            .any(|value| !valid_text(value))
+    {
+        return Err(bad_result());
+    }
+    let expires_at = value
+        .expires_at_ms
+        .map(|ms| chrono::DateTime::from_timestamp_millis(ms).ok_or_else(bad_result))
+        .transpose()?;
+    Ok(ProviderResetCredit {
+        id: value.id,
+        status: value.status,
+        title: value.title,
+        expires_at,
+        reset_type: value.reset_type,
+    })
+}
+
+fn valid_text(value: &str) -> bool {
+    value.len() <= 1024 && !value.chars().any(char::is_control)
+}
+
+fn bad_result() -> ProviderAdminError {
+    ProviderAdminError::new(ProviderAdminErrorKind::BadGateway)
+}
+fn ambiguous() -> ProviderAdminError {
+    ProviderAdminError::new(ProviderAdminErrorKind::Ambiguous)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/rotation.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/rotation.rs
new file mode 100644
index 000000000..fbf1e2344
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/rotation.rs
@@ -0,0 +1,232 @@
+use super::management::ProviderOperation;
+use gateway_admin::{
+    model::{
+        accounts::AccountRecord,
+        provider_credentials::{
+            CredentialCommitGuard, PreparedCredentialRotation, PreparedCredentialRotationFacts,
+            ProviderDocument,
+        },
+    },
+    ports::provider::{ProviderAdminError, ProviderAdminErrorKind},
+};
+use gateway_core::{
+    account::{
+        LoadedCredential, OpaqueProviderData, ProviderAccount, ProviderAccountId,
+        ProviderAccountIdentity,
+    },
+    provider_ports::{
+        ProviderLeaseAcquisition, ProviderLeaseGuard, ProviderLeaseRequest,
+        ProviderRefreshCapacityRequest, ProviderRefreshLeaseRequest,
+    },
+};
+use gateway_plugin_sdk::call::auth::{
+    CredentialFacts, CredentialOperation, ExportCredential, RotateCredential,
+};
+
+use super::{
+    PluginProvider,
+    administration::{invalid, unavailable, unsupported},
+    credentials::{timestamp, validate_facts},
+    management::ManagementOrigin,
+};
+
+struct RotationGuard {
+    _guards: Vec<Box<dyn ProviderLeaseGuard>>,
+}
+
+impl CredentialCommitGuard for RotationGuard {
+    fn finish(self: Box<Self>) {}
+}
+
+pub(super) enum CredentialChange {
+    Refresh,
+    Rotate,
+    Reauthorize,
+}
+
+impl PluginProvider {
+    pub(super) async fn rotate_credentials(
+        &self,
+        account: AccountRecord,
+        replacement: Option<ProviderDocument>,
+    ) -> Result<PreparedCredentialRotation, ProviderAdminError> {
+        self.rotate_credentials_from(account, replacement, ManagementOrigin::Interactive)
+            .await
+    }
+
+    pub(super) async fn rotate_credentials_from(
+        &self,
+        account: AccountRecord,
+        replacement: Option<ProviderDocument>,
+        origin: ManagementOrigin<'_>,
+    ) -> Result<PreparedCredentialRotation, ProviderAdminError> {
+        let refresh = replacement.is_none();
+        let operation = if refresh {
+            CredentialOperation::Refresh
+        } else {
+            CredentialOperation::Rotate
+        };
+        if !self.credential_operations.contains(&operation) {
+            return Err(unsupported());
+        }
+        let operation = if refresh {
+            ProviderOperation::Refresh
+        } else {
+            ProviderOperation::Rotate
+        };
+        self.ensure_provider(&account.provider_kind)?;
+        if let Some(document) = &replacement {
+            self.validate_credential_input(CredentialOperation::Rotate, document)?;
+        }
+        let id = ProviderAccountId::new(account.id.clone()).map_err(|_| invalid())?;
+        let (current, guard) = self.lock_credential(&id).await?;
+        if current.account.revision().get() != account.credential_revision.get() {
+            return Err(conflict());
+        }
+        let call = self.management_call_from(
+            operation,
+            Some(&current.account),
+            current.account.outbound_proxy().cloned(),
+            origin,
+        )?;
+        let input = RotateCredential {
+            current: ExportCredential {
+                account_id: id.as_str().into(),
+                credential_revision: current.account.revision().get(),
+                facts: CredentialFacts {
+                    name: current.account.name().into(),
+                    authentication_kind: current.account.authentication_kind().into(),
+                    material: current.credential.into_inner(),
+                    email: current.account.email().map(str::to_owned),
+                    upstream_user_id: current.account.upstream_user_id().map(str::to_owned),
+                    upstream_account_id: current.account.upstream_account_id().map(str::to_owned),
+                    plan_type: current.account.plan_type().map(str::to_owned),
+                    has_refresh_token: current.account.has_refresh_token(),
+                    access_token_expires_at_ms: current
+                        .account
+                        .access_token_expires_at()
+                        .map(chrono::DateTime::<chrono::Utc>::from)
+                        .map(|value| value.timestamp_millis()),
+                    next_refresh_at_ms: current
+                        .account
+                        .next_refresh_at()
+                        .map(chrono::DateTime::<chrono::Utc>::from)
+                        .map(|value| value.timestamp_millis()),
+                },
+            },
+            replacement: replacement.map(|document| document.into_provider_data().into_inner()),
+        };
+        let method = if refresh {
+            "provider.credentials.refresh"
+        } else {
+            "provider.credentials.rotate"
+        };
+        let facts: CredentialFacts = call.invoke(method, &input).await?;
+        self.prepare_changed_credential(
+            current.account,
+            facts,
+            if refresh {
+                CredentialChange::Refresh
+            } else {
+                CredentialChange::Rotate
+            },
+            guard,
+        )
+        .map_err(|_| call.invalid_result())
+    }
+
+    pub(super) async fn lock_credential(
+        &self,
+        id: &ProviderAccountId,
+    ) -> Result<(LoadedCredential, Box<dyn CredentialCommitGuard>), ProviderAdminError> {
+        let current = self.load_management_credential(id).await?;
+        let revision = current.account.revision();
+        let policy = self
+            .ports
+            .runtime_policy()
+            .load_refresh_policy()
+            .await
+            .map_err(|_| unavailable())?;
+        let leases = self.ports.leases();
+        let capacity = leases
+            .try_acquire(ProviderLeaseRequest::RefreshCapacity(
+                ProviderRefreshCapacityRequest::new(policy.concurrency()),
+            ))
+            .await
+            .map_err(|_| unavailable())?;
+        let ProviderLeaseAcquisition::Acquired(capacity) = capacity else {
+            return Err(conflict());
+        };
+        let mutex = leases
+            .try_acquire(ProviderLeaseRequest::Refresh(
+                ProviderRefreshLeaseRequest::new(id.clone(), revision),
+            ))
+            .await
+            .map_err(|_| unavailable())?;
+        let ProviderLeaseAcquisition::Acquired(mutex) = mutex else {
+            return Err(conflict());
+        };
+        let guard = Box::new(RotationGuard {
+            _guards: vec![capacity, mutex],
+        });
+        // 排队和取锁期间可能已有另一轮提交；在任何上游操作前重新读取版本。
+        let current = self.load_management_credential(id).await?;
+        if current.account.revision() != revision {
+            return Err(conflict());
+        }
+        Ok((current, guard))
+    }
+
+    pub(super) fn prepare_changed_credential(
+        &self,
+        current: ProviderAccount,
+        facts: CredentialFacts,
+        change: CredentialChange,
+        guard: Box<dyn CredentialCommitGuard>,
+    ) -> Result<PreparedCredentialRotation, ProviderAdminError> {
+        let refresh = matches!(change, CredentialChange::Refresh);
+        validate_facts(&facts)?;
+        if facts.authentication_kind != current.authentication_kind()
+            || (refresh
+                && (facts.upstream_user_id.as_deref() != current.upstream_user_id()
+                    || facts.upstream_account_id.as_deref() != current.upstream_account_id()))
+            || (!refresh
+                && facts.upstream_user_id.is_none()
+                && current.upstream_user_id().is_some())
+        {
+            return Err(invalid());
+        }
+        let access_token_expires_at = timestamp(facts.access_token_expires_at_ms)?;
+        let next_refresh_at = timestamp(facts.next_refresh_at_ms)?;
+        Ok(PreparedCredentialRotation::new(
+            PreparedCredentialRotationFacts {
+                account_id: current.id().clone(),
+                provider_kind: self.kind.clone(),
+                expected_credential_revision: gateway_admin::model::Revision::new(
+                    current.revision().get(),
+                )
+                .map_err(|_| invalid())?,
+                replacement_identity: if refresh {
+                    None
+                } else {
+                    facts
+                        .upstream_user_id
+                        .map(|user| ProviderAccountIdentity::new(user, facts.upstream_account_id))
+                },
+                name: facts.name,
+                email: facts.email,
+                plan_type: facts.plan_type,
+                preserve_profile: !matches!(change, CredentialChange::Rotate),
+                provider_material: ProviderDocument::new(OpaqueProviderData::new(facts.material)),
+                has_refresh_token: facts.has_refresh_token,
+                access_token_expires_at,
+                next_refresh_at,
+            },
+            guard,
+        ))
+    }
+}
+
+fn conflict() -> ProviderAdminError {
+    ProviderAdminError::new(ProviderAdminErrorKind::Conflict)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/provider/selection.rs b/backend/crates/gateway-plugin/runtime/src/adapter/provider/selection.rs
new file mode 100644
index 000000000..f96b8caf7
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/provider/selection.rs
@@ -0,0 +1,197 @@
+use std::time::SystemTime;
+
+use futures::{StreamExt as _, stream};
+use gateway_core::{
+    account::{
+        AccountCandidate, AccountEligibilityPolicy, AccountSelectionContext, AccountSelector,
+        LoadedCredential,
+    },
+    concurrency::CapacityWait,
+    engine::{AttemptContext, policy::AccountPolicyError},
+    error::{ProviderError, ProviderErrorKind},
+    operation::CapabilityRequirements,
+    provider_ports::{
+        ProviderLeaseAcquisition, ProviderLeaseGuard, ProviderLeaseRequest,
+        ProviderSchedulingLeaseRequest,
+    },
+    upstream::UpstreamSendState,
+};
+
+use super::PluginProvider;
+
+impl PluginProvider {
+    pub(super) async fn select_account(
+        &self,
+        model: Option<&str>,
+        requirements: &CapabilityRequirements,
+        context: &AttemptContext,
+    ) -> Result<(LoadedCredential, Box<dyn ProviderLeaseGuard>), ProviderError> {
+        let policy = context.account_selection_policy();
+        let mut waiting = CapacityWait::new(
+            &self.waiting,
+            policy.queue_policy(),
+            context.deadline(),
+            context.concurrency_wait_budget(),
+        );
+        let accounts = self.ports.accounts();
+        let leases = self.ports.leases();
+        let cooldowns = self.ports.cooldowns();
+        'refresh: loop {
+            let candidates = accounts
+                .list_for_provider(&self.kind)
+                .await
+                .map_err(|_| unavailable())?;
+            let candidates: Vec<_> = candidates
+                .into_iter()
+                .filter(|account| {
+                    account.provider() == &self.kind
+                        && context
+                            .required_account()
+                            .is_none_or(|required| account.id() == required)
+                        && context.account_scope().is_none_or(|scope| {
+                            scope.allows(account.id())
+                                && model.is_none_or(|model| scope.allows_model(account.id(), model))
+                        })
+                })
+                .collect();
+            let candidates = self
+                .filter_model_accounts(candidates, model, requirements, context)
+                .await?;
+            let ids: Vec<_> = candidates
+                .iter()
+                .map(|account| account.id().clone())
+                .collect();
+            let state = leases
+                .load_state(context.client_api_key_ref(), &self.kind, &ids)
+                .await
+                .map_err(|_| unavailable())?;
+            // 冷却查询有界并发，避免大账号池串行往返；事实始终由现有端口提供。
+            let results: Vec<Result<_, ProviderError>> = stream::iter(candidates)
+                .map(|account| {
+                    let cooldowns = &cooldowns;
+                    let state = &state;
+                    async move {
+                        let cooldown = cooldowns
+                            .read(account.id())
+                            .await
+                            .map_err(|_| unavailable())?
+                            .filter(|cooldown| {
+                                cooldown.credential_revision() == account.revision()
+                            });
+                        let signals = state
+                            .signals()
+                            .get(account.id())
+                            .cloned()
+                            .ok_or_else(unavailable)?
+                            .with_rate_limit(cooldown.map(|cooldown| cooldown.scheduling_state()));
+                        Ok(AccountCandidate { account, signals })
+                    }
+                })
+                .buffer_unordered(16)
+                .collect()
+                .await;
+            let candidates: Vec<_> = results.into_iter().collect::<Result<_, _>>()?;
+            let mut selection = AccountSelectionContext {
+                policy,
+                now: SystemTime::now(),
+                excluded_accounts: context.excluded_accounts().clone(),
+                preferred_account: context.required_account().cloned(),
+                preferred_account_overrides_weight: true,
+                round_robin_cursor: state.round_robin_cursor(),
+                eligibility: if context.is_diagnostic_required_account() {
+                    AccountEligibilityPolicy::BypassForDiagnostic
+                } else {
+                    AccountEligibilityPolicy::Enforce
+                },
+                account_scope: context.account_scope().cloned(),
+            };
+            let mut wait_for = AccountSelector.wait_candidates(&candidates, &selection);
+            for candidate in &candidates {
+                if !waiting.can_try(candidate.account.id()) {
+                    selection
+                        .excluded_accounts
+                        .insert(candidate.account.id().clone());
+                    wait_for.push(candidate.account.id().clone());
+                }
+            }
+            while let Some(selected) = match context
+                .select_account(&self.kind, model, &candidates, &selection)
+                .await
+            {
+                Ok(selection) => selection,
+                Err(AccountPolicyError::StaleCandidate) => continue 'refresh,
+                Err(AccountPolicyError::Rejected) => {
+                    return Err(ProviderError::new(
+                        ProviderErrorKind::RequestPolicyDenied,
+                        UpstreamSendState::NotSent,
+                    ));
+                }
+                Err(AccountPolicyError::Fault) => {
+                    return Err(ProviderError::new(
+                        ProviderErrorKind::Unavailable,
+                        UpstreamSendState::NotSent,
+                    ));
+                }
+            } {
+                let account = &selected.candidate().account;
+                let acquired = leases
+                    .try_acquire(ProviderLeaseRequest::Scheduling(
+                        ProviderSchedulingLeaseRequest::new(
+                            self.kind.clone(),
+                            account.id().clone(),
+                            account.revision(),
+                            account.effective_concurrency(policy.max_concurrent_per_account()),
+                            policy.request_interval(),
+                            context.deadline(),
+                        ),
+                    ))
+                    .await
+                    .map_err(|_| unavailable())?;
+                match acquired {
+                    ProviderLeaseAcquisition::Acquired(guard) => {
+                        let loaded = accounts
+                            .load_credential(account.id(), account.revision())
+                            .await
+                            .map_err(|_| unavailable())?;
+                        if loaded.account.id() != account.id()
+                            || loaded.account.provider() != &self.kind
+                            || loaded.account.revision() != account.revision()
+                        {
+                            drop(guard);
+                            continue 'refresh;
+                        }
+                        return Ok((loaded, guard));
+                    }
+                    ProviderLeaseAcquisition::Busy { .. } => {
+                        wait_for.push(account.id().clone());
+                        selection.excluded_accounts.insert(account.id().clone());
+                    }
+                }
+            }
+            wait_for.sort();
+            wait_for.dedup();
+            if wait_for.is_empty() {
+                return Err(ProviderError::new(
+                    ProviderErrorKind::NoEligibleAccount,
+                    UpstreamSendState::NotSent,
+                ));
+            }
+            if policy.queue_policy().max_waiting == 0 {
+                return Err(ProviderError::new(
+                    ProviderErrorKind::AccountCapacityUnavailable,
+                    UpstreamSendState::NotSent,
+                ));
+            }
+            waiting.wait(&wait_for).await.map_err(|error| {
+                ProviderError::new(error.provider_kind(), UpstreamSendState::NotSent)
+            })?;
+        }
+    }
+}
+
+fn unavailable() -> ProviderError {
+    ProviderError::new(
+        ProviderErrorKind::ProviderInfrastructureUnavailable,
+        UpstreamSendState::NotSent,
+    )
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/adapter/scope.rs b/backend/crates/gateway-plugin/runtime/src/adapter/scope.rs
new file mode 100644
index 000000000..a4c807af0
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/adapter/scope.rs
@@ -0,0 +1,159 @@
+use std::collections::BTreeSet;
+
+use gateway_admin::model::{AdminError, plugins::instances::PluginCapabilityBinding};
+use gateway_core::{
+    engine::{
+        observation::{RequestObservation, WebSocketResponseObservation},
+        policy::{AccountScheduleInput, ModelRouteInput},
+    },
+    identity::ProviderKind,
+    policy::ClientApiKeyId,
+    routing::{AccountGroupId, PublicModelId},
+};
+
+/// 由 Admin 已冻结引用编译出的通用请求绑定范围。
+///
+/// 组条件采用“任一命中”；同一 Key 可以同时属于多个组，因此不同组集合不能单独证明两个
+/// 调度绑定互斥。
+#[derive(Default)]
+pub(crate) struct BindingScope {
+    client_keys: BTreeSet<ClientApiKeyId>,
+    account_groups: BTreeSet<AccountGroupId>,
+    providers: BTreeSet<ProviderKind>,
+    models: BTreeSet<String>,
+}
+
+impl BindingScope {
+    pub(crate) fn compile(binding: &PluginCapabilityBinding) -> Result<Self, AdminError> {
+        if binding.client_key_ids.len() > 256
+            || binding.account_group_ids.len() > 256
+            || binding.provider_ids.len() > 64
+            || binding.models.len() > 256
+        {
+            return Err(AdminError::invalid("插件绑定范围过大"));
+        }
+        let client_keys: BTreeSet<ClientApiKeyId> = binding
+            .client_key_ids
+            .iter()
+            .map(|key| {
+                ClientApiKeyId::new(key.clone())
+                    .map_err(|_| AdminError::invalid("插件绑定 Client Key 范围无效"))
+            })
+            .collect::<Result<_, _>>()?;
+        let account_groups: BTreeSet<AccountGroupId> = binding
+            .account_group_ids
+            .iter()
+            .map(|group| {
+                AccountGroupId::new(group.clone())
+                    .map_err(|_| AdminError::invalid("插件绑定账号组范围无效"))
+            })
+            .collect::<Result<_, _>>()?;
+        let providers: BTreeSet<ProviderKind> = binding
+            .provider_ids
+            .iter()
+            .map(|provider| {
+                ProviderKind::new(provider.clone())
+                    .map_err(|_| AdminError::invalid("插件绑定 Provider 范围无效"))
+            })
+            .collect::<Result<_, _>>()?;
+        let models: BTreeSet<String> = binding
+            .models
+            .iter()
+            .map(|model| {
+                PublicModelId::new(model.clone())
+                    .map(|model| model.as_str().to_owned())
+                    .map_err(|_| AdminError::invalid("插件绑定模型范围无效"))
+            })
+            .collect::<Result<_, _>>()?;
+        if client_keys.len() != binding.client_key_ids.len()
+            || account_groups.len() != binding.account_group_ids.len()
+            || providers.len() != binding.provider_ids.len()
+            || models.len() != binding.models.len()
+        {
+            return Err(AdminError::invalid("插件绑定范围重复"));
+        }
+        Ok(Self {
+            client_keys,
+            account_groups,
+            providers,
+            models,
+        })
+    }
+
+    pub(crate) fn has_provider_condition(&self) -> bool {
+        !self.providers.is_empty()
+    }
+
+    pub(crate) fn matches_observation(&self, observation: &RequestObservation) -> bool {
+        self.matches_identity(observation.client_key_id(), observation.account_group_ids())
+            && self.matches_provider(observation.provider())
+            && self.matches_model(observation.requested_model().map(PublicModelId::as_str))
+    }
+
+    pub(crate) fn matches_websocket_observation(
+        &self,
+        observation: &WebSocketResponseObservation,
+    ) -> bool {
+        self.matches_identity(observation.client_key_id(), observation.account_group_ids())
+            && self.matches_provider(Some(observation.provider()))
+            && self.matches_model(observation.requested_model().map(PublicModelId::as_str))
+    }
+
+    pub(crate) fn matches_route(&self, input: &ModelRouteInput) -> bool {
+        // Router 执行时 Provider 尚未产生；带 Provider 条件的绑定在编译时拒绝。
+        !self.has_provider_condition()
+            && self.matches_identity(Some(input.client_key_id()), input.account_group_ids())
+            && self.matches_model(Some(input.requested_model().as_str()))
+    }
+
+    pub(crate) fn matches_schedule(&self, input: &AccountScheduleInput) -> bool {
+        self.matches_identity(Some(input.client_key_id()), input.account_group_ids())
+            && self.matches_provider(Some(input.provider()))
+            && self.matches_model(input.model())
+    }
+
+    pub(crate) fn matches_processing(
+        &self,
+        client_key: &ClientApiKeyId,
+        account_groups: &[AccountGroupId],
+        provider: Option<&ProviderKind>,
+        model: Option<&str>,
+    ) -> bool {
+        self.matches_identity(Some(client_key), account_groups)
+            && self.matches_provider(provider)
+            && self.matches_model(model)
+    }
+
+    /// 保守判断两个范围能否同时匹配；只有 Key、Provider 或模型的明确不交集可证明互斥。
+    pub(crate) fn overlaps(&self, other: &Self) -> bool {
+        !disjoint_when_both_constrained(&self.client_keys, &other.client_keys)
+            && !disjoint_when_both_constrained(&self.providers, &other.providers)
+            && !disjoint_when_both_constrained(&self.models, &other.models)
+    }
+
+    fn matches_identity(
+        &self,
+        client_key: Option<&ClientApiKeyId>,
+        account_groups: &[AccountGroupId],
+    ) -> bool {
+        (self.client_keys.is_empty()
+            || client_key.is_some_and(|key| self.client_keys.contains(key)))
+            && (self.account_groups.is_empty()
+                || account_groups
+                    .iter()
+                    .any(|group| self.account_groups.contains(group)))
+    }
+
+    fn matches_provider(&self, provider: Option<&ProviderKind>) -> bool {
+        self.providers.is_empty()
+            || provider.is_some_and(|provider| self.providers.contains(provider))
+    }
+
+    fn matches_model(&self, model: Option<&str>) -> bool {
+        self.models.is_empty() || model.is_some_and(|model| self.models.contains(model))
+    }
+}
+
+fn disjoint_when_both_constrained<T: Ord>(left: &BTreeSet<T>, right: &BTreeSet<T>) -> bool {
+    !left.is_empty() && !right.is_empty() && left.is_disjoint(right)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/callback/accounts.rs b/backend/crates/gateway-plugin/runtime/src/callback/accounts.rs
new file mode 100644
index 000000000..68fdb664d
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/callback/accounts.rs
@@ -0,0 +1,400 @@
+//! 账号域回调；账号归属与凭据版本由 Admin 复核，不接受插件伪造归属。
+
+use std::sync::{Arc, OnceLock, Weak};
+
+use chrono::Utc;
+use gateway_admin::{
+    model::{
+        AdminError, AdminErrorKind, MutationActor, MutationContext, PageSize, Revision,
+        plugins::instances::PluginPermissionGrant,
+        provider_credentials::{
+            PluginAccountListQuery, PluginAccountSaveReason, PreparedCredentialCreate,
+            PreparedCredentialRotationFacts, PreparedPluginAccountSave, ProviderDocument,
+        },
+    },
+    ports::plugin_accounts::PluginAccountAccess,
+};
+use gateway_core::{
+    account::{
+        CredentialState, OpaqueProviderData, ProviderAccount, ProviderAccountId,
+        ProviderAccountIdentity,
+    },
+    routing::ProviderKind,
+};
+use gateway_plugin_sdk::{
+    CallContext, ErrorCode, PluginFault,
+    call::{
+        auth::CredentialFacts,
+        host::{
+            AuthCredential, AuthGetRequest, AuthListRequest, AuthListResult, AuthRuntimeAccount,
+            AuthSaveRequest, AuthSaveResult,
+        },
+    },
+};
+
+use super::{NetworkScope, invalid};
+use crate::{RpcReply, adapter::provider};
+
+pub(crate) struct PluginAccountPortSlot {
+    access: OnceLock<Weak<dyn PluginAccountAccess>>,
+}
+
+impl PluginAccountPortSlot {
+    pub(crate) const fn new() -> Self {
+        Self {
+            access: OnceLock::new(),
+        }
+    }
+
+    pub(crate) fn bind(&self, access: &Arc<dyn PluginAccountAccess>) -> Result<(), AdminError> {
+        self.access
+            .set(Arc::downgrade(access))
+            .map_err(|_| AdminError::conflict("插件账号端口已经绑定"))
+    }
+
+    pub(crate) fn upgrade(&self) -> Result<Arc<dyn PluginAccountAccess>, AdminError> {
+        self.access
+            .get()
+            .and_then(Weak::upgrade)
+            .ok_or_else(|| AdminError::unavailable("插件账号服务暂不可用"))
+    }
+}
+
+pub(super) struct PluginAccounts {
+    slot: Arc<PluginAccountPortSlot>,
+    authorized: bool,
+}
+
+impl PluginAccounts {
+    pub(super) fn new(slot: Arc<PluginAccountPortSlot>, grants: &[PluginPermissionGrant]) -> Self {
+        Self {
+            slot,
+            authorized: grants.iter().any(|grant| grant.permission == "accounts"),
+        }
+    }
+
+    pub(super) async fn call(
+        &self,
+        context: &CallContext,
+        scope: &NetworkScope,
+        method: &str,
+        params: serde_json::Value,
+        payload: &[u8],
+    ) -> Result<RpcReply, PluginFault> {
+        if params != serde_json::json!({}) {
+            return Err(invalid());
+        }
+        self.authorize()?;
+        let access = self.slot.upgrade().map_err(map_admin_error)?;
+        match method {
+            "host.auth.list" => {
+                let request: AuthListRequest = decode(payload)?;
+                let limit = PageSize::new(request.limit).map_err(|_| invalid())?;
+                let cursor = request
+                    .cursor
+                    .map(ProviderAccountId::new)
+                    .transpose()
+                    .map_err(|_| invalid())?;
+                let provider_kind = request
+                    .provider_id
+                    .map(ProviderKind::new)
+                    .transpose()
+                    .map_err(|_| invalid())?;
+                let page = access
+                    .list(PluginAccountListQuery {
+                        provider_kind,
+                        cursor,
+                        limit,
+                    })
+                    .await
+                    .map_err(map_admin_error)?;
+                encode(&AuthListResult {
+                    accounts: page.accounts.iter().map(runtime_account).collect(),
+                    next_cursor: page.next_cursor.map(|cursor| cursor.as_str().to_owned()),
+                })
+            }
+            "host.auth.get_runtime" => {
+                let request: AuthGetRequest = decode(payload)?;
+                let account_id =
+                    ProviderAccountId::new(request.account_id).map_err(|_| invalid())?;
+                let account = access
+                    .get_runtime(&account_id)
+                    .await
+                    .map_err(map_admin_error)?;
+                encode(&runtime_account(&account))
+            }
+            "host.auth.get" => {
+                let request: AuthGetRequest = decode(payload)?;
+                let account_id =
+                    ProviderAccountId::new(request.account_id).map_err(|_| invalid())?;
+                let credential = access
+                    .get_credential(&account_id)
+                    .await
+                    .map_err(map_admin_error)?;
+                let account = credential.account;
+                encode(&AuthCredential {
+                    account_id: account.id.clone(),
+                    provider_id: account.provider_kind.as_str().to_owned(),
+                    credential_revision: account.credential_revision.get(),
+                    facts: credential_facts(account, credential.provider_material),
+                })
+            }
+            "host.auth.save" => {
+                let request: AuthSaveRequest = decode(payload)?;
+                encode(&self.save(context, scope, request).await?)
+            }
+            _ => Err(PluginFault::new(
+                ErrorCode::Unsupported,
+                "account callback is unsupported",
+            )),
+        }
+    }
+
+    pub(super) async fn save(
+        &self,
+        context: &CallContext,
+        scope: &NetworkScope,
+        request: AuthSaveRequest,
+    ) -> Result<AuthSaveResult, PluginFault> {
+        self.authorize()?;
+        let access = self.slot.upgrade().map_err(map_admin_error)?;
+        let prepared = match request {
+            AuthSaveRequest::Create { provider_id, facts } => {
+                let provider = ProviderKind::new(provider_id).map_err(|_| invalid())?;
+                PreparedPluginAccountSave::Create(prepare_create(provider, facts)?)
+            }
+            AuthSaveRequest::Replace {
+                account_id,
+                credential_revision,
+                facts,
+            } => {
+                let account_id = ProviderAccountId::new(account_id).map_err(|_| invalid())?;
+                if scope.account_id() == Some(account_id.as_str())
+                    && scope
+                        .credential_revision()
+                        .is_some_and(|bound| bound != credential_revision)
+                {
+                    return Err(denied());
+                }
+                let account = access
+                    .get_runtime(&account_id)
+                    .await
+                    .map_err(map_admin_error)?;
+                PreparedPluginAccountSave::Replace {
+                    authentication_kind: facts.authentication_kind.clone(),
+                    facts: prepare_replace(
+                        account.provider_kind,
+                        account_id,
+                        credential_revision,
+                        facts,
+                        false,
+                    )?,
+                    reason: PluginAccountSaveReason::Explicit,
+                }
+            }
+        };
+        let result = access
+            .save(prepared, &mutation_context(context))
+            .await
+            .map_err(map_admin_error)?;
+        Ok(AuthSaveResult {
+            account_id: result.account_id.as_str().to_owned(),
+            credential_revision: result.credential_revision.get(),
+        })
+    }
+
+    pub(crate) async fn save_discovered_facts(
+        &self,
+        context: &CallContext,
+        scope: &NetworkScope,
+        account: &ProviderAccount,
+        facts: CredentialFacts,
+    ) -> Result<gateway_admin::model::provider_credentials::PluginAccountSaveResult, AdminError>
+    {
+        if !self.authorized {
+            return Err(AdminError::new(AdminErrorKind::Forbidden, "账号访问未授权"));
+        }
+        if scope.account_id() != Some(account.id().as_str())
+            || scope.credential_revision() != Some(account.revision().get())
+            || facts.authentication_kind != account.authentication_kind()
+            || facts.upstream_user_id.as_deref() != account.upstream_user_id()
+            || facts.upstream_account_id.as_deref() != account.upstream_account_id()
+        {
+            return Err(AdminError::conflict("模型发现的账号事实已失效或未获授权"));
+        }
+        let authentication_kind = facts.authentication_kind.clone();
+        let prepared = PreparedPluginAccountSave::Replace {
+            facts: prepare_replace(
+                account.provider().clone(),
+                account.id().clone(),
+                account.revision().get(),
+                facts,
+                true,
+            )
+            .map_err(|_| AdminError::invalid("模型发现返回的账号事实不合法"))?,
+            authentication_kind,
+            reason: PluginAccountSaveReason::ModelDiscovery,
+        };
+        self.slot
+            .upgrade()?
+            .save(prepared, &mutation_context(context))
+            .await
+    }
+
+    fn authorize(&self) -> Result<(), PluginFault> {
+        if !self.authorized {
+            return Err(denied());
+        }
+        Ok(())
+    }
+}
+
+fn prepare_create(
+    provider_kind: ProviderKind,
+    facts: CredentialFacts,
+) -> Result<PreparedCredentialCreate, PluginFault> {
+    provider::validate_facts(&facts).map_err(|_| invalid())?;
+    Ok(PreparedCredentialCreate {
+        model_access: None,
+        outbound_proxy: None,
+        account_id: ProviderAccountId::new(format!("acct_{}", uuid::Uuid::now_v7().simple()))
+            .map_err(|_| invalid())?,
+        provider_kind,
+        name: facts.name,
+        email: facts.email,
+        upstream_user_id: facts.upstream_user_id,
+        upstream_account_id: facts.upstream_account_id,
+        plan_type: facts.plan_type,
+        authentication_kind: facts.authentication_kind,
+        provider_material: ProviderDocument::new(OpaqueProviderData::new(facts.material)),
+        has_refresh_token: facts.has_refresh_token,
+        access_token_expires_at: provider::credential_timestamp(facts.access_token_expires_at_ms)
+            .map_err(|_| invalid())?,
+        next_refresh_at: provider::credential_timestamp(facts.next_refresh_at_ms)
+            .map_err(|_| invalid())?,
+        enabled: true,
+        credential_state: CredentialState::Ready,
+        credential_observed_at: Utc::now(),
+    })
+}
+
+fn prepare_replace(
+    provider_kind: ProviderKind,
+    account_id: ProviderAccountId,
+    credential_revision: u64,
+    facts: CredentialFacts,
+    preserve_identity: bool,
+) -> Result<PreparedCredentialRotationFacts, PluginFault> {
+    provider::validate_facts(&facts).map_err(|_| invalid())?;
+    Ok(PreparedCredentialRotationFacts {
+        account_id,
+        provider_kind,
+        expected_credential_revision: Revision::new(credential_revision).map_err(|_| invalid())?,
+        replacement_identity: if preserve_identity {
+            None
+        } else {
+            facts
+                .upstream_user_id
+                .clone()
+                .map(|user| ProviderAccountIdentity::new(user, facts.upstream_account_id.clone()))
+        },
+        name: facts.name,
+        email: facts.email,
+        plan_type: facts.plan_type,
+        preserve_profile: false,
+        provider_material: ProviderDocument::new(OpaqueProviderData::new(facts.material)),
+        has_refresh_token: facts.has_refresh_token,
+        access_token_expires_at: provider::credential_timestamp(facts.access_token_expires_at_ms)
+            .map_err(|_| invalid())?,
+        next_refresh_at: provider::credential_timestamp(facts.next_refresh_at_ms)
+            .map_err(|_| invalid())?,
+    })
+}
+
+fn runtime_account(account: &gateway_admin::model::accounts::AccountRecord) -> AuthRuntimeAccount {
+    AuthRuntimeAccount {
+        account_id: account.id.clone(),
+        provider_id: account.provider_kind.as_str().to_owned(),
+        credential_revision: account.credential_revision.get(),
+        name: account.name.clone(),
+        email: account.email.clone(),
+        upstream_user_id: account.upstream_user_id.clone(),
+        upstream_account_id: account.upstream_account_id.clone(),
+        plan_type: account.plan_type.clone(),
+        authentication_kind: account.authentication_kind.clone(),
+        enabled: account.enabled,
+        credential_state: account.credential_state.as_str().to_owned(),
+        has_refresh_token: account.has_refresh_token,
+        access_token_expires_at_ms: account
+            .access_token_expires_at
+            .map(|value| value.timestamp_millis()),
+        next_refresh_at_ms: account
+            .next_refresh_at
+            .map(|value| value.timestamp_millis()),
+    }
+}
+
+fn credential_facts(
+    account: gateway_admin::model::accounts::AccountRecord,
+    material: ProviderDocument,
+) -> CredentialFacts {
+    CredentialFacts {
+        name: account.name,
+        authentication_kind: account.authentication_kind,
+        material: material.into_provider_data().into_inner(),
+        email: account.email,
+        upstream_user_id: account.upstream_user_id,
+        upstream_account_id: account.upstream_account_id,
+        plan_type: account.plan_type,
+        has_refresh_token: account.has_refresh_token,
+        access_token_expires_at_ms: account
+            .access_token_expires_at
+            .map(|value| value.timestamp_millis()),
+        next_refresh_at_ms: account
+            .next_refresh_at
+            .map(|value| value.timestamp_millis()),
+    }
+}
+
+fn mutation_context(context: &CallContext) -> MutationContext {
+    MutationContext {
+        actor: MutationActor::System,
+        // RPC 回调使用真实 call_id，RPC 结果的后置提交仍使用原始上下文；scope 由宿主签发且全局唯一。
+        request_id: format!(
+            "plugin:{}:scope:{}:call:{}",
+            context.instance_id, context.resource_scope_id, context.call_id
+        ),
+    }
+}
+
+fn decode<T: serde::de::DeserializeOwned>(payload: &[u8]) -> Result<T, PluginFault> {
+    serde_json::from_slice(payload).map_err(|_| invalid())
+}
+
+fn encode(value: &impl serde::Serialize) -> Result<RpcReply, PluginFault> {
+    Ok(RpcReply {
+        result: serde_json::json!({}),
+        payload: serde_json::to_vec(value).map_err(|_| invalid())?,
+    })
+}
+
+fn denied() -> PluginFault {
+    PluginFault::new(
+        ErrorCode::PermissionDenied,
+        "account callback is not authorized",
+    )
+}
+
+pub(super) fn map_admin_error(error: AdminError) -> PluginFault {
+    let code = match error.kind() {
+        AdminErrorKind::Invalid => ErrorCode::InvalidInput,
+        AdminErrorKind::Unauthorized | AdminErrorKind::Forbidden => ErrorCode::PermissionDenied,
+        AdminErrorKind::NotFound => ErrorCode::Rejected,
+        AdminErrorKind::Conflict => ErrorCode::Conflict,
+        AdminErrorKind::RateLimited => ErrorCode::Capacity,
+        AdminErrorKind::UpstreamResultUnknown => ErrorCode::Uncertain,
+        AdminErrorKind::BadGateway => ErrorCode::Upstream,
+        AdminErrorKind::Unavailable | AdminErrorKind::Internal => ErrorCode::Fault,
+    };
+    PluginFault::new(code, "account callback failed")
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/callback/affinity.rs b/backend/crates/gateway-plugin/runtime/src/callback/affinity.rs
new file mode 100644
index 000000000..1992ab9f1
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/callback/affinity.rs
@@ -0,0 +1,92 @@
+//! Provider 会话亲和读取；只查询既有记录，不推导或写入亲和事实。
+
+use std::sync::{Arc, OnceLock, Weak};
+
+use gateway_admin::model::{AdminError, plugins::instances::PluginPermissionGrant};
+use gateway_core::{
+    engine::{ModelRequestId, nested::AffinityLookupPort},
+    identity::ProviderKind,
+    provider_ports::ProviderSessionAffinityKey,
+};
+use gateway_plugin_sdk::{
+    CallContext, PluginFault,
+    call::host::{AffinityLookupRequest, AffinityLookupResult},
+};
+
+use super::{denied, invalid};
+use crate::RpcReply;
+
+pub(crate) struct PluginAffinityPortSlot {
+    port: OnceLock<Weak<dyn AffinityLookupPort>>,
+}
+
+impl PluginAffinityPortSlot {
+    pub(crate) const fn new() -> Self {
+        Self {
+            port: OnceLock::new(),
+        }
+    }
+
+    pub(crate) fn bind(&self, port: &Arc<dyn AffinityLookupPort>) -> Result<(), AdminError> {
+        self.port
+            .set(Arc::downgrade(port))
+            .map_err(|_| AdminError::conflict("插件亲和查询端口已经绑定"))
+    }
+
+    fn upgrade(&self) -> Result<Arc<dyn AffinityLookupPort>, PluginFault> {
+        self.port.get().and_then(Weak::upgrade).ok_or_else(denied)
+    }
+}
+
+pub(super) struct PluginAffinity {
+    slot: Arc<PluginAffinityPortSlot>,
+    authorized: bool,
+}
+
+impl PluginAffinity {
+    pub(super) fn new(slot: Arc<PluginAffinityPortSlot>, grants: &[PluginPermissionGrant]) -> Self {
+        Self {
+            slot,
+            authorized: grants.iter().any(|grant| grant.permission == "requests"),
+        }
+    }
+
+    pub(super) async fn call(
+        &self,
+        context: &CallContext,
+        params: serde_json::Value,
+        payload: &[u8],
+    ) -> Result<RpcReply, PluginFault> {
+        if !payload.is_empty() {
+            return Err(invalid());
+        }
+        let request: AffinityLookupRequest =
+            serde_json::from_value(params).map_err(|_| invalid())?;
+        let parent_request_id = context
+            .request_id
+            .as_ref()
+            .ok_or_else(denied)
+            .and_then(|request_id| ModelRequestId::new(request_id.clone()).map_err(|_| denied()))?;
+        if !self.authorized {
+            return Err(denied());
+        }
+        let provider = ProviderKind::new(request.provider).map_err(|_| invalid())?;
+        let result = self
+            .slot
+            .upgrade()?
+            .lookup(gateway_core::engine::nested::AffinityLookupRequest {
+                parent_request_id,
+                provider,
+                key: ProviderSessionAffinityKey::try_new(request.key).map_err(|_| invalid())?,
+            })
+            .await
+            .map_err(super::model::gateway_fault)?;
+        Ok(RpcReply {
+            result: serde_json::to_value(AffinityLookupResult {
+                account_id: result.map(|result| result.account().as_str().to_owned()),
+            })
+            .map_err(|_| invalid())?,
+            payload: Vec::new(),
+        })
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/callback/http.rs b/backend/crates/gateway-plugin/runtime/src/callback/http.rs
new file mode 100644
index 000000000..15cd5111c
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/callback/http.rs
@@ -0,0 +1,206 @@
+use std::sync::Arc;
+
+use gateway_core::upstream::UpstreamSendState;
+use gateway_host::outbound::{HttpClient, HttpError, HttpErrorKind, HttpRequest};
+use gateway_plugin_sdk::{ErrorCode, PluginFault, SendState, call::host as wire};
+use serde::de::DeserializeOwned;
+
+use super::{CallResources, HttpAuthorization, HttpStream, NetworkScope, denied, invalid};
+use crate::RpcReply;
+
+#[expect(
+    clippy::too_many_arguments,
+    reason = "回调只接受宿主已解析的调用资源与权限，不重建第二份上下文"
+)]
+pub(super) async fn dispatch(
+    client: &HttpClient,
+    authorization: &HttpAuthorization,
+    scope: &Arc<NetworkScope>,
+    call: &CallResources,
+    method: &str,
+    params: serde_json::Value,
+    payload: Vec<u8>,
+    maximum_payload: usize,
+) -> Result<RpcReply, PluginFault> {
+    match method {
+        "host.http.do" | "host.http.do_stream" => {
+            let request: wire::HttpRequest = decode(params)?;
+            let timeout = call
+                .deadline
+                .checked_duration_since(tokio::time::Instant::now())
+                .ok_or_else(|| PluginFault::new(ErrorCode::Timeout, "callback deadline elapsed"))?;
+            let attempt = scope.start_http();
+            let response = client
+                .open(
+                    HttpRequest {
+                        method: request.method,
+                        url: request.url,
+                        headers: request
+                            .headers
+                            .into_iter()
+                            .map(|(name, value)| (name, value.into_bytes()))
+                            .collect(),
+                        body: payload,
+                    },
+                    scope.proxy.as_ref(),
+                    &authorization.network,
+                    timeout,
+                )
+                .await;
+            attempt.finish(
+                response
+                    .as_ref()
+                    .map_or_else(|error| error.send_state, |_| UpstreamSendState::Sent),
+            );
+            let response = response.map_err(http_error)?;
+            let mut body = response.body;
+            let headers = response
+                .headers
+                .into_iter()
+                .map(|(name, value)| String::from_utf8(value).map(|value| (name, value)))
+                .collect::<Result<Vec<_>, _>>()
+                .map_err(|_| sent_fault(ErrorCode::Fault, "HTTP header cannot be represented"))?;
+            let mut result = wire::HttpResponse {
+                status: response.status,
+                headers,
+                stream: None,
+            };
+            let mut payload = Vec::new();
+            if method == "host.http.do_stream" {
+                let id = uuid::Uuid::new_v4().to_string();
+                let mut state = call
+                    .state
+                    .lock()
+                    .unwrap_or_else(std::sync::PoisonError::into_inner);
+                if state.closed {
+                    return Err(denied());
+                }
+                if state.streams.len() >= 16 {
+                    return Err(sent_fault(
+                        ErrorCode::Capacity,
+                        "HTTP stream capacity exhausted",
+                    ));
+                }
+                state.streams.insert(
+                    id.clone(),
+                    Arc::new(HttpStream {
+                        body: tokio::sync::Mutex::new(Some(body)),
+                        closed: tokio::sync::watch::channel(false).0,
+                    }),
+                );
+                result.stream = Some(id);
+            } else {
+                while let Some(chunk) = body.read(64 * 1024).await.map_err(http_error)? {
+                    if payload.len() + chunk.len() > maximum_payload {
+                        return Err(sent_fault(
+                            ErrorCode::Capacity,
+                            "HTTP body requires streaming",
+                        ));
+                    }
+                    payload.extend_from_slice(&chunk);
+                }
+            }
+            Ok(RpcReply {
+                result: serde_json::to_value(result).map_err(|_| invalid())?,
+                payload,
+            })
+        }
+        "host.http.stream_read" => {
+            if !payload.is_empty() {
+                return Err(invalid());
+            }
+            let request: wire::StreamRead = decode(params)?;
+            if request.maximum_bytes == 0 || request.maximum_bytes > 64 * 1024 {
+                return Err(invalid());
+            }
+            let stream = call
+                .state
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner)
+                .streams
+                .get(&request.stream)
+                .cloned()
+                .ok_or_else(denied)?;
+            let mut body = stream.body.try_lock().map_err(|_| {
+                PluginFault::new(ErrorCode::Capacity, "HTTP stream already has a reader")
+            })?;
+            let mut closed = stream.closed.subscribe();
+            let result = tokio::select! {
+                biased;
+                _ = closed.wait_for(|closed| *closed) => Err(denied()),
+                result = body.as_mut().ok_or_else(denied)?.read(request.maximum_bytes as usize) => result.map_err(http_error),
+            };
+            if !matches!(&result, Ok(Some(_))) {
+                body.take();
+                stream.closed.send_replace(true);
+                call.state
+                    .lock()
+                    .unwrap_or_else(std::sync::PoisonError::into_inner)
+                    .streams
+                    .remove(&request.stream);
+            }
+            let chunk = result?;
+            Ok(RpcReply {
+                result: serde_json::json!({"eof":chunk.is_none()}),
+                payload: chunk.map_or_else(Vec::new, |chunk| chunk.to_vec()),
+            })
+        }
+        "host.http.stream_close" => {
+            if !payload.is_empty() {
+                return Err(invalid());
+            }
+            let request: wire::StreamClose = decode(params)?;
+            let stream = call
+                .state
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner)
+                .streams
+                .remove(&request.stream)
+                .ok_or_else(denied)?;
+            stream.close();
+            Ok(RpcReply {
+                result: serde_json::json!({}),
+                payload: vec![],
+            })
+        }
+        _ => Err(denied()),
+    }
+}
+
+fn decode<T: DeserializeOwned>(value: serde_json::Value) -> Result<T, PluginFault> {
+    serde_json::from_value(value).map_err(|_| invalid())
+}
+
+fn sent_fault(code: ErrorCode, message: &'static str) -> PluginFault {
+    let mut error = PluginFault::new(code, message);
+    error.send_state = SendState::Sent;
+    error
+}
+
+fn http_error(error: HttpError) -> PluginFault {
+    tracing::warn!(
+        reason = error.reason(),
+        kind = ?error.kind(),
+        send_state = ?error.send_state,
+        "插件受管 HTTP 请求失败"
+    );
+    let (code, message) = match error.kind() {
+        HttpErrorKind::InvalidRequest => (ErrorCode::InvalidInput, "网络请求参数无效"),
+        HttpErrorKind::AddressDenied => (
+            ErrorCode::PermissionDenied,
+            "目标地址被安全策略拦截，请检查宿主 DNS 或代理设置",
+        ),
+        HttpErrorKind::Dns => (ErrorCode::Upstream, "域名解析失败，请检查宿主 DNS"),
+        HttpErrorKind::Timeout => (ErrorCode::Timeout, "网络请求超时，请稍后重试"),
+        HttpErrorKind::Transport => (ErrorCode::Upstream, "无法连接目标网站，请检查网络或代理"),
+        HttpErrorKind::Capacity => (ErrorCode::Capacity, "网络请求繁忙，请稍后重试"),
+        HttpErrorKind::Response => (ErrorCode::Upstream, "目标网站响应读取失败"),
+    };
+    let mut fault = PluginFault::new(code, message);
+    fault.send_state = match error.send_state {
+        UpstreamSendState::NotSent => SendState::NotSent,
+        UpstreamSendState::Sent => SendState::Sent,
+        UpstreamSendState::Ambiguous => SendState::Ambiguous,
+    };
+    fault
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/callback/keys.rs b/backend/crates/gateway-plugin/runtime/src/callback/keys.rs
new file mode 100644
index 000000000..301b59a90
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/callback/keys.rs
@@ -0,0 +1,98 @@
+//! Key 目录只传递非秘密身份，模型规则仍由 Core 在执行时复核。
+
+use std::sync::{Arc, OnceLock, Weak};
+
+use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
+use gateway_admin::{
+    model::{
+        AdminError, PageSize,
+        plugin_client_keys::{PluginClientKeyCursor, PluginClientKeyListQuery},
+    },
+    ports::plugin_client_keys::PluginClientKeyAccess,
+};
+use gateway_core::policy::ClientApiKeyId;
+use gateway_plugin_sdk::{
+    PluginFault,
+    call::host::{ClientKey, KeyListRequest, KeyListResult},
+};
+
+use super::{denied, invalid};
+use crate::RpcReply;
+
+pub(crate) struct PluginClientKeyPortSlot {
+    access: OnceLock<Weak<dyn PluginClientKeyAccess>>,
+}
+
+impl PluginClientKeyPortSlot {
+    pub(crate) const fn new() -> Self {
+        Self {
+            access: OnceLock::new(),
+        }
+    }
+
+    pub(crate) fn bind(&self, access: &Arc<dyn PluginClientKeyAccess>) -> Result<(), AdminError> {
+        self.access
+            .set(Arc::downgrade(access))
+            .map_err(|_| AdminError::conflict("插件 Key 目录端口已经绑定"))
+    }
+
+    pub(super) async fn list(
+        &self,
+        params: serde_json::Value,
+        payload: &[u8],
+    ) -> Result<RpcReply, PluginFault> {
+        if !payload.is_empty() {
+            return Err(invalid());
+        }
+        let request: KeyListRequest = serde_json::from_value(params).map_err(|_| invalid())?;
+        let limit = PageSize::new(request.limit).map_err(|_| invalid())?;
+        let cursor = request
+            .cursor
+            .map(|cursor| {
+                if cursor.len() > 2048 {
+                    return Err(invalid());
+                }
+                let bytes = URL_SAFE_NO_PAD.decode(cursor).map_err(|_| invalid())?;
+                let (name, id): (String, String) =
+                    serde_json::from_slice(&bytes).map_err(|_| invalid())?;
+                Ok(PluginClientKeyCursor {
+                    name,
+                    id: ClientApiKeyId::new(id).map_err(|_| invalid())?,
+                })
+            })
+            .transpose()?;
+        let access = self
+            .access
+            .get()
+            .and_then(Weak::upgrade)
+            .ok_or_else(denied)?;
+        let page = access
+            .list(PluginClientKeyListQuery { cursor, limit })
+            .await
+            .map_err(super::accounts::map_admin_error)?;
+        let next_cursor = page
+            .next_cursor
+            .map(|cursor| {
+                serde_json::to_vec(&(cursor.name, cursor.id.as_str()))
+                    .map(|bytes| URL_SAFE_NO_PAD.encode(bytes))
+                    .map_err(|_| invalid())
+            })
+            .transpose()?;
+        Ok(RpcReply {
+            result: serde_json::to_value(KeyListResult {
+                keys: page
+                    .items
+                    .into_iter()
+                    .map(|key| ClientKey {
+                        id: key.id.as_str().to_owned(),
+                        name: key.name,
+                        enabled: key.enabled,
+                    })
+                    .collect(),
+                next_cursor,
+            })
+            .map_err(|_| invalid())?,
+            payload: Vec::new(),
+        })
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/callback/log.rs b/backend/crates/gateway-plugin/runtime/src/callback/log.rs
new file mode 100644
index 000000000..749b93055
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/callback/log.rs
@@ -0,0 +1,143 @@
+use std::{
+    sync::{Arc, Mutex},
+    time::Duration,
+};
+
+use gateway_core::diagnostics::{body_fingerprint, diagnostic_json};
+use gateway_plugin_sdk::{
+    CallContext, Manifest, PluginFault,
+    call::host::{LogLevel, LogRequest, LogResult},
+};
+use tokio::{sync::Semaphore, time::Instant};
+
+use crate::RpcReply;
+
+// 这是保护宿主的有界默认值，不是吞吐保证；预算按实例 incarnation 隔离。
+const WINDOW: Duration = Duration::from_secs(1);
+const MAXIMUM_EVENTS: u32 = 64;
+const MAXIMUM_INPUT_BYTES: usize = 8 * 1024;
+const MAXIMUM_FIELDS: usize = 32;
+
+pub(super) struct PluginLog {
+    plugin_id: String,
+    plugin_version: String,
+    budget: Mutex<Budget>,
+    slots: Arc<Semaphore>,
+}
+
+struct Budget {
+    started: Instant,
+    recorded: u32,
+    suppressed: u64,
+}
+
+impl PluginLog {
+    pub(super) fn new(
+        manifest: &Manifest,
+        slots: Arc<Semaphore>,
+    ) -> Result<Self, gateway_plugin_sdk::ManifestError> {
+        Ok(Self {
+            plugin_id: manifest.plugin_id()?,
+            plugin_version: manifest.version.to_string(),
+            slots,
+            budget: Mutex::new(Budget {
+                started: Instant::now(),
+                recorded: 0,
+                suppressed: 0,
+            }),
+        })
+    }
+
+    pub(super) fn record(
+        &self,
+        context: &CallContext,
+        params: serde_json::Value,
+        payload: &[u8],
+    ) -> Result<RpcReply, PluginFault> {
+        if !payload.is_empty()
+            || serde_json::to_vec(&params)
+                .map_err(|_| super::invalid())?
+                .len()
+                > MAXIMUM_INPUT_BYTES
+        {
+            return Err(super::invalid());
+        }
+        let request: LogRequest = serde_json::from_value(params).map_err(|_| super::invalid())?;
+        if request.event.is_empty()
+            || request.event.len() > 64
+            || !request
+                .event
+                .bytes()
+                .all(|byte| byte.is_ascii_alphanumeric() || b"._-".contains(&byte))
+            || request.fields.len() > MAXIMUM_FIELDS
+        {
+            return Err(super::invalid());
+        }
+        let (suppressed, slot) = {
+            let mut budget = self
+                .budget
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            if budget.started.elapsed() >= WINDOW {
+                budget.started = Instant::now();
+                budget.recorded = 0;
+            }
+            if budget.recorded == MAXIMUM_EVENTS {
+                budget.suppressed = budget.suppressed.saturating_add(1);
+                return reply(false);
+            }
+            let Ok(slot) = self.slots.clone().try_acquire_owned() else {
+                budget.suppressed = budget.suppressed.saturating_add(1);
+                return reply(false);
+            };
+            budget.recorded += 1;
+            (std::mem::take(&mut budget.suppressed), slot)
+        };
+        // 使用现有诊断 owner；未知键名、正文和嵌套敏感字段不会原样进入普通日志。
+        let fields =
+            diagnostic_json(&serde_json::to_value(request.fields).map_err(|_| super::invalid())?);
+        // 标识的字符形状不能证明内容安全；事件名也只保留摘要。
+        let event = body_fingerprint(request.event.as_bytes());
+        let plugin_id = self.plugin_id.clone();
+        let plugin_version = self.plugin_version.clone();
+        let context = context.clone();
+        // tracing 后端可能同步阻塞。任务容量跨实例与代次共享，并由写入任务持有到完成，
+        // 父调用取消不能释放容量后继续无限排队；已受理日志可在父调用结束后落盘。
+        tokio::task::spawn_blocking(move || {
+            let _slot = slot;
+            macro_rules! record {
+            ($level:expr) => {
+                tracing::event!(target: "gateway_plugin", $level,
+                    plugin_id = %plugin_id,
+                    plugin_version = %plugin_version,
+                    instance_id = %context.instance_id,
+                    generation = context.generation,
+                    incarnation = %context.incarnation,
+                    call_id = context.call_id,
+                    request_id = context.request_id.as_deref(),
+                    attempt_id = context.attempt_id.as_deref(),
+                    stage = ?context.stage,
+                    event = %event,
+                    fields = %fields,
+                    suppressed_logs = suppressed,
+                    "插件事件"
+                )
+            };
+        }
+            match request.level {
+                LogLevel::Debug => record!(tracing::Level::DEBUG),
+                LogLevel::Info => record!(tracing::Level::INFO),
+                LogLevel::Warn => record!(tracing::Level::WARN),
+                LogLevel::Error => record!(tracing::Level::ERROR),
+            }
+        });
+        reply(true)
+    }
+}
+
+fn reply(recorded: bool) -> Result<RpcReply, PluginFault> {
+    Ok(RpcReply {
+        result: serde_json::to_value(LogResult { recorded }).map_err(|_| super::invalid())?,
+        payload: vec![],
+    })
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/callback/middleware/body.rs b/backend/crates/gateway-plugin/runtime/src/callback/middleware/body.rs
new file mode 100644
index 000000000..88d7f9ac5
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/callback/middleware/body.rs
@@ -0,0 +1,253 @@
+use std::sync::{
+    Arc, Mutex,
+    atomic::{AtomicBool, Ordering},
+};
+
+use bytes::Bytes;
+use gateway_core::engine::middleware::{
+    MiddlewareBody, MiddlewareError, MiddlewareFrame, MiddlewareFrameEnvelope, MiddlewareFraming,
+};
+use gateway_plugin_sdk::{ErrorCode, PluginFault, call::middleware::MiddlewareBodyDisposition};
+
+use super::{denied, invalid};
+
+pub(super) struct BodyResource {
+    expected_framing: MiddlewareFraming,
+    downstream_error: Arc<Mutex<Option<MiddlewareError>>>,
+    finalized: AtomicBool,
+    state: tokio::sync::Mutex<BodyState>,
+    source_released: tokio::sync::Notify,
+}
+
+struct BodyState {
+    body: Option<Box<dyn MiddlewareBody>>,
+    read_started: bool,
+    next_source_id: u64,
+    source: Option<(u64, SourceFrame)>,
+}
+
+struct SourceFrame {
+    bytes: Bytes,
+    framing: MiddlewareFraming,
+    terminal: bool,
+    transformed: bool,
+    envelope: Option<MiddlewareFrameEnvelope>,
+}
+
+pub(super) struct BodyReadFrame {
+    pub(super) bytes: Bytes,
+    pub(super) framing: MiddlewareFraming,
+    pub(super) source_id: u64,
+    pub(super) terminal: bool,
+}
+
+#[derive(Clone)]
+pub(crate) struct MiddlewareBodyAuthority(Arc<BodyResource>);
+
+impl MiddlewareBodyAuthority {
+    pub(super) fn new(body: Arc<BodyResource>) -> Self {
+        Self(body)
+    }
+
+    pub(crate) async fn resolve_source_output(
+        &self,
+        source_id: u64,
+        disposition: MiddlewareBodyDisposition,
+        bytes: Bytes,
+    ) -> Result<Option<MiddlewareFrame>, MiddlewareError> {
+        let mut state = self.0.state.lock().await;
+        let finishes_source = matches!(
+            disposition,
+            MiddlewareBodyDisposition::Only
+                | MiddlewareBodyDisposition::Last
+                | MiddlewareBodyDisposition::Drop
+        );
+        let (framing, terminal, source_bytes, transformed, envelope) = if finishes_source {
+            let (stored_id, source) = state.source.take().ok_or(MiddlewareError::InvalidState)?;
+            if stored_id != source_id {
+                return Err(MiddlewareError::InvalidState);
+            }
+            self.0.source_released.notify_waiters();
+            (
+                source.framing,
+                source.terminal,
+                source.bytes,
+                source.transformed,
+                source.envelope,
+            )
+        } else {
+            let (stored_id, source) = state.source.as_ref().ok_or(MiddlewareError::InvalidState)?;
+            if *stored_id != source_id {
+                return Err(MiddlewareError::InvalidState);
+            }
+            (
+                source.framing,
+                source.terminal,
+                source.bytes.clone(),
+                source.transformed,
+                None,
+            )
+        };
+        if disposition == MiddlewareBodyDisposition::Drop && terminal {
+            return Err(MiddlewareError::InvalidState);
+        }
+        let output_transformed =
+            transformed || disposition != MiddlewareBodyDisposition::Only || bytes != source_bytes;
+        let mut frame = MiddlewareFrame::new(bytes, framing, finishes_source && terminal)
+            .with_transformed(output_transformed);
+        let has_envelope = envelope.is_some();
+        if let Some(envelope) = envelope {
+            frame = frame.with_envelope(envelope);
+        }
+        if disposition == MiddlewareBodyDisposition::Drop && !has_envelope {
+            Ok(None)
+        } else {
+            Ok(Some(frame))
+        }
+    }
+
+    pub(crate) async fn has_pending_sources(&self) -> bool {
+        self.0.state.lock().await.source.is_some()
+    }
+
+    pub(crate) async fn commit_downstream(
+        &self,
+        client_status_code: Option<u16>,
+    ) -> Result<(), MiddlewareError> {
+        let mut state = self.0.state.lock().await;
+        let body = state.body.as_mut().ok_or(MiddlewareError::InvalidState)?;
+        let result = body.commit_downstream(client_status_code).await;
+        self.0
+            .finalized
+            .store(body.is_finalized(), Ordering::Release);
+        result
+    }
+
+    pub(crate) async fn record_client_status(
+        &self,
+        client_status_code: u16,
+    ) -> Result<(), MiddlewareError> {
+        let mut state = self.0.state.lock().await;
+        let body = state.body.as_mut().ok_or(MiddlewareError::InvalidState)?;
+        let result = body.record_client_status(client_status_code).await;
+        self.0
+            .finalized
+            .store(body.is_finalized(), Ordering::Release);
+        result
+    }
+
+    #[must_use]
+    pub(crate) fn is_finalized(&self) -> bool {
+        self.0.finalized.load(Ordering::Acquire)
+    }
+}
+
+impl BodyResource {
+    pub(super) fn new(
+        expected_framing: MiddlewareFraming,
+        downstream_error: Arc<Mutex<Option<MiddlewareError>>>,
+        body: Box<dyn MiddlewareBody>,
+    ) -> Arc<Self> {
+        Arc::new(Self {
+            expected_framing,
+            downstream_error,
+            finalized: AtomicBool::new(body.is_finalized()),
+            state: tokio::sync::Mutex::new(BodyState {
+                body: Some(body),
+                read_started: false,
+                next_source_id: 0,
+                source: None,
+            }),
+            source_released: tokio::sync::Notify::new(),
+        })
+    }
+
+    pub(super) const fn expected_framing(&self) -> MiddlewareFraming {
+        self.expected_framing
+    }
+
+    pub(super) async fn read(&self, maximum: usize) -> Result<Option<BodyReadFrame>, PluginFault> {
+        // SDK 发出上一源的映射帧后即可请求下一源；消费者可能尚未处理排队帧。
+        // 等待归还而非报冲突，仍只保留一个源；父 RPC 的期限与取消约束等待。
+        let mut state = loop {
+            let released = self.source_released.notified();
+            let state = self.state.lock().await;
+            if state.source.is_none() {
+                break state;
+            }
+            drop(state);
+            released.await;
+        };
+        state.read_started = true;
+        let body = state.body.as_mut().ok_or_else(denied)?;
+        let frame = match body.next_frame().await {
+            Ok(frame) => frame,
+            Err(error) => {
+                let mut stored = self
+                    .downstream_error
+                    .lock()
+                    .unwrap_or_else(std::sync::PoisonError::into_inner);
+                if stored.is_none() {
+                    *stored = Some(error);
+                }
+                return Err(PluginFault::new(
+                    ErrorCode::Fault,
+                    "middleware downstream body failed",
+                ));
+            }
+        };
+        self.finalized.store(body.is_finalized(), Ordering::Release);
+        let Some(frame) = frame else {
+            return Ok(None);
+        };
+        let transformed = frame.transformed();
+        let (bytes, framing, terminal, envelope) = frame.into_parts();
+        if framing != self.expected_framing || bytes.len() > maximum {
+            return Err(invalid());
+        }
+        let source_id = state.next_source_id.checked_add(1).ok_or_else(invalid)?;
+        state.next_source_id = source_id;
+        state.source = Some((
+            source_id,
+            SourceFrame {
+                bytes: bytes.clone(),
+                framing,
+                terminal,
+                transformed,
+                envelope,
+            },
+        ));
+        Ok(Some(BodyReadFrame {
+            bytes,
+            framing,
+            source_id,
+            terminal,
+        }))
+    }
+
+    pub(super) async fn take_unread(&self) -> Option<Box<dyn MiddlewareBody>> {
+        let mut state = self.state.lock().await;
+        if state.read_started {
+            return None;
+        }
+        state.body.take()
+    }
+
+    pub(super) async fn close(&self) {
+        let body = {
+            let mut state = self.state.lock().await;
+            state.source.take();
+            self.source_released.notify_waiters();
+            state.body.take()
+        };
+        if let Some(body) = body {
+            body.close().await;
+        }
+    }
+
+    pub(super) fn close_detached(self: Arc<Self>) {
+        if let Ok(handle) = tokio::runtime::Handle::try_current() {
+            handle.spawn(async move { self.close().await });
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/callback/middleware/headers.rs b/backend/crates/gateway-plugin/runtime/src/callback/middleware/headers.rs
new file mode 100644
index 000000000..4c7876aa1
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/callback/middleware/headers.rs
@@ -0,0 +1,157 @@
+use bytes::Bytes;
+use gateway_core::engine::middleware::MiddlewareHeader;
+use gateway_plugin_sdk::{
+    PluginFault,
+    call::middleware::{MiddlewareHeader as WireHeader, MiddlewareHeaderMutation},
+};
+use gateway_protocol::openai::{
+    is_transport_managed_request_header, response_header_is_forwardable,
+};
+
+use super::{denied, invalid};
+
+const MAX_HEADERS: usize = 128;
+const MAX_HEADER_NAME_BYTES: usize = 128;
+const MAX_HEADER_VALUE_BYTES: usize = 16 * 1024;
+const MAX_HEADER_TOTAL_BYTES: usize = 64 * 1024;
+
+#[derive(Clone, Copy)]
+pub(super) enum HeaderDirection {
+    Request,
+    Response,
+}
+
+pub(super) fn apply_header_mutations(
+    headers: &mut Vec<MiddlewareHeader>,
+    mutations: &[MiddlewareHeaderMutation],
+    direction: HeaderDirection,
+) -> Result<(), PluginFault> {
+    if mutations.len() > MAX_HEADERS {
+        return Err(invalid());
+    }
+    validate_headers(headers)?;
+    let connection_options = connection_options(headers);
+    for mutation in mutations {
+        let (name, value) = match mutation {
+            MiddlewareHeaderMutation::Remove { name } => (normalized_header_name(name)?, None),
+            MiddlewareHeaderMutation::Append { name, value } => {
+                if value.len() > MAX_HEADER_VALUE_BYTES {
+                    return Err(invalid());
+                }
+                (normalized_header_name(name)?, Some(value.clone()))
+            }
+        };
+        if name == "x-gateway-request-id"
+            || !header_is_visible(&name, direction)
+            || connection_options.iter().any(|option| option == &name)
+        {
+            return Err(denied());
+        }
+        match value {
+            None => headers.retain(|header| !header.name().eq_ignore_ascii_case(&name)),
+            Some(value) => headers.push(MiddlewareHeader::new(name, Bytes::from(value))),
+        }
+    }
+    validate_headers(headers)
+}
+
+/// 原始头保留给宿主；这里检查格式与大小，可见性和写权限由各自边界控制。
+pub(super) fn validate_headers(headers: &[MiddlewareHeader]) -> Result<(), PluginFault> {
+    if headers.len() > MAX_HEADERS {
+        return Err(invalid());
+    }
+    let mut total = 0_usize;
+    for header in headers {
+        let name = normalized_header_name(header.name())?;
+        if header.value().len() > MAX_HEADER_VALUE_BYTES
+            || header
+                .value()
+                .iter()
+                .any(|byte| *byte != b'\t' && (*byte < b' ' || *byte == 0x7f))
+        {
+            return Err(invalid());
+        }
+        total = total
+            .checked_add(name.len())
+            .and_then(|value| value.checked_add(header.value().len()))
+            .ok_or_else(invalid)?;
+        if total > MAX_HEADER_TOTAL_BYTES {
+            return Err(invalid());
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn project_headers(
+    headers: &[MiddlewareHeader],
+    direction: HeaderDirection,
+) -> Result<Vec<WireHeader>, PluginFault> {
+    validate_headers(headers)?;
+    let connection_options = connection_options(headers);
+    let mut projected = Vec::with_capacity(headers.len());
+    for header in headers {
+        let name = normalized_header_name(header.name())?;
+        if header_is_visible(&name, direction)
+            && !connection_options.iter().any(|option| option == &name)
+        {
+            projected.push(WireHeader {
+                name,
+                value: header.value().to_vec(),
+            });
+        }
+    }
+    Ok(projected)
+}
+
+fn normalized_header_name(name: &str) -> Result<String, PluginFault> {
+    let name = name.to_ascii_lowercase();
+    if name.is_empty()
+        || name.len() > MAX_HEADER_NAME_BYTES
+        || !name
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || b"!#$%&'*+-.^_`|~".contains(&byte))
+    {
+        return Err(invalid());
+    }
+    Ok(name)
+}
+
+fn header_is_visible(name: &str, direction: HeaderDirection) -> bool {
+    !sensitive_or_identity_header(name)
+        && match direction {
+            HeaderDirection::Request => !is_transport_managed_request_header(name),
+            HeaderDirection::Response => response_header_is_forwardable(name, &[]),
+        }
+}
+
+fn connection_options(headers: &[MiddlewareHeader]) -> Vec<String> {
+    headers
+        .iter()
+        .filter(|header| header.name().eq_ignore_ascii_case("connection"))
+        .filter_map(|header| std::str::from_utf8(header.value()).ok())
+        .flat_map(|value| value.split(','))
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+        .map(str::to_ascii_lowercase)
+        .collect()
+}
+
+fn sensitive_or_identity_header(name: &str) -> bool {
+    name.contains("auth")
+        || name.contains("credential")
+        || name.contains("secret")
+        || name.contains("token")
+        || name.contains("cookie")
+        || name.contains("session")
+        || name.contains("conversation")
+        || name.contains("thread")
+        || name.contains("account")
+        || name.contains("organization")
+        || name.contains("project")
+        || name.contains("tenant")
+        || name.contains("principal")
+        || name.contains("identity")
+        || name.contains("user-id")
+        || name.ends_with("-key")
+        || name.ends_with("_key")
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/callback/middleware/mod.rs b/backend/crates/gateway-plugin/runtime/src/callback/middleware/mod.rs
new file mode 100644
index 000000000..61c59a678
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/callback/middleware/mod.rs
@@ -0,0 +1,584 @@
+mod body;
+mod headers;
+
+use std::sync::{Arc, Mutex};
+
+use bytes::Bytes;
+use gateway_core::engine::{
+    execution::ClientTransport,
+    middleware::{
+        MiddlewareBody, MiddlewareContext, MiddlewareError, MiddlewareFraming, MiddlewareHeader,
+        MiddlewareNext, MiddlewareRequest, MiddlewareResponseEnvelope,
+    },
+};
+use gateway_plugin_sdk::{
+    ErrorCode, PluginFault,
+    call::middleware::{
+        BODY_CLOSE_METHOD, BODY_READ_METHOD, MiddlewareBodyClose, MiddlewareBodyCloseResult,
+        MiddlewareBodyFraming, MiddlewareBodyHandle, MiddlewareBodyRead, MiddlewareBodyReadResult,
+        MiddlewareHeader as WireHeader, MiddlewareNextRequest, MiddlewareNextResponse,
+        MiddlewareRequestBody, MiddlewareResponseBody, MiddlewareResponseHead, NEXT_METHOD,
+    },
+};
+
+use crate::RpcReply;
+
+use super::PluginCallbacks;
+use body::BodyResource;
+pub(crate) use body::MiddlewareBodyAuthority;
+use headers::{HeaderDirection, apply_header_mutations, project_headers, validate_headers};
+
+pub(crate) struct MiddlewareInvocation {
+    requests_authorized: bool,
+    transport: ClientTransport,
+    state: Mutex<InvocationState>,
+    downstream_error: Arc<Mutex<Option<MiddlewareError>>>,
+}
+
+pub(crate) struct MiddlewareBinding {
+    callbacks: Arc<PluginCallbacks>,
+    resource_scope_id: String,
+    invocation: Arc<MiddlewareInvocation>,
+}
+
+struct InvocationState {
+    closed: bool,
+    original_request: MiddlewareRequest,
+    next: Option<Box<dyn MiddlewareNext>>,
+    next_consumed: bool,
+    response: Option<DownstreamResponse>,
+}
+
+struct DownstreamResponse {
+    id: String,
+    protocol: String,
+    status: u16,
+    headers: Vec<MiddlewareHeader>,
+    body_handle: String,
+    body: Arc<BodyResource>,
+    envelope: Option<MiddlewareResponseEnvelope>,
+}
+
+pub(crate) struct MiddlewareCompletion {
+    pub(crate) protocol: String,
+    pub(crate) status: u16,
+    pub(crate) headers: Vec<MiddlewareHeader>,
+    pub(crate) body: MiddlewareCompletionBody,
+    pub(crate) envelope: Option<MiddlewareResponseEnvelope>,
+}
+
+pub(crate) enum MiddlewareCompletionBody {
+    Empty,
+    PassThrough(Box<dyn MiddlewareBody>),
+    Stream {
+        framing: MiddlewareFraming,
+        downstream: Option<MiddlewareBodyAuthority>,
+    },
+}
+
+impl MiddlewareInvocation {
+    pub(crate) fn new(
+        context: &MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+        requests_authorized: bool,
+    ) -> Arc<Self> {
+        Arc::new(Self {
+            requests_authorized,
+            transport: context.transport(),
+            state: Mutex::new(InvocationState {
+                closed: false,
+                original_request: request,
+                next: Some(next),
+                next_consumed: false,
+                response: None,
+            }),
+            downstream_error: Arc::new(Mutex::new(None)),
+        })
+    }
+
+    pub(crate) fn request_projection(
+        &self,
+    ) -> Result<(String, Vec<WireHeader>, bool, Vec<u8>), PluginFault> {
+        let state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let headers = if self.requests_authorized {
+            project_headers(state.original_request.headers(), HeaderDirection::Request)?
+        } else {
+            Vec::new()
+        };
+        let body_visible = self.requests_authorized;
+        let body = if body_visible {
+            state.original_request.body().to_vec()
+        } else {
+            Vec::new()
+        };
+        Ok((
+            state.original_request.protocol().to_owned(),
+            headers,
+            body_visible,
+            body,
+        ))
+    }
+
+    pub(crate) fn take_delegate(&self) -> Option<(Box<dyn MiddlewareNext>, MiddlewareRequest)> {
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if state.next_consumed {
+            return None;
+        }
+        state
+            .next
+            .take()
+            .map(|next| (next, state.original_request.clone()))
+    }
+
+    pub(crate) fn take_downstream_error(&self) -> Option<MiddlewareError> {
+        self.downstream_error
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .take()
+    }
+
+    pub(crate) fn close(&self) {
+        let body = {
+            let mut state = self
+                .state
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            state.closed = true;
+            state.response.take().map(|response| response.body)
+        };
+        if let Some(body) = body {
+            body.close_detached();
+        }
+    }
+
+    pub(crate) async fn call(
+        self: &Arc<Self>,
+        method: &str,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+        maximum_payload: usize,
+    ) -> Result<RpcReply, PluginFault> {
+        match method {
+            NEXT_METHOD => self.call_next(params, payload).await,
+            BODY_READ_METHOD => self.call_body_read(params, payload, maximum_payload).await,
+            BODY_CLOSE_METHOD => self.call_body_close(params, payload).await,
+            _ => Err(denied()),
+        }
+    }
+
+    async fn call_next(
+        self: &Arc<Self>,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+    ) -> Result<RpcReply, PluginFault> {
+        let request: MiddlewareNextRequest =
+            serde_json::from_value(params).map_err(|_| invalid())?;
+        let (next, original) = {
+            let mut state = self
+                .state
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            if state.closed || state.next_consumed {
+                return Err(conflict());
+            }
+            state.next_consumed = true;
+            let next = state.next.take().ok_or_else(conflict)?;
+            (next, state.original_request.clone())
+        };
+        let request = self.apply_next_request(original, request, payload)?;
+        let response = match next.run(request).await {
+            Ok(response) => response,
+            Err(error) => {
+                self.record_downstream_error(error);
+                return Err(PluginFault::new(
+                    ErrorCode::Fault,
+                    "middleware downstream failed",
+                ));
+            }
+        };
+        let (protocol, status, headers, body, envelope) = response.into_parts();
+        validate_protocol(&protocol)?;
+        validate_status(status)?;
+        validate_headers(&headers)?;
+        let expected_framing = framing_for_response(self.transport, status);
+        let response_id = uuid::Uuid::new_v4().to_string();
+        let body_handle = uuid::Uuid::new_v4().to_string();
+        let body = BodyResource::new(expected_framing, Arc::clone(&self.downstream_error), body);
+        let visible_headers = if self.requests_authorized {
+            project_headers(&headers, HeaderDirection::Response)?
+        } else {
+            Vec::new()
+        };
+        {
+            let mut state = self
+                .state
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            if state.closed || state.response.is_some() {
+                drop(state);
+                body.close_detached();
+                return Err(denied());
+            }
+            state.response = Some(DownstreamResponse {
+                id: response_id.clone(),
+                protocol: protocol.clone(),
+                status,
+                headers,
+                body_handle: body_handle.clone(),
+                body,
+                envelope,
+            });
+        }
+        let result = MiddlewareNextResponse {
+            response: response_id,
+            protocol,
+            status,
+            headers: visible_headers,
+            body: Some(MiddlewareBodyHandle {
+                handle: body_handle,
+                framing: wire_framing(expected_framing),
+            }),
+        };
+        Ok(RpcReply {
+            result: serde_json::to_value(result).map_err(|_| invalid())?,
+            payload: Vec::new(),
+        })
+    }
+
+    fn apply_next_request(
+        &self,
+        original: MiddlewareRequest,
+        request: MiddlewareNextRequest,
+        payload: Vec<u8>,
+    ) -> Result<MiddlewareRequest, PluginFault> {
+        let (mut protocol, mut headers, original_body) = original.into_parts();
+        if let Some(replacement) = request.protocol {
+            if !self.requests_authorized {
+                return Err(denied());
+            }
+            validate_protocol(&replacement)?;
+            protocol = replacement;
+        }
+        if !request.header_mutations.is_empty() {
+            if !self.requests_authorized {
+                return Err(denied());
+            }
+            apply_header_mutations(
+                &mut headers,
+                &request.header_mutations,
+                HeaderDirection::Request,
+            )?;
+        }
+        let body = match request.body {
+            MiddlewareRequestBody::Preserve if payload.is_empty() => original_body,
+            MiddlewareRequestBody::Preserve => return Err(invalid()),
+            MiddlewareRequestBody::Replace if self.requests_authorized => Bytes::from(payload),
+            MiddlewareRequestBody::Replace => return Err(denied()),
+        };
+        Ok(MiddlewareRequest::new(protocol, headers, body))
+    }
+
+    async fn call_body_read(
+        &self,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+        maximum_payload: usize,
+    ) -> Result<RpcReply, PluginFault> {
+        if !payload.is_empty() {
+            return Err(invalid());
+        }
+        if !self.requests_authorized {
+            return Err(denied());
+        }
+        let request: MiddlewareBodyRead = serde_json::from_value(params).map_err(|_| invalid())?;
+        let maximum = usize::try_from(request.maximum_bytes).map_err(|_| invalid())?;
+        if maximum == 0 || maximum > maximum_payload {
+            return Err(invalid());
+        }
+        let body = self.body(&request.handle)?;
+        let frame = body.read(maximum).await?;
+        let (result, payload) = match frame {
+            Some(frame) => (
+                MiddlewareBodyReadResult {
+                    framing: wire_framing(frame.framing),
+                    source_id: frame.source_id,
+                    eof: false,
+                    terminal: frame.terminal,
+                },
+                frame.bytes.to_vec(),
+            ),
+            None => (
+                MiddlewareBodyReadResult {
+                    framing: wire_framing(body.expected_framing()),
+                    source_id: 0,
+                    eof: true,
+                    terminal: false,
+                },
+                Vec::new(),
+            ),
+        };
+        Ok(RpcReply {
+            result: serde_json::to_value(result).map_err(|_| invalid())?,
+            payload,
+        })
+    }
+
+    async fn call_body_close(
+        &self,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+    ) -> Result<RpcReply, PluginFault> {
+        if !payload.is_empty() || !self.requests_authorized {
+            return Err(denied());
+        }
+        let request: MiddlewareBodyClose = serde_json::from_value(params).map_err(|_| invalid())?;
+        let body = self.body(&request.handle)?;
+        body.close().await;
+        Ok(RpcReply {
+            result: serde_json::to_value(MiddlewareBodyCloseResult {}).map_err(|_| invalid())?,
+            payload: Vec::new(),
+        })
+    }
+
+    fn body(&self, handle: &str) -> Result<Arc<BodyResource>, PluginFault> {
+        let state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let response = state.response.as_ref().ok_or_else(denied)?;
+        if state.closed || response.body_handle != handle {
+            return Err(denied());
+        }
+        Ok(Arc::clone(&response.body))
+    }
+
+    pub(crate) async fn resolve_response(
+        &self,
+        response: MiddlewareResponseHead,
+    ) -> Result<MiddlewareCompletion, MiddlewareError> {
+        if let Some(error) = self.take_downstream_error() {
+            return Err(error);
+        }
+        let downstream = {
+            let mut state = self
+                .state
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            match response.response.as_deref() {
+                Some(id) => {
+                    let stored = state
+                        .response
+                        .as_mut()
+                        .ok_or(MiddlewareError::InvalidState)?;
+                    if stored.id != id {
+                        return Err(MiddlewareError::InvalidState);
+                    }
+                    Some((
+                        stored.protocol.clone(),
+                        stored.status,
+                        stored.headers.clone(),
+                        stored.body_handle.clone(),
+                        Arc::clone(&stored.body),
+                        stored.envelope.take(),
+                    ))
+                }
+                None => {
+                    if state.response.is_some() {
+                        return Err(MiddlewareError::InvalidState);
+                    }
+                    None
+                }
+            }
+        };
+        let (mut protocol, mut status, mut headers) = match &downstream {
+            Some((protocol, status, headers, ..)) => (protocol.clone(), *status, headers.clone()),
+            None => (
+                response
+                    .protocol
+                    .clone()
+                    .ok_or(MiddlewareError::InvalidState)?,
+                response.status.ok_or(MiddlewareError::InvalidState)?,
+                Vec::new(),
+            ),
+        };
+        if let Some(replacement) = response.protocol {
+            validate_protocol(&replacement).map_err(|_| MiddlewareError::InvalidState)?;
+            if downstream.is_some() && replacement != protocol && !self.requests_authorized {
+                return Err(MiddlewareError::InvalidState);
+            }
+            protocol = replacement;
+        }
+        if let Some(replacement) = response.status {
+            validate_status(replacement).map_err(|_| MiddlewareError::InvalidState)?;
+            if downstream.is_some() && replacement != status && !self.requests_authorized {
+                return Err(MiddlewareError::InvalidState);
+            }
+            status = replacement;
+        }
+        if !response.header_mutations.is_empty() {
+            if downstream.is_some() && !self.requests_authorized {
+                return Err(MiddlewareError::InvalidState);
+            }
+            apply_header_mutations(
+                &mut headers,
+                &response.header_mutations,
+                HeaderDirection::Response,
+            )
+            .map_err(|_| MiddlewareError::InvalidState)?;
+        }
+        let body = match response.body {
+            MiddlewareResponseBody::PassThrough { body } => {
+                let (_, _, _, body_handle, stored_body, _) =
+                    downstream.as_ref().ok_or(MiddlewareError::InvalidState)?;
+                if body_handle != &body.handle
+                    || wire_framing(stored_body.expected_framing()) != body.framing
+                {
+                    return Err(MiddlewareError::InvalidState);
+                }
+                MiddlewareCompletionBody::PassThrough(
+                    stored_body
+                        .take_unread()
+                        .await
+                        .ok_or(MiddlewareError::InvalidState)?,
+                )
+            }
+            MiddlewareResponseBody::Empty => {
+                // 调用过 next 后不能靠关闭下游流伪装成已完成；需要丢弃正文时也必须
+                // 通过 preserving mapper 拉取到底，才能保留计量、终态和取消合同。
+                if downstream.is_some() {
+                    return Err(MiddlewareError::InvalidState);
+                }
+                MiddlewareCompletionBody::Empty
+            }
+            MiddlewareResponseBody::Stream { framing } => {
+                let framing = core_framing(framing);
+                let expected = downstream.as_ref().map_or_else(
+                    || framing_for_response(self.transport, status),
+                    |(_, _, _, _, body, _)| body.expected_framing(),
+                );
+                if !self.requests_authorized || framing != expected {
+                    return Err(MiddlewareError::InvalidState);
+                }
+                MiddlewareCompletionBody::Stream {
+                    framing,
+                    downstream: downstream.as_ref().map(|(_, _, _, _, body, _)| {
+                        MiddlewareBodyAuthority::new(Arc::clone(body))
+                    }),
+                }
+            }
+        };
+        Ok(MiddlewareCompletion {
+            protocol,
+            status,
+            headers,
+            body,
+            envelope: downstream.and_then(|(_, _, _, _, _, envelope)| envelope),
+        })
+    }
+
+    fn record_downstream_error(&self, error: MiddlewareError) {
+        let mut stored = self
+            .downstream_error
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if stored.is_none() {
+            *stored = Some(error);
+        }
+    }
+
+    pub(crate) fn downstream_error_slot(&self) -> Arc<Mutex<Option<MiddlewareError>>> {
+        Arc::clone(&self.downstream_error)
+    }
+}
+
+impl MiddlewareBinding {
+    pub(super) fn new(
+        callbacks: Arc<PluginCallbacks>,
+        resource_scope_id: String,
+        invocation: Arc<MiddlewareInvocation>,
+    ) -> Self {
+        Self {
+            callbacks,
+            resource_scope_id,
+            invocation,
+        }
+    }
+}
+
+impl Drop for MiddlewareBinding {
+    fn drop(&mut self) {
+        self.callbacks
+            .unbind_middleware(&self.resource_scope_id, &self.invocation);
+    }
+}
+
+impl Drop for MiddlewareInvocation {
+    fn drop(&mut self) {
+        self.close();
+    }
+}
+
+fn validate_protocol(protocol: &str) -> Result<(), PluginFault> {
+    if protocol.is_empty() || protocol.len() > 64 || protocol.chars().any(char::is_control) {
+        return Err(invalid());
+    }
+    Ok(())
+}
+
+fn validate_status(status: u16) -> Result<(), PluginFault> {
+    if !(100..=599).contains(&status) {
+        return Err(invalid());
+    }
+    Ok(())
+}
+
+const fn framing_for_response(transport: ClientTransport, status: u16) -> MiddlewareFraming {
+    if status < 200 || status >= 300 {
+        return MiddlewareFraming::RawBytes;
+    }
+    match transport {
+        ClientTransport::HttpJson => MiddlewareFraming::JsonDocument,
+        ClientTransport::HttpSse => MiddlewareFraming::SseEvent,
+        ClientTransport::WebSocket
+        | ClientTransport::InternalProbe
+        | ClientTransport::InternalPlugin => MiddlewareFraming::RawBytes,
+    }
+}
+
+const fn wire_framing(framing: MiddlewareFraming) -> MiddlewareBodyFraming {
+    match framing {
+        MiddlewareFraming::JsonDocument => MiddlewareBodyFraming::JsonDocument,
+        MiddlewareFraming::SseEvent => MiddlewareBodyFraming::SseEvent,
+        MiddlewareFraming::RawBytes => MiddlewareBodyFraming::RawBytes,
+    }
+}
+
+pub(crate) const fn core_framing(framing: MiddlewareBodyFraming) -> MiddlewareFraming {
+    match framing {
+        MiddlewareBodyFraming::JsonDocument => MiddlewareFraming::JsonDocument,
+        MiddlewareBodyFraming::SseEvent => MiddlewareFraming::SseEvent,
+        MiddlewareBodyFraming::RawBytes => MiddlewareFraming::RawBytes,
+    }
+}
+
+fn denied() -> PluginFault {
+    PluginFault::new(
+        ErrorCode::PermissionDenied,
+        "middleware resource is not authorized",
+    )
+}
+
+fn invalid() -> PluginFault {
+    PluginFault::new(ErrorCode::InvalidInput, "middleware input is invalid")
+}
+
+fn conflict() -> PluginFault {
+    PluginFault::new(ErrorCode::Conflict, "middleware next was already consumed")
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/callback/mod.rs b/backend/crates/gateway-plugin/runtime/src/callback/mod.rs
new file mode 100644
index 000000000..02626e34c
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/callback/mod.rs
@@ -0,0 +1,530 @@
+mod accounts;
+mod affinity;
+mod http;
+mod keys;
+mod log;
+mod middleware;
+mod model;
+pub(crate) mod private_state;
+mod scope;
+
+use std::{
+    collections::BTreeMap,
+    sync::{Arc, Mutex, Weak},
+    time::Duration,
+};
+
+use futures::future::BoxFuture;
+use gateway_admin::model::{AdminError, plugins::instances::PluginPermissionGrant};
+use gateway_core::{account::OutboundProxy, lifecycle::CancellationToken};
+use gateway_host::outbound::{HttpBody, HttpClient, NetworkPolicy};
+use gateway_plugin_sdk::{CallContext, ErrorCode, PluginFault, Stage};
+use tokio::time::Instant;
+
+use crate::{CallbackHandler, RpcReply};
+pub(crate) use accounts::PluginAccountPortSlot;
+pub(crate) use affinity::PluginAffinityPortSlot;
+pub(crate) use keys::PluginClientKeyPortSlot;
+pub(crate) use middleware::{
+    MiddlewareBinding, MiddlewareBodyAuthority, MiddlewareCompletionBody, MiddlewareInvocation,
+};
+pub(crate) use model::PluginModelPortSlot;
+pub(crate) use scope::NetworkScope;
+
+pub(crate) struct PluginCallbackPorts {
+    http: Arc<HttpClient>,
+    network: NetworkPolicy,
+    accounts: Arc<PluginAccountPortSlot>,
+    keys: Arc<PluginClientKeyPortSlot>,
+    models: Arc<PluginModelPortSlot>,
+    affinity: Arc<PluginAffinityPortSlot>,
+}
+
+impl PluginCallbackPorts {
+    pub(crate) fn new(
+        http: Arc<HttpClient>,
+        network: NetworkPolicy,
+        accounts: Arc<PluginAccountPortSlot>,
+        keys: Arc<PluginClientKeyPortSlot>,
+        models: Arc<PluginModelPortSlot>,
+        affinity: Arc<PluginAffinityPortSlot>,
+    ) -> Self {
+        Self {
+            http,
+            network,
+            accounts,
+            keys,
+            models,
+            affinity,
+        }
+    }
+}
+
+pub(crate) struct PluginCallbacks {
+    accounts: Arc<accounts::PluginAccounts>,
+    keys: Arc<PluginClientKeyPortSlot>,
+    models_authorized: bool,
+    affinity: Arc<affinity::PluginAffinity>,
+    log: Arc<log::PluginLog>,
+    models: Arc<model::PluginModels>,
+    private_state: Arc<private_state::PluginPrivateState>,
+    http: Arc<HttpClient>,
+    http_authorization: Arc<HttpAuthorization>,
+    scopes: Mutex<BTreeMap<String, Weak<NetworkScope>>>,
+    pending_middleware: Mutex<BTreeMap<String, Arc<MiddlewareInvocation>>>,
+    calls: Mutex<BTreeMap<u64, Arc<CallResources>>>,
+    maximum_payload: usize,
+}
+
+struct HttpAuthorization {
+    network: NetworkPolicy,
+    authorized: bool,
+}
+
+struct CallResources {
+    deadline: Instant,
+    cancellation: CancellationToken,
+    scope: Arc<NetworkScope>,
+    model_bindings: tokio::sync::Mutex<
+        BTreeMap<String, gateway_core::engine::execution::BoundModelExecutionContext>,
+    >,
+    state: Mutex<CallState>,
+}
+
+#[derive(Default)]
+struct CallState {
+    closed: bool,
+    middleware: Option<Arc<MiddlewareInvocation>>,
+    streams: BTreeMap<String, Arc<HttpStream>>,
+    model_streams: BTreeMap<String, Arc<model::ModelStream>>,
+}
+
+struct HttpStream {
+    body: tokio::sync::Mutex<Option<HttpBody>>,
+    closed: tokio::sync::watch::Sender<bool>,
+}
+
+impl HttpStream {
+    fn close(&self) {
+        self.closed.send_replace(true);
+        if let Ok(mut body) = self.body.try_lock() {
+            body.take();
+        }
+    }
+}
+
+impl PluginCallbacks {
+    pub(crate) fn new(
+        grants: &[PluginPermissionGrant],
+        maximum_payload: usize,
+        manifest: &gateway_plugin_sdk::Manifest,
+        log_slots: Arc<tokio::sync::Semaphore>,
+        private_state: Arc<private_state::PluginPrivateState>,
+        ports: PluginCallbackPorts,
+    ) -> Result<Self, AdminError> {
+        Ok(Self {
+            accounts: Arc::new(accounts::PluginAccounts::new(ports.accounts, grants)),
+            keys: ports.keys,
+            models_authorized: grants.iter().any(|grant| grant.permission == "models"),
+            affinity: Arc::new(affinity::PluginAffinity::new(ports.affinity, grants)),
+            log: Arc::new(
+                log::PluginLog::new(manifest, log_slots)
+                    .map_err(|_| AdminError::invalid("插件清单身份不合法"))?,
+            ),
+            models: Arc::new(model::PluginModels::new(
+                ports.models,
+                grants,
+                maximum_payload,
+            )),
+            private_state,
+            http: ports.http,
+            http_authorization: Arc::new(HttpAuthorization {
+                network: ports.network,
+                authorized: grants.iter().any(|grant| grant.permission == "network"),
+            }),
+            scopes: Mutex::new(BTreeMap::new()),
+            pending_middleware: Mutex::new(BTreeMap::new()),
+            calls: Mutex::new(BTreeMap::new()),
+            maximum_payload,
+        })
+    }
+
+    pub(crate) async fn save_discovered_facts(
+        &self,
+        context: &CallContext,
+        scope: &NetworkScope,
+        account: &gateway_core::account::ProviderAccount,
+        facts: gateway_plugin_sdk::call::auth::CredentialFacts,
+    ) -> Result<gateway_admin::model::provider_credentials::PluginAccountSaveResult, AdminError>
+    {
+        self.accounts
+            .save_discovered_facts(context, scope, account, facts)
+            .await
+    }
+
+    pub(crate) fn bind_middleware(
+        self: &Arc<Self>,
+        resource_scope_id: String,
+        invocation: Arc<MiddlewareInvocation>,
+    ) -> Result<MiddlewareBinding, gateway_core::engine::middleware::MiddlewareError> {
+        let mut pending = self
+            .pending_middleware
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if pending
+            .insert(resource_scope_id.clone(), Arc::clone(&invocation))
+            .is_some()
+        {
+            return Err(gateway_core::engine::middleware::MiddlewareError::InvalidState);
+        }
+        Ok(MiddlewareBinding::new(
+            Arc::clone(self),
+            resource_scope_id,
+            invocation,
+        ))
+    }
+
+    fn unbind_middleware(&self, resource_scope_id: &str, invocation: &Arc<MiddlewareInvocation>) {
+        let mut pending = self
+            .pending_middleware
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if pending
+            .get(resource_scope_id)
+            .is_some_and(|pending| Arc::ptr_eq(pending, invocation))
+        {
+            pending.remove(resource_scope_id);
+        }
+    }
+
+    pub(crate) fn prepare_execution(
+        &self,
+        context: &CallContext,
+        proxy: Option<OutboundProxy>,
+    ) -> Result<Arc<NetworkScope>, PluginFault> {
+        if context.stage != gateway_plugin_sdk::Stage::Attempt
+            || context.account_id.is_none()
+            || context.credential_revision.is_none()
+            || context.attempt_id.is_none()
+        {
+            return Err(denied());
+        }
+        self.prepare_scope(context, proxy)
+    }
+
+    pub(crate) fn prepare_data_plane(
+        &self,
+        context: &CallContext,
+        effects: Arc<gateway_core::engine::nested::ExecutionEffects>,
+    ) -> Result<Arc<NetworkScope>, PluginFault> {
+        if !matches!(
+            context.stage,
+            gateway_plugin_sdk::Stage::Request
+                | gateway_plugin_sdk::Stage::Attempt
+                | gateway_plugin_sdk::Stage::Routing
+                | gateway_plugin_sdk::Stage::Scheduling
+        ) {
+            return Err(denied());
+        }
+        self.register_scope(
+            context,
+            NetworkScope::for_call(context).with_execution_effects(effects),
+        )
+    }
+
+    pub(crate) fn prepare_management(
+        &self,
+        context: &CallContext,
+        proxy: Option<OutboundProxy>,
+    ) -> Result<Arc<NetworkScope>, PluginFault> {
+        if !matches!(
+            context.stage,
+            gateway_plugin_sdk::Stage::Management | gateway_plugin_sdk::Stage::Maintenance
+        ) {
+            return Err(denied());
+        }
+        self.prepare_scope(context, proxy)
+    }
+
+    pub(crate) fn prepare_command_line(
+        &self,
+        context: &CallContext,
+    ) -> Result<Arc<NetworkScope>, PluginFault> {
+        if context.stage != gateway_plugin_sdk::Stage::CommandLine {
+            return Err(denied());
+        }
+        let scope = self.prepare_scope(context, None)?;
+        scope.activate();
+        Ok(scope)
+    }
+
+    pub(crate) fn prepare_frontend_authentication(
+        &self,
+        context: &CallContext,
+    ) -> Result<Arc<NetworkScope>, PluginFault> {
+        if context.stage != gateway_plugin_sdk::Stage::Authentication
+            || context.account_id.is_some()
+            || context.credential_revision.is_some()
+            || context.attempt_id.is_some()
+        {
+            return Err(denied());
+        }
+        let scope = self.prepare_scope(context, None)?;
+        scope.activate();
+        Ok(scope)
+    }
+
+    pub(crate) async fn save_command_account(
+        &self,
+        context: &CallContext,
+        scope: &NetworkScope,
+        request: gateway_plugin_sdk::call::host::AuthSaveRequest,
+    ) -> Result<gateway_plugin_sdk::call::host::AuthSaveResult, PluginFault> {
+        if context.stage != gateway_plugin_sdk::Stage::CommandLine || !scope.authorizes(context) {
+            return Err(denied());
+        }
+        self.accounts.save(context, scope, request).await
+    }
+
+    fn prepare_scope(
+        &self,
+        context: &CallContext,
+        proxy: Option<OutboundProxy>,
+    ) -> Result<Arc<NetworkScope>, PluginFault> {
+        self.register_scope(context, NetworkScope::new(context, proxy))
+    }
+
+    pub(crate) fn prepare_observation(
+        &self,
+        context: &CallContext,
+        extension_scope: gateway_core::engine::extensions::ExtensionCallScope,
+    ) -> Result<Arc<NetworkScope>, PluginFault> {
+        let mut scope = NetworkScope::for_call(context);
+        scope.extension_scope = extension_scope;
+        self.register_scope(context, scope)
+    }
+
+    fn register_scope(
+        &self,
+        context: &CallContext,
+        scope: NetworkScope,
+    ) -> Result<Arc<NetworkScope>, PluginFault> {
+        let scope = Arc::new(scope);
+        let mut scopes = self
+            .scopes
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        scopes.retain(|_, scope| scope.strong_count() != 0);
+        if scopes
+            .get(&context.resource_scope_id)
+            .and_then(Weak::upgrade)
+            .is_some()
+        {
+            return Err(denied());
+        }
+        scopes.insert(context.resource_scope_id.clone(), Arc::downgrade(&scope));
+        Ok(scope)
+    }
+}
+
+impl CallbackHandler for PluginCallbacks {
+    fn begin(&self, context: &CallContext) {
+        let scope = self
+            .scopes
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .get(&context.resource_scope_id)
+            .and_then(Weak::upgrade)
+            .unwrap_or_else(|| Arc::new(NetworkScope::for_call(context)));
+        let middleware = self
+            .pending_middleware
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .remove(&context.resource_scope_id);
+        self.calls
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .insert(
+                context.call_id,
+                Arc::new(CallResources {
+                    deadline: Instant::now() + Duration::from_millis(context.timeout_ms),
+                    cancellation: CancellationToken::new(),
+                    scope,
+                    model_bindings: tokio::sync::Mutex::new(BTreeMap::new()),
+                    state: Mutex::new(CallState {
+                        middleware,
+                        ..CallState::default()
+                    }),
+                }),
+            );
+    }
+
+    fn finish(&self, context: &CallContext) {
+        if let Some(call) = self
+            .calls
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .remove(&context.call_id)
+        {
+            call.cancellation.cancel();
+            let mut state = call
+                .state
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            state.closed = true;
+            // RPC End 可以先于消费者取完已入队的中间件正文到达。这里只撤销新的
+            // callback 入口；正文包装器持有 invocation，最后一个 owner 释放时再关闭
+            // 下游，避免提前丢失尚未搬运的计量/终态信封。
+            state.middleware.take();
+            for stream in state.streams.values() {
+                stream.close();
+            }
+            state.streams.clear();
+            for stream in state.model_streams.values() {
+                stream.close();
+            }
+            state.model_streams.clear();
+        }
+    }
+
+    fn call(
+        &self,
+        context: CallContext,
+        method: String,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+    ) -> BoxFuture<'static, Result<RpcReply, PluginFault>> {
+        let call = self
+            .calls
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .get(&context.call_id)
+            .cloned();
+        let http = self.http.clone();
+        let authorization = self.http_authorization.clone();
+        let maximum_payload = self.maximum_payload;
+        let log = self.log.clone();
+        let private_state = self.private_state.clone();
+        let accounts = self.accounts.clone();
+        let keys = self.keys.clone();
+        let models_authorized = self.models_authorized;
+        let models = self.models.clone();
+        let affinity = self.affinity.clone();
+        Box::pin(async move {
+            let call = call.ok_or_else(denied)?;
+            let scope = &call.scope;
+            let (middleware, is_private_state) = {
+                let state = call
+                    .state
+                    .lock()
+                    .unwrap_or_else(std::sync::PoisonError::into_inner);
+                if state.closed || Instant::now() >= call.deadline {
+                    return Err(denied());
+                }
+                if method == "host.log" {
+                    return log.record(&context, params, &payload);
+                }
+                let middleware = if matches!(
+                    method.as_str(),
+                    gateway_plugin_sdk::call::middleware::NEXT_METHOD
+                        | gateway_plugin_sdk::call::middleware::BODY_READ_METHOD
+                        | gateway_plugin_sdk::call::middleware::BODY_CLOSE_METHOD
+                ) {
+                    Some(state.middleware.clone().ok_or_else(denied)?)
+                } else {
+                    None
+                };
+                let is_private_state = matches!(
+                    method.as_str(),
+                    "host.state.get" | "host.state.put" | "host.state.delete"
+                );
+                (middleware, is_private_state)
+            };
+            if let Some(middleware) = middleware {
+                return middleware
+                    .call(&method, params, payload, maximum_payload)
+                    .await;
+            }
+            if is_private_state {
+                return private_state.call(&method, params, &payload).await;
+            }
+            if method == "host.keys.list" {
+                if !models_authorized {
+                    return Err(denied());
+                }
+                return keys.list(params, &payload).await;
+            }
+            if method == "host.models.list" {
+                return models
+                    .call(&context, &call, None, &method, params, payload)
+                    .await;
+            }
+            if matches!(
+                method.as_str(),
+                "host.model.execute"
+                    | "host.model.execute_stream"
+                    | "host.model.stream_read"
+                    | "host.model.stream_close"
+            ) {
+                let model_scope = match context.stage {
+                    Stage::Execution => Some(
+                        Some(scope.as_ref())
+                            .filter(|scope| scope.authorizes(&context))
+                            .ok_or_else(denied)?,
+                    ),
+                    Stage::Routing
+                    | Stage::Scheduling
+                    | Stage::Request
+                    | Stage::Attempt
+                    | Stage::Observation => None,
+                    Stage::Management
+                    | Stage::CommandLine
+                    | Stage::Maintenance
+                    | Stage::Authentication => None,
+                    _ => return Err(denied()),
+                };
+                return models
+                    .call(&context, &call, model_scope, &method, params, payload)
+                    .await;
+            }
+            if method == "host.affinity.lookup" {
+                return affinity.call(&context, params, &payload).await;
+            }
+            let scope = Some(scope)
+                .filter(|scope| scope.authorizes(&context))
+                .ok_or_else(denied)?;
+            if matches!(
+                method.as_str(),
+                "host.auth.list" | "host.auth.get" | "host.auth.get_runtime" | "host.auth.save"
+            ) {
+                return accounts
+                    .call(&context, scope, &method, params, &payload)
+                    .await;
+            }
+            if !authorization.authorized {
+                return Err(denied());
+            }
+            http::dispatch(
+                &http,
+                &authorization,
+                scope,
+                &call,
+                &method,
+                params,
+                payload,
+                maximum_payload,
+            )
+            .await
+        })
+    }
+}
+
+fn denied() -> PluginFault {
+    PluginFault::new(
+        ErrorCode::PermissionDenied,
+        "callback resource is not authorized",
+    )
+}
+fn invalid() -> PluginFault {
+    PluginFault::new(ErrorCode::InvalidInput, "callback input is invalid")
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/callback/model.rs b/backend/crates/gateway-plugin/runtime/src/callback/model.rs
new file mode 100644
index 000000000..4549f3c8f
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/callback/model.rs
@@ -0,0 +1,881 @@
+//! 嵌套模型执行；只驱动 Core 会话，不拥有路由、重试或计费规则。
+
+use std::sync::{Arc, OnceLock, Weak};
+
+use bytes::Bytes;
+use gateway_admin::model::{AdminError, plugins::instances::PluginPermissionGrant};
+use gateway_core::{
+    account::ProviderAccountId,
+    engine::{
+        CommitRequirement, ModelRequestId,
+        execution::{
+            BoundModelExecutionContext, ClientTransport, ExecutionRequestMetadata, ExecutionSession,
+        },
+        nested::{
+            BoundModelExecutionBinding, BoundModelExecutionRequest, NestedModelExecutionPort,
+            NestedModelExecutionRequest,
+        },
+    },
+    error::{GatewayError, GatewayErrorKind},
+    event::{ContentKind, FinishReason, GatewayEvent, ProtocolWireEvent, ProviderEvent},
+    identity::ProviderKind,
+    operation::{
+        GenerateRequest, ImageRequest, ImageRequestKind, Operation, ProtocolPayload,
+        RawJsonPayload, StandaloneSearchRequest,
+    },
+    policy::ClientApiKeyId,
+    routing::PublicModelId,
+};
+use gateway_plugin_sdk::{
+    CallContext, ErrorCode, PluginFault,
+    call::{
+        host::{
+            ModelEventBatch, ModelExecuteRequest, ModelExecuteResult, ModelListRequest,
+            ModelListResult, ModelOperation, ModelStreamCloseRequest, ModelStreamReadRequest,
+            ModelStreamReadResult, ModelStreamResult,
+        },
+        provider::{
+            CanonicalEvent, ContentKind as WireContentKind, ExecutionEvent,
+            FinishReason as WireFinishReason, Usage as WireUsage, WireEvent, WirePayload,
+        },
+    },
+};
+
+use super::{CallResources, NetworkScope, denied, invalid};
+use crate::RpcReply;
+
+const MAX_MODEL_STREAMS_PER_CALL: usize = 16;
+
+pub(crate) struct PluginModelPortSlot {
+    port: OnceLock<Weak<dyn NestedModelExecutionPort>>,
+}
+
+impl PluginModelPortSlot {
+    pub(crate) const fn new() -> Self {
+        Self {
+            port: OnceLock::new(),
+        }
+    }
+
+    pub(crate) fn bind(&self, port: &Arc<dyn NestedModelExecutionPort>) -> Result<(), AdminError> {
+        self.port
+            .set(Arc::downgrade(port))
+            .map_err(|_| AdminError::conflict("插件模型执行端口已经绑定"))
+    }
+
+    fn upgrade(&self) -> Result<Arc<dyn NestedModelExecutionPort>, PluginFault> {
+        self.port.get().and_then(Weak::upgrade).ok_or_else(denied)
+    }
+}
+
+pub(super) struct PluginModels {
+    slot: Arc<PluginModelPortSlot>,
+    authorized: bool,
+    maximum_payload: usize,
+}
+
+impl PluginModels {
+    pub(super) fn new(
+        slot: Arc<PluginModelPortSlot>,
+        grants: &[PluginPermissionGrant],
+        maximum_payload: usize,
+    ) -> Self {
+        Self {
+            slot,
+            authorized: grants.iter().any(|grant| grant.permission == "models"),
+            maximum_payload,
+        }
+    }
+
+    pub(super) async fn call(
+        &self,
+        context: &CallContext,
+        call: &Arc<CallResources>,
+        scope: Option<&NetworkScope>,
+        method: &str,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+    ) -> Result<RpcReply, PluginFault> {
+        if !self.authorized {
+            return Err(denied());
+        }
+        match method {
+            "host.models.list" => {
+                if !payload.is_empty() {
+                    return Err(invalid());
+                }
+                let request: ModelListRequest =
+                    serde_json::from_value(params).map_err(|_| invalid())?;
+                if request.protocol.is_empty()
+                    || request.protocol.len() > 64
+                    || request.client_version.len() > 128
+                {
+                    return Err(invalid());
+                }
+                let port = self.slot.upgrade()?;
+                let bound = port
+                    .bind(BoundModelExecutionBinding {
+                        client_key_id: ClientApiKeyId::new(request.client_key_id)
+                            .map_err(|_| invalid())?,
+                        initiating_plugin_instance_id: context.instance_id.clone(),
+                        timeout: call
+                            .deadline
+                            .saturating_duration_since(tokio::time::Instant::now()),
+                        cancellation: call.cancellation.child_token(),
+                        extension_scope: call.scope.extension_scope.clone(),
+                    })
+                    .await
+                    .map_err(gateway_fault)?;
+                let models = port
+                    .models(bound, request.protocol, request.client_version)
+                    .await
+                    .map_err(gateway_fault)?;
+                encode_result(ModelListResult {
+                    models: models
+                        .into_iter()
+                        .map(|model| model.as_str().to_owned())
+                        .collect(),
+                })
+            }
+            "host.model.execute" | "host.model.execute_stream" => {
+                let mut request: ModelExecuteRequest =
+                    serde_json::from_value(params).map_err(|_| invalid())?;
+                if payload.is_empty() || payload.len() > self.maximum_payload {
+                    return Err(invalid());
+                }
+                let port = self.slot.upgrade()?;
+                let stream = method == "host.model.execute_stream";
+                let started = if matches!(
+                    context.stage,
+                    gateway_plugin_sdk::Stage::Management
+                        | gateway_plugin_sdk::Stage::CommandLine
+                        | gateway_plugin_sdk::Stage::Maintenance
+                        | gateway_plugin_sdk::Stage::Authentication
+                        | gateway_plugin_sdk::Stage::Observation
+                ) {
+                    let client_key_id = request.client_key_id.take().ok_or_else(invalid)?;
+                    let bound = self.binding(&port, context, call, client_key_id).await?;
+                    port.start_bound(self.bound_request(request, payload, stream, bound)?)
+                        .await
+                        .map_err(gateway_fault)?
+                } else {
+                    if request.client_key_id.is_some() {
+                        return Err(invalid());
+                    }
+                    let request = self.request(context, request, payload, stream)?;
+                    if let Some(scope) = scope {
+                        scope.observe_nested_execution();
+                    }
+                    port.start(request).await.map_err(gateway_fault)?
+                };
+                if method == "host.model.execute" {
+                    execute_buffered(started, self.maximum_payload).await
+                } else {
+                    let stream = Arc::new(ModelStream::new(started.session, self.maximum_payload));
+                    let id = uuid::Uuid::new_v4().to_string();
+                    let mut state = call
+                        .state
+                        .lock()
+                        .unwrap_or_else(std::sync::PoisonError::into_inner);
+                    if state.closed || state.model_streams.len() >= MAX_MODEL_STREAMS_PER_CALL {
+                        drop(state);
+                        stream.close();
+                        return Err(PluginFault::new(
+                            ErrorCode::Capacity,
+                            "model stream capacity is exhausted",
+                        ));
+                    }
+                    state.model_streams.insert(id.clone(), stream);
+                    encode_result(ModelStreamResult {
+                        request_id: started.request_id.as_str().to_owned(),
+                        stream: id,
+                    })
+                }
+            }
+            "host.model.stream_read" => {
+                if !payload.is_empty() {
+                    return Err(invalid());
+                }
+                let request: ModelStreamReadRequest =
+                    serde_json::from_value(params).map_err(|_| invalid())?;
+                if request.maximum_bytes == 0
+                    || usize::try_from(request.maximum_bytes)
+                        .map_or(true, |maximum| maximum > self.maximum_payload)
+                {
+                    return Err(invalid());
+                }
+                let stream = call
+                    .state
+                    .lock()
+                    .unwrap_or_else(std::sync::PoisonError::into_inner)
+                    .model_streams
+                    .get(&request.stream)
+                    .cloned()
+                    .ok_or_else(denied)?;
+                let read = stream
+                    .read(usize::try_from(request.maximum_bytes).map_err(|_| invalid())?)
+                    .await?;
+                if read.end {
+                    call.state
+                        .lock()
+                        .unwrap_or_else(std::sync::PoisonError::into_inner)
+                        .model_streams
+                        .remove(&request.stream);
+                }
+                Ok(RpcReply {
+                    result: serde_json::to_value(ModelStreamReadResult {
+                        events: read.events,
+                        end: read.end,
+                    })
+                    .map_err(|_| invalid())?,
+                    payload: read.payload,
+                })
+            }
+            "host.model.stream_close" => {
+                if !payload.is_empty() {
+                    return Err(invalid());
+                }
+                let request: ModelStreamCloseRequest =
+                    serde_json::from_value(params).map_err(|_| invalid())?;
+                let stream = call
+                    .state
+                    .lock()
+                    .unwrap_or_else(std::sync::PoisonError::into_inner)
+                    .model_streams
+                    .remove(&request.stream)
+                    .ok_or_else(denied)?;
+                stream.close();
+                Ok(RpcReply {
+                    result: serde_json::json!({}),
+                    payload: Vec::new(),
+                })
+            }
+            _ => Err(denied()),
+        }
+    }
+
+    async fn binding(
+        &self,
+        port: &Arc<dyn NestedModelExecutionPort>,
+        context: &CallContext,
+        call: &CallResources,
+        client_key_id: String,
+    ) -> Result<BoundModelExecutionContext, PluginFault> {
+        let key = ClientApiKeyId::new(client_key_id.clone()).map_err(|_| invalid())?;
+        let mut bindings = call.model_bindings.lock().await;
+        if let Some(bound) = bindings.get(&client_key_id) {
+            return Ok(bound.clone());
+        }
+        if bindings.len() >= MAX_MODEL_STREAMS_PER_CALL {
+            return Err(PluginFault::new(
+                ErrorCode::Capacity,
+                "model identity capacity is exhausted",
+            ));
+        }
+        let bound = port
+            .bind(BoundModelExecutionBinding {
+                client_key_id: key,
+                initiating_plugin_instance_id: context.instance_id.clone(),
+                timeout: call
+                    .deadline
+                    .saturating_duration_since(tokio::time::Instant::now()),
+                cancellation: call.cancellation.child_token(),
+                extension_scope: call.scope.extension_scope.clone(),
+            })
+            .await
+            .map_err(gateway_fault)?;
+        // 调用持有身份直到 RPC 结束，流式执行不会因单次 callback 返回而提前取消；
+        // 同一 Key 复用 Core 调用图，不能通过重复 bind 重置深度与并发限制。
+        bindings.insert(client_key_id, bound.clone());
+        Ok(bound)
+    }
+
+    fn request(
+        &self,
+        context: &CallContext,
+        request: ModelExecuteRequest,
+        body: Vec<u8>,
+        stream: bool,
+    ) -> Result<NestedModelExecutionRequest, PluginFault> {
+        let parent_request_id = context
+            .request_id
+            .as_ref()
+            .ok_or_else(denied)
+            .and_then(|request_id| ModelRequestId::new(request_id.clone()).map_err(|_| denied()))?;
+        let parent_account = context
+            .account_id
+            .as_ref()
+            .map(|account| ProviderAccountId::new(account.clone()))
+            .transpose()
+            .map_err(|_| denied())?;
+        let request = self.request_parts(request, body, stream)?;
+        Ok(NestedModelExecutionRequest {
+            parent_request_id,
+            initiating_plugin_instance_id: context.instance_id.clone(),
+            public_model: request.public_model,
+            operation: request.operation,
+            metadata: request.metadata,
+            provider: request.provider,
+            account: request.account,
+            parent_account,
+        })
+    }
+
+    fn bound_request(
+        &self,
+        request: ModelExecuteRequest,
+        body: Vec<u8>,
+        stream: bool,
+        context: BoundModelExecutionContext,
+    ) -> Result<BoundModelExecutionRequest, PluginFault> {
+        let request = self.request_parts(request, body, stream)?;
+        Ok(BoundModelExecutionRequest {
+            context,
+            public_model: request.public_model,
+            operation: request.operation,
+            metadata: request.metadata,
+            provider: request.provider,
+            account: request.account,
+        })
+    }
+
+    fn request_parts(
+        &self,
+        request: ModelExecuteRequest,
+        body: Vec<u8>,
+        stream: bool,
+    ) -> Result<ModelRequestParts, PluginFault> {
+        if !self.authorized {
+            return Err(denied());
+        }
+        let provider = request
+            .provider
+            .map(ProviderKind::new)
+            .transpose()
+            .map_err(|_| invalid())?;
+        let account = request
+            .account_id
+            .map(ProviderAccountId::new)
+            .transpose()
+            .map_err(|_| invalid())?;
+        let previous_response_id = request
+            .previous_response_id
+            .map(gateway_core::engine::continuation::PreviousResponseId::new);
+        let operation = decode_operation(
+            request.operation,
+            request.protocol.clone(),
+            body,
+            previous_response_id.as_ref().map(|id| id.as_str()),
+        )?;
+        Ok(ModelRequestParts {
+            public_model: PublicModelId::new(request.model).map_err(|_| invalid())?,
+            operation,
+            metadata: ExecutionRequestMetadata {
+                protocol: request.protocol,
+                endpoint: "host.model".to_owned(),
+                transport: ClientTransport::InternalPlugin,
+                stream,
+                client_ip: None,
+                user_agent: None,
+                previous_response_id,
+            },
+            provider,
+            account,
+        })
+    }
+}
+
+struct ModelRequestParts {
+    public_model: PublicModelId,
+    operation: Operation,
+    metadata: ExecutionRequestMetadata,
+    provider: Option<ProviderKind>,
+    account: Option<ProviderAccountId>,
+}
+
+fn decode_operation(
+    operation: ModelOperation,
+    protocol: String,
+    body: Vec<u8>,
+    previous_response_id: Option<&str>,
+) -> Result<Operation, PluginFault> {
+    if serde_json::from_slice::<serde_json::Value>(&body).is_err() {
+        return Err(invalid());
+    }
+    match operation {
+        ModelOperation::Generate => {
+            let mut body =
+                serde_json::from_slice::<serde_json::Map<String, serde_json::Value>>(&body)
+                    .map_err(|_| invalid())?;
+            if let Some(previous) = previous_response_id {
+                match body.get("previous_response_id") {
+                    Some(value) if value.as_str() != Some(previous) => return Err(invalid()),
+                    Some(_) => {}
+                    None => {
+                        body.insert(
+                            "previous_response_id".to_owned(),
+                            serde_json::Value::String(previous.to_owned()),
+                        );
+                    }
+                }
+            }
+            Ok(Operation::Generate(GenerateRequest::from_protocol_payload(
+                ProtocolPayload::json_object(protocol, body).map_err(|_| invalid())?,
+            )))
+        }
+        ModelOperation::GenerateImage | ModelOperation::EditImage => {
+            let kind = if operation == ModelOperation::GenerateImage {
+                ImageRequestKind::Generation
+            } else {
+                ImageRequestKind::Edit
+            };
+            Ok(Operation::GenerateImage(ImageRequest::from_raw_json(
+                kind,
+                RawJsonPayload::new(protocol, Bytes::from(body)).map_err(|_| invalid())?,
+            )))
+        }
+        ModelOperation::Search => Ok(Operation::Search(StandaloneSearchRequest::from_raw_json(
+            RawJsonPayload::new(protocol, Bytes::from(body)).map_err(|_| invalid())?,
+        ))),
+    }
+}
+
+async fn execute_buffered(
+    mut started: gateway_core::engine::execution::StartedExecution,
+    maximum_payload: usize,
+) -> Result<RpcReply, PluginFault> {
+    let events = match started.session.collect_uncommitted().await {
+        Ok(events) => events,
+        Err(error) => {
+            let fault = gateway_fault(gateway_core::engine::execution::gateway_error_from_engine(
+                &error,
+            ));
+            started.session.detach_finalize().await;
+            return Err(fault);
+        }
+    };
+    let (payload, events) = match encode_events(events) {
+        Ok(encoded) => encoded,
+        Err(error) => {
+            started.session.detach_finalize().await;
+            return Err(error);
+        }
+    };
+    if payload.len() > maximum_payload {
+        started.session.detach_finalize().await;
+        return Err(PluginFault::new(
+            ErrorCode::Capacity,
+            "model response requires streaming",
+        ));
+    }
+    if let Err(error) = started.session.commit_downstream(Some(200)).await {
+        let fault = gateway_fault(gateway_core::engine::execution::gateway_error_from_engine(
+            &error,
+        ));
+        started.session.detach_finalize().await;
+        return Err(fault);
+    }
+    if !started.session.is_finalized() {
+        started.session.detach_finalize().await;
+        return Err(PluginFault::new(
+            ErrorCode::Fault,
+            "model execution did not finalize",
+        ));
+    }
+    Ok(RpcReply {
+        result: serde_json::to_value(ModelExecuteResult {
+            request_id: started.request_id.as_str().to_owned(),
+            events,
+        })
+        .map_err(|_| invalid())?,
+        payload,
+    })
+}
+
+struct PendingBatch {
+    payload: Vec<u8>,
+    events: u32,
+    commit: bool,
+}
+
+struct ModelStreamState {
+    session: Option<Box<dyn ExecutionSession>>,
+    pending: Option<PendingBatch>,
+}
+
+pub(super) struct ModelStream {
+    state: tokio::sync::Mutex<ModelStreamState>,
+    closed: tokio::sync::watch::Sender<bool>,
+    maximum_payload: usize,
+}
+
+struct ModelRead {
+    payload: Vec<u8>,
+    events: u32,
+    end: bool,
+}
+
+impl ModelStream {
+    fn new(session: Box<dyn ExecutionSession>, maximum_payload: usize) -> Self {
+        Self {
+            state: tokio::sync::Mutex::new(ModelStreamState {
+                session: Some(session),
+                pending: None,
+            }),
+            closed: tokio::sync::watch::channel(false).0,
+            maximum_payload,
+        }
+    }
+
+    async fn read(&self, maximum_bytes: usize) -> Result<ModelRead, PluginFault> {
+        let mut state = self.state.try_lock().map_err(|_| {
+            PluginFault::new(ErrorCode::Capacity, "model stream already has a reader")
+        })?;
+        loop {
+            let is_closed = *self.closed.borrow();
+            if is_closed {
+                let session = state.session.take();
+                state.pending.take();
+                drop(state);
+                if let Some(session) = session {
+                    session.cancel();
+                    session.detach_finalize().await;
+                }
+                return Err(PluginFault::new(
+                    ErrorCode::Cancelled,
+                    "model stream was closed",
+                ));
+            }
+            if let Some(pending) = state.pending.take() {
+                if pending.payload.len() > maximum_bytes {
+                    state.pending = Some(pending);
+                    return Err(PluginFault::new(
+                        ErrorCode::Capacity,
+                        "model event exceeds the requested read size",
+                    ));
+                }
+                if pending.commit {
+                    let result = state
+                        .session
+                        .as_mut()
+                        .ok_or_else(denied)?
+                        .commit_downstream(Some(200))
+                        .await;
+                    if let Err(error) = result {
+                        let fault = gateway_fault(
+                            gateway_core::engine::execution::gateway_error_from_engine(&error),
+                        );
+                        let session = state.session.take();
+                        drop(state);
+                        if let Some(session) = session {
+                            session.cancel();
+                            session.detach_finalize().await;
+                        }
+                        return Err(fault);
+                    }
+                }
+                return Ok(ModelRead {
+                    payload: pending.payload,
+                    events: pending.events,
+                    end: false,
+                });
+            }
+            let mut closed = self.closed.subscribe();
+            let next = {
+                let session = state.session.as_mut().ok_or_else(denied)?;
+                tokio::select! {
+                    biased;
+                    _ = closed.wait_for(|closed| *closed) => {
+                        session.cancel();
+                        None
+                    }
+                    result = session.next_event() => Some(result),
+                }
+            };
+            let Some(next) = next else {
+                let session = state.session.take();
+                drop(state);
+                if let Some(session) = session {
+                    session.cancel();
+                    session.detach_finalize().await;
+                }
+                return Err(PluginFault::new(
+                    ErrorCode::Cancelled,
+                    "model stream was closed",
+                ));
+            };
+            match next {
+                Ok(Some(event)) => {
+                    let commit =
+                        event.commit_requirement() == CommitRequirement::CommitBeforeDelivery;
+                    let (payload, events) = match encode_events(event.into_provider_events()) {
+                        Ok(encoded) => encoded,
+                        Err(error) => {
+                            let session = state.session.take();
+                            drop(state);
+                            if let Some(session) = session {
+                                session.cancel();
+                                session.detach_finalize().await;
+                            }
+                            return Err(error);
+                        }
+                    };
+                    if events == 0 {
+                        // 首次未提交批次即使只含 Core 内部事实，也必须释放交付屏障；
+                        // 已提交批次没有待交付状态，过滤后可直接继续读取下一帧。
+                        if commit {
+                            let result = state
+                                .session
+                                .as_mut()
+                                .ok_or_else(denied)?
+                                .discard_pending_delivery();
+                            if result.is_err() {
+                                let session = state.session.take();
+                                drop(state);
+                                if let Some(session) = session {
+                                    session.cancel();
+                                    session.detach_finalize().await;
+                                }
+                                return Err(PluginFault::new(
+                                    ErrorCode::Fault,
+                                    "model event cannot be discarded",
+                                ));
+                            }
+                        }
+                        continue;
+                    }
+                    if payload.len() > self.maximum_payload {
+                        let session = state.session.take();
+                        drop(state);
+                        if let Some(session) = session {
+                            session.cancel();
+                            session.detach_finalize().await;
+                        }
+                        return Err(PluginFault::new(
+                            ErrorCode::Capacity,
+                            "model event exceeds the stream payload limit",
+                        ));
+                    }
+                    state.pending = Some(PendingBatch {
+                        payload,
+                        events,
+                        commit,
+                    });
+                }
+                Ok(None) => {
+                    let finalized = state
+                        .session
+                        .as_ref()
+                        .is_some_and(|session| session.is_finalized());
+                    let session = state.session.take();
+                    drop(state);
+                    if !finalized {
+                        if let Some(session) = session {
+                            session.cancel();
+                            session.detach_finalize().await;
+                        }
+                        return Err(PluginFault::new(
+                            ErrorCode::Fault,
+                            "model stream ended before finalization",
+                        ));
+                    }
+                    return Ok(ModelRead {
+                        payload: Vec::new(),
+                        events: 0,
+                        end: true,
+                    });
+                }
+                Err(error) => {
+                    let fault = gateway_fault(
+                        gateway_core::engine::execution::gateway_error_from_engine(&error),
+                    );
+                    let session = state.session.take();
+                    drop(state);
+                    if let Some(session) = session {
+                        session.cancel();
+                        session.detach_finalize().await;
+                    }
+                    return Err(fault);
+                }
+            }
+        }
+    }
+
+    pub(super) fn close(self: &Arc<Self>) {
+        self.closed.send_replace(true);
+        let stream = Arc::clone(self);
+        if let Ok(handle) = tokio::runtime::Handle::try_current() {
+            drop(handle.spawn(async move {
+                let session = stream.state.lock().await.session.take();
+                if let Some(session) = session {
+                    session.cancel();
+                    session.detach_finalize().await;
+                }
+            }));
+        }
+    }
+}
+
+fn encode_events(events: Vec<ProviderEvent>) -> Result<(Vec<u8>, u32), PluginFault> {
+    let events = events
+        .into_iter()
+        .filter_map(|event| project_event(event).transpose())
+        .collect::<Result<Vec<_>, _>>()?;
+    let count = u32::try_from(events.len()).map_err(|_| invalid())?;
+    if events.is_empty() {
+        return Ok((Vec::new(), 0));
+    }
+    let payload = ModelEventBatch { events }
+        .encode()
+        .map_err(|_| PluginFault::new(ErrorCode::Capacity, "model event batch is too large"))?;
+    Ok((payload, count))
+}
+
+fn project_event(event: ProviderEvent) -> Result<Option<ExecutionEvent>, PluginFault> {
+    let (facts, wire) = event.into_parts();
+    let facts = facts
+        .into_iter()
+        .filter_map(project_fact)
+        .collect::<Result<Vec<_>, _>>()?;
+    let wire = wire.map(project_wire).transpose()?;
+    if facts.is_empty() && wire.is_none() {
+        return Ok(None);
+    }
+    Ok(Some(ExecutionEvent {
+        facts,
+        wire,
+        observation: None,
+        session_update: None,
+        failure: None,
+    }))
+}
+
+fn project_fact(event: GatewayEvent) -> Option<Result<CanonicalEvent, PluginFault>> {
+    Some(Ok(match event {
+        GatewayEvent::Started(meta) => CanonicalEvent::Started {
+            id: meta.response_id().to_owned(),
+            model: meta.model().map(str::to_owned),
+        },
+        GatewayEvent::ContentAdded(item) => CanonicalEvent::ContentAdded {
+            index: item.index(),
+            kind: match item.kind() {
+                ContentKind::Text => WireContentKind::Text,
+                ContentKind::Reasoning => WireContentKind::Reasoning,
+                ContentKind::ToolCall => WireContentKind::ToolCall,
+                ContentKind::Image => WireContentKind::Image,
+                ContentKind::Audio => WireContentKind::Audio,
+                _ => {
+                    return Some(Err(PluginFault::new(
+                        ErrorCode::Unsupported,
+                        "unknown content kind",
+                    )));
+                }
+            },
+        },
+        GatewayEvent::TextDelta(delta) => CanonicalEvent::TextDelta {
+            index: delta.content_index,
+            text: delta.text,
+        },
+        GatewayEvent::ReasoningDelta(delta) => CanonicalEvent::ReasoningDelta {
+            index: delta.content_index,
+            text: delta.text,
+        },
+        GatewayEvent::ToolCallDelta(delta) => CanonicalEvent::ToolCallDelta {
+            index: delta.content_index,
+            id: delta.call_id,
+            name: delta.name,
+            arguments: delta.arguments_delta,
+        },
+        GatewayEvent::Usage(usage) => CanonicalEvent::Usage {
+            usage: WireUsage {
+                input_tokens: usage.input_tokens,
+                output_tokens: usage.output_tokens,
+                cached_tokens: usage.cached_tokens,
+                cache_write_tokens: usage.cache_write_tokens,
+                reasoning_tokens: usage.reasoning_tokens,
+                image_input_tokens: usage.image_input_tokens,
+                image_output_tokens: usage.image_output_tokens,
+                total_tokens: usage.total_tokens,
+            },
+        },
+        // 费用已经由子请求的 Core 结算；不把它重新作为父插件可上报的用量输入。
+        GatewayEvent::CalculatedCost(_) | GatewayEvent::ProviderCost(_) => return None,
+        GatewayEvent::Completed(meta) => CanonicalEvent::Completed {
+            id: meta.response_id().to_owned(),
+            model: meta.model().map(str::to_owned),
+            reason: match meta.finish_reason().unwrap_or(FinishReason::Other) {
+                FinishReason::Stop => WireFinishReason::Stop,
+                FinishReason::Length => WireFinishReason::Length,
+                FinishReason::ToolCall => WireFinishReason::ToolCall,
+                FinishReason::ContentFilter => WireFinishReason::ContentFilter,
+                FinishReason::Other => WireFinishReason::Other,
+                _ => WireFinishReason::Other,
+            },
+        },
+        _ => {
+            return Some(Err(PluginFault::new(
+                ErrorCode::Unsupported,
+                "unknown model event",
+            )));
+        }
+    }))
+}
+
+fn project_wire(wire: ProtocolWireEvent) -> Result<WireEvent, PluginFault> {
+    let protocol = wire.protocol().to_owned();
+    let payload = if let Some(body) = wire.raw_http_body_bytes() {
+        WirePayload::RawBody {
+            body: body.to_vec(),
+        }
+    } else if let Some(body) = wire.raw_json_body() {
+        WirePayload::RawJson {
+            body: body.to_vec(),
+        }
+    } else if wire.has_json_data() {
+        WirePayload::Json {
+            event: wire.event_type().map(str::to_owned),
+            data: wire.data().clone(),
+            id: wire.sse_id().map(str::to_owned),
+            retry: wire.sse_retry(),
+            raw_sse: wire.raw_sse_frame().map(|frame| frame.to_vec()),
+        }
+    } else if let Some(frame) = wire.raw_sse_frame() {
+        WirePayload::RawSse {
+            frame: frame.to_vec(),
+        }
+    } else {
+        return Err(PluginFault::new(
+            ErrorCode::Fault,
+            "model wire event has no payload",
+        ));
+    };
+    Ok(WireEvent { protocol, payload })
+}
+
+pub(super) fn gateway_fault(error: GatewayError) -> PluginFault {
+    let code = match error.kind() {
+        GatewayErrorKind::InvalidRequest => ErrorCode::InvalidInput,
+        GatewayErrorKind::Unsupported | GatewayErrorKind::ModelNotFound => ErrorCode::Unsupported,
+        GatewayErrorKind::Unauthorized => ErrorCode::PermissionDenied,
+        GatewayErrorKind::PolicyDenied => ErrorCode::Rejected,
+        GatewayErrorKind::AccountCapacityUnavailable
+        | GatewayErrorKind::ConcurrencyQueueFull
+        | GatewayErrorKind::ConcurrencyQueueTimeout
+        | GatewayErrorKind::RateLimited
+        | GatewayErrorKind::NoAvailableProvider => ErrorCode::Capacity,
+        GatewayErrorKind::Timeout => ErrorCode::Timeout,
+        GatewayErrorKind::Cancelled => ErrorCode::Cancelled,
+        GatewayErrorKind::UpstreamUnavailable
+        | GatewayErrorKind::ProviderInfrastructureUnavailable => ErrorCode::Upstream,
+        GatewayErrorKind::Internal => ErrorCode::Fault,
+        _ => ErrorCode::Fault,
+    };
+    PluginFault::new(code, "nested model execution failed")
+}
+
+fn encode_result(value: impl serde::Serialize) -> Result<RpcReply, PluginFault> {
+    Ok(RpcReply {
+        result: serde_json::to_value(value).map_err(|_| invalid())?,
+        payload: Vec::new(),
+    })
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/callback/private_state.rs b/backend/crates/gateway-plugin/runtime/src/callback/private_state.rs
new file mode 100644
index 000000000..a1c498981
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/callback/private_state.rs
@@ -0,0 +1,244 @@
+use std::{
+    collections::BTreeMap,
+    sync::{Arc, RwLock},
+};
+
+use gateway_admin::{
+    model::{
+        AdminError,
+        plugins::{
+            instances::PluginInstance,
+            state::{
+                DeletePluginState, PluginStateConfiguration, PluginStateOwner,
+                PluginStateOwnerRequest, PluginStateSchema, PutPluginState,
+            },
+        },
+    },
+    ports::plugins::{PluginStateStore, PluginStateStoreError, PluginStateStoreErrorKind},
+};
+use gateway_plugin_sdk::{
+    ErrorCode, Manifest, PluginFault,
+    call::host::{
+        StateDeleteRequest, StateDeleteResult, StateGetRequest, StateGetResult, StatePutRequest,
+        StatePutResult, StateRecord,
+    },
+};
+use sha2::{Digest as _, Sha256};
+
+use crate::RpcReply;
+
+pub(crate) struct PluginPrivateState {
+    store: Arc<dyn PluginStateStore>,
+    configuration: PluginStateConfiguration,
+    validators: BTreeMap<String, jsonschema::Validator>,
+    owner: RwLock<Option<PluginStateOwner>>,
+}
+
+impl PluginPrivateState {
+    pub(crate) fn new(
+        store: Arc<dyn PluginStateStore>,
+        manifest: &Manifest,
+        configuration: PluginStateConfiguration,
+        owner: Option<PluginStateOwner>,
+    ) -> Result<Self, AdminError> {
+        let validators = validators(manifest)?;
+        Ok(Self {
+            store,
+            configuration,
+            validators,
+            owner: RwLock::new(owner),
+        })
+    }
+
+    pub(crate) fn owner_request(&self, instance: &PluginInstance) -> PluginStateOwnerRequest {
+        PluginStateOwnerRequest {
+            instance_id: instance.id.clone(),
+            artifact_sha256: instance.artifact_sha256.clone(),
+            instance_revision: instance.revision,
+            configuration: self.configuration.clone(),
+        }
+    }
+
+    pub(crate) fn activate(&self, owner: PluginStateOwner) {
+        *self
+            .owner
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner) = Some(owner);
+    }
+
+    pub(crate) fn validate_value(
+        &self,
+        namespace: &str,
+        value: &serde_json::Value,
+    ) -> Result<(), AdminError> {
+        let validator = self
+            .validators
+            .get(namespace)
+            .ok_or_else(|| AdminError::invalid("插件状态迁移使用了未声明的命名空间"))?;
+        if !validator.is_valid(value) {
+            return Err(AdminError::invalid("插件状态迁移结果不符合目标 schema"));
+        }
+        Ok(())
+    }
+
+    pub(crate) async fn call(
+        &self,
+        method: &str,
+        params: serde_json::Value,
+        payload: &[u8],
+    ) -> Result<RpcReply, PluginFault> {
+        if !payload.is_empty() {
+            return Err(invalid_fault());
+        }
+        let owner = self
+            .owner
+            .read()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .clone()
+            .ok_or_else(denied_fault)?;
+        let result = match method {
+            "host.state.get" => {
+                let request: StateGetRequest =
+                    serde_json::from_value(params).map_err(|_| invalid_fault())?;
+                self.authorize(&request.namespace)?;
+                let record = self
+                    .store
+                    .get(&owner, &request.namespace, &request.key)
+                    .await
+                    .map_err(map_store_fault)?
+                    .map(|record| StateRecord {
+                        value: record.value,
+                        version: record.version,
+                        schema_version: record.schema_version,
+                    });
+                serde_json::to_value(StateGetResult { record }).map_err(|_| internal_fault())?
+            }
+            "host.state.put" => {
+                let request: StatePutRequest =
+                    serde_json::from_value(params).map_err(|_| invalid_fault())?;
+                self.authorize(&request.namespace)?;
+                self.validators
+                    .get(&request.namespace)
+                    .filter(|validator| validator.is_valid(&request.value))
+                    .ok_or_else(invalid_fault)?;
+                let write = self
+                    .store
+                    .put(
+                        &owner,
+                        PutPluginState {
+                            namespace: request.namespace,
+                            key: request.key,
+                            value: request.value,
+                            expected_version: request.expected_version,
+                        },
+                    )
+                    .await
+                    .map_err(map_store_fault)?;
+                serde_json::to_value(StatePutResult {
+                    version: write.version,
+                })
+                .map_err(|_| internal_fault())?
+            }
+            "host.state.delete" => {
+                let request: StateDeleteRequest =
+                    serde_json::from_value(params).map_err(|_| invalid_fault())?;
+                self.authorize(&request.namespace)?;
+                let deleted = self
+                    .store
+                    .delete(
+                        &owner,
+                        DeletePluginState {
+                            namespace: request.namespace,
+                            key: request.key,
+                            expected_version: request.expected_version,
+                        },
+                    )
+                    .await
+                    .map_err(map_store_fault)?;
+                serde_json::to_value(StateDeleteResult { deleted }).map_err(|_| internal_fault())?
+            }
+            _ => return Err(denied_fault()),
+        };
+        Ok(RpcReply {
+            result,
+            payload: Vec::new(),
+        })
+    }
+
+    fn authorize(&self, namespace: &str) -> Result<(), PluginFault> {
+        if !self.validators.contains_key(namespace) {
+            return Err(denied_fault());
+        }
+        Ok(())
+    }
+}
+
+pub(crate) fn configuration(manifest: &Manifest) -> Result<PluginStateConfiguration, AdminError> {
+    let _ = validators(manifest)?;
+    let mut namespaces = Vec::with_capacity(manifest.state.len());
+    for state in &manifest.state {
+        let mut schema = state.schema.clone();
+        schema.sort_all_objects();
+        let encoded = serde_json::to_vec(&schema)
+            .map_err(|_| AdminError::invalid("插件状态 schema 无法编码"))?;
+        namespaces.push(PluginStateSchema {
+            namespace: state.namespace.clone(),
+            schema_version: state.schema_version,
+            schema_sha256: hex::encode(Sha256::digest(encoded)),
+            schema: state.schema.clone(),
+            maximum_records: state.maximum_records,
+            maximum_bytes: state.maximum_bytes,
+            maximum_value_bytes: state.maximum_value_bytes,
+            migrates_from: state.migrates_from.clone(),
+        });
+    }
+    namespaces.sort_by(|left, right| left.namespace.cmp(&right.namespace));
+    Ok(PluginStateConfiguration { namespaces })
+}
+
+fn validators(manifest: &Manifest) -> Result<BTreeMap<String, jsonschema::Validator>, AdminError> {
+    manifest
+        .state
+        .iter()
+        .map(|state| {
+            let validator = jsonschema::options()
+                .offline()
+                .with_pattern_options(
+                    jsonschema::PatternOptions::fancy_regex().backtrack_limit(20_000),
+                )
+                .build(&state.schema)
+                .map_err(|_| AdminError::invalid("插件状态 schema 无效或引用了外部资源"))?;
+            Ok((state.namespace.clone(), validator))
+        })
+        .collect()
+}
+
+fn map_store_fault(error: PluginStateStoreError) -> PluginFault {
+    let (code, message) = match error.kind() {
+        PluginStateStoreErrorKind::Invalid => (ErrorCode::InvalidInput, "state input is invalid"),
+        PluginStateStoreErrorKind::Conflict => (ErrorCode::Conflict, "state version conflicts"),
+        PluginStateStoreErrorKind::Quota => (ErrorCode::Capacity, "state quota is exhausted"),
+        PluginStateStoreErrorKind::NotFound | PluginStateStoreErrorKind::PermissionDenied => {
+            (ErrorCode::PermissionDenied, "state owner is not authorized")
+        }
+        PluginStateStoreErrorKind::Unavailable => {
+            (ErrorCode::Upstream, "state store is unavailable")
+        }
+    };
+    PluginFault::new(code, message)
+}
+
+fn denied_fault() -> PluginFault {
+    PluginFault::new(
+        ErrorCode::PermissionDenied,
+        "state namespace is not authorized",
+    )
+}
+
+fn invalid_fault() -> PluginFault {
+    PluginFault::new(ErrorCode::InvalidInput, "state input is invalid")
+}
+
+fn internal_fault() -> PluginFault {
+    PluginFault::new(ErrorCode::Fault, "state response could not be encoded")
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/callback/scope.rs b/backend/crates/gateway-plugin/runtime/src/callback/scope.rs
new file mode 100644
index 000000000..9164b0c9e
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/callback/scope.rs
@@ -0,0 +1,157 @@
+use std::sync::{Arc, Mutex};
+
+use gateway_core::{
+    account::OutboundProxy, engine::nested::ExecutionEffects, upstream::UpstreamSendState,
+};
+use gateway_plugin_sdk::{CallContext, Stage};
+
+/// 一次执行或管理操作的网络事实独立于插件错误，由操作本身保活。
+pub(crate) struct NetworkScope {
+    stage: Stage,
+    account_id: Option<String>,
+    credential_revision: Option<u64>,
+    pub(super) proxy: Option<OutboundProxy>,
+    pub(super) extension_scope: gateway_core::engine::extensions::ExtensionCallScope,
+    execution_effects: Option<Arc<ExecutionEffects>>,
+    state: Mutex<ExecutionState>,
+}
+
+struct ExecutionState {
+    active: bool,
+    pending: usize,
+    sent: bool,
+    ambiguous: bool,
+}
+
+impl NetworkScope {
+    pub(super) fn new(context: &CallContext, proxy: Option<OutboundProxy>) -> Self {
+        Self {
+            stage: if context.stage == Stage::Attempt {
+                Stage::Execution
+            } else {
+                context.stage
+            },
+            account_id: context.account_id.clone(),
+            credential_revision: context.credential_revision,
+            proxy,
+            extension_scope: Default::default(),
+            execution_effects: None,
+            state: Mutex::new(ExecutionState {
+                active: context.stage != Stage::Attempt,
+                pending: 0,
+                sent: false,
+                ambiguous: false,
+            }),
+        }
+    }
+
+    pub(super) fn for_call(context: &CallContext) -> Self {
+        let mut scope = Self::new(context, None);
+        scope.stage = context.stage;
+        scope.activate();
+        scope
+    }
+
+    pub(crate) fn activate(&self) {
+        self.state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .active = true;
+    }
+
+    pub(super) fn with_execution_effects(mut self, effects: Arc<ExecutionEffects>) -> Self {
+        self.execution_effects = Some(effects);
+        self
+    }
+
+    pub(super) fn account_id(&self) -> Option<&str> {
+        self.account_id.as_deref()
+    }
+
+    pub(super) const fn credential_revision(&self) -> Option<u64> {
+        self.credential_revision
+    }
+
+    pub(super) fn authorizes(&self, context: &CallContext) -> bool {
+        context.stage == self.stage
+            && context.account_id == self.account_id
+            && context.credential_revision == self.credential_revision
+            && self
+                .state
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner)
+                .active
+    }
+
+    pub(super) fn start_http(self: &Arc<Self>) -> HttpAttempt {
+        self.state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .pending += 1;
+        HttpAttempt {
+            scope: self.clone(),
+            completed: false,
+        }
+    }
+
+    pub(super) fn observe_nested_execution(&self) {
+        // Core 启动子请求时也可能经路由继续嵌套；父侧无法证明完全未发送。
+        // 只收紧父 attempt 的重放判断，子请求的费用仍由它自己的 Core 会话结算。
+        self.state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .ambiguous = true;
+    }
+
+    pub(crate) fn send_state(&self) -> UpstreamSendState {
+        let state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if state.sent {
+            UpstreamSendState::Sent
+        } else if state.ambiguous || state.pending != 0 {
+            UpstreamSendState::Ambiguous
+        } else {
+            UpstreamSendState::NotSent
+        }
+    }
+}
+
+pub(super) struct HttpAttempt {
+    scope: Arc<NetworkScope>,
+    completed: bool,
+}
+
+impl HttpAttempt {
+    pub(super) fn finish(mut self, observed: UpstreamSendState) {
+        self.record(observed);
+        self.completed = true;
+    }
+
+    fn record(&self, observed: UpstreamSendState) {
+        let mut state = self
+            .scope
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        state.pending -= 1;
+        state.sent |= observed == UpstreamSendState::Sent;
+        state.ambiguous |= observed == UpstreamSendState::Ambiguous;
+        drop(state);
+        if observed != UpstreamSendState::NotSent
+            && let Some(effects) = &self.scope.execution_effects
+        {
+            effects.observe();
+        }
+    }
+}
+
+impl Drop for HttpAttempt {
+    fn drop(&mut self) {
+        // send future 被取消时无法证明上游未接收，不能把请求回退成可重试。
+        if !self.completed {
+            self.record(UpstreamSendState::Ambiguous);
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/contribution.rs b/backend/crates/gateway-plugin/runtime/src/contribution.rs
new file mode 100644
index 000000000..ca2036096
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/contribution.rs
@@ -0,0 +1,23 @@
+use gateway_admin::model::{AdminError, plugins::instances::PluginCapabilityBinding};
+use gateway_plugin_sdk::{Capability, ContributionDeclaration, Manifest};
+
+pub(super) struct ResolvedContribution<'a> {
+    pub(super) capability: Capability,
+    pub(super) declaration: &'a ContributionDeclaration,
+}
+
+/// 绑定只保存贡献项 ID；实际能力始终来自已检查清单的 map key。
+pub(super) fn resolve<'a>(
+    manifest: &'a Manifest,
+    binding: &PluginCapabilityBinding,
+) -> Result<ResolvedContribution<'a>, AdminError> {
+    manifest
+        .contributes
+        .iter()
+        .find(|(_, declaration)| declaration.id == binding.contribution)
+        .map(|(capability, declaration)| ResolvedContribution {
+            capability: *capability,
+            declaration,
+        })
+        .ok_or_else(|| AdminError::invalid("插件绑定引用了未声明的贡献项"))
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/generation/configuration.rs b/backend/crates/gateway-plugin/runtime/src/generation/configuration.rs
new file mode 100644
index 000000000..a8da3d8c9
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/generation/configuration.rs
@@ -0,0 +1,156 @@
+use std::collections::BTreeSet;
+
+use gateway_admin::model::{
+    AdminError,
+    plugins::{
+        instances::{PluginFailurePolicy, PluginInstance},
+        state::PluginStateConfiguration,
+    },
+};
+use gateway_plugin_sdk::{Capability, Manifest, Permission, Stage};
+use secrecy::ExposeSecret as _;
+
+pub(super) fn validate(
+    instance: &PluginInstance,
+    manifest: &Manifest,
+) -> Result<(serde_json::Value, Vec<Permission>, PluginStateConfiguration), AdminError> {
+    if instance.enabled && !instance.trusted_process {
+        return Err(AdminError::invalid("插件制品尚未接受安装"));
+    }
+    let (configuration, ready) = prepare_configuration(
+        instance,
+        &manifest.configuration_schema,
+        &manifest.secret_fields,
+    )?;
+    if instance.enabled && !ready {
+        return Err(AdminError::invalid("请填写插件必填配置"));
+    }
+    let mut permissions = BTreeSet::new();
+    for grant in &instance.grants {
+        let permission: Permission =
+            serde_json::from_value(serde_json::Value::String(grant.permission.clone()))
+                .map_err(|_| AdminError::invalid("插件权限标识不合法"))?;
+        if !manifest.permissions.contains(&permission) || !permissions.insert(permission) {
+            return Err(AdminError::invalid("插件权限未声明或重复"));
+        }
+    }
+    let mut bindings = BTreeSet::new();
+    for binding in &instance.bindings {
+        let resolved = crate::contribution::resolve(manifest, binding)?;
+        let capability = resolved.capability;
+        if matches!(capability, Capability::Management | Capability::CommandLine) {
+            return Err(AdminError::invalid("管理页面与命令行无需功能绑定"));
+        }
+        let stage: Stage = serde_json::from_value(serde_json::Value::String(binding.stage.clone()))
+            .map_err(|_| AdminError::invalid("插件调用阶段不合法"))?;
+        if !bindings.insert((capability, stage)) || !resolved.declaration.stages.contains(&stage) {
+            return Err(AdminError::invalid("插件能力或阶段未声明，或者重复绑定"));
+        }
+        let frontend_authentication = capability == Capability::FrontendAuthentication;
+        if frontend_authentication
+            && (stage != Stage::Authentication
+                || !matches!(
+                    binding.failure_policy,
+                    PluginFailurePolicy::Reject | PluginFailurePolicy::Delegate
+                )
+                || binding.identity_bindings.is_empty()
+                || !binding.client_key_ids.is_empty()
+                || !binding.account_group_ids.is_empty()
+                || !binding.provider_ids.is_empty()
+                || !binding.models.is_empty())
+        {
+            return Err(AdminError::invalid(
+                "客户端认证绑定必须配置认证阶段、回退策略和身份映射",
+            ));
+        }
+        if !frontend_authentication && !binding.identity_bindings.is_empty() {
+            return Err(AdminError::invalid("身份映射只能用于客户端认证绑定"));
+        }
+    }
+    Ok((
+        configuration,
+        permissions.into_iter().collect(),
+        crate::callback::private_state::configuration(manifest)?,
+    ))
+}
+
+pub(super) fn configuration_ready(
+    instance: &PluginInstance,
+    schema: &serde_json::Value,
+    secret_fields: &BTreeSet<String>,
+) -> Result<bool, AdminError> {
+    prepare_configuration(instance, schema, secret_fields).map(|(_, ready)| ready)
+}
+
+fn prepare_configuration(
+    instance: &PluginInstance,
+    schema: &serde_json::Value,
+    secret_fields: &BTreeSet<String>,
+) -> Result<(serde_json::Value, bool), AdminError> {
+    let mut configuration = instance
+        .configuration
+        .as_object()
+        .cloned()
+        .ok_or_else(|| AdminError::invalid("插件配置必须是对象"))?;
+    for (name, value) in &instance.secrets {
+        if !secret_fields.contains(name) || configuration.contains_key(name) {
+            return Err(AdminError::invalid("插件敏感字段必须通过独立 secret 配置"));
+        }
+        configuration.insert(
+            name.clone(),
+            serde_json::Value::String(value.expose_secret().into()),
+        );
+    }
+    if secret_fields
+        .iter()
+        .any(|field| instance.configuration.get(field).is_some())
+    {
+        return Err(AdminError::invalid("普通配置不能包含声明的敏感字段"));
+    }
+    let configuration = serde_json::Value::Object(configuration);
+    // 禁用网络与文件解析，配置 schema 只能引用包内同一 JSON 文档。
+    let schema = jsonschema::options()
+        .offline()
+        .with_pattern_options(jsonschema::PatternOptions::fancy_regex().backtrack_limit(20_000))
+        .build(schema)
+        .map_err(|_| AdminError::invalid("插件配置 schema 无效或引用外部资源"))?;
+    let mut ready = true;
+    for error in schema.iter_errors(&configuration) {
+        // 待配置只代表缺少必填值，不能借停用保存类型错误或非法配置。
+        if matches!(
+            error.kind(),
+            jsonschema::error::ValidationErrorKind::Required { .. }
+        ) {
+            ready = false;
+        } else {
+            return Err(configuration_error(&error));
+        }
+    }
+    Ok((configuration, ready))
+}
+
+fn configuration_error(error: &jsonschema::ValidationError<'_>) -> AdminError {
+    use jsonschema::error::ValidationErrorKind;
+
+    // 校验库的 Display 会包含原值，敏感配置也参与校验，只返回字段路径和静态原因。
+    let mut path = error.instance_path().to_string();
+    let reason = match error.kind() {
+        ValidationErrorKind::AdditionalProperties { unexpected } => {
+            if let Some(name) = unexpected.first() {
+                path.push('/');
+                path.push_str(&name.replace('~', "~0").replace('/', "~1"));
+            }
+            "目标版本不支持此字段"
+        }
+        ValidationErrorKind::Type { .. } => "类型不匹配",
+        ValidationErrorKind::Enum { .. } => "不在允许的选项中",
+        _ => "不符合字段要求",
+    };
+    let path: String = path
+        .chars()
+        .filter(|value| !value.is_control())
+        .take(128)
+        .collect();
+    let field = if path.is_empty() { "根对象" } else { &path };
+    AdminError::invalid(format!("插件配置 {field}：{reason}"))
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/generation/mod.rs b/backend/crates/gateway-plugin/runtime/src/generation/mod.rs
new file mode 100644
index 000000000..a27e7ffbe
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/generation/mod.rs
@@ -0,0 +1,7 @@
+mod configuration;
+mod prepare;
+mod restart_circuit;
+mod worker;
+
+pub use prepare::{ContinuationDrainConfig, PluginRuntime, PluginRuntimeConfig};
+pub use restart_circuit::PluginRestartCircuitConfig;
diff --git a/backend/crates/gateway-plugin/runtime/src/generation/prepare/instance.rs b/backend/crates/gateway-plugin/runtime/src/generation/prepare/instance.rs
new file mode 100644
index 000000000..779907621
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/generation/prepare/instance.rs
@@ -0,0 +1,328 @@
+use super::{
+    AdminError, Arc, Capability, ConfigRevision, Duration, Handshake, PluginCallbackPorts,
+    PluginCallbacks, PluginInstance, PluginPrivateState, PluginRuntime, PluginStateStoreErrorKind,
+    PreparedContributions, PreparedInstance, Provider, ProviderAdmin, ProviderKind, Registration,
+    RestartIdentity, Revision, RpcSession, Stage, ValidatedPackage,
+    continuation_authorization_fingerprint, instance_fingerprint,
+};
+
+impl PluginRuntime {
+    pub(super) async fn prepare_instance(
+        &self,
+        instance: PluginInstance,
+        config_revision: ConfigRevision,
+        target_revision: Revision,
+    ) -> Result<PreparedContributions, AdminError> {
+        let mut sessions = Vec::new();
+        let mut providers: Vec<Arc<dyn Provider>> = Vec::new();
+        let mut request_profile_providers = Vec::new();
+        let mut admin_providers: Vec<Arc<dyn ProviderAdmin>> = Vec::new();
+        let mut observer_entries = Vec::new();
+        let mut commands = Vec::new();
+        let mut management = Vec::new();
+        let mut maintenance = Vec::new();
+        let mut policy_entries = Vec::new();
+        let mut authentication_entries = Vec::new();
+        let authorization_binding = instance_fingerprint(&instance)?;
+        if self.restart_circuit_is_open(&RestartIdentity::new(
+            instance.id.clone(),
+            authorization_binding.clone(),
+        )) {
+            return Err(AdminError::unavailable(
+                "插件实例连续异常退出，已暂停自动重启；请检查配置后重新启用",
+            ));
+        }
+        let artifact = self
+            .store
+            .load_artifact(&instance.artifact_sha256)
+            .await
+            .map_err(|_| AdminError::unavailable("插件制品不可用"))?;
+        let limits = self.config.package_limits;
+        let directory = self.config.cache_directory.clone();
+        let host_version = self.config.host_version.clone();
+        let grants = instance.grants.clone();
+        let validation_slot = self
+            .validators
+            .clone()
+            .try_acquire_owned()
+            .map_err(|_| AdminError::unavailable("插件校验繁忙"))?;
+        let (package, configuration, instance, granted_permissions, state_configuration) =
+            tokio::task::spawn_blocking(move || {
+                let _validation_slot = validation_slot;
+                let package = Arc::new(
+                    ValidatedPackage::read(
+                        artifact.archive,
+                        Some(&instance.artifact_sha256),
+                        limits,
+                    )
+                    .map_err(|_| AdminError::invalid("插件恢复包校验失败"))?,
+                );
+                let (configuration, permissions, state_configuration) =
+                    super::super::configuration::validate(&instance, package.manifest())?;
+                crate::adapter::observer::validate_bindings(
+                    package.manifest(),
+                    &instance.bindings,
+                )?;
+                crate::adapter::policy::validate_bindings(package.manifest(), &instance.bindings)?;
+                crate::adapter::frontend_authentication::validate_bindings(
+                    package.manifest(),
+                    &instance.bindings,
+                )?;
+                // 发行清单与当前 Runtime 共用同一份能力声明，不能让二者分别漂移。
+                if !crate::package::host_supports(package.manifest())? {
+                    return Err(AdminError::invalid("该插件声明的业务能力尚未接入运行时"));
+                }
+                if !package
+                    .manifest()
+                    .engines
+                    .codex_proxy_rs
+                    .matches(&host_version)
+                {
+                    return Err(AdminError::invalid(format!(
+                        "插件要求宿主 {}，当前为 {}",
+                        package.manifest().engines.codex_proxy_rs,
+                        host_version
+                    )));
+                }
+                let package = Arc::new(
+                    package
+                        .prepare(&directory, &host_version)
+                        .map_err(|_| AdminError::unavailable("插件制品准备失败"))?,
+                );
+                Ok((
+                    package,
+                    configuration,
+                    instance,
+                    permissions,
+                    state_configuration,
+                ))
+            })
+            .await
+            .map_err(|_| AdminError::internal("插件校验任务失败"))??;
+        let manifest = package.package().manifest().clone();
+        let plugin_id = manifest
+            .plugin_id()
+            .map_err(|_| AdminError::invalid("插件身份无效"))?;
+        let instance_id = instance.id.clone();
+        let restart_identity =
+            RestartIdentity::new(instance_id.clone(), authorization_binding.clone());
+        let bindings = instance.bindings.clone();
+        let mut continuation_provider = None;
+        let owner = self
+            .state
+            .load_owner(
+                gateway_admin::model::plugins::state::PluginStateOwnerRequest {
+                    instance_id: instance.id.clone(),
+                    artifact_sha256: instance.artifact_sha256.clone(),
+                    instance_revision: instance.revision,
+                    configuration: state_configuration.clone(),
+                },
+            )
+            .await
+            .map_err(|error| match error.kind() {
+                PluginStateStoreErrorKind::Unavailable => {
+                    AdminError::unavailable("插件状态存储暂不可用")
+                }
+                _ => AdminError::invalid("插件状态 owner 无法恢复"),
+            })?;
+        let private_state = Arc::new(PluginPrivateState::new(
+            self.state.clone(),
+            &manifest,
+            state_configuration,
+            owner,
+        )?);
+        let incarnation = uuid::Uuid::new_v4().to_string();
+        let lifecycle = self
+            .restart_circuits
+            .begin(restart_identity)
+            .ok_or_else(|| {
+                AdminError::unavailable(
+                    "插件实例连续异常退出，已暂停自动重启；请检查配置后重新启用",
+                )
+            })?;
+        let handshake = Handshake {
+            protocol_version: gateway_plugin_sdk::PROTOCOL_VERSION,
+            artifact_sha256: package.package().digest().into(),
+            plugin_id: plugin_id.clone(),
+            instance_id: instance_id.clone(),
+            generation: target_revision.get(),
+            incarnation,
+            configuration,
+            permissions: granted_permissions.clone(),
+            contributes: manifest.contributes.clone(),
+        };
+        let callbacks = Arc::new(PluginCallbacks::new(
+            &grants,
+            self.config.rpc_limits.maximum_frame_bytes,
+            &manifest,
+            self.log_slots.clone(),
+            private_state.clone(),
+            PluginCallbackPorts::new(
+                self.http.clone(),
+                self.network_policy.clone(),
+                self.account_ports.clone(),
+                self.client_key_ports.clone(),
+                self.model_ports.clone(),
+                self.affinity_ports.clone(),
+            ),
+        )?);
+        let session = Arc::new(
+            RpcSession::start_supervised(
+                package.clone(),
+                handshake,
+                self.config.rpc_limits,
+                &self.processes,
+                callbacks.clone(),
+                lifecycle,
+            )
+            .await
+            .map_err(|_| AdminError::unavailable("插件进程握手失败"))?,
+        );
+        let registration = session
+            .call(
+                "plugin.register",
+                session.context(Stage::Registration, Duration::from_secs(5)),
+                serde_json::json!({}),
+                vec![],
+            )
+            .await
+            .map_err(|_| AdminError::invalid("插件注册失败"))?;
+        let descriptor: Registration = serde_json::from_value(registration.result)
+            .map_err(|_| AdminError::invalid("插件注册结果无效"))?;
+        if descriptor.contributes != manifest.contributes || !registration.payload.is_empty() {
+            return Err(AdminError::invalid("插件注册结果与清单不符"));
+        }
+        let is_provider = manifest.contributes.contains_key(&Capability::Executor);
+        let has_provider_only_capability = manifest.contributes.keys().any(|capability| {
+            matches!(
+                capability,
+                Capability::Models
+                    | Capability::Authentication
+                    | Capability::Quota
+                    | Capability::AccountManagement
+                    | Capability::Billing
+                    | Capability::Maintenance
+                    | Capability::RequestProfile
+            )
+        });
+        if has_provider_only_capability && descriptor.provider.is_none() {
+            return Err(AdminError::invalid(
+                "插件声明了 Provider 专属能力但未注册 Provider",
+            ));
+        }
+        if descriptor.provider.is_some() != is_provider {
+            return Err(AdminError::invalid("插件 Provider 声明与执行能力不符"));
+        }
+        commands.extend(
+            crate::adapter::command_line::prepare(
+                &instance,
+                &manifest,
+                session.clone(),
+                callbacks.clone(),
+            )
+            .await?,
+        );
+        if let Some(entry) = crate::adapter::management::prepare(
+            &instance,
+            package.package(),
+            session.clone(),
+            callbacks.clone(),
+        )
+        .await?
+        {
+            management.push(entry);
+        }
+        if let Some(entry) = crate::adapter::frontend_authentication::prepare_entry(
+            &manifest,
+            &bindings,
+            session.clone(),
+            callbacks.clone(),
+        )
+        .await?
+        {
+            authentication_entries.push(entry);
+        }
+        if let Some(descriptor) = descriptor.provider {
+            let ports = self
+                .provider_ports
+                .as_ref()
+                .ok_or_else(|| AdminError::unavailable("Provider 宿主端口不可用"))?;
+            let provider_binding = crate::adapter::provider::ProviderInstanceBinding::new(
+                instance_id.clone(),
+                authorization_binding,
+                continuation_authorization_fingerprint(&instance, &plugin_id, &descriptor.id)?,
+                Arc::downgrade(&self.continuations),
+            );
+            let provider = Arc::new(crate::adapter::provider::PluginProvider::prepare(
+                descriptor,
+                provider_binding,
+                &manifest,
+                &grants,
+                session.clone(),
+                ports.clone(),
+                callbacks.clone(),
+            )?);
+            provider.register_continuation()?;
+            let provider_kind = ProviderKind::new(provider.name())
+                .map_err(|_| AdminError::invalid("插件 Provider ID 无效"))?;
+            provider.restore_request_profiles().await?;
+            self.validate_provider_request_profiles(
+                config_revision,
+                &provider_kind,
+                provider.as_ref(),
+            )
+            .await?;
+            request_profile_providers.push(provider_kind);
+            if provider.maintenance_enabled(&manifest, &bindings)? {
+                maintenance.push(super::super::worker::MaintenanceEntry {
+                    instance_id: instance_id.clone(),
+                    artifact_sha256: instance.artifact_sha256.clone(),
+                    revision: instance.revision,
+                    provider: provider.clone(),
+                });
+            }
+            admin_providers.push(provider.clone());
+            providers.push(provider.clone());
+            continuation_provider = Some(provider);
+        }
+        if let Some(entry) = crate::adapter::observer::compile_entry(
+            &manifest,
+            &plugin_id,
+            &instance_id,
+            &bindings,
+            &granted_permissions,
+            session.clone(),
+            callbacks.clone(),
+        )? {
+            observer_entries.push(entry);
+        }
+        policy_entries.extend(crate::adapter::policy::compile_entries(
+            &manifest,
+            &instance_id,
+            &bindings,
+            &granted_permissions,
+            session.clone(),
+            callbacks.clone(),
+        )?);
+        sessions.push(PreparedInstance {
+            instance_id,
+            artifact_sha256: instance.artifact_sha256,
+            revision: instance.revision,
+            session,
+            private_state,
+            continuation_provider,
+        });
+        Ok(PreparedContributions {
+            sessions,
+            providers,
+            request_profile_providers,
+            admin_providers,
+            observer_entries,
+            commands,
+            management,
+            maintenance,
+            policy_entries,
+            authentication_entries,
+        })
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/generation/prepare/mod.rs b/backend/crates/gateway-plugin/runtime/src/generation/prepare/mod.rs
new file mode 100644
index 000000000..f94af7cfa
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/generation/prepare/mod.rs
@@ -0,0 +1,1408 @@
+mod instance;
+
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    num::NonZeroUsize,
+    path::PathBuf,
+    sync::{
+        Arc, Mutex as SyncMutex, Weak,
+        atomic::{AtomicBool, Ordering},
+    },
+    time::Duration,
+};
+
+use async_trait::async_trait;
+use futures::future::BoxFuture;
+use gateway_admin::{
+    model::{
+        AdminError, AdminErrorKind, Revision,
+        plugins::{
+            instances::{
+                PluginInstance, PluginInstanceRuntime, PluginInstanceRuntimeFailure,
+                PluginInstanceRuntimeStatus, PluginInstanceSnapshot,
+            },
+            state::{
+                ApplyPluginStateMigration, PluginStateConfiguration, PluginStateMigrationAction,
+                PluginStateMigrationChange, PluginStateTransition,
+            },
+        },
+    },
+    ports::{
+        plugin_accounts::PluginAccountAccess,
+        plugin_client_keys::PluginClientKeyAccess,
+        plugins::{PluginPreparation, PluginStateStore, PluginStateStoreErrorKind, PluginStore},
+        provider::{ProviderAdmin, ProviderAdminRegistry},
+        provider_extensions::ProviderAdminExtensionIndex,
+    },
+};
+use gateway_core::{
+    engine::{
+        authentication::FrontendAuthenticationExtensionIndex,
+        extensions::ProviderExtensionIndex,
+        middleware::{MiddlewareExtensionIndex, MiddlewarePlan},
+        nested::{AffinityLookupPort, NestedModelExecutionPort},
+        observation::{RequestObserverExtensionIndex, RequestObserverPlan},
+        policy::{RequestPolicyExtensionIndex, RequestPolicyPlan},
+        provider::{Provider, ProviderRegistry},
+    },
+    provider_ports::{ProviderStoreErrorKind, ProviderStorePorts},
+    routing::{ConfigRevision, ProviderKind},
+    runtime::extensions::{
+        ExtensionPreparationError, ExtensionPreparationPort, ExtensionSetId, ExtensionSetLease,
+        ExtensionSetReference,
+    },
+};
+use gateway_plugin_sdk::{
+    Capability, Handshake, Stage,
+    call::{
+        host::{
+            StateMigrationChange, StateMigrationRecord, StateMigrationRequest, StateMigrationResult,
+        },
+        provider::Registration,
+    },
+};
+use secrecy::ExposeSecret as _;
+use sha2::{Digest as _, Sha256};
+use tokio::sync::{Mutex, Semaphore};
+
+use crate::{
+    PackageLimits, RpcLimits, RpcSession, ValidatedPackage,
+    callback::{
+        PluginAccountPortSlot, PluginAffinityPortSlot, PluginCallbackPorts, PluginCallbacks,
+        PluginClientKeyPortSlot, PluginModelPortSlot, private_state::PluginPrivateState,
+    },
+};
+
+use super::restart_circuit::{PluginRestartCircuitConfig, RestartCircuits, RestartIdentity};
+
+const RUNTIME_SHUTDOWN_GRACE: Duration = Duration::from_secs(2);
+const MAXIMUM_PREPARATION_DIAGNOSTICS: usize = 8;
+
+pub struct PluginRuntimeConfig {
+    pub cache_directory: PathBuf,
+    pub host_version: semver::Version,
+    pub package_limits: PackageLimits,
+    pub rpc_limits: RpcLimits,
+    pub continuation_drain: ContinuationDrainConfig,
+    pub restart_circuit: PluginRestartCircuitConfig,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct ContinuationDrainConfig {
+    pub retention: Duration,
+    pub maximum_generations: NonZeroUsize,
+    pub maximum_per_instance: NonZeroUsize,
+}
+
+impl Default for ContinuationDrainConfig {
+    fn default() -> Self {
+        Self {
+            retention: Duration::from_secs(30 * 60),
+            maximum_generations: NonZeroUsize::new(64).unwrap_or(NonZeroUsize::MIN),
+            maximum_per_instance: NonZeroUsize::new(2).unwrap_or(NonZeroUsize::MIN),
+        }
+    }
+}
+
+/// 只索引有主人的候选；当前代次仅由 Core 的发布视图持有。
+pub struct PluginRuntime {
+    pub(super) store: Arc<dyn PluginStore>,
+    state: Arc<dyn PluginStateStore>,
+    config: PluginRuntimeConfig,
+    prepare_lock: Mutex<()>,
+    prepared: Mutex<BTreeMap<String, Weak<PreparedSet>>>,
+    preparation_diagnostics: SyncMutex<BTreeMap<u64, PreparationDiagnostic>>,
+    restart_circuits: Arc<RestartCircuits>,
+    shutting_down: Arc<AtomicBool>,
+    shutdown_lock: Mutex<()>,
+    processes: Arc<gateway_host::process::ProcessSupervisor>,
+    validators: Arc<Semaphore>,
+    log_slots: Arc<Semaphore>,
+    pub(super) account_ports: Arc<PluginAccountPortSlot>,
+    client_key_ports: Arc<PluginClientKeyPortSlot>,
+    model_ports: Arc<PluginModelPortSlot>,
+    affinity_ports: Arc<PluginAffinityPortSlot>,
+    providers: ProviderExtensionIndex,
+    observers: RequestObserverExtensionIndex,
+    policies: RequestPolicyExtensionIndex,
+    middleware: MiddlewareExtensionIndex,
+    authentications: FrontendAuthenticationExtensionIndex,
+    admin_providers: ProviderAdminExtensionIndex,
+    provider_ports: Option<ProviderStorePorts>,
+    http: Arc<gateway_host::outbound::HttpClient>,
+    network_policy: gateway_host::outbound::NetworkPolicy,
+    continuations: Arc<crate::adapter::provider::ContinuationDrain>,
+}
+
+#[derive(Clone)]
+enum PreparationDiagnostic {
+    Preparing,
+    Prepared { set_id: String },
+    Failed(PluginInstanceRuntimeFailure),
+}
+
+pub(super) struct PreparedSet {
+    id: ExtensionSetId,
+    providers: Arc<ProviderRegistry>,
+    request_profile_providers: Vec<ProviderKind>,
+    _observers: Option<Arc<dyn RequestObserverPlan>>,
+    _policies: Option<Arc<dyn RequestPolicyPlan>>,
+    _middleware: Option<Arc<dyn MiddlewarePlan>>,
+    _authentication:
+        Option<Arc<dyn gateway_core::engine::authentication::FrontendAuthenticationPlan>>,
+    _admin_providers: Arc<ProviderAdminRegistry>,
+    sessions: Vec<PreparedInstance>,
+    failures: BTreeMap<String, PluginInstanceRuntimeFailure>,
+    shutting_down: Arc<AtomicBool>,
+    commands: Vec<Arc<crate::adapter::command_line::PluginCommand>>,
+    management: Vec<crate::adapter::management::ManagementEntry>,
+    pub(super) maintenance: Vec<super::worker::MaintenanceEntry>,
+}
+
+#[derive(Default)]
+struct PreparedContributions {
+    sessions: Vec<PreparedInstance>,
+    providers: Vec<Arc<dyn Provider>>,
+    request_profile_providers: Vec<ProviderKind>,
+    admin_providers: Vec<Arc<dyn ProviderAdmin>>,
+    observer_entries: Vec<crate::adapter::observer::ObserverEntry>,
+    commands: Vec<Arc<crate::adapter::command_line::PluginCommand>>,
+    management: Vec<crate::adapter::management::ManagementEntry>,
+    maintenance: Vec<super::worker::MaintenanceEntry>,
+    policy_entries: Vec<crate::adapter::policy::PolicyEntry>,
+    authentication_entries:
+        Vec<crate::adapter::frontend_authentication::FrontendAuthenticationEntry>,
+}
+
+impl PreparedContributions {
+    fn append(&mut self, other: Self) {
+        self.sessions.extend(other.sessions);
+        self.providers.extend(other.providers);
+        self.request_profile_providers
+            .extend(other.request_profile_providers);
+        self.admin_providers.extend(other.admin_providers);
+        self.observer_entries.extend(other.observer_entries);
+        self.commands.extend(other.commands);
+        self.management.extend(other.management);
+        self.maintenance.extend(other.maintenance);
+        self.policy_entries.extend(other.policy_entries);
+        self.authentication_entries
+            .extend(other.authentication_entries);
+    }
+}
+
+struct PreparedInstance {
+    instance_id: String,
+    artifact_sha256: String,
+    revision: Revision,
+    session: Arc<RpcSession>,
+    private_state: Arc<PluginPrivateState>,
+    continuation_provider: Option<Arc<crate::adapter::provider::PluginProvider>>,
+}
+
+impl PreparedSet {
+    fn sessions_ready(&self) -> bool {
+        self.sessions
+            .iter()
+            .all(|instance| instance.session.is_ready())
+    }
+}
+
+impl ExtensionSetLease for PreparedSet {
+    fn is_ready(&self) -> bool {
+        self.sessions_ready() && self.can_serve()
+    }
+
+    fn can_serve(&self) -> bool {
+        // 发布的是可用能力和故障绑定组成的完整计划；单个进程退出不能使原生转发失效。
+        !self.shutting_down.load(Ordering::Acquire)
+    }
+}
+
+impl Drop for PreparedSet {
+    fn drop(&mut self) {
+        for mut instance in self.sessions.drain(..) {
+            if instance
+                .continuation_provider
+                .take()
+                .is_some_and(|provider| provider.retire_continuation())
+            {
+                continue;
+            }
+            if let Ok(handle) = tokio::runtime::Handle::try_current() {
+                handle.spawn(async move {
+                    let session = instance.session;
+                    session.quiesce();
+                    session.shutdown(Duration::from_secs(1)).await;
+                });
+            }
+        }
+    }
+}
+
+impl PluginRuntime {
+    #[must_use]
+    pub fn new(
+        store: Arc<dyn PluginStore>,
+        state: Arc<dyn PluginStateStore>,
+        config: PluginRuntimeConfig,
+        providers: ProviderRegistry,
+        admin_providers: ProviderAdminRegistry,
+        http: Arc<gateway_host::outbound::HttpClient>,
+        processes: Arc<gateway_host::process::ProcessSupervisor>,
+    ) -> Self {
+        let continuations =
+            crate::adapter::provider::ContinuationDrain::new(config.continuation_drain);
+        let restart_circuit = config.restart_circuit;
+        Self {
+            store,
+            state,
+            log_slots: Arc::new(Semaphore::new(
+                config
+                    .rpc_limits
+                    .maximum_callbacks
+                    .min(Semaphore::MAX_PERMITS),
+            )),
+            config,
+            prepare_lock: Mutex::new(()),
+            prepared: Mutex::new(BTreeMap::new()),
+            preparation_diagnostics: SyncMutex::new(BTreeMap::new()),
+            restart_circuits: RestartCircuits::new(restart_circuit),
+            shutting_down: Arc::new(AtomicBool::new(false)),
+            shutdown_lock: Mutex::new(()),
+            processes,
+            validators: Arc::new(Semaphore::new(2)),
+            account_ports: Arc::new(PluginAccountPortSlot::new()),
+            client_key_ports: Arc::new(PluginClientKeyPortSlot::new()),
+            model_ports: Arc::new(PluginModelPortSlot::new()),
+            affinity_ports: Arc::new(PluginAffinityPortSlot::new()),
+            providers: ProviderExtensionIndex::new(providers),
+            observers: RequestObserverExtensionIndex::default(),
+            policies: RequestPolicyExtensionIndex::default(),
+            middleware: MiddlewareExtensionIndex::default(),
+            authentications: FrontendAuthenticationExtensionIndex::default(),
+            admin_providers: ProviderAdminExtensionIndex::new(admin_providers),
+            provider_ports: None,
+            http,
+            network_policy: gateway_host::outbound::NetworkPolicy::default(),
+            continuations,
+        }
+    }
+
+    #[must_use]
+    pub fn with_provider_ports(mut self, ports: ProviderStorePorts) -> Self {
+        self.provider_ports = Some(ports);
+        self
+    }
+
+    /// 宿主统一决定可到达的地址段；插件配置与请求不能自行放宽 DNS/IP 边界。
+    #[must_use]
+    pub fn with_network_policy(mut self, policy: gateway_host::outbound::NetworkPolicy) -> Self {
+        self.network_policy = policy;
+        self
+    }
+
+    /// Admin 初始化后一次性绑定窄账号端口；Runtime 仅保存 Weak，避免组合根强环。
+    pub fn bind_account_ports(
+        &self,
+        access: &Arc<dyn PluginAccountAccess>,
+    ) -> Result<(), AdminError> {
+        self.account_ports.bind(access)
+    }
+
+    /// Key 目录由 Admin 组合并保活，Runtime 不取得明文访问端口。
+    pub fn bind_client_key_ports(
+        &self,
+        access: &Arc<dyn PluginClientKeyAccess>,
+    ) -> Result<(), AdminError> {
+        self.client_key_ports.bind(access)
+    }
+
+    /// Core 激活后一次性绑定嵌套执行与亲和查询端口；Runtime 仅保存 Weak，避免组合根强环。
+    pub fn bind_model_ports(
+        &self,
+        models: &Arc<dyn NestedModelExecutionPort>,
+        affinity: &Arc<dyn AffinityLookupPort>,
+    ) -> Result<(), AdminError> {
+        self.model_ports.bind(models)?;
+        self.affinity_ports.bind(affinity)
+    }
+
+    /// 调用方必须先停止接收 HTTP 与 Worker；这里拒绝新候选并等待全部插件 I/O 退出。
+    pub async fn shutdown(&self) {
+        self.shutting_down.store(true, Ordering::Release);
+        let _shutdown = self.shutdown_lock.lock().await;
+        let _prepare = self.prepare_lock.lock().await;
+        let sets = {
+            let mut prepared = self.prepared.lock().await;
+            prepared.retain(|_, set| set.strong_count() > 0);
+            let sets = prepared
+                .values()
+                .filter_map(Weak::upgrade)
+                .collect::<Vec<_>>();
+            prepared.clear();
+            sets
+        };
+        let mut sessions = self.continuations.sessions();
+        for set in &sets {
+            for instance in &set.sessions {
+                if !sessions
+                    .iter()
+                    .any(|session| Arc::ptr_eq(session, &instance.session))
+                {
+                    sessions.push(Arc::clone(&instance.session));
+                }
+            }
+        }
+        shutdown_sessions(sessions, RUNTIME_SHUTDOWN_GRACE).await;
+        self.continuations.finish_shutdown();
+    }
+
+    #[must_use]
+    pub fn provider_registry(&self) -> ProviderRegistry {
+        self.providers.registry()
+    }
+
+    #[must_use]
+    pub fn observer_registry(&self) -> RequestObserverExtensionIndex {
+        self.observers.clone()
+    }
+
+    #[must_use]
+    pub fn policy_registry(&self) -> RequestPolicyExtensionIndex {
+        self.policies.clone()
+    }
+
+    #[must_use]
+    pub fn middleware_registry(&self) -> MiddlewareExtensionIndex {
+        self.middleware.clone()
+    }
+
+    #[must_use]
+    pub fn frontend_authentication_registry(&self) -> FrontendAuthenticationExtensionIndex {
+        self.authentications.clone()
+    }
+
+    #[must_use]
+    pub fn admin_registry(
+        &self,
+        snapshots: gateway_core::runtime::RuntimeSnapshotHandle,
+    ) -> ProviderAdminRegistry {
+        self.admin_providers.registry(snapshots)
+    }
+
+    fn record_preparation(&self, revision: u64, diagnostic: PreparationDiagnostic) {
+        let mut diagnostics = self
+            .preparation_diagnostics
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        diagnostics.insert(revision, diagnostic);
+        while diagnostics.len() > MAXIMUM_PREPARATION_DIAGNOSTICS {
+            diagnostics.pop_first();
+        }
+    }
+
+    fn preparation_diagnostic(&self, revision: u64) -> Option<PreparationDiagnostic> {
+        self.preparation_diagnostics
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .get(&revision)
+            .cloned()
+    }
+
+    fn restart_circuit_is_open(&self, identity: &RestartIdentity) -> bool {
+        self.restart_circuits.is_open(identity)
+    }
+
+    async fn validate_request_profile_configurations(
+        &self,
+        revision: ConfigRevision,
+        providers: &ProviderRegistry,
+        provider_kinds: &[ProviderKind],
+    ) -> Result<(), AdminError> {
+        for provider_kind in provider_kinds {
+            let provider = providers
+                .get(provider_kind)
+                .ok_or_else(|| AdminError::invalid("插件 Provider 注册结果缺失"))?;
+            self.validate_provider_request_profiles(revision, provider_kind, provider.as_ref())
+                .await?;
+        }
+        Ok(())
+    }
+
+    async fn validate_provider_request_profiles(
+        &self,
+        revision: ConfigRevision,
+        provider_kind: &ProviderKind,
+        provider: &dyn Provider,
+    ) -> Result<(), AdminError> {
+        let ports = self
+            .provider_ports
+            .as_ref()
+            .ok_or_else(|| AdminError::unavailable("Provider 宿主端口不可用"))?;
+        let configurations = ports
+            .runtime_policy()
+            .load_request_profile_configurations(revision, provider_kind)
+            .await
+            .map_err(|error| match error.kind() {
+                ProviderStoreErrorKind::Unavailable => {
+                    AdminError::unavailable("Provider 请求画像配置读取失败")
+                }
+                ProviderStoreErrorKind::Conflict => AdminError::conflict("插件候选配置版本已变化"),
+                ProviderStoreErrorKind::InvalidData => {
+                    AdminError::invalid("Provider 请求画像配置无效")
+                }
+            })?;
+        configurations.iter().try_for_each(|configuration| {
+            provider
+                .resolve_request_profile(configuration)
+                .map(|_| ())
+                .map_err(|_| AdminError::invalid("已保存的 Provider 请求画像不受当前插件支持"))
+        })
+    }
+
+    async fn prepare_snapshot(
+        &self,
+        source_revision: Revision,
+        snapshot: PluginInstanceSnapshot,
+        required_revision: Option<Revision>,
+    ) -> Result<ExtensionSetReference, AdminError> {
+        let target_revision = snapshot.config_revision.get();
+        self.record_preparation(target_revision, PreparationDiagnostic::Preparing);
+        let result = self
+            .prepare_inner(source_revision, snapshot, required_revision)
+            .await;
+        match &result {
+            Ok(reference) => self.record_preparation(
+                target_revision,
+                PreparationDiagnostic::Prepared {
+                    set_id: reference.id().as_str().to_owned(),
+                },
+            ),
+            Err(error) => self.record_preparation(
+                target_revision,
+                PreparationDiagnostic::Failed(runtime_failure_from_admin(error)),
+            ),
+        }
+        result
+    }
+
+    async fn prepare_inner(
+        &self,
+        source_revision: Revision,
+        snapshot: PluginInstanceSnapshot,
+        required_revision: Option<Revision>,
+    ) -> Result<ExtensionSetReference, AdminError> {
+        if self.shutting_down.load(Ordering::Acquire) {
+            return Err(AdminError::unavailable("插件运行时正在关闭"));
+        }
+        if snapshot.instances.len() > 64 {
+            return Err(AdminError::invalid("最多配置 64 个插件实例"));
+        }
+        self.continuations.reap_expired().await;
+        let config_revision = ConfigRevision::new(source_revision.get())
+            .map_err(|_| AdminError::invalid("插件候选事实版本无效"))?;
+        let fingerprint = fingerprint(&snapshot)?;
+        // 准备串行化与弱索引分锁；诊断和已发布请求不会等待外部 I/O。
+        let _prepare = self.prepare_lock.lock().await;
+        if self.shutting_down.load(Ordering::Acquire) {
+            return Err(AdminError::unavailable("插件运行时正在关闭"));
+        }
+        let existing = {
+            let mut prepared = self.prepared.lock().await;
+            prepared.retain(|_, set| set.strong_count() > 0);
+            prepared
+                .get(&fingerprint)
+                .and_then(Weak::upgrade)
+                .filter(|set| set.sessions_ready())
+        };
+        if let Some(set) = existing {
+            if snapshot.instances.iter().any(|instance| {
+                required_revision == Some(instance.revision)
+                    && set.failures.contains_key(&instance.id)
+            }) {
+                return Err(AdminError::unavailable("插件启动失败，请重新启用后重试"));
+            }
+            self.validate_request_profile_configurations(
+                config_revision,
+                &set.providers,
+                &set.request_profile_providers,
+            )
+            .await?;
+            return Ok(ExtensionSetReference::new(set.id.clone(), set));
+        }
+        let mut contributions = PreparedContributions::default();
+        let mut failures = BTreeMap::new();
+        let mut identities = BTreeSet::new();
+        for instance in snapshot
+            .instances
+            .iter()
+            .filter(|instance| instance.enabled)
+        {
+            if !identities.insert(instance.id.clone()) {
+                return Err(AdminError::invalid("插件实例 ID 重复"));
+            }
+            let result = tokio::time::timeout(
+                // 沿用准备阶段原有的 30 秒预算；打包校验与能力恢复也在预算内。
+                Duration::from_secs(30),
+                self.prepare_instance(instance.clone(), config_revision, snapshot.config_revision),
+            )
+            .await
+            .unwrap_or_else(|_| Err(AdminError::unavailable("插件启动超时")));
+            let result = result.and_then(|candidate| {
+                self.validate_provider_addition(&contributions, &candidate)?;
+                Ok(candidate)
+            });
+            match result {
+                Ok(candidate) => contributions.append(candidate),
+                Err(error) if required_revision == Some(instance.revision) => return Err(error),
+                Err(error) => {
+                    // 恢复失败只隔离该实例；绑定的拒绝策略仍保留，不能绕过认证或必需处理。
+                    contributions
+                        .policy_entries
+                        .extend(crate::adapter::policy::unavailable_entries(instance)?);
+                    if let Some(entry) =
+                        crate::adapter::frontend_authentication::unavailable_entry(instance)
+                    {
+                        contributions.authentication_entries.push(entry);
+                    }
+                    failures.insert(instance.id.clone(), runtime_failure_from_admin(&error));
+                }
+            }
+        }
+        let PreparedContributions {
+            sessions,
+            providers,
+            request_profile_providers,
+            admin_providers,
+            observer_entries,
+            commands,
+            management,
+            maintenance,
+            policy_entries,
+            authentication_entries,
+        } = contributions;
+        let id = ExtensionSetId::new(uuid::Uuid::new_v4().to_string())
+            .map_err(|_| AdminError::internal("插件集合 ID 无效"))?;
+        let providers = self
+            .providers
+            .register(id.clone(), providers)
+            .map_err(|_| AdminError::invalid("插件 Provider 注册冲突"))?;
+        let observers = crate::adapter::observer::PluginObserverPlan::compile(
+            observer_entries,
+            self.config.rpc_limits.maximum_calls,
+            self.config.rpc_limits.maximum_call_timeout,
+            self.config.rpc_limits.maximum_frame_bytes,
+        )
+        .map(|plan| {
+            self.observers
+                .register(id.clone(), plan)
+                .map_err(|_| AdminError::invalid("插件观察计划注册冲突"))
+        })
+        .transpose()?;
+        let policy_plan = crate::adapter::policy::PluginRequestPolicyPlan::compile(
+            policy_entries,
+            self.config.rpc_limits.maximum_call_timeout,
+            self.config.rpc_limits.maximum_frame_bytes,
+        )?;
+        let policies = policy_plan
+            .as_ref()
+            .filter(|plan| plan.has_request_policy())
+            .cloned()
+            .map(|plan| {
+                self.policies
+                    .register(id.clone(), plan)
+                    .map_err(|_| AdminError::invalid("插件请求策略计划注册冲突"))
+            })
+            .transpose()?;
+        let middleware = policy_plan
+            .filter(|plan| plan.has_middleware())
+            .map(|plan| {
+                self.middleware
+                    .register(id.clone(), plan)
+                    .map_err(|_| AdminError::invalid("插件中间件计划注册冲突"))
+            })
+            .transpose()?;
+        let authentication =
+            crate::adapter::frontend_authentication::PluginFrontendAuthenticationPlan::compile(
+                authentication_entries,
+                self.config.rpc_limits.maximum_call_timeout,
+            )?
+            .map(|plan| {
+                self.authentications
+                    .register(id.clone(), plan)
+                    .map_err(|_| AdminError::invalid("插件入口认证计划注册冲突"))
+            })
+            .transpose()?;
+        let set = Arc::new(PreparedSet {
+            _admin_providers: self
+                .admin_providers
+                .register(id.clone(), admin_providers)
+                .map_err(|_| AdminError::invalid("插件管理 Provider 注册冲突"))?,
+            id,
+            providers,
+            request_profile_providers,
+            _observers: observers,
+            _policies: policies,
+            _middleware: middleware,
+            _authentication: authentication,
+            sessions,
+            commands,
+            management,
+            maintenance,
+            failures,
+            shutting_down: self.shutting_down.clone(),
+        });
+        self.prepared
+            .lock()
+            .await
+            .insert(fingerprint, Arc::downgrade(&set));
+        Ok(ExtensionSetReference::new(set.id.clone(), set))
+    }
+
+    fn validate_provider_addition(
+        &self,
+        current: &PreparedContributions,
+        candidate: &PreparedContributions,
+    ) -> Result<(), AdminError> {
+        // 先在私有候选中检查身份冲突，避免一个插件覆盖原生 Provider 或拖累其他实例。
+        let id = ExtensionSetId::new(uuid::Uuid::new_v4().to_string())
+            .map_err(|_| AdminError::internal("插件集合 ID 无效"))?;
+        let _providers = self
+            .providers
+            .register(
+                id.clone(),
+                current
+                    .providers
+                    .iter()
+                    .chain(&candidate.providers)
+                    .cloned(),
+            )
+            .map_err(|_| AdminError::invalid("插件 Provider 注册冲突"))?;
+        let _admin = self
+            .admin_providers
+            .register(
+                id,
+                current
+                    .admin_providers
+                    .iter()
+                    .chain(&candidate.admin_providers)
+                    .cloned(),
+            )
+            .map_err(|_| AdminError::invalid("插件管理 Provider 注册冲突"))?;
+        Ok(())
+    }
+
+    /// CLI 复用同一候选准备与弱索引；读取帮助不会发布 Core 快照或执行命令。
+    pub async fn prepare_command_line(&self) -> Result<crate::PluginCommandSession, AdminError> {
+        let snapshot = self
+            .store
+            .load_instances()
+            .await
+            .map_err(|_| AdminError::unavailable("无法读取已安装插件"))?;
+        let reference = self
+            .prepare_snapshot(snapshot.config_revision, snapshot, None)
+            .await?;
+        let set = self.prepared_set(&reference).await?;
+        Ok(crate::PluginCommandSession::new(
+            reference,
+            set.commands.clone(),
+            set.sessions
+                .iter()
+                .map(|instance| instance.session.clone())
+                .collect(),
+            self.store.clone(),
+            self.config.rpc_limits,
+        ))
+    }
+
+    pub(super) async fn prepared_set(
+        &self,
+        reference: &ExtensionSetReference,
+    ) -> Result<Arc<PreparedSet>, AdminError> {
+        self.prepared
+            .lock()
+            .await
+            .values()
+            .filter_map(Weak::upgrade)
+            .find(|set| set.id == *reference.id())
+            .ok_or_else(|| AdminError::conflict("插件候选已过期，请重试"))
+    }
+
+    async fn run_state_migration(
+        &self,
+        prepared: &ExtensionSetReference,
+        transition: PluginStateTransition,
+    ) -> Result<(), AdminError> {
+        let set = self.prepared_set(prepared).await?;
+        let instance = set
+            .sessions
+            .iter()
+            .find(|instance| {
+                instance.instance_id == transition.instance_id
+                    && instance.artifact_sha256 == transition.artifact_sha256
+            })
+            .ok_or_else(|| AdminError::conflict("状态迁移候选插件已失效"))?;
+        for namespace in &transition.namespaces {
+            let mut batches = 0usize;
+            loop {
+                batches += 1;
+                if batches > 200 {
+                    return Err(AdminError::invalid("插件状态迁移超过有界批次数"));
+                }
+                let batch = self
+                    .state
+                    .migration_batch(&transition.id, &namespace.namespace, 64)
+                    .await
+                    .map_err(map_state_admin_error)?;
+                let expected_keys = batch
+                    .records
+                    .iter()
+                    .map(|record| record.key.clone())
+                    .collect::<Vec<_>>();
+                if batch.records.is_empty() {
+                    self.state
+                        .apply_migration_batch(ApplyPluginStateMigration {
+                            transition_id: transition.id.clone(),
+                            namespace: namespace.namespace.clone(),
+                            cursor: batch.cursor,
+                            expected_keys,
+                            changes: Vec::new(),
+                        })
+                        .await
+                        .map_err(map_state_admin_error)?;
+                    break;
+                }
+                let request = StateMigrationRequest {
+                    namespace: namespace.namespace.clone(),
+                    from_schema_version: namespace.from_schema_version,
+                    to_schema_version: namespace.to_schema_version,
+                    records: batch
+                        .records
+                        .iter()
+                        .map(|record| StateMigrationRecord {
+                            key: record.key.clone(),
+                            value: record.value.clone(),
+                            version: record.version,
+                        })
+                        .collect(),
+                };
+                let reply = instance
+                    .session
+                    .call(
+                        "plugin.state.migrate",
+                        instance
+                            .session
+                            .context(Stage::Configuration, Duration::from_secs(30)),
+                        serde_json::json!({}),
+                        serde_json::to_vec(&request)
+                            .map_err(|_| AdminError::internal("状态迁移批次无法编码"))?,
+                    )
+                    .await
+                    .map_err(|_| AdminError::invalid("插件状态迁移调用失败"))?;
+                if reply.result != serde_json::json!({}) {
+                    return Err(AdminError::invalid("插件状态迁移结果信封无效"));
+                }
+                let result: StateMigrationResult = serde_json::from_slice(&reply.payload)
+                    .map_err(|_| AdminError::invalid("插件状态迁移结果无效"))?;
+                if result.changes.len() != batch.records.len()
+                    || result
+                        .changes
+                        .iter()
+                        .zip(&expected_keys)
+                        .any(|(change, expected)| change.key() != expected)
+                {
+                    return Err(AdminError::invalid("插件状态迁移结果未逐项对应源批次"));
+                }
+                let mut changes = Vec::with_capacity(result.changes.len());
+                for (change, source) in result.changes.into_iter().zip(&batch.records) {
+                    let (key, action) = match change {
+                        StateMigrationChange::Keep { key } => {
+                            instance
+                                .private_state
+                                .validate_value(&namespace.namespace, &source.value)?;
+                            (key, PluginStateMigrationAction::Keep)
+                        }
+                        StateMigrationChange::Replace { key, value } => {
+                            instance
+                                .private_state
+                                .validate_value(&namespace.namespace, &value)?;
+                            (key, PluginStateMigrationAction::Replace(value))
+                        }
+                        StateMigrationChange::Delete { key } => {
+                            (key, PluginStateMigrationAction::Delete)
+                        }
+                    };
+                    changes.push(PluginStateMigrationChange { key, action });
+                }
+                self.state
+                    .apply_migration_batch(ApplyPluginStateMigration {
+                        transition_id: transition.id.clone(),
+                        namespace: namespace.namespace.clone(),
+                        cursor: batch.cursor,
+                        expected_keys,
+                        changes,
+                    })
+                    .await
+                    .map_err(map_state_admin_error)?;
+            }
+        }
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl gateway_admin::ports::plugin_management::PluginManagement for PluginRuntime {
+    async fn authorize_models(
+        &self,
+        published: &ExtensionSetReference,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+    ) -> Result<(), AdminError> {
+        let set = self.prepared_set(published).await?;
+        let entry = set
+            .management
+            .iter()
+            .find(|entry| &entry.view.target == target)
+            .ok_or_else(|| AdminError::conflict("插件页面版本已变化，请刷新页面"))?;
+        if !entry.models_authorized {
+            return Err(AdminError::new(
+                gateway_admin::model::AdminErrorKind::Forbidden,
+                "插件未声明模型访问能力",
+            ));
+        }
+        Ok(())
+    }
+
+    async fn start_callback(
+        &self,
+        published: &ExtensionSetReference,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+        command: gateway_admin::model::plugins::management::StartPluginManagementCallback,
+        context: &gateway_admin::model::auth::AdminRequestContext,
+    ) -> Result<gateway_admin::model::plugins::management::PluginManagementCallbackTicket, AdminError>
+    {
+        let store = self
+            .provider_ports
+            .as_ref()
+            .ok_or_else(|| AdminError::unavailable("插件登录状态端口不可用"))?
+            .oauth_pending();
+        self.prepared_set(published)
+            .await?
+            .management
+            .iter()
+            .find(|entry| &entry.view.target == target)
+            .ok_or_else(|| AdminError::conflict("插件页面版本已变化，请刷新页面"))?
+            .start_callback(store.as_ref(), command, context)
+            .await
+    }
+
+    async fn callback(
+        &self,
+        published: &ExtensionSetReference,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+        state: &str,
+        request: gateway_admin::model::plugins::management::PluginManagementRequest,
+    ) -> Result<gateway_admin::model::plugins::management::PluginManagementResponse, AdminError>
+    {
+        let store = self
+            .provider_ports
+            .as_ref()
+            .ok_or_else(|| AdminError::unavailable("插件登录状态端口不可用"))?
+            .oauth_pending();
+        self.prepared_set(published)
+            .await?
+            .management
+            .iter()
+            .find(|entry| &entry.view.target == target)
+            .ok_or_else(|| AdminError::conflict("插件页面版本已变化，请刷新页面"))?
+            .callback(store.as_ref(), state, request, self.config.rpc_limits)
+            .await
+    }
+
+    async fn views(
+        &self,
+        published: &ExtensionSetReference,
+    ) -> Result<Vec<gateway_admin::model::plugins::management::PluginManagementView>, AdminError>
+    {
+        Ok(self
+            .prepared_set(published)
+            .await?
+            .management
+            .iter()
+            .map(|entry| entry.view.clone())
+            .collect())
+    }
+
+    async fn resource(
+        &self,
+        published: &ExtensionSetReference,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+        path: &str,
+        public: bool,
+    ) -> Result<gateway_admin::model::plugins::management::PluginManagementResponse, AdminError>
+    {
+        self.prepared_set(published)
+            .await?
+            .management
+            .iter()
+            .find(|entry| &entry.view.target == target)
+            .ok_or_else(|| AdminError::conflict("插件页面版本已变化，请刷新页面"))?
+            .resource(path, public)
+    }
+
+    async fn handle(
+        &self,
+        published: &ExtensionSetReference,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+        request: gateway_admin::model::plugins::management::PluginManagementRequest,
+    ) -> Result<gateway_admin::model::plugins::management::PluginManagementResponse, AdminError>
+    {
+        self.prepared_set(published)
+            .await?
+            .management
+            .iter()
+            .find(|entry| &entry.view.target == target)
+            .ok_or_else(|| AdminError::conflict("插件页面版本已变化，请刷新页面"))?
+            .handle(request, self.config.rpc_limits)
+            .await
+    }
+}
+
+#[async_trait]
+impl PluginPreparation for PluginRuntime {
+    async fn configuration_ready(
+        &self,
+        instance: PluginInstance,
+        metadata: &gateway_admin::model::plugins::PluginArtifactMetadata,
+    ) -> Result<bool, AdminError> {
+        if instance.artifact_sha256 != metadata.sha256 {
+            return Err(AdminError::invalid("插件配置与制品不匹配"));
+        }
+        // 安装时已验证声明；只读列表不重新解包，也不占用安装与启用的校验配额。
+        let schema = metadata.configuration_schema.clone();
+        let secret_fields = metadata.secret_fields.iter().cloned().collect();
+        tokio::task::spawn_blocking(move || {
+            super::configuration::configuration_ready(&instance, &schema, &secret_fields)
+        })
+        .await
+        .map_err(|_| AdminError::internal("插件校验任务失败"))?
+    }
+
+    async fn validate(
+        &self,
+        instance: PluginInstance,
+    ) -> Result<PluginStateConfiguration, AdminError> {
+        let artifact = self
+            .store
+            .load_artifact(&instance.artifact_sha256)
+            .await
+            .map_err(|_| AdminError::not_found("插件制品不存在"))?;
+        let limits = self.config.package_limits;
+        let slot = self
+            .validators
+            .clone()
+            .try_acquire_owned()
+            .map_err(|_| AdminError::unavailable("插件校验繁忙"))?;
+        tokio::task::spawn_blocking(move || {
+            let _slot = slot;
+            let package =
+                ValidatedPackage::read(artifact.archive, Some(&instance.artifact_sha256), limits)
+                    .map_err(|_| AdminError::invalid("插件制品校验失败"))?;
+            let (_, _, state) = super::configuration::validate(&instance, package.manifest())?;
+            crate::adapter::observer::validate_bindings(package.manifest(), &instance.bindings)?;
+            crate::adapter::policy::validate_bindings(package.manifest(), &instance.bindings)?;
+            crate::adapter::frontend_authentication::validate_bindings(
+                package.manifest(),
+                &instance.bindings,
+            )?;
+            Ok(state)
+        })
+        .await
+        .map_err(|_| AdminError::internal("插件校验任务失败"))?
+    }
+    async fn prepare(
+        &self,
+        source_revision: Revision,
+        snapshot: PluginInstanceSnapshot,
+    ) -> Result<ExtensionSetReference, AdminError> {
+        let required_revision = snapshot.config_revision;
+        self.prepare_snapshot(source_revision, snapshot, Some(required_revision))
+            .await
+    }
+
+    async fn runtime_diagnostics(
+        &self,
+        snapshot: &PluginInstanceSnapshot,
+        published_revision: Option<u64>,
+        published: Option<&ExtensionSetReference>,
+    ) -> Option<BTreeMap<String, PluginInstanceRuntime>> {
+        let sets = {
+            let mut prepared = self.prepared.lock().await;
+            prepared.retain(|_, set| set.strong_count() > 0);
+            prepared
+                .values()
+                .filter_map(Weak::upgrade)
+                .collect::<Vec<_>>()
+        };
+        let open_restart_circuits = snapshot
+            .instances
+            .iter()
+            .filter(|instance| instance.enabled)
+            .filter_map(|instance| {
+                let identity =
+                    RestartIdentity::new(instance.id.clone(), instance_fingerprint(instance).ok()?);
+                self.restart_circuit_is_open(&identity)
+                    .then(|| instance.id.clone())
+            })
+            .collect::<BTreeSet<_>>();
+        let published_set = published
+            .and_then(|reference| sets.iter().find(|set| set.id == *reference.id()).cloned());
+        let published_ready = published.is_some_and(ExtensionSetReference::can_serve);
+        let preparation = self.preparation_diagnostic(snapshot.config_revision.get());
+        let retained = self.continuations.retained_by_instance();
+        let projection = InstanceRuntimeProjection {
+            target_revision: snapshot.config_revision,
+            published_revision,
+            published_ready,
+            published_set: published_set.as_deref(),
+            sets: &sets,
+            preparation: preparation.as_ref(),
+            retained: &retained,
+            open_restart_circuits: &open_restart_circuits,
+        };
+        Some(
+            snapshot
+                .instances
+                .iter()
+                .map(|instance| {
+                    let runtime = projection.project(instance);
+                    (instance.id.clone(), runtime)
+                })
+                .collect(),
+        )
+    }
+
+    async fn activate_state(
+        &self,
+        prepared: &ExtensionSetReference,
+        instance: &PluginInstance,
+    ) -> Result<(), AdminError> {
+        if !instance.enabled {
+            return Ok(());
+        }
+        let set = self.prepared_set(prepared).await?;
+        let prepared = set
+            .sessions
+            .iter()
+            .find(|prepared| {
+                prepared.instance_id == instance.id
+                    && prepared.artifact_sha256 == instance.artifact_sha256
+            })
+            .ok_or_else(|| AdminError::conflict("插件候选实例已失效"))?;
+        let owner = self
+            .state
+            .load_owner(prepared.private_state.owner_request(instance))
+            .await
+            .map_err(map_state_admin_error)?
+            .ok_or_else(|| AdminError::conflict("插件状态 fence 尚未提交"))?;
+        prepared.private_state.activate(owner);
+        Ok(())
+    }
+
+    async fn quiesce_instance(&self, instance_id: &str, artifact_sha256: &str, revision: Revision) {
+        let mut sessions = Vec::new();
+        for set in self
+            .prepared
+            .lock()
+            .await
+            .values()
+            .filter_map(Weak::upgrade)
+        {
+            for prepared in &set.sessions {
+                if prepared.instance_id == instance_id
+                    && prepared.artifact_sha256 == artifact_sha256
+                    && prepared.revision == revision
+                    && !sessions
+                        .iter()
+                        .any(|session| Arc::ptr_eq(session, &prepared.session))
+                {
+                    sessions.push(prepared.session.clone());
+                }
+            }
+        }
+        shutdown_sessions(sessions, Duration::from_secs(2)).await;
+    }
+
+    async fn migrate_state(
+        &self,
+        prepared: &ExtensionSetReference,
+        transition: PluginStateTransition,
+    ) -> Result<(), AdminError> {
+        self.run_state_migration(prepared, transition).await
+    }
+}
+
+struct InstanceRuntimeProjection<'a> {
+    target_revision: Revision,
+    published_revision: Option<u64>,
+    published_ready: bool,
+    published_set: Option<&'a PreparedSet>,
+    sets: &'a [Arc<PreparedSet>],
+    preparation: Option<&'a PreparationDiagnostic>,
+    retained: &'a BTreeMap<String, u32>,
+    open_restart_circuits: &'a BTreeSet<String>,
+}
+
+impl InstanceRuntimeProjection<'_> {
+    fn project(&self, expected: &PluginInstance) -> PluginInstanceRuntime {
+        let active = self.published_set.and_then(|set| {
+            set.sessions
+                .iter()
+                .find(|instance| instance.instance_id == expected.id)
+        });
+        let actual_matches = active.is_some_and(|instance| {
+            instance.revision == expected.revision
+                && instance.artifact_sha256 == expected.artifact_sha256
+        });
+        let target_is_published = self.published_revision == Some(self.target_revision.get());
+        let candidate_set = match self.preparation {
+            Some(PreparationDiagnostic::Prepared { set_id }) => Some(set_id.as_str()),
+            _ => None,
+        };
+        let published_set_id = self.published_set.map(|set| set.id.as_str());
+        let mut draining_revisions = BTreeSet::new();
+        for set in self.sets {
+            if Some(set.id.as_str()) == published_set_id || Some(set.id.as_str()) == candidate_set {
+                continue;
+            }
+            if let Some(instance) = set
+                .sessions
+                .iter()
+                .find(|instance| instance.instance_id == expected.id)
+                && instance.revision.get() < expected.revision.get()
+            {
+                draining_revisions.insert(instance.revision.get());
+            }
+        }
+        if !expected.enabled
+            && let Some(instance) = active
+            && instance.revision != expected.revision
+        {
+            draining_revisions.insert(instance.revision.get());
+        }
+
+        let retained_continuations = self.retained.get(&expected.id).copied().unwrap_or_default();
+        let diagnostic = active.map(|instance| instance.session.diagnostic());
+        let mut failure = None;
+        let status = if !expected.enabled {
+            if active.is_some() || !draining_revisions.is_empty() || retained_continuations > 0 {
+                PluginInstanceRuntimeStatus::Draining
+            } else {
+                PluginInstanceRuntimeStatus::Disabled
+            }
+        } else if target_is_published
+            && let Some(reason) = self
+                .published_set
+                .and_then(|set| set.failures.get(&expected.id))
+        {
+            failure = Some(reason.clone());
+            PluginInstanceRuntimeStatus::PreparationFailed
+        } else if self.open_restart_circuits.contains(&expected.id) {
+            failure = Some(runtime_failure(
+                "restart_circuit_open",
+                "插件实例连续异常退出，已暂停自动重启",
+            ));
+            PluginInstanceRuntimeStatus::Faulted
+        } else if actual_matches
+            && let Some(crate::rpc::RpcSessionDiagnostic::Failed { code, message }) = diagnostic
+        {
+            failure = Some(runtime_failure(code, message));
+            PluginInstanceRuntimeStatus::Faulted
+        } else if !target_is_published {
+            match self.preparation {
+                Some(PreparationDiagnostic::Preparing) => PluginInstanceRuntimeStatus::Preparing,
+                Some(PreparationDiagnostic::Failed(reason)) => {
+                    failure = Some(reason.clone());
+                    PluginInstanceRuntimeStatus::PreparationFailed
+                }
+                Some(PreparationDiagnostic::Prepared { .. }) | None => {
+                    PluginInstanceRuntimeStatus::AwaitingPublication
+                }
+            }
+        } else if !actual_matches {
+            failure = Some(runtime_failure(
+                "published_instance_mismatch",
+                "已发布插件实例与期望版本不一致",
+            ));
+            PluginInstanceRuntimeStatus::Blocked
+        } else {
+            match diagnostic {
+                Some(crate::rpc::RpcSessionDiagnostic::Ready) if self.published_ready => {
+                    PluginInstanceRuntimeStatus::Running
+                }
+                Some(crate::rpc::RpcSessionDiagnostic::Ready) => {
+                    failure = Some(runtime_failure(
+                        "published_set_unready",
+                        "同一发布集合中存在未就绪插件实例",
+                    ));
+                    PluginInstanceRuntimeStatus::Blocked
+                }
+                Some(crate::rpc::RpcSessionDiagnostic::Quiescing) => {
+                    PluginInstanceRuntimeStatus::Draining
+                }
+                Some(crate::rpc::RpcSessionDiagnostic::Failed { code, message }) => {
+                    failure = Some(runtime_failure(code, message));
+                    PluginInstanceRuntimeStatus::Faulted
+                }
+                None => {
+                    failure = Some(runtime_failure(
+                        "instance_not_published",
+                        "已发布集合缺少该插件实例",
+                    ));
+                    PluginInstanceRuntimeStatus::Blocked
+                }
+            }
+        };
+
+        PluginInstanceRuntime {
+            status,
+            actual_revision: active.map(|instance| instance.revision.get()),
+            actual_artifact_sha256: active.map(|instance| instance.artifact_sha256.clone()),
+            failure,
+            draining_revisions: draining_revisions.into_iter().collect(),
+            retained_continuations,
+        }
+    }
+}
+
+fn runtime_failure(code: &str, message: &str) -> PluginInstanceRuntimeFailure {
+    PluginInstanceRuntimeFailure {
+        code: code.to_owned(),
+        message: message.to_owned(),
+    }
+}
+
+fn runtime_failure_from_admin(error: &AdminError) -> PluginInstanceRuntimeFailure {
+    let code = match error.kind() {
+        AdminErrorKind::Invalid => "invalid",
+        AdminErrorKind::Unauthorized => "unauthorized",
+        AdminErrorKind::Forbidden => "forbidden",
+        AdminErrorKind::NotFound => "not_found",
+        AdminErrorKind::Conflict => "conflict",
+        AdminErrorKind::RateLimited => "rate_limited",
+        AdminErrorKind::BadGateway => "bad_gateway",
+        AdminErrorKind::UpstreamResultUnknown => "upstream_result_unknown",
+        AdminErrorKind::Unavailable => "unavailable",
+        AdminErrorKind::Internal => "internal",
+    };
+    runtime_failure(code, error.message())
+}
+
+async fn shutdown_sessions(sessions: Vec<Arc<RpcSession>>, grace: Duration) {
+    for session in &sessions {
+        session.quiesce();
+    }
+    let deadline = tokio::time::Instant::now() + grace;
+    futures::future::join_all(
+        sessions
+            .iter()
+            .map(|session| session.shutdown_until(deadline)),
+    )
+    .await;
+}
+
+fn map_state_admin_error(
+    error: gateway_admin::ports::plugins::PluginStateStoreError,
+) -> AdminError {
+    match error.kind() {
+        PluginStateStoreErrorKind::Invalid => AdminError::invalid("插件状态请求不合法"),
+        PluginStateStoreErrorKind::NotFound => AdminError::not_found("插件状态迁移不存在"),
+        PluginStateStoreErrorKind::Conflict => AdminError::conflict("插件状态版本或迁移游标冲突"),
+        PluginStateStoreErrorKind::Quota => AdminError::conflict("插件状态超过声明配额"),
+        PluginStateStoreErrorKind::PermissionDenied => {
+            AdminError::conflict("插件状态 fence 已失效")
+        }
+        PluginStateStoreErrorKind::Unavailable => AdminError::unavailable("插件状态存储暂不可用"),
+    }
+}
+
+impl ExtensionPreparationPort for PluginRuntime {
+    fn prepare(
+        &self,
+        revision: ConfigRevision,
+    ) -> BoxFuture<'_, Result<ExtensionSetReference, ExtensionPreparationError>> {
+        Box::pin(async move {
+            let snapshot = self
+                .store
+                .load_instances()
+                .await
+                .map_err(|_| ExtensionPreparationError)?;
+            if snapshot.config_revision.get() != revision.get() {
+                return Err(ExtensionPreparationError);
+            }
+            self.prepare_snapshot(snapshot.config_revision, snapshot, None)
+                .await
+                .map_err(|_| ExtensionPreparationError)
+        })
+    }
+}
+
+fn fingerprint(snapshot: &PluginInstanceSnapshot) -> Result<String, AdminError> {
+    let mut instances: Vec<_> = snapshot
+        .instances
+        .iter()
+        .filter(|instance| instance.enabled)
+        .collect();
+    instances.sort_by(|left, right| left.id.cmp(&right.id));
+    let mut hash = Sha256::new();
+    for instance in instances {
+        hash.update(instance_fingerprint(instance)?.as_bytes());
+    }
+    Ok(hex::encode(hash.finalize()))
+}
+
+fn instance_fingerprint(
+    instance: &gateway_admin::model::plugins::instances::PluginInstance,
+) -> Result<String, AdminError> {
+    let secrets: BTreeMap<_, _> = instance
+        .secrets
+        .iter()
+        .map(|(name, value)| (name, value.expose_secret()))
+        .collect();
+    let mut value = serde_json::json!({"id":instance.id,"artifact":instance.artifact_sha256,"revision":instance.revision.get(),"trusted":instance.trusted_process,"configuration":instance.configuration,"secrets":secrets,"grants":instance.grants,"bindings":instance.bindings});
+    // JSONB 恢复可以改变对象键顺序，不能因此替换已经准备好的同一配置。
+    value.sort_all_objects();
+    let bytes = serde_json::to_vec(&value).map_err(|_| AdminError::invalid("插件配置无法编码"))?;
+    Ok(hex::encode(Sha256::digest(bytes)))
+}
+
+fn continuation_authorization_fingerprint(
+    instance: &gateway_admin::model::plugins::instances::PluginInstance,
+    plugin_id: &str,
+    provider_id: &str,
+) -> Result<String, AdminError> {
+    let secret_digests: BTreeMap<_, _> = instance
+        .secrets
+        .iter()
+        .map(|(name, value)| {
+            (
+                name,
+                hex::encode(Sha256::digest(value.expose_secret().as_bytes())),
+            )
+        })
+        .collect();
+    let mut value = serde_json::json!({
+        "plugin": plugin_id,
+        "instance": instance.id,
+        "provider": provider_id,
+        "trusted": instance.trusted_process,
+        "configuration": instance.configuration,
+        "secret_digests": secret_digests,
+        "grants": instance.grants,
+        "bindings": instance.bindings,
+    });
+    value.sort_all_objects();
+    let bytes =
+        serde_json::to_vec(&value).map_err(|_| AdminError::invalid("插件续写授权无法编码"))?;
+    Ok(hex::encode(Sha256::digest(bytes)))
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/generation/restart_circuit.rs b/backend/crates/gateway-plugin/runtime/src/generation/restart_circuit.rs
new file mode 100644
index 000000000..b7ef54728
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/generation/restart_circuit.rs
@@ -0,0 +1,230 @@
+use std::{
+    collections::BTreeMap,
+    num::NonZeroUsize,
+    sync::{Arc, Mutex},
+    time::Duration,
+};
+
+use crate::rpc::RpcSessionLifecycle;
+
+const MAXIMUM_TRACKED_IDENTITIES: usize = 256;
+
+/// 原生插件重启熔断的保守初始参数；数值可调，但不代表已完成性能定标。
+#[derive(Debug, Clone, Copy)]
+pub struct PluginRestartCircuitConfig {
+    pub maximum_failures: NonZeroUsize,
+    pub stability_window: Duration,
+}
+
+impl Default for PluginRestartCircuitConfig {
+    fn default() -> Self {
+        Self {
+            maximum_failures: NonZeroUsize::new(3).unwrap_or(NonZeroUsize::MIN),
+            stability_window: Duration::from_secs(60),
+        }
+    }
+}
+
+#[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]
+pub(super) struct RestartIdentity {
+    instance_id: String,
+    fingerprint: String,
+}
+
+impl RestartIdentity {
+    pub(super) fn new(instance_id: String, fingerprint: String) -> Self {
+        Self {
+            instance_id,
+            fingerprint,
+        }
+    }
+}
+
+struct FailureBudget {
+    failures: usize,
+    latest_attempt: u64,
+    touched: u64,
+}
+
+#[derive(Clone)]
+struct AttemptFailure {
+    uptime: Duration,
+}
+
+#[derive(Default)]
+struct Attempt {
+    failure: Option<AttemptFailure>,
+    failure_applied: bool,
+}
+
+#[derive(Default)]
+struct RestartCircuitState {
+    budgets: BTreeMap<RestartIdentity, FailureBudget>,
+    attempts: BTreeMap<RestartIdentity, BTreeMap<u64, Attempt>>,
+    next_attempt: u64,
+    clock: u64,
+}
+
+pub(super) struct RestartCircuits {
+    config: PluginRestartCircuitConfig,
+    state: Mutex<RestartCircuitState>,
+}
+
+impl RestartCircuits {
+    pub(super) fn new(config: PluginRestartCircuitConfig) -> Arc<Self> {
+        Arc::new(Self {
+            config,
+            state: Mutex::new(RestartCircuitState::default()),
+        })
+    }
+
+    pub(super) fn begin(
+        self: &Arc<Self>,
+        identity: RestartIdentity,
+    ) -> Option<RpcSessionLifecycle> {
+        let attempt = {
+            let mut state = self
+                .state
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            if is_open(&state, &identity, self.config.maximum_failures) {
+                return None;
+            }
+            state.next_attempt = state.next_attempt.wrapping_add(1);
+            let attempt = state.next_attempt;
+            state
+                .attempts
+                .entry(identity.clone())
+                .or_default()
+                .insert(attempt, Attempt::default());
+            attempt
+        };
+        let failure_registry = Arc::clone(self);
+        let failure_identity = identity.clone();
+        let end_registry = Arc::clone(self);
+        Some(RpcSessionLifecycle::new(
+            move |uptime| {
+                failure_registry.record_failure(&failure_identity, attempt, uptime);
+            },
+            move || end_registry.end(&identity, attempt),
+        ))
+    }
+
+    pub(super) fn is_open(&self, identity: &RestartIdentity) -> bool {
+        let state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        is_open(&state, identity, self.config.maximum_failures)
+    }
+
+    fn record_failure(&self, identity: &RestartIdentity, attempt: u64, uptime: Duration) {
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let apply = state.attempts.get_mut(identity).and_then(|attempts| {
+            let current = attempts.keys().next_back().copied();
+            let entry = attempts.get_mut(&attempt)?;
+            if entry.failure.is_none() {
+                entry.failure = Some(AttemptFailure { uptime });
+            }
+            if current == Some(attempt) && !entry.failure_applied {
+                entry.failure_applied = true;
+                entry.failure.clone()
+            } else {
+                None
+            }
+        });
+        if let Some(failure) = apply {
+            self.apply_failure(&mut state, identity.clone(), attempt, failure);
+        }
+    }
+
+    fn end(&self, identity: &RestartIdentity, attempt: u64) {
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let mut restored = None;
+        let mut remove_identity = false;
+        if let Some(attempts) = state.attempts.get_mut(identity) {
+            let was_current = attempts.keys().next_back().copied() == Some(attempt);
+            attempts.remove(&attempt);
+            if was_current
+                && let Some((_, previous)) = attempts.last_key_value()
+                && !previous.failure_applied
+                && let Some(failure) = previous.failure.clone()
+            {
+                restored = attempts
+                    .keys()
+                    .next_back()
+                    .copied()
+                    .map(|attempt| (attempt, failure));
+            }
+            let previous = attempts.keys().next_back().copied();
+            if restored.is_some()
+                && let Some(previous) = previous.and_then(|key| attempts.get_mut(&key))
+            {
+                previous.failure_applied = true;
+            }
+            remove_identity = attempts.is_empty();
+        }
+        if remove_identity {
+            state.attempts.remove(identity);
+        }
+        if let Some((attempt, failure)) = restored {
+            self.apply_failure(&mut state, identity.clone(), attempt, failure);
+        }
+    }
+
+    fn apply_failure(
+        &self,
+        state: &mut RestartCircuitState,
+        identity: RestartIdentity,
+        attempt: u64,
+        failure: AttemptFailure,
+    ) {
+        state.clock = state.clock.wrapping_add(1);
+        let touched = state.clock;
+        let entry = state.budgets.entry(identity).or_insert(FailureBudget {
+            failures: 0,
+            latest_attempt: 0,
+            touched,
+        });
+        // 监督事实只向前推进；旧代次迟到故障不能清掉或重复累加更新代次的预算。
+        if attempt <= entry.latest_attempt {
+            return;
+        }
+        // 稳定运行过的 incarnation 先清掉旧预算，本次退出作为新周期的第一次故障。
+        if failure.uptime >= self.config.stability_window {
+            entry.failures = 0;
+        }
+        entry.failures = entry.failures.saturating_add(1);
+        entry.latest_attempt = attempt;
+        entry.touched = touched;
+        while state.budgets.len() > MAXIMUM_TRACKED_IDENTITIES {
+            let Some(identity) = state
+                .budgets
+                .iter()
+                .filter(|(identity, _)| !state.attempts.contains_key(*identity))
+                .min_by_key(|(_, entry)| entry.touched)
+                .map(|(identity, _)| identity.clone())
+            else {
+                break;
+            };
+            state.budgets.remove(&identity);
+        }
+    }
+}
+
+fn is_open(
+    state: &RestartCircuitState,
+    identity: &RestartIdentity,
+    maximum_failures: NonZeroUsize,
+) -> bool {
+    state
+        .budgets
+        .get(identity)
+        .is_some_and(|entry| entry.failures >= maximum_failures.get())
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/generation/worker.rs b/backend/crates/gateway-plugin/runtime/src/generation/worker.rs
new file mode 100644
index 000000000..04ea90455
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/generation/worker.rs
@@ -0,0 +1,259 @@
+//! 固定 Host worker 每轮取得 Core 已发布代次；候选和 CLI 不会派发维护。
+
+use std::{collections::BTreeMap, sync::Arc, time::Duration};
+
+use futures::{StreamExt as _, future::BoxFuture};
+use gateway_admin::{
+    model::{PageSize, Revision, provider_credentials::PluginAccountListQuery},
+    ports::provider::ProviderAdmin as _,
+};
+use gateway_core::{
+    account::ProviderAccountId,
+    runtime::RuntimeSnapshotHandle,
+    task::{
+        ScheduledTask, WorkerContribution, WorkerCycleContext, WorkerDefinitionError, WorkerId,
+        WorkerLeaseRequest, WorkerRegistration, WorkerRunnable, WorkerSchedule, WorkerTaskError,
+    },
+};
+use tokio::sync::Mutex;
+
+use super::PluginRuntime;
+use crate::adapter::provider::{MaintenanceKind, PluginProvider};
+
+const PAGE_SIZE: u16 = 16;
+const CONCURRENCY: usize = 4;
+const CYCLE_TIMEOUT: Duration = Duration::from_secs(150);
+
+#[derive(Clone)]
+pub(super) struct MaintenanceEntry {
+    pub instance_id: String,
+    pub artifact_sha256: String,
+    pub revision: Revision,
+    pub provider: Arc<PluginProvider>,
+}
+
+struct PluginMaintenanceTask {
+    runtime: Arc<PluginRuntime>,
+    snapshots: RuntimeSnapshotHandle,
+    kind: MaintenanceKind,
+    cursors: Mutex<BTreeMap<(String, u64), Option<ProviderAccountId>>>,
+    last_instance: Mutex<Option<String>>,
+}
+
+impl PluginRuntime {
+    /// 只返回任务定义；只有 Host 的统一启动入口可以执行任务。
+    pub fn worker_contributions(
+        self: &Arc<Self>,
+        snapshots: RuntimeSnapshotHandle,
+    ) -> Result<Vec<WorkerContribution>, WorkerDefinitionError> {
+        MaintenanceKind::ALL
+            .into_iter()
+            .map(|kind| {
+                let (worker_kind, owner, interval) = kind.worker();
+                let id = WorkerId::try_new(worker_kind, owner)?;
+                let lease_ttl = Duration::from_secs(15 * 60);
+                let schedule = WorkerSchedule::try_new(
+                    interval,
+                    Duration::from_secs(1),
+                    Duration::from_secs(60),
+                    lease_ttl,
+                    Duration::from_secs(5 * 60),
+                )?;
+                let lease = WorkerLeaseRequest::try_new(id.clone(), lease_ttl)?;
+                Ok(WorkerContribution::Registration(
+                    WorkerRegistration::try_new(
+                        id,
+                        WorkerRunnable::Scheduled {
+                            schedule,
+                            lease: Some(lease),
+                            task: Box::new(PluginMaintenanceTask {
+                                runtime: self.clone(),
+                                snapshots: snapshots.clone(),
+                                kind,
+                                cursors: Mutex::new(BTreeMap::new()),
+                                last_instance: Mutex::new(None),
+                            }),
+                        },
+                    )?,
+                ))
+            })
+            .collect()
+    }
+}
+
+impl ScheduledTask for PluginMaintenanceTask {
+    fn run_cycle(&self, context: WorkerCycleContext) -> BoxFuture<'_, Result<(), WorkerTaskError>> {
+        Box::pin(async move {
+            tokio::select! {
+                () = context.cancellation().cancelled() => Ok(()),
+                result = tokio::time::timeout(CYCLE_TIMEOUT, self.run(&context)) => {
+                    result.map_err(|_| WorkerTaskError::safe("插件维护轮次超时"))?
+                }
+            }
+        })
+    }
+}
+
+impl PluginMaintenanceTask {
+    async fn run(&self, context: &WorkerCycleContext) -> Result<(), WorkerTaskError> {
+        let snapshot = self.snapshots.acquire().map_err(|_| failed())?;
+        let Some(reference) = snapshot.extensions() else {
+            return Ok(());
+        };
+        let set = self
+            .runtime
+            .prepared_set(reference)
+            .await
+            .map_err(|_| failed())?;
+        let current = self
+            .runtime
+            .store
+            .load_instances()
+            .await
+            .map_err(|_| failed())?;
+        let mut entries: Vec<_> = set
+            .maintenance
+            .iter()
+            .filter(|entry| {
+                entry.provider.supports_maintenance(self.kind)
+                    && current.instances.iter().any(|instance| {
+                        instance.enabled
+                            && instance.id == entry.instance_id
+                            && instance.artifact_sha256 == entry.artifact_sha256
+                            && instance.revision == entry.revision
+                    })
+            })
+            .cloned()
+            .collect();
+        self.cursors.lock().await.retain(|(id, revision), _| {
+            entries
+                .iter()
+                .any(|entry| &entry.instance_id == id && entry.revision.get() == *revision)
+        });
+        if entries.is_empty() {
+            return Ok(());
+        }
+        if let Some(last) = self.last_instance.lock().await.as_ref()
+            && let Some(index) = entries.iter().position(|entry| &entry.instance_id == last)
+        {
+            let next = (index + 1) % entries.len();
+            entries.rotate_left(next);
+        }
+        let mut failed_instances = 0usize;
+        let mut first_failure = None;
+        for entry in entries {
+            if context.cancellation().is_cancelled() {
+                break;
+            }
+            // 整轮超时也从下一个实例继续，避免慢插件永久饿死后面的插件。
+            *self.last_instance.lock().await = Some(entry.instance_id.clone());
+            if let Err(error) = self.run_entry(&entry, context).await {
+                failed_instances += 1;
+                first_failure.get_or_insert(error);
+            }
+        }
+        if let Some(error) = first_failure {
+            tracing::warn!(worker = %context.worker(), failed_instances, "插件维护部分实例失败");
+            Err(error)
+        } else {
+            Ok(())
+        }
+    }
+
+    async fn run_entry(
+        &self,
+        entry: &MaintenanceEntry,
+        context: &WorkerCycleContext,
+    ) -> Result<(), WorkerTaskError> {
+        if !self.is_current(entry).await? {
+            return Ok(());
+        }
+        let task_id = format!(
+            "worker:{}:instance:{}:revision:{}:cycle:{}",
+            context.worker(),
+            entry.instance_id,
+            entry.revision.get(),
+            uuid::Uuid::new_v4()
+        );
+        if self.kind == MaintenanceKind::RequestProfiles {
+            return entry
+                .provider
+                .maintain_request_profiles(&task_id)
+                .await
+                .map_err(|error| provider_failure(&error));
+        }
+        let accounts = self.runtime.account_ports.upgrade().map_err(|_| failed())?;
+        let cursor_key = (entry.instance_id.clone(), entry.revision.get());
+        let cursor = self
+            .cursors
+            .lock()
+            .await
+            .get(&cursor_key)
+            .cloned()
+            .flatten();
+        let page = accounts
+            .list(PluginAccountListQuery {
+                provider_kind: Some(entry.provider.provider_kind().clone()),
+                cursor,
+                limit: PageSize::new(PAGE_SIZE).map_err(|_| failed())?,
+            })
+            .await
+            .map_err(|_| WorkerTaskError::safe("插件维护读取账号列表失败"))?;
+        let mut work = futures::stream::iter(page.accounts)
+            .map(|account| async {
+                // 获得并发位置后才检查；停用后不继续派发排队账号。
+                if !self.is_current(entry).await? {
+                    return Ok(());
+                }
+                match entry
+                    .provider
+                    .maintain_account(self.kind, account, accounts.as_ref(), &task_id)
+                    .await
+                {
+                    Ok(()) => Ok(()),
+                    Err(error)
+                        if error.kind()
+                            == gateway_admin::ports::provider::ProviderAdminErrorKind::Conflict =>
+                    {
+                        Ok(())
+                    }
+                    Err(error) => Err(provider_failure(&error)),
+                }
+            })
+            .buffer_unordered(CONCURRENCY);
+        let mut first_failure = None;
+        while let Some(result) = work.next().await {
+            if let Err(error) = result {
+                first_failure.get_or_insert(error);
+            }
+        }
+        self.cursors
+            .lock()
+            .await
+            .insert(cursor_key, page.next_cursor);
+        first_failure.map_or(Ok(()), Err)
+    }
+
+    async fn is_current(&self, entry: &MaintenanceEntry) -> Result<bool, WorkerTaskError> {
+        let snapshot = self
+            .runtime
+            .store
+            .load_instances()
+            .await
+            .map_err(|_| failed())?;
+        Ok(snapshot.instances.iter().any(|instance| {
+            instance.enabled
+                && instance.id == entry.instance_id
+                && instance.artifact_sha256 == entry.artifact_sha256
+                && instance.revision == entry.revision
+        }))
+    }
+}
+
+fn failed() -> WorkerTaskError {
+    WorkerTaskError::safe("插件维护未完成")
+}
+
+fn provider_failure(error: &gateway_admin::ports::provider::ProviderAdminError) -> WorkerTaskError {
+    WorkerTaskError::safe(format!("插件维护 Provider 操作失败：{:?}", error.kind()))
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/lib.rs b/backend/crates/gateway-plugin/runtime/src/lib.rs
new file mode 100644
index 000000000..3141fd03b
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/lib.rs
@@ -0,0 +1,19 @@
+//! 插件包校验与线协议适配；安装选择和授权事实由 Admin/Store 拥有。
+
+mod adapter;
+mod callback;
+mod contribution;
+mod generation;
+mod package;
+mod rpc;
+mod stream;
+
+pub use adapter::command_line::{PluginCommandError, PluginCommandOutput, PluginCommandSession};
+pub use generation::{
+    ContinuationDrainConfig, PluginRestartCircuitConfig, PluginRuntime, PluginRuntimeConfig,
+};
+pub use package::{
+    PackageError, PackageInspector, PackageLimits, PreparedPackage, ValidatedPackage,
+};
+pub use rpc::{CallbackHandler, RpcError, RpcLimits, RpcReply, RpcSession};
+pub use stream::RpcStream;
diff --git a/backend/crates/gateway-plugin/runtime/src/package/cache.rs b/backend/crates/gateway-plugin/runtime/src/package/cache.rs
new file mode 100644
index 000000000..5469071f1
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/package/cache.rs
@@ -0,0 +1,70 @@
+use std::{
+    fs,
+    path::{Path, PathBuf},
+    sync::Arc,
+};
+
+use super::{PackageError, ValidatedPackage};
+
+/// 每次准备创建独立私有目录；存储中的包体为权威，缓存不会被原地升级。
+pub struct PreparedPackage {
+    directory: tempfile::TempDir,
+    executable: PathBuf,
+    package: Arc<ValidatedPackage>,
+}
+
+impl ValidatedPackage {
+    pub fn prepare(
+        self: &Arc<Self>,
+        cache: &Path,
+        host_version: &semver::Version,
+    ) -> Result<PreparedPackage, PackageError> {
+        self.manifest
+            .package_for(host_version, std::env::consts::OS, std::env::consts::ARCH)?;
+        fs::create_dir_all(cache).map_err(|_| PackageError::Cache)?;
+        let directory = tempfile::Builder::new()
+            .prefix("plugin-")
+            .tempdir_in(cache)
+            .map_err(|_| PackageError::Cache)?;
+        for (path, data) in &self.files {
+            let target = directory.path().join(path);
+            fs::create_dir_all(target.parent().ok_or(PackageError::Path)?)
+                .map_err(|_| PackageError::Cache)?;
+            fs::write(&target, data).map_err(|_| PackageError::Cache)?;
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt as _;
+                let mode = if path == &self.manifest.main {
+                    0o700
+                } else {
+                    0o600
+                };
+                fs::set_permissions(&target, fs::Permissions::from_mode(mode))
+                    .map_err(|_| PackageError::Cache)?;
+            }
+        }
+        let executable = directory.path().join(&self.manifest.main);
+        Ok(PreparedPackage {
+            directory,
+            executable,
+            package: Arc::clone(self),
+        })
+    }
+}
+
+impl PreparedPackage {
+    #[must_use]
+    pub fn executable(&self) -> &Path {
+        &self.executable
+    }
+
+    #[must_use]
+    pub fn directory(&self) -> &Path {
+        self.directory.path()
+    }
+
+    #[must_use]
+    pub fn package(&self) -> &ValidatedPackage {
+        &self.package
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/package/compatibility.rs b/backend/crates/gateway-plugin/runtime/src/package/compatibility.rs
new file mode 100644
index 000000000..6799a8400
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/package/compatibility.rs
@@ -0,0 +1,72 @@
+use std::sync::OnceLock;
+
+use gateway_admin::model::{
+    AdminError,
+    plugins::{PluginCompatibilityRequirements, PluginHostCompatibility},
+};
+use gateway_plugin_sdk::Manifest;
+
+const HOST_COMPATIBILITY_JSON: &str = include_str!("../../plugin-host-compatibility.json");
+
+pub(crate) fn host_compatibility() -> Result<&'static PluginHostCompatibility, AdminError> {
+    static COMPATIBILITY: OnceLock<Result<PluginHostCompatibility, ()>> = OnceLock::new();
+    COMPATIBILITY
+        .get_or_init(|| {
+            let compatibility =
+                serde_json::from_str::<PluginHostCompatibility>(HOST_COMPATIBILITY_JSON)
+                    .map_err(|_| ())?;
+            compatibility.is_valid().then_some(compatibility).ok_or(())
+        })
+        .as_ref()
+        .map_err(|()| AdminError::internal("宿主插件兼容声明不合法"))
+}
+
+pub(crate) fn requirements(
+    manifest: &Manifest,
+) -> Result<PluginCompatibilityRequirements, AdminError> {
+    let package = manifest
+        .package
+        .as_ref()
+        .ok_or_else(|| AdminError::invalid("插件包缺少构建元数据"))?;
+    Ok(PluginCompatibilityRequirements {
+        host_version: manifest.engines.codex_proxy_rs.to_string(),
+        manifest_schema_version: manifest.manifest_version,
+        protocol_version: package.protocol_version,
+        capabilities: manifest
+            .contributes
+            .iter()
+            .map(|(capability, declaration)| Ok((identifier(*capability)?, declaration.version)))
+            .collect::<Result<_, AdminError>>()?,
+        permissions: manifest
+            .permissions
+            .iter()
+            .map(|permission| identifier(*permission))
+            .collect::<Result<_, _>>()?,
+    })
+}
+
+pub(crate) fn supports(manifest: &Manifest) -> Result<bool, AdminError> {
+    let compatibility = host_compatibility()?;
+    let requirements = requirements(manifest)?;
+    Ok(compatibility
+        .manifest_schema_versions
+        .contains(&requirements.manifest_schema_version)
+        && compatibility
+            .protocol_versions
+            .contains(&requirements.protocol_version)
+        && requirements
+            .capabilities
+            .iter()
+            .all(|(capability, version)| compatibility.supports_capability(capability, *version))
+        && requirements
+            .permissions
+            .iter()
+            .all(|permission| compatibility.supports_permission(permission)))
+}
+
+fn identifier(value: impl serde::Serialize) -> Result<String, AdminError> {
+    serde_json::to_value(value)
+        .ok()
+        .and_then(|value| value.as_str().map(str::to_owned))
+        .ok_or_else(|| AdminError::internal("插件描述转换失败"))
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/package/icon.rs b/backend/crates/gateway-plugin/runtime/src/package/icon.rs
new file mode 100644
index 000000000..2067f7d85
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/package/icon.rs
@@ -0,0 +1,164 @@
+use std::{collections::BTreeMap, io::Cursor};
+
+use gateway_admin::model::plugins::PluginIconTheme;
+use gateway_plugin_sdk::{Manifest, PluginIcon};
+use image::{
+    AnimationDecoder as _, Frames, ImageDecoder as _, ImageFormat, ImageReader, Limits,
+    codecs::{gif::GifDecoder, png::PngDecoder, webp::WebPDecoder},
+};
+
+use super::PackageError;
+
+const MAXIMUM_ICON_BYTES: usize = 512 * 1024;
+const MAXIMUM_ICON_DIMENSION: u32 = 4096;
+const MAXIMUM_ICON_ALLOCATION: u64 = 128 * 1024 * 1024;
+const MAXIMUM_ICON_FRAMES: usize = 256;
+const MAXIMUM_SVG_NODES: u32 = 16_384;
+
+pub(super) fn validate(
+    manifest: &Manifest,
+    files: &BTreeMap<String, Vec<u8>>,
+) -> Result<(), PackageError> {
+    let Some(icon) = &manifest.icon else {
+        return Ok(());
+    };
+    match icon {
+        PluginIcon::Path(path) => validate_path(manifest, files, path),
+        PluginIcon::Themed(variants) => {
+            validate_path(manifest, files, &variants.light)?;
+            validate_path(manifest, files, &variants.dark)
+        }
+    }
+}
+
+pub(super) fn path(manifest: &Manifest, theme: PluginIconTheme) -> Option<&str> {
+    match manifest.icon.as_ref()? {
+        PluginIcon::Path(path) => Some(path),
+        PluginIcon::Themed(variants) => Some(match theme {
+            PluginIconTheme::Light => &variants.light,
+            PluginIconTheme::Dark => &variants.dark,
+        }),
+    }
+}
+
+fn validate_path(
+    manifest: &Manifest,
+    files: &BTreeMap<String, Vec<u8>>,
+    path: &str,
+) -> Result<(), PackageError> {
+    let bytes = files.get(path).ok_or(PackageError::Archive)?;
+    if bytes.len() > MAXIMUM_ICON_BYTES {
+        return Err(PackageError::Limit);
+    }
+    if manifest.resources.get(path).map(String::as_str) == Some("image/svg+xml") {
+        return validate_svg(bytes);
+    }
+    // 扩展名与 MIME 的对应关系由 SDK 清单校验拥有，这里只核对实际编码与解码预算。
+    let expected = ImageFormat::from_path(path).map_err(|_| PackageError::Archive)?;
+    let mut reader = ImageReader::new(Cursor::new(bytes))
+        .with_guessed_format()
+        .map_err(|_| PackageError::Archive)?;
+    if reader.format() != Some(expected) {
+        return Err(PackageError::Archive);
+    }
+    let mut header = ImageReader::with_format(Cursor::new(bytes), expected);
+    header.limits(icon_limits());
+    let (width, height) = header.into_dimensions().map_err(map_image_error)?;
+    validate_dimensions(width, height)?;
+    // 动画逐帧检查但不收集帧，避免为了验证小图标保留整段动画的解码内存。
+    match expected {
+        ImageFormat::Png => {
+            let decoder = PngDecoder::with_limits(Cursor::new(bytes), icon_limits())
+                .map_err(map_image_error)?;
+            if decoder.is_apng().map_err(map_image_error)? {
+                return validate_frames(decoder.apng().map_err(map_image_error)?.into_frames());
+            }
+        }
+        ImageFormat::WebP => {
+            let decoder = WebPDecoder::new(Cursor::new(bytes)).map_err(map_image_error)?;
+            if decoder.has_animation() {
+                return validate_frames(decoder.into_frames());
+            }
+        }
+        ImageFormat::Gif => {
+            let mut decoder = GifDecoder::new(Cursor::new(bytes)).map_err(map_image_error)?;
+            decoder.set_limits(icon_limits()).map_err(map_image_error)?;
+            return validate_frames(decoder.into_frames());
+        }
+        _ => {}
+    }
+    reader.limits(icon_limits());
+    let image = reader.decode().map_err(map_image_error)?;
+    if image.width() != width || image.height() != height {
+        return Err(PackageError::Archive);
+    }
+    Ok(())
+}
+
+fn validate_svg(bytes: &[u8]) -> Result<(), PackageError> {
+    let text = std::str::from_utf8(bytes).map_err(|_| PackageError::Archive)?;
+    // 不解析 DTD 或外部实体；保留正常 SVG 样式与矢量内容，由图像上下文和接口 CSP 隔离主动内容。
+    let document = roxmltree::Document::parse_with_options(
+        text,
+        roxmltree::ParsingOptions {
+            nodes_limit: MAXIMUM_SVG_NODES,
+            ..Default::default()
+        },
+    )
+    .map_err(|error| match error {
+        roxmltree::Error::NodesLimitReached => PackageError::Limit,
+        _ => PackageError::Archive,
+    })?;
+    if !document
+        .root_element()
+        .has_tag_name(("http://www.w3.org/2000/svg", "svg"))
+        || document.descendants().any(|node| node.is_pi())
+    {
+        return Err(PackageError::Archive);
+    }
+    Ok(())
+}
+
+fn validate_dimensions(width: u32, height: u32) -> Result<(), PackageError> {
+    if width == 0
+        || height == 0
+        || width > MAXIMUM_ICON_DIMENSION
+        || height > MAXIMUM_ICON_DIMENSION
+    {
+        return Err(PackageError::Limit);
+    }
+    Ok(())
+}
+
+fn validate_frames(frames: Frames<'_>) -> Result<(), PackageError> {
+    let mut decoded_bytes = 0_u64;
+    let mut frame_count = 0;
+    for (index, frame) in frames.enumerate() {
+        if index >= MAXIMUM_ICON_FRAMES {
+            return Err(PackageError::Limit);
+        }
+        let frame = frame.map_err(map_image_error)?;
+        let buffer = frame.buffer();
+        validate_dimensions(buffer.width(), buffer.height())?;
+        decoded_bytes += buffer.as_raw().len() as u64;
+        if decoded_bytes > MAXIMUM_ICON_ALLOCATION {
+            return Err(PackageError::Limit);
+        }
+        frame_count += 1;
+    }
+    (frame_count > 0).then_some(()).ok_or(PackageError::Archive)
+}
+
+fn icon_limits() -> Limits {
+    let mut limits = Limits::default();
+    limits.max_alloc = Some(MAXIMUM_ICON_ALLOCATION);
+    limits
+}
+
+fn map_image_error(error: image::ImageError) -> PackageError {
+    if matches!(error, image::ImageError::Limits(_)) {
+        PackageError::Limit
+    } else {
+        PackageError::Archive
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/package/inspection.rs b/backend/crates/gateway-plugin/runtime/src/package/inspection.rs
new file mode 100644
index 000000000..e9c00e2e1
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/package/inspection.rs
@@ -0,0 +1,219 @@
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use gateway_admin::{
+    model::{
+        AdminError,
+        plugins::{
+            InspectedPluginArtifact, PluginArtifactIcon, PluginArtifactIconResource,
+            PluginArtifactIconVariants, PluginArtifactMetadata, PluginContribution,
+            PluginIconTheme,
+        },
+    },
+    ports::plugins::PluginPackageInspector,
+};
+
+use super::{PackageError, PackageLimits, ValidatedPackage};
+
+pub struct PackageInspector {
+    limits: PackageLimits,
+    host_version: semver::Version,
+    slots: Arc<tokio::sync::Semaphore>,
+}
+
+impl PackageInspector {
+    #[must_use]
+    pub fn new(limits: PackageLimits, host_version: semver::Version) -> Self {
+        Self {
+            limits,
+            host_version,
+            slots: Arc::new(tokio::sync::Semaphore::new(2)),
+        }
+    }
+}
+
+#[async_trait]
+impl PluginPackageInspector for PackageInspector {
+    fn permission_descriptions(
+        &self,
+        permissions: &[String],
+    ) -> Vec<gateway_admin::model::plugins::PluginPermissionDescription> {
+        permissions
+            .iter()
+            .map(|identifier| {
+                let permission = serde_json::from_value::<gateway_plugin_sdk::Permission>(
+                    serde_json::Value::String(identifier.clone()),
+                )
+                .ok();
+                gateway_admin::model::plugins::PluginPermissionDescription {
+                    permission: identifier.clone(),
+                    label: permission
+                        .map_or(identifier.as_str(), |value| value.label())
+                        .into(),
+                    description: permission.map_or("", |value| value.description()).into(),
+                }
+            })
+            .collect()
+    }
+
+    async fn inspect(
+        &self,
+        archive: Arc<[u8]>,
+        expected_sha256: Option<String>,
+    ) -> Result<InspectedPluginArtifact, AdminError> {
+        let permit = Arc::clone(&self.slots)
+            .try_acquire_owned()
+            .map_err(|_| AdminError::unavailable("插件包校验繁忙，请稍后重试"))?;
+        let limits = self.limits;
+        let host_version = self.host_version.clone();
+        tokio::task::spawn_blocking(move || {
+            // blocking 任务取消后仍可能运行，容量引用由任务持有直到真正结束。
+            let _permit = permit;
+            let package = ValidatedPackage::read(archive, expected_sha256.as_deref(), limits)
+                .map_err(inspection_error)?;
+            let manifest = package.manifest();
+            let target = manifest
+                .package_for(&host_version, std::env::consts::OS, std::env::consts::ARCH)
+                .map_err(|_| AdminError::invalid("插件不支持当前网关版本或平台"))?;
+            let metadata = PluginArtifactMetadata {
+                plugin_id: manifest
+                    .plugin_id()
+                    .map_err(|_| AdminError::invalid("插件身份不合法"))?,
+                version: manifest.version.to_string(),
+                name: manifest.name.clone(),
+                display_name: manifest.display_name.clone(),
+                publisher: manifest.publisher.clone(),
+                author: manifest.author.clone(),
+                description: manifest.description.clone(),
+                license: manifest.license.clone(),
+                sha256: package.digest().into(),
+                platforms: vec![format!(
+                    "{}-{}",
+                    target.target.os, target.target.architecture
+                )],
+                icon: manifest.icon.as_ref().map(|icon| match icon {
+                    gateway_plugin_sdk::PluginIcon::Path(path) => {
+                        PluginArtifactIcon::Path(path.clone())
+                    }
+                    gateway_plugin_sdk::PluginIcon::Themed(variants) => {
+                        PluginArtifactIcon::Themed(PluginArtifactIconVariants {
+                            light: variants.light.clone(),
+                            dark: variants.dark.clone(),
+                        })
+                    }
+                }),
+                contributes: manifest
+                    .contributes
+                    .iter()
+                    .map(|(capability, declaration)| {
+                        Ok((
+                            identifier(*capability)?,
+                            PluginContribution {
+                                id: declaration.id.clone(),
+                                version: declaration.version,
+                                stages: declaration
+                                    .stages
+                                    .iter()
+                                    .map(|stage| identifier(*stage))
+                                    .collect::<Result<_, _>>()?,
+                                input_formats: declaration.input_formats.clone(),
+                                output_formats: declaration.output_formats.clone(),
+                            },
+                        ))
+                    })
+                    .collect::<Result<_, _>>()?,
+                requested_permissions: manifest
+                    .permissions
+                    .iter()
+                    .map(identifier)
+                    .collect::<Result<_, _>>()?,
+                configuration_schema: manifest.configuration_schema.clone(),
+                secret_fields: manifest.secret_fields.iter().cloned().collect(),
+                state_namespaces: crate::callback::private_state::configuration(manifest)?
+                    .namespaces,
+            };
+            Ok(InspectedPluginArtifact {
+                metadata,
+                archive: package.archive(),
+            })
+        })
+        .await
+        .map_err(|_| AdminError::internal("插件包校验任务失败"))?
+    }
+
+    async fn icon(
+        &self,
+        archive: Arc<[u8]>,
+        expected_sha256: String,
+        theme: PluginIconTheme,
+    ) -> Result<Option<PluginArtifactIconResource>, AdminError> {
+        let permit = Arc::clone(&self.slots).acquire_owned();
+        let permit = tokio::time::timeout(Duration::from_secs(5), permit)
+            .await
+            .map_err(|_| AdminError::unavailable("插件图标读取繁忙，请稍后重试"))?
+            .map_err(|_| AdminError::unavailable("插件包校验繁忙，请稍后重试"))?;
+        let limits = self.limits;
+        tokio::task::spawn_blocking(move || {
+            let _permit = permit;
+            let package = ValidatedPackage::read(archive, Some(&expected_sha256), limits)
+                .map_err(icon_error)?;
+            let Some(path) = super::icon::path(package.manifest(), theme) else {
+                return Ok(None);
+            };
+            let content_type = package
+                .manifest()
+                .resources
+                .get(path)
+                .cloned()
+                .ok_or_else(|| AdminError::invalid("插件图标资源声明无效"))?;
+            let body = package
+                .resource(path)
+                .map(<[u8]>::to_vec)
+                .ok_or_else(|| AdminError::invalid("插件图标资源缺失"))?;
+            Ok(Some(PluginArtifactIconResource { content_type, body }))
+        })
+        .await
+        .map_err(|_| AdminError::internal("插件图标读取任务失败"))?
+    }
+
+    async fn compatibility(
+        &self,
+        archive: Arc<[u8]>,
+        expected_sha256: String,
+    ) -> Result<gateway_admin::model::plugins::PluginCompatibilityRequirements, AdminError> {
+        let permit = Arc::clone(&self.slots)
+            .try_acquire_owned()
+            .map_err(|_| AdminError::unavailable("插件包校验繁忙，请稍后重试"))?;
+        let limits = self.limits;
+        tokio::task::spawn_blocking(move || {
+            let _permit = permit;
+            let package = ValidatedPackage::read(archive, Some(&expected_sha256), limits)
+                .map_err(inspection_error)?;
+            super::compatibility::requirements(package.manifest())
+        })
+        .await
+        .map_err(|_| AdminError::internal("插件兼容性检查任务失败"))?
+    }
+}
+
+fn inspection_error(error: PackageError) -> AdminError {
+    match error {
+        PackageError::Manifest(gateway_plugin_sdk::ManifestError::Incompatible) => {
+            AdminError::invalid("插件清单或协议版本不兼容，请使用当前 SDK 重新构建")
+        }
+        _ => AdminError::invalid("插件包格式、兼容性或摘要校验失败"),
+    }
+}
+
+fn icon_error(error: PackageError) -> AdminError {
+    tracing::warn!(error = ?error, "installed plugin icon validation failed");
+    AdminError::unavailable("插件图标读取失败")
+}
+
+fn identifier(value: impl serde::Serialize) -> Result<String, AdminError> {
+    serde_json::to_value(value)
+        .ok()
+        .and_then(|value| value.as_str().map(str::to_owned))
+        .ok_or_else(|| AdminError::internal("插件描述转换失败"))
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/package/mod.rs b/backend/crates/gateway-plugin/runtime/src/package/mod.rs
new file mode 100644
index 000000000..b7895c50b
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/package/mod.rs
@@ -0,0 +1,10 @@
+mod cache;
+mod compatibility;
+mod icon;
+mod inspection;
+mod validation;
+
+pub use cache::PreparedPackage;
+pub(crate) use compatibility::supports as host_supports;
+pub use inspection::PackageInspector;
+pub use validation::{PackageError, PackageLimits, ValidatedPackage};
diff --git a/backend/crates/gateway-plugin/runtime/src/package/validation.rs b/backend/crates/gateway-plugin/runtime/src/package/validation.rs
new file mode 100644
index 000000000..3838a669f
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/package/validation.rs
@@ -0,0 +1,157 @@
+use std::{collections::BTreeMap, io::Read, sync::Arc};
+
+use flate2::read::MultiGzDecoder;
+use gateway_plugin_sdk::{Manifest, ManifestError, valid_package_path};
+use sha2::{Digest as _, Sha256};
+
+#[derive(Debug, Clone, Copy)]
+pub struct PackageLimits {
+    pub compressed_bytes: usize,
+    pub expanded_bytes: usize,
+    pub file_count: usize,
+    pub manifest_bytes: usize,
+}
+
+impl Default for PackageLimits {
+    fn default() -> Self {
+        Self {
+            compressed_bytes: 32 * 1024 * 1024,
+            expanded_bytes: 128 * 1024 * 1024,
+            file_count: 256,
+            manifest_bytes: 64 * 1024,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+pub enum PackageError {
+    #[error("plugin package exceeds configured limits")]
+    Limit,
+    #[error("plugin package archive is invalid")]
+    Archive,
+    #[error("plugin package digest does not match")]
+    Digest,
+    #[error("plugin package contains an unsafe or duplicate path")]
+    Path,
+    #[error(transparent)]
+    Manifest(#[from] ManifestError),
+    #[error("plugin artifact cache is unavailable")]
+    Cache,
+}
+
+/// 校验后的不可变字节；无需先把未可信压缩包解压到宿主文件系统。
+#[derive(Clone)]
+pub struct ValidatedPackage {
+    pub(super) manifest: Manifest,
+    pub(super) digest: String,
+    pub(super) archive: Arc<[u8]>,
+    pub(super) files: BTreeMap<String, Vec<u8>>,
+}
+
+impl ValidatedPackage {
+    /// 仅供已冻结资源声明读取校验后的字节，不暴露缓存路径或任意文件读取。
+    pub(crate) fn resource(&self, path: &str) -> Option<&[u8]> {
+        self.manifest
+            .resources
+            .contains_key(path)
+            .then(|| self.files.get(path).map(Vec::as_slice))
+            .flatten()
+    }
+
+    pub fn read(
+        archive: Arc<[u8]>,
+        expected_sha256: Option<&str>,
+        limits: PackageLimits,
+    ) -> Result<Self, PackageError> {
+        if archive.len() > limits.compressed_bytes {
+            return Err(PackageError::Limit);
+        }
+        let digest = hex::encode(Sha256::digest(&archive));
+        if expected_sha256.is_some_and(|expected| expected != digest) {
+            return Err(PackageError::Digest);
+        }
+
+        // 先限制整个解压字节流，连 PAX 元数据、目录、padding 和尾部数据也纳入预算。
+        let expanded_limit =
+            u64::try_from(limits.expanded_bytes).map_err(|_| PackageError::Limit)?;
+        let mut expanded = Vec::new();
+        MultiGzDecoder::new(archive.as_ref())
+            .take(expanded_limit.saturating_add(1))
+            .read_to_end(&mut expanded)
+            .map_err(|_| PackageError::Archive)?;
+        if expanded.len() > limits.expanded_bytes {
+            return Err(PackageError::Limit);
+        }
+        let mut tar = tar::Archive::new(expanded.as_slice());
+        let mut files = BTreeMap::new();
+        let mut folded_paths = std::collections::BTreeSet::new();
+        let mut total = 0usize;
+        for entry in tar.entries().map_err(|_| PackageError::Archive)? {
+            let mut entry = entry.map_err(|_| PackageError::Archive)?;
+            if !entry.header().entry_type().is_file() {
+                return Err(PackageError::Path);
+            }
+            let path = std::str::from_utf8(&entry.path_bytes())
+                .map_err(|_| PackageError::Path)?
+                .to_owned();
+            if !valid_package_path(&path) || !folded_paths.insert(path.to_ascii_lowercase()) {
+                return Err(PackageError::Path);
+            }
+            if files.len() > limits.file_count {
+                return Err(PackageError::Limit);
+            }
+            let size = usize::try_from(entry.size()).map_err(|_| PackageError::Limit)?;
+            total = total.checked_add(size).ok_or(PackageError::Limit)?;
+            if total > limits.expanded_bytes
+                || (path == "plugin.json" && size > limits.manifest_bytes)
+            {
+                return Err(PackageError::Limit);
+            }
+            let mut data = Vec::new();
+            entry
+                .read_to_end(&mut data)
+                .map_err(|_| PackageError::Archive)?;
+            if data.len() != size {
+                return Err(PackageError::Archive);
+            }
+            files.insert(path, data);
+        }
+        let manifest_bytes = files.remove("plugin.json").ok_or(PackageError::Archive)?;
+        let manifest: Manifest =
+            serde_json::from_slice(&manifest_bytes).map_err(|_| PackageError::Archive)?;
+        manifest.validate()?;
+        // 源清单可以省略 package，但归档安装入口必须只接受构建后的单平台包。
+        let package = manifest.package.as_ref().ok_or(ManifestError::Invalid)?;
+        if files.len() != package.files.len() || files.len() > limits.file_count {
+            return Err(PackageError::Archive);
+        }
+        for (path, expected) in &package.files {
+            let data = files.get(path).ok_or(PackageError::Archive)?;
+            if hex::encode(Sha256::digest(data)) != *expected {
+                return Err(PackageError::Digest);
+            }
+        }
+        super::icon::validate(&manifest, &files)?;
+        Ok(Self {
+            manifest,
+            digest,
+            archive,
+            files,
+        })
+    }
+
+    #[must_use]
+    pub fn manifest(&self) -> &Manifest {
+        &self.manifest
+    }
+
+    #[must_use]
+    pub fn digest(&self) -> &str {
+        &self.digest
+    }
+
+    #[must_use]
+    pub fn archive(&self) -> Arc<[u8]> {
+        Arc::clone(&self.archive)
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/rpc/dispatch.rs b/backend/crates/gateway-plugin/runtime/src/rpc/dispatch.rs
new file mode 100644
index 000000000..facf0da47
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/rpc/dispatch.rs
@@ -0,0 +1,240 @@
+use std::sync::Arc;
+
+use gateway_plugin_sdk::{
+    ErrorCode, Frame, Message, Permission, PluginFault, Stage,
+    client::{read_frame, write_frame},
+};
+use tokio::{
+    io::{AsyncRead, AsyncWrite},
+    sync::{mpsc, oneshot},
+};
+
+use super::session::{CallbackHandler, RpcError, RpcLimits, RpcReply, Shared};
+
+#[expect(
+    clippy::too_many_arguments,
+    reason = "双向资源在一个入口交给独立读写任务，不引入重复连接状态"
+)]
+pub(super) fn start<W, R>(
+    writer: W,
+    reader: R,
+    data: mpsc::Receiver<Frame>,
+    control: mpsc::Receiver<Frame>,
+    shared: Arc<Shared>,
+    callbacks: Arc<dyn CallbackHandler>,
+    permissions: Vec<Permission>,
+    limits: RpcLimits,
+) where
+    W: AsyncWrite + Unpin + Send + 'static,
+    R: AsyncRead + Unpin + Send + 'static,
+{
+    tokio::spawn(write_loop(
+        writer,
+        data,
+        control,
+        Arc::clone(&shared),
+        limits.maximum_frame_bytes,
+    ));
+    tokio::spawn(read_loop(reader, shared, callbacks, permissions, limits));
+}
+
+async fn write_loop<W: AsyncWrite + Unpin>(
+    mut writer: W,
+    mut data: mpsc::Receiver<Frame>,
+    mut control: mpsc::Receiver<Frame>,
+    shared: Arc<Shared>,
+    maximum: usize,
+) {
+    let mut stopped = shared.stopped.subscribe();
+    loop {
+        if *stopped.borrow() {
+            return;
+        }
+        let frame = tokio::select! {
+            biased;
+            _ = stopped.changed() => return,
+            frame = control.recv() => frame,
+            frame = data.recv() => frame,
+        };
+        let Some(frame) = frame else {
+            shared.fail(RpcError::Closed);
+            return;
+        };
+        // 撤销尚未发送的调用时丢弃排队帧；已开始写入的 Call 必须先于 Cancel。
+        if let Message::Call { id, .. } = &frame.message {
+            if !shared.mark_transmitted(*id) {
+                continue;
+            }
+        } else if let Message::Credit { id, .. } = &frame.message
+            && shared.context(*id).is_none()
+        {
+            continue;
+        }
+        let written = tokio::select! {
+            biased;
+            _ = stopped.changed() => return,
+            result = write_frame(&mut writer, &frame, maximum) => result,
+        };
+        if written.is_err() {
+            shared.fail(RpcError::Closed);
+            return;
+        }
+    }
+}
+
+async fn read_loop<R: AsyncRead + Unpin>(
+    mut reader: R,
+    shared: Arc<Shared>,
+    callbacks: Arc<dyn CallbackHandler>,
+    permissions: Vec<Permission>,
+    limits: RpcLimits,
+) {
+    let mut stopped = shared.stopped.subscribe();
+    let mut last_callback = 0;
+    loop {
+        if *stopped.borrow() {
+            return;
+        }
+        let frame = tokio::select! {
+            biased;
+            _ = stopped.changed() => return,
+            frame = read_frame(&mut reader, limits.maximum_frame_bytes) => frame,
+        };
+        let Ok(frame) = frame else {
+            shared.fail(RpcError::Closed);
+            return;
+        };
+        let result = match frame.message {
+            Message::Cancelled { id } if frame.payload.is_empty() => {
+                shared.acknowledge_cancellation(id)
+            }
+            Message::Stream { id, sequence } => shared.stream_chunk(id, sequence, frame.payload),
+            Message::End { id, error } if frame.payload.is_empty() => shared.stream_end(id, error),
+            Message::Result { id, result } => shared.finish(
+                id,
+                Ok(RpcReply {
+                    result,
+                    payload: frame.payload,
+                }),
+            ),
+            Message::Error { id, error } if frame.payload.is_empty() => {
+                shared.finish(id, Err(RpcError::Remote(error)))
+            }
+            Message::Callback {
+                id,
+                parent_id,
+                method,
+                params,
+            } => {
+                if id == 0 || id % 2 != 0 || id <= last_callback {
+                    Err(RpcError::Protocol)
+                } else if let Some(context) = shared.context(parent_id) {
+                    last_callback = id;
+                    if !callback_allowed(&method, context.stage, &permissions) {
+                        shared.send_control(Frame::control(Message::Error {
+                            id,
+                            error: PluginFault::new(
+                                ErrorCode::PermissionDenied,
+                                "callback is not authorized in this stage",
+                            ),
+                        }));
+                    } else if let Some(permit) = shared.try_callback_slot() {
+                        let handler = Arc::clone(&callbacks);
+                        let response = Arc::clone(&shared);
+                        let (ready, started) = oneshot::channel();
+                        let task = tokio::spawn(async move {
+                            // 先把任务归属登记到父调用，再允许执行宿主操作。
+                            if started.await.is_err() {
+                                return;
+                            }
+                            let result = handler.call(context, method, params, frame.payload).await;
+                            let reply = match result {
+                                Ok(reply) => Frame {
+                                    message: Message::Result {
+                                        id,
+                                        result: reply.result,
+                                    },
+                                    payload: reply.payload,
+                                },
+                                Err(error) => Frame::control(Message::Error { id, error }),
+                            };
+                            response.send_control(reply);
+                            drop(permit);
+                        });
+                        if shared.track_callback(parent_id, task.abort_handle()) {
+                            let _ = ready.send(());
+                        }
+                    } else {
+                        shared.send_control(Frame::control(Message::Error {
+                            id,
+                            error: PluginFault::new(
+                                ErrorCode::Capacity,
+                                "callback capacity is exhausted",
+                            ),
+                        }));
+                    }
+                    Ok(())
+                } else if shared.is_cancelling(parent_id) {
+                    last_callback = id;
+                    shared.send_control(Frame::control(Message::Error {
+                        id,
+                        error: PluginFault::new(ErrorCode::Cancelled, "parent call was cancelled"),
+                    }));
+                    Ok(())
+                } else {
+                    Err(RpcError::Protocol)
+                }
+            }
+            _ => Err(RpcError::Protocol),
+        };
+        if let Err(error) = result {
+            shared.fail(error);
+            return;
+        }
+    }
+}
+
+fn callback_allowed(method: &str, stage: Stage, permissions: &[Permission]) -> bool {
+    // 未登录端点只服务声明的公开内容，不能借宿主回调取得管理资源。
+    if stage == Stage::PublicManagement {
+        return false;
+    }
+    if method == "host.log" {
+        return true;
+    }
+    if matches!(stage, Stage::Registration | Stage::Configuration) {
+        return false;
+    }
+    if matches!(
+        method,
+        "host.state.get" | "host.state.put" | "host.state.delete"
+    ) {
+        return true;
+    }
+    if matches!(
+        method,
+        gateway_plugin_sdk::call::middleware::NEXT_METHOD
+            | gateway_plugin_sdk::call::middleware::BODY_READ_METHOD
+            | gateway_plugin_sdk::call::middleware::BODY_CLOSE_METHOD
+    ) {
+        return matches!(stage, Stage::Request | Stage::Attempt);
+    }
+    let permission = match method {
+        "host.http.do"
+        | "host.http.do_stream"
+        | "host.http.stream_read"
+        | "host.http.stream_close" => Permission::Network,
+        "host.model.execute"
+        | "host.model.execute_stream"
+        | "host.model.stream_read"
+        | "host.model.stream_close"
+        | "host.models.list"
+        | "host.keys.list" => Permission::Models,
+        "host.auth.list" | "host.auth.get_runtime" | "host.auth.get" | "host.auth.save" => {
+            Permission::Accounts
+        }
+        "host.affinity.lookup" => Permission::Requests,
+        _ => return false,
+    };
+    permissions.contains(&permission)
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/rpc/mod.rs b/backend/crates/gateway-plugin/runtime/src/rpc/mod.rs
new file mode 100644
index 000000000..53da11e68
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/rpc/mod.rs
@@ -0,0 +1,5 @@
+mod dispatch;
+mod session;
+
+pub use session::{CallbackHandler, RpcError, RpcLimits, RpcReply, RpcSession};
+pub(crate) use session::{RpcSessionDiagnostic, RpcSessionLifecycle, Shared};
diff --git a/backend/crates/gateway-plugin/runtime/src/rpc/session.rs b/backend/crates/gateway-plugin/runtime/src/rpc/session.rs
new file mode 100644
index 000000000..fa566229d
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/rpc/session.rs
@@ -0,0 +1,894 @@
+use std::{
+    collections::BTreeMap,
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicBool, Ordering},
+    },
+    time::{Duration, Instant},
+};
+
+use futures::future::BoxFuture;
+use gateway_host::process::{ProcessControl, ProcessSpec, ProcessStartError, ProcessSupervisor};
+use gateway_plugin_sdk::{
+    CallContext, Frame, Handshake, Message, PROTOCOL_VERSION, PluginFault,
+    client::{read_frame, write_frame},
+};
+use tokio::sync::{Mutex as AsyncMutex, Semaphore, mpsc, oneshot, watch};
+
+use crate::{PreparedPackage, RpcStream, stream::StreamIngress};
+
+use super::dispatch;
+
+#[derive(Debug, Clone, Copy)]
+pub struct RpcLimits {
+    pub maximum_frame_bytes: usize,
+    pub maximum_calls: usize,
+    pub maximum_callbacks: usize,
+    pub handshake_timeout: Duration,
+    pub maximum_call_timeout: Duration,
+    pub maximum_stderr_bytes: usize,
+}
+
+impl Default for RpcLimits {
+    fn default() -> Self {
+        Self {
+            maximum_frame_bytes: 1024 * 1024,
+            maximum_calls: 16,
+            maximum_callbacks: 16,
+            handshake_timeout: Duration::from_secs(5),
+            maximum_call_timeout: Duration::from_secs(120),
+            maximum_stderr_bytes: 64 * 1024,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+pub enum RpcError {
+    #[error("plugin process could not be started: {0}")]
+    Start(#[source] ProcessStartError),
+    #[error("plugin handshake does not match the prepared instance")]
+    Handshake,
+    #[error("plugin protocol is invalid")]
+    Protocol,
+    #[error("plugin process or transport has stopped")]
+    Closed,
+    #[error("plugin call exceeded its deadline")]
+    Timeout,
+    #[error("plugin session was cancelled")]
+    Cancelled,
+    #[error("plugin call capacity is exhausted")]
+    Capacity,
+    #[error("plugin call context is invalid")]
+    Context,
+    #[error("plugin returned an error")]
+    Remote(PluginFault),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum RpcSessionDiagnostic {
+    Ready,
+    Quiescing,
+    Failed {
+        code: &'static str,
+        message: &'static str,
+    },
+}
+
+pub(crate) struct RpcSessionLifecycle {
+    failure: Arc<dyn Fn(Duration) + Send + Sync>,
+    end: Option<Box<dyn FnOnce() + Send + Sync>>,
+}
+
+impl RpcSessionLifecycle {
+    pub(crate) fn new(
+        failure: impl Fn(Duration) + Send + Sync + 'static,
+        end: impl FnOnce() + Send + Sync + 'static,
+    ) -> Self {
+        Self {
+            failure: Arc::new(failure),
+            end: Some(Box::new(end)),
+        }
+    }
+
+    fn fail(&self, uptime: Duration) {
+        (self.failure)(uptime);
+    }
+}
+
+impl Drop for RpcSessionLifecycle {
+    fn drop(&mut self) {
+        if let Some(end) = self.end.take() {
+            end();
+        }
+    }
+}
+
+/// 不派生 Debug，防止原始请求、凭据或模型输出进入宿主诊断。
+pub struct RpcReply {
+    pub result: serde_json::Value,
+    pub payload: Vec<u8>,
+}
+
+/// 具体回调在领域适配器校验账号、出站与执行身份；上下文只取自宿主在途调用表。
+pub trait CallbackHandler: Send + Sync {
+    /// 在 Call 可见之前建立资源范围；不得执行 I/O 或调用 RPC。
+    fn begin(&self, _context: &CallContext) {}
+
+    /// 调用结束或取消时立即撤销其句柄；实现必须幂等且不能阻塞。
+    fn finish(&self, _context: &CallContext) {}
+
+    fn call(
+        &self,
+        context: CallContext,
+        method: String,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+    ) -> BoxFuture<'static, Result<RpcReply, PluginFault>>;
+}
+
+pub struct RpcSession {
+    shared: Arc<Shared>,
+    handshake: Handshake,
+    data: mpsc::Sender<Frame>,
+    slots: Arc<Semaphore>,
+    next_call: AsyncMutex<u64>,
+    limits: RpcLimits,
+    callbacks: Arc<dyn CallbackHandler>,
+    _lifecycle: Option<RpcSessionLifecycle>,
+}
+
+pub(crate) struct Shared {
+    state: Mutex<State>,
+    started_at: Instant,
+    expected_stop: AtomicBool,
+    failure_observer: Option<Arc<dyn Fn(Duration) + Send + Sync>>,
+    pub control: mpsc::Sender<Frame>,
+    pub process: ProcessControl,
+    pub stopped: watch::Sender<bool>,
+    callback_slots: Arc<Semaphore>,
+}
+
+struct State {
+    failure: Option<RpcError>,
+    calls: BTreeMap<u64, PendingCall>,
+}
+
+struct PendingCall {
+    handler: Arc<dyn CallbackHandler>,
+    transmitted: bool,
+    cancellation: Option<RpcError>,
+    context: CallContext,
+    result: Option<oneshot::Sender<Result<RpcReply, RpcError>>>,
+    stream: Option<StreamIngress>,
+    callbacks: Vec<tokio::task::AbortHandle>,
+}
+
+impl PendingCall {
+    fn finish(mut self, result: Result<RpcReply, RpcError>) {
+        for callback in self.callbacks.drain(..) {
+            callback.abort();
+        }
+        if let Some(stream) = self.stream.take() {
+            stream.finish(result.as_ref().map(|_| ()).map_err(Clone::clone));
+        }
+        if let Some(sender) = self.result.take() {
+            let _ = sender.send(result);
+        }
+    }
+}
+
+impl Drop for PendingCall {
+    fn drop(&mut self) {
+        self.handler.finish(&self.context);
+    }
+}
+
+impl Shared {
+    fn state(&self) -> std::sync::MutexGuard<'_, State> {
+        self.state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+    }
+
+    pub fn fail(&self, error: RpcError) {
+        let uptime = self.started_at.elapsed();
+        let (calls, failure_observer) = {
+            let mut state = self.state();
+            if state.failure.is_some() {
+                return;
+            }
+            state.failure = Some(error.clone());
+            let observer = (!self.expected_stop.load(Ordering::Acquire))
+                .then(|| self.failure_observer.clone())
+                .flatten();
+            (std::mem::take(&mut state.calls), observer)
+        };
+        for call in calls.into_values() {
+            call.finish(Err(error.clone()));
+        }
+        if let Some(observer) = failure_observer {
+            observer(uptime);
+        }
+        self.stopped.send_replace(true);
+        self.process.stop();
+    }
+
+    fn expect_stop(&self) {
+        self.expected_stop.store(true, Ordering::Release);
+    }
+
+    pub fn finish(&self, id: u64, result: Result<RpcReply, RpcError>) -> Result<(), RpcError> {
+        let mut state = self.state();
+        let call = state.calls.get_mut(&id).ok_or(RpcError::Protocol)?;
+        if call.cancellation.is_some() {
+            return Ok(());
+        }
+        if call.stream.is_some() && result.is_ok() {
+            let initial = call.result.take().ok_or(RpcError::Protocol)?;
+            let _ = initial.send(result);
+        } else {
+            let pending = state.calls.remove(&id).ok_or(RpcError::Protocol)?;
+            drop(state);
+            pending.finish(result);
+        }
+        Ok(())
+    }
+
+    pub fn stream_chunk(&self, id: u64, sequence: u64, payload: Vec<u8>) -> Result<(), RpcError> {
+        let mut state = self.state();
+        let call = state.calls.get_mut(&id).ok_or(RpcError::Protocol)?;
+        if call.cancellation.is_some() {
+            return Ok(());
+        }
+        if call.result.is_some() {
+            return Err(RpcError::Protocol);
+        }
+        call.stream
+            .as_mut()
+            .ok_or(RpcError::Protocol)?
+            .receive(sequence, payload)
+    }
+
+    pub fn stream_end(&self, id: u64, error: Option<PluginFault>) -> Result<(), RpcError> {
+        let mut state = self.state();
+        if state
+            .calls
+            .get(&id)
+            .is_some_and(|call| call.cancellation.is_some())
+        {
+            return Ok(());
+        }
+        let call = state.calls.remove(&id).ok_or(RpcError::Protocol)?;
+        drop(state);
+        if call.stream.is_none() || call.result.is_some() {
+            call.finish(Err(RpcError::Protocol));
+            return Err(RpcError::Protocol);
+        }
+        let result = error.map_or_else(
+            || {
+                Ok(RpcReply {
+                    result: serde_json::Value::Null,
+                    payload: Vec::new(),
+                })
+            },
+            |error| Err(RpcError::Remote(error)),
+        );
+        call.finish(result);
+        Ok(())
+    }
+
+    pub fn release_stream_credit(&self, id: u64, bytes: u32) -> Result<(), RpcError> {
+        let mut state = self.state();
+        // 完成后仍可消费已排队数据，无须再给已关闭的流发信用。
+        let Some(call) = state.calls.get_mut(&id) else {
+            return Ok(());
+        };
+        call.stream
+            .as_mut()
+            .ok_or(RpcError::Protocol)?
+            .release(bytes)?;
+        drop(state);
+        self.send_control(Frame::control(Message::Credit {
+            id,
+            bytes,
+            frames: 1,
+        }));
+        Ok(())
+    }
+
+    pub fn context(&self, id: u64) -> Option<CallContext> {
+        self.state()
+            .calls
+            .get(&id)
+            .filter(|call| call.cancellation.is_none())
+            .map(|call| call.context.clone())
+    }
+
+    pub fn is_cancelling(&self, id: u64) -> bool {
+        self.state()
+            .calls
+            .get(&id)
+            .is_some_and(|call| call.cancellation.is_some())
+    }
+
+    pub fn mark_transmitted(&self, id: u64) -> bool {
+        let mut state = self.state();
+        let Some(call) = state.calls.get_mut(&id) else {
+            return false;
+        };
+        if call.cancellation.is_some() {
+            return false;
+        }
+        call.transmitted = true;
+        true
+    }
+
+    /// 先撤销调用权限，再等待对端确认；只有无响应对端才终止整个 incarnation。
+    pub fn cancel(self: &Arc<Self>, id: u64, error: RpcError) {
+        let mut state = self.state();
+        let Some(call) = state.calls.get_mut(&id) else {
+            return;
+        };
+        if call.cancellation.is_some() {
+            return;
+        }
+        if !call.transmitted {
+            if let Some(call) = state.calls.remove(&id) {
+                call.finish(Err(error));
+            }
+            return;
+        }
+        call.cancellation = Some(error.clone());
+        call.handler.finish(&call.context);
+        for callback in call.callbacks.drain(..) {
+            callback.abort();
+        }
+        if let Some(result) = call.result.take() {
+            let _ = result.send(Err(error.clone()));
+        }
+        if let Some(stream) = call.stream.take() {
+            stream.finish(Err(error.clone()));
+        }
+        drop(state);
+        self.send_control(Frame::control(Message::Cancel { id }));
+        let shared = Arc::clone(self);
+        tokio::spawn(async move {
+            tokio::time::sleep(Duration::from_millis(250)).await;
+            if shared.is_cancelling(id) {
+                shared.fail(error);
+            }
+        });
+    }
+
+    pub fn acknowledge_cancellation(&self, id: u64) -> Result<(), RpcError> {
+        let mut state = self.state();
+        if !state
+            .calls
+            .get(&id)
+            .is_some_and(|call| call.cancellation.is_some())
+        {
+            return Err(RpcError::Protocol);
+        }
+        state.calls.remove(&id);
+        Ok(())
+    }
+
+    pub fn track_callback(&self, parent_id: u64, callback: tokio::task::AbortHandle) -> bool {
+        if let Some(call) = self
+            .state()
+            .calls
+            .get_mut(&parent_id)
+            .filter(|call| call.cancellation.is_none())
+        {
+            // 已完成回调的句柄不继续占用请求预算。
+            call.callbacks.retain(|handle| !handle.is_finished());
+            call.callbacks.push(callback);
+            true
+        } else {
+            callback.abort();
+            false
+        }
+    }
+
+    pub fn send_control(&self, frame: Frame) {
+        if self.control.try_send(frame).is_err() {
+            self.fail(RpcError::Capacity);
+        }
+    }
+
+    pub(super) fn try_callback_slot(&self) -> Option<tokio::sync::OwnedSemaphorePermit> {
+        self.callback_slots.clone().try_acquire_owned().ok()
+    }
+
+    async fn wait_for_callbacks(&self, maximum_callbacks: usize) {
+        let Ok(maximum_callbacks) = u32::try_from(maximum_callbacks) else {
+            return;
+        };
+        if let Ok(permits) = self
+            .callback_slots
+            .clone()
+            .acquire_many_owned(maximum_callbacks)
+            .await
+        {
+            drop(permits);
+        }
+    }
+}
+
+impl RpcSession {
+    pub async fn start(
+        package: Arc<PreparedPackage>,
+        handshake: Handshake,
+        limits: RpcLimits,
+        processes: &ProcessSupervisor,
+        callbacks: Arc<dyn CallbackHandler>,
+    ) -> Result<Self, RpcError> {
+        Self::start_inner(package, handshake, limits, processes, callbacks, None).await
+    }
+
+    pub(crate) async fn start_supervised(
+        package: Arc<PreparedPackage>,
+        handshake: Handshake,
+        limits: RpcLimits,
+        processes: &ProcessSupervisor,
+        callbacks: Arc<dyn CallbackHandler>,
+        lifecycle: RpcSessionLifecycle,
+    ) -> Result<Self, RpcError> {
+        Self::start_inner(
+            package,
+            handshake,
+            limits,
+            processes,
+            callbacks,
+            Some(lifecycle),
+        )
+        .await
+    }
+
+    async fn start_inner(
+        package: Arc<PreparedPackage>,
+        handshake: Handshake,
+        limits: RpcLimits,
+        processes: &ProcessSupervisor,
+        callbacks: Arc<dyn CallbackHandler>,
+        lifecycle: Option<RpcSessionLifecycle>,
+    ) -> Result<Self, RpcError> {
+        if limits.maximum_calls == 0
+            || limits.maximum_calls > 256
+            || limits.maximum_callbacks == 0
+            || limits.maximum_callbacks > 256
+            || limits.maximum_frame_bytes < 1024
+            || limits.maximum_frame_bytes > 16 * 1024 * 1024
+            || limits.handshake_timeout.is_zero()
+            || limits.maximum_call_timeout.is_zero()
+        {
+            return Err(RpcError::Context);
+        }
+        let manifest = package.package().manifest();
+        let plugin_id = manifest.plugin_id().map_err(|_| RpcError::Handshake)?;
+        if handshake.protocol_version != PROTOCOL_VERSION
+            || handshake.plugin_id != plugin_id
+            || handshake.artifact_sha256 != package.package().digest()
+            || handshake.contributes != manifest.contributes
+            || handshake
+                .permissions
+                .iter()
+                .any(|permission| !manifest.permissions.contains(permission))
+            || handshake.instance_id.is_empty()
+            || handshake.incarnation.is_empty()
+            || handshake.generation == 0
+        {
+            return Err(RpcError::Handshake);
+        }
+        let process = processes
+            .spawn(ProcessSpec {
+                executable: package.executable().to_owned(),
+                directory: package.directory().to_owned(),
+                maximum_stderr_bytes: limits.maximum_stderr_bytes,
+            })
+            .map_err(RpcError::Start)?;
+        let gateway_host::process::ProcessConnection {
+            mut input,
+            mut output,
+            control: process,
+        } = process;
+        let ready = tokio::time::timeout(limits.handshake_timeout, async {
+            write_frame(
+                &mut input,
+                &Frame::control(Message::Hello {
+                    handshake: handshake.clone(),
+                }),
+                limits.maximum_frame_bytes,
+            )
+            .await
+            .map_err(|_| RpcError::Handshake)?;
+            let reply = read_frame(&mut output, limits.maximum_frame_bytes)
+                .await
+                .map_err(|_| RpcError::Handshake)?;
+            match reply.message {
+                Message::Ready {
+                    protocol_version: PROTOCOL_VERSION,
+                    incarnation,
+                } if incarnation == handshake.incarnation && reply.payload.is_empty() => Ok(()),
+                _ => Err(RpcError::Handshake),
+            }
+        })
+        .await
+        .map_err(|_| RpcError::Timeout)
+        .and_then(|result| result);
+        if let Err(error) = ready {
+            if let Some(lifecycle) = &lifecycle {
+                // 只有 Ready 之后的存活才可复位预算；长时间卡在握手不等于稳定运行。
+                lifecycle.fail(Duration::ZERO);
+            }
+            process.stop();
+            process.exited().await;
+            return Err(error);
+        }
+        let (data, data_receiver) = mpsc::channel(limits.maximum_calls);
+        let (control, control_receiver) =
+            mpsc::channel(limits.maximum_callbacks + limits.maximum_calls + 8);
+        let (stopped, _) = watch::channel(false);
+        let callback_slots = Arc::new(Semaphore::new(limits.maximum_callbacks));
+        let shared = Arc::new(Shared {
+            state: Mutex::new(State {
+                failure: None,
+                calls: BTreeMap::new(),
+            }),
+            started_at: Instant::now(),
+            expected_stop: AtomicBool::new(false),
+            failure_observer: lifecycle
+                .as_ref()
+                .map(|lifecycle| Arc::clone(&lifecycle.failure)),
+            control,
+            process,
+            stopped,
+            callback_slots,
+        });
+        dispatch::start(
+            input,
+            output,
+            data_receiver,
+            control_receiver,
+            Arc::clone(&shared),
+            callbacks.clone(),
+            handshake.permissions.clone(),
+            limits,
+        );
+        let monitor = Arc::clone(&shared);
+        let instance_id = handshake.instance_id.clone();
+        tokio::spawn(async move {
+            let reason = monitor.process.exited().await;
+            if !monitor.expected_stop.load(Ordering::Acquire) {
+                tracing::warn!(instance_id, exit = ?reason, "插件进程意外停止");
+            }
+            monitor.fail(RpcError::Closed);
+            // 等进程退出后再回收其文件，避免 Windows 上删除正在执行的制品。
+            drop(package);
+        });
+        Ok(Self {
+            shared,
+            handshake,
+            data,
+            slots: Arc::new(Semaphore::new(limits.maximum_calls)),
+            next_call: AsyncMutex::new(1),
+            limits,
+            callbacks,
+            _lifecycle: lifecycle,
+        })
+    }
+
+    #[must_use]
+    pub fn is_ready(&self) -> bool {
+        self.shared
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .failure
+            .is_none()
+    }
+
+    /// 仅返回稳定分类与固定文案，绝不展开插件 fault、stderr 或请求内容。
+    pub(crate) fn diagnostic(&self) -> RpcSessionDiagnostic {
+        let state = self
+            .shared
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if let Some(error) = &state.failure {
+            let (code, message) = match error {
+                RpcError::Start(_) => ("process_start", "插件进程启动失败"),
+                RpcError::Handshake => ("handshake", "插件握手失败"),
+                RpcError::Protocol => ("protocol", "插件协议错误"),
+                RpcError::Closed => ("closed", "插件进程或传输已停止"),
+                RpcError::Timeout => ("timeout", "插件调用超时"),
+                RpcError::Cancelled => ("cancelled", "插件会话已取消"),
+                RpcError::Capacity => ("capacity", "插件调用容量已耗尽"),
+                RpcError::Context => ("context", "插件调用上下文无效"),
+                RpcError::Remote(_) => ("remote", "插件返回错误"),
+            };
+            return RpcSessionDiagnostic::Failed { code, message };
+        }
+        if self.slots.is_closed() {
+            RpcSessionDiagnostic::Quiescing
+        } else {
+            RpcSessionDiagnostic::Ready
+        }
+    }
+
+    #[must_use]
+    pub fn context(&self, stage: gateway_plugin_sdk::Stage, timeout: Duration) -> CallContext {
+        // 宿主生成的上下文受本会话预算约束；固定注册期限不能使较小的总预算无法启动。
+        let timeout = timeout.min(self.limits.maximum_call_timeout);
+        CallContext {
+            call_id: 0,
+            instance_id: self.handshake.instance_id.clone(),
+            generation: self.handshake.generation,
+            incarnation: self.handshake.incarnation.clone(),
+            stage,
+            timeout_ms: timeout.as_millis().min(u128::from(u64::MAX)) as u64,
+            resource_scope_id: uuid::Uuid::new_v4().to_string(),
+            request_id: None,
+            attempt_id: None,
+            account_id: None,
+            credential_revision: None,
+        }
+    }
+
+    fn call_deadline(
+        &self,
+        method: &str,
+        context: &CallContext,
+        payload: &[u8],
+    ) -> Result<tokio::time::Instant, RpcError> {
+        if context.instance_id != self.handshake.instance_id
+            || context.generation != self.handshake.generation
+            || context.incarnation != self.handshake.incarnation
+            || context.timeout_ms == 0
+            || Duration::from_millis(context.timeout_ms) > self.limits.maximum_call_timeout
+            || method.is_empty()
+            || method.len() > 128
+            || payload.len() > self.limits.maximum_frame_bytes
+        {
+            return Err(RpcError::Context);
+        }
+        Ok(tokio::time::Instant::now() + Duration::from_millis(context.timeout_ms))
+    }
+
+    fn begin_call(
+        &self,
+        context: CallContext,
+        deadline: tokio::time::Instant,
+        stream: Option<StreamIngress>,
+    ) -> Result<StartedCall, RpcError> {
+        let id = context.call_id;
+        let (result, received) = oneshot::channel();
+        let mut state = self.shared.state();
+        if let Some(error) = &state.failure {
+            return Err(error.clone());
+        }
+        if state.calls.len() >= self.limits.maximum_calls {
+            return Err(RpcError::Capacity);
+        }
+        self.callbacks.begin(&context);
+        state.calls.insert(
+            id,
+            PendingCall {
+                handler: self.callbacks.clone(),
+                transmitted: false,
+                cancellation: None,
+                context,
+                result: Some(result),
+                stream,
+                callbacks: Vec::new(),
+            },
+        );
+        Ok(StartedCall {
+            id,
+            deadline,
+            received,
+        })
+    }
+
+    async fn send_call(
+        &self,
+        method: &str,
+        context: CallContext,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+        stream: Option<StreamIngress>,
+        credit: Option<(u32, u32)>,
+    ) -> Result<CompletedCall, RpcError> {
+        let deadline = self.call_deadline(method, &context, &payload)?;
+        // FIFO 锁同时拥有 ID 与 data 入队顺序；Call/初始 Credit 入队后必须立即释放，
+        // 不能把插件回复或重入回调纳入串行区，也不能为等待锁重置调用期限。
+        let mut next_call = tokio::time::timeout_at(deadline, self.next_call.lock())
+            .await
+            .map_err(|_| RpcError::Timeout)?;
+        let id = *next_call;
+        *next_call = id.checked_add(2).ok_or(RpcError::Capacity)?;
+        let mut context = context;
+        context.call_id = id;
+        let frame = Frame {
+            message: Message::Call {
+                id,
+                method: method.to_owned(),
+                context: context.clone(),
+                params,
+            },
+            payload,
+        };
+        let started = self.begin_call(context, deadline, stream)?;
+        let mut guard = CallGuard {
+            shared: Arc::clone(&self.shared),
+            id: started.id,
+            armed: true,
+        };
+        let sent = tokio::time::timeout_at(started.deadline, async {
+            self.data.send(frame).await.map_err(|_| RpcError::Closed)?;
+            if let Some((bytes, frames)) = credit {
+                // 初始信用跟在 Call 后走同一有序队列，不能被控制队列提前发送。
+                self.data
+                    .send(Frame::control(Message::Credit {
+                        id: started.id,
+                        bytes,
+                        frames,
+                    }))
+                    .await
+                    .map_err(|_| RpcError::Closed)?;
+            }
+            Ok::<(), RpcError>(())
+        })
+        .await;
+        drop(next_call);
+        match sent {
+            Ok(Ok(())) => {}
+            Ok(Err(error)) => {
+                self.shared.cancel(started.id, error.clone());
+                guard.armed = false;
+                return Err(error);
+            }
+            Err(_) => {
+                self.shared.cancel(started.id, RpcError::Timeout);
+                guard.armed = false;
+                return Err(RpcError::Timeout);
+            }
+        }
+        let result = tokio::time::timeout_at(started.deadline, started.received).await;
+        let reply = match result {
+            Ok(Ok(result)) => {
+                guard.armed = false;
+                result?
+            }
+            Ok(Err(_)) => {
+                self.shared.cancel(started.id, RpcError::Closed);
+                guard.armed = false;
+                return Err(RpcError::Closed);
+            }
+            Err(_) => {
+                self.shared.cancel(started.id, RpcError::Timeout);
+                guard.armed = false;
+                return Err(RpcError::Timeout);
+            }
+        };
+        Ok(CompletedCall {
+            id: started.id,
+            deadline: started.deadline,
+            reply,
+        })
+    }
+
+    pub async fn call(
+        &self,
+        method: &str,
+        context: CallContext,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+    ) -> Result<RpcReply, RpcError> {
+        let _slot = self.slots.try_acquire().map_err(|_| RpcError::Capacity)?;
+        self.send_call(method, context, params, payload, None, None)
+            .await
+            .map(|completed| completed.reply)
+    }
+
+    pub async fn call_stream(
+        self: &Arc<Self>,
+        method: &str,
+        context: CallContext,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+    ) -> Result<RpcStream, RpcError> {
+        let slot = Arc::clone(&self.slots)
+            .try_acquire_owned()
+            .map_err(|_| RpcError::Capacity)?;
+        let bytes = self.limits.maximum_frame_bytes.min(256 * 1024) as u32;
+        let frames = 32;
+        let (stream, chunks, terminal) = StreamIngress::new(bytes, frames);
+        let completed = self
+            .send_call(
+                method,
+                context,
+                params,
+                payload,
+                Some(stream),
+                Some((bytes, frames)),
+            )
+            .await?;
+        Ok(RpcStream {
+            initial: completed.reply,
+            chunks,
+            terminal: Some(terminal),
+            deadline: completed.deadline,
+            id: completed.id,
+            shared: Arc::clone(&self.shared),
+            _slot: slot,
+            _session: Arc::clone(self),
+        })
+    }
+
+    pub fn quiesce(&self) {
+        self.shared.expect_stop();
+        self.slots.close();
+        self.shared.send_control(Frame::control(Message::Quiesce));
+    }
+
+    pub async fn shutdown(&self, grace: Duration) {
+        let deadline = tokio::time::Instant::now() + grace;
+        self.shutdown_until(deadline).await;
+    }
+
+    pub(crate) async fn shutdown_until(&self, deadline: tokio::time::Instant) {
+        self.shared.expect_stop();
+        self.shared.send_control(Frame::control(Message::Shutdown));
+        if tokio::time::timeout_at(deadline, self.settle_shutdown())
+            .await
+            .is_err()
+        {
+            self.shared.fail(RpcError::Closed);
+            // 强制停止没有第二段宽限；退出和回调析构是返回前必须确认的事实。
+            self.settle_shutdown().await;
+        }
+    }
+
+    async fn settle_shutdown(&self) {
+        self.shared.process.exited().await;
+        // 不等待监控任务调度；先撤销父调用并中止其回调，再确认回调 future 已析构。
+        self.shared.fail(RpcError::Closed);
+        self.shared
+            .wait_for_callbacks(self.limits.maximum_callbacks)
+            .await;
+    }
+}
+
+impl Drop for RpcSession {
+    fn drop(&mut self) {
+        self.shared.expect_stop();
+        self.shared.fail(RpcError::Closed);
+    }
+}
+
+struct CallGuard {
+    shared: Arc<Shared>,
+    id: u64,
+    armed: bool,
+}
+
+impl Drop for CallGuard {
+    fn drop(&mut self) {
+        if self.armed {
+            self.shared.cancel(self.id, RpcError::Cancelled);
+        }
+    }
+}
+
+struct StartedCall {
+    id: u64,
+    deadline: tokio::time::Instant,
+    received: oneshot::Receiver<Result<RpcReply, RpcError>>,
+}
+
+struct CompletedCall {
+    id: u64,
+    deadline: tokio::time::Instant,
+    reply: RpcReply,
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/stream/bridge.rs b/backend/crates/gateway-plugin/runtime/src/stream/bridge.rs
new file mode 100644
index 000000000..77d05e355
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/stream/bridge.rs
@@ -0,0 +1,101 @@
+use std::sync::Arc;
+
+use tokio::{
+    sync::{OwnedSemaphorePermit, mpsc, oneshot},
+    time::Instant,
+};
+
+use crate::{RpcError, RpcReply, RpcSession, rpc::Shared};
+
+use super::flow_control::ReceiveWindow;
+
+pub(crate) struct StreamIngress {
+    chunks: mpsc::Sender<Vec<u8>>,
+    terminal: oneshot::Sender<Result<(), RpcError>>,
+    window: ReceiveWindow,
+}
+
+impl StreamIngress {
+    pub fn new(
+        bytes: u32,
+        frames: u32,
+    ) -> (
+        Self,
+        mpsc::Receiver<Vec<u8>>,
+        oneshot::Receiver<Result<(), RpcError>>,
+    ) {
+        let (chunks, received) = mpsc::channel(frames as usize);
+        let (terminal, ended) = oneshot::channel();
+        (
+            Self {
+                chunks,
+                terminal,
+                window: ReceiveWindow::new(bytes, frames),
+            },
+            received,
+            ended,
+        )
+    }
+
+    pub fn receive(&mut self, sequence: u64, payload: Vec<u8>) -> Result<(), RpcError> {
+        self.window.receive(sequence, payload.len())?;
+        self.chunks
+            .try_send(payload)
+            .map_err(|_| RpcError::Protocol)
+    }
+
+    pub fn release(&mut self, bytes: u32) -> Result<(), RpcError> {
+        self.window.release(bytes)
+    }
+
+    pub fn finish(self, result: Result<(), RpcError>) {
+        let _ = self.terminal.send(result);
+    }
+}
+
+/// 消费者读取后才补充窗口；终态走独立通道，不会排在满数据队列后等待。
+pub struct RpcStream {
+    pub initial: RpcReply,
+    pub(crate) chunks: mpsc::Receiver<Vec<u8>>,
+    pub(crate) terminal: Option<oneshot::Receiver<Result<(), RpcError>>>,
+    pub(crate) deadline: Instant,
+    pub(crate) id: u64,
+    pub(crate) shared: Arc<Shared>,
+    pub(crate) _slot: OwnedSemaphorePermit,
+    pub(crate) _session: Arc<RpcSession>,
+}
+
+impl RpcStream {
+    pub async fn next(&mut self) -> Result<Option<Vec<u8>>, RpcError> {
+        if self.terminal.is_none() {
+            return Ok(None);
+        }
+        match tokio::time::timeout_at(self.deadline, self.chunks.recv()).await {
+            Ok(Some(chunk)) => {
+                self.shared
+                    .release_stream_credit(self.id, chunk.len() as u32)?;
+                Ok(Some(chunk))
+            }
+            Ok(None) => {
+                let Some(terminal) = self.terminal.take() else {
+                    return Ok(None);
+                };
+                terminal.await.map_err(|_| RpcError::Closed)??;
+                Ok(None)
+            }
+            Err(_) => {
+                self.shared.cancel(self.id, RpcError::Timeout);
+                self.terminal = None;
+                Err(RpcError::Timeout)
+            }
+        }
+    }
+}
+
+impl Drop for RpcStream {
+    fn drop(&mut self) {
+        if self.shared.context(self.id).is_some() {
+            self.shared.cancel(self.id, RpcError::Cancelled);
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/stream/flow_control.rs b/backend/crates/gateway-plugin/runtime/src/stream/flow_control.rs
new file mode 100644
index 000000000..724139367
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/stream/flow_control.rs
@@ -0,0 +1,38 @@
+use crate::RpcError;
+
+/// 字节与帧数一起授予，避免攻击者用大量单字节分块突破队列上限。
+pub(super) struct ReceiveWindow {
+    bytes: u32,
+    frames: u32,
+    next_sequence: u64,
+}
+
+impl ReceiveWindow {
+    pub fn new(bytes: u32, frames: u32) -> Self {
+        Self {
+            bytes,
+            frames,
+            next_sequence: 0,
+        }
+    }
+
+    pub fn receive(&mut self, sequence: u64, bytes: usize) -> Result<(), RpcError> {
+        let bytes = u32::try_from(bytes).map_err(|_| RpcError::Protocol)?;
+        if sequence != self.next_sequence || bytes == 0 || bytes > self.bytes || self.frames == 0 {
+            return Err(RpcError::Protocol);
+        }
+        self.next_sequence = self
+            .next_sequence
+            .checked_add(1)
+            .ok_or(RpcError::Protocol)?;
+        self.bytes -= bytes;
+        self.frames -= 1;
+        Ok(())
+    }
+
+    pub fn release(&mut self, bytes: u32) -> Result<(), RpcError> {
+        self.bytes = self.bytes.checked_add(bytes).ok_or(RpcError::Protocol)?;
+        self.frames = self.frames.checked_add(1).ok_or(RpcError::Protocol)?;
+        Ok(())
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/src/stream/mod.rs b/backend/crates/gateway-plugin/runtime/src/stream/mod.rs
new file mode 100644
index 000000000..71c0bd00d
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/src/stream/mod.rs
@@ -0,0 +1,5 @@
+mod bridge;
+mod flow_control;
+
+pub use bridge::RpcStream;
+pub(crate) use bridge::StreamIngress;
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/execution.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/execution.rs
new file mode 100644
index 000000000..a45143cd4
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/execution.rs
@@ -0,0 +1,292 @@
+use gateway_core::policy::{ClientApiKeyId, RateLimits};
+use gateway_plugin_runtime::PluginCommandError;
+use serde_json::json;
+
+use crate::support::environment::{Environment, account_grant};
+
+#[tokio::test]
+async fn command_selects_key_at_call_time_and_uses_normal_model_ledger() {
+    let Some(mut environment) = Environment::create_command().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let account = environment.account(None).await;
+    let group_id = environment.account_group_with_account(&account).await;
+    let key_id = format!("key_{}", uuid::Uuid::new_v4().simple());
+    environment
+        .client_key_with_limits_and_groups(
+            &key_id,
+            "sk-command-bound-fixture",
+            RateLimits {
+                max_concurrency: 1,
+                requests_per_minute: 0,
+            },
+            vec![group_id.clone()],
+        )
+        .await;
+    let marker = environment
+        .directory
+        .path()
+        .join("command-bound-model.jsonl");
+    let command_marker = environment.directory.path().join("command-bound.jsonl");
+    let model_grant = account_grant("models");
+    let source_credentials = account_grant("accounts");
+    environment
+        .install_provider(
+            json!({
+                "provider_id":"command-source",
+                "command_registration":{"commands":[
+                    {"name":"run","description":"执行模型"},
+                    {"name":"fail","description":"执行后失败"}
+                ]},
+                "command_nested_model_fixture":{
+                    "request":{
+                        "client_key_id":key_id,
+                        "model":"plugin-model",
+                        "protocol":"openai",
+                        "operation":"generate",
+                        "provider":"example",
+                        "account_id":account.as_str()
+                    },
+                    "body":{"model":"plugin-model","input":"bound command"}
+                },
+                "command_nested_model_marker":marker,
+                "command_marker":command_marker,
+                "command_error_after_nested_model":"fail",
+                "command_result":{"stdout":"ok\n","stderr":"","exit_code":0}
+            }),
+            vec![model_grant, source_credentials],
+        )
+        .await;
+    environment
+        .install_provider(
+            json!({"provider_id":"example","generation_marker":"command-target"}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let (runtime, core) = environment.command_plane().await;
+    let snapshot = environment
+        .store
+        .admin_ports()
+        .plugins()
+        .load_instances()
+        .await
+        .unwrap();
+    let instance = snapshot
+        .instances
+        .iter()
+        .find(|instance| instance.configuration.get("command_registration").is_some())
+        .unwrap();
+    let commands = runtime.prepare_command_line().await.unwrap();
+    environment.store.start_command_line_writes().unwrap();
+    let output = commands.execute(&instance.id, "run", &[]).await.unwrap();
+    assert_eq!(output.stdout, "ok\n");
+    assert_eq!(std::fs::read_to_string(&marker).unwrap().lines().count(), 1);
+    assert_eq!(
+        environment.wait_for_bound_model_requests(&key_id, 1).await,
+        vec![("plugin_bound_model".into(), instance.id.clone())]
+    );
+    let second = commands.execute(&instance.id, "run", &[]).await.unwrap();
+    assert_eq!(second.stdout, "ok\n", "the first Key slot must be released");
+    assert_eq!(
+        environment.wait_for_bound_model_requests(&key_id, 2).await,
+        vec![
+            ("plugin_bound_model".into(), instance.id.clone()),
+            ("plugin_bound_model".into(), instance.id.clone()),
+        ]
+    );
+
+    environment
+        .set_account_group_enabled(group_id.clone(), false)
+        .await;
+    assert!(
+        environment
+            .store
+            .admin_ports()
+            .client_keys()
+            .get_client_key(&ClientApiKeyId::new(key_id.clone()).unwrap())
+            .await
+            .unwrap()
+            .unwrap()
+            .enabled,
+        "scope revocation must not disable the bound Key itself"
+    );
+    let error = commands
+        .execute(&instance.id, "run", &[])
+        .await
+        .err()
+        .unwrap();
+    assert!(matches!(error, PluginCommandError::Incomplete { .. }));
+    assert_eq!(
+        std::fs::read_to_string(command_marker)
+            .unwrap()
+            .lines()
+            .count(),
+        3,
+        "scope revocation is enforced by the host callback, not hidden from the plugin RPC"
+    );
+    let revoked = std::fs::read_to_string(&marker).unwrap();
+    let revoked: serde_json::Value = serde_json::from_str(revoked.lines().last().unwrap()).unwrap();
+    assert_eq!(revoked["error"], "rejected");
+    assert_eq!(environment.bound_model_requests(&key_id).await.len(), 2);
+
+    environment.set_account_group_enabled(group_id, true).await;
+    let error = commands
+        .execute(&instance.id, "fail", &[])
+        .await
+        .err()
+        .unwrap();
+    assert!(matches!(error, PluginCommandError::Incomplete { .. }));
+
+    commands.shutdown().await;
+    environment
+        .store
+        .shutdown_command_line_writes()
+        .await
+        .unwrap();
+    assert_eq!(
+        environment.bound_model_requests(&key_id).await.len(),
+        3,
+        "an error exit must drain the completed child model ledger"
+    );
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn command_accounts_use_admin_cas_audit_and_report_partial_commit_without_replay() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let existing = environment.account(None).await;
+    let facts = json!({"name":"CLI created account","authentication_kind":"api_key","material":{"key":"cli-test-only"}});
+    let config = json!({
+        "command_registration":{"commands":[{"name":"login","description":"提交账号"}]},
+        "command_registration_probe":true,
+        "command_result":{"stdout":"saved\n","stderr":"","exit_code":0,"accounts":[
+            {"action":"create","provider_id":"example","facts":facts},
+            {"action":"replace","account_id":existing.as_str(),"credential_revision":999,"facts":facts}
+        ]}
+    });
+    let (runtime, core) = environment
+        .provider(config, vec![account_grant("accounts")])
+        .await;
+    let admin = environment.bind_admin_accounts(&runtime, &core).await;
+    let snapshot = environment
+        .store
+        .admin_ports()
+        .plugins()
+        .load_instances()
+        .await
+        .unwrap();
+    let id = &snapshot.instances[0].id;
+    let commands = runtime.prepare_command_line().await.unwrap();
+    assert!(commands.help(Some(id), Some("login")).is_ok());
+    assert_eq!(
+        environment
+            .store
+            .provider_ports()
+            .accounts()
+            .list_accounts()
+            .await
+            .unwrap()
+            .len(),
+        1
+    );
+    assert!(
+        environment
+            .audit_requests("import_document")
+            .await
+            .is_empty()
+    );
+    let error = commands.execute(id, "login", &[]).await.err().unwrap();
+    assert!(matches!(
+        error,
+        PluginCommandError::Incomplete {
+            saved_accounts: 1,
+            ..
+        }
+    ));
+    let accounts = environment
+        .store
+        .provider_ports()
+        .accounts()
+        .list_accounts()
+        .await
+        .unwrap();
+    assert_eq!(accounts.len(), 2);
+    assert_eq!(
+        accounts
+            .iter()
+            .find(|account| account.id() == &existing)
+            .unwrap()
+            .revision()
+            .get(),
+        1
+    );
+    let created = accounts
+        .iter()
+        .find(|account| account.id() != &existing)
+        .unwrap();
+    assert!(created.id().as_str().starts_with("acct_"));
+    assert_eq!(created.name(), "CLI created account");
+    let audits = environment.audit_requests("import_document").await;
+    assert_eq!(audits.len(), 1);
+    assert!(audits[0].contains(":scope:"));
+    assert!(!error.to_string().contains("cli-test-only"));
+    drop(commands);
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn command_accounts_domain_does_not_need_separate_login_or_write_grants() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let config = json!({
+        "command_registration":{"commands":[{"name":"login","description":"提交账号"}]},
+        "command_result":{"stdout":"","stderr":"","exit_code":0,"accounts":[
+            {"action":"create","provider_id":"example","facts":{"name":"CLI created","authentication_kind":"api_key","material":{"key":"cli-test-only"}}}
+        ]}
+    });
+    let (runtime, core) = environment
+        .provider(config, vec![account_grant("accounts")])
+        .await;
+    let admin = environment.bind_admin_accounts(&runtime, &core).await;
+    let snapshot = environment
+        .store
+        .admin_ports()
+        .plugins()
+        .load_instances()
+        .await
+        .unwrap();
+    let commands = runtime.prepare_command_line().await.unwrap();
+    let output = commands
+        .execute(&snapshot.instances[0].id, "login", &[])
+        .await
+        .unwrap();
+    assert_eq!(output.saved_accounts, 1);
+    assert_eq!(
+        environment
+            .store
+            .provider_ports()
+            .accounts()
+            .list_accounts()
+            .await
+            .unwrap()
+            .len(),
+        1
+    );
+    assert_eq!(environment.audit_requests("import_document").await.len(), 1);
+    drop(commands);
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/mod.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/mod.rs
new file mode 100644
index 000000000..98e53e456
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/mod.rs
@@ -0,0 +1,210 @@
+mod execution;
+mod parameters;
+
+use std::{
+    collections::BTreeMap,
+    sync::{Arc, Mutex},
+};
+
+use gateway_admin::{
+    model::{
+        Revision,
+        plugins::instances::{PluginInstance, PluginInstanceSnapshot},
+    },
+    ports::plugins::PluginPackageInspector,
+};
+use gateway_plugin_runtime::{
+    PackageInspector, PackageLimits, PluginRuntime, PluginRuntimeConfig, RpcLimits,
+};
+use gateway_plugin_sdk::{Capability, Contributions, Stage};
+use serde_json::{Value, json};
+
+use crate::support::store::Store;
+
+async fn setup(configuration: Value) -> (tempfile::TempDir, Arc<Store>, PluginRuntime) {
+    setup_with_limits(configuration, RpcLimits::default()).await
+}
+
+async fn setup_with_limits(
+    configuration: Value,
+    rpc_limits: RpcLimits,
+) -> (tempfile::TempDir, Arc<Store>, PluginRuntime) {
+    let directory = tempfile::tempdir().unwrap();
+    let archive = crate::support::package_with_contributions(
+        crate::support::worker(),
+        vec![],
+        Contributions::from([crate::support::contribution(
+            Capability::CommandLine,
+            vec![Stage::CommandLine],
+            vec![],
+            vec![],
+        )]),
+    );
+    let artifact = PackageInspector::new(PackageLimits::default(), "1.0.0".parse().unwrap())
+        .inspect(archive, None)
+        .await
+        .unwrap();
+    let instance = PluginInstance {
+        id: "commands".into(),
+        name: "Commands".into(),
+        artifact_sha256: artifact.metadata.sha256.clone(),
+        enabled: true,
+        trusted_process: true,
+        configuration,
+        secrets: BTreeMap::new(),
+        grants: vec![],
+        bindings: vec![],
+        revision: Revision::new(1).unwrap(),
+    };
+    let store = Arc::new(Store {
+        artifacts: BTreeMap::from([(artifact.metadata.sha256.clone(), artifact)]),
+        snapshot: Mutex::new(PluginInstanceSnapshot {
+            config_revision: Revision::new(1).unwrap(),
+            instances: vec![instance],
+        }),
+    });
+    let runtime = PluginRuntime::new(
+        store.clone(),
+        store.clone(),
+        PluginRuntimeConfig {
+            cache_directory: directory.path().join("cache"),
+            host_version: "1.0.0".parse().unwrap(),
+            package_limits: PackageLimits::default(),
+            rpc_limits,
+            continuation_drain: Default::default(),
+            restart_circuit: Default::default(),
+        },
+        gateway_core::engine::provider::ProviderRegistry::default(),
+        gateway_admin::ports::provider::ProviderAdminRegistry::new([]).unwrap(),
+        Arc::new(gateway_host::outbound::HttpClient::new().unwrap()),
+        Arc::new(gateway_host::process::ProcessSupervisor::default()),
+    );
+    (directory, store, runtime)
+}
+
+fn configuration(parameters: Value) -> Value {
+    json!({"command_registration":{"commands":[{"name":"inspect","description":"检查参数","parameters":parameters}]},"command_echo":true})
+}
+
+#[tokio::test]
+async fn command_help_does_not_execute_and_stale_authorization_cannot_execute() {
+    let (directory, store, runtime) = setup(configuration(json!([]))).await;
+    let marker = directory.path().join("commands.jsonl");
+    store.snapshot.lock().unwrap().instances[0].configuration["command_marker"] = json!(marker);
+    let commands = runtime.prepare_command_line().await.unwrap();
+    assert!(
+        commands
+            .help(None, None)
+            .unwrap()
+            .contains("commands inspect")
+    );
+    assert!(
+        commands
+            .help(Some("commands"), Some("inspect"))
+            .unwrap()
+            .contains("--help")
+    );
+    assert!(!marker.exists());
+    assert!(commands.execute("commands", "missing", &[]).await.is_err());
+    assert!(!marker.exists());
+    let output = commands.execute("commands", "inspect", &[]).await.unwrap();
+    assert_eq!(output.exit_code, 0);
+    assert_eq!(std::fs::read_to_string(&marker).unwrap().lines().count(), 1);
+    store.snapshot.lock().unwrap().instances[0].enabled = false;
+    let error = commands
+        .execute("commands", "inspect", &[])
+        .await
+        .err()
+        .unwrap();
+    assert!(matches!(
+        error,
+        gateway_plugin_runtime::PluginCommandError::Invalid(_)
+    ));
+    assert_eq!(std::fs::read_to_string(marker).unwrap().lines().count(), 1);
+}
+
+#[tokio::test]
+async fn command_returns_separate_output_and_exit_code_without_saving_on_failure() {
+    let mut config = configuration(json!([]));
+    config["command_echo"] = json!(false);
+    config["command_result"] = json!({"stdout":"out\n","stderr":"err\n","exit_code":17});
+    let (_directory, _store, runtime) = setup(config).await;
+    let commands = runtime.prepare_command_line().await.unwrap();
+    let output = commands.execute("commands", "inspect", &[]).await.unwrap();
+    assert_eq!(
+        (
+            output.stdout.as_str(),
+            output.stderr.as_str(),
+            output.exit_code
+        ),
+        ("out\n", "err\n", 17)
+    );
+    assert_eq!(output.saved_accounts, 0);
+}
+
+#[tokio::test]
+async fn failed_or_cancelled_commands_are_not_replayed_and_children_are_reaped() {
+    use gateway_core::lifecycle::CancellationToken;
+    use gateway_plugin_runtime::PluginCommandError;
+    use std::time::Duration;
+
+    for failure in ["timeout", "crash", "cancel"] {
+        let mut config = configuration(json!([]));
+        config["command_wait"] = json!(true);
+        config["command_crash"] = json!(failure == "crash");
+        let limits = RpcLimits::default();
+        let (directory, store, runtime) = setup_with_limits(config, limits).await;
+        let marker = directory.path().join("commands.jsonl");
+        store.snapshot.lock().unwrap().instances[0].configuration["command_marker"] = json!(marker);
+        let commands = runtime.prepare_command_line().await.unwrap();
+        let cancellation = CancellationToken::new();
+        let invoke = commands.execute_cancellable("commands", "inspect", &[], &cancellation);
+        let interrupt = async {
+            if failure != "crash" {
+                tokio::time::timeout(Duration::from_secs(2), async {
+                    while !marker.exists() {
+                        tokio::time::sleep(Duration::from_millis(5)).await;
+                    }
+                })
+                .await
+                .unwrap();
+                if failure == "cancel" {
+                    cancellation.cancel();
+                } else {
+                    // 正常完成注册并确认命令已进入子进程后，只推进执行期限。
+                    tokio::time::pause();
+                    tokio::time::advance(limits.maximum_call_timeout + Duration::from_millis(1))
+                        .await;
+                }
+            }
+        };
+        let (result, ()) = tokio::join!(invoke, interrupt);
+        if failure == "timeout" {
+            tokio::time::resume();
+        }
+        let error = result.err().unwrap();
+        assert!(matches!(
+            error,
+            PluginCommandError::Incomplete {
+                saved_accounts: 0,
+                ..
+            }
+        ));
+        if failure == "cancel" {
+            assert!(error.to_string().contains("调用已取消"));
+        } else if failure == "timeout" {
+            assert!(error.to_string().contains("超时") || error.to_string().contains("总期限"));
+        } else {
+            assert!(error.to_string().contains("插件进程不可用"));
+        }
+        commands.shutdown().await;
+        let invocations = std::fs::read_to_string(marker).unwrap();
+        assert_eq!(invocations.lines().count(), 1, "{failure}");
+        #[cfg(target_os = "linux")]
+        {
+            let invocation: Value = serde_json::from_str(invocations.trim()).unwrap();
+            let pid = invocation["pid"].as_u64().unwrap();
+            assert!(!std::path::Path::new(&format!("/proc/{pid}")).exists());
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/parameters.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/parameters.rs
new file mode 100644
index 000000000..6c88dd11c
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/parameters.rs
@@ -0,0 +1,125 @@
+use serde_json::{Value, json};
+
+#[tokio::test]
+async fn command_parser_preserves_all_types_defaults_and_signed_nanosecond_boundaries() {
+    let parameters = json!([
+        {"name":"enabled","description":"启用","value_type":"bool"},
+        {"name":"label","description":"名称","value_type":"string","required":true},
+        {"name":"count","description":"数量","value_type":"int"},
+        {"name":"wide","description":"编号","value_type":"int64"},
+        {"name":"ratio","description":"比例","value_type":"float64"},
+        {"name":"wait","description":"等待","value_type":"duration"},
+        {"name":"secret","description":"私密默认","value_type":"string","sensitive":true,"default":{"type":"string","value":"hidden-default"}}
+    ]);
+    let (_directory, _store, runtime) = super::setup(super::configuration(parameters)).await;
+    let commands = runtime.prepare_command_line().await.unwrap();
+    let help = commands.help(Some("commands"), Some("inspect")).unwrap();
+    assert!(!help.contains("hidden-default"));
+    assert!(help.contains("已隐藏"));
+    for (duration, expected) in [
+        ("1h2m3.000000001s", 3_723_000_000_001_i64),
+        ("-9223372036854775808ns", i64::MIN),
+        (".5s", 500_000_000),
+        ("0", 0),
+    ] {
+        let args = [
+            "--enabled",
+            "--label=a=b",
+            "--count=-2147483648",
+            "--wide=9223372036854775807",
+            "--ratio=.125",
+            "--wait",
+            duration,
+        ]
+        .map(str::to_owned);
+        let output = commands
+            .execute("commands", "inspect", &args)
+            .await
+            .unwrap();
+        let invocation: Value = serde_json::from_str(&output.stdout).unwrap();
+        assert_eq!(
+            invocation["arguments"]["enabled"],
+            json!({"type":"bool","value":true})
+        );
+        assert_eq!(invocation["arguments"]["label"]["value"], "a=b");
+        assert_eq!(invocation["arguments"]["count"]["value"], i32::MIN);
+        assert_eq!(invocation["arguments"]["wide"]["value"], i64::MAX);
+        assert_eq!(invocation["arguments"]["ratio"]["value"], 0.125);
+        assert_eq!(invocation["arguments"]["wait"]["value"], expected);
+        assert_eq!(invocation["arguments"]["secret"]["value"], "hidden-default");
+    }
+    for invalid in [
+        vec!["--label=private-sentinel", "--count=2147483648"],
+        vec!["--label=private-sentinel", "--ratio=NaN"],
+        vec!["--label=private-sentinel", "--ratio=inf"],
+        vec!["--label=private-sentinel", "--wait=9223372036854775808ns"],
+        vec!["--label=private-sentinel", "--wait=0.1ns"],
+        vec!["--label=private-sentinel", "--wait=1.2.3s"],
+        vec!["--label=private-sentinel", "--label=duplicate"],
+        vec!["--label=private-sentinel", "--unknown"],
+        vec!["--count=1"],
+    ] {
+        let args = invalid.into_iter().map(str::to_owned).collect::<Vec<_>>();
+        let error = commands
+            .execute("commands", "inspect", &args)
+            .await
+            .err()
+            .unwrap();
+        assert!(matches!(
+            error,
+            gateway_plugin_runtime::PluginCommandError::Invalid(_)
+        ));
+        assert!(!error.to_string().contains("private-sentinel"));
+    }
+}
+
+#[tokio::test]
+async fn command_registration_rejects_reserved_duplicate_and_mistyped_parameters() {
+    let (_directory, store, runtime) = super::setup(super::configuration(json!([]))).await;
+    for parameters in [
+        json!([{"name":"help","description":"保留名","value_type":"bool"}]),
+        json!([{"name":"test","description":"默认类型错误","value_type":"int","default":{"type":"string","value":"bad"}}]),
+        json!([{"name":"same","description":"重复","value_type":"bool"},{"name":"same","description":"重复","value_type":"bool"}]),
+        json!([{"name":"bad","description":"\u{1b}[2J","value_type":"bool"}]),
+    ] {
+        store.snapshot.lock().unwrap().instances[0].configuration =
+            super::configuration(parameters);
+        let commands = runtime
+            .prepare_command_line()
+            .await
+            .expect("invalid plugin is isolated from the host");
+        assert!(commands.help(Some("commands"), None).is_err());
+        let snapshot = store.snapshot.lock().unwrap().clone();
+        assert!(
+            gateway_admin::ports::plugins::PluginPreparation::prepare(
+                &runtime,
+                snapshot.config_revision,
+                snapshot,
+            )
+            .await
+            .is_err(),
+            "invalid registration still rejects an explicit candidate"
+        );
+    }
+    for name in ["help", "serve", "plugin", "version"] {
+        let mut config = super::configuration(json!([]));
+        config["command_registration"]["commands"][0]["name"] = json!(name);
+        store.snapshot.lock().unwrap().instances[0].configuration = config;
+        let commands = runtime
+            .prepare_command_line()
+            .await
+            .expect("invalid plugin is isolated from the host");
+        assert!(commands.help(Some("commands"), None).is_err());
+        let snapshot = store.snapshot.lock().unwrap().clone();
+        assert!(
+            gateway_admin::ports::plugins::PluginPreparation::prepare(
+                &runtime,
+                snapshot.config_revision,
+                snapshot,
+            )
+            .await
+            .is_err(),
+            "invalid registration still rejects an explicit candidate"
+        );
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/management/callback.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/management/callback.rs
new file mode 100644
index 000000000..97c361f8b
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/management/callback.rs
@@ -0,0 +1,148 @@
+use gateway_admin::{
+    PluginManagementService,
+    model::{
+        auth::{AdminPrincipal, AdminRequestContext},
+        plugins::management::{PluginManagementRequest, StartPluginManagementCallback},
+    },
+};
+use serde_json::json;
+
+use super::{Environment, install, registration};
+
+fn request() -> PluginManagementRequest {
+    PluginManagementRequest {
+        method: "GET".into(),
+        path: "oauth".into(),
+        query: "code=synthetic-code".into(),
+        content_type: None,
+        body: Vec::new(),
+        request_id: "callback-test".into(),
+    }
+}
+
+#[tokio::test]
+async fn public_login_callbacks_consume_bound_state_once_and_reject_wrong_owner_instance_and_expiry()
+ {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let mut registration = registration();
+    registration["callbacks"] = json!([{"path":"oauth","response_content_types":["text/plain"]}]);
+    let first = install(
+        &environment,
+        json!({"management_registration":registration}),
+    )
+    .await;
+    let second = install(
+        &environment,
+        json!({"management_registration":{"callbacks":registration["callbacks"]}}),
+    )
+    .await;
+    let (runtime, core) = environment.runtime().await;
+    let service = PluginManagementService::new(
+        runtime.clone(),
+        environment.store.admin_ports().plugins(),
+        core.snapshots(),
+    );
+    let views = service.views().await.unwrap();
+    let callback_only = views
+        .iter()
+        .find(|view| view.target.instance_id == second.id)
+        .unwrap();
+    assert!(callback_only.routes.is_empty());
+    assert!(callback_only.resources.is_empty());
+    assert!(callback_only.pages.is_empty());
+    assert_eq!(callback_only.callbacks.len(), 1);
+    let target = &views
+        .iter()
+        .find(|view| view.target.instance_id == first.id)
+        .unwrap()
+        .target;
+    let other = &views
+        .iter()
+        .find(|view| view.target.instance_id == second.id)
+        .unwrap()
+        .target;
+    let context = AdminRequestContext {
+        principal: AdminPrincipal::Session {
+            admin_user_id: "synthetic-admin".into(),
+        },
+        request_id: "start-callback".into(),
+    };
+    let ticket = service
+        .start_callback(
+            target,
+            StartPluginManagementCallback {
+                path: "oauth".into(),
+                ttl_seconds: 60,
+            },
+            &context,
+        )
+        .await
+        .unwrap();
+    assert!(!ticket.state.contains("synthetic-admin"));
+    let mut wrong_owner = ticket.state.clone();
+    let tail = wrong_owner.pop().unwrap();
+    wrong_owner.push(if tail == '0' { '1' } else { '0' });
+    assert!(
+        service
+            .callback(target, &wrong_owner, request())
+            .await
+            .is_err()
+    );
+    assert!(
+        service
+            .callback(other, &ticket.state, request())
+            .await
+            .is_err()
+    );
+    let (one, two) = tokio::join!(
+        service.callback(target, &ticket.state, request()),
+        service.callback(target, &ticket.state, request())
+    );
+    assert_eq!(usize::from(one.is_ok()) + usize::from(two.is_ok()), 1);
+    let response = one.or(two).unwrap();
+    assert_eq!(response.body.as_ref(), b"callback received");
+    assert!(
+        service
+            .callback(target, &ticket.state, request())
+            .await
+            .is_err()
+    );
+    let expired = service
+        .start_callback(
+            target,
+            StartPluginManagementCallback {
+                path: "oauth".into(),
+                ttl_seconds: 1,
+            },
+            &context,
+        )
+        .await
+        .unwrap();
+    tokio::time::sleep(std::time::Duration::from_millis(1100)).await;
+    assert!(
+        service
+            .callback(target, &expired.state, request())
+            .await
+            .is_err()
+    );
+    assert!(
+        service
+            .start_callback(
+                target,
+                StartPluginManagementCallback {
+                    path: "oauth".into(),
+                    ttl_seconds: 601
+                },
+                &context
+            )
+            .await
+            .is_err()
+    );
+    drop(service);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/management/mod.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/management/mod.rs
new file mode 100644
index 000000000..a8b859c9f
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/management/mod.rs
@@ -0,0 +1,387 @@
+mod callback;
+mod registration;
+
+use std::collections::BTreeMap;
+
+use gateway_admin::{
+    PluginManagementService,
+    model::{
+        Revision,
+        client_keys::SetClientKeyEnabled,
+        plugins::{PluginSource, instances::PluginInstance, management::PluginManagementRequest},
+    },
+    ports::plugins::PluginPackageInspector,
+};
+use gateway_core::{policy::ClientApiKeyId, routing::ConfigRevision};
+use gateway_plugin_runtime::{PackageInspector, PackageLimits};
+use serde_json::{Value, json};
+use sha2::{Digest as _, Sha256};
+
+use crate::support::{
+    self,
+    environment::{Environment, account_grant, mutation},
+};
+
+fn registration() -> Value {
+    json!({
+        "routes":[{"method":"POST","path":"echo","request_content_types":["application/octet-stream"],"response_content_types":["application/octet-stream"]}],
+        "resources":[{"path":"ui/index.html"},{"path":"ui/app.js"},{"path":"ui/public.svg","public":true}],
+        "pages":[{"id":"overview","title":"测试页面","description":"查看插件状态与调用结果","entry":"ui/index.html","icon":"ui/public.svg"}],
+    })
+}
+
+async fn install(environment: &Environment, config: Value) -> PluginInstance {
+    let mut files = BTreeMap::from([
+        ("bin/worker".to_owned(), support::worker().to_vec()),
+        (
+            "ui/index.html".to_owned(),
+            b"<!doctype html><title>Plugin</title><script src=app.js></script>".to_vec(),
+        ),
+        (
+            "ui/app.js".to_owned(),
+            b"parent.postMessage({kind:'loaded'}, '*')".to_vec(),
+        ),
+        (
+            "ui/public.svg".to_owned(),
+            b"<svg xmlns=\"http://www.w3.org/2000/svg\"/>".to_vec(),
+        ),
+    ]);
+    let digests: BTreeMap<_, _> = files
+        .iter()
+        .map(|(name, bytes)| (name.clone(), hex::encode(Sha256::digest(bytes))))
+        .collect();
+    let manifest = json!({
+        "manifestVersion":3,"name":"example","displayName":"管理示例","publisher":"management","version":"1.0.0",
+        "engines":{"codex-proxy-rs":">=1.0.0, <2.0.0"},"main":"bin/worker","author":"test","description":"管理测试","license":"MIT",
+        "runtime":"trustedProcess","resources":{"ui/index.html":"text/html","ui/app.js":"text/javascript","ui/public.svg":"image/svg+xml"},
+        "contributes":{"management":{"id":"management.example.management","version":1,"stages":["management"],"inputFormats":[],"outputFormats":[]}},
+        "permissions":["public_endpoints"],
+        "package":{"protocolVersion":4,"target":{"os":std::env::consts::OS,"architecture":std::env::consts::ARCH},"files":digests},
+    });
+    files.insert("plugin.json".into(), serde_json::to_vec(&manifest).unwrap());
+    let artifact = PackageInspector::new(PackageLimits::default(), "1.0.0".parse().unwrap())
+        .inspect(support::archive(files), None)
+        .await
+        .unwrap();
+    let store = environment.store.admin_ports().plugins();
+    let installed = store
+        .install_artifact(artifact, PluginSource::Upload, &mutation())
+        .await
+        .unwrap();
+    let installed = store
+        .accept_artifact(&installed.artifact.metadata.sha256, &mutation())
+        .await
+        .unwrap();
+    let instance = PluginInstance {
+        id: uuid::Uuid::new_v4().to_string(),
+        name: "管理页面".into(),
+        artifact_sha256: installed.artifact.metadata.sha256,
+        enabled: true,
+        trusted_process: true,
+        configuration: config,
+        secrets: BTreeMap::new(),
+        bindings: vec![],
+        grants: vec![serde_json::from_value(json!({"permission":"public_endpoints"})).unwrap()],
+        revision: Revision::new(1).unwrap(),
+    };
+    store
+        .save_instance(instance, installed.config_revision, &mutation())
+        .await
+        .unwrap()
+        .instance
+}
+
+fn request() -> PluginManagementRequest {
+    PluginManagementRequest {
+        method: "POST".into(),
+        path: "echo".into(),
+        query: "unicode=%E4%B8%AD".into(),
+        content_type: Some("application/octet-stream".into()),
+        body: vec![0, 255, 128, 10],
+        request_id: "management-test".into(),
+    }
+}
+
+#[tokio::test]
+async fn management_model_stream_retains_selected_identity_until_completion_and_rechecks_revocation()
+ {
+    let Some(mut environment) = Environment::create_command().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let account = environment.account(None).await;
+    let key_id = format!("key_{}", uuid::Uuid::new_v4().simple());
+    environment
+        .client_key(&key_id, "sk-management-bound-fixture")
+        .await;
+    let bound_nested = environment
+        .directory
+        .path()
+        .join("management-bound-model.jsonl");
+    let bound_calls = environment.directory.path().join("management-bound.jsonl");
+    let unbound_nested = environment
+        .directory
+        .path()
+        .join("management-unbound-model.jsonl");
+    let model_grant = account_grant("models");
+    let bound_credentials = account_grant("accounts");
+    let unbound_credentials = account_grant("accounts");
+    let nested_request = json!({
+        "stream":true,
+        "request":{
+            "client_key_id":key_id,
+            "model":"plugin-model",
+            "protocol":"openai",
+            "operation":"generate",
+            "provider":"example",
+            "account_id":account.as_str()
+        },
+        "body":{"model":"plugin-model","input":"bound management"}
+    });
+    let model_route = json!({
+        "routes":[{
+            "method":"POST",
+            "path":"echo",
+            "request_content_types":["application/octet-stream"],
+            "response_content_types":["application/octet-stream"]
+        }]
+    });
+    environment
+        .install_provider(
+            json!({
+                "provider_id":"management-source",
+                "management_registration":model_route,
+                "management_nested_model_fixture":nested_request,
+                "management_nested_model_marker":bound_nested,
+                "nested_stream_trace_marker":environment.directory.path().join("management-stream.jsonl"),
+                "management_marker":bound_calls,
+            }),
+            vec![model_grant.clone(), bound_credentials],
+        )
+        .await;
+    let mut denied_request = nested_request;
+    denied_request["stream"] = json!(false);
+    denied_request["request"]
+        .as_object_mut()
+        .unwrap()
+        .remove("client_key_id");
+    denied_request["expect_error"] = json!(true);
+    environment
+        .install_provider(
+            json!({
+                "provider_id":"management-unbound",
+                "management_registration":model_route,
+                "management_nested_model_fixture":denied_request,
+                "management_nested_model_marker":unbound_nested,
+            }),
+            vec![model_grant, unbound_credentials],
+        )
+        .await;
+    environment
+        .install_provider(
+            json!({"provider_id":"example","generation_marker":"management-target"}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let (runtime, core) = environment.runtime().await;
+    let service = PluginManagementService::new(
+        runtime.clone(),
+        environment.store.admin_ports().plugins(),
+        core.snapshots(),
+    );
+    let instances = environment
+        .store
+        .admin_ports()
+        .plugins()
+        .load_instances()
+        .await
+        .unwrap();
+    let bound_id = &instances
+        .instances
+        .iter()
+        .find(|instance| instance.configuration["provider_id"] == "management-source")
+        .unwrap()
+        .id;
+    let unbound_id = &instances
+        .instances
+        .iter()
+        .find(|instance| instance.configuration["provider_id"] == "management-unbound")
+        .unwrap()
+        .id;
+    let views = service.views().await.unwrap();
+    let bound = &views
+        .iter()
+        .find(|view| &view.target.instance_id == bound_id)
+        .unwrap()
+        .target;
+    let unbound = &views
+        .iter()
+        .find(|view| &view.target.instance_id == unbound_id)
+        .unwrap()
+        .target;
+    environment.store.start_command_line_writes().unwrap();
+    assert_eq!(
+        tokio::time::timeout(
+            std::time::Duration::from_secs(20),
+            service.handle(bound, request()),
+        )
+        .await
+        .unwrap_or_else(|_| {
+            let trace = std::fs::read_to_string(
+                environment.directory.path().join("management-stream.jsonl"),
+            );
+            panic!("管理模型流未完成：{trace:?}");
+        })
+        .unwrap()
+        .status,
+        200,
+    );
+    assert_eq!(
+        service.handle(unbound, request()).await.unwrap().status,
+        200
+    );
+    assert_eq!(
+        std::fs::read_to_string(&bound_nested)
+            .unwrap()
+            .lines()
+            .count(),
+        1
+    );
+    let unbound_marker: Value =
+        serde_json::from_str(std::fs::read_to_string(&unbound_nested).unwrap().trim()).unwrap();
+    assert_eq!(unbound_marker["error"], "invalid_input");
+    assert_eq!(
+        environment.wait_for_bound_model_requests(&key_id, 1).await,
+        vec![("plugin_bound_model".into(), bound_id.clone())]
+    );
+
+    let (revision, _) = environment
+        .store
+        .admin_ports()
+        .client_keys()
+        .set_client_key_enabled(
+            SetClientKeyEnabled {
+                id: ClientApiKeyId::new(key_id).unwrap(),
+                enabled: false,
+            },
+            &mutation(),
+        )
+        .await
+        .unwrap();
+    core.snapshot_control()
+        .publish_committed(ConfigRevision::new(revision.get()).unwrap())
+        .await;
+    assert!(service.handle(bound, request()).await.is_err());
+    assert_eq!(
+        std::fs::read_to_string(bound_calls)
+            .unwrap()
+            .lines()
+            .count(),
+        2,
+        "Key revocation is checked by the model callback, not before entering the plugin"
+    );
+
+    drop(service);
+    drop(core);
+    drop(runtime);
+    environment
+        .store
+        .shutdown_command_line_writes()
+        .await
+        .unwrap();
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn management_resources_and_raw_calls_are_version_bound_and_revocation_removes_pages() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let marker = environment.directory.path().join("management-calls.jsonl");
+    install(
+        &environment,
+        json!({"management_registration":registration(),"management_marker":marker}),
+    )
+    .await;
+    let (runtime, core) = environment.runtime().await;
+    let service = PluginManagementService::new(
+        runtime.clone(),
+        environment.store.admin_ports().plugins(),
+        core.snapshots(),
+    );
+    let views = service.views().await.unwrap();
+    assert_eq!(views.len(), 1);
+    assert_eq!(views[0].pages[0].id, "overview");
+    assert_eq!(
+        views[0].pages[0].description.as_deref(),
+        Some("查看插件状态与调用结果")
+    );
+    assert_eq!(views[0].resources.len(), 3);
+    let target = &views[0].target;
+    assert_eq!(
+        service
+            .resource(target, "ui/index.html", false)
+            .await
+            .unwrap()
+            .content_type,
+        "text/html"
+    );
+    assert!(
+        service
+            .resource(target, "ui/index.html", true)
+            .await
+            .is_err()
+    );
+    assert_eq!(
+        service
+            .resource(target, "ui/public.svg", true)
+            .await
+            .unwrap()
+            .body
+            .as_ref(),
+        b"<svg xmlns=\"http://www.w3.org/2000/svg\"/>"
+    );
+    for path in [
+        "../bin/worker",
+        "ui/../app.js",
+        "%2e%2e/bin/worker",
+        "ui//index.html",
+        "bin/worker",
+    ] {
+        assert!(service.resource(target, path, false).await.is_err());
+    }
+    assert!(!marker.exists(), "静态资源读取不能执行插件 handler");
+    let response = service.handle(target, request()).await.unwrap();
+    assert_eq!(response.status, 200);
+    assert_eq!(response.body.as_ref(), &[0, 255, 128, 10]);
+    let mut invalid = request();
+    invalid.content_type = Some("text/html".into());
+    assert!(service.handle(target, invalid).await.is_err());
+    let mut invalid = request();
+    invalid.path = "unregistered".into();
+    assert!(service.handle(target, invalid).await.is_err());
+    assert_eq!(std::fs::read_to_string(&marker).unwrap().lines().count(), 1);
+    let store = environment.store.admin_ports().plugins();
+    let mut snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.remove(0);
+    instance.enabled = false;
+    store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    // 模拟持久撤销已提交但旧发布视图仍存在；页面与资源都不能继续使用旧权限。
+    assert!(service.views().await.unwrap().is_empty());
+    assert!(service.handle(target, request()).await.is_err());
+    assert!(
+        service
+            .resource(target, "ui/public.svg", true)
+            .await
+            .is_err()
+    );
+    assert_eq!(std::fs::read_to_string(&marker).unwrap().lines().count(), 1);
+    drop(service);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/management/registration.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/management/registration.rs
new file mode 100644
index 000000000..11baa9ce0
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/management/registration.rs
@@ -0,0 +1,77 @@
+use gateway_admin::ports::plugins::PluginPreparation;
+use serde_json::json;
+
+use super::{Environment, install, registration};
+
+#[tokio::test]
+async fn candidate_rejects_undeclared_resources_invalid_routes_and_missing_public_grants() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    install(
+        &environment,
+        json!({"management_registration":registration()}),
+    )
+    .await;
+    let (runtime, core) = environment.runtime().await;
+    let source = environment
+        .store
+        .admin_ports()
+        .plugins()
+        .load_instances()
+        .await
+        .unwrap();
+    for (field, value) in [
+        (
+            "routes",
+            json!([{"method":"CONNECT","path":"tunnel","response_content_types":["application/json"]}]),
+        ),
+        (
+            "routes",
+            json!([{"method":"GET","path":"../admin","response_content_types":["application/json"]}]),
+        ),
+        (
+            "routes",
+            json!([{"method":"GET","path":"ok","response_content_types":["text/html\r\nSet-Cookie: attack"]}]),
+        ),
+        ("resources", json!([{"path":"bin/worker"}])),
+        (
+            "pages",
+            json!([{"id":"bad","title":"Bad","entry":"ui/app.js"}]),
+        ),
+        (
+            "pages",
+            json!([{"id":"bad","title":"Bad","description":" ","entry":"ui/index.html"}]),
+        ),
+        (
+            "pages",
+            json!([{"id":"bad","title":"Bad","description":"line\ncontrol","entry":"ui/index.html"}]),
+        ),
+        (
+            "pages",
+            json!([{"id":"bad","title":"Bad","description":"x".repeat(513),"entry":"ui/index.html"}]),
+        ),
+    ] {
+        let mut candidate = source.clone();
+        candidate.instances[0].configuration["management_registration"][field] = value;
+        assert!(
+            runtime
+                .prepare(source.config_revision, candidate)
+                .await
+                .is_err(),
+            "{field}"
+        );
+    }
+    let mut candidate = source.clone();
+    candidate.instances[0].grants.clear();
+    assert!(
+        runtime
+            .prepare(source.config_revision, candidate)
+            .await
+            .is_err()
+    );
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/mod.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/mod.rs
new file mode 100644
index 000000000..22dd2c98e
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/mod.rs
@@ -0,0 +1,3 @@
+mod command_line;
+mod management;
+mod provider;
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/authorization.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/authorization.rs
new file mode 100644
index 000000000..170702f1c
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/authorization.rs
@@ -0,0 +1,599 @@
+use std::{sync::Arc, time::Duration};
+
+use futures::future::BoxFuture;
+use gateway_admin::{
+    CredentialsService,
+    model::{
+        MutationActor, MutationContext,
+        provider_credentials::{
+            AuthorizationPollResult, PollAuthorization, PrepareCredentialRefresh,
+            PreparedAuthorizationPoll, StartAuthorization,
+        },
+    },
+    ports::provider::ProviderAdminErrorKind,
+};
+use gateway_core::{
+    account::{ProviderAccountId, ProviderAccountUpdate},
+    provider_ports::{
+        NewOAuthPendingFlow, OAuthPendingBinding, OAuthPendingClaimOutcome,
+        OAuthPendingConsumeOutcome, OAuthPendingFlowPort, OAuthPendingPutOutcome,
+        OAuthPendingReleaseOutcome, ProviderStoreError, ProviderStorePorts,
+    },
+    routing::ProviderKind,
+};
+use serde_json::json;
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+fn owner(name: &str) -> MutationContext {
+    MutationContext {
+        actor: MutationActor::AdminSession {
+            admin_user_id: name.into(),
+        },
+        request_id: uuid::Uuid::new_v4().to_string(),
+    }
+}
+
+async fn environment() -> Option<Environment> {
+    let environment = Environment::create().await?;
+    environment.administrator("first-admin").await;
+    environment.administrator("second-admin").await;
+    Some(environment)
+}
+
+fn start(reauthorization: Option<ProviderAccountId>) -> StartAuthorization {
+    StartAuthorization {
+        input: gateway_admin::model::provider_credentials::ProviderDocument::new(
+            gateway_core::account::OpaqueProviderData::new(serde_json::Map::new()),
+        ),
+        context: owner("first-admin"),
+        name: "login account".into(),
+        reauthorization,
+        outbound_proxy: None,
+    }
+}
+
+fn poll(flow: &str, ready: bool) -> PollAuthorization {
+    PollAuthorization {
+        context: owner("first-admin"),
+        flow_id: flow.into(),
+        callback_url: ready.then(|| "ready".into()),
+        settings: None,
+    }
+}
+
+fn service(
+    environment: &Environment,
+    runtime: &gateway_plugin_runtime::PluginRuntime,
+    core: &gateway_core::CoreBundle,
+) -> CredentialsService {
+    let ports = environment.store.admin_ports();
+    CredentialsService::new(
+        runtime.admin_registry(core.snapshots()),
+        ports.accounts(),
+        ports.proxies(),
+        core.snapshot_control(),
+    )
+}
+
+#[tokio::test]
+async fn login_polls_with_owner_isolation_and_commits_all_accounts_once() {
+    let Some(environment) = environment().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment.provider(json!({"login_accounts":[
+        {"name":"first", "authentication_kind":"api_key", "material":{"key":"first-test-key"}},
+        {"name":"second", "authentication_kind":"api_key", "material":{"key":"second-test-key"}}
+    ]}), vec![account_grant("accounts")]).await;
+    let credentials = service(&environment, &runtime, &core);
+    let provider = credentials
+        .for_provider(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let before = core.snapshots().acquire().unwrap().revision();
+    let started = provider.start_authorization(start(None)).await.unwrap();
+    let mut intruder = poll(&started.flow_id, true);
+    intruder.context = owner("second-admin");
+    assert!(
+        credentials
+            .poll_authorization(&ProviderKind::new("example").unwrap(), intruder)
+            .await
+            .is_err()
+    );
+    for _ in 0..2 {
+        assert_eq!(
+            credentials
+                .poll_authorization(
+                    &ProviderKind::new("example").unwrap(),
+                    poll(&started.flow_id, false)
+                )
+                .await
+                .unwrap(),
+            AuthorizationPollResult::Pending {
+                retry_after: Duration::from_secs(1)
+            }
+        );
+    }
+    assert_eq!(core.snapshots().acquire().unwrap().revision(), before);
+    let AuthorizationPollResult::Complete(result) = credentials
+        .poll_authorization(
+            &ProviderKind::new("example").unwrap(),
+            poll(&started.flow_id, true),
+        )
+        .await
+        .unwrap()
+    else {
+        panic!("expected completed login");
+    };
+    assert_eq!(result.accounts.len(), 2);
+    for (index, account) in result.accounts.iter().enumerate() {
+        assert_eq!(account.credential_revision.unwrap().get(), 1);
+        let loaded = environment
+            .store
+            .provider_ports()
+            .accounts()
+            .load_current_credential(&account.account_id)
+            .await
+            .unwrap();
+        assert_eq!(
+            loaded.credential.expose_to_provider()["key"],
+            if index == 0 {
+                "first-test-key"
+            } else {
+                "second-test-key"
+            }
+        );
+    }
+    assert!(core.snapshots().acquire().unwrap().revision().get() > before.get());
+    assert_eq!(
+        credentials
+            .poll_authorization(
+                &ProviderKind::new("example").unwrap(),
+                poll(&started.flow_id, true)
+            )
+            .await
+            .unwrap(),
+        AuthorizationPollResult::Complete(result)
+    );
+    drop(provider);
+    drop(credentials);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn encrypted_login_survives_restart_but_rejects_changed_plugin_configuration() {
+    let Some(environment) = environment().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(json!({}), vec![account_grant("accounts")])
+        .await;
+    let credentials = service(&environment, &runtime, &core);
+    let kind = ProviderKind::new("example").unwrap();
+    let provider = credentials.for_provider(&kind).unwrap();
+    let survives = provider.start_authorization(start(None)).await.unwrap();
+    let invalidated = provider.start_authorization(start(None)).await.unwrap();
+    drop(provider);
+    drop(credentials);
+    drop(core);
+    drop(runtime);
+    let (runtime, core) = environment.runtime().await;
+    let credentials = service(&environment, &runtime, &core);
+    let provider = credentials.for_provider(&kind).unwrap();
+    assert!(matches!(
+        credentials
+            .poll_authorization(
+                &ProviderKind::new("example").unwrap(),
+                poll(&survives.flow_id, true)
+            )
+            .await
+            .unwrap(),
+        AuthorizationPollResult::Complete(_)
+    ));
+    drop(provider);
+    drop(credentials);
+    drop(core);
+    drop(runtime);
+    let store = environment.store.admin_ports().plugins();
+    let mut snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.remove(0);
+    instance.configuration = json!({"new_configuration":true});
+    store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    let (runtime, core) = environment.runtime().await;
+    let credentials = service(&environment, &runtime, &core);
+    let provider = credentials.for_provider(&kind).unwrap();
+    assert!(
+        credentials
+            .poll_authorization(
+                &ProviderKind::new("example").unwrap(),
+                poll(&invalidated.flow_id, true)
+            )
+            .await
+            .is_err()
+    );
+    drop(provider);
+    drop(credentials);
+    drop(core);
+    drop(runtime);
+    drop(store);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn claimed_login_blocks_other_pollers_and_reauthorization_preserves_latest_profile() {
+    let Some(environment) = environment().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(json!({}), vec![account_grant("accounts")])
+        .await;
+    let id = environment.account(None).await;
+    let credentials = service(&environment, &runtime, &core);
+    let kind = ProviderKind::new("example").unwrap();
+    let provider = credentials.for_provider(&kind).unwrap();
+    let started = provider
+        .start_authorization(start(Some(id.clone())))
+        .await
+        .unwrap();
+    let registry = runtime.admin_registry(core.snapshots());
+    let adapter = registry.require(&kind).unwrap();
+    let prepared = adapter
+        .poll_authorization(poll(&started.flow_id, true))
+        .await
+        .unwrap();
+    assert!(matches!(prepared, PreparedAuthorizationPoll::Complete(_)));
+    let error = adapter
+        .poll_authorization(poll(&started.flow_id, true))
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), ProviderAdminErrorKind::Conflict);
+    let account = environment
+        .store
+        .admin_ports()
+        .accounts()
+        .credential_details(&kind, &id)
+        .await
+        .unwrap()
+        .unwrap()
+        .credential;
+    assert_eq!(
+        adapter
+            .prepare_refresh(PrepareCredentialRefresh { account })
+            .await
+            .unwrap_err()
+            .kind(),
+        ProviderAdminErrorKind::Conflict
+    );
+    environment
+        .store
+        .provider_ports()
+        .accounts()
+        .update_account(ProviderAccountUpdate {
+            account_id: id.clone(),
+            name: "administrator edited during login".into(),
+            email: None,
+            plan_type: None,
+        })
+        .await
+        .unwrap();
+    // 丢弃尚未提交的结果同时释放登录 claim 与账号 lease，下一次轮询可接续。
+    drop(prepared);
+    let result = tokio::time::timeout(Duration::from_secs(3), async {
+        loop {
+            match adapter
+                .poll_authorization(poll(&started.flow_id, false))
+                .await
+            {
+                Ok(result) => break result,
+                Err(error) if error.kind() == ProviderAdminErrorKind::Conflict => {
+                    tokio::time::sleep(Duration::from_millis(20)).await
+                }
+                Err(error) => panic!("poll after release failed: {error:?}"),
+            }
+        }
+    })
+    .await
+    .unwrap();
+    assert!(matches!(result, PreparedAuthorizationPoll::Pending { .. }));
+    let AuthorizationPollResult::Complete(result) = credentials
+        .poll_authorization(
+            &ProviderKind::new("example").unwrap(),
+            poll(&started.flow_id, true),
+        )
+        .await
+        .unwrap()
+    else {
+        panic!("expected complete");
+    };
+    assert_eq!(result.accounts[0].account_id, id);
+    assert_eq!(result.accounts[0].credential_revision.unwrap().get(), 2);
+    let loaded = environment
+        .store
+        .provider_ports()
+        .accounts()
+        .load_current_credential(&id)
+        .await
+        .unwrap();
+    assert_eq!(loaded.account.name(), "administrator edited during login");
+    assert_eq!(
+        loaded.credential.expose_to_provider()["key"],
+        "login-test-only"
+    );
+    drop(adapter);
+    drop(registry);
+    drop(provider);
+    drop(credentials);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn invalid_login_results_cannot_commit_accounts() {
+    for configuration in [
+        json!({"login_accounts":[]}),
+        json!({"login_retry_ms":0}),
+        json!({"login_ttl_ms":-1}),
+    ] {
+        let Some(environment) = environment().await else {
+            eprintln!("SKIP: plugin integration environment absent");
+            return;
+        };
+        let (runtime, core) = environment
+            .provider(configuration.clone(), vec![account_grant("accounts")])
+            .await;
+        let credentials = service(&environment, &runtime, &core);
+        let provider = credentials
+            .for_provider(&ProviderKind::new("example").unwrap())
+            .unwrap();
+        let revision = core.snapshots().acquire().unwrap().revision();
+        match provider.start_authorization(start(None)).await {
+            Ok(started) => {
+                for _ in 0..2 {
+                    assert!(
+                        credentials
+                            .poll_authorization(
+                                &ProviderKind::new("example").unwrap(),
+                                poll(
+                                    &started.flow_id,
+                                    configuration.get("login_accounts").is_some()
+                                )
+                            )
+                            .await
+                            .is_err()
+                    );
+                }
+            }
+            Err(_) => assert!(configuration.get("login_ttl_ms").is_some()),
+        }
+        assert_eq!(core.snapshots().acquire().unwrap().revision(), revision);
+        drop(provider);
+        drop(credentials);
+        drop(core);
+        drop(runtime);
+        environment.close().await;
+    }
+}
+
+#[tokio::test]
+async fn expired_login_cannot_be_reclaimed_or_commit_credentials() {
+    let Some(environment) = environment().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(
+            json!({"login_ttl_ms":1000}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let credentials = service(&environment, &runtime, &core);
+    let kind = ProviderKind::new("example").unwrap();
+    let provider = credentials.for_provider(&kind).unwrap();
+    let before = core.snapshots().acquire().unwrap().revision();
+    let started = provider.start_authorization(start(None)).await.unwrap();
+    let remaining = (started.expires_at - chrono::Utc::now())
+        .to_std()
+        .unwrap_or_default();
+    tokio::time::sleep(remaining + Duration::from_millis(30)).await;
+    let registry = runtime.admin_registry(core.snapshots());
+    let adapter = registry.require(&kind).unwrap();
+    assert_eq!(
+        adapter
+            .poll_authorization(poll(&started.flow_id, true))
+            .await
+            .err()
+            .unwrap()
+            .kind(),
+        ProviderAdminErrorKind::NotFound
+    );
+    assert_eq!(core.snapshots().acquire().unwrap().revision(), before);
+    drop(adapter);
+    drop(registry);
+    drop(provider);
+    drop(credentials);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+struct PausedConsumption {
+    inner: Arc<dyn OAuthPendingFlowPort>,
+    reached: tokio::sync::Notify,
+}
+
+impl OAuthPendingFlowPort for PausedConsumption {
+    fn put_if_absent(
+        &self,
+        flow: NewOAuthPendingFlow,
+    ) -> BoxFuture<'_, Result<OAuthPendingPutOutcome, ProviderStoreError>> {
+        self.inner.put_if_absent(flow)
+    }
+    fn claim_if_owner<'a>(
+        &'a self,
+        provider: &'a ProviderKind,
+        flow: &'a OAuthPendingBinding,
+        owner: &'a OAuthPendingBinding,
+        claim: &'a OAuthPendingBinding,
+        ttl: Duration,
+    ) -> BoxFuture<'a, Result<OAuthPendingClaimOutcome, ProviderStoreError>> {
+        self.inner.claim_if_owner(provider, flow, owner, claim, ttl)
+    }
+    fn release_claim<'a>(
+        &'a self,
+        provider: &'a ProviderKind,
+        flow: &'a OAuthPendingBinding,
+        owner: &'a OAuthPendingBinding,
+        claim: &'a OAuthPendingBinding,
+    ) -> BoxFuture<'a, Result<OAuthPendingReleaseOutcome, ProviderStoreError>> {
+        self.inner.release_claim(provider, flow, owner, claim)
+    }
+    fn consume_claim<'a>(
+        &'a self,
+        _: &'a ProviderKind,
+        _: &'a OAuthPendingBinding,
+        _: &'a OAuthPendingBinding,
+        _: &'a OAuthPendingBinding,
+    ) -> BoxFuture<'a, Result<OAuthPendingConsumeOutcome, ProviderStoreError>> {
+        Box::pin(async move {
+            self.reached.notify_one();
+            // 精确停在 PostgreSQL 提交之后；中断此 future 模拟宿主丢失后续结算。
+            std::future::pending().await
+        })
+    }
+}
+
+#[tokio::test]
+async fn committed_login_recovers_after_interruption_before_redis_consumption_and_plugin_shutdown()
+{
+    let Some(environment) = environment().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(json!({}), vec![account_grant("accounts")])
+        .await;
+    let credentials = service(&environment, &runtime, &core);
+    let kind = ProviderKind::new("example").unwrap();
+    let started = credentials
+        .for_provider(&kind)
+        .unwrap()
+        .start_authorization(start(None))
+        .await
+        .unwrap();
+    drop(credentials);
+    drop(core);
+    drop(runtime);
+    let ports = environment.store.provider_ports();
+    let pending = Arc::new(PausedConsumption {
+        inner: ports.oauth_pending(),
+        reached: tokio::sync::Notify::new(),
+    });
+    let injected = ProviderStorePorts::new(
+        ports.accounts(),
+        ports.leases(),
+        ports.session_affinity(),
+        ports.session_exclusions(),
+        ports.catalog_cache(),
+        ports.artifact_profiles(),
+        ports.credential_state(),
+        ports.cooldowns(),
+        ports.runtime_policy(),
+        pending.clone(),
+    );
+    let (runtime, core) = environment.runtime_with_ports(injected).await;
+    let credentials = Arc::new(service(&environment, &runtime, &core));
+    let request = poll(&started.flow_id, true);
+    let operation = {
+        let credentials = credentials.clone();
+        let kind = kind.clone();
+        tokio::spawn(async move { credentials.poll_authorization(&kind, request).await })
+    };
+    tokio::time::timeout(Duration::from_secs(10), pending.reached.notified())
+        .await
+        .unwrap();
+    let key = gateway_admin::model::provider_credentials::AuthorizationReceiptKey::new(
+        kind.clone(),
+        &started.flow_id,
+        &owner("first-admin"),
+    )
+    .unwrap();
+    let receipt = environment
+        .store
+        .admin_ports()
+        .accounts()
+        .authorization_receipt(&key)
+        .await
+        .unwrap()
+        .unwrap();
+    assert!(core.snapshots().acquire().unwrap().revision().get() < receipt.config_revision.get());
+    operation.abort();
+    assert!(operation.await.unwrap_err().is_cancelled());
+    let claim = pending
+        .inner
+        .claim_if_owner(
+            &kind,
+            &OAuthPendingBinding::try_new(&started.flow_id).unwrap(),
+            &OAuthPendingBinding::try_new("admin_session:first-admin").unwrap(),
+            &OAuthPendingBinding::try_new("another-claim").unwrap(),
+            Duration::from_secs(5),
+        )
+        .await
+        .unwrap();
+    assert_eq!(claim, OAuthPendingClaimOutcome::InProgress);
+    assert_eq!(
+        credentials
+            .poll_authorization(&kind, poll(&started.flow_id, true))
+            .await
+            .unwrap(),
+        AuthorizationPollResult::Complete(receipt.clone())
+    );
+    assert_eq!(
+        core.snapshots().acquire().unwrap().revision().get(),
+        receipt.config_revision.get()
+    );
+    drop(credentials);
+    drop(core);
+    drop(runtime);
+    drop(pending);
+    drop(ports);
+    let store = environment.store.admin_ports().plugins();
+    let mut snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.remove(0);
+    instance.enabled = false;
+    store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    let (runtime, core) = environment.runtime().await;
+    let credentials = service(&environment, &runtime, &core);
+    assert!(credentials.for_provider(&kind).is_err());
+    assert_eq!(
+        credentials
+            .poll_authorization(&kind, poll(&started.flow_id, true))
+            .await
+            .unwrap(),
+        AuthorizationPollResult::Complete(receipt.clone())
+    );
+    let account = environment
+        .store
+        .provider_ports()
+        .accounts()
+        .load_current_credential(&receipt.accounts[0].account_id)
+        .await
+        .unwrap();
+    assert_eq!(account.account.revision().get(), 1);
+    drop(credentials);
+    drop(core);
+    drop(runtime);
+    drop(store);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/billing.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/billing.rs
new file mode 100644
index 000000000..cc741bbcc
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/billing.rs
@@ -0,0 +1,294 @@
+use std::{
+    num::NonZeroU32,
+    sync::Arc,
+    time::{Duration, SystemTime},
+};
+
+use futures::StreamExt as _;
+use gateway_admin::{
+    model::observability::{CurrencyCost, ProviderBillingInput},
+    ports::plugins::PluginPreparation,
+};
+use gateway_core::{
+    account::{AccountSelectionPolicy, RotationStrategy},
+    engine::{
+        AccountAttemptContext, AttemptContext, ModelRequestId, RequestAttemptContext,
+        provider::ProviderRequest,
+    },
+    event::{GatewayEvent, ProviderEvent},
+    lifecycle::CancellationToken,
+    metering::PricingOverrides,
+    policy::ClientApiKeyId,
+    routing::{ProviderKind, PublicModelId, RoutingContext, UpstreamModelId},
+};
+use serde_json::{Value, json};
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+fn configuration() -> Value {
+    json!({
+        "billing":{"rule":"token_v1", "prices":{"plugin-model":{
+            "standard":{"input":"1", "output":"2", "cache_read":"0.5", "cache_write":"1.5"}
+        }}},
+        "execution_events":[
+            {"facts":[{"type":"started", "id":"response-billing", "model":"untrusted-response-model"}]},
+            {"facts":[{"type":"billable_usage", "band":"standard", "usage":{
+                "input_tokens":1000, "output_tokens":500, "cached_tokens":100, "cache_write_tokens":50
+            }}]},
+            {"facts":[{"type":"completed", "id":"response-billing", "model":"untrusted-response-model", "reason":"stop"}]}
+        ]
+    })
+}
+
+async fn execute(
+    runtime: &gateway_plugin_runtime::PluginRuntime,
+    core: &gateway_core::CoreBundle,
+    pricing: PricingOverrides,
+) -> Vec<ProviderEvent> {
+    let kind = ProviderKind::new("example").unwrap();
+    let snapshot = core.snapshots().acquire().unwrap();
+    let admin = runtime
+        .admin_registry(core.snapshots())
+        .require(&kind)
+        .unwrap();
+    let operation = admin
+        .connection_test_operation(&UpstreamModelId::new("plugin-model").unwrap(), "billing")
+        .await
+        .unwrap();
+    let plan = snapshot
+        .plan(
+            &PublicModelId::new("plugin-model").unwrap(),
+            &operation,
+            snapshot.all_account_scope(),
+            &RoutingContext::default(),
+        )
+        .unwrap();
+    let registry = runtime
+        .provider_registry()
+        .for_extensions(snapshot.extensions())
+        .unwrap();
+    let provider = registry.get(&kind).unwrap();
+    let context = AttemptContext::new(
+        RequestAttemptContext::new(
+            ModelRequestId::new("req_plugin_billing").unwrap(),
+            ClientApiKeyId::new("key_plugin_billing").unwrap(),
+        )
+        .with_pricing(Arc::new(pricing)),
+        NonZeroU32::new(1).unwrap(),
+        SystemTime::now() + Duration::from_secs(15),
+        AccountSelectionPolicy::new(
+            RotationStrategy::RoundRobin,
+            NonZeroU32::new(1).unwrap(),
+            Duration::ZERO,
+        ),
+        AccountAttemptContext::default().with_account_scope(snapshot.all_account_scope()),
+        None,
+        CancellationToken::new(),
+    );
+    Arc::clone(provider)
+        .execute(
+            ProviderRequest::new(operation, plan.candidates()[0].clone()),
+            context,
+        )
+        .await
+        .unwrap()
+        .map(|event| event.unwrap())
+        .collect()
+        .await
+}
+
+#[tokio::test]
+async fn token_pricing_uses_sent_model_and_frozen_prices_without_changing_usage() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    environment.account(None).await;
+    let (runtime, core) = environment
+        .provider(configuration(), vec![account_grant("accounts")])
+        .await;
+    let registry = runtime.admin_registry(core.snapshots());
+    let frozen_admin = registry.freeze().unwrap();
+    assert_eq!(
+        String::from(
+            frozen_admin.pricing_catalog().unwrap()["example"]["plugin-model"].bands["standard"]
+                .input
+        ),
+        "1"
+    );
+    assert!(
+        frozen_admin
+            .calculated_billing(
+                &ProviderKind::new("example").unwrap(),
+                &ProviderBillingInput {
+                    upstream_model_id: "plugin-model".to_owned(),
+                    service_tier: None,
+                    input_tokens: Some(1_000),
+                    output_tokens: Some(500),
+                    cached_tokens: Some(100),
+                    cache_write_tokens: Some(50),
+                    total: CurrencyCost {
+                        currency: "USD".to_owned(),
+                        amount: "0.001975".parse().unwrap(),
+                    },
+                },
+            )
+            .unwrap()
+            .is_none(),
+        "current plugin pricing must not reconstruct a request without its persisted snapshot"
+    );
+    let prices = serde_json::from_value(json!({"example":{"plugin-model":{
+        "multiplierBps":20000,
+        "bands":{"standard":{"input":"3","output":"4","cacheRead":"0.5","cacheWrite":"1.5"}}
+    }}}))
+    .unwrap();
+    let events = execute(&runtime, &core, prices).await;
+    let facts: Vec<_> = events
+        .iter()
+        .flat_map(ProviderEvent::canonical_facts)
+        .collect();
+    let usage = facts
+        .iter()
+        .find_map(|event| match event {
+            GatewayEvent::Usage(usage) => Some(usage),
+            _ => None,
+        })
+        .unwrap();
+    assert_eq!(
+        (
+            usage.input_tokens,
+            usage.output_tokens,
+            usage.cached_tokens,
+            usage.cache_write_tokens
+        ),
+        (Some(1000), Some(500), Some(100), Some(50))
+    );
+    let cost = facts
+        .iter()
+        .find_map(|event| match event {
+            GatewayEvent::CalculatedCost(cost) => Some(cost),
+            _ => None,
+        })
+        .unwrap();
+    assert_eq!(cost.total().amount().canonical(), "0.00935");
+    let estimate = (*cost).clone().into_estimate();
+    let breakdown = estimate.breakdown().unwrap();
+    // Core 明细保存应用自定义倍率后的有效单价，原始价目仍在冻结配置中。
+    assert_eq!(
+        breakdown.input_price_per_million().amount().canonical(),
+        "6"
+    );
+    assert_eq!(breakdown.custom_multiplier_bps(), 20000);
+
+    let store = environment.store.admin_ports().plugins();
+    let mut snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.remove(0);
+    instance.configuration["billing"]["prices"]["plugin-model"]["standard"]["input"] = json!("100");
+    store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    let revision = store.load_instances().await.unwrap().config_revision;
+    core.snapshot_control()
+        .publish_committed(gateway_core::routing::ConfigRevision::new(revision.get()).unwrap())
+        .await;
+    assert_eq!(
+        String::from(
+            registry.pricing_catalog().unwrap()["example"]["plugin-model"].bands["standard"].input
+        ),
+        "100"
+    );
+    assert_eq!(
+        String::from(
+            frozen_admin.pricing_catalog().unwrap()["example"]["plugin-model"].bands["standard"]
+                .input
+        ),
+        "1"
+    );
+    assert_eq!(cost.total().amount().canonical(), "0.00935");
+    drop(frozen_admin);
+    drop(registry);
+    drop(store);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn missing_usage_unknown_bands_and_non_token_charges_keep_cost_unknown() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    environment.account(None).await;
+    let mut config = configuration();
+    config["execution_events"] = json!([
+        {"facts":[{"type":"started","id":"response-unknown","model":"plugin-model"}]},
+        {"facts":[{"type":"billable_usage","band":"standard","usage":{"input_tokens":1,"output_tokens":1}}]},
+        {"facts":[{"type":"billable_usage","band":"flex","usage":{"input_tokens":1,"output_tokens":1,"cached_tokens":0,"cache_write_tokens":0}}]},
+        {"facts":[{"type":"billable_usage","band":"standard","usage":{"input_tokens":1,"output_tokens":1,"cached_tokens":2,"cache_write_tokens":0}}]},
+        {"facts":[{"type":"billable_usage","band":"standard","usage":{"input_tokens":1,"output_tokens":1,"cached_tokens":0,"cache_write_tokens":0,"image_input_tokens":1}}]},
+        {"facts":[{"type":"completed","id":"response-unknown","model":"plugin-model","reason":"stop"}]}
+    ]);
+    let (runtime, core) = environment
+        .provider(config, vec![account_grant("accounts")])
+        .await;
+    let events = execute(&runtime, &core, PricingOverrides::new()).await;
+    assert_eq!(
+        events
+            .iter()
+            .flat_map(ProviderEvent::canonical_facts)
+            .filter(|event| matches!(event, GatewayEvent::Usage(_)))
+            .count(),
+        4
+    );
+    assert!(
+        !events
+            .iter()
+            .flat_map(ProviderEvent::canonical_facts)
+            .any(|event| matches!(event, GatewayEvent::CalculatedCost(_)))
+    );
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn invalid_price_data_never_replaces_the_published_catalog() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(configuration(), vec![account_grant("accounts")])
+        .await;
+    let registry = runtime.admin_registry(core.snapshots());
+    let before = registry.pricing_catalog().unwrap();
+    let snapshot = environment
+        .store
+        .admin_ports()
+        .plugins()
+        .load_instances()
+        .await
+        .unwrap();
+    for invalid in [
+        json!("-1"),
+        json!("0.00001"),
+        json!("1000001"),
+        json!("NaN"),
+    ] {
+        let mut candidate = snapshot.clone();
+        candidate.instances[0].configuration["billing"]["prices"]["plugin-model"]["standard"]["input"] =
+            invalid;
+        assert!(
+            PluginPreparation::prepare(runtime.as_ref(), candidate.config_revision, candidate)
+                .await
+                .is_err()
+        );
+        assert_eq!(registry.pricing_catalog().unwrap(), before);
+    }
+    drop(registry);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/capabilities.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/capabilities.rs
new file mode 100644
index 000000000..85e873dc7
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/capabilities.rs
@@ -0,0 +1,426 @@
+use gateway_admin::{
+    CredentialsService,
+    model::{
+        AdminErrorKind,
+        provider_capabilities::AuthorizationCompletion,
+        provider_credentials::{
+            AuthorizationPollResult, PollAuthorization, ProviderDocument, StartAuthorization,
+        },
+    },
+    ports::plugins::PluginPreparation,
+};
+use gateway_core::{account::OpaqueProviderData, routing::ProviderKind};
+use serde_json::{Value, json};
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+fn start(input: Value) -> StartAuthorization {
+    StartAuthorization {
+        context: mutation(),
+        name: "form login".into(),
+        reauthorization: None,
+        outbound_proxy: None,
+        input: ProviderDocument::new(OpaqueProviderData::new(input.as_object().unwrap().clone())),
+    }
+}
+
+#[tokio::test]
+async fn declared_login_inputs_are_validated_before_rpc_and_reach_the_rust_plugin() {
+    let diagnostics = crate::support::diagnostics::Diagnostics::default();
+    let _diagnostics = diagnostics.install();
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let schema = json!({
+        "type":"object", "additionalProperties":false,
+        "properties":{
+            "token":{"type":"string", "minLength":1, "writeOnly":true},
+            "region":{"type":"string", "enum":["us", "eu"]}
+        },
+        "required":["token", "region"]
+    });
+    let valid = json!({"token":"fixture-sensitive-input", "region":"eu"});
+    let (runtime, core) = environment
+        .provider(
+            json!({
+                "credential_input_schemas":{"login":schema}, "expected_login_input":valid,
+            }),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let admin = environment.store.admin_ports();
+    let service = CredentialsService::new(
+        runtime.admin_registry(core.snapshots()),
+        admin.accounts(),
+        admin.proxies(),
+        core.snapshot_control(),
+    );
+    let kind = ProviderKind::new("example").unwrap();
+    let descriptors = service.providers().unwrap();
+    assert_eq!(descriptors.len(), 1);
+    assert_eq!(descriptors[0].provider, kind);
+    let login = descriptors[0].capabilities.login.as_ref().unwrap();
+    assert_eq!(login.input_schema, schema);
+    assert_eq!(login.completion, AuthorizationCompletion::Poll);
+    let provider = service.for_provider(&kind).unwrap();
+    for input in [
+        json!({}),
+        json!({"token":"fixture-sensitive-input", "region":"invalid"}),
+        json!({"token":"fixture-sensitive-input", "region":"eu", "unexpected":true}),
+        json!({"token":"x".repeat(64 * 1024), "region":"eu"}),
+    ] {
+        let error = provider
+            .start_authorization(start(input))
+            .await
+            .unwrap_err();
+        assert_eq!(error.kind(), AdminErrorKind::Invalid);
+        assert!(!format!("{error:?}").contains("fixture-sensitive-input"));
+    }
+    // worker 只接受完整的合法输入；错误输入若进入 RPC，就无法得到上面要求的本地 Invalid 结果。
+    let started = provider.start_authorization(start(valid)).await.unwrap();
+    let result = service
+        .poll_authorization(
+            &kind,
+            PollAuthorization {
+                context: mutation(),
+                flow_id: started.flow_id,
+                callback_url: Some("ready".into()),
+                settings: None,
+            },
+        )
+        .await
+        .unwrap();
+    let AuthorizationPollResult::Complete(result) = result else {
+        panic!("login must complete")
+    };
+    assert_eq!(result.accounts.len(), 1);
+    drop(provider);
+    drop(service);
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn login_rpc_failure_reports_its_class_without_input_or_plugin_message() {
+    let diagnostics = crate::support::diagnostics::Diagnostics::default();
+    let _diagnostics = diagnostics.install();
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(
+            json!({
+                "credential_input_schemas":{"login":{
+                    "type":"object", "properties":{"token":{"type":"string", "writeOnly":true}},
+                    "required":["token"]
+                }},
+                "login_fault":{
+                    "code":"fault", "message":"fixture-sensitive-rpc-detail", "send_state":"not_sent"
+                }
+            }),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let admin = environment.store.admin_ports();
+    let service = CredentialsService::new(
+        runtime.admin_registry(core.snapshots()),
+        admin.accounts(),
+        admin.proxies(),
+        core.snapshot_control(),
+    );
+    let provider = service
+        .for_provider(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let error = provider
+        .start_authorization(start(json!({"token":"fixture-sensitive-login-input"})))
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), AdminErrorKind::Unavailable);
+    let records = diagnostics.records();
+    let rpc = records
+        .iter()
+        .find(|fields| {
+            fields
+                .get("method")
+                .is_some_and(|method| method.contains("provider.login.start"))
+        })
+        .expect("保留原始 RPC 分类");
+    assert!(rpc["error"].contains("Remote"));
+    assert!(rpc["error"].contains("Fault"));
+    assert!(!format!("{records:?}").contains("fixture-sensitive-rpc-detail"));
+    assert!(!format!("{records:?}").contains("fixture-sensitive-login-input"));
+    drop(provider);
+    drop(service);
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn invalid_form_schemas_cannot_replace_the_published_capabilities() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(json!({}), vec![account_grant("accounts")])
+        .await;
+    let registry = runtime.admin_registry(core.snapshots());
+    let descriptors = registry.credential_descriptors().unwrap();
+    let store = environment.store.admin_ports().plugins();
+    let snapshot = store.load_instances().await.unwrap();
+    for schemas in [
+        json!({"login":{"type":"array"}}),
+        json!({"login":{"type":"object", "properties":{"code":{"type":"unknown"}}}}),
+        json!({"login":{"type":"object", "$ref":"https://example.test/schema.json"}}),
+        json!({"login":{"type":"object", "$ref":"file:///etc/passwd"}}),
+        json!({"login":{"type":"object", "description":"x".repeat(64 * 1024)}}),
+        json!({"refresh":{"type":"object"}}),
+    ] {
+        let mut candidate = snapshot.clone();
+        candidate.instances[0].configuration = json!({"credential_input_schemas":schemas});
+        assert!(
+            PluginPreparation::prepare(runtime.as_ref(), candidate.config_revision, candidate)
+                .await
+                .is_err()
+        );
+        assert_eq!(registry.credential_descriptors().unwrap(), descriptors);
+        assert!(core.snapshots().acquire().is_ok());
+    }
+    let provider = registry
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    assert_eq!(
+        provider
+            .credential_capabilities()
+            .login
+            .unwrap()
+            .input_schema,
+        json!({"type":"object", "additionalProperties":false})
+    );
+    drop(provider);
+    drop(registry);
+    drop(store);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn capability_descriptions_follow_publication_and_frozen_readers_keep_their_generation() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(json!({}), vec![account_grant("accounts")])
+        .await;
+    let registry = runtime.admin_registry(core.snapshots());
+    let frozen = registry.freeze().unwrap();
+    let before = frozen.credential_descriptors().unwrap();
+    let store = environment.store.admin_ports().plugins();
+    let mut snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.remove(0);
+    let schema =
+        json!({"type":"object", "properties":{"region":{"enum":["eu"]}}, "required":["region"]});
+    instance.configuration = json!({"credential_input_schemas":{"login":schema}});
+    store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    assert_eq!(registry.credential_descriptors().unwrap(), before);
+    let revision = store.load_instances().await.unwrap().config_revision;
+    core.snapshot_control()
+        .publish_committed(gateway_core::routing::ConfigRevision::new(revision.get()).unwrap())
+        .await;
+    let after = registry.credential_descriptors().unwrap();
+    assert_eq!(
+        after[0].capabilities.login.as_ref().unwrap().input_schema,
+        schema
+    );
+    assert_eq!(frozen.credential_descriptors().unwrap(), before);
+    let mut snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.remove(0);
+    instance.enabled = false;
+    store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    let revision = store.load_instances().await.unwrap().config_revision;
+    core.snapshot_control()
+        .publish_committed(gateway_core::routing::ConfigRevision::new(revision.get()).unwrap())
+        .await;
+    assert!(registry.credential_descriptors().unwrap().is_empty());
+    assert_eq!(frozen.credential_descriptors().unwrap(), before);
+    drop(frozen);
+    drop(registry);
+    drop(store);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn import_and_rotation_validate_forms_before_plugin_calls_and_account_writes() {
+    use gateway_admin::model::provider_credentials::{
+        CredentialMutation, ImportCredentials, RotateCredential,
+    };
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let document = |value: Value| {
+        ProviderDocument::new(OpaqueProviderData::new(value.as_object().unwrap().clone()))
+    };
+    let valid_import = json!({"accounts":[{"name":"form import", "authentication_kind":"api_key", "material":{"key":"import-test-key"}}]});
+    let valid_rotation = json!({"key":"rotated-test-key"});
+    let (runtime, core) = environment.provider(json!({
+        "credential_input_schemas": {
+            "import":{"type":"object", "required":["accounts"], "properties":{"accounts":{"type":"array", "minItems":1}}},
+            "rotate":{"type":"object", "required":["key"], "properties":{"key":{"type":"string", "minLength":1}}, "additionalProperties":false}
+        },
+        "expected_import_input":valid_import, "expected_rotation_input":valid_rotation,
+    }), vec![account_grant("accounts")]).await;
+    let admin = environment.store.admin_ports();
+    let service = CredentialsService::new(
+        runtime.admin_registry(core.snapshots()),
+        admin.accounts(),
+        admin.proxies(),
+        core.snapshot_control(),
+    );
+    let provider = service
+        .for_provider(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    for input in [json!({}), json!({"accounts":[]})] {
+        let error = provider
+            .import_document(ImportCredentials {
+                context: mutation(),
+                document: document(input),
+                outbound_proxy_id: None,
+                settings: None,
+            })
+            .await
+            .unwrap_err();
+        assert_eq!(error.kind(), AdminErrorKind::Invalid);
+    }
+    let imported = provider
+        .import_document(ImportCredentials {
+            context: mutation(),
+            document: document(valid_import),
+            outbound_proxy_id: None,
+            settings: None,
+        })
+        .await
+        .unwrap();
+    let id = imported.credential_ids[0].clone();
+    let before = core.snapshots().acquire().unwrap().revision();
+    let error = provider
+        .rotate(RotateCredential {
+            mutation: CredentialMutation {
+                account_id: id.clone(),
+                context: mutation(),
+            },
+            provider_material: document(json!({"key":42})),
+            settings: None,
+        })
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+    assert_eq!(core.snapshots().acquire().unwrap().revision(), before);
+    let rotated = provider
+        .rotate(RotateCredential {
+            mutation: CredentialMutation {
+                account_id: id.clone(),
+                context: mutation(),
+            },
+            provider_material: document(valid_rotation),
+            settings: None,
+        })
+        .await
+        .unwrap();
+    assert_eq!(rotated.credential_revision.unwrap().get(), 2);
+    let stored = environment
+        .store
+        .provider_ports()
+        .accounts()
+        .load_current_credential(&id)
+        .await
+        .unwrap();
+    assert_eq!(
+        stored.credential.expose_to_provider()["key"],
+        "rotated-test-key"
+    );
+    drop(provider);
+    drop(service);
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn account_capabilities_cover_provider_accounts_and_follow_published_generations() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let account = environment.account(None).await;
+    let other = environment.account(None).await;
+    let (runtime, core) = environment
+        .provider(
+            json!({
+                "account_operations":["profile", "subscription", "avatar"],
+                "quota_url":"http://127.0.0.1:9/quota",
+            }),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let registry = runtime.admin_registry(core.snapshots());
+    let kind = ProviderKind::new("example").unwrap();
+    let frozen = registry.require(&kind).unwrap();
+    let before = frozen.account_capabilities(&account, "api_key");
+    assert!(before.quota && before.profile && before.subscription && before.avatar);
+    assert!(before.quota_refresh);
+    assert!(!before.reset_credits && !before.consume_reset_credit);
+    assert_eq!(frozen.account_capabilities(&other, "api_key"), before);
+
+    let store = environment.store.admin_ports().plugins();
+    let mut snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.remove(0);
+    instance.configuration["account_operations"] = json!(["subscription"]);
+    store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    assert_eq!(
+        registry
+            .require(&kind)
+            .unwrap()
+            .account_capabilities(&account, "api_key"),
+        before
+    );
+    let revision = store.load_instances().await.unwrap().config_revision;
+    core.snapshot_control()
+        .publish_committed(gateway_core::routing::ConfigRevision::new(revision.get()).unwrap())
+        .await;
+    let after = registry
+        .require(&kind)
+        .unwrap()
+        .account_capabilities(&account, "api_key");
+    assert!(after.subscription);
+    assert!(after.quota);
+    assert!(after.quota_refresh);
+    assert!(!after.profile && !after.avatar);
+    assert_eq!(frozen.account_capabilities(&account, "api_key"), before);
+    drop(frozen);
+    drop(registry);
+    drop(store);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/catalog/mod.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/catalog/mod.rs
new file mode 100644
index 000000000..8e4910f84
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/catalog/mod.rs
@@ -0,0 +1,710 @@
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    path::Path,
+    sync::Arc,
+    time::Duration,
+};
+
+use gateway_admin::{
+    model::plugins::instances::PluginPermissionGrant, ports::provider::ProviderAdminErrorKind,
+};
+use gateway_core::{
+    account::scope::{
+        ClientRoutingScope, FrozenAccountScope, RuntimeAccount, RuntimeAccountDirectory,
+    },
+    engine::probe::AccountProbeRequest,
+    error::GatewayErrorKind,
+    operation::{GenerateRequest, Operation, ProtocolPayload},
+    routing::{ProviderKind, UpstreamModelId},
+};
+use serde_json::{Value, json};
+
+use crate::support::environment::{Environment, account_grant};
+
+fn configuration() -> Value {
+    json!({
+        "model_discovery":{"include_static":false,"cache_ttl_seconds":60},
+        "discovered_catalog":{"models":[{"id":"discovered-model","operations":["generate"]}],"exhaustive":true},
+    })
+}
+
+fn records(path: &Path) -> Vec<Value> {
+    std::fs::read_to_string(path)
+        .unwrap_or_default()
+        .lines()
+        .map(|line| serde_json::from_str(line).unwrap())
+        .collect()
+}
+
+fn grants() -> Vec<PluginPermissionGrant> {
+    vec![account_grant("accounts"), account_grant("network")]
+}
+
+#[tokio::test]
+async fn native_continuation_routing_requires_the_static_or_discovered_model_declaration() {
+    for discovered in [false, true] {
+        let Some(environment) = Environment::create().await else {
+            eprintln!("SKIP: plugin integration environment absent");
+            return;
+        };
+        environment.account(None).await;
+        let models = json!([
+            {"id":"continuation-model", "operations":["generate"], "features":["native_continuation"]},
+            {"id":"plain-model", "operations":["generate"]}
+        ]);
+        let config = if discovered {
+            json!({
+                "model_discovery":{"include_static":false,"cache_ttl_seconds":60},
+                "discovered_catalog":{"models":models,"exhaustive":true}
+            })
+        } else {
+            json!({"static_models":models})
+        };
+        let (runtime, core) = environment
+            .provider(config, vec![account_grant("accounts")])
+            .await;
+        let snapshot = core.snapshots().acquire().unwrap();
+        for (model, supported) in [("continuation-model", true), ("plain-model", false)] {
+            let operation = Operation::Generate(GenerateRequest::from_protocol_payload(
+                ProtocolPayload::json_object("openai", json!({"model":model,"input":"next turn","previous_response_id":"response-before"}).as_object().unwrap().clone()).unwrap(),
+            ));
+            let plan = snapshot.plan(
+                &gateway_core::routing::PublicModelId::new(model).unwrap(),
+                &operation,
+                snapshot.all_account_scope(),
+                &gateway_core::routing::RoutingContext::default(),
+            );
+            assert_eq!(
+                plan.is_ok(),
+                supported,
+                "discovered={discovered}, model={model}"
+            );
+        }
+        drop(snapshot);
+        drop(core);
+        drop(runtime);
+        environment.close().await;
+    }
+}
+
+#[tokio::test]
+async fn directory_publication_is_independent_of_bounded_account_cache_eviction() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    // 比账号缓存多一个账号；每轮重建被淘汰项不得持续推进全局目录代次。
+    for _ in 0..257 {
+        environment.account(None).await;
+    }
+    let marker = environment.directory.path().join("large-models.jsonl");
+    let mut config = configuration();
+    config["models_marker"] = json!(marker);
+    let (runtime, core) = environment
+        .provider(config, vec![account_grant("accounts")])
+        .await;
+    assert_eq!(records(&marker).len(), 257);
+    let snapshot = core.snapshots().acquire().unwrap();
+    let providers = runtime
+        .provider_registry()
+        .for_extensions(snapshot.extensions())
+        .unwrap();
+    let provider = providers
+        .get(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let generation = provider.catalog_generation();
+    for _ in 0..3 {
+        assert_eq!(
+            provider.query_model_capabilities().await.unwrap()[0]
+                .upstream_model()
+                .as_str(),
+            "discovered-model"
+        );
+        assert_eq!(provider.catalog_generation(), generation);
+    }
+    assert_eq!(records(&marker).len(), 257);
+    drop(providers);
+    drop(snapshot);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn directory_ttl_starts_after_the_complete_account_scan() {
+    let diagnostics = crate::support::diagnostics::Diagnostics::default();
+    let _diagnostics = diagnostics.install();
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    for _ in 0..8 {
+        environment.account(None).await;
+    }
+    let server = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::any())
+        .respond_with(
+            wiremock::ResponseTemplate::new(200)
+                .set_body_json(configuration()["discovered_catalog"].clone())
+                .set_delay(Duration::from_millis(550)),
+        )
+        .expect(8)
+        .mount(&server)
+        .await;
+    let mut config = configuration();
+    config["model_discovery"]["cache_ttl_seconds"] = json!(1);
+    config["models_url"] = json!(server.uri());
+    let (runtime, core) = environment.provider(config, grants()).await;
+    assert_eq!(
+        server.received_requests().await.unwrap().len(),
+        8,
+        "首次目录扫描必须完成所有账号查询：{:?}",
+        diagnostics.records()
+    );
+    let snapshot = core.snapshots().acquire().unwrap();
+    let providers = runtime
+        .provider_registry()
+        .for_extensions(snapshot.extensions())
+        .unwrap();
+    let provider = providers
+        .get(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    assert_eq!(
+        provider.query_model_capabilities().await.unwrap()[0]
+            .upstream_model()
+            .as_str(),
+        "discovered-model"
+    );
+    let generation = provider.catalog_generation();
+    tokio::time::sleep(Duration::from_millis(1100)).await;
+    assert!(provider.catalog_generation() > generation);
+    // 到期只标记一次失效；同步代次读取不得发起后台 RPC 或重复推进版本。
+    assert_eq!(provider.catalog_generation(), provider.catalog_generation());
+    drop(providers);
+    drop(snapshot);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn partial_directory_failure_reports_account_and_stage_without_model_payload() {
+    let diagnostics = crate::support::diagnostics::Diagnostics::default();
+    let _diagnostics = diagnostics.install();
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    environment.account(None).await;
+    let rejected = environment.account(None).await;
+    let mut config = configuration();
+    config["account_catalogs"] = json!({
+        rejected.as_str(): {"models":[{"id":"fixture-sensitive-model", "operations":[]}], "exhaustive":true}
+    });
+    let (runtime, core) = environment.provider(config, grants()).await;
+    let snapshot = core.snapshots().acquire().unwrap();
+    let providers = runtime
+        .provider_registry()
+        .for_extensions(snapshot.extensions())
+        .unwrap();
+    let provider = providers
+        .get(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let models = provider.query_model_capabilities().await.unwrap();
+    assert_eq!(models.len(), 1);
+    assert_eq!(models[0].upstream_model().as_str(), "discovered-model");
+    let records = diagnostics.records();
+    let failure = records
+        .iter()
+        .find(|fields| {
+            fields
+                .get("account_id")
+                .is_some_and(|id| id.contains(rejected.as_str()))
+        })
+        .expect("部分失败不能在目录合并时丢失诊断");
+    assert_eq!(failure["stage"], "\"validate\"");
+    assert_eq!(failure["kind"], "BadGateway");
+    assert_eq!(failure["timed_out"], "false");
+    assert!(!format!("{records:?}").contains("fixture-sensitive-model"));
+    drop(providers);
+    drop(snapshot);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn account_model_cache_coalesces_reads_and_publishes_invalidation_generations() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let id = environment.account(None).await;
+    let marker = environment.directory.path().join("models.jsonl");
+    let mut config = configuration();
+    config["models_marker"] = json!(marker);
+    let (runtime, core) = environment
+        .provider(config, vec![account_grant("accounts")])
+        .await;
+    let admin = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let snapshot = core.snapshots().acquire().unwrap();
+    let providers = runtime
+        .provider_registry()
+        .for_extensions(snapshot.extensions())
+        .unwrap();
+    let provider = providers
+        .get(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    assert_eq!(records(&marker).len(), 1);
+    for result in futures::future::join_all((0..8).map(|_| admin.models(&id, false))).await {
+        let result = result.unwrap();
+        assert_eq!(result.models[0].id.as_str(), "discovered-model");
+        assert!(result.observed_at.is_some());
+    }
+    assert_eq!(records(&marker).len(), 1);
+    let generation = provider.catalog_generation();
+    admin.account_facts_changed(std::slice::from_ref(&id)).await;
+    assert!(provider.catalog_generation() > generation);
+    for result in futures::future::join_all((0..8).map(|_| admin.models(&id, false))).await {
+        result.unwrap();
+    }
+    assert_eq!(records(&marker).len(), 2);
+    admin.models(&id, true).await.unwrap();
+    assert_eq!(records(&marker).len(), 3);
+    drop(providers);
+    drop(snapshot);
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn initial_model_discovery_commits_prepared_facts_without_refresh_reentry() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let id = environment.account(None).await;
+    let marker = environment
+        .directory
+        .path()
+        .join("prepared-account-facts.jsonl");
+    let mut config = configuration();
+    config["models_marker"] = json!(marker);
+    config["prepared_facts_after_models"] = json!(0);
+    config["prepared_account_facts"] = json!({
+        "name":"plugin refreshed account",
+        "authentication_kind":"api_key",
+        "material":{"key":"rotated-test-only"},
+        "email":"refreshed@example.invalid",
+        "upstream_user_id":null,
+        "upstream_account_id":null,
+        "plan_type":"team",
+        "has_refresh_token":false,
+        "access_token_expires_at_ms":null,
+        "next_refresh_at_ms":null
+    });
+    // 死锁预算只约束初始化与目录发布，不能被前置制品打包、校验和安装消耗。
+    environment
+        .install_provider(config, vec![account_grant("accounts")])
+        .await;
+    let (runtime, core) =
+        tokio::time::timeout(Duration::from_secs(30), environment.runtime())
+            .await
+            .unwrap_or_else(|error| {
+                panic!(
+                    "initial discovery must not wait on its own snapshot publication: {error}; model queries={}",
+                    records(&marker).len()
+                )
+            });
+    // 首轮提交推进配置 revision，Core 用合并的候选 revision 再编译一次。
+    assert_eq!(records(&marker).len(), 2);
+
+    let accounts = environment.store.admin_ports().accounts();
+    let details = accounts
+        .credential_details(&ProviderKind::new("example").unwrap(), &id)
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(details.credential.credential_revision.get(), 2);
+    assert_eq!(details.credential.name, "plugin refreshed account");
+    let admin_bundle = environment.bind_admin_accounts(&runtime, &core).await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+
+    let result = provider.models(&id, true).await.unwrap();
+    assert_eq!(result.models[0].id.as_str(), "discovered-model");
+
+    assert_eq!(
+        details.credential.email.as_deref(),
+        Some("refreshed@example.invalid")
+    );
+    let exported = accounts
+        .load_credentials_for_export(
+            &ProviderKind::new("example").unwrap(),
+            std::slice::from_ref(&id),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        exported[0]
+            .provider_material
+            .expose_to_provider()
+            .expose_to_provider()["key"],
+        "rotated-test-only"
+    );
+    let audit = environment.audit_requests("refresh_credential").await;
+    assert_eq!(audit.len(), 1);
+    assert!(audit[0].starts_with("plugin:"));
+    assert!(audit[0].contains(":call:"));
+
+    drop(provider);
+    drop(admin_bundle);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn account_callbacks_use_host_scope_and_reject_the_stale_catalog_publication() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let id = environment.account(None).await;
+    let other = environment.account(None).await;
+    let marker = environment.directory.path().join("account-callbacks.jsonl");
+    let mut config = configuration();
+    config["account_callback_fixture"] = json!({
+        "after_models":2,
+        "marker":marker,
+        "other_account_id":other.as_str(),
+        "expected_key":"test-only",
+        "replacement_key":"callback-rotated-test-only"
+    });
+    let (runtime, core) = environment
+        .provider(config, vec![account_grant("accounts")])
+        .await;
+    let admin_bundle = environment.bind_admin_accounts(&runtime, &core).await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+
+    let error = provider.models(&id, true).await.unwrap_err();
+    assert_eq!(error.kind(), ProviderAdminErrorKind::Conflict);
+    assert_eq!(
+        records(&marker),
+        [json!({
+            "listed":2,
+            "account_id":id.as_str(),
+            "cross_account_readable":true,
+            "read_revision":1,
+            "saved_revision":2,
+        })]
+    );
+
+    let accounts = environment.store.admin_ports().accounts();
+    let details = accounts
+        .credential_details(&ProviderKind::new("example").unwrap(), &id)
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(details.credential.credential_revision.get(), 2);
+    assert_eq!(details.credential.name, "callback rotated account");
+    let exported = accounts
+        .load_credentials_for_export(
+            &ProviderKind::new("example").unwrap(),
+            std::slice::from_ref(&id),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        exported[0]
+            .provider_material
+            .expose_to_provider()
+            .expose_to_provider()["key"],
+        "callback-rotated-test-only"
+    );
+    let audit = environment.audit_requests("rotate_credential").await;
+    assert_eq!(audit.len(), 1);
+    assert!(audit[0].starts_with("plugin:"));
+    assert!(audit[0].contains(":call:"));
+
+    drop(provider);
+    drop(admin_bundle);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn merged_catalog_keeps_client_scope_and_account_feature_gates() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let first = environment.account(None).await;
+    let second = environment.account(None).await;
+    let mut config = configuration();
+    config["model_discovery"]["include_static"] = json!(true);
+    config["account_catalogs"] = json!({
+        (first.as_str()):{"models":[{"id":"first-model","operations":["generate"]},{"id":"shared","operations":["generate"]}],"exhaustive":true},
+        (second.as_str()):{"models":[{"id":"second-model","operations":["generate"]},{"id":"shared","operations":["generate"],"features":["tools"],"maximum_output_tokens":32}],"exhaustive":true},
+    });
+    let (runtime, core) = environment
+        .provider(config, vec![account_grant("accounts")])
+        .await;
+    let kind = ProviderKind::new("example").unwrap();
+    let admin = runtime
+        .admin_registry(core.snapshots())
+        .require(&kind)
+        .unwrap();
+    assert_eq!(
+        admin
+            .models(&first, false)
+            .await
+            .unwrap()
+            .models
+            .iter()
+            .map(|model| model.id.as_str())
+            .collect::<Vec<_>>(),
+        vec!["first-model", "plugin-model", "shared"]
+    );
+    let snapshot = core.snapshots().acquire().unwrap();
+    let providers = runtime
+        .provider_registry()
+        .for_extensions(snapshot.extensions())
+        .unwrap();
+    let provider = providers.get(&kind).unwrap();
+    let scope = FrozenAccountScope::new(
+        Arc::new(RuntimeAccountDirectory::new(BTreeMap::from([(
+            first.clone(),
+            RuntimeAccount::new(kind.clone(), BTreeSet::new()),
+        )]))),
+        ClientRoutingScope::all_accounts(),
+    );
+    let client = provider
+        .query_client_model_catalog(&scope, "openai", "test")
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(
+        client
+            .iter()
+            .map(|model| model.model.as_str())
+            .collect::<Vec<_>>(),
+        vec!["first-model", "plugin-model", "shared"]
+    );
+    let operation = |limit| {
+        Operation::Generate(GenerateRequest::from_protocol_payload(ProtocolPayload::json_object("openai", json!({"model":"shared", "input":"hello", "tools":[{"type":"function", "name":"echo", "parameters":{"type":"object"}}], "max_output_tokens":limit}).as_object().unwrap().clone()).unwrap()))
+    };
+    let denied = core
+        .account_probe()
+        .probe(
+            AccountProbeRequest {
+                account_id: first,
+                provider_kind: kind.clone(),
+                upstream_model: UpstreamModelId::new("shared").unwrap(),
+                operation: operation(16),
+            },
+            admin.snapshot(),
+        )
+        .await
+        .unwrap_err();
+    assert_eq!(denied.kind(), GatewayErrorKind::NoAvailableProvider);
+    let reply = core
+        .account_probe()
+        .probe(
+            AccountProbeRequest {
+                account_id: second.clone(),
+                provider_kind: kind.clone(),
+                upstream_model: UpstreamModelId::new("shared").unwrap(),
+                operation: operation(16),
+            },
+            admin.snapshot(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(reply.text, vec!["Rust plugin response"]);
+    let denied = core
+        .account_probe()
+        .probe(
+            AccountProbeRequest {
+                account_id: second,
+                provider_kind: kind,
+                upstream_model: UpstreamModelId::new("shared").unwrap(),
+                operation: operation(33),
+            },
+            admin.snapshot(),
+        )
+        .await
+        .unwrap_err();
+    assert!(matches!(
+        denied.kind(),
+        GatewayErrorKind::NoAvailableProvider | GatewayErrorKind::Unsupported
+    ));
+    drop(providers);
+    drop(snapshot);
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn model_http_uses_each_selected_account_without_permission_prebinding() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let proxy = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::header(
+        "proxy-authorization",
+        "Basic dXNlcjpwYXNz",
+    ))
+    .and(wiremock::matchers::header(
+        "authorization",
+        "Bearer test-only",
+    ))
+    .respond_with(
+        wiremock::ResponseTemplate::new(200)
+            .set_body_json(configuration()["discovered_catalog"].clone()),
+    )
+    .expect(2)
+    .mount(&proxy)
+    .await;
+    let outbound_proxy = gateway_core::account::OutboundProxy::parse(&format!(
+        "http://user:pass@{}",
+        proxy.address()
+    ))
+    .unwrap();
+    let id = environment.account(Some(outbound_proxy.clone())).await;
+    let other = environment.account(Some(outbound_proxy)).await;
+    let mut config = configuration();
+    config["models_url"] = json!("http://127.0.0.1:9/models");
+    let (runtime, core) = environment.provider(config, grants()).await;
+    let admin = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    assert_eq!(
+        admin.models(&id, false).await.unwrap().models[0]
+            .id
+            .as_str(),
+        "discovered-model"
+    );
+    assert_eq!(
+        admin.models(&other, false).await.unwrap().models[0]
+            .id
+            .as_str(),
+        "discovered-model"
+    );
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn malformed_refresh_does_not_replace_a_valid_account_catalog() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let server = wiremock::MockServer::start().await;
+    let good = configuration()["discovered_catalog"].clone();
+    wiremock::Mock::given(wiremock::matchers::any())
+        .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(&good))
+        .mount(&server)
+        .await;
+    let id = environment.account(None).await;
+    let mut config = configuration();
+    config["models_url"] = json!(server.uri());
+    let (runtime, core) = environment.provider(config, grants()).await;
+    let admin = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    for models in [
+        json!([{"id":"duplicate","operations":["generate"]},{"id":"duplicate","operations":["generate"]}]),
+        json!([{"id":"bad","operations":[]}]),
+        json!([{"id":"bad","operations":["generate"],"features":["tools","tools"]}]),
+        json!([{"id":"bad","operations":["generate"],"maximum_output_tokens":0}]),
+    ] {
+        server.reset().await;
+        wiremock::Mock::given(wiremock::matchers::any())
+            .respond_with(
+                wiremock::ResponseTemplate::new(200)
+                    .set_body_json(json!({"models":models,"exhaustive":true})),
+            )
+            .mount(&server)
+            .await;
+        assert_eq!(
+            admin.models(&id, true).await.unwrap_err().kind(),
+            ProviderAdminErrorKind::BadGateway
+        );
+        assert_eq!(
+            admin.models(&id, false).await.unwrap().models[0]
+                .id
+                .as_str(),
+            "discovered-model"
+        );
+    }
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn invalidation_during_discovery_rejects_the_late_publication() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let server = wiremock::MockServer::start().await;
+    let good = configuration()["discovered_catalog"].clone();
+    wiremock::Mock::given(wiremock::matchers::any())
+        .respond_with(
+            wiremock::ResponseTemplate::new(200)
+                .set_body_json(&good)
+                .set_delay(Duration::from_millis(500)),
+        )
+        .mount(&server)
+        .await;
+    let id = environment.account(None).await;
+    let marker = environment.directory.path().join("late-models.jsonl");
+    let mut config = configuration();
+    config["models_url"] = json!(server.uri());
+    config["models_marker"] = json!(marker);
+    let (runtime, core) = environment.provider(config, grants()).await;
+    let admin = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let invalidate = async {
+        tokio::time::timeout(Duration::from_secs(3), async {
+            while records(&marker).len() < 2 {
+                tokio::time::sleep(Duration::from_millis(10)).await;
+            }
+        })
+        .await
+        .unwrap();
+        admin.account_facts_changed(std::slice::from_ref(&id)).await;
+    };
+    let (result, ()) = tokio::join!(admin.models(&id, true), invalidate);
+    assert_eq!(result.unwrap_err().kind(), ProviderAdminErrorKind::Conflict);
+    admin.models(&id, false).await.unwrap();
+    assert_eq!(records(&marker).len(), 3);
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/configuration.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/configuration.rs
new file mode 100644
index 000000000..cd1c6c817
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/configuration.rs
@@ -0,0 +1,286 @@
+use gateway_admin::{
+    CredentialsService,
+    model::provider_credentials::{CredentialMutation, ProviderDocument, RotateCredential},
+    ports::{plugins::PluginPreparation, provider::ProviderAdminErrorKind},
+};
+use gateway_core::{account::OpaqueProviderData, routing::ProviderKind};
+use serde_json::{Value, json};
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+fn configuration(result: Value) -> Value {
+    json!({
+        "credential_input_schemas": {
+            "rotate": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                    "base_url": {"type": "string", "format": "uri", "maxLength": 2048},
+                    "transport": {"type": "string", "enum": ["http", "prefer_websocket"]},
+                    "api_key": {"type": "string", "writeOnly": true}
+                }
+            }
+        },
+        "account_configuration": {"public_fields": ["base_url", "transport"]},
+        "account_configuration_result": result,
+    })
+}
+
+#[tokio::test]
+async fn declared_connection_settings_are_projected_with_the_accounts_domain() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let account_id = environment.account(None).await;
+    let expected = json!({
+        "account_id": account_id.as_str(),
+        "credential_revision": 1,
+        "credential": {"key": "test-only"},
+    });
+    let mut config = configuration(json!({
+        "base_url": "https://example.test/v1",
+        "transport": "http",
+    }));
+    config["expected_account_configuration"] = expected;
+    let (runtime, core) = environment
+        .provider(config, vec![account_grant("accounts")])
+        .await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+
+    let projected = provider
+        .account_configuration(&account_id)
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(
+        Value::Object(projected.into_provider_data().into_inner()),
+        json!({"base_url":"https://example.test/v1", "transport":"http"})
+    );
+    assert_eq!(
+        environment
+            .store
+            .provider_ports()
+            .accounts()
+            .get_account(&account_id)
+            .await
+            .unwrap()
+            .unwrap()
+            .revision()
+            .get(),
+        1
+    );
+
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn unsafe_or_undeclared_connection_settings_cannot_replace_the_published_provider() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(
+            configuration(json!({"base_url":"https://example.test", "transport":"http"})),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let registry = runtime.admin_registry(core.snapshots());
+    let published = registry.credential_descriptors().unwrap();
+    let store = environment.store.admin_ports().plugins();
+    let snapshot = store.load_instances().await.unwrap();
+
+    for (public_fields, property) in [
+        (json!(["missing"]), json!({"type":"string"})),
+        (json!(["base_url", "base_url"]), json!({"type":"string"})),
+        (
+            json!(["base_url"]),
+            json!({"type":"string", "writeOnly":true}),
+        ),
+        (
+            json!(["base_url"]),
+            json!({"type":"string", "format":"password"}),
+        ),
+        (json!(["base_url"]), json!({"$ref":"#/$defs/value"})),
+        (
+            json!(["base_url"]),
+            json!({"type":"string", "allOf":[{"writeOnly":true}]}),
+        ),
+        (json!(["base_url"]), json!({"type":"object"})),
+    ] {
+        let mut candidate = snapshot.clone();
+        candidate.instances[0].configuration = json!({
+            "credential_input_schemas": {
+                "rotate": {
+                    "type":"object",
+                    "properties":{"base_url":property},
+                }
+            },
+            "account_configuration":{"public_fields":public_fields},
+        });
+        assert!(
+            PluginPreparation::prepare(runtime.as_ref(), candidate.config_revision, candidate)
+                .await
+                .is_err()
+        );
+        assert_eq!(registry.credential_descriptors().unwrap(), published);
+    }
+
+    for root_constraint in [
+        json!({"writeOnly":true}),
+        json!({"$ref":"#/$defs/connection"}),
+        json!({"allOf":[{"properties":{"base_url":{"writeOnly":true}}}]}),
+        json!({"if":{"properties":{"base_url":{"const":"https://private.test"}}}, "then":{"properties":{"base_url":{"format":"password"}}}}),
+    ] {
+        let mut rotate_schema = json!({
+            "type":"object",
+            "properties":{"base_url":{"type":"string"}},
+        });
+        rotate_schema
+            .as_object_mut()
+            .unwrap()
+            .extend(root_constraint.as_object().unwrap().clone());
+        let mut candidate = snapshot.clone();
+        candidate.instances[0].configuration = json!({
+            "credential_input_schemas":{"rotate":rotate_schema},
+            "account_configuration":{"public_fields":["base_url"]},
+        });
+        assert!(
+            PluginPreparation::prepare(runtime.as_ref(), candidate.config_revision, candidate)
+                .await
+                .is_err()
+        );
+        assert_eq!(registry.credential_descriptors().unwrap(), published);
+    }
+
+    let mut candidate = snapshot;
+    candidate.instances[0].grants.clear();
+    // Provider 是账号驱动扩展；缺少整个 Accounts 域时必须在候选代次准备阶段拒绝。
+    assert!(
+        PluginPreparation::prepare(runtime.as_ref(), candidate.config_revision, candidate)
+            .await
+            .is_err()
+    );
+    assert_eq!(registry.credential_descriptors().unwrap(), published);
+
+    drop(store);
+    drop(registry);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn plugin_results_cannot_add_credential_fields_or_leak_rejected_values() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let account_id = environment.account(None).await;
+    let (runtime, core) = environment
+        .provider(
+            configuration(json!({
+                "base_url":"https://example.test",
+                "transport":"http",
+                "api_key":"fixture-sensitive-value",
+            })),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let error = provider
+        .account_configuration(&account_id)
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), ProviderAdminErrorKind::BadGateway);
+    assert!(!format!("{error:?}").contains("fixture-sensitive-value"));
+
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn credential_revision_changes_discard_a_late_configuration_projection() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let account_id = environment.account(None).await;
+    let marker = environment
+        .directory
+        .path()
+        .join("configuration-started.jsonl");
+    let mut config = configuration(json!({
+        "base_url":"https://stale.example.test",
+        "transport":"http",
+    }));
+    let release = environment.directory.path().join("configuration-release");
+    config["account_configuration_release_marker"] = json!(release);
+    config["account_configuration_started_marker"] = json!(marker.to_string_lossy().into_owned());
+    let (runtime, core) = environment
+        .provider(config, vec![account_grant("accounts")])
+        .await;
+    let kind = ProviderKind::new("example").unwrap();
+    let registry = runtime.admin_registry(core.snapshots());
+    let provider = registry.require(&kind).unwrap();
+    let pending_id = account_id.clone();
+    let pending = tokio::spawn(async move { provider.account_configuration(&pending_id).await });
+    tokio::time::timeout(std::time::Duration::from_secs(2), async {
+        while !marker.exists() {
+            tokio::time::sleep(std::time::Duration::from_millis(5)).await;
+        }
+    })
+    .await
+    .unwrap();
+
+    let admin = environment.store.admin_ports();
+    let credentials = CredentialsService::new(
+        registry,
+        admin.accounts(),
+        admin.proxies(),
+        core.snapshot_control(),
+    );
+    credentials
+        .for_provider(&kind)
+        .unwrap()
+        .rotate(RotateCredential {
+            mutation: CredentialMutation {
+                account_id,
+                context: mutation(),
+            },
+            provider_material: ProviderDocument::new(OpaqueProviderData::new(
+                json!({"api_key":"replacement-test-key"})
+                    .as_object()
+                    .unwrap()
+                    .clone(),
+            )),
+            settings: None,
+        })
+        .await
+        .unwrap();
+    // 先确认轮换提交，再释放旧 revision 的投影，避免依赖机器负载决定先后。
+    assert!(!pending.is_finished());
+    std::fs::write(release, b"committed").unwrap();
+    assert_eq!(
+        pending.await.unwrap().unwrap_err().kind(),
+        ProviderAdminErrorKind::Conflict
+    );
+
+    drop(credentials);
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/credentials.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/credentials.rs
new file mode 100644
index 000000000..82ff2809e
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/credentials.rs
@@ -0,0 +1,291 @@
+use gateway_admin::{
+    CredentialsService,
+    model::provider_credentials::{
+        ImportCredentials, PrepareCredentialImport, ProviderDocument, ProviderExportCredentialInput,
+    },
+};
+use gateway_core::{account::OpaqueProviderData, routing::ProviderKind};
+use serde_json::json;
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+#[tokio::test]
+async fn rust_plugin_imports_and_exports_through_admin_transactions_and_core_publication() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(json!({}), vec![account_grant("accounts")])
+        .await;
+    let kind = ProviderKind::new("example").unwrap();
+    let registry = runtime.admin_registry(core.snapshots());
+    let admin = environment.store.admin_ports();
+    let credentials = CredentialsService::new(
+        registry.clone(),
+        admin.accounts(),
+        admin.proxies(),
+        core.snapshot_control(),
+    );
+    let document = json!({"accounts":[
+        {"name":"first", "authentication_kind":"api_key", "material":{"key":"test-first"}},
+        {"name":"second", "authentication_kind":"api_key", "material":{"key":"test-second"}}
+    ]});
+    let before = core.snapshots().acquire().unwrap();
+    let result = credentials
+        .for_provider(&kind)
+        .unwrap()
+        .import_document(ImportCredentials {
+            outbound_proxy_id: None,
+            settings: None,
+            context: mutation(),
+            document: provider_document(document.clone()),
+        })
+        .await
+        .unwrap();
+    assert_eq!(result.credential_ids.len(), 2);
+    let after = core.snapshots().acquire().unwrap();
+    assert!(after.revision().get() > before.revision().get());
+    let ports = environment.store.provider_ports();
+    let mut exported = Vec::new();
+    for id in &result.credential_ids {
+        let loaded = ports
+            .accounts()
+            .load_credential(
+                id,
+                gateway_core::account::CredentialRevision::new(1).unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(loaded.account.provider(), &kind);
+        assert_eq!(loaded.account.revision().get(), 1);
+        let details = admin
+            .accounts()
+            .credential_details(&kind, id)
+            .await
+            .unwrap()
+            .unwrap();
+        exported.push(ProviderExportCredentialInput {
+            account: details.credential,
+            provider_material: provider_document(json!(loaded.credential.expose_to_provider())),
+        });
+    }
+    let provider = registry.require(&kind).unwrap();
+    let export = provider.export_credentials(exported).await.unwrap();
+    assert_eq!(export.account_ids, result.credential_ids);
+    let exported = export.document.expose_to_provider().expose_to_provider();
+    assert_eq!(
+        exported["accounts"][0]["material"],
+        document["accounts"][0]["material"]
+    );
+    assert_eq!(
+        exported["accounts"][1]["material"],
+        document["accounts"][1]["material"]
+    );
+    // 整个批次准备失败时，前面的合法账号也不能提前进入 Store。
+    let invalid = json!({"accounts":[document["accounts"][0], {"name":"", "authentication_kind":"api_key", "material":{"key":"test-invalid"}}]});
+    assert!(
+        credentials
+            .for_provider(&kind)
+            .unwrap()
+            .import_document(ImportCredentials {
+                outbound_proxy_id: None,
+                settings: None,
+                context: mutation(),
+                document: provider_document(invalid),
+            })
+            .await
+            .is_err()
+    );
+    assert_eq!(
+        core.snapshots().acquire().unwrap().revision(),
+        after.revision()
+    );
+    drop(provider);
+    drop(credentials);
+    drop(registry);
+    drop(before);
+    drop(after);
+    drop(admin);
+    drop(ports);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn accounts_domain_allows_plugin_to_prepare_account_creation() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(json!({}), vec![account_grant("accounts")])
+        .await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let prepared = provider
+        .prepare_import(PrepareCredentialImport {
+            default_outbound_proxy: None,
+            document: provider_document(json!({"accounts":[{
+                "name":"prepared account",
+                "authentication_kind":"api_key",
+                "material":{"key":"prepared-test-only"}
+            }]})),
+        })
+        .await
+        .unwrap();
+    assert_eq!(prepared.credentials.len(), 1);
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn host_account_create_uses_admin_transaction_and_host_generated_id() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let marker = environment.directory.path().join("account-create.jsonl");
+    let (runtime, core) = environment
+        .provider(
+            json!({"account_create_marker":marker}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let admin_bundle = environment.bind_admin_accounts(&runtime, &core).await;
+    let kind = ProviderKind::new("example").unwrap();
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&kind)
+        .unwrap();
+    let prepared = provider
+        .prepare_import(PrepareCredentialImport {
+            default_outbound_proxy: None,
+            document: provider_document(json!({"accounts":[{
+                "name":"callback created account",
+                "authentication_kind":"api_key",
+                "material":{"key":"created-test-only"}
+            }]})),
+        })
+        .await
+        .unwrap();
+    assert_eq!(prepared.credentials.len(), 1);
+
+    let saved: serde_json::Value = serde_json::from_str(
+        std::fs::read_to_string(&marker)
+            .unwrap()
+            .lines()
+            .next()
+            .unwrap(),
+    )
+    .unwrap();
+    let account_id = gateway_core::account::ProviderAccountId::new(
+        saved["account_id"].as_str().unwrap().to_owned(),
+    )
+    .unwrap();
+    assert!(account_id.as_str().starts_with("acct_"));
+    assert_eq!(saved["credential_revision"], 1);
+    assert_ne!(account_id, prepared.credentials[0].account_id);
+    let details = environment
+        .store
+        .admin_ports()
+        .accounts()
+        .credential_details(&kind, &account_id)
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(details.credential.name, "callback created account");
+    assert_eq!(details.credential.credential_revision.get(), 1);
+    let audit = environment.audit_requests("import_document").await;
+    assert_eq!(audit.len(), 1);
+    assert!(audit[0].starts_with("plugin:"));
+    assert!(audit[0].contains(":call:"));
+
+    drop(provider);
+    drop(admin_bundle);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+fn provider_document(value: serde_json::Value) -> ProviderDocument {
+    ProviderDocument::new(OpaqueProviderData::new(value.as_object().unwrap().clone()))
+}
+
+#[tokio::test]
+async fn accounts_domain_allows_export_while_missing_network_blocks_http_operations() {
+    use gateway_admin::{
+        model::provider_credentials::{PrepareCredentialRefresh, ProviderQuotaRequest},
+        ports::provider::ProviderAdminErrorKind,
+    };
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let server = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::any())
+        .respond_with(wiremock::ResponseTemplate::new(200))
+        .expect(0)
+        .mount(&server)
+        .await;
+    let id = environment.account(None).await;
+    let (runtime, core) = environment
+        .provider(
+            json!({"quota_url":server.uri(), "management_url":server.uri()}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let kind = ProviderKind::new("example").unwrap();
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&kind)
+        .unwrap();
+    let account = environment
+        .store
+        .admin_ports()
+        .accounts()
+        .credential_details(&kind, &id)
+        .await
+        .unwrap()
+        .unwrap()
+        .credential;
+    assert_eq!(
+        provider
+            .prepare_refresh(PrepareCredentialRefresh {
+                account: account.clone()
+            })
+            .await
+            .unwrap_err()
+            .kind(),
+        ProviderAdminErrorKind::Invalid
+    );
+    assert_eq!(
+        provider
+            .quota(ProviderQuotaRequest {
+                account_id: id.clone(),
+                refresh: true,
+                rolling_usage: None
+            })
+            .await
+            .unwrap_err()
+            .kind(),
+        ProviderAdminErrorKind::Invalid
+    );
+    let exported = provider
+        .export_credentials(vec![ProviderExportCredentialInput {
+            account,
+            provider_material: provider_document(json!({"key":"test-only"})),
+        }])
+        .await
+        .unwrap();
+    assert_eq!(exported.account_ids, vec![id]);
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/events/mod.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/events/mod.rs
new file mode 100644
index 000000000..a508d974d
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/events/mod.rs
@@ -0,0 +1,886 @@
+use std::{
+    collections::BTreeMap,
+    num::{NonZeroU32, NonZeroUsize},
+    path::Path,
+    sync::Arc,
+    time::{Duration, SystemTime},
+};
+
+use futures::TryStreamExt as _;
+use gateway_admin::{
+    CredentialsService,
+    model::{
+        plugins::PluginSource,
+        provider_credentials::{CredentialMutation, ProviderDocument, RotateCredential},
+    },
+    ports::plugins::{PluginPackageInspector as _, PluginPreparation, PluginStore},
+};
+use gateway_core::{
+    account::{AccountSelectionPolicy, OpaqueProviderData, RotationStrategy},
+    engine::{
+        AccountAttemptContext, AttemptContext, ModelRequestId, RequestAttemptContext,
+        provider::ProviderRequest,
+    },
+    error::{ProviderError, ProviderErrorKind},
+    event::{GatewayEvent, ProviderEvent, UpstreamHttpVersion},
+    lifecycle::CancellationToken,
+    operation::ProviderSessionState,
+    policy::ClientApiKeyId,
+    routing::{ConfigRevision, ProviderKind, PublicModelId, RoutingContext, UpstreamModelId},
+    upstream::UpstreamSendState,
+};
+use gateway_plugin_runtime::{
+    ContinuationDrainConfig, PackageInspector, PackageLimits, ValidatedPackage,
+};
+use serde_json::json;
+
+use crate::support::{
+    archive,
+    environment::{Environment, account_grant, mutation},
+    worker,
+};
+
+pub(super) async fn execute(
+    runtime: &gateway_plugin_runtime::PluginRuntime,
+    core: &gateway_core::CoreBundle,
+    state: Option<ProviderSessionState>,
+) -> Result<Vec<ProviderEvent>, ProviderError> {
+    let kind = ProviderKind::new("example").unwrap();
+    let snapshot = core.snapshots().acquire().unwrap();
+    let admin = runtime
+        .admin_registry(core.snapshots())
+        .require(&kind)
+        .unwrap();
+    let mut operation = admin
+        .connection_test_operation(&UpstreamModelId::new("plugin-model").unwrap(), "events")
+        .await
+        .unwrap();
+    if let Some(state) = state {
+        operation.set_provider_session_state(state);
+    }
+    let plan = snapshot
+        .plan(
+            &PublicModelId::new("plugin-model").unwrap(),
+            &operation,
+            snapshot.all_account_scope(),
+            &RoutingContext::default(),
+        )
+        .unwrap();
+    let registry = runtime
+        .provider_registry()
+        .for_extensions(snapshot.extensions())
+        .unwrap();
+    let provider = registry.get(&kind).unwrap();
+    let context = AttemptContext::new(
+        RequestAttemptContext::new(
+            ModelRequestId::new("req_plugin_events").unwrap(),
+            ClientApiKeyId::new("key_plugin_events").unwrap(),
+        ),
+        NonZeroU32::MIN,
+        SystemTime::now() + Duration::from_secs(15),
+        AccountSelectionPolicy::new(
+            RotationStrategy::RoundRobin,
+            NonZeroU32::MIN,
+            Duration::ZERO,
+        ),
+        AccountAttemptContext::default().with_account_scope(snapshot.all_account_scope()),
+        None,
+        CancellationToken::new(),
+    );
+    Arc::clone(provider)
+        .execute(
+            ProviderRequest::new(operation, plan.candidates()[0].clone()),
+            context,
+        )
+        .await?
+        .try_collect()
+        .await
+}
+
+fn continuation_state(events: &[ProviderEvent]) -> ProviderSessionState {
+    events
+        .last()
+        .and_then(ProviderEvent::session_update)
+        .cloned()
+        .expect("terminal event continuation state")
+}
+
+fn assert_replay_required(error: &ProviderError) {
+    assert_eq!(error.kind(), ProviderErrorKind::InvalidRequest);
+    assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+}
+
+async fn wait_until_entry_count(path: &Path, expected: usize) {
+    tokio::time::timeout(Duration::from_secs(3), async {
+        loop {
+            match std::fs::read_dir(path) {
+                Ok(entries) => {
+                    if entries.count() == expected {
+                        break;
+                    }
+                    tokio::time::sleep(Duration::from_millis(20)).await;
+                }
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound && expected == 0 => {
+                    break;
+                }
+                Err(error) => panic!("read plugin cache: {error}"),
+            }
+        }
+    })
+    .await
+    .expect("plugin generation resources should reach the expected count");
+}
+
+async fn publish(core: &gateway_core::CoreBundle, revision: u64) {
+    core.snapshot_control()
+        .publish_committed(ConfigRevision::new(revision).unwrap())
+        .await;
+}
+
+async fn install_artifact_version(
+    store: &dyn PluginStore,
+    source_digest: &str,
+    version: &str,
+) -> String {
+    let artifact = store.load_artifact(source_digest).await.unwrap();
+    let package = ValidatedPackage::read(artifact.archive, None, PackageLimits::default()).unwrap();
+    let mut manifest = package.manifest().clone();
+    manifest.version = version.parse().unwrap();
+    let archive = archive(BTreeMap::from([
+        ("plugin.json".into(), serde_json::to_vec(&manifest).unwrap()),
+        ("bin/worker".into(), worker().to_vec()),
+    ]));
+    let artifact = PackageInspector::new(PackageLimits::default(), "1.0.0".parse().unwrap())
+        .inspect(archive, None)
+        .await
+        .unwrap();
+    let installed = store
+        .install_artifact(artifact, PluginSource::Upload, &mutation())
+        .await
+        .unwrap();
+    store
+        .accept_artifact(&installed.artifact.metadata.sha256, &mutation())
+        .await
+        .unwrap()
+        .artifact
+        .metadata
+        .sha256
+}
+
+#[tokio::test]
+async fn event_envelope_preserves_raw_bytes_metadata_and_bound_continuation() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    environment.account(None).await;
+    let raw = b": keep comment\r\nid: frame-1\r\nretry: 123\r\nevent: response.created\r\ndata: {\"type\":\"response.created\",\r\ndata: \"response\":{\"id\":\"response-plugin\"}}\r\n\r\n".as_slice();
+    let raw_json = b"{ \"z\": 1, \"a\": 2 }\n".as_slice();
+    let raw_body = b"opaque raw http body".as_slice();
+    let (runtime, core) = environment.provider(json!({
+        "output_formats":["canonical","openai"],
+        "execution_events":[
+            {"observation":{"status":200,"request_id":"opaque request-id","http_version":"http2","timings":{"headers_ms":7},"client_headers":[{"name":"retry-after","value":b"12".as_slice()}]}},
+            {"facts":[{"type":"started","id":"response-plugin","model":"plugin-model"}],"wire":{"protocol":"openai","payload":{"kind":"json","event":"response.created","id":"frame-1","retry":123,"data":{"type":"response.created","response":{"id":"response-plugin"}},"raw_sse":raw}}},
+            {"wire":{"protocol":"openai","payload":{"kind":"raw_sse","frame":b": comment only\n\n".as_slice()}}},
+            {"wire":{"protocol":"openai","payload":{"kind":"raw_json","body":raw_json}}},
+            {"observation":{"status":200,"client_headers":[{"name":"content-type","value":b"application/octet-stream".as_slice()}]},"wire":{"protocol":"openai","payload":{"kind":"raw_body","body":raw_body}}},
+            {"facts":[{"type":"usage","usage":{"input_tokens":7}},{"type":"completed","id":"response-plugin","model":"plugin-model","reason":"stop"}],"wire":{"protocol":"openai","payload":{"kind":"json","event":"response.completed","data":{"type":"response.completed","response":{"id":"response-plugin"}}}},"session_update":{"payload":{"turn":"private checkpoint"}}}
+        ]
+    }), vec![account_grant("accounts")]).await;
+    let events = execute(&runtime, &core, None).await.unwrap();
+    assert_eq!(events.len(), 6);
+    let observation = events[0].response_observation().unwrap();
+    assert_eq!(observation.status_code(), Some(200));
+    assert_eq!(
+        observation.request_id().unwrap().as_str(),
+        "opaque request-id"
+    );
+    assert_eq!(observation.http_version(), Some(UpstreamHttpVersion::Http2));
+    assert_eq!(observation.timings().headers_ms, Some(7));
+    assert_eq!(
+        observation.client_headers()[0].value().as_ref(),
+        b"12".as_slice()
+    );
+    assert_eq!(
+        events[1]
+            .wire_event()
+            .unwrap()
+            .raw_sse_frame()
+            .unwrap()
+            .as_ref(),
+        raw
+    );
+    assert!(matches!(
+        events[1].canonical_facts(),
+        [GatewayEvent::Started(_)]
+    ));
+    assert_eq!(
+        events[2]
+            .wire_event()
+            .unwrap()
+            .raw_sse_frame()
+            .unwrap()
+            .as_ref(),
+        b": comment only\n\n".as_slice()
+    );
+    assert_eq!(
+        events[3]
+            .wire_event()
+            .unwrap()
+            .raw_json_body()
+            .unwrap()
+            .as_ref(),
+        raw_json
+    );
+    assert_eq!(
+        events[4]
+            .wire_event()
+            .unwrap()
+            .raw_http_body_bytes()
+            .unwrap()
+            .as_ref(),
+        raw_body
+    );
+    let raw_observation = events[4].response_observation().unwrap();
+    assert_eq!(raw_observation.client_headers().len(), 1);
+    assert_eq!(raw_observation.client_headers()[0].name(), "content-type");
+    let state = events[5].session_update().unwrap();
+    assert_eq!(state.provider(), "example");
+    assert_eq!(
+        execute(&runtime, &core, Some(state.clone()))
+            .await
+            .unwrap()
+            .len(),
+        6
+    );
+    // 宿主私有绑定在 RPC 前拒绝，不能切账号、换凭据或跨实例授权重用。
+    for (field, value) in [
+        ("account_id", json!("another-account")),
+        ("credential_revision", json!(999)),
+        ("authorization", json!("other-instance")),
+        ("continuation_authorization", json!("other-authority")),
+        ("execution_owner", json!("not-a-host-owner")),
+        ("provider", json!("other-provider")),
+    ] {
+        let mut payload = state.payload().clone();
+        payload["binding"][field] = value;
+        let invalid = ProviderSessionState::new("example", payload).unwrap();
+        let error = execute(&runtime, &core, Some(invalid)).await.unwrap_err();
+        assert_eq!(error.kind(), ProviderErrorKind::InvalidRequest);
+        assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+    }
+    drop(events);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn declared_continuation_format_survives_artifact_upgrade_but_not_authority_changes() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let account_id = environment.account(None).await;
+    let grants = vec![account_grant("accounts")];
+    environment
+        .install_provider(
+            json!({
+                "continuation_state":{"format":"example.responses","write_version":1,"readable_versions":[1]},
+                "execution_events":[
+                    {"facts":[{"type":"started","id":"response-plugin","model":"plugin-model"}]},
+                    {"facts":[{"type":"completed","id":"response-plugin","model":"plugin-model","reason":"stop"}],"session_update":{"payload":{"turn":"opaque-v1"}}}
+                ]
+            }),
+            grants,
+        )
+        .await;
+
+    let store = environment.store.admin_ports().plugins();
+    let snapshot = store.load_instances().await.unwrap();
+    let initial_digest = snapshot.instances[0].artifact_sha256.clone();
+    let artifact = store.load_artifact(&initial_digest).await.unwrap();
+    let package = ValidatedPackage::read(artifact.archive, None, PackageLimits::default()).unwrap();
+    let mut manifest = package.manifest().clone();
+    manifest.version = "1.0.1".parse().unwrap();
+    let next_archive = archive(BTreeMap::from([
+        ("plugin.json".into(), serde_json::to_vec(&manifest).unwrap()),
+        ("bin/worker".into(), worker().to_vec()),
+    ]));
+    let next_artifact = PackageInspector::new(PackageLimits::default(), "1.0.0".parse().unwrap())
+        .inspect(next_archive, None)
+        .await
+        .unwrap();
+    let installed = store
+        .install_artifact(next_artifact, PluginSource::Upload, &mutation())
+        .await
+        .unwrap();
+    let installed = store
+        .accept_artifact(&installed.artifact.metadata.sha256, &mutation())
+        .await
+        .unwrap();
+    let next_digest = installed.artifact.metadata.sha256;
+    assert_ne!(next_digest, initial_digest);
+
+    // 测试 worker 依据不可变制品摘要返回该版本自身的格式声明；实例配置在升级前后不变。
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    let mut by_artifact = serde_json::Map::new();
+    by_artifact.insert(
+        next_digest.clone(),
+        json!({"format":"example.responses","write_version":2,"readable_versions":[1,2]}),
+    );
+    instance.configuration.as_object_mut().unwrap().insert(
+        "continuation_state_by_artifact".into(),
+        serde_json::Value::Object(by_artifact),
+    );
+    store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+
+    let (runtime, core) = environment.runtime().await;
+    let events = execute(&runtime, &core, None).await.unwrap();
+    let state = continuation_state(&events);
+    assert_eq!(
+        state.payload()["binding"]["continuation_state"],
+        json!({"format":"example.responses","version":1})
+    );
+
+    // 发布新制品时旧快照模拟在途请求；发布后新请求使用新解释器，旧资源直到引用释放才回收。
+    let old_snapshot = core.snapshots().acquire().unwrap();
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    instance.artifact_sha256.clone_from(&next_digest);
+    let saved = store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    publish(&core, saved.config_revision.get()).await;
+    drop(events);
+    let events = execute(&runtime, &core, Some(state.clone())).await.unwrap();
+    let upgraded_state = continuation_state(&events);
+    assert_eq!(
+        upgraded_state.payload()["binding"]["continuation_state"],
+        json!({"format":"example.responses","version":2})
+    );
+    assert!(execute(&runtime, &core, Some(upgraded_state)).await.is_ok());
+    assert_eq!(
+        std::fs::read_dir(environment.directory.path().join("cache"))
+            .unwrap()
+            .count(),
+        2
+    );
+    drop(old_snapshot);
+    wait_until_entry_count(&environment.directory.path().join("cache"), 1).await;
+
+    for (field, value) in [("format", json!("another.format")), ("version", json!(3))] {
+        let mut payload = state.payload().clone();
+        payload["binding"]["continuation_state"][field] = value;
+        let invalid = ProviderSessionState::new("example", payload).unwrap();
+        assert_replay_required(&execute(&runtime, &core, Some(invalid)).await.unwrap_err());
+    }
+
+    drop(events);
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    instance
+        .configuration
+        .as_object_mut()
+        .unwrap()
+        .insert("authorization_change".into(), json!(true));
+    let saved = store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    publish(&core, saved.config_revision.get()).await;
+    assert_replay_required(
+        &execute(&runtime, &core, Some(state.clone()))
+            .await
+            .unwrap_err(),
+    );
+
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    instance
+        .configuration
+        .as_object_mut()
+        .unwrap()
+        .remove("authorization_change");
+    let saved = store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    publish(&core, saved.config_revision.get()).await;
+    assert!(execute(&runtime, &core, Some(state.clone())).await.is_ok());
+
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    instance
+        .grants
+        .retain(|grant| grant.permission != "accounts");
+    // 授权来自制品接受事实；配置写入不能另造一份权限集合。
+    assert!(
+        store
+            .save_instance(instance, snapshot.config_revision, &mutation())
+            .await
+            .is_err()
+    );
+    assert!(execute(&runtime, &core, Some(state.clone())).await.is_ok());
+
+    let registry = runtime.admin_registry(core.snapshots());
+    let admin = environment.store.admin_ports();
+    let credentials = CredentialsService::new(
+        registry.clone(),
+        admin.accounts(),
+        admin.proxies(),
+        core.snapshot_control(),
+    );
+    credentials
+        .for_provider(&ProviderKind::new("example").unwrap())
+        .unwrap()
+        .rotate(RotateCredential {
+            mutation: CredentialMutation {
+                account_id,
+                context: mutation(),
+            },
+            provider_material: ProviderDocument::new(OpaqueProviderData::new(
+                json!({"key":"rotated-continuation-test"})
+                    .as_object()
+                    .unwrap()
+                    .clone(),
+            )),
+            settings: None,
+        })
+        .await
+        .unwrap();
+    assert_replay_required(&execute(&runtime, &core, Some(state)).await.unwrap_err());
+
+    drop(credentials);
+    drop(registry);
+    drop(admin);
+    environment.release_plugin_accounts(&runtime);
+    drop(core);
+    drop(runtime);
+    drop(store);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn incompatible_upgrade_uses_retired_executor_but_current_disable_wins() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    environment.account(None).await;
+    environment
+        .install_provider(
+            json!({
+                "execution_events":[
+                    {"facts":[{"type":"started","id":"response-old","model":"plugin-model"}]},
+                    {"facts":[{"type":"completed","id":"response-old","model":"plugin-model","reason":"stop"}],"session_update":{"payload":{"executor":"old"}}}
+                ]
+            }),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let store = environment.store.admin_ports().plugins();
+    let snapshot = store.load_instances().await.unwrap();
+    let initial_digest = snapshot.instances[0].artifact_sha256.clone();
+    let next_digest = install_artifact_version(store.as_ref(), &initial_digest, "1.0.1").await;
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    instance.configuration["execution_events_by_artifact"] = json!({
+        next_digest.clone():[
+            {"facts":[{"type":"started","id":"response-new","model":"plugin-model"}]},
+            {"facts":[{"type":"completed","id":"response-new","model":"plugin-model","reason":"stop"}],"session_update":{"payload":{"executor":"new"}}}
+        ]
+    });
+    store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+
+    let (runtime, core) = environment.runtime().await;
+    let initial = execute(&runtime, &core, None).await.unwrap();
+    let state = continuation_state(&initial);
+    assert_eq!(state.payload()["payload"]["executor"], "old");
+    drop(initial);
+
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    instance.artifact_sha256.clone_from(&next_digest);
+    let saved = store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    publish(&core, saved.config_revision.get()).await;
+    let resumed = execute(&runtime, &core, Some(state.clone())).await.unwrap();
+    assert_eq!(
+        continuation_state(&resumed).payload()["payload"]["executor"],
+        "old"
+    );
+    drop(resumed);
+
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    instance.enabled = false;
+    let saved = store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    publish(&core, saved.config_revision.get()).await;
+    let snapshot = core.snapshots().acquire().unwrap();
+    let registry = runtime
+        .provider_registry()
+        .for_extensions(snapshot.extensions())
+        .unwrap();
+    assert!(!registry.contains(&ProviderKind::new("example").unwrap()));
+    drop(registry);
+    drop(snapshot);
+
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    instance.enabled = true;
+    let saved = store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    publish(&core, saved.config_revision.get()).await;
+    // 停用期间入口已移除；重新启用相同权限与配置后，未到期的旧执行器仍可排空续链。
+    let resumed = execute(&runtime, &core, Some(state)).await.unwrap();
+    assert_eq!(
+        continuation_state(&resumed).payload()["payload"]["executor"],
+        "old"
+    );
+    drop(resumed);
+
+    // 当前代次仍由 Core 保活，旧执行器仍由续写排空表保活；显式关闭必须同时回收两者。
+    runtime.shutdown().await;
+    wait_until_entry_count(&environment.directory.path().join("cache"), 0).await;
+
+    environment.release_plugin_accounts(&runtime);
+    drop(core);
+    drop(runtime);
+    drop(store);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn retired_executor_expires_without_sliding_on_continuation_use() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    environment.account(None).await;
+    environment
+        .install_provider(
+            json!({
+                "execution_events":[
+                    {"facts":[{"type":"started","id":"response","model":"plugin-model"}]},
+                    {"facts":[{"type":"completed","id":"response","model":"plugin-model","reason":"stop"}],"session_update":{"payload":{"turn":1}}}
+                ]
+            }),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let store = environment.store.admin_ports().plugins();
+    let snapshot = store.load_instances().await.unwrap();
+    let initial_digest = snapshot.instances[0].artifact_sha256.clone();
+    let next_digest = install_artifact_version(store.as_ref(), &initial_digest, "1.0.1").await;
+    let (runtime, core) = environment
+        .runtime_with_continuation_drain(ContinuationDrainConfig {
+            retention: Duration::from_millis(500),
+            maximum_generations: NonZeroUsize::new(64).unwrap(),
+            maximum_per_instance: NonZeroUsize::new(2).unwrap(),
+        })
+        .await;
+    let state = continuation_state(&execute(&runtime, &core, None).await.unwrap());
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    instance.artifact_sha256 = next_digest;
+    let saved = store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    publish(&core, saved.config_revision.get()).await;
+    let expected = store.load_instances().await.unwrap();
+    let published = core
+        .snapshots()
+        .snapshot_for_diagnostics()
+        .expect("published plugin generation");
+    let diagnostics = PluginPreparation::runtime_diagnostics(
+        runtime.as_ref(),
+        &expected,
+        Some(published.revision().get()),
+        published.extensions(),
+    )
+    .await
+    .expect("runtime diagnostics");
+    assert_eq!(
+        diagnostics[&expected.instances[0].id].retained_continuations,
+        1
+    );
+    tokio::time::sleep(Duration::from_millis(350)).await;
+    assert!(execute(&runtime, &core, Some(state.clone())).await.is_ok());
+    // 使用旧执行器不会延长从撤下时开始的固定期限。
+    tokio::time::sleep(Duration::from_millis(250)).await;
+    assert_replay_required(&execute(&runtime, &core, Some(state)).await.unwrap_err());
+    wait_until_entry_count(&environment.directory.path().join("cache"), 1).await;
+
+    environment.release_plugin_accounts(&runtime);
+    drop(core);
+    drop(runtime);
+    drop(store);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn retired_executor_capacity_evicts_the_oldest_owner() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    environment.account(None).await;
+    environment
+        .install_provider(
+            json!({
+                "execution_events":[
+                    {"facts":[{"type":"started","id":"response","model":"plugin-model"}]},
+                    {"facts":[{"type":"completed","id":"response","model":"plugin-model","reason":"stop"}],"session_update":{"payload":{"turn":1}}}
+                ]
+            }),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let store = environment.store.admin_ports().plugins();
+    let snapshot = store.load_instances().await.unwrap();
+    let digest1 = snapshot.instances[0].artifact_sha256.clone();
+    let digest2 = install_artifact_version(store.as_ref(), &digest1, "1.0.1").await;
+    let digest3 = install_artifact_version(store.as_ref(), &digest1, "1.0.2").await;
+    let digest4 = install_artifact_version(store.as_ref(), &digest1, "1.0.3").await;
+    let (runtime, core) = environment
+        .runtime_with_continuation_drain(ContinuationDrainConfig {
+            retention: Duration::from_secs(30 * 60),
+            maximum_generations: NonZeroUsize::new(2).unwrap(),
+            maximum_per_instance: NonZeroUsize::new(2).unwrap(),
+        })
+        .await;
+    let state1 = continuation_state(&execute(&runtime, &core, None).await.unwrap());
+
+    let mut states = Vec::new();
+    for digest in [&digest2, &digest3] {
+        let snapshot = store.load_instances().await.unwrap();
+        let mut instance = snapshot.instances.into_iter().next().unwrap();
+        instance.artifact_sha256.clone_from(digest);
+        let saved = store
+            .save_instance(instance, snapshot.config_revision, &mutation())
+            .await
+            .unwrap();
+        publish(&core, saved.config_revision.get()).await;
+        states.push(continuation_state(
+            &execute(&runtime, &core, None).await.unwrap(),
+        ));
+    }
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    instance.artifact_sha256 = digest4;
+    let saved = store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    publish(&core, saved.config_revision.get()).await;
+    wait_until_entry_count(&environment.directory.path().join("cache"), 3).await;
+
+    assert_replay_required(&execute(&runtime, &core, Some(state1)).await.unwrap_err());
+    assert!(
+        execute(&runtime, &core, Some(states.remove(0)))
+            .await
+            .is_ok()
+    );
+    assert!(
+        execute(&runtime, &core, Some(states.remove(0)))
+            .await
+            .is_ok()
+    );
+
+    environment.release_plugin_accounts(&runtime);
+    drop(core);
+    drop(runtime);
+    drop(store);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn continuation_format_contract_is_bounded_unique_and_self_readable() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    environment.account(None).await;
+    let (runtime, core) = environment
+        .provider(
+            json!({"continuation_state":{"format":"example.responses","write_version":1,"readable_versions":[1]}}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let store = environment.store.admin_ports().plugins();
+    let snapshot = store.load_instances().await.unwrap();
+    let mut cases = vec![
+        json!({"format":"","write_version":1,"readable_versions":[1]}),
+        json!({"format":"unsafe/path","write_version":1,"readable_versions":[1]}),
+        json!({"format":"example.responses","write_version":0,"readable_versions":[1]}),
+        json!({"format":"example.responses","write_version":1,"readable_versions":[]}),
+        json!({"format":"example.responses","write_version":2,"readable_versions":[1]}),
+        json!({"format":"example.responses","write_version":1,"readable_versions":[1,1]}),
+    ];
+    cases.push(json!({
+        "format":"example.responses",
+        "write_version":1,
+        "readable_versions":(1_u32..=33).collect::<Vec<_>>()
+    }));
+    for descriptor in cases {
+        let mut candidate = snapshot.clone();
+        candidate.instances[0].configuration["continuation_state"] = descriptor;
+        let error =
+            PluginPreparation::prepare(runtime.as_ref(), candidate.config_revision, candidate)
+                .await
+                .expect_err("invalid continuation descriptor");
+        assert_eq!(error.message(), "插件续写状态兼容声明无效");
+    }
+    drop(store);
+    environment.release_plugin_accounts(&runtime);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn event_envelope_rejects_ambiguous_frames_unsafe_headers_and_unbound_state() {
+    let invalid = [
+        json!({}),
+        json!({"wire":{"protocol":"undeclared","payload":{"kind":"raw_sse","frame":b"data: {}\n\n".as_slice()}}}),
+        json!({"wire":{"protocol":"openai","payload":{"kind":"raw_sse","frame":b"data: {}\n\ndata: {}\n\n".as_slice()}}}),
+        json!({"wire":{"protocol":"openai","payload":{"kind":"raw_sse","frame":b"data: {}\n".as_slice()}}}),
+        json!({"wire":{"protocol":"openai","payload":{"kind":"json","event":null,"data":{"actual":false},"raw_sse":b"data: {\"actual\":true}\n\n".as_slice()}}}),
+        json!({"wire":{"protocol":"openai","payload":{"kind":"raw_json","body":b"{} {}".as_slice()}}}),
+        json!({"observation":{"status":600}}),
+        json!({"observation":{"client_headers":[{"name":"set-cookie","value":b"private=value".as_slice()}]}}),
+        json!({"observation":{"client_headers":[{"name":"x-safe","value":b"injected\r\nheader: value".as_slice()}]}}),
+        json!({"facts":[{"type":"started","id":"id","model":null}],"session_update":{"payload":{}}}),
+        json!({"facts":[{"type":"completed","id":"id","model":null,"reason":"stop"}],"session_update":{"payload":{"too_large":""}}}),
+        json!({"observation":{"client_headers":[{"name":"content-type","value":b"application/json".as_slice()}]},"wire":{"protocol":"openai","payload":{"kind":"raw_json","body":b"{}".as_slice()}}}),
+    ];
+    for (index, event) in invalid.into_iter().enumerate() {
+        let Some(environment) = Environment::create().await else {
+            eprintln!("SKIP: plugin integration environment absent");
+            return;
+        };
+        environment.account(None).await;
+        let (runtime, core) = environment
+            .provider(
+                json!({"output_formats":["canonical","openai"],"execution_events":[event],"oversize_session_payload":index == 10}),
+                vec![account_grant("accounts")],
+            )
+            .await;
+        let error = execute(&runtime, &core, None).await.unwrap_err();
+        assert_eq!(
+            error.kind(),
+            ProviderErrorKind::Protocol,
+            "invalid envelope case {index}"
+        );
+        assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+        drop(core);
+        drop(runtime);
+        environment.close().await;
+    }
+}
+
+#[tokio::test]
+async fn structured_execution_failure_keeps_client_body_and_host_send_watermark() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    environment.account(None).await;
+    let upstream = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::any())
+        .respond_with(wiremock::ResponseTemplate::new(429).set_body_string("upstream reached"))
+        .expect(1)
+        .mount(&upstream)
+        .await;
+    let network = account_grant("network");
+    let body = b"{ \"error\": {\"message\":\"private upstream response\"} }\n".as_slice();
+    let (runtime, core) = environment.provider(json!({
+        "http_url":upstream.uri(),
+        "execution_events":[{
+            "observation":{"status":429,"request_id":"private-request-id","client_headers":[{"name":"retry-after","value":b"2".as_slice()}]},
+            "failure":{"kind":"rate_limited","send_state":"not_sent","code":"private-code","retry_after_ms":2000,"response":{"status":429,"content_type":b"application/json".as_slice(),"body":body}}
+        }]
+    }), vec![account_grant("accounts"), network]).await;
+    let error = execute(&runtime, &core, None).await.unwrap_err();
+    assert_eq!(error.kind(), ProviderErrorKind::RateLimited);
+    assert_eq!(error.send_state(), UpstreamSendState::Sent);
+    assert_eq!(error.upstream_status(), Some(429));
+    assert_eq!(
+        error.upstream_request_id().unwrap().as_str(),
+        "private-request-id"
+    );
+    assert_eq!(error.retry_after(), Some(Duration::from_secs(2)));
+    let response = error.client_visible_upstream_response().unwrap();
+    assert_eq!(response.body().as_ref(), body);
+    assert_eq!(response.headers()[0].value().as_ref(), b"2".as_slice());
+    assert!(error.clone().client_visible_upstream_response().is_none());
+    let diagnostic = format!("{error:?}");
+    assert!(!diagnostic.contains("private"));
+    drop(error);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn failure_wire_is_atomic_and_cannot_also_report_completion() {
+    for completed in [false, true] {
+        let Some(environment) = Environment::create().await else {
+            eprintln!("SKIP: plugin integration environment absent");
+            return;
+        };
+        environment.account(None).await;
+        let raw = b"event: response.failed\ndata: {\"type\":\"response.failed\"}\n\n".as_slice();
+        let facts = if completed {
+            json!([{"type":"completed","id":"response","model":null,"reason":"stop"}])
+        } else {
+            json!([])
+        };
+        let (runtime, core) = environment.provider(json!({
+            "output_formats":["canonical","openai"],
+            "execution_events":[{"facts":facts,"wire":{"protocol":"openai","payload":{"kind":"raw_sse","frame":raw}},"failure":{"kind":"unavailable","send_state":"sent","code":null,"retry_after_ms":null,"response":null}}]
+        }), vec![account_grant("accounts")]).await;
+        let mut error = execute(&runtime, &core, None).await.unwrap_err();
+        if completed {
+            assert_eq!(error.kind(), ProviderErrorKind::Protocol);
+            assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+        } else {
+            assert_eq!(error.kind(), ProviderErrorKind::Unavailable);
+            assert_eq!(error.send_state(), UpstreamSendState::Sent);
+            assert!(error.clone().take_atomic_client_events().is_empty());
+            let events = error.take_atomic_client_events();
+            assert_eq!(events.len(), 1);
+            assert_eq!(
+                events[0]
+                    .wire_event()
+                    .unwrap()
+                    .raw_sse_frame()
+                    .unwrap()
+                    .as_ref(),
+                raw
+            );
+        }
+        drop(error);
+        drop(core);
+        drop(runtime);
+        environment.close().await;
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/execution.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/execution.rs
new file mode 100644
index 000000000..68258723b
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/execution.rs
@@ -0,0 +1,1058 @@
+use std::{
+    num::NonZeroU32,
+    sync::Arc,
+    time::{Duration, SystemTime},
+};
+
+use futures::StreamExt as _;
+use gateway_admin::model::plugins::instances::PluginPermissionGrant;
+use gateway_core::{
+    account::{AccountSelectionPolicy, OutboundProxy, RotationStrategy},
+    engine::{
+        AccountAttemptContext, AttemptContext, EngineError, ModelRequestId, RequestAttemptContext,
+        execution::{ClientTransport, ExecutionRequestMetadata, StartExecution},
+        policy::RequestPolicyContext,
+        probe::AccountProbeRequest,
+        provider::ProviderRequest,
+    },
+    error::ProviderErrorKind,
+    event::GatewayEvent,
+    lifecycle::CancellationToken,
+    metering::Decimal,
+    operation::{GenerateRequest, Operation, ProtocolPayload},
+    policy::{ClientApiKeyId, RateLimits},
+    provider_ports::ProviderSessionAffinityKey,
+    routing::{ProviderKind, PublicModelId, RoutingContext, UpstreamModelId},
+    upstream::UpstreamSendState,
+};
+use serde_json::json;
+
+#[tokio::test]
+async fn rust_provider_uses_real_database_leases_and_core_probe_without_sending_during_prepare() {
+    let Some(environment) = crate::support::environment::Environment::create().await else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    run_provider(
+        environment,
+        json!({}),
+        None,
+        network_grant(),
+        Ok(Some("Rust plugin response")),
+    )
+    .await;
+}
+
+#[tokio::test]
+async fn rust_provider_streams_http_through_selected_account_proxy() {
+    let Some(environment) = crate::support::environment::Environment::create().await else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    let proxy = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::header(
+        "proxy-authorization",
+        "Basic dXNlcjpwYXNz",
+    ))
+    .respond_with(
+        wiremock::ResponseTemplate::new(200).set_body_string("managed response ".repeat(200)),
+    )
+    .expect(2)
+    .mount(&proxy)
+    .await;
+    let response = "managed response ".repeat(200);
+    run_provider(
+        environment,
+        json!({"http_url":"http://127.0.0.1:9/model"}),
+        Some(OutboundProxy::parse(&format!("http://user:pass@{}", proxy.address())).unwrap()),
+        network_grant(),
+        Ok(Some(&response)),
+    )
+    .await;
+}
+
+#[tokio::test]
+async fn rust_provider_cannot_downgrade_host_http_send_state() {
+    let Some(environment) = crate::support::environment::Environment::create().await else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    let server = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::any())
+        .respond_with(wiremock::ResponseTemplate::new(200).set_body_string("accepted"))
+        .expect(1)
+        .mount(&server)
+        .await;
+    run_provider(
+        environment,
+        json!({"http_url":server.uri(),"error_after_http":true}),
+        None,
+        network_grant(),
+        Err(UpstreamSendState::Sent),
+    )
+    .await;
+}
+
+#[tokio::test]
+async fn network_domain_does_not_require_origin_prebinding() {
+    let Some(environment) = crate::support::environment::Environment::create().await else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    let server = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::any())
+        .respond_with(wiremock::ResponseTemplate::new(200).set_body_string("domain response"))
+        .expect(2)
+        .mount(&server)
+        .await;
+    run_provider(
+        environment,
+        json!({"http_url":server.uri()}),
+        None,
+        network_grant(),
+        Ok(Some("domain response")),
+    )
+    .await;
+}
+
+#[tokio::test]
+async fn rust_provider_runs_scheduler_rpc_before_lease_and_execution() {
+    let Some(environment) = crate::support::environment::Environment::create().await else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    let kind = ProviderKind::new("example").unwrap();
+    let account_id = environment.account(None).await;
+    let schedule_marker = environment.directory.path().join("scheduled.jsonl");
+    let execution_marker = environment.directory.path().join("executed");
+    let (runtime, core) = environment
+        .provider(
+            json!({
+                "schedule_decision":{"decision":"reject"},
+                "schedule_marker":schedule_marker.to_string_lossy(),
+                "execution_marker":execution_marker.to_string_lossy(),
+                "generation_marker":"scheduler",
+            }),
+            vec![crate::support::environment::account_grant("accounts")],
+        )
+        .await;
+    let ports = environment.store.provider_ports();
+    let snapshot = core.snapshots().acquire().unwrap();
+    let generation = snapshot.extensions().cloned().unwrap();
+    let policy = RequestPolicyContext::new(
+        runtime.policy_registry().resolve(&generation).unwrap(),
+        generation,
+        ModelRequestId::new("req_plugin_scheduler").unwrap(),
+        ClientApiKeyId::new("key_plugin_scheduler").unwrap(),
+        vec![],
+    );
+    let admin_registry = runtime.admin_registry(core.snapshots());
+    let admin = admin_registry.require(&kind).unwrap();
+    let model = UpstreamModelId::new("plugin-model").unwrap();
+    let operation = admin
+        .connection_test_operation(&model, "scheduler")
+        .await
+        .unwrap();
+    let plan = snapshot
+        .plan(
+            &PublicModelId::new("plugin-model").unwrap(),
+            &operation,
+            snapshot.all_account_scope(),
+            &RoutingContext::default(),
+        )
+        .unwrap();
+    let providers = runtime
+        .provider_registry()
+        .for_extensions(snapshot.extensions())
+        .unwrap();
+    let provider = providers.get(&kind).unwrap();
+    let attempt = AttemptContext::new(
+        RequestAttemptContext::new(
+            ModelRequestId::new("req_plugin_scheduler").unwrap(),
+            ClientApiKeyId::new("key_plugin_scheduler").unwrap(),
+        )
+        .with_request_policy(Some(policy)),
+        NonZeroU32::MIN,
+        SystemTime::now() + Duration::from_secs(30),
+        AccountSelectionPolicy::new(
+            RotationStrategy::RoundRobin,
+            NonZeroU32::MIN,
+            Duration::ZERO,
+        ),
+        AccountAttemptContext::default().with_account_scope(snapshot.all_account_scope()),
+        None,
+        CancellationToken::new(),
+    );
+    let error = match Arc::clone(provider)
+        .execute(
+            ProviderRequest::new(operation, plan.candidates()[0].clone()),
+            attempt,
+        )
+        .await
+    {
+        Ok(_) => panic!("scheduler should reject before provider execution"),
+        Err(error) => error,
+    };
+    assert_eq!(error.kind(), ProviderErrorKind::RequestPolicyDenied);
+    assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+    assert_eq!(
+        ports
+            .leases()
+            .account_in_flight(std::slice::from_ref(&account_id))
+            .await
+            .unwrap()[&account_id],
+        0,
+        "明确拒绝发生在账号租约获取前"
+    );
+    assert!(!execution_marker.exists(), "明确拒绝不能进入 Provider 执行");
+    let schedules = std::fs::read_to_string(schedule_marker).unwrap();
+    assert_eq!(schedules.lines().count(), 1, "必须真实派发一次调度 RPC");
+
+    drop(admin);
+    drop(admin_registry);
+    drop(providers);
+    drop(snapshot);
+    drop(core);
+    drop(runtime);
+    drop(ports);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn routing_callback_inherits_admission_and_reads_real_affinity_without_recursing() {
+    let Some(environment) = crate::support::environment::Environment::create().await else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    let provider = ProviderKind::new("example").unwrap();
+    let account_id = environment
+        .account_for_with_concurrency(provider.as_str(), None, Some(1))
+        .await;
+    let _router_account = environment
+        .account_for_with_concurrency("router", None, Some(1))
+        .await;
+    let affinity_key = ProviderSessionAffinityKey::try_new("nested-routing-affinity").unwrap();
+    let ports = environment.store.provider_ports();
+    ports
+        .session_affinity()
+        .bind(
+            &provider,
+            &affinity_key,
+            &account_id,
+            Duration::from_secs(60),
+        )
+        .await
+        .unwrap();
+
+    let route_marker = environment.directory.path().join("nested-route.jsonl");
+    let nested_marker = environment.directory.path().join("nested-model.jsonl");
+    let affinity_marker = environment.directory.path().join("nested-affinity.jsonl");
+    let child_execution_marker = environment.directory.path().join("child-executions.jsonl");
+    let model_grant = crate::support::environment::account_grant("models");
+    let affinity_grant = crate::support::environment::account_grant("requests");
+    let router_credential = crate::support::environment::account_grant("accounts");
+    environment
+        .install_provider(
+            json!({
+                "provider_id":"router",
+                "generation_marker":"nested-router",
+                "route_marker":route_marker,
+                "route_decision":{
+                    "decision":"route",
+                    "provider":"example",
+                    "model":"plugin-model"
+                },
+                "nested_model_fixture":{
+                    "request":{
+                        "model":"plugin-model",
+                        "protocol":"openai",
+                        "operation":"generate",
+                        "provider":"example",
+                        "account_id":account_id.as_str()
+                    },
+                    "body":{"model":"plugin-model","input":"nested routing request"}
+                },
+                "nested_model_marker":nested_marker,
+                "affinity_fixture":{
+                    "request":{
+                        "provider":"example",
+                        "key":affinity_key.expose_to_store()
+                    }
+                },
+                "affinity_marker":affinity_marker,
+            }),
+            vec![model_grant, affinity_grant, router_credential],
+        )
+        .await;
+    environment
+        .install_provider(
+            json!({
+                "provider_id":"example",
+                "generation_marker":"nested-target",
+                "execution_calls_marker":child_execution_marker,
+            }),
+            vec![crate::support::environment::account_grant("accounts")],
+        )
+        .await;
+    let key_secret = "sk-nested-routing-fixture";
+    let key_id = format!("key_{}", uuid::Uuid::new_v4().simple());
+    environment
+        .client_key_with_limits(
+            &key_id,
+            key_secret,
+            RateLimits {
+                max_concurrency: 1,
+                requests_per_minute: 0,
+            },
+        )
+        .await;
+    let (runtime, core) = environment.runtime().await;
+    let execution = core.execution_service();
+    let client = execution.authenticate(key_secret).unwrap();
+    let mut started = tokio::time::timeout(
+        Duration::from_secs(10),
+        execution.start(StartExecution {
+            client,
+            public_model: PublicModelId::new("plugin-model").unwrap(),
+            operation: generate_operation(),
+            metadata: ExecutionRequestMetadata {
+                protocol: "openai".into(),
+                endpoint: "/v1/responses".into(),
+                transport: ClientTransport::HttpJson,
+                stream: false,
+                client_ip: None,
+                user_agent: Some("nested-routing-integration".into()),
+                previous_response_id: None,
+            },
+        }),
+    )
+    .await
+    .expect("nested execution must reuse the admitted Key slot")
+    .unwrap_or_else(|error| {
+        panic!(
+            "routing callback failed: {error:?}; route={:?}; affinity={:?}; nested={:?}",
+            marker_records(&route_marker),
+            marker_records(&affinity_marker),
+            marker_records(&nested_marker),
+        )
+    });
+    let events = tokio::time::timeout(
+        Duration::from_secs(10),
+        started.session.collect_uncommitted(),
+    )
+    .await
+    .expect("parent execution must not recurse into the router")
+    .unwrap();
+    assert!(
+        events
+            .iter()
+            .any(|event| matches!(event.canonical_facts(), [GatewayEvent::Completed(_)]))
+    );
+    started.session.commit_downstream(Some(200)).await.unwrap();
+
+    let route_calls = marker_records(&route_marker);
+    assert_eq!(route_calls.len(), 1, "A→child must suppress router A");
+    let nested_calls = marker_records(&nested_marker);
+    assert_eq!(nested_calls.len(), 1);
+    assert!(nested_calls[0]["events"].as_u64().unwrap() >= 1);
+    let affinity_calls = marker_records(&affinity_marker);
+    assert_eq!(affinity_calls.len(), 1);
+    assert_eq!(
+        affinity_calls[0]["result"]["account_id"],
+        account_id.as_str()
+    );
+    assert_eq!(
+        marker_records(&child_execution_marker).len(),
+        2,
+        "the child and then the parent each execute exactly once"
+    );
+    let markers = format!(
+        "{}{}{}",
+        std::fs::read_to_string(&route_marker).unwrap(),
+        std::fs::read_to_string(&nested_marker).unwrap(),
+        std::fs::read_to_string(&affinity_marker).unwrap()
+    );
+    assert!(!markers.contains(key_secret));
+
+    drop(started);
+    tokio::time::timeout(Duration::from_secs(3), async {
+        while ports
+            .leases()
+            .account_in_flight(std::slice::from_ref(&account_id))
+            .await
+            .unwrap()[&account_id]
+            != 0
+        {
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+    })
+    .await
+    .unwrap();
+    drop(execution);
+    environment.release_plugin_accounts(&runtime);
+    drop(core);
+    drop(runtime);
+    drop(ports);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn cancelling_a_single_slot_parent_reaps_the_child_and_charges_its_cost_once() {
+    let Some(mut environment) = crate::support::environment::Environment::create_command().await
+    else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    // 测试不启动 Host 监督器，直接启动生产同款四个写泵，
+    // 确保终态、计费和准入释放都真实落入 PostgreSQL/Redis。
+    environment.store.start_command_line_writes().unwrap();
+    let parent_account = environment
+        .account_for_with_concurrency("parent", None, Some(1))
+        .await;
+    let child_account = environment
+        .account_for_with_concurrency("child", None, Some(1))
+        .await;
+    let parent_execution_marker = environment.directory.path().join("cancel-parent.jsonl");
+    let child_execution_marker = environment.directory.path().join("cancel-child.jsonl");
+    let child_waiting_marker = environment.directory.path().join("child-waiting.jsonl");
+    let child_cost_consumed_marker = environment.directory.path().join("child-cost.jsonl");
+    let child_stream_trace_marker = environment.directory.path().join("child-stream.jsonl");
+    let child_cancelled_marker = environment.directory.path().join("child-cancelled.jsonl");
+    let parent_credential = crate::support::environment::account_grant("accounts");
+    let model_grant = crate::support::environment::account_grant("models");
+    environment
+        .install_provider(
+            json!({
+                "provider_id":"parent",
+                "generation_marker":"cancel-parent",
+                "execution_calls_marker":parent_execution_marker,
+                "execution_nested_model_fixture":{
+                    "stream_until_after_provider_cost":true,
+                    "request":{
+                        "model":"child-model",
+                        "protocol":"openai",
+                        "operation":"generate",
+                        "provider":"child",
+                        "account_id":child_account.as_str()
+                    },
+                    "body":{"model":"child-model","input":"cancel the active child"}
+                },
+                "execution_nested_model_marker":child_cost_consumed_marker,
+                "nested_stream_trace_marker":child_stream_trace_marker
+            }),
+            vec![parent_credential, model_grant],
+        )
+        .await;
+    let child_credential = crate::support::environment::account_grant("accounts");
+    environment
+        .install_provider(
+            json!({
+                "provider_id":"child",
+                "generation_marker":"cancel-child",
+                "static_models":[{"id":"child-model","operations":["generate"]}],
+                "output_formats":["canonical","openai"],
+                "execution_calls_marker":child_execution_marker,
+                "execution_wait_for_cancel_marker":child_waiting_marker,
+                "execution_cancelled_marker":child_cancelled_marker,
+                "execution_events":[
+                    {"facts":[{"type":"started","id":"cancel-child","model":"child-model"}]},
+                    {"facts":[{"type":"provider_cost","amount":"0.0125","currency":"USD"}]},
+                    {
+                        "facts":[
+                            {"type":"content_added","index":0,"kind":"text"},
+                            {"type":"text_delta","index":0,"text":"visible after cost"}
+                        ],
+                        "wire":{
+                            "protocol":"openai",
+                            "payload":{
+                                "kind":"json",
+                                "event":"response.output_text.delta",
+                                "data":{"delta":"visible after cost"}
+                            }
+                        }
+                    }
+                ]
+            }),
+            vec![child_credential],
+        )
+        .await;
+    let key_secret = "sk-nested-cancel-fixture";
+    let key_id = format!("key_{}", uuid::Uuid::new_v4().simple());
+    environment
+        .client_key_with_limits(
+            &key_id,
+            key_secret,
+            RateLimits {
+                max_concurrency: 1,
+                requests_per_minute: 0,
+            },
+        )
+        .await;
+    let ports = environment.store.provider_ports();
+    let (runtime, core) = environment.runtime().await;
+    let execution = core.execution_service();
+    let client = execution.authenticate(key_secret).unwrap();
+    let mut started = execution
+        .start(StartExecution {
+            client,
+            public_model: PublicModelId::new("plugin-model").unwrap(),
+            operation: generate_operation(),
+            metadata: ExecutionRequestMetadata {
+                protocol: "openai".into(),
+                endpoint: "/v1/responses".into(),
+                transport: ClientTransport::HttpJson,
+                stream: false,
+                client_ip: None,
+                user_agent: Some("nested-cancel-single-slot".into()),
+                previous_response_id: None,
+            },
+        })
+        .await
+        .unwrap();
+    let mut next = started.session.next_event();
+    tokio::select! {
+        biased;
+        () = wait_for_marker(&child_cost_consumed_marker) => {}
+        result = &mut next => panic!(
+            "parent completed before cancellation: {result:?}; parent={:?}; child={:?}; waiting={:?}; barrier={:?}; stream={:?}",
+            marker_records(&parent_execution_marker),
+            marker_records(&child_execution_marker),
+            marker_records(&child_waiting_marker),
+            marker_records(&child_cost_consumed_marker),
+            marker_records(&child_stream_trace_marker),
+        ),
+    }
+    drop(next);
+    assert_eq!(marker_records(&parent_execution_marker).len(), 1);
+    assert_eq!(marker_records(&child_execution_marker).len(), 1);
+    assert_eq!(marker_records(&child_waiting_marker).len(), 1);
+    assert!(
+        marker_records(&child_cost_consumed_marker)[0]["after_provider_cost_consumed"]
+            .as_bool()
+            .unwrap_or(false)
+    );
+
+    started.session.cancel();
+    tokio::time::timeout(Duration::from_secs(3), started.session.detach_finalize())
+        .await
+        .expect("parent and child cleanup must be bounded");
+    wait_for_marker(&child_cancelled_marker).await;
+    assert_eq!(marker_records(&child_cancelled_marker).len(), 1);
+
+    let ledger = tokio::time::timeout(Duration::from_secs(5), async {
+        loop {
+            let ledger = environment.model_request_ledger(&key_id).await;
+            if ledger.len() >= 2
+                && ledger.iter().all(|request| request.completed)
+                && ledger
+                    .iter()
+                    .all(|request| request.charged_amount.is_some())
+            {
+                break ledger;
+            }
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+    })
+    .await;
+    let ledger = match ledger {
+        Ok(ledger) => ledger,
+        Err(_) => panic!(
+            "parent and child ledger writes must drain; last facts: {:?}",
+            environment.model_request_ledger(&key_id).await,
+        ),
+    };
+    assert_eq!(
+        ledger.len(),
+        2,
+        "one parent and one child request are expected"
+    );
+    let parent = ledger
+        .iter()
+        .find(|request| request.provider_kind.as_deref() == Some("parent"))
+        .expect("parent ledger row");
+    let child = ledger
+        .iter()
+        .find(|request| request.provider_kind.as_deref() == Some("child"))
+        .expect("child ledger row");
+    assert_ne!(parent.request_id, child.request_id);
+    assert!(parent.completed);
+    assert_eq!(parent.outcome, "cancelled");
+    assert_eq!(parent.cost_source, "unavailable");
+    assert!(parent.cost_amount.is_none());
+    assert!(child.completed);
+    assert_eq!(child.outcome, "cancelled");
+    assert_eq!(child.request_kind.as_deref(), Some("plugin_child_model"));
+    assert!(child.subagent_kind.is_some());
+    assert_eq!(child.cost_source, "provider_reported");
+    assert_eq!(
+        child
+            .cost_amount
+            .as_deref()
+            .unwrap()
+            .parse::<Decimal>()
+            .unwrap()
+            .canonical(),
+        "0.0125"
+    );
+    let charges = ledger
+        .iter()
+        .map(|request| {
+            request
+                .charged_amount
+                .as_deref()
+                .unwrap()
+                .parse::<Decimal>()
+                .unwrap()
+        })
+        .collect::<Vec<_>>();
+    assert_eq!(
+        parent
+            .charged_amount
+            .as_deref()
+            .unwrap()
+            .parse::<Decimal>()
+            .unwrap(),
+        Decimal::ZERO
+    );
+    assert_eq!(
+        child
+            .charged_amount
+            .as_deref()
+            .unwrap()
+            .parse::<Decimal>()
+            .unwrap()
+            .canonical(),
+        "0.0125"
+    );
+    let charged = charges
+        .iter()
+        .copied()
+        .fold(Decimal::ZERO, |total, amount| {
+            total.checked_add(amount).unwrap()
+        });
+    assert_eq!(charged.canonical(), "0.0125");
+    assert_eq!(
+        charges
+            .iter()
+            .filter(|amount| **amount != Decimal::ZERO)
+            .count(),
+        1,
+        "the orchestrating parent must not duplicate the child's upstream cost"
+    );
+
+    let accounts = [parent_account, child_account];
+    tokio::time::timeout(Duration::from_secs(3), async {
+        loop {
+            let in_flight = ports.leases().account_in_flight(&accounts).await.unwrap();
+            if in_flight.values().all(|count| *count == 0) {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+    })
+    .await
+    .expect("parent and child account leases must be released");
+
+    drop(execution);
+    environment.release_plugin_accounts(&runtime);
+    drop(core);
+    drop(runtime);
+    drop(ports);
+    environment
+        .store
+        .shutdown_command_line_writes()
+        .await
+        .unwrap();
+    environment.close().await;
+}
+
+fn marker_records(path: &std::path::Path) -> Vec<serde_json::Value> {
+    std::fs::read_to_string(path)
+        .unwrap_or_default()
+        .lines()
+        .map(|line| serde_json::from_str(line).unwrap())
+        .collect()
+}
+
+async fn wait_for_marker(path: &std::path::Path) {
+    tokio::time::timeout(Duration::from_secs(5), async {
+        while marker_records(path).is_empty() {
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .expect("worker marker must arrive");
+}
+
+#[tokio::test]
+async fn provider_nested_model_side_effect_makes_a_claimed_not_sent_failure_non_replayable() {
+    let Some(environment) = crate::support::environment::Environment::create().await else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    let parent_accounts = [
+        environment
+            .account_for_with_concurrency("parent", None, Some(1))
+            .await,
+        environment
+            .account_for_with_concurrency("parent", None, Some(1))
+            .await,
+    ];
+    let child_account = environment
+        .account_for_with_concurrency("child", None, Some(1))
+        .await;
+    let parent_execution_marker = environment.directory.path().join("parent-executions.jsonl");
+    let child_execution_marker = environment.directory.path().join("child-executions.jsonl");
+    let nested_marker = environment.directory.path().join("provider-nested.jsonl");
+    let parent_credential = crate::support::environment::account_grant("accounts");
+    let model_grant = crate::support::environment::account_grant("models");
+    environment
+        .install_provider(
+            json!({
+                "provider_id":"parent",
+                "generation_marker":"nested-parent",
+                "execution_calls_marker":parent_execution_marker,
+                "execution_nested_model_fixture":{
+                    "request":{
+                        "model":"child-model",
+                        "protocol":"openai",
+                        "operation":"generate",
+                        "provider":"child",
+                        "account_id":child_account.as_str()
+                    },
+                    "body":{"model":"child-model","input":"child side effect"}
+                },
+                "execution_nested_model_marker":nested_marker,
+                "error_after_nested_model":true,
+            }),
+            vec![parent_credential, model_grant],
+        )
+        .await;
+    let child_credential = crate::support::environment::account_grant("accounts");
+    environment
+        .install_provider(
+            json!({
+                "provider_id":"child",
+                "generation_marker":"nested-child",
+                "static_models":[{"id":"child-model","operations":["generate"]}],
+                "execution_calls_marker":child_execution_marker,
+            }),
+            vec![child_credential],
+        )
+        .await;
+    let key_secret = "sk-nested-side-effect-fixture";
+    let key_id = format!("key_{}", uuid::Uuid::new_v4().simple());
+    environment
+        .client_key_with_limits(
+            &key_id,
+            key_secret,
+            RateLimits {
+                max_concurrency: 1,
+                requests_per_minute: 0,
+            },
+        )
+        .await;
+    let (runtime, core) = environment.runtime().await;
+    let execution = core.execution_service();
+    let client = execution.authenticate(key_secret).unwrap();
+    let mut started = execution
+        .start(StartExecution {
+            client,
+            public_model: PublicModelId::new("plugin-model").unwrap(),
+            operation: generate_operation(),
+            metadata: ExecutionRequestMetadata {
+                protocol: "openai".into(),
+                endpoint: "/v1/responses".into(),
+                transport: ClientTransport::HttpJson,
+                stream: false,
+                client_ip: None,
+                user_agent: Some("nested-side-effect-watermark".into()),
+                previous_response_id: None,
+            },
+        })
+        .await
+        .unwrap();
+    let error = tokio::time::timeout(
+        Duration::from_secs(10),
+        started.session.collect_uncommitted(),
+    )
+    .await
+    .unwrap()
+    .expect_err("the parent fixture must fail after the child completed");
+    assert!(matches!(
+        error,
+        EngineError::Provider(ref error) if error.send_state() == UpstreamSendState::Ambiguous
+    ));
+    assert_eq!(marker_records(&parent_execution_marker).len(), 1);
+    assert_eq!(marker_records(&child_execution_marker).len(), 1);
+    assert_eq!(marker_records(&nested_marker).len(), 1);
+
+    started.session.detach_finalize().await;
+    let all_accounts = parent_accounts
+        .iter()
+        .cloned()
+        .chain(std::iter::once(child_account.clone()))
+        .collect::<Vec<_>>();
+    tokio::time::timeout(Duration::from_secs(3), async {
+        loop {
+            let in_flight = environment
+                .store
+                .provider_ports()
+                .leases()
+                .account_in_flight(&all_accounts)
+                .await
+                .unwrap();
+            if all_accounts
+                .iter()
+                .all(|account| in_flight.get(account).copied().unwrap_or(0) == 0)
+            {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+    })
+    .await
+    .unwrap();
+    drop(execution);
+    environment.release_plugin_accounts(&runtime);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+fn generate_operation() -> Operation {
+    Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "openai",
+            json!({"model":"plugin-model","input":"generate"})
+                .as_object()
+                .unwrap()
+                .clone(),
+        )
+        .unwrap(),
+    ))
+}
+
+#[tokio::test]
+async fn network_domain_does_not_override_the_host_live_network_policy() {
+    if std::env::var("CPR_PLUGIN_TEST_LIVE_HTTP").as_deref() != Ok("1") {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_LIVE_HTTP 未启用");
+        return;
+    }
+    let Some(environment) = crate::support::environment::Environment::create().await else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    run_provider(
+        environment,
+        json!({"http_url":"https://api.github.com/zen"}),
+        None,
+        network_grant(),
+        Err(UpstreamSendState::NotSent),
+    )
+    .await;
+}
+
+fn network_grant() -> PluginPermissionGrant {
+    crate::support::environment::account_grant("network")
+}
+
+async fn run_provider(
+    environment: crate::support::environment::Environment,
+    mut configuration: serde_json::Value,
+    proxy: Option<OutboundProxy>,
+    network: PluginPermissionGrant,
+    expected: Result<Option<&str>, UpstreamSendState>,
+) {
+    let kind = ProviderKind::new("example").unwrap();
+    let account_id = environment.account(proxy).await;
+    let ports = environment.store.provider_ports();
+    let marker = environment.directory.path().join("executed");
+    configuration["execution_marker"] = json!(marker);
+    configuration["generation_marker"] = json!("old");
+    let (runtime, core) = environment
+        .provider(
+            configuration,
+            vec![
+                crate::support::environment::account_grant("accounts"),
+                network,
+            ],
+        )
+        .await;
+    let registry = runtime.provider_registry();
+    let snapshot = core.snapshots().acquire().unwrap();
+    let admin_registry = runtime.admin_registry(core.snapshots());
+    let old_admin = admin_registry.require(&kind).unwrap();
+    let model = UpstreamModelId::new("plugin-model").unwrap();
+    assert_eq!(
+        old_admin.models(&account_id, false).await.unwrap().models[0].id,
+        model
+    );
+    let operation = old_admin
+        .connection_test_operation(&model, "hello")
+        .await
+        .unwrap();
+    let plan = snapshot
+        .plan(
+            &PublicModelId::new("plugin-model").unwrap(),
+            &operation,
+            snapshot.all_account_scope(),
+            &RoutingContext::default(),
+        )
+        .unwrap();
+    let providers = registry.for_extensions(snapshot.extensions()).unwrap();
+    let provider = providers.get(&kind).unwrap();
+    let context = AttemptContext::new(
+        RequestAttemptContext::new(
+            ModelRequestId::new("req_plugin_cold").unwrap(),
+            ClientApiKeyId::new("key_plugin_test").unwrap(),
+        ),
+        NonZeroU32::new(1).unwrap(),
+        SystemTime::now() + Duration::from_secs(30),
+        AccountSelectionPolicy::new(
+            RotationStrategy::RoundRobin,
+            NonZeroU32::new(1).unwrap(),
+            Duration::ZERO,
+        ),
+        AccountAttemptContext::default().with_account_scope(snapshot.all_account_scope()),
+        None,
+        CancellationToken::new(),
+    );
+    let mut response = Arc::clone(provider)
+        .execute(
+            ProviderRequest::new(operation.clone(), plan.candidates()[0].clone()),
+            context,
+        )
+        .await
+        .unwrap();
+    assert!(!marker.exists(), "准备完成不能发送业务请求");
+    assert_eq!(
+        ports
+            .leases()
+            .account_in_flight(std::slice::from_ref(&account_id))
+            .await
+            .unwrap()[&account_id],
+        1
+    );
+    let mut events = Vec::new();
+    let mut failure = None;
+    while let Some(event) = response.next().await {
+        match event {
+            Ok(event) => events.push(event),
+            Err(error) => {
+                failure = Some(error);
+                break;
+            }
+        }
+    }
+    assert_eq!(
+        std::fs::read_to_string(&marker).unwrap(),
+        account_id.as_str()
+    );
+    match expected {
+        Ok(_) => {
+            assert!(failure.is_none(), "provider failed: {failure:?}");
+            assert!(events.iter().any(|event| matches!(event.canonical_facts(), [GatewayEvent::ProviderCost(cost)] if cost.total().amount().canonical() == "0.0125")));
+        }
+        Err(state) => assert_eq!(failure.unwrap().send_state(), state),
+    }
+    drop(response);
+    tokio::time::timeout(Duration::from_secs(3), async {
+        while ports
+            .leases()
+            .account_in_flight(std::slice::from_ref(&account_id))
+            .await
+            .unwrap()
+            .get(&account_id)
+            .copied()
+            .unwrap_or(0)
+            != 0
+        {
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+    })
+    .await
+    .unwrap();
+
+    let mut candidate = environment
+        .store
+        .admin_ports()
+        .plugins()
+        .load_instances()
+        .await
+        .unwrap();
+    candidate.instances[0].configuration["generation_marker"] = json!("new");
+    let next = gateway_admin::ports::plugins::PluginPreparation::prepare(
+        runtime.as_ref(),
+        candidate.config_revision,
+        candidate,
+    )
+    .await
+    .unwrap();
+    core.snapshots()
+        .publish(snapshot.as_ref().clone().with_extensions(Some(next)));
+    let current_admin = admin_registry.require(&kind).unwrap();
+    if let Ok(expected_text) = expected {
+        let probe = core
+            .account_probe()
+            .probe(
+                AccountProbeRequest {
+                    account_id,
+                    provider_kind: kind.clone(),
+                    upstream_model: UpstreamModelId::new("plugin-model").unwrap(),
+                    operation,
+                },
+                old_admin.snapshot(),
+            )
+            .await
+            .unwrap();
+        if let Some(text) = expected_text {
+            assert_eq!(probe.text, vec![text]);
+        } else {
+            assert!(!probe.text.concat().is_empty());
+        }
+    }
+    drop(providers);
+    drop(snapshot);
+    // 此时只有管理句柄持有旧集合；发布切换不能在管理操作 await 时关闭其 RPC。
+    let Operation::Generate(old_probe) = old_admin
+        .connection_test_operation(&model, "old")
+        .await
+        .unwrap()
+    else {
+        panic!("probe operation")
+    };
+    let Operation::Generate(new_probe) = current_admin
+        .connection_test_operation(&model, "new")
+        .await
+        .unwrap()
+    else {
+        panic!("probe operation")
+    };
+    assert_eq!(
+        old_probe.protocol_payload().body()["plugin_generation"],
+        "old"
+    );
+    assert_eq!(
+        new_probe.protocol_payload().body()["plugin_generation"],
+        "new"
+    );
+    drop(old_admin);
+    tokio::time::timeout(Duration::from_secs(3), async {
+        while std::fs::read_dir(environment.directory.path().join("cache"))
+            .unwrap()
+            .count()
+            != 1
+        {
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+    })
+    .await
+    .unwrap();
+    drop(current_admin);
+    drop(admin_registry);
+    drop(core);
+    drop(runtime);
+    drop(ports);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/forecast.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/forecast.rs
new file mode 100644
index 000000000..5f89ab029
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/forecast.rs
@@ -0,0 +1,377 @@
+use chrono::{DateTime, Utc};
+use gateway_admin::model::provider_credentials::{
+    ProviderDocument, ProviderQuotaRequest, ProviderQuotaWindow, ProviderQuotaWindowRole,
+    QuotaLocalUsageAttribution,
+};
+use gateway_core::{
+    account::OpaqueProviderData,
+    engine::{
+        CommitRequirement,
+        execution::{ClientTransport, ExecutionRequestMetadata, StartExecution},
+    },
+    error::ProviderErrorKind,
+    operation::{GenerateRequest, Operation, ProtocolPayload},
+    routing::{ConfigRevision, ProviderKind, PublicModelId},
+};
+use serde_json::{Value, json};
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+const RESET_AT_MS: i64 = 1_800_000_000_000;
+
+fn forecast() -> Value {
+    json!({"plan_type":"plugin-pro","windows":[{
+        "key":"weekly","group":"chat","limit_id":"chat-main","role":"secondary",
+        "account_wide":true,"window_seconds":604800,"used_percent":25.0,"reset_at_ms":RESET_AT_MS
+    }]})
+}
+
+fn configuration(value: Value) -> Value {
+    json!({
+        "quota_url":"http://127.0.0.1:1/not-requested",
+        "execution_events":[
+            {"observation":{"quota_forecast":value}},
+            {"facts":[{"type":"started","id":"forecast-response","model":"plugin-model"}]},
+            {"facts":[{"type":"usage","usage":{"input_tokens":5,"output_tokens":2,"total_tokens":7}},
+                {"type":"completed","id":"forecast-response","model":"plugin-model","reason":"stop"}]}
+        ]
+    })
+}
+
+fn window() -> ProviderQuotaWindow {
+    ProviderQuotaWindow {
+        key: "weekly".into(),
+        group: "chat".into(),
+        label: "Weekly quota".into(),
+        limit_id: Some("chat-main".into()),
+        limit_name: None,
+        role: Some(ProviderQuotaWindowRole::Secondary),
+        local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+        window_seconds: Some(604800),
+        used_percent: Some(50.0),
+        reset_at: DateTime::<Utc>::from_timestamp_millis(RESET_AT_MS),
+        limit_reached: false,
+        local_usage: None,
+        provider_data: None,
+    }
+}
+
+async fn complete_request(core: &gateway_core::CoreBundle, key: &str) {
+    let execution = core.execution_service();
+    let client = execution.authenticate(key).unwrap();
+    let mut started = execution
+        .start(StartExecution {
+            client,
+            public_model: PublicModelId::new("plugin-model").unwrap(),
+            operation: Operation::Generate(GenerateRequest::from_protocol_payload(
+                ProtocolPayload::json_object(
+                    "openai",
+                    json!({"model":"plugin-model","input":"forecast fixture","stream":true})
+                        .as_object()
+                        .unwrap()
+                        .clone(),
+                )
+                .unwrap(),
+            )),
+            metadata: ExecutionRequestMetadata {
+                protocol: "openai".into(),
+                endpoint: "/v1/responses".into(),
+                transport: ClientTransport::HttpSse,
+                stream: true,
+                client_ip: None,
+                user_agent: Some("plugin-forecast-test".into()),
+                previous_response_id: None,
+            },
+        })
+        .await
+        .unwrap();
+    let mut committed = false;
+    while let Some(event) = started.session.next_event().await.unwrap() {
+        if !committed && event.commit_requirement() == CommitRequirement::CommitBeforeDelivery {
+            started.session.commit_downstream(Some(200)).await.unwrap();
+            committed = true;
+        }
+    }
+    assert!(committed);
+    assert!(started.session.is_finalized());
+}
+
+#[tokio::test]
+async fn core_persists_quota_facts_and_admin_pairs_them_after_generation_changes() {
+    use gateway_admin::model::{accounts::AccountUsageWindowQuery, observability::TimeRange};
+
+    let Some(mut environment) = Environment::create_command().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let account = environment.account(None).await;
+    let key_id = format!("key_{}", uuid::Uuid::new_v4().simple());
+    let key = format!("sk-forecast-{}", uuid::Uuid::new_v4().simple());
+    environment.client_key(&key_id, &key).await;
+    let reset = Utc::now() + chrono::Duration::days(3);
+    let mut observed = forecast();
+    observed["windows"][0]["reset_at_ms"] = json!(reset.timestamp_millis());
+    let mut current = observed.clone();
+    current["access"] = json!({"kind":"allowed"});
+    current["windows"][0]["label"] = json!("Weekly quota");
+    current["windows"][0]["used_percent"] = json!(50.0);
+    current["windows"][0]["limit_reached"] = json!(false);
+    let current: gateway_plugin_sdk::call::provider::quota::Quota =
+        serde_json::from_value(current).unwrap();
+    let server = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::header(
+        "authorization",
+        "Bearer test-only",
+    ))
+    .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(current))
+    .expect(1)
+    .mount(&server)
+    .await;
+    let network = account_grant("network");
+    let mut config = configuration(observed.clone());
+    config["quota_url"] = json!(server.uri());
+    let (runtime, core) = environment
+        .provider(config, vec![account_grant("accounts"), network])
+        .await;
+    // 复用 Store 的有界写泵，断言真实 Core 结算持久化；不直接种植请求行或历史文档。
+    environment.store.start_command_line_writes().unwrap();
+    let begin = Utc::now();
+    complete_request(&core, &key).await;
+
+    // 新代次不再上报额度事实；历史解释不能依赖当时的子进程，也不能补造新请求的事实。
+    let store = environment.store.admin_ports().plugins();
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    instance.configuration["execution_events"]
+        .as_array_mut()
+        .unwrap()
+        .remove(0);
+    let changed = store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    core.snapshot_control()
+        .publish_committed(ConfigRevision::new(changed.config_revision.get()).unwrap())
+        .await;
+    complete_request(&core, &key).await;
+    environment
+        .store
+        .shutdown_command_line_writes()
+        .await
+        .unwrap();
+
+    let history = environment
+        .store
+        .admin_ports()
+        .accounts()
+        .load_quota_forecast_history(&AccountUsageWindowQuery {
+            account_id: account.to_string(),
+            key: "weekly".into(),
+            range: TimeRange::new(begin, Utc::now()).unwrap(),
+        })
+        .await
+        .unwrap();
+    assert_eq!(history.pending_request_count, 0);
+    assert_eq!(history.usage.request_count, 2);
+    assert_eq!(history.usage.tokens, 14);
+    assert_eq!(history.points.len(), 1);
+    assert_eq!(history.points[0].usage.request_count, 1);
+    assert_eq!(history.points[0].usage.tokens, 7);
+    assert_eq!(
+        history.points[0]
+            .provider_observation
+            .expose_to_provider()
+            .expose_to_provider(),
+        json!({"plugin_quota_forecast_v1":observed})
+            .as_object()
+            .unwrap()
+    );
+    let other_account = environment.account(None).await;
+    let unrelated = environment
+        .store
+        .admin_ports()
+        .accounts()
+        .load_quota_forecast_history(&AccountUsageWindowQuery {
+            account_id: other_account.to_string(),
+            key: "weekly".into(),
+            range: TimeRange::new(begin, Utc::now()).unwrap(),
+        })
+        .await
+        .unwrap();
+    assert!(
+        unrelated.points.is_empty(),
+        "相同 Provider 和窗口不能串入其他账号历史"
+    );
+    assert_eq!(unrelated.usage.request_count, 0);
+    assert_eq!(unrelated.usage.tokens, 0);
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    provider
+        .quota(ProviderQuotaRequest {
+            account_id: account.clone(),
+            refresh: true,
+            rolling_usage: None,
+        })
+        .await
+        .unwrap();
+    let admin = environment.bind_admin_accounts(&runtime, &core).await;
+    let report = admin
+        .services()
+        .accounts()
+        .quota_forecast(&account)
+        .await
+        .unwrap();
+    let weekly = &report.forecasts[0];
+    assert_eq!(weekly.source.as_ref().unwrap().tokens, Some(14));
+    assert_eq!(weekly.unavailable_reason, None);
+    assert_eq!(weekly.remaining_tokens, Some(14));
+    assert_eq!(weekly.estimated_tokens, Some(28));
+    assert!(
+        weekly.estimated_usd.is_none(),
+        "没有费用事实时不按请求数捏造金额"
+    );
+    assert!(weekly.incomplete_cost);
+    // 只有显式刷新调用过上游；历史查询和预测都只读本地事实。
+    server.verify().await;
+    drop(provider);
+    drop(admin);
+    drop(store);
+    drop(core);
+    runtime.shutdown().await;
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn real_worker_quota_facts_are_projected_locally_with_exact_window_identity() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    environment.account(None).await;
+    let value = forecast();
+    let (runtime, core) = environment
+        .provider(
+            configuration(value.clone()),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let events = super::events::execute(&runtime, &core, None).await.unwrap();
+    let metadata = events[0]
+        .response_observation()
+        .unwrap()
+        .provider_metadata()
+        .unwrap();
+    let saved: Value = serde_json::from_str(metadata.as_json()).unwrap();
+    assert_eq!(saved, json!({"plugin_quota_forecast_v1":value}));
+    assert!(events[0].wire_event().is_none());
+    assert!(events[0].canonical_facts().is_empty());
+    let document =
+        ProviderDocument::new(OpaqueProviderData::new(saved.as_object().unwrap().clone()));
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let expected = provider
+        .quota_forecast_observation(&document, &window())
+        .unwrap();
+    assert_eq!(expected.used_percent, 25.0, "不从当前额度 50% 反推历史");
+    assert_eq!(expected.reset_at.timestamp_millis(), RESET_AT_MS);
+    assert_eq!(expected.plan_type.as_deref(), Some("plugin-pro"));
+    // 发布对象仍持有句柄，但同步历史解释无需活着的子进程或额外权限。
+    runtime.shutdown().await;
+    assert_eq!(
+        provider.quota_forecast_observation(&document, &window()),
+        Some(expected)
+    );
+    for index in 0..6 {
+        let mut mismatch = window();
+        match index {
+            0 => mismatch.key = "monthly".into(),
+            1 => mismatch.group = "images".into(),
+            2 => mismatch.limit_id = None,
+            3 => mismatch.role = Some(ProviderQuotaWindowRole::Primary),
+            4 => mismatch.window_seconds = Some(3600),
+            _ => mismatch.local_usage_attribution = QuotaLocalUsageAttribution::Unavailable,
+        }
+        assert!(
+            provider
+                .quota_forecast_observation(&document, &mismatch)
+                .is_none(),
+            "window mismatch {index}"
+        );
+    }
+    let legacy = ProviderDocument::new(OpaqueProviderData::new(Default::default()));
+    assert!(
+        provider
+            .quota_forecast_observation(&legacy, &window())
+            .is_none()
+    );
+    drop(provider);
+    environment.release_plugin_accounts(&runtime);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn real_worker_rejects_invalid_or_oversized_quota_observations() {
+    let mut invalid = Vec::new();
+    for (field, replacement) in [
+        ("window_seconds", json!(0)),
+        ("used_percent", json!(-1.0)),
+        ("reset_at_ms", json!(i64::MAX)),
+        ("key", json!("")),
+        ("group", json!("invalid\nvalue")),
+        ("limit_id", json!("x".repeat(1025))),
+    ] {
+        let mut value = forecast();
+        value["windows"][0][field] = replacement;
+        invalid.push(value);
+    }
+    let mut duplicate = forecast();
+    duplicate["windows"]
+        .as_array_mut()
+        .unwrap()
+        .push(forecast()["windows"][0].clone());
+    invalid.push(duplicate);
+    for count in [18, 65] {
+        let mut value = forecast();
+        value["windows"] = (0..count)
+            .map(|index| {
+                let mut window = forecast()["windows"][0].clone();
+                window["key"] = json!(format!(
+                    "{index}-{}",
+                    "k".repeat(if count == 18 { 1000 } else { 1 })
+                ));
+                window["group"] = json!("g".repeat(if count == 18 { 1000 } else { 1 }));
+                window
+            })
+            .collect();
+        invalid.push(value);
+    }
+    for (index, value) in invalid.into_iter().enumerate() {
+        let Some(environment) = Environment::create().await else {
+            eprintln!("SKIP: plugin integration environment absent");
+            return;
+        };
+        environment.account(None).await;
+        let (runtime, core) = environment
+            .provider(configuration(value), vec![account_grant("accounts")])
+            .await;
+        let error = super::events::execute(&runtime, &core, None)
+            .await
+            .unwrap_err();
+        assert_eq!(
+            error.kind(),
+            ProviderErrorKind::Protocol,
+            "invalid quota observation {index}"
+        );
+        environment.release_plugin_accounts(&runtime);
+        drop(core);
+        drop(runtime);
+        environment.close().await;
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/invalidation.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/invalidation.rs
new file mode 100644
index 000000000..664b6753c
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/invalidation.rs
@@ -0,0 +1,223 @@
+use std::{path::Path, time::Duration};
+
+use gateway_admin::{
+    CredentialsService,
+    model::provider_credentials::{CredentialMutation, ProviderDocument, RotateCredential},
+};
+use gateway_core::{
+    account::{OpaqueProviderData, ProviderAccountId},
+    routing::{ProviderKind, UpstreamModelId},
+};
+use serde_json::{Value, json};
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+fn observations(path: &Path) -> Vec<Value> {
+    std::fs::read_to_string(path)
+        .unwrap_or_default()
+        .lines()
+        .map(|line| serde_json::from_str(line).unwrap())
+        .collect()
+}
+
+#[tokio::test]
+async fn notifications_are_not_prebound_deduplicate_and_require_network_for_http() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let id = environment.account(None).await;
+    let other = ProviderAccountId::new("acct_outside_grant").unwrap();
+    let marker = environment.directory.path().join("invalidations.jsonl");
+    let denied = environment.directory.path().join("denied.jsonl");
+    let server = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::any())
+        .respond_with(wiremock::ResponseTemplate::new(200))
+        .expect(0)
+        .mount(&server)
+        .await;
+    let (runtime, core) = environment
+        .provider(
+            json!({
+                "account_operations":["unavailable", "facts_changed"],
+                "invalidation_marker":marker, "invalidation_http_url":server.uri(),
+                "invalidation_denied_marker":denied,
+            }),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    provider.account_unavailable(&other).await;
+    provider.account_unavailable(&id).await;
+    provider
+        .account_facts_changed(&[id.clone(), other.clone(), id.clone()])
+        .await;
+    let mut changed = vec![id.as_str(), other.as_str()];
+    changed.sort_unstable();
+    assert_eq!(
+        observations(&marker),
+        vec![
+            json!({"kind":"unavailable", "account_id":other.as_str()}),
+            json!({"kind":"unavailable", "account_id":id.as_str()}),
+            json!({"kind":"facts_changed", "account_ids":changed}),
+        ]
+    );
+    assert_eq!(
+        observations(&denied),
+        vec![json!(true), json!(true), json!(true)]
+    );
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn bulk_notifications_are_bounded_and_undeclared_operations_are_not_called() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let marker = environment.directory.path().join("batches.jsonl");
+    let (runtime, core) = environment
+        .provider(
+            json!({"account_operations":["facts_changed"], "invalidation_marker":marker}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let ids: Vec<_> = (0..513)
+        .map(|index| ProviderAccountId::new(format!("acct_{index:04}")).unwrap())
+        .collect();
+    provider.account_unavailable(&ids[0]).await;
+    provider.account_facts_changed(&[]).await;
+    assert!(observations(&marker).is_empty());
+    provider.account_facts_changed(&ids).await;
+    let events = observations(&marker);
+    assert_eq!(
+        events
+            .iter()
+            .map(|event| event["account_ids"].as_array().unwrap().len())
+            .collect::<Vec<_>>(),
+        vec![256, 256, 1]
+    );
+    let notified: Vec<_> = events
+        .iter()
+        .flat_map(|event| event["account_ids"].as_array().unwrap())
+        .map(|id| id.as_str().unwrap())
+        .collect();
+    assert_eq!(
+        notified,
+        ids.iter()
+            .map(ProviderAccountId::as_str)
+            .collect::<Vec<_>>()
+    );
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn failed_notification_cannot_undo_a_committed_credential_rotation() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let id = environment.account(None).await;
+    let marker = environment.directory.path().join("failed.jsonl");
+    let (runtime, core) = environment
+        .provider(
+            json!({"account_operations":["facts_changed"], "invalidation_marker":marker, "invalidation_fault":true}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let admin = environment.store.admin_ports();
+    let registry = runtime.admin_registry(core.snapshots());
+    let service = CredentialsService::new(
+        registry.clone(),
+        admin.accounts(),
+        admin.proxies(),
+        core.snapshot_control(),
+    );
+    service
+        .for_provider(&ProviderKind::new("example").unwrap())
+        .unwrap()
+        .rotate(RotateCredential {
+            mutation: CredentialMutation {
+                account_id: id.clone(),
+                context: mutation(),
+            },
+            provider_material: ProviderDocument::new(OpaqueProviderData::new(
+                json!({"key":"rotated-test-only"})
+                    .as_object()
+                    .unwrap()
+                    .clone(),
+            )),
+            settings: None,
+        })
+        .await
+        .unwrap();
+    let current = environment
+        .store
+        .provider_ports()
+        .accounts()
+        .load_current_credential(&id)
+        .await
+        .unwrap();
+    assert_eq!(
+        current.credential.expose_to_provider()["key"],
+        "rotated-test-only"
+    );
+    assert_eq!(current.account.revision().get(), 2);
+    assert_eq!(
+        observations(&marker),
+        vec![json!({"kind":"facts_changed", "account_ids":[id.as_str()]})]
+    );
+    drop(service);
+    drop(registry);
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn notification_timeout_ends_the_whole_batch_and_preserves_the_session() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let marker = environment.directory.path().join("timeout.jsonl");
+    let (runtime, core) = environment
+        .provider(
+            json!({"account_operations":["facts_changed"], "invalidation_marker":marker, "invalidation_delay_ms":30_000}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let ids: Vec<_> = (0..513)
+        .map(|index| ProviderAccountId::new(format!("acct_{index:04}")).unwrap())
+        .collect();
+    tokio::time::timeout(Duration::from_secs(4), provider.account_facts_changed(&ids))
+        .await
+        .unwrap();
+    assert_eq!(observations(&marker).len(), 1);
+    provider
+        .connection_test_operation(&UpstreamModelId::new("plugin-model").unwrap(), "test")
+        .await
+        .unwrap();
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/mod.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/mod.rs
new file mode 100644
index 000000000..504d2d317
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/mod.rs
@@ -0,0 +1,15 @@
+mod authorization;
+mod billing;
+mod capabilities;
+mod catalog;
+mod configuration;
+mod credentials;
+mod events;
+mod execution;
+mod forecast;
+mod invalidation;
+mod profile;
+mod quota;
+mod request_profile;
+mod reset_credits;
+mod rotation;
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/profile.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/profile.rs
new file mode 100644
index 000000000..b7d49377f
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/profile.rs
@@ -0,0 +1,536 @@
+use futures::TryStreamExt as _;
+use gateway_admin::{
+    CredentialsService,
+    model::{
+        plugins::instances::PluginPermissionGrant,
+        provider_credentials::{CredentialMutation, ProviderDocument, RotateCredential},
+    },
+    ports::{
+        plugins::{PluginPackageInspector as _, PluginPreparation},
+        provider::ProviderAdminErrorKind,
+    },
+};
+use gateway_core::{account::OpaqueProviderData, routing::ProviderKind};
+use gateway_plugin_sdk::{Capability, Contributions, Permission, Stage};
+use serde_json::{Value, json};
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+fn profile() -> Value {
+    json!({
+        "display_name":"插件用户", "username":"plugin-user", "image_url":"https://example.test/avatar.png",
+        "has_stats_error":false, "summary":{"total_text_tokens":91234, "current_streak_days":7},
+        "daily_usage":[{"date":"2026-09-19", "tokens":1234}],
+        "activity_insights":{"fast_mode_percent":25.0, "reasoning_effort":"high", "reasoning_effort_percent":75.0,
+            "invocations":[{"invocation_type":"skill", "skill_id":"test-skill", "skill_name":"测试技能", "usage_count":8}]},
+    })
+}
+
+fn subscription() -> Value {
+    json!({
+        "starts_at_ms":1_780_000_000_000_i64, "expires_at_ms":1_790_000_000_000_i64,
+        "will_renew":true, "billing_period":"monthly", "billing_currency":"USD", "observed_at_ms":1_785_000_000_000_i64,
+    })
+}
+
+fn configuration() -> Value {
+    json!({"account_operations":["profile", "subscription", "avatar"], "profile":profile(), "subscription":subscription()})
+}
+
+fn grants() -> Vec<PluginPermissionGrant> {
+    vec![account_grant("accounts"), account_grant("network")]
+}
+
+#[tokio::test]
+async fn profile_http_uses_the_accounts_proxy_and_its_credentials() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let proxy = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::header(
+        "proxy-authorization",
+        "Basic dXNlcjpwYXNz",
+    ))
+    .and(wiremock::matchers::header(
+        "authorization",
+        "Bearer test-only",
+    ))
+    .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(profile()))
+    .expect(1)
+    .mount(&proxy)
+    .await;
+    let id = environment
+        .account(Some(
+            gateway_core::account::OutboundProxy::parse(&format!(
+                "http://user:pass@{}",
+                proxy.address()
+            ))
+            .unwrap(),
+        ))
+        .await;
+    let mut config = configuration();
+    config["profile_url"] = json!("http://127.0.0.1:9/profile");
+    let (runtime, core) = environment.provider(config, grants()).await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    assert_eq!(
+        provider
+            .profile_statistics(&id)
+            .await
+            .unwrap()
+            .display_name
+            .as_deref(),
+        Some("插件用户")
+    );
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn avatar_rejects_malformed_headers_before_exposing_a_body() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let id = environment.account(None).await;
+    let mut config = configuration();
+    config["avatar_metadata"] =
+        json!({"content_type":"image/png\r\nx-private: secret", "content_length":524288});
+    let (runtime, core) = environment
+        .provider(config, vec![account_grant("accounts")])
+        .await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    assert_eq!(
+        provider.profile_avatar(&id).await.unwrap_err().kind(),
+        ProviderAdminErrorKind::BadGateway
+    );
+    assert!(provider.profile_statistics(&id).await.is_ok());
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn profile_subscription_and_avatar_use_managed_http_without_mutating_account_or_quota() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let server = wiremock::MockServer::start().await;
+    for (path, body) in [("/profile", profile()), ("/subscription", subscription())] {
+        wiremock::Mock::given(wiremock::matchers::path(path))
+            .and(wiremock::matchers::header(
+                "authorization",
+                "Bearer test-only",
+            ))
+            .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(body))
+            .expect(1)
+            .mount(&server)
+            .await;
+    }
+    let avatar_bytes = vec![42; 524288];
+    wiremock::Mock::given(wiremock::matchers::path("/avatar"))
+        .and(wiremock::matchers::header(
+            "authorization",
+            "Bearer test-only",
+        ))
+        .respond_with(wiremock::ResponseTemplate::new(200).set_body_bytes(avatar_bytes.clone()))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let id = environment.account(None).await;
+    let ports = environment.store.provider_ports();
+    let before = ports.accounts().get_account(&id).await.unwrap().unwrap();
+    let mut config = configuration();
+    for operation in ["profile", "subscription", "avatar"] {
+        config[format!("{operation}_url")] = json!(format!("{}/{operation}", server.uri()));
+    }
+    // Accounts 域授权后，三个只读操作都应完成且不得改写账号事实。
+    let (runtime, core) = environment.provider(config, grants()).await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let (profile, subscription) =
+        tokio::join!(provider.profile_statistics(&id), provider.subscription(&id));
+    let profile = profile.unwrap();
+    assert_eq!(profile.display_name.as_deref(), Some("插件用户"));
+    assert_eq!(profile.summary.total_text_tokens, Some(91234));
+    assert_eq!(profile.daily_usage.unwrap()[0].tokens, 1234);
+    assert_eq!(profile.activity_insights.fast_mode_percent, Some(25.0));
+    assert_eq!(
+        profile.activity_insights.invocations.unwrap()[0].usage_count,
+        Some(8)
+    );
+    assert_eq!(
+        subscription.unwrap().unwrap().expires_at.timestamp_millis(),
+        1_790_000_000_000
+    );
+    let avatar = provider.profile_avatar(&id).await.unwrap();
+    assert_eq!(avatar.content_length, Some(avatar_bytes.len() as u64));
+    let chunks: Vec<_> = avatar.body.try_collect().await.unwrap();
+    assert_eq!(chunks.concat(), avatar_bytes);
+    let after = ports.accounts().get_account(&id).await.unwrap().unwrap();
+    assert_eq!(after.revision(), before.revision());
+    assert_eq!(after.quota(), before.quota());
+    assert_eq!(after.name(), before.name());
+    assert_eq!(after.upstream_account_id(), before.upstream_account_id());
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    drop(ports);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn profile_requires_declared_operation_and_network_domain_before_rpc() {
+    for restriction in ["undeclared", "network"] {
+        let Some(environment) = Environment::create().await else {
+            eprintln!("SKIP: plugin integration environment absent");
+            return;
+        };
+        let server = wiremock::MockServer::start().await;
+        wiremock::Mock::given(wiremock::matchers::any())
+            .respond_with(wiremock::ResponseTemplate::new(200))
+            .expect(0)
+            .mount(&server)
+            .await;
+        let id = environment.account(None).await;
+        let mut config = configuration();
+        config["profile_url"] = json!(server.uri());
+        let mut grants = grants();
+        match restriction {
+            "undeclared" => config["account_operations"] = json!(["subscription"]),
+            "network" => grants.retain(|grant| grant.permission != "network"),
+            _ => unreachable!(),
+        }
+        let (runtime, core) = environment.provider(config, grants).await;
+        let provider = runtime
+            .admin_registry(core.snapshots())
+            .require(&ProviderKind::new("example").unwrap())
+            .unwrap();
+        let error = provider.profile_statistics(&id).await.unwrap_err();
+        assert_eq!(
+            error.kind(),
+            if restriction == "undeclared" {
+                ProviderAdminErrorKind::Unsupported
+            } else {
+                ProviderAdminErrorKind::Invalid
+            }
+        );
+        assert!(!format!("{error:?}").contains("test-only"));
+        drop(provider);
+        drop(core);
+        drop(runtime);
+        environment.close().await;
+    }
+}
+
+#[tokio::test]
+async fn malformed_profile_and_subscription_results_do_not_publish_untrusted_facts() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let server = wiremock::MockServer::start().await;
+    let id = environment.account(None).await;
+    let mut config = configuration();
+    config["profile_url"] = json!(server.uri());
+    config["subscription_url"] = json!(server.uri());
+    let (runtime, core) = environment.provider(config, grants()).await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let mut bad_profiles = Vec::new();
+    for (field, value) in [
+        ("display_name", json!("x".repeat(1025))),
+        ("username", json!("injected\nline")),
+        ("image_url", json!("https://token@example.test/a")),
+    ] {
+        let mut value_profile = profile();
+        value_profile[field] = value;
+        bad_profiles.push(value_profile);
+    }
+    let mut bad = profile();
+    bad["activity_insights"]["fast_mode_percent"] = json!(100.1);
+    bad_profiles.push(bad);
+    for usage in [
+        json!([{"date":"2026-02-30", "tokens":1}]),
+        json!([{"date":"2026-09-19", "tokens":1}, {"date":"2026-09-19", "tokens":2}]),
+        json!(vec![json!({"date":"2026-09-19", "tokens":1}); 4097]),
+    ] {
+        let mut bad = profile();
+        bad["daily_usage"] = usage;
+        bad_profiles.push(bad);
+    }
+    for value in bad_profiles {
+        server.reset().await;
+        wiremock::Mock::given(wiremock::matchers::any())
+            .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(value))
+            .expect(1)
+            .mount(&server)
+            .await;
+        assert_eq!(
+            provider.profile_statistics(&id).await.unwrap_err().kind(),
+            ProviderAdminErrorKind::BadGateway
+        );
+    }
+    for (field, value) in [
+        ("expires_at_ms", json!(i64::MAX)),
+        ("starts_at_ms", json!(1_800_000_000_000_i64)),
+        ("billing_currency", json!("USD\r\nprivate")),
+    ] {
+        let mut bad = subscription();
+        bad[field] = value;
+        server.reset().await;
+        wiremock::Mock::given(wiremock::matchers::any())
+            .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(bad))
+            .expect(1)
+            .mount(&server)
+            .await;
+        assert_eq!(
+            provider.subscription(&id).await.unwrap_err().kind(),
+            ProviderAdminErrorKind::BadGateway
+        );
+    }
+    server.reset().await;
+    wiremock::Mock::given(wiremock::matchers::any())
+        .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(Value::Null))
+        .expect(1)
+        .mount(&server)
+        .await;
+    assert!(provider.subscription(&id).await.unwrap().is_none());
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn credential_rotation_discards_late_profile_subscription_and_avatar_results() {
+    for operation in ["profile", "subscription", "avatar"] {
+        let Some(environment) = Environment::create().await else {
+            eprintln!("SKIP: plugin integration environment absent");
+            return;
+        };
+        let body = if operation == "subscription" {
+            subscription()
+        } else {
+            profile()
+        };
+        let mut server = crate::support::http::GatedResponse::start(body).await;
+        let id = environment.account(None).await;
+        let mut config = configuration();
+        config[format!("{operation}_url")] = json!(server.uri());
+        let (runtime, core) = environment.provider(config, grants()).await;
+        let kind = ProviderKind::new("example").unwrap();
+        let registry = runtime.admin_registry(core.snapshots());
+        let provider = registry.require(&kind).unwrap();
+        let pending_id = id.clone();
+        let pending = tokio::spawn(async move {
+            match operation {
+                "profile" => provider.profile_statistics(&pending_id).await.map(|_| ()),
+                "subscription" => provider.subscription(&pending_id).await.map(|_| ()),
+                "avatar" => provider.profile_avatar(&pending_id).await.map(|_| ()),
+                _ => unreachable!(),
+            }
+        });
+        server.received().await;
+        let admin = environment.store.admin_ports();
+        let service = CredentialsService::new(
+            registry,
+            admin.accounts(),
+            admin.proxies(),
+            core.snapshot_control(),
+        );
+        service
+            .for_provider(&kind)
+            .unwrap()
+            .rotate(RotateCredential {
+                mutation: CredentialMutation {
+                    account_id: id,
+                    context: mutation(),
+                },
+                provider_material: ProviderDocument::new(OpaqueProviderData::new(
+                    json!({"key":"replacement-test-key"})
+                        .as_object()
+                        .unwrap()
+                        .clone(),
+                )),
+                settings: None,
+            })
+            .await
+            .unwrap();
+        server.respond().await;
+        assert_eq!(
+            pending.await.unwrap().unwrap_err().kind(),
+            ProviderAdminErrorKind::Conflict
+        );
+        drop(service);
+        drop(admin);
+        drop(core);
+        drop(runtime);
+        environment.close().await;
+    }
+}
+
+#[tokio::test]
+async fn avatar_preserves_stream_errors_and_checks_declared_length() {
+    for metadata in [
+        json!({"content_type":"image/png", "content_length":524289}),
+        json!({"content_type":"image/png", "content_length":1}),
+        Value::Null,
+    ] {
+        let Some(environment) = Environment::create().await else {
+            eprintln!("SKIP: plugin integration environment absent");
+            return;
+        };
+        let id = environment.account(None).await;
+        let mut config = configuration();
+        if metadata.is_null() {
+            config["avatar_end_error"] = json!(true);
+        } else {
+            config["avatar_metadata"] = metadata;
+        }
+        let (runtime, core) = environment
+            .provider(config, vec![account_grant("accounts")])
+            .await;
+        let provider = runtime
+            .admin_registry(core.snapshots())
+            .require(&ProviderKind::new("example").unwrap())
+            .unwrap();
+        let avatar = provider.profile_avatar(&id).await.unwrap();
+        assert!(avatar.body.try_collect::<Vec<_>>().await.is_err());
+        // 头像失败是该次调用的终态，不能破坏同进程后续资料查询。
+        assert!(provider.profile_statistics(&id).await.is_ok());
+        drop(provider);
+        drop(core);
+        drop(runtime);
+        environment.close().await;
+    }
+}
+
+#[tokio::test]
+async fn dropping_a_backpressured_avatar_cancels_only_that_call() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let id = environment.account(None).await;
+    let (runtime, core) = environment
+        .provider(configuration(), vec![account_grant("accounts")])
+        .await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    // 总量超过 RPC 信用窗口；未消费的流必须能释放槽位且不终止整个进程。
+    for _ in 0..140 {
+        drop(provider.profile_avatar(&id).await.unwrap());
+    }
+    assert_eq!(
+        provider
+            .profile_statistics(&id)
+            .await
+            .unwrap()
+            .username
+            .as_deref(),
+        Some("plugin-user")
+    );
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn malformed_account_operation_registration_keeps_the_published_provider() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let id = environment.account(None).await;
+    let (runtime, core) = environment
+        .provider(configuration(), vec![account_grant("accounts")])
+        .await;
+    let store = environment.store.admin_ports().plugins();
+    let snapshot = store.load_instances().await.unwrap();
+    for operations in [json!([]), json!(["profile", "profile"]), json!(["unknown"])] {
+        let mut candidate = snapshot.clone();
+        candidate.instances[0].configuration["account_operations"] = operations;
+        assert!(
+            PluginPreparation::prepare(runtime.as_ref(), candidate.config_revision, candidate)
+                .await
+                .is_err()
+        );
+    }
+    // 非中间件阶段由能力固定；无效安装合同在进入候选集合前被拒绝。
+    let contributes = [
+        Capability::Executor,
+        Capability::Authentication,
+        Capability::AccountManagement,
+    ]
+    .into_iter()
+    .map(|capability| {
+        crate::support::contribution(
+            capability,
+            if capability == Capability::AccountManagement {
+                vec![Stage::Execution]
+            } else {
+                capability.fixed_stages().to_vec()
+            },
+            if capability == Capability::Executor {
+                vec!["openai".into()]
+            } else {
+                vec![]
+            },
+            if capability == Capability::Executor {
+                vec!["canonical".into()]
+            } else {
+                vec![]
+            },
+        )
+    })
+    .collect::<Contributions>();
+    let archive = crate::support::package_with_contributions(
+        crate::support::worker(),
+        vec![Permission::Accounts],
+        contributes,
+    );
+    let inspector = gateway_plugin_runtime::PackageInspector::new(
+        gateway_plugin_runtime::PackageLimits::default(),
+        "1.0.0".parse().unwrap(),
+    );
+    assert_eq!(
+        gateway_plugin_runtime::ValidatedPackage::read(
+            archive.clone(),
+            None,
+            gateway_plugin_runtime::PackageLimits::default(),
+        )
+        .err(),
+        Some(gateway_plugin_runtime::PackageError::Manifest(
+            gateway_plugin_sdk::ManifestError::Invalid,
+        )),
+    );
+    assert!(inspector.inspect(archive, None).await.is_err());
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    assert!(provider.profile_statistics(&id).await.is_ok());
+    drop(provider);
+    drop(store);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/quota.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/quota.rs
new file mode 100644
index 000000000..9d1cc188a
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/quota.rs
@@ -0,0 +1,302 @@
+use std::{
+    num::NonZeroU32,
+    time::{Duration, SystemTime},
+};
+
+use gateway_admin::{
+    CredentialsService,
+    model::provider_credentials::{
+        CredentialMutation, ProviderDocument, ProviderQuotaRequest, RotateCredential,
+    },
+    ports::provider::ProviderAdminErrorKind,
+};
+use gateway_core::{
+    account::{AccountSelectionPolicy, OpaqueProviderData, QuotaAccessState, RotationStrategy},
+    engine::{
+        AccountAttemptContext, AttemptContext, ModelRequestId, RequestAttemptContext,
+        provider::ProviderRequest,
+    },
+    error::ProviderErrorKind,
+    lifecycle::CancellationToken,
+    policy::ClientApiKeyId,
+    routing::{ProviderKind, PublicModelId, RoutingContext, UpstreamModelId},
+};
+use serde_json::json;
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+#[tokio::test]
+async fn quota_persists_and_survives_restart_without_inferring_access_from_percentage() {
+    for exhausted in [false, true] {
+        let Some(environment) = Environment::create().await else {
+            eprintln!("SKIP: plugin integration environment absent");
+            return;
+        };
+        let server = wiremock::MockServer::start().await;
+        wiremock::Mock::given(wiremock::matchers::header(
+            "authorization",
+            "Bearer test-only",
+        ))
+        .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(quota(exhausted)))
+        .expect(1)
+        .mount(&server)
+        .await;
+        let id = environment.account(None).await;
+        let (runtime, core) = environment
+            .provider(json!({"quota_url":server.uri()}), grants())
+            .await;
+        let kind = ProviderKind::new("example").unwrap();
+        let provider = runtime
+            .admin_registry(core.snapshots())
+            .require(&kind)
+            .unwrap();
+        let result = provider
+            .quota(ProviderQuotaRequest {
+                account_id: id.clone(),
+                refresh: true,
+                rolling_usage: None,
+            })
+            .await
+            .unwrap();
+        assert_eq!(result.plan_type.as_deref(), Some("plugin-pro"));
+        assert_eq!(result.windows[0].used_percent, Some(100.0));
+        assert_eq!(result.windows[0].window_seconds, Some(604800));
+        let loaded = environment
+            .store
+            .provider_ports()
+            .accounts()
+            .get_account(&id)
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(
+            loaded.quota().access(),
+            if exhausted {
+                QuotaAccessState::Exhausted
+            } else {
+                QuotaAccessState::Allowed
+            }
+        );
+        let cached = provider
+            .quota(ProviderQuotaRequest {
+                account_id: id.clone(),
+                refresh: false,
+                rolling_usage: None,
+            })
+            .await
+            .unwrap();
+        assert_eq!(result, cached);
+        // 销毁进程和 Core 后仅从持久化实例与额度文档恢复，不再次查询上游。
+        drop(provider);
+        drop(core);
+        drop(runtime);
+        let (runtime, core) = environment.runtime().await;
+        let provider = runtime
+            .admin_registry(core.snapshots())
+            .require(&kind)
+            .unwrap();
+        assert_eq!(
+            provider
+                .quota(ProviderQuotaRequest {
+                    account_id: id,
+                    refresh: false,
+                    rolling_usage: None
+                })
+                .await
+                .unwrap(),
+            result
+        );
+        if exhausted {
+            let snapshot = core.snapshots().acquire().unwrap();
+            let operation = provider
+                .connection_test_operation(&UpstreamModelId::new("plugin-model").unwrap(), "test")
+                .await
+                .unwrap();
+            let plan = snapshot
+                .plan(
+                    &PublicModelId::new("plugin-model").unwrap(),
+                    &operation,
+                    snapshot.all_account_scope(),
+                    &RoutingContext::default(),
+                )
+                .unwrap();
+            let registry = runtime
+                .provider_registry()
+                .for_extensions(snapshot.extensions())
+                .unwrap();
+            let execution = registry
+                .get(&kind)
+                .unwrap()
+                .clone()
+                .execute(
+                    ProviderRequest::new(operation, plan.candidates()[0].clone()),
+                    AttemptContext::new(
+                        RequestAttemptContext::new(
+                            ModelRequestId::new("req_quota_test").unwrap(),
+                            ClientApiKeyId::new("key_quota_test").unwrap(),
+                        ),
+                        NonZeroU32::new(1).unwrap(),
+                        SystemTime::now() + Duration::from_secs(5),
+                        AccountSelectionPolicy::new(
+                            RotationStrategy::RoundRobin,
+                            NonZeroU32::new(1).unwrap(),
+                            Duration::ZERO,
+                        ),
+                        AccountAttemptContext::default()
+                            .with_account_scope(snapshot.all_account_scope()),
+                        None,
+                        CancellationToken::new(),
+                    ),
+                )
+                .await;
+            match execution {
+                Err(error) => assert_eq!(error.kind(), ProviderErrorKind::NoEligibleAccount),
+                Ok(_) => panic!("exhausted account was selected"),
+            }
+        }
+        drop(provider);
+        drop(core);
+        drop(runtime);
+        environment.close().await;
+    }
+}
+
+#[tokio::test]
+async fn late_quota_response_cannot_overwrite_a_rotated_credentials_account() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let mut server = crate::support::http::GatedResponse::start(quota(true)).await;
+    let id = environment.account(None).await;
+    let (runtime, core) = environment
+        .provider(json!({"quota_url":server.uri()}), grants())
+        .await;
+    let registry = runtime.admin_registry(core.snapshots());
+    let kind = ProviderKind::new("example").unwrap();
+    let provider = registry.require(&kind).unwrap();
+    let pending_id = id.clone();
+    let pending = tokio::spawn(async move {
+        provider
+            .quota(ProviderQuotaRequest {
+                account_id: pending_id,
+                refresh: true,
+                rolling_usage: None,
+            })
+            .await
+    });
+    server.received().await;
+    let admin = environment.store.admin_ports();
+    let service = CredentialsService::new(
+        registry.clone(),
+        admin.accounts(),
+        admin.proxies(),
+        core.snapshot_control(),
+    );
+    service
+        .for_provider(&kind)
+        .unwrap()
+        .rotate(RotateCredential {
+            mutation: CredentialMutation {
+                account_id: id.clone(),
+                context: mutation(),
+            },
+            provider_material: ProviderDocument::new(OpaqueProviderData::new(
+                json!({"key":"new-test-key"}).as_object().unwrap().clone(),
+            )),
+            settings: None,
+        })
+        .await
+        .unwrap();
+    server.respond().await;
+    assert_eq!(
+        pending.await.unwrap().unwrap_err().kind(),
+        ProviderAdminErrorKind::Conflict
+    );
+    let account = environment
+        .store
+        .provider_ports()
+        .accounts()
+        .get_account(&id)
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(account.revision().get(), 2);
+    assert_eq!(account.quota().access(), QuotaAccessState::Unknown);
+    assert!(
+        environment
+            .store
+            .provider_ports()
+            .accounts()
+            .get_quotas(&[id])
+            .await
+            .unwrap()
+            .is_empty()
+    );
+    drop(service);
+    drop(registry);
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+fn grants() -> Vec<gateway_admin::model::plugins::instances::PluginPermissionGrant> {
+    vec![account_grant("accounts"), account_grant("network")]
+}
+
+fn quota(exhausted: bool) -> serde_json::Value {
+    json!({
+        "plan_type":"plugin-pro", "access":if exhausted { json!({"kind":"exhausted","evidence":"usage_limit_reached"}) } else { json!({"kind":"allowed"}) },
+        "windows":[{"key":"weekly", "group":"shortTerm", "label":"weekly", "role":"primary", "account_wide":true, "window_seconds":604800, "used_percent":100.0, "limit_reached":true}],
+    })
+}
+
+#[tokio::test]
+async fn quota_requires_network_domain_before_sending() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let server = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::any())
+        .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(quota(false)))
+        .expect(0)
+        .mount(&server)
+        .await;
+    let id = environment.account(None).await;
+    let (runtime, core) = environment
+        .provider(
+            json!({"quota_url":server.uri()}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    assert!(
+        provider
+            .quota(ProviderQuotaRequest {
+                account_id: id.clone(),
+                refresh: true,
+                rolling_usage: None
+            })
+            .await
+            .is_err()
+    );
+    assert!(
+        environment
+            .store
+            .provider_ports()
+            .accounts()
+            .get_quotas(&[id])
+            .await
+            .unwrap()
+            .is_empty()
+    );
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/request_profile.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/request_profile.rs
new file mode 100644
index 000000000..2a0bcab5c
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/request_profile.rs
@@ -0,0 +1,280 @@
+use std::{
+    num::NonZeroU32,
+    sync::Arc,
+    time::{Duration, SystemTime},
+};
+
+use gateway_admin::{
+    model::{AdminErrorKind, Revision},
+    ports::plugins::PluginPreparation,
+};
+use gateway_core::{
+    account::{AccountSelectionPolicy, OpaqueProviderData, RotationStrategy},
+    engine::{
+        AccountAttemptContext, AttemptContext, ModelRequestId, RequestAttemptContext,
+        provider::ProviderRequest,
+    },
+    lifecycle::CancellationToken,
+    policy::ClientApiKeyId,
+    routing::{ProviderKind, PublicModelId, RoutingContext, UpstreamModelId},
+};
+use serde_json::{Map, Value, json};
+
+use crate::support::environment::{Environment, account_grant};
+
+fn object(value: Value) -> Map<String, Value> {
+    value.as_object().expect("object fixture").clone()
+}
+
+fn request_profiles() -> Value {
+    let presentation = |channel: &str, version: &str| {
+        json!({
+            "product":"Example CLI",
+            "version":version,
+            "build":format!("build-{version}"),
+            "target":{"os_type":"linux","os_version":"6.8","arch":"x86_64","terminal":"headless"},
+            "user_agent":format!("Example CLI/{version}"),
+            "attributes":[{"label":"通道","value":channel}],
+            "verified_at_ms":1_780_000_000_000_i64,
+            "release":{"status":"current","checked_at_ms":1_780_000_000_100_i64,"latest_version":version},
+        })
+    };
+    json!({
+        "default_configuration":{"channel":"stable"},
+        "options":[
+            {
+                "id":"stable","label":"稳定版","description":"默认核验版本",
+                "configuration":{"channel":"stable"},
+                "resolved":{"upstreamIdentity":"stable-wire"},
+                "presentation":presentation("stable", "1.2.3"),
+            },
+            {
+                "id":"beta","label":"测试版",
+                "configuration":{"channel":"beta"},
+                "resolved":{"upstreamIdentity":"beta-wire"},
+                "presentation":presentation("beta", "1.3.0-beta.1"),
+            }
+        ]
+    })
+}
+
+#[tokio::test]
+async fn future_candidate_reads_current_profile_facts_and_cached_candidates_reject_stale_sources() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(
+            json!({"request_profiles": request_profiles()}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let mut candidate = environment
+        .store
+        .admin_ports()
+        .plugins()
+        .load_instances()
+        .await
+        .unwrap();
+    let source_revision = candidate.config_revision;
+    candidate.config_revision = Revision::new(source_revision.get() + 1).unwrap();
+    candidate.instances[0].revision = candidate.config_revision;
+    let prepared = runtime
+        .prepare(source_revision, candidate.clone())
+        .await
+        .unwrap();
+    let error = runtime
+        .prepare(candidate.config_revision, candidate.clone())
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), AdminErrorKind::Conflict);
+    assert_eq!(
+        environment
+            .store
+            .admin_ports()
+            .plugins()
+            .load_instances()
+            .await
+            .unwrap()
+            .config_revision,
+        source_revision,
+        "候选准备不能提前提交配置"
+    );
+    environment
+        .set_request_profile("example", object(json!({"channel":"beta"})))
+        .await;
+    let error = runtime
+        .prepare(source_revision, candidate)
+        .await
+        .unwrap_err();
+    assert_eq!(
+        error.kind(),
+        AdminErrorKind::Conflict,
+        "缓存命中不能绕过源事实版本校验"
+    );
+    drop(prepared);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn request_profiles_validate_cached_candidates_and_reach_the_real_worker() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: CPR_PLUGIN_TEST_DATABASE_URL / CPR_PLUGIN_TEST_REDIS_URL 未设置");
+        return;
+    };
+    let marker = environment.directory.path().join("request-profile.json");
+    let _account_id = environment.account(None).await;
+    let (runtime, core) = environment
+        .provider(
+            json!({
+                "request_profiles":request_profiles(),
+                "request_profile_marker":marker,
+            }),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let provider_kind = ProviderKind::new("example").unwrap();
+    let admin_registry = runtime.admin_registry(core.snapshots());
+    assert_eq!(
+        admin_registry.client_profile_providers().unwrap(),
+        vec![provider_kind.clone()]
+    );
+    let admin = admin_registry.require(&provider_kind).unwrap();
+    let options = admin.client_profile_options().unwrap();
+    assert_eq!(
+        options.expose_to_provider()["presets"]
+            .as_array()
+            .unwrap()
+            .len(),
+        2
+    );
+    assert!(
+        !serde_json::to_string(options.expose_to_provider())
+            .unwrap()
+            .contains("stable-wire"),
+        "管理选项不能暴露 Provider resolved 文档"
+    );
+    let stable = admin.default_client_profile().unwrap();
+    assert_eq!(stable.expose_to_provider()["channel"], "stable");
+    let beta = OpaqueProviderData::new(object(json!({"channel":"beta"})));
+    let preview = admin.preview_client_profile(&beta).unwrap();
+    assert_eq!(
+        preview.expose_to_provider()["userAgent"],
+        "Example CLI/1.3.0-beta.1"
+    );
+    assert_eq!(
+        admin.configured_wire_profile(&beta).unwrap().user_agent,
+        "Example CLI/1.3.0-beta.1"
+    );
+
+    environment
+        .set_request_profile("example", object(json!({"channel":"removed"})))
+        .await;
+    let invalid_candidate = environment
+        .store
+        .admin_ports()
+        .plugins()
+        .load_instances()
+        .await
+        .unwrap();
+    let error = runtime
+        .prepare(invalid_candidate.config_revision, invalid_candidate)
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+
+    environment
+        .set_request_profile("example", beta.expose_to_provider().clone())
+        .await;
+    let valid_candidate = environment
+        .store
+        .admin_ports()
+        .plugins()
+        .load_instances()
+        .await
+        .unwrap();
+    let prepared = runtime
+        .prepare(valid_candidate.config_revision, valid_candidate)
+        .await
+        .unwrap();
+    assert_eq!(
+        prepared.id(),
+        core.snapshots()
+            .acquire()
+            .unwrap()
+            .extensions()
+            .unwrap()
+            .id(),
+        "仅全局选择变化应复用同一插件代次"
+    );
+
+    let snapshot = core.snapshots().acquire().unwrap();
+    let providers = runtime
+        .provider_registry()
+        .for_extensions(snapshot.extensions())
+        .unwrap();
+    let provider = providers.get(&provider_kind).unwrap();
+    let default = provider.default_request_profile().unwrap().unwrap();
+    assert_eq!(
+        default.expose_to_provider()["upstreamIdentity"],
+        "stable-wire"
+    );
+    let resolved = provider.resolve_request_profile(&beta).unwrap();
+    assert_eq!(
+        resolved.expose_to_provider()["upstreamIdentity"],
+        "beta-wire"
+    );
+    let model = UpstreamModelId::new("plugin-model").unwrap();
+    let operation = admin
+        .connection_test_operation(&model, "profile")
+        .await
+        .unwrap();
+    let plan = snapshot
+        .plan(
+            &PublicModelId::new("plugin-model").unwrap(),
+            &operation,
+            snapshot.all_account_scope(),
+            &RoutingContext::default(),
+        )
+        .unwrap();
+    let request = RequestAttemptContext::new(
+        ModelRequestId::new("req_plugin_request_profile").unwrap(),
+        ClientApiKeyId::new("key_plugin_request_profile").unwrap(),
+    )
+    .with_request_profile(Some(resolved.clone()));
+    let attempt = AttemptContext::new(
+        request,
+        NonZeroU32::MIN,
+        SystemTime::now() + Duration::from_secs(30),
+        AccountSelectionPolicy::new(
+            RotationStrategy::RoundRobin,
+            NonZeroU32::MIN,
+            Duration::ZERO,
+        ),
+        AccountAttemptContext::default().with_account_scope(snapshot.all_account_scope()),
+        None,
+        CancellationToken::new(),
+    );
+    let response = Arc::clone(provider)
+        .execute(
+            ProviderRequest::new(operation, plan.candidates()[0].clone()),
+            attempt,
+        )
+        .await
+        .unwrap();
+    let sent: Value = serde_json::from_slice(&std::fs::read(&marker).unwrap()).unwrap();
+    assert_eq!(sent, Value::Object(resolved.into_inner()));
+
+    drop(response);
+    drop(prepared);
+    drop(providers);
+    drop(snapshot);
+    drop(admin);
+    drop(admin_registry);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/reset_credits.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/reset_credits.rs
new file mode 100644
index 000000000..407469135
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/reset_credits.rs
@@ -0,0 +1,460 @@
+use std::{
+    collections::BTreeSet,
+    sync::{Arc, Mutex},
+    time::Duration,
+};
+
+use gateway_admin::{
+    CredentialsService,
+    model::{
+        plugins::instances::PluginPermissionGrant,
+        provider_credentials::{
+            ConsumeProviderResetCredit, CredentialMutation, ProviderDocument, RotateCredential,
+        },
+    },
+    ports::provider::ProviderAdminErrorKind,
+};
+use gateway_core::{
+    account::{OpaqueProviderData, ProviderAccountId},
+    routing::ProviderKind,
+};
+use serde_json::{Value, json};
+use wiremock::{
+    Mock, MockServer, ResponseTemplate,
+    matchers::{any, header, method, path},
+};
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+fn credit() -> Value {
+    json!({"id":"credit-test", "status":"available", "title":"测试重置卡", "expires_at_ms":1_900_000_000_000_i64, "reset_type":"primary"})
+}
+
+fn configuration() -> Value {
+    json!({"account_operations":["reset_credits", "consume_reset_credit"],
+        "reset_credits":{"outcome":"completed", "result":{"available_count":1, "credits":[credit()]}},
+        "consume_reset_credit":{"outcome":"completed", "result":{"code":"reset", "credit":credit()}}})
+}
+
+fn grants(with_network: bool) -> Vec<PluginPermissionGrant> {
+    let mut grants = vec![account_grant("accounts")];
+    if with_network {
+        grants.push(account_grant("network"));
+    }
+    grants
+}
+
+fn command(id: &ProviderAccountId) -> ConsumeProviderResetCredit {
+    ConsumeProviderResetCredit {
+        account_id: id.clone(),
+        credit_id: Some("credit-test".into()),
+        redeem_request_id: uuid::Uuid::new_v4(),
+    }
+}
+
+#[tokio::test]
+async fn reset_queries_and_consumption_preserve_target_and_idempotency_key_without_local_inventory()
+{
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let server = MockServer::start().await;
+    let consumed = Arc::new(Mutex::new(BTreeSet::new()));
+    let consumed_upstream = Arc::clone(&consumed);
+    Mock::given(method("GET"))
+        .and(path("/credits"))
+        .and(header("authorization", "Bearer test-only"))
+        .respond_with(
+            ResponseTemplate::new(200)
+                .set_body_json(json!({"available_count":1, "credits":[credit()]})),
+        )
+        .expect(2)
+        .mount(&server)
+        .await;
+    Mock::given(method("POST"))
+        .and(path("/consume"))
+        .and(header("authorization", "Bearer test-only"))
+        .respond_with(move |request: &wiremock::Request| {
+            let body: Value = serde_json::from_slice(&request.body).unwrap();
+            assert_eq!(body["credit_id"], "credit-test");
+            let key = body["redeem_request_id"].as_str().unwrap();
+            let first = consumed_upstream.lock().unwrap().insert(key.to_owned());
+            ResponseTemplate::new(200).set_body_json(
+                json!({"code":if first {"reset"} else {"already_redeemed"}, "credit":credit()}),
+            )
+        })
+        .expect(2)
+        .mount(&server)
+        .await;
+    let id = environment.account(None).await;
+    let mut config = configuration();
+    config["reset_credits_url"] = json!(format!("{}/credits", server.uri()));
+    config["consume_reset_credit_url"] = json!(format!("{}/consume", server.uri()));
+    let (runtime, core) = environment.provider(config, grants(true)).await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let capabilities = provider.account_capabilities(&id, "api_key");
+    assert!(capabilities.reset_credits && capabilities.consume_reset_credit);
+    assert!(!capabilities.quota_refresh);
+    for _ in 0..2 {
+        let list = provider.reset_credits(&id).await.unwrap();
+        assert_eq!(list.available_count, 1);
+        assert_eq!(list.credits[0].id, "credit-test");
+    }
+    let command = command(&id);
+    assert_eq!(
+        provider
+            .consume_reset_credit(command.clone())
+            .await
+            .unwrap()
+            .code,
+        "reset"
+    );
+    assert_eq!(
+        provider
+            .consume_reset_credit(command.clone())
+            .await
+            .unwrap()
+            .code,
+        "already_redeemed"
+    );
+    assert_eq!(
+        *consumed.lock().unwrap(),
+        BTreeSet::from([command.redeem_request_id.to_string()])
+    );
+    let stored = environment
+        .store
+        .provider_ports()
+        .accounts()
+        .load_current_credential(&id)
+        .await
+        .unwrap();
+    assert_eq!(stored.account.revision().get(), 1);
+    assert!(
+        server
+            .received_requests()
+            .await
+            .unwrap()
+            .iter()
+            .all(|request| !request.headers.contains_key("cookie"))
+    );
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn accounts_domain_allows_reset_consumption_and_declared_operations_stay_authoritative() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let id = environment.account(None).await;
+    let (runtime, core) = environment.provider(configuration(), grants(false)).await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let capabilities = provider.account_capabilities(&id, "api_key");
+    assert!(capabilities.reset_credits);
+    assert!(capabilities.consume_reset_credit);
+    assert!(provider.reset_credits(&id).await.is_ok());
+    assert!(provider.consume_reset_credit(command(&id)).await.is_ok());
+    drop(provider);
+    let store = environment.store.admin_ports().plugins();
+    let mut snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.remove(0);
+    instance.configuration["account_operations"] = json!(["subscription"]);
+    store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    let revision = store.load_instances().await.unwrap().config_revision;
+    core.snapshot_control()
+        .publish_committed(gateway_core::routing::ConfigRevision::new(revision.get()).unwrap())
+        .await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    assert_eq!(
+        provider.reset_credits(&id).await.unwrap_err().kind(),
+        ProviderAdminErrorKind::Unsupported
+    );
+    assert_eq!(
+        provider
+            .consume_reset_credit(command(&id))
+            .await
+            .unwrap_err()
+            .kind(),
+        ProviderAdminErrorKind::Unsupported
+    );
+    drop(store);
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn confirmed_reset_rejection_and_expired_credential_are_not_uncertain_consumption() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let id = environment.account(None).await;
+    let server = MockServer::start().await;
+    let mut config = configuration();
+    config["reset_credits_url"] = json!(server.uri());
+    config["consume_reset_credit_url"] = json!(server.uri());
+    let (runtime, core) = environment.provider(config, grants(true)).await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    for (status, expected) in [
+        (401, ProviderAdminErrorKind::CredentialRefreshRequired),
+        (403, ProviderAdminErrorKind::BadGateway),
+        (503, ProviderAdminErrorKind::BadGateway),
+    ] {
+        server.reset().await;
+        Mock::given(any())
+            .respond_with(ResponseTemplate::new(status))
+            .expect(2)
+            .mount(&server)
+            .await;
+        assert_eq!(
+            provider.reset_credits(&id).await.unwrap_err().kind(),
+            expected
+        );
+        assert_eq!(
+            provider
+                .consume_reset_credit(command(&id))
+                .await
+                .unwrap_err()
+                .kind(),
+            expected
+        );
+    }
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn malformed_reset_results_never_become_a_confirmed_consumption() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let id = environment.account(None).await;
+    let server = MockServer::start().await;
+    let mut config = configuration();
+    config["reset_credits_url"] = json!(server.uri());
+    config["consume_reset_credit_url"] = json!(server.uri());
+    let (runtime, core) = environment.provider(config, grants(true)).await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&ProviderKind::new("example").unwrap())
+        .unwrap();
+    let mut bad_date = credit();
+    bad_date["expires_at_ms"] = json!(i64::MAX);
+    for credits in [
+        vec![credit(), credit()],
+        vec![bad_date],
+        vec![credit(); 4097],
+    ] {
+        server.reset().await;
+        Mock::given(any())
+            .respond_with(
+                ResponseTemplate::new(200)
+                    .set_body_json(json!({"available_count":1,"credits":credits})),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        assert_eq!(
+            provider.reset_credits(&id).await.unwrap_err().kind(),
+            ProviderAdminErrorKind::BadGateway
+        );
+    }
+    for result in [
+        json!({"code":"","credit":null}),
+        json!({"code":"reset","credit":{"id":"other"}}),
+        json!({"code":"reset","credit":null,"unexpected":true}),
+    ] {
+        server.reset().await;
+        Mock::given(any())
+            .respond_with(ResponseTemplate::new(200).set_body_json(result))
+            .expect(1)
+            .mount(&server)
+            .await;
+        assert_eq!(
+            provider
+                .consume_reset_credit(command(&id))
+                .await
+                .unwrap_err()
+                .kind(),
+            ProviderAdminErrorKind::Ambiguous
+        );
+    }
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn process_loss_and_forged_not_sent_after_reset_are_uncertain_and_never_retried() {
+    for mode in [
+        "crash",
+        "fault",
+        "crash_without_http",
+        "malformed_without_http",
+    ] {
+        let Some(environment) = Environment::create().await else {
+            eprintln!("SKIP: plugin integration environment absent");
+            return;
+        };
+        let id = environment.account(None).await;
+        let server = MockServer::start().await;
+        Mock::given(any())
+            .respond_with(
+                ResponseTemplate::new(200).set_body_json(json!({"code":"reset","credit":null})),
+            )
+            .expect(if mode.ends_with("without_http") { 0 } else { 1 })
+            .mount(&server)
+            .await;
+        let mut config = configuration();
+        if !mode.ends_with("without_http") {
+            config["consume_reset_credit_url"] = json!(server.uri());
+        }
+        match mode {
+            "crash" | "crash_without_http" => config["consume_reset_credit_crash"] = json!(true),
+            "fault" => {
+                config["consume_reset_credit_fault"] =
+                    json!({"code":"fault","message":"test-only","send_state":"not_sent"})
+            }
+            "malformed_without_http" => config["consume_reset_credit"] = json!({"unexpected":true}),
+            _ => unreachable!(),
+        }
+        let (runtime, core) = environment.provider(config, grants(true)).await;
+        let provider = runtime
+            .admin_registry(core.snapshots())
+            .require(&ProviderKind::new("example").unwrap())
+            .unwrap();
+        assert_eq!(
+            provider
+                .consume_reset_credit(command(&id))
+                .await
+                .unwrap_err()
+                .kind(),
+            ProviderAdminErrorKind::Ambiguous
+        );
+        assert_eq!(
+            server.received_requests().await.unwrap().len(),
+            usize::from(!mode.ends_with("without_http"))
+        );
+        drop(provider);
+        drop(core);
+        drop(runtime);
+        environment.close().await;
+    }
+}
+
+#[tokio::test]
+async fn reset_results_cannot_cross_credential_rotation_and_consumption_remains_uncertain() {
+    for consume in [false, true] {
+        let Some(environment) = Environment::create().await else {
+            eprintln!("SKIP: plugin integration environment absent");
+            return;
+        };
+        let id = environment.account(None).await;
+        let server = MockServer::start().await;
+        let result = if consume {
+            json!({"code":"reset","credit":null})
+        } else {
+            json!({"available_count":1,"credits":[credit()]})
+        };
+        Mock::given(any())
+            .respond_with(
+                ResponseTemplate::new(200)
+                    .set_body_json(result)
+                    .set_delay(Duration::from_secs(1)),
+            )
+            .expect(1)
+            .mount(&server)
+            .await;
+        let mut config = configuration();
+        config[if consume {
+            "consume_reset_credit_url"
+        } else {
+            "reset_credits_url"
+        }] = json!(server.uri());
+        let (runtime, core) = environment.provider(config, grants(true)).await;
+        let kind = ProviderKind::new("example").unwrap();
+        let registry = runtime.admin_registry(core.snapshots());
+        let provider = registry.require(&kind).unwrap();
+        let pending_id = id.clone();
+        let pending = tokio::spawn(async move {
+            if consume {
+                provider
+                    .consume_reset_credit(command(&pending_id))
+                    .await
+                    .map(|_| ())
+            } else {
+                provider.reset_credits(&pending_id).await.map(|_| ())
+            }
+        });
+        tokio::time::timeout(Duration::from_secs(3), async {
+            while server.received_requests().await.unwrap().is_empty() {
+                tokio::time::sleep(Duration::from_millis(10)).await;
+            }
+        })
+        .await
+        .unwrap();
+        let admin = environment.store.admin_ports();
+        let service = CredentialsService::new(
+            registry,
+            admin.accounts(),
+            admin.proxies(),
+            core.snapshot_control(),
+        );
+        service
+            .for_provider(&kind)
+            .unwrap()
+            .rotate(RotateCredential {
+                mutation: CredentialMutation {
+                    account_id: id,
+                    context: mutation(),
+                },
+                provider_material: ProviderDocument::new(OpaqueProviderData::new(
+                    json!({"key":"replacement-test-key"})
+                        .as_object()
+                        .unwrap()
+                        .clone(),
+                )),
+                settings: None,
+            })
+            .await
+            .unwrap();
+        assert_eq!(
+            pending.await.unwrap().unwrap_err().kind(),
+            if consume {
+                ProviderAdminErrorKind::Ambiguous
+            } else {
+                ProviderAdminErrorKind::Conflict
+            }
+        );
+        drop(service);
+        drop(admin);
+        drop(core);
+        drop(runtime);
+        environment.close().await;
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/provider/rotation.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/rotation.rs
new file mode 100644
index 000000000..2c0d4a4bc
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/adapter/provider/rotation.rs
@@ -0,0 +1,284 @@
+use gateway_admin::{
+    CredentialsService,
+    model::provider_credentials::{
+        CredentialMutation, CredentialRotationCommit, ImportCredentials, PrepareCredentialRefresh,
+        ProviderDocument, RotateCredential,
+    },
+    ports::provider::ProviderAdminErrorKind,
+};
+use gateway_core::{
+    account::{OpaqueProviderData, ProviderAccountUpdate},
+    routing::ProviderKind,
+};
+use serde_json::json;
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+#[tokio::test]
+async fn refresh_holds_real_redis_leases_through_commit_and_preserves_concurrent_profile_edits() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(json!({}), vec![account_grant("accounts")])
+        .await;
+    let registry = runtime.admin_registry(core.snapshots());
+    let admin = environment.store.admin_ports();
+    let ports = environment.store.provider_ports();
+    let service = CredentialsService::new(
+        registry.clone(),
+        admin.accounts(),
+        admin.proxies(),
+        core.snapshot_control(),
+    );
+    let kind = ProviderKind::new("example").unwrap();
+    let id = service
+        .for_provider(&kind)
+        .unwrap()
+        .import_document(import())
+        .await
+        .unwrap()
+        .credential_ids
+        .remove(0);
+    let provider = registry.require(&kind).unwrap();
+    let account = admin
+        .accounts()
+        .credential_details(&kind, &id)
+        .await
+        .unwrap()
+        .unwrap()
+        .credential;
+    let prepared = provider
+        .prepare_refresh(PrepareCredentialRefresh {
+            account: account.clone(),
+        })
+        .await
+        .unwrap();
+    let busy = provider
+        .prepare_refresh(PrepareCredentialRefresh {
+            account: account.clone(),
+        })
+        .await
+        .unwrap_err();
+    assert_eq!(busy.kind(), ProviderAdminErrorKind::Conflict);
+    ports
+        .accounts()
+        .update_account(ProviderAccountUpdate {
+            account_id: id.clone(),
+            name: "concurrent admin edit".into(),
+            email: None,
+            plan_type: None,
+        })
+        .await
+        .unwrap();
+    let (facts, guard) = prepared.into_parts();
+    let result = admin
+        .accounts()
+        .commit_credential_refresh(
+            CredentialRotationCommit {
+                prepared: facts,
+                settings: None,
+            },
+            &mutation(),
+        )
+        .await
+        .unwrap();
+    guard.finish();
+    core.snapshot_control()
+        .publish_committed(
+            gateway_core::routing::ConfigRevision::new(result.config_revision.get()).unwrap(),
+        )
+        .await;
+    let loaded = ports.accounts().load_current_credential(&id).await.unwrap();
+    assert_eq!(loaded.account.revision().get(), 2);
+    assert_eq!(loaded.account.name(), "concurrent admin edit");
+    assert_eq!(
+        loaded.credential.expose_to_provider()["key"],
+        "refreshed-test-key"
+    );
+    assert_eq!(
+        provider
+            .prepare_refresh(PrepareCredentialRefresh { account })
+            .await
+            .unwrap_err()
+            .kind(),
+        ProviderAdminErrorKind::Conflict
+    );
+    let rotated = service
+        .for_provider(&kind)
+        .unwrap()
+        .rotate(RotateCredential {
+            mutation: CredentialMutation {
+                account_id: id.clone(),
+                context: mutation(),
+            },
+            provider_material: document(json!({"key":"manually-rotated"})),
+            settings: None,
+        })
+        .await
+        .unwrap();
+    assert_eq!(rotated.credential_revision.unwrap().get(), 3);
+    let loaded = ports.accounts().load_current_credential(&id).await.unwrap();
+    assert_eq!(
+        loaded.credential.expose_to_provider()["key"],
+        "manually-rotated"
+    );
+    let account = admin
+        .accounts()
+        .credential_details(&kind, &id)
+        .await
+        .unwrap()
+        .unwrap()
+        .credential;
+    // 失败事务或取消会 drop 准备结果，不能留下账号互斥锁。
+    drop(
+        provider
+            .prepare_refresh(PrepareCredentialRefresh {
+                account: account.clone(),
+            })
+            .await
+            .unwrap(),
+    );
+    tokio::time::timeout(std::time::Duration::from_secs(3), async {
+        loop {
+            match provider
+                .prepare_refresh(PrepareCredentialRefresh {
+                    account: account.clone(),
+                })
+                .await
+            {
+                Ok(prepared) => {
+                    drop(prepared);
+                    break;
+                }
+                Err(error) if error.kind() == ProviderAdminErrorKind::Conflict => {
+                    tokio::time::sleep(std::time::Duration::from_millis(20)).await
+                }
+                Err(error) => panic!("refresh after guard release failed: {error:?}"),
+            }
+        }
+    })
+    .await
+    .unwrap();
+    drop(provider);
+    drop(service);
+    drop(registry);
+    drop(ports);
+    drop(admin);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn refresh_uses_managed_http_and_never_reports_sent_failures_as_safe_to_retry() {
+    for ambiguous in [false, true] {
+        let Some(environment) = Environment::create().await else {
+            eprintln!("SKIP: plugin integration environment absent");
+            return;
+        };
+        let server = wiremock::MockServer::start().await;
+        wiremock::Mock::given(wiremock::matchers::method("POST"))
+            .and(wiremock::matchers::header("authorization", "Bearer original-test-key"))
+            .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(json!({"name":"upstream profile", "authentication_kind":"oauth", "material":{"key":"upstream-rotated-key"}, "has_refresh_token":true})))
+            .expect(1).mount(&server).await;
+        let network = account_grant("network");
+        let (runtime, core) = environment
+            .provider(
+                json!({"management_url":server.uri(), "management_error_after_http":ambiguous}),
+                vec![account_grant("accounts"), network],
+            )
+            .await;
+        let registry = runtime.admin_registry(core.snapshots());
+        let admin = environment.store.admin_ports();
+        let service = CredentialsService::new(
+            registry.clone(),
+            admin.accounts(),
+            admin.proxies(),
+            core.snapshot_control(),
+        );
+        let kind = ProviderKind::new("example").unwrap();
+        let id = service
+            .for_provider(&kind)
+            .unwrap()
+            .import_document(import())
+            .await
+            .unwrap()
+            .credential_ids
+            .remove(0);
+        let provider = registry.require(&kind).unwrap();
+        let account = admin
+            .accounts()
+            .credential_details(&kind, &id)
+            .await
+            .unwrap()
+            .unwrap()
+            .credential;
+        let prepared = provider
+            .prepare_refresh(PrepareCredentialRefresh { account })
+            .await;
+        if ambiguous {
+            assert_eq!(
+                prepared.unwrap_err().kind(),
+                ProviderAdminErrorKind::Ambiguous
+            );
+        } else {
+            let prepared = prepared.unwrap();
+            assert_eq!(
+                prepared
+                    .facts()
+                    .provider_material
+                    .expose_to_provider()
+                    .expose_to_provider()["key"],
+                "upstream-rotated-key"
+            );
+            let (facts, guard) = prepared.into_parts();
+            admin
+                .accounts()
+                .commit_credential_refresh(
+                    CredentialRotationCommit {
+                        prepared: facts,
+                        settings: None,
+                    },
+                    &mutation(),
+                )
+                .await
+                .unwrap();
+            guard.finish();
+        }
+        let account = environment
+            .store
+            .provider_ports()
+            .accounts()
+            .load_current_credential(&id)
+            .await
+            .unwrap();
+        assert_eq!(
+            account.account.revision().get(),
+            if ambiguous { 1 } else { 2 }
+        );
+        drop(provider);
+        drop(service);
+        drop(registry);
+        drop(admin);
+        drop(core);
+        drop(runtime);
+        environment.close().await;
+    }
+}
+
+fn import() -> ImportCredentials {
+    ImportCredentials {
+        outbound_proxy_id: None,
+        settings: None,
+        context: mutation(),
+        document: document(
+            json!({"accounts":[{"name":"initial profile", "authentication_kind":"oauth", "material":{"key":"original-test-key"}, "has_refresh_token":true}]}),
+        ),
+    }
+}
+
+fn document(value: serde_json::Value) -> ProviderDocument {
+    ProviderDocument::new(OpaqueProviderData::new(value.as_object().unwrap().clone()))
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/callback/log.rs b/backend/crates/gateway-plugin/runtime/tests/callback/log.rs
new file mode 100644
index 000000000..18e9f9f3a
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/callback/log.rs
@@ -0,0 +1,340 @@
+use std::{
+    collections::BTreeMap,
+    sync::{Arc, Condvar, Mutex},
+    time::Duration,
+};
+
+use gateway_admin::{
+    model::{
+        Revision,
+        plugins::instances::{PluginInstance, PluginInstanceSnapshot},
+    },
+    ports::plugins::{PluginPackageInspector, PluginPreparation},
+};
+use gateway_plugin_runtime::{
+    PackageInspector, PackageLimits, PluginRuntime, PluginRuntimeConfig, RpcLimits,
+};
+use serde_json::{Value, json};
+
+#[derive(Clone, Default)]
+struct Capture(Arc<Mutex<Vec<BTreeMap<String, String>>>>, Arc<Gate>);
+
+#[derive(Default)]
+struct Gate {
+    released: Mutex<bool>,
+    changed: Condvar,
+}
+
+impl Gate {
+    fn wait(&self) {
+        // 测试回归为同步阻塞时也能自行退出，不能把测试运行器永久挂住。
+        let (mut released, _) = self
+            .changed
+            .wait_timeout_while(
+                self.released.lock().unwrap(),
+                Duration::from_secs(30),
+                |released| !*released,
+            )
+            .unwrap();
+        *released = true;
+        self.changed.notify_all();
+    }
+
+    fn release(&self) {
+        *self.released.lock().unwrap() = true;
+        self.changed.notify_all();
+    }
+}
+
+struct ReleaseOnDrop(Arc<Gate>);
+
+impl Drop for ReleaseOnDrop {
+    fn drop(&mut self) {
+        self.0.release();
+    }
+}
+
+struct Fields(BTreeMap<String, String>);
+
+impl tracing::field::Visit for Fields {
+    fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn std::fmt::Debug) {
+        self.0.insert(field.name().into(), format!("{value:?}"));
+    }
+}
+
+impl tracing::Subscriber for Capture {
+    fn enabled(&self, metadata: &tracing::Metadata<'_>) -> bool {
+        metadata.target() == "gateway_plugin"
+    }
+
+    fn new_span(&self, _: &tracing::span::Attributes<'_>) -> tracing::span::Id {
+        tracing::span::Id::from_u64(1)
+    }
+
+    fn record(&self, _: &tracing::span::Id, _: &tracing::span::Record<'_>) {}
+    fn record_follows_from(&self, _: &tracing::span::Id, _: &tracing::span::Id) {}
+    fn enter(&self, _: &tracing::span::Id) {}
+    fn exit(&self, _: &tracing::span::Id) {}
+
+    fn event(&self, event: &tracing::Event<'_>) {
+        if event.metadata().target() == "gateway_plugin" {
+            let mut fields = Fields(BTreeMap::from([(
+                "level".into(),
+                event.metadata().level().to_string(),
+            )]));
+            event.record(&mut fields);
+            if fields
+                .0
+                .get("instance_id")
+                .is_some_and(|id| id == "log-blocked")
+            {
+                self.1.wait();
+            }
+            self.0.lock().unwrap().push(fields.0);
+        }
+    }
+}
+
+#[tokio::test]
+async fn real_worker_logs_are_correlated_sanitized_validated_and_bounded() {
+    let capture = Capture::default();
+    tracing::subscriber::set_global_default(capture.clone()).unwrap();
+    let directory = tempfile::tempdir().unwrap();
+    let marker = directory.path().join("callbacks.jsonl");
+    let mut entries = ["debug", "info", "warn", "error"].map(|level| json!({
+        "params":{"event":"fixture-secret-event-token","level":level,"fields":{
+            "status":429,"authorization":"fixture-secret-token",
+            "metadata":{"message":"fixture-private-body","credential":"fixture-nested-secret"},
+            "fixture-private-key-name":"fixture-private-value"
+        }}
+    })).to_vec();
+    for params in [
+        json!({"event":"bad\nline"}),
+        json!({"event":"x".repeat(65)}),
+        json!({"event":"fixture.log","fields":{"message":"x".repeat(9000)}}),
+        json!({"event":"fixture.log","fields": (0..33).map(|i| (format!("f{i}"),json!(1))).collect::<BTreeMap<_,_>>()}),
+        json!({"event":"fixture.log","instance_id":"forged"}),
+        json!({"event":"fixture.log","level":"trace"}),
+    ] {
+        entries.push(json!({"params":params}));
+    }
+    entries.push(json!({"params":{"event":"fixture.log"},"with_payload":true}));
+    entries.push(json!({"params":{"event":"fixture.flood"},"repeat":128}));
+    entries.push(json!({"params":{"event":"fixture.resumed"},"delay_ms":1100}));
+
+    let artifact = PackageInspector::new(PackageLimits::default(), "1.0.0".parse().unwrap())
+        .inspect(
+            crate::support::package_with_permissions(crate::support::worker(), vec![]),
+            None,
+        )
+        .await
+        .unwrap();
+    let instance = PluginInstance {
+        id: "log-fixture".into(),
+        name: "日志验收".into(),
+        artifact_sha256: artifact.metadata.sha256.clone(),
+        enabled: true,
+        trusted_process: true,
+        configuration: json!({"log_method":"plugin.register","log_entries":entries,"log_marker":marker}),
+        secrets: BTreeMap::new(),
+        grants: vec![],
+        bindings: vec![],
+        revision: Revision::new(1).unwrap(),
+    };
+    let snapshot = PluginInstanceSnapshot {
+        config_revision: Revision::new(7).unwrap(),
+        instances: vec![instance],
+    };
+    let store = Arc::new(crate::support::store::Store {
+        artifacts: BTreeMap::from([(artifact.metadata.sha256.clone(), artifact)]),
+        snapshot: Mutex::new(snapshot.clone()),
+    });
+    let runtime = PluginRuntime::new(
+        store.clone(),
+        store,
+        PluginRuntimeConfig {
+            cache_directory: directory.path().join("cache"),
+            host_version: "1.0.0".parse().unwrap(),
+            package_limits: PackageLimits::default(),
+            rpc_limits: RpcLimits::default(),
+            continuation_drain: Default::default(),
+            restart_circuit: Default::default(),
+        },
+        gateway_core::engine::provider::ProviderRegistry::default(),
+        gateway_admin::ports::provider::ProviderAdminRegistry::new([]).unwrap(),
+        Arc::new(gateway_host::outbound::HttpClient::new().unwrap()),
+        Arc::new(gateway_host::process::ProcessSupervisor::new(
+            std::num::NonZeroUsize::new(4).unwrap(),
+        )),
+    );
+    let generation =
+        PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+            .await
+            .unwrap();
+    let results: Vec<Value> =
+        serde_json::from_str(std::fs::read_to_string(&marker).unwrap().trim()).unwrap();
+    assert!(
+        results[..4].iter().all(|result| result["recorded"] == true),
+        "{:?}",
+        &results[..4]
+    );
+    assert!(
+        results[4..11]
+            .iter()
+            .all(|result| result["error"] == "invalid_input")
+    );
+    let suppressed = results
+        .iter()
+        .filter(|result| result["recorded"] == false)
+        .count();
+    assert!(suppressed > 0, "日志过量应丢弃，不把背压传播给业务调用");
+    assert_eq!(results.last().unwrap()["recorded"], true);
+    let accepted = results
+        .iter()
+        .filter(|result| result["recorded"] == true)
+        .count();
+    tokio::time::timeout(Duration::from_secs(3), async {
+        loop {
+            let count = capture
+                .0
+                .lock()
+                .unwrap()
+                .iter()
+                .filter(|fields| {
+                    fields
+                        .get("instance_id")
+                        .is_some_and(|id| id == "log-fixture")
+                })
+                .count();
+            if count == accepted {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .unwrap();
+    {
+        let captured = capture.0.lock().unwrap();
+        let records = captured
+            .iter()
+            .filter(|fields| {
+                fields
+                    .get("instance_id")
+                    .is_some_and(|id| id == "log-fixture")
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(
+            records.len(),
+            results
+                .iter()
+                .filter(|result| result["recorded"] == true)
+                .count()
+        );
+        for record in &records {
+            assert_eq!(record["plugin_id"], "test.example");
+            assert_eq!(record["plugin_version"], "1.0.0");
+            assert_eq!(record["generation"], "7");
+            assert_ne!(record["call_id"], "0");
+            assert!(!record["incarnation"].is_empty());
+        }
+        for level in ["DEBUG", "INFO", "WARN", "ERROR"] {
+            assert!(records.iter().any(|record| record["level"] == level));
+        }
+        let first_fields: Value = serde_json::from_str(
+            &records
+                .iter()
+                .find(|record| record["level"] == "ERROR")
+                .unwrap()["fields"],
+        )
+        .unwrap();
+        assert_eq!(first_fields["status"], 429);
+        let encoded = format!("{records:?}");
+        for secret in [
+            "fixture-secret-event-token",
+            "fixture-secret-token",
+            "fixture-private-body",
+            "fixture-nested-secret",
+            "fixture-private-key-name",
+            "fixture-private-value",
+        ] {
+            assert!(
+                !encoded.contains(secret),
+                "普通日志不得保留 fixture 敏感内容"
+            );
+        }
+        assert!(
+            records
+                .iter()
+                .any(|record| record["suppressed_logs"].parse::<u64>().unwrap() > 0)
+        );
+    }
+    let release = ReleaseOnDrop(capture.1.clone());
+    let blocked_marker = directory.path().join("blocked.jsonl");
+    let mut blocked = snapshot.clone();
+    blocked.config_revision = Revision::new(9).unwrap();
+    blocked.instances[0].id = "log-blocked".into();
+    blocked.instances[0].configuration = json!({
+        "log_method":"plugin.register", "log_entries":[{"params":{"event":"fixture.blocked"},"repeat":32}],
+        "log_marker":blocked_marker,
+    });
+    // 日志后端停住时，注册的业务结果和父调用结束仍须及时完成。
+    let blocked_generation = tokio::time::timeout(
+        Duration::from_secs(10),
+        PluginPreparation::prepare(&runtime, blocked.config_revision, blocked),
+    )
+    .await
+    .unwrap()
+    .unwrap();
+    let blocked_results: Vec<Value> =
+        serde_json::from_str(std::fs::read_to_string(blocked_marker).unwrap().trim()).unwrap();
+    assert_eq!(
+        blocked_results
+            .iter()
+            .filter(|result| result["recorded"] == true)
+            .count(),
+        RpcLimits::default().maximum_callbacks
+    );
+    assert!(
+        blocked_results
+            .iter()
+            .any(|result| result["recorded"] == false)
+    );
+    drop(blocked_generation);
+    let next_marker = directory.path().join("next-generation.jsonl");
+    let mut next = snapshot;
+    next.config_revision = Revision::new(10).unwrap();
+    next.instances[0].id = "log-next-generation".into();
+    next.instances[0].configuration = json!({
+        "log_method":"plugin.register", "log_entries":[{"params":{"event":"fixture.next"}}],
+        "log_marker":next_marker,
+    });
+    let next_generation = tokio::time::timeout(
+        Duration::from_secs(10),
+        PluginPreparation::prepare(&runtime, next.config_revision, next),
+    )
+    .await
+    .unwrap()
+    .unwrap();
+    let next_results: Vec<Value> =
+        serde_json::from_str(std::fs::read_to_string(next_marker).unwrap().trim()).unwrap();
+    assert_eq!(
+        next_results,
+        [json!({"recorded":false})],
+        "父调用结束与代次撤下不能提前释放仍阻塞的写入容量"
+    );
+    drop(next_generation);
+    drop(release);
+    drop(generation);
+    tokio::time::timeout(Duration::from_secs(3), async {
+        while std::fs::read_dir(directory.path().join("cache"))
+            .unwrap()
+            .next()
+            .is_some()
+        {
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+    })
+    .await
+    .unwrap();
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/callback/mod.rs b/backend/crates/gateway-plugin/runtime/tests/callback/mod.rs
new file mode 100644
index 000000000..aad31d7a6
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/callback/mod.rs
@@ -0,0 +1 @@
+mod log;
diff --git a/backend/crates/gateway-plugin/runtime/tests/generation/authentication.rs b/backend/crates/gateway-plugin/runtime/tests/generation/authentication.rs
new file mode 100644
index 000000000..68957f91c
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/generation/authentication.rs
@@ -0,0 +1,252 @@
+use gateway_admin::model::client_keys::SetClientKeyEnabled;
+use gateway_core::{
+    engine::{authentication::ClientAuthenticationRequest, execution::ClientAuthenticationError},
+    policy::ClientApiKeyId,
+};
+use serde_json::{Value, json};
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+async fn authenticate(
+    configuration: Value,
+    authorization: &str,
+) -> Option<(
+    Environment,
+    std::sync::Arc<gateway_plugin_runtime::PluginRuntime>,
+    gateway_core::CoreBundle,
+    Result<gateway_core::engine::execution::AuthenticatedClient, ClientAuthenticationError>,
+)> {
+    let environment = Environment::create().await?;
+    environment
+        .client_key("key_frontend", "sk-native-fixture")
+        .await;
+    let (runtime, core) = environment
+        .provider(configuration, vec![account_grant("accounts")])
+        .await;
+    let result = core
+        .execution_service()
+        .authenticate_request(ClientAuthenticationRequest::new(authorization).unwrap())
+        .await;
+    Some((environment, runtime, core, result))
+}
+
+async fn close(
+    environment: Environment,
+    runtime: std::sync::Arc<gateway_plugin_runtime::PluginRuntime>,
+    core: gateway_core::CoreBundle,
+) {
+    environment.release_plugin_accounts(&runtime);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+fn configuration(result: Value, exclusive: bool, expected_authorization: &str) -> Value {
+    json!({
+        "frontend_authentication_result": result,
+        "frontend_authentication_principal": "external-user",
+        "frontend_authentication_client_key_id": "key_frontend",
+        "frontend_authentication_exclusive": exclusive,
+        "expected_frontend_authorization": expected_authorization,
+    })
+}
+
+#[tokio::test]
+async fn frontend_authentication_maps_only_the_configured_principal_to_an_existing_policy() {
+    let Some((environment, runtime, core, result)) = authenticate(
+        configuration(
+            json!({"outcome":"authenticated","principal":"external-user"}),
+            true,
+            "External controlled-fixture",
+        ),
+        "External controlled-fixture",
+    )
+    .await
+    else {
+        return;
+    };
+
+    let client = result.expect("configured principal authenticates");
+    assert_eq!(client.policy().key_id().as_str(), "key_frontend");
+    close(environment, runtime, core).await;
+}
+
+#[tokio::test]
+async fn delegate_falls_back_only_for_not_matched_while_exclusive_never_falls_back() {
+    let Some((delegating_environment, delegating_runtime, delegating_core, delegated)) =
+        authenticate(
+            configuration(
+                json!({"outcome":"not_matched"}),
+                false,
+                "Bearer sk-native-fixture",
+            ),
+            "Bearer sk-native-fixture",
+        )
+        .await
+    else {
+        return;
+    };
+    assert_eq!(
+        delegated.unwrap().policy().key_id().as_str(),
+        "key_frontend"
+    );
+    close(delegating_environment, delegating_runtime, delegating_core).await;
+
+    let Some((exclusive_environment, exclusive_runtime, exclusive_core, exclusive)) = authenticate(
+        configuration(
+            json!({"outcome":"not_matched"}),
+            true,
+            "Bearer sk-native-fixture",
+        ),
+        "Bearer sk-native-fixture",
+    )
+    .await
+    else {
+        return;
+    };
+    assert!(matches!(
+        exclusive,
+        Err(ClientAuthenticationError::InvalidKey)
+    ));
+    close(exclusive_environment, exclusive_runtime, exclusive_core).await;
+}
+
+#[tokio::test]
+async fn rejection_unmapped_principal_and_plugin_supplied_key_id_fail_closed() {
+    for result in [
+        json!({"outcome":"rejected"}),
+        json!({"outcome":"authenticated","principal":"unmapped"}),
+    ] {
+        let Some((environment, runtime, core, authentication)) = authenticate(
+            configuration(result, false, "Bearer sk-native-fixture"),
+            "Bearer sk-native-fixture",
+        )
+        .await
+        else {
+            return;
+        };
+        assert!(matches!(
+            authentication,
+            Err(ClientAuthenticationError::InvalidKey)
+        ));
+        close(environment, runtime, core).await;
+    }
+
+    let Some((environment, runtime, core, authentication)) = authenticate(
+        configuration(
+            json!({
+                "outcome":"authenticated",
+                "principal":"external-user",
+                "client_key_id":"attacker-selected-key"
+            }),
+            false,
+            "Bearer sk-native-fixture",
+        ),
+        "Bearer sk-native-fixture",
+    )
+    .await
+    else {
+        return;
+    };
+    assert!(matches!(
+        authentication,
+        Err(ClientAuthenticationError::ProviderUnavailable)
+    ));
+    close(environment, runtime, core).await;
+}
+
+#[tokio::test]
+async fn disabling_the_mapped_client_key_revokes_frontend_authentication_after_publish() {
+    let Some((environment, runtime, core, first)) = authenticate(
+        configuration(
+            json!({"outcome":"authenticated","principal":"external-user"}),
+            true,
+            "External controlled-fixture",
+        ),
+        "External controlled-fixture",
+    )
+    .await
+    else {
+        return;
+    };
+    assert!(first.is_ok());
+
+    let (revision, _) = environment
+        .store
+        .admin_ports()
+        .client_keys()
+        .set_client_key_enabled(
+            SetClientKeyEnabled {
+                id: ClientApiKeyId::new("key_frontend").unwrap(),
+                enabled: false,
+            },
+            &mutation(),
+        )
+        .await
+        .unwrap();
+    core.snapshot_control()
+        .publish_committed(gateway_core::routing::ConfigRevision::new(revision.get()).unwrap())
+        .await;
+    let revoked = core
+        .execution_service()
+        .authenticate_request(
+            ClientAuthenticationRequest::new("External controlled-fixture").unwrap(),
+        )
+        .await;
+    assert!(matches!(
+        revoked,
+        Err(ClientAuthenticationError::InvalidKey)
+    ));
+    close(environment, runtime, core).await;
+}
+
+#[tokio::test]
+async fn startup_failure_of_an_authentication_plugin_never_falls_back_to_a_native_key() {
+    let mut config = configuration(
+        json!({"outcome":"not_matched"}),
+        false,
+        "Bearer sk-native-fixture",
+    );
+    config["startup"] = json!("fail");
+    let Some((environment, runtime, core, authentication)) =
+        authenticate(config, "Bearer sk-native-fixture").await
+    else {
+        return;
+    };
+    assert!(
+        core.snapshots().acquire().is_ok(),
+        "the host stays available"
+    );
+    assert!(matches!(
+        authentication,
+        Err(ClientAuthenticationError::ProviderUnavailable)
+    ));
+    for probe in core.health_probes() {
+        assert!(matches!(
+            probe.check().await,
+            gateway_core::health::HealthState::Healthy
+        ));
+    }
+    close(environment, runtime, core).await;
+}
+
+#[tokio::test]
+async fn startup_failure_of_an_unrelated_plugin_preserves_native_authentication_and_health() {
+    let Some((environment, runtime, core, authentication)) =
+        authenticate(json!({"startup":"fail"}), "Bearer sk-native-fixture").await
+    else {
+        return;
+    };
+    assert_eq!(
+        authentication.unwrap().policy().key_id().as_str(),
+        "key_frontend"
+    );
+    assert!(core.snapshots().acquire().is_ok());
+    for probe in core.health_probes() {
+        assert!(matches!(
+            probe.check().await,
+            gateway_core::health::HealthState::Healthy
+        ));
+    }
+    close(environment, runtime, core).await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/generation/configuration.rs b/backend/crates/gateway-plugin/runtime/tests/generation/configuration.rs
new file mode 100644
index 000000000..701bdd23e
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/generation/configuration.rs
@@ -0,0 +1,171 @@
+use gateway_admin::{
+    model::plugins::instances::{
+        PluginCapabilityBinding, PluginFailurePolicy, PluginPermissionGrant,
+    },
+    ports::plugins::PluginPreparation,
+};
+use gateway_plugin_sdk::{Capability, Contributions, Stage};
+
+#[tokio::test]
+async fn readiness_uses_validated_metadata_without_loading_the_archive() {
+    let (_cache, store, runtime) = super::setup().await;
+    let mut instance = store.snapshot.lock().unwrap().instances[0].clone();
+    let mut metadata = store.artifacts[&instance.artifact_sha256].metadata.clone();
+    // Store 中没有这个摘要；只读校验只能消费传入的声明，不能退回整包加载。
+    metadata.sha256 = "0".repeat(64);
+    instance.artifact_sha256 = metadata.sha256.clone();
+    metadata.configuration_schema = serde_json::json!({
+        "type": "object", "required": ["name", "token"],
+        "properties": {"name": {"type": "string"}, "token": {"type": "string"}},
+        "additionalProperties": false
+    });
+    metadata.secret_fields = vec!["token".into()];
+    instance.configuration = serde_json::json!({});
+    assert!(
+        !runtime
+            .configuration_ready(instance.clone(), &metadata)
+            .await
+            .unwrap()
+    );
+    instance.configuration = serde_json::json!({"name": "fixture"});
+    instance
+        .secrets
+        .insert("token".into(), "fixture-value".into());
+    assert!(
+        runtime
+            .configuration_ready(instance.clone(), &metadata)
+            .await
+            .unwrap()
+    );
+    instance.configuration = serde_json::json!({"name": 42});
+    assert!(
+        runtime
+            .configuration_ready(instance.clone(), &metadata)
+            .await
+            .is_err()
+    );
+    instance.configuration = serde_json::json!({"name": "fixture", "token": "not-allowed"});
+    assert!(
+        runtime
+            .configuration_ready(instance.clone(), &metadata)
+            .await
+            .is_err()
+    );
+    instance.configuration = serde_json::json!({"name": "fixture"});
+    instance
+        .secrets
+        .insert("undeclared".into(), "fixture-value".into());
+    assert!(
+        runtime
+            .configuration_ready(instance, &metadata)
+            .await
+            .is_err()
+    );
+}
+
+#[tokio::test]
+async fn schema_rejection_identifies_the_field_without_exposing_configuration_values() {
+    let (_cache, store, runtime) = super::setup().await;
+    let mut instance = store.snapshot.lock().unwrap().instances[0].clone();
+    let mut metadata = store.artifacts[&instance.artifact_sha256].metadata.clone();
+    metadata.configuration_schema = serde_json::json!({
+        "type": "object",
+        "properties": {
+            "timeout": {"type": "integer"},
+            "token": {"type": "string", "pattern": "^accepted$"}
+        },
+        "additionalProperties": false
+    });
+    metadata.secret_fields = vec!["token".into()];
+    for (configuration, secret, expected) in [
+        (
+            serde_json::json!({"timeout": "private-value"}),
+            None,
+            "插件配置 /timeout：类型不匹配",
+        ),
+        (
+            serde_json::json!({"retired": "private-value"}),
+            None,
+            "插件配置 /retired：目标版本不支持此字段",
+        ),
+        (
+            serde_json::json!({}),
+            Some("private-value"),
+            "插件配置 /token：不符合字段要求",
+        ),
+    ] {
+        instance.configuration = configuration;
+        instance.secrets.clear();
+        if let Some(value) = secret {
+            instance.secrets.insert("token".into(), value.into());
+        }
+        let error = runtime
+            .configuration_ready(instance.clone(), &metadata)
+            .await
+            .unwrap_err();
+        assert_eq!(error.message(), expected);
+    }
+}
+
+#[tokio::test]
+async fn process_execution_requires_trust_and_undeclared_permissions_are_rejected() {
+    let (_cache, store, runtime) = super::setup().await;
+    let mut instance = store.snapshot.lock().unwrap().instances[0].clone();
+    instance.trusted_process = false;
+    assert!(runtime.validate(instance.clone()).await.is_err());
+    instance.trusted_process = true;
+    instance.grants.push(PluginPermissionGrant {
+        permission: "accounts".into(),
+    });
+    assert!(runtime.validate(instance).await.is_err());
+}
+
+#[tokio::test]
+async fn secrets_must_be_declared_by_the_package() {
+    let (_cache, store, runtime) = super::setup().await;
+    let mut instance = store.snapshot.lock().unwrap().instances[0].clone();
+    instance
+        .secrets
+        .insert("token".into(), "sensitive-fixture".into());
+    assert!(runtime.validate(instance).await.is_err());
+}
+
+#[tokio::test]
+async fn enabled_bindings_must_reference_the_exact_declared_contribution_and_stage() {
+    let (_cache, store, runtime) =
+        super::setup_with_contributions(Contributions::from([crate::support::contribution(
+            Capability::Usage,
+            vec![Stage::Observation],
+            vec![],
+            vec![],
+        )]))
+        .await;
+    let instance = store.snapshot.lock().unwrap().instances[0].clone();
+    let mut valid = instance.clone();
+    valid.bindings = vec![PluginCapabilityBinding {
+        contribution: "test.example.usage".into(),
+        stage: "observation".into(),
+        order: 0,
+        failure_policy: PluginFailurePolicy::Observe,
+        client_key_ids: vec![],
+        account_group_ids: vec![],
+        provider_ids: vec![],
+        models: vec![],
+        identity_bindings: vec![],
+    }];
+    assert!(runtime.validate(valid.clone()).await.is_ok());
+
+    for (contribution, stage) in [
+        ("test.example.unknown", "observation"),
+        ("other.example.usage", "observation"),
+        ("test.example.usage", "routing"),
+    ] {
+        let mut candidate = valid.clone();
+        candidate.bindings[0].contribution = contribution.into();
+        candidate.bindings[0].stage = stage.into();
+        assert!(
+            runtime.validate(candidate).await.is_err(),
+            "binding {contribution}/{stage} must be rejected"
+        );
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/generation/mod.rs b/backend/crates/gateway-plugin/runtime/tests/generation/mod.rs
new file mode 100644
index 000000000..190ebb67f
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/generation/mod.rs
@@ -0,0 +1,112 @@
+mod authentication;
+mod configuration;
+mod observer;
+mod observer_example;
+mod policy;
+mod prepare;
+mod private_state;
+mod worker;
+
+use gateway_admin::{
+    model::{
+        Revision,
+        plugins::instances::{PluginInstance, PluginInstanceSnapshot},
+    },
+    ports::plugins::PluginPackageInspector,
+};
+use gateway_plugin_runtime::{
+    PackageInspector, PackageLimits, PluginRestartCircuitConfig, PluginRuntime,
+    PluginRuntimeConfig, RpcLimits,
+};
+use gateway_plugin_sdk::Contributions;
+use std::{
+    collections::BTreeMap,
+    sync::{Arc, Mutex},
+};
+
+use crate::support::store::Store;
+
+async fn setup() -> (tempfile::TempDir, Arc<Store>, PluginRuntime) {
+    setup_with_contributions(Contributions::new()).await
+}
+
+async fn setup_with_contributions(
+    contributes: Contributions,
+) -> (tempfile::TempDir, Arc<Store>, PluginRuntime) {
+    setup_with_contributions_and_restart_circuit(contributes, Default::default()).await
+}
+
+async fn setup_with_restart_circuit(
+    restart_circuit: PluginRestartCircuitConfig,
+) -> (tempfile::TempDir, Arc<Store>, PluginRuntime) {
+    setup_with_contributions_and_restart_circuit(Contributions::new(), restart_circuit).await
+}
+
+async fn setup_with_contributions_and_restart_circuit(
+    contributes: Contributions,
+    restart_circuit: PluginRestartCircuitConfig,
+) -> (tempfile::TempDir, Arc<Store>, PluginRuntime) {
+    let cache = tempfile::tempdir().unwrap();
+    let artifact = PackageInspector::new(PackageLimits::default(), "1.0.0".parse().unwrap())
+        .inspect(
+            crate::support::package_with_contributions(
+                crate::support::worker(),
+                Vec::new(),
+                contributes,
+            ),
+            None,
+        )
+        .await
+        .unwrap();
+    let instance = PluginInstance {
+        id: "instance-one".into(),
+        name: "Example".into(),
+        artifact_sha256: artifact.metadata.sha256.clone(),
+        enabled: true,
+        trusted_process: true,
+        configuration: serde_json::json!({}),
+        secrets: BTreeMap::new(),
+        grants: vec![],
+        bindings: vec![],
+        revision: Revision::new(1).unwrap(),
+    };
+    let store = Arc::new(Store {
+        artifacts: BTreeMap::from([(artifact.metadata.sha256.clone(), artifact)]),
+        snapshot: Mutex::new(PluginInstanceSnapshot {
+            config_revision: Revision::new(1).unwrap(),
+            instances: vec![instance],
+        }),
+    });
+    let runtime = PluginRuntime::new(
+        store.clone(),
+        store.clone(),
+        PluginRuntimeConfig {
+            cache_directory: cache.path().to_owned(),
+            host_version: "1.0.0".parse().unwrap(),
+            package_limits: PackageLimits::default(),
+            rpc_limits: RpcLimits::default(),
+            continuation_drain: Default::default(),
+            restart_circuit,
+        },
+        gateway_core::engine::provider::ProviderRegistry::default(),
+        gateway_admin::ports::provider::ProviderAdminRegistry::new([]).unwrap(),
+        Arc::new(gateway_host::outbound::HttpClient::new().unwrap()),
+        Arc::new(gateway_host::process::ProcessSupervisor::new(
+            std::num::NonZeroUsize::new(128).unwrap(),
+        )),
+    );
+    (cache, store, runtime)
+}
+
+async fn wait_until_empty(cache: &std::path::Path) {
+    tokio::time::timeout(std::time::Duration::from_secs(3), async {
+        loop {
+            if std::fs::read_dir(cache).unwrap().next().is_none() {
+                break;
+            }
+            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
+        }
+    })
+    .await
+    .unwrap();
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/generation/observer.rs b/backend/crates/gateway-plugin/runtime/tests/generation/observer.rs
new file mode 100644
index 000000000..8600130be
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/generation/observer.rs
@@ -0,0 +1,868 @@
+use std::{collections::BTreeMap, num::NonZeroU32, sync::Arc, time::Duration};
+
+use gateway_admin::{
+    model::{
+        Revision,
+        plugins::instances::{
+            PluginCapabilityBinding, PluginFailurePolicy, PluginInstance, PluginInstanceSnapshot,
+            PluginPermissionGrant,
+        },
+    },
+    ports::plugins::PluginPackageInspector,
+};
+use gateway_core::{
+    account::ProviderAccountId,
+    engine::{
+        ModelRequestId, ModelRequestTimings,
+        observation::{
+            RequestObservation, RequestObservationOutcome, WebSocketResponseAttempt,
+            WebSocketResponseObservation,
+        },
+        provider::ProviderRegistry,
+    },
+    error::GatewayErrorKind,
+    event::ProtocolWireEvent,
+    identity::ProviderKind,
+    metering::{ProviderReportedCost, Usage},
+    operation::OperationKind,
+    policy::ClientApiKeyId,
+    routing::{AccountGroupId, ConfigRevision, PublicModelId},
+    upstream::UpstreamSendState,
+};
+use gateway_plugin_runtime::{
+    PackageInspector, PackageLimits, PluginRuntime, PluginRuntimeConfig, RpcLimits,
+};
+use gateway_plugin_sdk::{Capability, Contributions, Permission, Stage};
+
+use crate::support::store::Store;
+
+const REQUEST_LIFECYCLE_CONTRIBUTION: &str = "test.example.requestLifecycle";
+const USAGE_CONTRIBUTION: &str = "test.example.usage";
+const WEB_SOCKET_OBSERVER_CONTRIBUTION: &str = "test.example.webSocketObserver";
+
+fn binding(contribution: &str, order: i32) -> PluginCapabilityBinding {
+    PluginCapabilityBinding {
+        contribution: contribution.into(),
+        stage: "observation".into(),
+        order,
+        failure_policy: PluginFailurePolicy::Observe,
+        client_key_ids: vec![],
+        account_group_ids: vec![],
+        provider_ids: vec!["openai".into()],
+        models: vec!["gpt-observed".into()],
+        identity_bindings: vec![],
+    }
+}
+
+struct InstanceFixture {
+    id: String,
+    configuration: serde_json::Value,
+    grants: Vec<PluginPermissionGrant>,
+    bindings: Vec<PluginCapabilityBinding>,
+}
+
+fn grant(permission: Permission) -> PluginPermissionGrant {
+    PluginPermissionGrant {
+        permission: permission.as_str().to_owned(),
+    }
+}
+
+async fn setup(
+    instances: Vec<(&str, serde_json::Value, Vec<PluginCapabilityBinding>)>,
+    rpc_limits: RpcLimits,
+) -> (tempfile::TempDir, PluginRuntime) {
+    setup_with_permissions(
+        instances
+            .into_iter()
+            .map(|(id, configuration, bindings)| InstanceFixture {
+                id: id.to_owned(),
+                configuration,
+                grants: vec![],
+                bindings,
+            })
+            .collect(),
+        vec![],
+        rpc_limits,
+    )
+    .await
+}
+
+async fn setup_with_permissions(
+    instances: Vec<InstanceFixture>,
+    manifest_permissions: Vec<Permission>,
+    rpc_limits: RpcLimits,
+) -> (tempfile::TempDir, PluginRuntime) {
+    let cache = tempfile::tempdir().unwrap();
+    let contributes = Contributions::from([
+        crate::support::contribution(
+            Capability::RequestLifecycle,
+            vec![Stage::Observation],
+            vec![],
+            vec![],
+        ),
+        crate::support::contribution(Capability::Usage, vec![Stage::Observation], vec![], vec![]),
+        crate::support::contribution(
+            Capability::WebSocketObserver,
+            vec![Stage::Observation],
+            vec![],
+            vec![],
+        ),
+    ]);
+    let artifact = PackageInspector::new(PackageLimits::default(), "1.0.0".parse().unwrap())
+        .inspect(
+            crate::support::package_with_contributions(
+                crate::support::worker(),
+                manifest_permissions,
+                contributes,
+            ),
+            None,
+        )
+        .await
+        .unwrap();
+    let digest = artifact.metadata.sha256.clone();
+    let instances = instances
+        .into_iter()
+        .map(|fixture| PluginInstance {
+            id: fixture.id.clone(),
+            name: fixture.id,
+            artifact_sha256: digest.clone(),
+            enabled: true,
+            trusted_process: true,
+            configuration: fixture.configuration,
+            secrets: BTreeMap::new(),
+            grants: fixture.grants,
+            bindings: fixture.bindings,
+            revision: Revision::new(1).unwrap(),
+        })
+        .collect();
+    let store = Arc::new(Store {
+        artifacts: BTreeMap::from([(digest, artifact)]),
+        snapshot: std::sync::Mutex::new(PluginInstanceSnapshot {
+            config_revision: Revision::new(1).unwrap(),
+            instances,
+        }),
+    });
+    let runtime = PluginRuntime::new(
+        store.clone(),
+        store,
+        PluginRuntimeConfig {
+            cache_directory: cache.path().to_owned(),
+            host_version: "1.0.0".parse().unwrap(),
+            package_limits: PackageLimits::default(),
+            rpc_limits,
+            continuation_drain: Default::default(),
+            restart_circuit: Default::default(),
+        },
+        ProviderRegistry::default(),
+        gateway_admin::ports::provider::ProviderAdminRegistry::new([]).unwrap(),
+        Arc::new(gateway_host::outbound::HttpClient::new().unwrap()),
+        Arc::new(gateway_host::process::ProcessSupervisor::new(
+            std::num::NonZeroUsize::new(16).unwrap(),
+        )),
+    );
+    (cache, runtime)
+}
+
+fn observation(id: &str, outcome: RequestObservationOutcome) -> RequestObservation {
+    let send_state = if outcome == RequestObservationOutcome::Rejected {
+        UpstreamSendState::NotSent
+    } else {
+        UpstreamSendState::Sent
+    };
+    RequestObservation::new(
+        ModelRequestId::new(id).unwrap(),
+        ConfigRevision::new(1).unwrap(),
+        OperationKind::Generate,
+        outcome,
+        send_state,
+        std::time::SystemTime::now(),
+    )
+    .with_requested_model(PublicModelId::new("gpt-observed").unwrap())
+    .with_usage(Usage {
+        input_tokens: Some(11),
+        output_tokens: Some(7),
+        total_tokens: Some(18),
+        ..Usage::default()
+    })
+}
+
+fn websocket_observation(
+    id: &str,
+    sequence: u64,
+    body: serde_json::Value,
+) -> WebSocketResponseObservation {
+    WebSocketResponseObservation::new(
+        ModelRequestId::new(id).unwrap(),
+        ConfigRevision::new(1).unwrap(),
+        OperationKind::Generate,
+        WebSocketResponseAttempt::new(
+            ProviderKind::new("openai").unwrap(),
+            ProviderAccountId::new("acct_observed").unwrap(),
+            NonZeroU32::new(2).unwrap(),
+        ),
+        sequence,
+        ProtocolWireEvent::json("openai", Some("response.output_text.delta".into()), body).unwrap(),
+    )
+    .with_client_scope(
+        ClientApiKeyId::new("client-key-observed").unwrap(),
+        vec![AccountGroupId::new("grp_11111111111111111111111111111111").unwrap()],
+    )
+    .with_requested_model(PublicModelId::new("gpt-observed").unwrap())
+}
+
+async fn wait_for_lines(path: &std::path::Path, count: usize) -> Vec<serde_json::Value> {
+    tokio::time::timeout(Duration::from_secs(3), async {
+        loop {
+            let lines = std::fs::read_to_string(path)
+                .unwrap_or_default()
+                // 子进程先追加 JSON 再写换行；只解析已经提交完整行的记录。
+                .split_inclusive('\n')
+                .filter(|line| line.ends_with('\n'))
+                .map(|line| serde_json::from_str(line).unwrap())
+                .collect::<Vec<_>>();
+            if lines.len() >= count {
+                return lines;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .expect("observer marker")
+}
+
+#[tokio::test]
+async fn frozen_plan_applies_scope_order_and_instance_deduplication() {
+    let marker_directory = tempfile::tempdir().unwrap();
+    let marker = marker_directory.path().join("observations.jsonl");
+    let (cache, runtime) = setup(
+        vec![
+            (
+                "late",
+                serde_json::json!({"observation_label":"late","observation_marker":marker}),
+                vec![binding(REQUEST_LIFECYCLE_CONTRIBUTION, 20)],
+            ),
+            (
+                "early",
+                serde_json::json!({"observation_label":"early","observation_marker":marker}),
+                vec![
+                    binding(REQUEST_LIFECYCLE_CONTRIBUTION, 10),
+                    binding(USAGE_CONTRIBUTION, 10),
+                ],
+            ),
+        ],
+        RpcLimits::default(),
+    )
+    .await;
+    let generation = gateway_core::runtime::extensions::ExtensionPreparationPort::prepare(
+        &runtime,
+        ConfigRevision::new(1).unwrap(),
+    )
+    .await
+    .unwrap();
+    let plan = runtime.observer_registry().resolve(&generation).unwrap();
+    plan.dispatch(
+        generation.clone(),
+        observation("req_observed", RequestObservationOutcome::Succeeded)
+            .with_provider(ProviderKind::new("openai").unwrap()),
+    );
+    let lines = wait_for_lines(&marker, 2).await;
+    assert_eq!(
+        lines.len(),
+        2,
+        "lifecycle and usage observations on one instance share one call"
+    );
+    assert_eq!(lines[0]["label"], "early");
+    assert!(lines[0]["observation"]["terminal"].is_object());
+    assert_eq!(lines[0]["observation"]["usage"]["total_tokens"], 18);
+    assert_eq!(lines[1]["label"], "late");
+    assert!(lines[1]["observation"]["terminal"].is_object());
+    assert!(lines[1]["observation"].get("usage").is_none());
+
+    plan.dispatch(
+        generation.clone(),
+        observation("req_model_miss", RequestObservationOutcome::Succeeded)
+            .with_requested_model(PublicModelId::new("gpt-other").unwrap())
+            .with_provider(ProviderKind::new("openai").unwrap()),
+    );
+    plan.dispatch(
+        generation.clone(),
+        observation("req_rejected", RequestObservationOutcome::Rejected),
+    );
+    tokio::time::sleep(Duration::from_millis(100)).await;
+    assert_eq!(wait_for_lines(&marker, 2).await.len(), 2);
+    drop(plan);
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn websocket_observer_preserves_order_generation_and_permission_boundaries() {
+    let marker_directory = tempfile::tempdir().unwrap();
+    let hidden = marker_directory.path().join("hidden.jsonl");
+    let readable = marker_directory.path().join("readable.jsonl");
+    let (cache, runtime) = setup_with_permissions(
+        vec![
+            InstanceFixture {
+                id: "hidden".into(),
+                configuration: serde_json::json!({
+                    "observation_label":"hidden",
+                    "websocket_observation_marker":hidden,
+                }),
+                grants: vec![],
+                bindings: vec![binding(WEB_SOCKET_OBSERVER_CONTRIBUTION, 1)],
+            },
+            InstanceFixture {
+                id: "readable".into(),
+                configuration: serde_json::json!({
+                    "observation_label":"readable",
+                    "websocket_observation_marker":readable,
+                }),
+                grants: vec![grant(Permission::Requests)],
+                bindings: vec![binding(WEB_SOCKET_OBSERVER_CONTRIBUTION, 2)],
+            },
+        ],
+        vec![Permission::Requests],
+        RpcLimits::default(),
+    )
+    .await;
+    let generation = gateway_core::runtime::extensions::ExtensionPreparationPort::prepare(
+        &runtime,
+        ConfigRevision::new(1).unwrap(),
+    )
+    .await
+    .unwrap();
+    let plan = runtime.observer_registry().resolve(&generation).unwrap();
+    for (sequence, secret) in [(1, "first"), (2, "second")] {
+        plan.dispatch_websocket_response(
+            generation.clone(),
+            websocket_observation(
+                "req_websocket_ordered",
+                sequence,
+                serde_json::json!({"type":"response.output_text.delta","secret":secret}),
+            ),
+        );
+    }
+    plan.dispatch(
+        generation.clone(),
+        observation(
+            "req_websocket_ordered",
+            RequestObservationOutcome::Succeeded,
+        ),
+    );
+    drop(plan);
+    drop(generation);
+
+    let hidden = wait_for_lines(&hidden, 2).await;
+    let readable = wait_for_lines(&readable, 2).await;
+    assert_eq!(
+        hidden
+            .iter()
+            .map(|line| line["observation"]["sequence"].as_u64().unwrap())
+            .collect::<Vec<_>>(),
+        vec![1, 2]
+    );
+    assert!(hidden.iter().all(|line| {
+        line["payload_bytes"] == 0
+            && line["observation"]["payload_included"] == false
+            && line["observation"].get("event_type").is_none()
+            && line["observation"]["account_id"] == "acct_observed"
+            && !line.to_string().contains("client-key-observed")
+            && !line
+                .to_string()
+                .contains("grp_11111111111111111111111111111111")
+            && !line.to_string().contains("secret")
+    }));
+    assert_eq!(
+        readable
+            .iter()
+            .map(|line| line["observation"]["sequence"].as_u64().unwrap())
+            .collect::<Vec<_>>(),
+        vec![1, 2]
+    );
+    assert!(readable.iter().all(|line| {
+        line["payload_bytes"].as_u64().unwrap() > 0
+            && line["observation"]["payload_included"] == true
+            && line["observation"]["event_type"] == "response.output_text.delta"
+            && line["observation"]["account_id"] == "acct_observed"
+    }));
+    assert_eq!(
+        readable
+            .iter()
+            .map(|line| {
+                serde_json::from_str::<serde_json::Value>(line["payload_text"].as_str().unwrap())
+                    .unwrap()["secret"]
+                    .as_str()
+                    .unwrap()
+                    .to_owned()
+            })
+            .collect::<Vec<_>>(),
+        vec!["first", "second"]
+    );
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn websocket_observer_bounds_event_count_and_payload_bytes_without_blocking() {
+    let marker_directory = tempfile::tempdir().unwrap();
+    let count_started = marker_directory.path().join("count-started.jsonl");
+    let count_completed = marker_directory.path().join("count-completed.jsonl");
+    let limits = RpcLimits {
+        maximum_calls: 1,
+        ..RpcLimits::default()
+    };
+    let (count_cache, count_runtime) = setup_with_permissions(
+        vec![InstanceFixture {
+            id: "count".into(),
+            configuration: serde_json::json!({
+                "websocket_observation_started_marker":count_started,
+                "websocket_observation_marker":count_completed,
+                "websocket_observation_delay_ms":150,
+            }),
+            grants: vec![grant(Permission::Requests)],
+            bindings: vec![binding(WEB_SOCKET_OBSERVER_CONTRIBUTION, 1)],
+        }],
+        vec![Permission::Requests],
+        limits,
+    )
+    .await;
+    let count_generation = gateway_core::runtime::extensions::ExtensionPreparationPort::prepare(
+        &count_runtime,
+        ConfigRevision::new(1).unwrap(),
+    )
+    .await
+    .unwrap();
+    let count_plan = count_runtime
+        .observer_registry()
+        .resolve(&count_generation)
+        .unwrap();
+    count_plan.dispatch_websocket_response(
+        count_generation.clone(),
+        websocket_observation(
+            "req_websocket_count",
+            1,
+            serde_json::json!({"type":"response.delta","value":1}),
+        ),
+    );
+    wait_for_lines(&count_started, 1).await;
+    for sequence in [2, 3] {
+        count_plan.dispatch_websocket_response(
+            count_generation.clone(),
+            websocket_observation(
+                "req_websocket_count",
+                sequence,
+                serde_json::json!({"type":"response.delta","value":sequence}),
+            ),
+        );
+    }
+    count_plan.dispatch(
+        count_generation.clone(),
+        observation("req_websocket_count", RequestObservationOutcome::Succeeded),
+    );
+    drop(count_plan);
+    drop(count_generation);
+    let completed = wait_for_lines(&count_completed, 2).await;
+    assert_eq!(completed.len(), 2);
+    assert_eq!(completed[0]["observation"]["sequence"], 1);
+    assert_eq!(completed[1]["observation"]["sequence"], 2);
+    tokio::time::sleep(Duration::from_millis(50)).await;
+    assert_eq!(wait_for_lines(&count_completed, 2).await.len(), 2);
+    super::wait_until_empty(count_cache.path()).await;
+
+    let byte_started = marker_directory.path().join("byte-started.jsonl");
+    let fault_completed = marker_directory.path().join("fault-completed.jsonl");
+    let healthy_completed = marker_directory.path().join("healthy-completed.jsonl");
+    let (byte_cache, byte_runtime) = setup_with_permissions(
+        vec![
+            InstanceFixture {
+                id: "fault".into(),
+                configuration: serde_json::json!({
+                    "websocket_observation_started_marker":byte_started,
+                    "websocket_observation_marker":fault_completed,
+                    "websocket_observation_delay_ms":150,
+                    "websocket_observation_fault":true,
+                }),
+                grants: vec![grant(Permission::Requests)],
+                bindings: vec![binding(WEB_SOCKET_OBSERVER_CONTRIBUTION, 1)],
+            },
+            InstanceFixture {
+                id: "healthy".into(),
+                configuration: serde_json::json!({
+                    "websocket_observation_marker":healthy_completed,
+                }),
+                grants: vec![grant(Permission::Requests)],
+                bindings: vec![binding(WEB_SOCKET_OBSERVER_CONTRIBUTION, 2)],
+            },
+        ],
+        vec![Permission::Requests],
+        RpcLimits::default(),
+    )
+    .await;
+    let byte_generation = gateway_core::runtime::extensions::ExtensionPreparationPort::prepare(
+        &byte_runtime,
+        ConfigRevision::new(1).unwrap(),
+    )
+    .await
+    .unwrap();
+    let byte_plan = byte_runtime
+        .observer_registry()
+        .resolve(&byte_generation)
+        .unwrap();
+    let large_body = || {
+        serde_json::json!({
+            "type":"response.delta",
+            "content":"x".repeat(600_000),
+        })
+    };
+    byte_plan.dispatch_websocket_response(
+        byte_generation.clone(),
+        websocket_observation("req_websocket_bytes", 1, large_body()),
+    );
+    wait_for_lines(&byte_started, 1).await;
+    byte_plan.dispatch_websocket_response(
+        byte_generation.clone(),
+        websocket_observation("req_websocket_bytes", 2, large_body()),
+    );
+    byte_plan.dispatch(
+        byte_generation.clone(),
+        observation("req_websocket_bytes", RequestObservationOutcome::Succeeded),
+    );
+    drop(byte_plan);
+    drop(byte_generation);
+    assert_eq!(wait_for_lines(&fault_completed, 1).await.len(), 1);
+    let healthy = wait_for_lines(&healthy_completed, 1).await;
+    assert_eq!(healthy.len(), 1, "观察失败不能阻断同批后续订阅者");
+    assert_eq!(healthy[0]["observation"]["sequence"], 1);
+    tokio::time::sleep(Duration::from_millis(50)).await;
+    assert_eq!(wait_for_lines(&healthy_completed, 1).await.len(), 1);
+    super::wait_until_empty(byte_cache.path()).await;
+}
+
+#[tokio::test]
+async fn observer_failure_continues_the_plan_and_timeout_is_bounded() {
+    let marker_directory = tempfile::tempdir().unwrap();
+    let started = marker_directory.path().join("started.jsonl");
+    let completed = marker_directory.path().join("completed.jsonl");
+    let (cache, runtime) = setup(
+        vec![
+            (
+                "fault",
+                serde_json::json!({
+                    "observation_label":"fault",
+                    "observation_started_marker":started,
+                    "observation_marker":completed,
+                    "observation_fault":true,
+                }),
+                vec![binding(REQUEST_LIFECYCLE_CONTRIBUTION, 1)],
+            ),
+            (
+                "timeout",
+                serde_json::json!({
+                    "observation_label":"timeout",
+                    "observation_started_marker":started,
+                    "observation_marker":completed,
+                    "observation_delay_ms":2500,
+                }),
+                vec![binding(REQUEST_LIFECYCLE_CONTRIBUTION, 2)],
+            ),
+        ],
+        RpcLimits::default(),
+    )
+    .await;
+    let generation = gateway_core::runtime::extensions::ExtensionPreparationPort::prepare(
+        &runtime,
+        ConfigRevision::new(1).unwrap(),
+    )
+    .await
+    .unwrap();
+    let plan = runtime.observer_registry().resolve(&generation).unwrap();
+    plan.dispatch(
+        generation.clone(),
+        observation("req_failure", RequestObservationOutcome::Succeeded)
+            .with_provider(ProviderKind::new("openai").unwrap()),
+    );
+    let started_lines = wait_for_lines(&started, 2).await;
+    assert_eq!(started_lines[0]["label"], "fault");
+    assert_eq!(started_lines[1]["label"], "timeout");
+    tokio::time::sleep(Duration::from_millis(2100)).await;
+    let completed_lines = wait_for_lines(&completed, 1).await;
+    assert_eq!(completed_lines.len(), 1);
+    assert_eq!(completed_lines[0]["label"], "fault");
+    assert!(generation.is_ready(), "观察错误与超时不能击穿插件会话");
+    drop(plan);
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn invalid_observer_stage_policy_and_mixed_order_are_rejected_before_publish() {
+    let mut invalid_stage = binding(REQUEST_LIFECYCLE_CONTRIBUTION, 1);
+    invalid_stage.stage = "routing".into();
+    let mut invalid_policy = binding(REQUEST_LIFECYCLE_CONTRIBUTION, 1);
+    invalid_policy.failure_policy = PluginFailurePolicy::Reject;
+    let mut invalid_websocket_stage = binding(WEB_SOCKET_OBSERVER_CONTRIBUTION, 1);
+    invalid_websocket_stage.stage = "stream".into();
+    let mut invalid_websocket_policy = binding(WEB_SOCKET_OBSERVER_CONTRIBUTION, 1);
+    invalid_websocket_policy.failure_policy = PluginFailurePolicy::Delegate;
+    for bindings in [
+        vec![invalid_stage],
+        vec![invalid_policy],
+        vec![invalid_websocket_stage],
+        vec![invalid_websocket_policy],
+        vec![
+            binding(REQUEST_LIFECYCLE_CONTRIBUTION, 1),
+            binding(USAGE_CONTRIBUTION, 2),
+        ],
+        vec![
+            binding(USAGE_CONTRIBUTION, 1),
+            binding(WEB_SOCKET_OBSERVER_CONTRIBUTION, 2),
+        ],
+    ] {
+        let (_cache, runtime) = setup(
+            vec![("invalid", serde_json::json!({}), bindings)],
+            RpcLimits::default(),
+        )
+        .await;
+        assert!(
+            gateway_core::runtime::extensions::ExtensionPreparationPort::prepare(
+                &runtime,
+                ConfigRevision::new(1).unwrap(),
+            )
+            .await
+            .is_err()
+        );
+    }
+}
+
+#[tokio::test]
+async fn client_scope_filters_observations_and_exposes_only_the_key_identifier() {
+    let marker_directory = tempfile::tempdir().unwrap();
+    let marker = marker_directory.path().join("scoped-observations.jsonl");
+    let matching_group = "grp_11111111111111111111111111111111";
+    let other_group = "grp_22222222222222222222222222222222";
+    let mut scoped = binding(USAGE_CONTRIBUTION, 1);
+    scoped.client_key_ids = vec!["client-key-observed".into()];
+    scoped.account_group_ids = vec![matching_group.into()];
+    scoped.provider_ids.clear();
+    let (cache, runtime) = setup(
+        vec![(
+            "scoped",
+            serde_json::json!({"observation_label":"scoped","observation_marker":marker}),
+            vec![scoped],
+        )],
+        RpcLimits::default(),
+    )
+    .await;
+    let generation = gateway_core::runtime::extensions::ExtensionPreparationPort::prepare(
+        &runtime,
+        ConfigRevision::new(1).unwrap(),
+    )
+    .await
+    .unwrap();
+    let plan = runtime.observer_registry().resolve(&generation).unwrap();
+
+    plan.dispatch(
+        generation.clone(),
+        observation("req_scope_match", RequestObservationOutcome::Rejected).with_client_scope(
+            ClientApiKeyId::new("client-key-observed").unwrap(),
+            vec![AccountGroupId::new(matching_group).unwrap()],
+        ),
+    );
+    let lines = wait_for_lines(&marker, 1).await;
+    assert_eq!(lines[0]["observation"]["request_id"], "req_scope_match");
+    assert!(lines[0]["observation"].get("terminal").is_none());
+    assert_eq!(
+        lines[0]["observation"]["usage"]["failure"]["outcome"],
+        "rejected"
+    );
+    assert_eq!(
+        lines[0]["observation"]["usage"]["failure"]["send_state"],
+        "not_sent"
+    );
+    assert_eq!(
+        lines[0]["observation"]["usage"]["cost"]["status"],
+        "unknown"
+    );
+    let wire = lines[0]["observation"].to_string();
+    assert_eq!(
+        lines[0]["observation"]["client_key_id"],
+        "client-key-observed"
+    );
+    assert!(!wire.contains(matching_group));
+
+    for (request_id, key, groups) in [
+        (
+            "req_key_miss",
+            "client-key-other",
+            vec![AccountGroupId::new(matching_group).unwrap()],
+        ),
+        (
+            "req_group_miss",
+            "client-key-observed",
+            vec![AccountGroupId::new(other_group).unwrap()],
+        ),
+        ("req_all_accounts_miss", "client-key-observed", vec![]),
+    ] {
+        plan.dispatch(
+            generation.clone(),
+            observation(request_id, RequestObservationOutcome::Rejected)
+                .with_client_scope(ClientApiKeyId::new(key).unwrap(), groups),
+        );
+    }
+    tokio::time::sleep(Duration::from_millis(100)).await;
+    assert_eq!(wait_for_lines(&marker, 1).await.len(), 1);
+    drop(plan);
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn usage_observation_contains_final_cost_timings_and_safe_failure_only() {
+    let marker_directory = tempfile::tempdir().unwrap();
+    let marker = marker_directory.path().join("usage-observations.jsonl");
+    let (cache, runtime) = setup(
+        vec![(
+            "usage",
+            serde_json::json!({"observation_label":"usage","observation_marker":marker}),
+            vec![binding(USAGE_CONTRIBUTION, 1)],
+        )],
+        RpcLimits::default(),
+    )
+    .await;
+    let generation = gateway_core::runtime::extensions::ExtensionPreparationPort::prepare(
+        &runtime,
+        ConfigRevision::new(1).unwrap(),
+    )
+    .await
+    .unwrap();
+    let plan = runtime.observer_registry().resolve(&generation).unwrap();
+    plan.dispatch(
+        generation.clone(),
+        observation("req_usage_failure", RequestObservationOutcome::Failed)
+            .with_provider(ProviderKind::new("openai").unwrap())
+            .with_attempt_count(2)
+            .with_client_status_code(502)
+            .with_upstream_status_code(503)
+            .with_error_kind(GatewayErrorKind::UpstreamUnavailable)
+            .with_retry_after_ms(1_500)
+            .with_cost(
+                ProviderReportedCost::from_usd_ticks(123_000_000)
+                    .unwrap()
+                    .into_estimate(),
+            )
+            .with_timings(ModelRequestTimings {
+                first_text_ms: Some(12),
+                latency_ms: Some(34),
+                ..ModelRequestTimings::default()
+            }),
+    );
+    let lines = wait_for_lines(&marker, 1).await;
+    let observed = &lines[0]["observation"];
+    assert!(observed.get("terminal").is_none());
+    assert_eq!(observed["usage"]["cost"]["status"], "known");
+    assert_eq!(observed["usage"]["cost"]["source"], "provider_reported");
+    assert_eq!(observed["usage"]["cost"]["total"]["amount"], "0.0123");
+    assert_eq!(observed["usage"]["cost"]["total"]["currency"], "USD");
+    assert_eq!(observed["usage"]["timings"]["first_text_ms"], 12);
+    assert_eq!(observed["usage"]["timings"]["latency_ms"], 34);
+    assert_eq!(observed["usage"]["failure"]["outcome"], "failed");
+    assert_eq!(observed["usage"]["failure"]["attempt_count"], 2);
+    assert_eq!(observed["usage"]["failure"]["client_status_code"], 502);
+    assert_eq!(observed["usage"]["failure"]["upstream_status_code"], 503);
+    assert_eq!(
+        observed["usage"]["failure"]["error_code"],
+        "upstream_unavailable"
+    );
+    assert_eq!(observed["usage"]["failure"]["retry_after_ms"], 1_500);
+    let wire = observed["usage"]["failure"].to_string();
+    assert!(!wire.contains("message"));
+    assert!(!wire.contains("raw_upstream_error"));
+    assert!(!wire.contains("provider_error_code"));
+    drop(plan);
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn invalid_client_key_and_group_scopes_are_rejected_before_publish() {
+    let mut duplicate_keys = binding(USAGE_CONTRIBUTION, 1);
+    duplicate_keys.client_key_ids = vec!["client-key".into(), "client-key".into()];
+    let mut invalid_group = binding(USAGE_CONTRIBUTION, 1);
+    invalid_group.account_group_ids = vec!["not-a-group".into()];
+    let mut duplicate_groups = binding(USAGE_CONTRIBUTION, 1);
+    duplicate_groups.account_group_ids = vec![
+        "grp_33333333333333333333333333333333".into(),
+        "grp_33333333333333333333333333333333".into(),
+    ];
+    for bindings in [
+        vec![duplicate_keys],
+        vec![invalid_group],
+        vec![duplicate_groups],
+    ] {
+        let (_cache, runtime) = setup(
+            vec![("invalid-scope", serde_json::json!({}), bindings)],
+            RpcLimits::default(),
+        )
+        .await;
+        assert!(
+            gateway_core::runtime::extensions::ExtensionPreparationPort::prepare(
+                &runtime,
+                ConfigRevision::new(1).unwrap(),
+            )
+            .await
+            .is_err()
+        );
+    }
+}
+
+#[tokio::test]
+async fn observer_backpressure_drops_excess_and_inflight_dispatch_keeps_generation_alive() {
+    let marker_directory = tempfile::tempdir().unwrap();
+    let started = marker_directory.path().join("started.jsonl");
+    let completed = marker_directory.path().join("completed.jsonl");
+    let limits = RpcLimits {
+        maximum_calls: 1,
+        ..RpcLimits::default()
+    };
+    let (cache, runtime) = setup(
+        vec![(
+            "slow",
+            serde_json::json!({
+                "observation_label":"slow",
+                "observation_started_marker":started,
+                "observation_marker":completed,
+                "observation_delay_ms":200,
+            }),
+            vec![binding(REQUEST_LIFECYCLE_CONTRIBUTION, 1)],
+        )],
+        limits,
+    )
+    .await;
+    let generation = gateway_core::runtime::extensions::ExtensionPreparationPort::prepare(
+        &runtime,
+        ConfigRevision::new(1).unwrap(),
+    )
+    .await
+    .unwrap();
+    let plan = runtime.observer_registry().resolve(&generation).unwrap();
+    plan.dispatch(
+        generation.clone(),
+        observation("req_first", RequestObservationOutcome::Succeeded)
+            .with_provider(ProviderKind::new("openai").unwrap()),
+    );
+    wait_for_lines(&started, 1).await;
+    plan.dispatch(
+        generation.clone(),
+        observation("req_excess", RequestObservationOutcome::Succeeded)
+            .with_provider(ProviderKind::new("openai").unwrap()),
+    );
+    drop(plan);
+    drop(generation);
+
+    let completed = wait_for_lines(&completed, 1).await;
+    assert_eq!(completed.len(), 1);
+    assert_eq!(
+        completed[0]["observation"]["request_id"], "req_first",
+        "try-acquire backpressure must not queue a second observation"
+    );
+    super::wait_until_empty(cache.path()).await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/generation/observer_example.rs b/backend/crates/gateway-plugin/runtime/tests/generation/observer_example.rs
new file mode 100644
index 000000000..ed5af41db
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/generation/observer_example.rs
@@ -0,0 +1,290 @@
+use std::{
+    collections::BTreeMap,
+    num::NonZeroU32,
+    sync::{Arc, Mutex},
+    time::Duration,
+};
+
+use gateway_admin::{
+    model::{
+        Revision,
+        plugins::instances::{
+            PluginCapabilityBinding, PluginFailurePolicy, PluginInstance, PluginInstanceSnapshot,
+            PluginPermissionGrant,
+        },
+    },
+    ports::plugins::PluginPackageInspector,
+};
+use gateway_core::{
+    account::ProviderAccountId,
+    diagnostics::diagnostic_json,
+    engine::{
+        ModelRequestId,
+        observation::{WebSocketResponseAttempt, WebSocketResponseObservation},
+        provider::ProviderRegistry,
+    },
+    event::ProtocolWireEvent,
+    identity::ProviderKind,
+    operation::OperationKind,
+    policy::ClientApiKeyId,
+    routing::{ConfigRevision, PublicModelId},
+    runtime::extensions::{ExtensionPreparationPort, ExtensionSetReference},
+};
+use gateway_plugin_runtime::{
+    PackageInspector, PackageLimits, PluginRuntime, PluginRuntimeConfig, RpcLimits,
+};
+use serde_json::{Value, json};
+
+use crate::support::store::Store;
+
+#[derive(Clone, Default)]
+struct Capture(Arc<Mutex<Vec<BTreeMap<String, String>>>>);
+
+struct Fields(BTreeMap<String, String>);
+
+impl tracing::field::Visit for Fields {
+    fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn std::fmt::Debug) {
+        self.0.insert(field.name().to_owned(), format!("{value:?}"));
+    }
+}
+
+impl tracing::Subscriber for Capture {
+    fn enabled(&self, metadata: &tracing::Metadata<'_>) -> bool {
+        metadata.target() == "gateway_plugin"
+    }
+    fn new_span(&self, _: &tracing::span::Attributes<'_>) -> tracing::span::Id {
+        tracing::span::Id::from_u64(1)
+    }
+    fn record(&self, _: &tracing::span::Id, _: &tracing::span::Record<'_>) {}
+    fn record_follows_from(&self, _: &tracing::span::Id, _: &tracing::span::Id) {}
+    fn enter(&self, _: &tracing::span::Id) {}
+    fn exit(&self, _: &tracing::span::Id) {}
+    fn event(&self, event: &tracing::Event<'_>) {
+        if event.metadata().target() == "gateway_plugin" {
+            let mut fields = Fields(BTreeMap::new());
+            event.record(&mut fields);
+            self.0.lock().unwrap().push(fields.0);
+        }
+    }
+}
+
+impl Capture {
+    async fn wait_for(&self, count: usize) {
+        tokio::time::timeout(Duration::from_secs(5), async {
+            while self.0.lock().unwrap().len() < count {
+                tokio::time::sleep(Duration::from_millis(10)).await;
+            }
+        })
+        .await
+        .expect("independent observer log callback must complete");
+    }
+
+    fn assert_summary(&self, instance: &str, generation: u64, expected: Value) {
+        let logs = self.0.lock().unwrap();
+        let row = logs
+            .iter()
+            .rev()
+            .find(|row| {
+                row["instance_id"] == instance && row["generation"] == generation.to_string()
+            })
+            .expect("observer generation summary");
+        assert_eq!(
+            serde_json::from_str::<Value>(&row["fields"]).unwrap(),
+            diagnostic_json(&expected)
+        );
+        assert!(!row["fields"].contains("fixture-private-payload"));
+    }
+}
+
+fn grant(permission: &str) -> PluginPermissionGrant {
+    PluginPermissionGrant {
+        permission: permission.to_owned(),
+    }
+}
+
+fn binding(contribution: &str) -> PluginCapabilityBinding {
+    PluginCapabilityBinding {
+        contribution: contribution.to_owned(),
+        stage: "observation".to_owned(),
+        order: 1,
+        failure_policy: PluginFailurePolicy::Observe,
+        client_key_ids: Vec::new(),
+        account_group_ids: Vec::new(),
+        provider_ids: vec!["openai".to_owned()],
+        models: vec!["gpt-observed".to_owned()],
+        identity_bindings: Vec::new(),
+    }
+}
+
+async fn runtime(cache: &std::path::Path) -> (Arc<Store>, PluginRuntime) {
+    let inspector = PackageInspector::new(PackageLimits::default(), "3.12.1".parse().unwrap());
+    let mut artifacts = BTreeMap::new();
+    let mut instances = Vec::new();
+    for (variable, plugin, permissions) in [
+        (
+            "CPR_PLUGIN_WS_COUNTER_ARCHIVE",
+            "example-ws-event-counter",
+            vec![],
+        ),
+        (
+            "CPR_PLUGIN_WS_METRICS_ARCHIVE",
+            "example-ws-payload-metrics",
+            vec![grant("requests")],
+        ),
+    ] {
+        let path = std::env::var_os(variable).unwrap_or_else(|| {
+            panic!("{variable} must point to a packaged independent SDK example")
+        });
+        let archive = std::fs::read(path).expect("independent observer archive");
+        let artifact = inspector.inspect(archive.into(), None).await.unwrap();
+        assert_eq!(artifact.metadata.plugin_id, plugin);
+        let contribution = artifact.metadata.contributes["web_socket_observer"]
+            .id
+            .clone();
+        instances.push(PluginInstance {
+            id: plugin.to_owned(),
+            name: plugin.to_owned(),
+            artifact_sha256: artifact.metadata.sha256.clone(),
+            enabled: true,
+            trusted_process: true,
+            configuration: json!({}),
+            secrets: BTreeMap::new(),
+            grants: permissions,
+            bindings: vec![binding(&contribution)],
+            revision: Revision::new(1).unwrap(),
+        });
+        artifacts.insert(artifact.metadata.sha256.clone(), artifact);
+    }
+    let store = Arc::new(Store {
+        artifacts,
+        snapshot: Mutex::new(PluginInstanceSnapshot {
+            config_revision: Revision::new(1).unwrap(),
+            instances,
+        }),
+    });
+    let runtime = PluginRuntime::new(
+        store.clone(),
+        store.clone(),
+        PluginRuntimeConfig {
+            cache_directory: cache.to_owned(),
+            host_version: "3.12.1".parse().unwrap(),
+            package_limits: PackageLimits::default(),
+            rpc_limits: RpcLimits::default(),
+            continuation_drain: Default::default(),
+            restart_circuit: Default::default(),
+        },
+        ProviderRegistry::default(),
+        gateway_admin::ports::provider::ProviderAdminRegistry::new([]).unwrap(),
+        Arc::new(gateway_host::outbound::HttpClient::new().unwrap()),
+        Arc::new(gateway_host::process::ProcessSupervisor::new(
+            std::num::NonZeroUsize::new(8).unwrap(),
+        )),
+    );
+    (store, runtime)
+}
+
+fn observation(
+    generation: u64,
+    sequence: u64,
+    model: &str,
+    body: &Value,
+) -> WebSocketResponseObservation {
+    WebSocketResponseObservation::new(
+        ModelRequestId::new("req_observer_example").unwrap(),
+        ConfigRevision::new(generation).unwrap(),
+        OperationKind::Generate,
+        WebSocketResponseAttempt::new(
+            ProviderKind::new("openai").unwrap(),
+            ProviderAccountId::new("acct_observed").unwrap(),
+            NonZeroU32::new(1).unwrap(),
+        ),
+        sequence,
+        ProtocolWireEvent::json(
+            "openai",
+            body["type"].as_str().map(str::to_owned),
+            body.clone(),
+        )
+        .unwrap(),
+    )
+    .with_client_scope(
+        ClientApiKeyId::new("key_observer_example").unwrap(),
+        Vec::new(),
+    )
+    .with_requested_model(PublicModelId::new(model).unwrap())
+}
+
+fn dispatch(
+    runtime: &PluginRuntime,
+    generation: &ExtensionSetReference,
+    revision: u64,
+    sequence: u64,
+    model: &str,
+    body: &Value,
+) {
+    runtime
+        .observer_registry()
+        .resolve(generation)
+        .unwrap()
+        .dispatch_websocket_response(
+            generation.clone(),
+            observation(revision, sequence, model, body),
+        );
+}
+
+/// 必须单独按名称显式执行；真实包缺失时报错，不将未运行的依赖场景算作通过。
+#[tokio::test]
+#[ignore = "requires two packaged standalone observer examples and an isolated log subscriber"]
+async fn actual_observer_examples_share_runtime_contract_with_separate_permissions_and_generations()
+{
+    let capture = Capture::default();
+    tracing::subscriber::set_global_default(capture.clone()).unwrap();
+    let cache = tempfile::tempdir().unwrap();
+    let (store, runtime) = runtime(cache.path()).await;
+    let first = ExtensionPreparationPort::prepare(&runtime, ConfigRevision::new(1).unwrap())
+        .await
+        .unwrap();
+    let body = json!({"type":"response.output_text.delta","delta":"fixture-private-payload 中文","unknown":true});
+    let bytes = serde_json::to_vec(&body).unwrap().len();
+    let text_bytes = body["delta"].as_str().unwrap().len();
+    dispatch(&runtime, &first, 1, 1, "gpt-observed", &body);
+    capture.wait_for(2).await;
+    dispatch(&runtime, &first, 1, 2, "other-model", &body);
+    dispatch(&runtime, &first, 1, 9, "gpt-observed", &body);
+    capture.wait_for(4).await;
+    capture.assert_summary(
+        "example-ws-event-counter",
+        1,
+        json!({"events":2,"first_events":1,"maximum_sequence":9}),
+    );
+    capture.assert_summary("example-ws-payload-metrics", 1, json!({"delivered_events":2,"payload_bytes":bytes*2,"text_delta_bytes":text_bytes*2,"terminal_events":0}));
+    {
+        let mut snapshot = store.snapshot.lock().unwrap();
+        snapshot.config_revision = Revision::new(2).unwrap();
+        for instance in &mut snapshot.instances {
+            instance.revision = Revision::new(2).unwrap();
+        }
+    }
+    let second = ExtensionPreparationPort::prepare(&runtime, ConfigRevision::new(2).unwrap())
+        .await
+        .unwrap();
+    dispatch(&runtime, &second, 2, 1, "gpt-observed", &body);
+    dispatch(&runtime, &first, 1, 10, "gpt-observed", &body);
+    capture.wait_for(8).await;
+    capture.assert_summary(
+        "example-ws-event-counter",
+        2,
+        json!({"events":1,"first_events":1,"maximum_sequence":1}),
+    );
+    capture.assert_summary(
+        "example-ws-event-counter",
+        1,
+        json!({"events":3,"first_events":1,"maximum_sequence":10}),
+    );
+    capture.assert_summary("example-ws-payload-metrics", 2, json!({"delivered_events":1,"payload_bytes":bytes,"text_delta_bytes":text_bytes,"terminal_events":0}));
+    capture.assert_summary("example-ws-payload-metrics", 1, json!({"delivered_events":3,"payload_bytes":bytes*3,"text_delta_bytes":text_bytes*3,"terminal_events":0}));
+    assert_eq!(capture.0.lock().unwrap().len(), 8);
+    runtime.shutdown().await;
+    drop(first);
+    drop(second);
+    super::wait_until_empty(cache.path()).await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/generation/policy.rs b/backend/crates/gateway-plugin/runtime/tests/generation/policy.rs
new file mode 100644
index 000000000..7f9321829
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/generation/policy.rs
@@ -0,0 +1,1149 @@
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    num::{NonZeroU32, NonZeroUsize},
+    sync::{
+        Arc,
+        atomic::{AtomicUsize, Ordering},
+    },
+    time::{Duration, SystemTime},
+};
+
+use bytes::Bytes;
+use futures::future::BoxFuture;
+use gateway_admin::{
+    model::{
+        Revision,
+        plugins::instances::{
+            PluginCapabilityBinding, PluginFailurePolicy, PluginInstance, PluginInstanceSnapshot,
+            PluginPermissionGrant,
+        },
+    },
+    ports::plugins::PluginPackageInspector,
+};
+use gateway_core::{
+    account::{
+        AccountCandidate, AccountEligibilityPolicy, AccountRuntimeSignals, AccountSelectionContext,
+        AccountSelectionPolicy, AccountWeight, CredentialRevision, CredentialState,
+        ProviderAccount, ProviderAccountId, QuotaState, RotationStrategy,
+    },
+    engine::{
+        ModelRequestId,
+        execution::ClientTransport,
+        extensions::ExtensionCallScope,
+        middleware::{
+            MiddlewareAuthority, MiddlewareBody, MiddlewareContext, MiddlewareError,
+            MiddlewareFrame, MiddlewareFraming, MiddlewareHeader, MiddlewareMount, MiddlewareNext,
+            MiddlewareRequest, MiddlewareResponse, MiddlewareTarget,
+        },
+        nested::ExecutionEffects,
+        policy::{ModelRouteDecision, RequestPolicyContext},
+        provider::ProviderRegistry,
+    },
+    identity::ProviderKind,
+    lifecycle::CancellationToken,
+    operation::{GenerateRequest, Operation, OperationKind, ProtocolPayload},
+    policy::ClientApiKeyId,
+    routing::{AccountGroupId, ConfigRevision, PublicModelId},
+    runtime::extensions::{ExtensionPreparationPort, ExtensionSetReference},
+};
+use gateway_plugin_runtime::{
+    PackageInspector, PackageLimits, PluginRuntime, PluginRuntimeConfig, RpcLimits,
+};
+use gateway_plugin_sdk::{Capability, Contributions, Permission, Stage};
+use wiremock::{Mock, MockServer, ResponseTemplate, matchers::any};
+
+use crate::support::{
+    environment::{Environment, account_grant},
+    store::Store,
+};
+
+struct InstanceFixture {
+    id: &'static str,
+    configuration: serde_json::Value,
+    grants: Vec<PluginPermissionGrant>,
+    bindings: Vec<PluginCapabilityBinding>,
+}
+
+const MODEL_ROUTER_CONTRIBUTION: &str = "test.example.modelRouter";
+const SCHEDULER_CONTRIBUTION: &str = "test.example.scheduler";
+const MIDDLEWARE_CONTRIBUTION: &str = "test.example.middleware";
+
+fn binding(
+    contribution: &str,
+    stage: &str,
+    order: i32,
+    failure_policy: PluginFailurePolicy,
+) -> PluginCapabilityBinding {
+    PluginCapabilityBinding {
+        contribution: contribution.into(),
+        stage: stage.into(),
+        order,
+        failure_policy,
+        client_key_ids: vec![],
+        account_group_ids: vec![],
+        provider_ids: vec![],
+        models: vec![],
+        identity_bindings: vec![],
+    }
+}
+
+fn grant(permission: Permission) -> PluginPermissionGrant {
+    PluginPermissionGrant {
+        permission: permission.as_str().to_owned(),
+    }
+}
+
+async fn setup(
+    instances: Vec<InstanceFixture>,
+    manifest_permissions: Vec<Permission>,
+) -> (tempfile::TempDir, PluginRuntime) {
+    let contributes = Contributions::from([
+        crate::support::contribution(
+            Capability::ModelRouter,
+            vec![Stage::Routing],
+            vec![],
+            vec![],
+        ),
+        crate::support::contribution(
+            Capability::Scheduler,
+            vec![Stage::Scheduling],
+            vec![],
+            vec![],
+        ),
+        crate::support::contribution(
+            Capability::Middleware,
+            vec![Stage::Request, Stage::Attempt],
+            vec!["openai".into()],
+            vec!["openai".into()],
+        ),
+    ]);
+    setup_package(
+        instances,
+        crate::support::package_with_contributions(
+            crate::support::worker(),
+            manifest_permissions,
+            contributes,
+        ),
+    )
+    .await
+}
+
+async fn setup_package(
+    instances: Vec<InstanceFixture>,
+    package: Arc<[u8]>,
+) -> (tempfile::TempDir, PluginRuntime) {
+    let cache = tempfile::tempdir().unwrap();
+    let artifact = PackageInspector::new(PackageLimits::default(), "1.0.0".parse().unwrap())
+        .inspect(package, None)
+        .await
+        .unwrap();
+    let digest = artifact.metadata.sha256.clone();
+    let instances = instances
+        .into_iter()
+        .map(|fixture| PluginInstance {
+            id: fixture.id.into(),
+            name: fixture.id.into(),
+            artifact_sha256: digest.clone(),
+            enabled: true,
+            trusted_process: true,
+            configuration: fixture.configuration,
+            secrets: BTreeMap::new(),
+            grants: fixture.grants,
+            bindings: fixture.bindings,
+            revision: Revision::new(1).unwrap(),
+        })
+        .collect();
+    let store = Arc::new(Store {
+        artifacts: BTreeMap::from([(digest, artifact)]),
+        snapshot: std::sync::Mutex::new(PluginInstanceSnapshot {
+            config_revision: Revision::new(1).unwrap(),
+            instances,
+        }),
+    });
+    let runtime = PluginRuntime::new(
+        store.clone(),
+        store,
+        PluginRuntimeConfig {
+            cache_directory: cache.path().to_owned(),
+            host_version: "1.0.0".parse().unwrap(),
+            package_limits: PackageLimits::default(),
+            rpc_limits: RpcLimits::default(),
+            continuation_drain: Default::default(),
+            restart_circuit: Default::default(),
+        },
+        ProviderRegistry::default(),
+        gateway_admin::ports::provider::ProviderAdminRegistry::new([]).unwrap(),
+        Arc::new(gateway_host::outbound::HttpClient::new().unwrap()),
+        Arc::new(gateway_host::process::ProcessSupervisor::new(
+            NonZeroUsize::new(32).unwrap(),
+        )),
+    )
+    .with_network_policy(
+        gateway_host::outbound::NetworkPolicy::new(&["127.0.0.0/8".into(), "::1/128".into()])
+            .unwrap(),
+    );
+    (cache, runtime)
+}
+
+async fn prepare(runtime: &PluginRuntime) -> ExtensionSetReference {
+    ExtensionPreparationPort::prepare(runtime, ConfigRevision::new(1).unwrap())
+        .await
+        .unwrap()
+}
+
+fn policy_context(
+    runtime: &PluginRuntime,
+    generation: ExtensionSetReference,
+    request_id: &str,
+) -> RequestPolicyContext {
+    RequestPolicyContext::new(
+        runtime.policy_registry().resolve(&generation).unwrap(),
+        generation,
+        ModelRequestId::new(request_id).unwrap(),
+        ClientApiKeyId::new("key-policy").unwrap(),
+        Vec::new(),
+    )
+}
+
+fn operation() -> Operation {
+    let context = serde_json::json!({
+        "opaque_request_headers": [
+            ["x-feature", "b24="],
+            ["authorization", "c2VjcmV0"],
+        ]
+    })
+    .as_object()
+    .unwrap()
+    .clone();
+    Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "openai",
+            serde_json::json!({"model":"public-a","input":"synthetic"})
+                .as_object()
+                .unwrap()
+                .clone(),
+        )
+        .unwrap()
+        .with_context(context),
+    ))
+}
+
+async fn marker_lines(path: &std::path::Path, count: usize) -> Vec<serde_json::Value> {
+    tokio::time::timeout(Duration::from_secs(3), async {
+        loop {
+            let lines = std::fs::read_to_string(path)
+                .unwrap_or_default()
+                .lines()
+                .map(|line| serde_json::from_str(line).unwrap())
+                .collect::<Vec<_>>();
+            if lines.len() >= count {
+                return lines;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .expect("plugin marker")
+}
+
+#[tokio::test]
+async fn model_router_preserves_order_and_only_projects_authorized_request_data() {
+    let markers = tempfile::tempdir().unwrap();
+    let marker = markers.path().join("routes.jsonl");
+    let (cache, runtime) = setup(
+        vec![
+            InstanceFixture {
+                id: "unhandled",
+                configuration: serde_json::json!({
+                    "route_marker":marker,
+                    "route_decision":{"decision":"unhandled"},
+                }),
+                grants: vec![],
+                bindings: vec![binding(
+                    MODEL_ROUTER_CONTRIBUTION,
+                    "routing",
+                    1,
+                    PluginFailurePolicy::Reject,
+                )],
+            },
+            InstanceFixture {
+                id: "handled",
+                configuration: serde_json::json!({
+                    "route_marker":marker,
+                    "route_decision":{"decision":"route","provider":"openai","model":"public-b"},
+                }),
+                grants: vec![grant(Permission::Requests)],
+                bindings: vec![binding(
+                    MODEL_ROUTER_CONTRIBUTION,
+                    "routing",
+                    2,
+                    PluginFailurePolicy::Reject,
+                )],
+            },
+        ],
+        vec![Permission::Requests],
+    )
+    .await;
+    let generation = prepare(&runtime).await;
+    let context = policy_context(&runtime, generation.clone(), "req_route");
+    let decision = context
+        .route_model(
+            operation(),
+            PublicModelId::new("public-a").unwrap(),
+            BTreeSet::from([
+                ProviderKind::new("openai").unwrap(),
+                ProviderKind::new("example").unwrap(),
+            ]),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        decision,
+        ModelRouteDecision::Route {
+            provider: Some(ProviderKind::new("openai").unwrap()),
+            model: Some(PublicModelId::new("public-b").unwrap()),
+        }
+    );
+    let lines = marker_lines(&marker, 2).await;
+    assert_eq!(lines[0]["body"], "");
+    assert_eq!(lines[0]["request"]["headers"], serde_json::json!([]));
+    assert_eq!(
+        serde_json::from_str::<serde_json::Value>(lines[1]["body"].as_str().unwrap()).unwrap(),
+        serde_json::json!({"model":"public-a","input":"synthetic"})
+    );
+    assert_eq!(
+        lines[1]["request"]["headers"],
+        serde_json::json!([{"name":"x-feature","value_base64":"b24="}])
+    );
+    assert!(!lines[1].to_string().contains("secret"));
+    drop(context);
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn model_router_can_delegate_after_a_managed_http_side_effect() {
+    let server = MockServer::start().await;
+    Mock::given(any())
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"ok":true})))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let (cache, runtime) = setup(
+        vec![
+            InstanceFixture {
+                id: "http-then-fault",
+                configuration: serde_json::json!({
+                    "route_http_url":server.uri(),
+                    "route_fault":true,
+                }),
+                grants: vec![grant(Permission::Network)],
+                bindings: vec![binding(
+                    MODEL_ROUTER_CONTRIBUTION,
+                    "routing",
+                    1,
+                    PluginFailurePolicy::Delegate,
+                )],
+            },
+            InstanceFixture {
+                id: "fallback",
+                configuration: serde_json::json!({
+                    "route_decision":{"decision":"unhandled"},
+                }),
+                grants: vec![],
+                bindings: vec![binding(
+                    MODEL_ROUTER_CONTRIBUTION,
+                    "routing",
+                    2,
+                    PluginFailurePolicy::Reject,
+                )],
+            },
+        ],
+        vec![Permission::Network],
+    )
+    .await;
+    let generation = prepare(&runtime).await;
+    let context = policy_context(&runtime, generation.clone(), "req_route_http");
+    assert_eq!(
+        context
+            .route_model(
+                operation(),
+                PublicModelId::new("public-a").unwrap(),
+                BTreeSet::from([ProviderKind::new("openai").unwrap()]),
+            )
+            .await
+            .unwrap(),
+        ModelRouteDecision::Unhandled
+    );
+    drop(context);
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+fn candidate(id: &str, weight: u16) -> AccountCandidate {
+    AccountCandidate {
+        account: ProviderAccount::new(
+            ProviderAccountId::new(id).unwrap(),
+            ProviderKind::new("example").unwrap(),
+            id.into(),
+            None,
+            "test".into(),
+            CredentialRevision::new(1).unwrap(),
+            Some(SystemTime::now() + Duration::from_secs(60)),
+        )
+        .with_account_facts(
+            true,
+            CredentialState::Ready,
+            QuotaState::unknown(),
+            None,
+            None,
+        )
+        .with_scheduling(None, AccountWeight::new(weight).unwrap()),
+        signals: AccountRuntimeSignals {
+            in_flight: 0,
+            last_started_at: None,
+            quota_reset_at: None,
+            quota_remaining_rank: None,
+            cooldown: None,
+            failure_rate_basis_points: None,
+            first_output_latency_ms: None,
+        },
+    }
+}
+
+fn selection_context() -> AccountSelectionContext {
+    AccountSelectionContext {
+        policy: AccountSelectionPolicy::new(
+            RotationStrategy::RoundRobin,
+            NonZeroU32::new(4).unwrap(),
+            Duration::ZERO,
+        ),
+        now: SystemTime::now(),
+        excluded_accounts: BTreeSet::new(),
+        preferred_account: None,
+        preferred_account_overrides_weight: true,
+        round_robin_cursor: 0,
+        eligibility: AccountEligibilityPolicy::Enforce,
+        account_scope: None,
+    }
+}
+
+#[tokio::test]
+async fn scheduler_cannot_pick_outside_the_host_projected_priority_tier() {
+    let (cache, runtime) = setup(
+        vec![InstanceFixture {
+            id: "scheduler",
+            configuration: serde_json::json!({"schedule_pick_index":0}),
+            grants: vec![],
+            bindings: vec![binding(
+                SCHEDULER_CONTRIBUTION,
+                "scheduling",
+                0,
+                PluginFailurePolicy::Reject,
+            )],
+        }],
+        vec![],
+    )
+    .await;
+    let generation = prepare(&runtime).await;
+    let context = policy_context(&runtime, generation.clone(), "req_schedule");
+    let candidates = [candidate("acct_high", 100), candidate("acct_low", 10)];
+    let selection = selection_context();
+    let selected = context
+        .select_account(
+            NonZeroU32::MIN,
+            &ProviderKind::new("example").unwrap(),
+            Some("upstream-a"),
+            &candidates,
+            &selection,
+        )
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(selected.candidate().account.id().as_str(), "acct_high");
+    drop(context);
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+struct OneFrameBody {
+    frame: Option<MiddlewareFrame>,
+    reads: Arc<AtomicUsize>,
+    closes: Arc<AtomicUsize>,
+}
+
+impl MiddlewareBody for OneFrameBody {
+    fn next_frame(&mut self) -> BoxFuture<'_, Result<Option<MiddlewareFrame>, MiddlewareError>> {
+        Box::pin(async move {
+            self.reads.fetch_add(1, Ordering::Relaxed);
+            Ok(self.frame.take())
+        })
+    }
+
+    fn close(self: Box<Self>) -> BoxFuture<'static, ()> {
+        Box::pin(async move {
+            self.closes.fetch_add(1, Ordering::Relaxed);
+        })
+    }
+}
+
+struct Downstream {
+    calls: Arc<AtomicUsize>,
+    reads: Arc<AtomicUsize>,
+    closes: Arc<AtomicUsize>,
+    error: bool,
+}
+
+impl MiddlewareNext for Downstream {
+    fn run(
+        self: Box<Self>,
+        request: MiddlewareRequest,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        Box::pin(async move {
+            self.calls.fetch_add(1, Ordering::Relaxed);
+            assert_eq!(request.protocol(), "openai");
+            assert_eq!(request.body(), &Bytes::from_static(br#"{"input":"hello"}"#));
+            assert!(request.headers().iter().any(|header| {
+                header.name() == "authorization" && header.value().as_ref() == b"Bearer private"
+            }));
+            assert!(
+                request
+                    .headers()
+                    .iter()
+                    .any(|header| header.name() == "x_team" && header.value().as_ref() == b"team")
+            );
+            let (status, framing, body) = if self.error {
+                (502, MiddlewareFraming::RawBytes, b"\0upstream".as_slice())
+            } else {
+                (
+                    200,
+                    MiddlewareFraming::JsonDocument,
+                    br#"{"downstream":true}"#.as_slice(),
+                )
+            };
+            Ok(MiddlewareResponse::new(
+                "openai".into(),
+                status,
+                vec![
+                    MiddlewareHeader::new("content-type", Bytes::from_static(b"application/json")),
+                    MiddlewareHeader::new("x-upstream-marker", Bytes::from_static(b"kept")),
+                ],
+                Box::new(OneFrameBody {
+                    reads: Arc::clone(&self.reads),
+                    frame: Some(MiddlewareFrame::new(
+                        Bytes::copy_from_slice(body),
+                        framing,
+                        true,
+                    )),
+                    closes: Arc::clone(&self.closes),
+                }),
+            ))
+        })
+    }
+}
+
+fn middleware_context(transport: ClientTransport) -> MiddlewareContext {
+    MiddlewareContext::new(
+        MiddlewareTarget {
+            request_id: ModelRequestId::new("req_middleware").unwrap(),
+            mount: MiddlewareMount::Request,
+            attempt_index: None,
+            operation: Some(OperationKind::Generate),
+            endpoint: "/v1/responses".into(),
+            transport,
+            provider: None,
+            model: Some("public-a".into()),
+            account_id: None,
+        },
+        MiddlewareAuthority {
+            client_key_id: ClientApiKeyId::new("key-middleware").unwrap(),
+            account_group_ids: Arc::<[AccountGroupId]>::from([]),
+            cancellation: CancellationToken::new(),
+            deadline: SystemTime::now() + Duration::from_secs(5),
+            extension_scope: ExtensionCallScope::default(),
+            execution_effects: None,
+        },
+    )
+}
+
+fn attempt_middleware_context(effects: Arc<ExecutionEffects>) -> MiddlewareContext {
+    MiddlewareContext::new(
+        MiddlewareTarget {
+            request_id: ModelRequestId::new("req_attempt_http").unwrap(),
+            mount: MiddlewareMount::Attempt,
+            attempt_index: Some(NonZeroU32::MIN),
+            operation: Some(OperationKind::Generate),
+            endpoint: "/v1/responses".into(),
+            transport: ClientTransport::HttpJson,
+            provider: Some(ProviderKind::new("openai").unwrap()),
+            model: Some("public-a".into()),
+            account_id: Some(ProviderAccountId::new("acct_openai").unwrap()),
+        },
+        MiddlewareAuthority {
+            client_key_id: ClientApiKeyId::new("key-middleware").unwrap(),
+            account_group_ids: Arc::<[AccountGroupId]>::from([]),
+            cancellation: CancellationToken::new(),
+            deadline: SystemTime::now() + Duration::from_secs(5),
+            extension_scope: ExtensionCallScope::default(),
+            execution_effects: Some(effects),
+        },
+    )
+}
+
+fn middleware_headers() -> Vec<MiddlewareHeader> {
+    vec![
+        MiddlewareHeader::new("authorization", Bytes::from_static(b"Bearer private")),
+        MiddlewareHeader::new("connection", Bytes::from_static(b"x-hop")),
+        MiddlewareHeader::new("x-hop", Bytes::from_static(b"hidden")),
+        MiddlewareHeader::new("x_team", Bytes::from_static(b"team")),
+    ]
+}
+
+#[tokio::test]
+async fn attempt_middleware_can_delegate_after_a_managed_http_side_effect() {
+    let server = MockServer::start().await;
+    Mock::given(any())
+        .respond_with(ResponseTemplate::new(204))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let (cache, runtime) = setup(
+        vec![InstanceFixture {
+            id: "attempt-http",
+            configuration: serde_json::json!({
+                "middleware_http_url":server.uri(),
+                "middleware_fault_before_next":true,
+            }),
+            grants: vec![grant(Permission::Network)],
+            bindings: vec![binding(
+                MIDDLEWARE_CONTRIBUTION,
+                "attempt",
+                0,
+                PluginFailurePolicy::Delegate,
+            )],
+        }],
+        vec![Permission::Network],
+    )
+    .await;
+    let generation = prepare(&runtime).await;
+    let plan = runtime
+        .middleware_registry()
+        .resolve(&generation)
+        .expect("middleware plan");
+    let calls = Arc::new(AtomicUsize::new(0));
+    let closes = Arc::new(AtomicUsize::new(0));
+    let effects = Arc::new(ExecutionEffects::default());
+    let response = plan
+        .handle(
+            attempt_middleware_context(effects),
+            MiddlewareRequest::new(
+                "openai",
+                middleware_headers(),
+                Bytes::from_static(br#"{"input":"hello"}"#),
+            ),
+            Box::new(Downstream {
+                calls: Arc::clone(&calls),
+                closes: Arc::clone(&closes),
+                reads: Arc::default(),
+                error: false,
+            }),
+        )
+        .await
+        .unwrap();
+    assert_eq!(calls.load(Ordering::Relaxed), 1);
+    let (_, status, _, body, _) = response.into_parts();
+    assert_eq!(status, 200);
+    body.close().await;
+    drop(plan);
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn middleware_next_and_lazy_body_mapping_use_one_real_rpc_call() {
+    let markers = tempfile::tempdir().unwrap();
+    let marker = markers.path().join("middleware.jsonl");
+    let permissions = vec![Permission::Requests];
+    let (cache, runtime) = setup(
+        vec![InstanceFixture {
+            id: "middleware",
+            configuration: serde_json::json!({
+                "middleware_marker":marker,
+                "middleware_map_body":true,
+            }),
+            grants: permissions.iter().copied().map(grant).collect(),
+            bindings: vec![binding(
+                MIDDLEWARE_CONTRIBUTION,
+                "request",
+                0,
+                PluginFailurePolicy::Reject,
+            )],
+        }],
+        permissions,
+    )
+    .await;
+    let generation = prepare(&runtime).await;
+    let plan = runtime
+        .middleware_registry()
+        .resolve(&generation)
+        .expect("middleware plan");
+    let calls = Arc::new(AtomicUsize::new(0));
+    let closes = Arc::new(AtomicUsize::new(0));
+    let context = middleware_context(ClientTransport::HttpJson);
+    let response = plan
+        .handle(
+            context.clone(),
+            MiddlewareRequest::new(
+                "openai",
+                middleware_headers(),
+                Bytes::from_static(br#"{"input":"hello"}"#),
+            ),
+            Box::new(Downstream {
+                calls: Arc::clone(&calls),
+                closes: Arc::clone(&closes),
+                reads: Arc::default(),
+                error: false,
+            }),
+        )
+        .await
+        .unwrap();
+    assert_eq!(calls.load(Ordering::Relaxed), 1);
+    let (protocol, status, headers, mut body, envelope) = response.into_parts();
+    assert_eq!(protocol, "openai");
+    assert_eq!(status, 200);
+    assert!(headers.iter().any(|header| {
+        header.name() == "content-type" && header.value().as_ref() == b"application/json"
+    }));
+    assert!(envelope.is_none());
+    let frame = body.next_frame().await.unwrap().unwrap();
+    assert_eq!(frame.framing(), MiddlewareFraming::JsonDocument);
+    assert!(frame.terminal());
+    assert!(frame.transformed());
+    assert_eq!(
+        frame.into_bytes(),
+        Bytes::from_static(b"{\"downstream\":true} ")
+    );
+    assert!(body.next_frame().await.unwrap().is_none());
+    let first_marker = &marker_lines(&marker, 1).await[0];
+    assert_eq!(first_marker["body"], "{\"input\":\"hello\"}");
+    assert_eq!(
+        first_marker["headers"],
+        serde_json::json!([{
+            "name":"x_team",
+            "value":[116,101,97,109],
+        }])
+    );
+    body.close().await;
+    tokio::time::timeout(Duration::from_secs(1), async {
+        while closes.load(Ordering::Relaxed) != 1 {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .unwrap();
+
+    let response = plan
+        .handle(
+            context,
+            MiddlewareRequest::new(
+                "openai",
+                middleware_headers(),
+                Bytes::from_static(br#"{"input":"hello"}"#),
+            ),
+            Box::new(Downstream {
+                calls: Arc::clone(&calls),
+                closes: Arc::clone(&closes),
+                reads: Arc::default(),
+                error: false,
+            }),
+        )
+        .await
+        .unwrap();
+    let (_, _, _, body, _) = response.into_parts();
+    body.close().await;
+    tokio::time::timeout(Duration::from_secs(1), async {
+        while closes.load(Ordering::Relaxed) != 2 {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .unwrap();
+    assert_eq!(calls.load(Ordering::Relaxed), 2);
+
+    let response = plan
+        .handle(
+            middleware_context(ClientTransport::HttpSse),
+            MiddlewareRequest::new(
+                "openai",
+                middleware_headers(),
+                Bytes::from_static(br#"{"input":"hello"}"#),
+            ),
+            Box::new(Downstream {
+                calls: Arc::clone(&calls),
+                closes: Arc::clone(&closes),
+                reads: Arc::default(),
+                error: true,
+            }),
+        )
+        .await
+        .unwrap();
+    let (_, status, _, mut body, _) = response.into_parts();
+    assert_eq!(status, 502);
+    let frame = body.next_frame().await.unwrap().unwrap();
+    assert_eq!(frame.framing(), MiddlewareFraming::RawBytes);
+    assert!(frame.transformed());
+    assert_eq!(frame.into_bytes(), Bytes::from_static(b"\0upstream "));
+    body.close().await;
+    tokio::time::timeout(Duration::from_secs(1), async {
+        while closes.load(Ordering::Relaxed) != 3 {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .unwrap();
+    assert_eq!(calls.load(Ordering::Relaxed), 3);
+    drop(plan);
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn middleware_classifies_real_rpc_output_after_a_terminal_frame() {
+    for (id, extra_chunk, terminal_error) in [
+        ("middleware-terminal-chunk", true, false),
+        ("middleware-terminal-error", false, true),
+    ] {
+        let permissions = vec![Permission::Requests];
+        let (cache, runtime) = setup(
+            vec![InstanceFixture {
+                id,
+                configuration: serde_json::json!({
+                    "middleware_map_body": true,
+                    "middleware_chunk_after_terminal": extra_chunk,
+                    "middleware_error_after_terminal": terminal_error,
+                }),
+                grants: permissions.iter().copied().map(grant).collect(),
+                bindings: vec![binding(
+                    MIDDLEWARE_CONTRIBUTION,
+                    "request",
+                    0,
+                    PluginFailurePolicy::Reject,
+                )],
+            }],
+            permissions,
+        )
+        .await;
+        let generation = prepare(&runtime).await;
+        let plan = runtime.middleware_registry().resolve(&generation).unwrap();
+        let calls = Arc::new(AtomicUsize::new(0));
+        let closes = Arc::new(AtomicUsize::new(0));
+        let response = plan
+            .handle(
+                middleware_context(ClientTransport::HttpJson),
+                MiddlewareRequest::new(
+                    "openai",
+                    middleware_headers(),
+                    Bytes::from_static(br#"{"input":"hello"}"#),
+                ),
+                Box::new(Downstream {
+                    calls: Arc::clone(&calls),
+                    closes: Arc::clone(&closes),
+                    reads: Arc::default(),
+                    error: false,
+                }),
+            )
+            .await
+            .unwrap();
+        let (_, _, _, mut body, _) = response.into_parts();
+        let error = body
+            .next_frame()
+            .await
+            .expect_err("output after the terminal frame must fail");
+        let expected = if terminal_error {
+            matches!(&error, MiddlewareError::Fault)
+        } else {
+            matches!(&error, MiddlewareError::InvalidState)
+        };
+        assert!(
+            expected,
+            "unexpected terminal stream error for {id}: {error:?}"
+        );
+        body.close().await;
+        assert_eq!(calls.load(Ordering::Relaxed), 1);
+        drop(plan);
+        drop(generation);
+        super::wait_until_empty(cache.path()).await;
+    }
+}
+
+#[tokio::test]
+async fn sdk_middleware_entry_registers_and_maps_a_real_process_response() {
+    let worker = std::fs::read(env!("CARGO_BIN_EXE_gateway-plugin-test-middleware")).unwrap();
+    let permissions = vec![Permission::Requests];
+    let package = crate::support::package_with_contributions(
+        &worker,
+        permissions.clone(),
+        Contributions::from([crate::support::contribution(
+            Capability::Middleware,
+            vec![Stage::Request],
+            vec!["openai".into()],
+            vec!["openai".into()],
+        )]),
+    );
+    let (cache, runtime) = setup_package(
+        vec![InstanceFixture {
+            id: "sdk-middleware",
+            configuration: serde_json::json!({}),
+            grants: permissions.into_iter().map(grant).collect(),
+            bindings: vec![binding(
+                MIDDLEWARE_CONTRIBUTION,
+                "request",
+                0,
+                PluginFailurePolicy::Reject,
+            )],
+        }],
+        package,
+    )
+    .await;
+    let generation = prepare(&runtime).await;
+    let plan = runtime.middleware_registry().resolve(&generation).unwrap();
+    let calls = Arc::new(AtomicUsize::new(0));
+    let closes = Arc::new(AtomicUsize::new(0));
+    let reads = Arc::new(AtomicUsize::new(0));
+    let response = plan
+        .handle(
+            middleware_context(ClientTransport::HttpJson),
+            MiddlewareRequest::new(
+                "openai",
+                middleware_headers(),
+                Bytes::from_static(br#"{"input":"hello"}"#),
+            ),
+            Box::new(Downstream {
+                calls: Arc::clone(&calls),
+                closes: Arc::clone(&closes),
+                reads: Arc::clone(&reads),
+                error: false,
+            }),
+        )
+        .await
+        .unwrap();
+    let (_, status, headers, mut body, _) = response.into_parts();
+    assert_eq!(status, 200);
+    assert!(
+        headers.iter().any(|header| {
+            header.name() == "x-sdk-plugin" && header.value().as_ref() == b"active"
+        })
+    );
+    tokio::time::timeout(Duration::from_secs(5), async {
+        while reads.load(Ordering::Relaxed) == 0 {
+            tokio::time::sleep(Duration::from_millis(5)).await;
+        }
+    })
+    .await
+    .unwrap();
+    // 模拟慢消费者：SDK 可以继续发起读回调，但宿主不得预读第二个源。
+    tokio::time::sleep(Duration::from_millis(100)).await;
+    assert_eq!(reads.load(Ordering::Relaxed), 1);
+    let frame = body.next_frame().await.unwrap().unwrap();
+    assert!(frame.terminal());
+    assert!(frame.transformed());
+    assert_eq!(
+        frame.into_bytes(),
+        Bytes::from_static(b"{\"downstream\":true} ")
+    );
+    assert!(body.next_frame().await.unwrap().is_none());
+    assert_eq!(reads.load(Ordering::Relaxed), 2);
+    body.close().await;
+    assert_eq!(calls.load(Ordering::Relaxed), 1);
+    tokio::time::timeout(Duration::from_secs(1), async {
+        while closes.load(Ordering::Relaxed) != 1 {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .unwrap();
+    // 尚未消费源帧就关闭，等待源归还的回调必须一起取消并释放下游正文。
+    reads.store(0, Ordering::Relaxed);
+    let response = plan
+        .handle(
+            middleware_context(ClientTransport::HttpJson),
+            MiddlewareRequest::new(
+                "openai",
+                middleware_headers(),
+                Bytes::from_static(br#"{"input":"hello"}"#),
+            ),
+            Box::new(Downstream {
+                calls: Arc::clone(&calls),
+                reads: Arc::clone(&reads),
+                closes: Arc::clone(&closes),
+                error: false,
+            }),
+        )
+        .await
+        .unwrap();
+    let (_, _, _, body, _) = response.into_parts();
+    tokio::time::timeout(Duration::from_secs(5), async {
+        while reads.load(Ordering::Relaxed) == 0 {
+            tokio::time::sleep(Duration::from_millis(5)).await;
+        }
+    })
+    .await
+    .unwrap();
+    tokio::time::sleep(Duration::from_millis(100)).await;
+    assert_eq!(reads.load(Ordering::Relaxed), 1);
+    body.close().await;
+    tokio::time::timeout(Duration::from_secs(1), async {
+        while closes.load(Ordering::Relaxed) != 2 {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .unwrap();
+    assert_eq!(calls.load(Ordering::Relaxed), 2);
+    drop(plan);
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn core_execution_resolves_the_plugin_runtime_middleware_plan() {
+    let Some(environment) = Environment::create().await else {
+        return;
+    };
+    let marker = environment.directory.path().join("core-middleware.jsonl");
+    environment
+        .install_provider(
+            serde_json::json!({"middleware_marker": marker}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let key_secret = "sk-core-middleware-fixture";
+    environment
+        .client_key("key_core_middleware", key_secret)
+        .await;
+
+    let (runtime, core) = environment.runtime().await;
+    let execution = core.execution_service();
+    let client = execution.authenticate(key_secret).unwrap();
+    let prepared = execution.prepare_execution(client).await.unwrap();
+    assert!(execution.middleware_plan(&prepared).is_some());
+
+    environment.release_plugin_accounts(&runtime);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn instances_without_data_plane_bindings_publish_neither_plan() {
+    let (cache, runtime) = setup(
+        vec![InstanceFixture {
+            id: "unbound",
+            configuration: serde_json::json!({}),
+            grants: vec![],
+            bindings: vec![],
+        }],
+        vec![],
+    )
+    .await;
+    let generation = prepare(&runtime).await;
+    assert!(runtime.policy_registry().resolve(&generation).is_none());
+    assert!(runtime.middleware_registry().resolve(&generation).is_none());
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn a_failed_plugin_rejects_only_its_bound_models_and_preserves_delegate_policy() {
+    for failure_policy in [PluginFailurePolicy::Reject, PluginFailurePolicy::Delegate] {
+        let mut mount = binding(
+            MODEL_ROUTER_CONTRIBUTION,
+            "routing",
+            0,
+            failure_policy.clone(),
+        );
+        mount.models = vec!["plugin-required".into()];
+        let (cache, runtime) = setup(
+            vec![InstanceFixture {
+                id: "failed-router",
+                configuration: serde_json::json!({"startup":"fail"}),
+                grants: vec![],
+                bindings: vec![mount],
+            }],
+            vec![],
+        )
+        .await;
+        let generation = prepare(&runtime).await;
+        let context = policy_context(&runtime, generation.clone(), "req_isolated_failure");
+        let unrelated = context
+            .route_model(
+                operation(),
+                PublicModelId::new("unrelated-model").unwrap(),
+                BTreeSet::new(),
+            )
+            .await;
+        assert_eq!(unrelated.unwrap(), ModelRouteDecision::Unhandled);
+        let required = context
+            .route_model(
+                operation(),
+                PublicModelId::new("plugin-required").unwrap(),
+                BTreeSet::new(),
+            )
+            .await;
+        if failure_policy == PluginFailurePolicy::Reject {
+            assert!(required.is_err());
+        } else {
+            assert_eq!(required.unwrap(), ModelRouteDecision::Unhandled);
+        }
+        drop(context);
+        drop(generation);
+        super::wait_until_empty(cache.path()).await;
+    }
+}
+
+#[tokio::test]
+async fn a_failed_middleware_preserves_scope_and_the_configured_failure_policy() {
+    for (model, failure_policy, expected_calls) in [
+        ("unrelated", PluginFailurePolicy::Reject, 1),
+        ("public-a", PluginFailurePolicy::Reject, 0),
+        ("public-a", PluginFailurePolicy::Delegate, 1),
+    ] {
+        let mut mount = binding(MIDDLEWARE_CONTRIBUTION, "request", 0, failure_policy);
+        mount.models = vec![model.into()];
+        let (cache, runtime) = setup(
+            vec![InstanceFixture {
+                id: "failed-middleware",
+                configuration: serde_json::json!({"startup":"fail"}),
+                grants: vec![],
+                bindings: vec![mount],
+            }],
+            vec![],
+        )
+        .await;
+        let generation = prepare(&runtime).await;
+        let plan = runtime.middleware_registry().resolve(&generation).unwrap();
+        let calls = Arc::new(AtomicUsize::new(0));
+        let response = plan
+            .handle(
+                middleware_context(ClientTransport::HttpJson),
+                MiddlewareRequest::new(
+                    "openai",
+                    middleware_headers(),
+                    Bytes::from_static(br#"{"input":"hello"}"#),
+                ),
+                Box::new(Downstream {
+                    calls: calls.clone(),
+                    reads: Arc::default(),
+                    closes: Arc::default(),
+                    error: false,
+                }),
+            )
+            .await;
+        assert_eq!(response.is_ok(), expected_calls == 1);
+        assert_eq!(calls.load(Ordering::Relaxed), expected_calls);
+        drop(response);
+        drop(plan);
+        drop(generation);
+        super::wait_until_empty(cache.path()).await;
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/generation/prepare/mod.rs b/backend/crates/gateway-plugin/runtime/tests/generation/prepare/mod.rs
new file mode 100644
index 000000000..d1b890cf5
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/generation/prepare/mod.rs
@@ -0,0 +1,866 @@
+use gateway_admin::{
+    model::{
+        Revision,
+        plugins::instances::{
+            PluginCapabilityBinding, PluginFailurePolicy, PluginInstanceRuntimeStatus,
+        },
+    },
+    ports::plugins::PluginPreparation,
+};
+use gateway_core::{routing::ConfigRevision, runtime::extensions::ExtensionPreparationPort};
+use gateway_plugin_sdk::{Capability, Contributions, Stage};
+use std::{num::NonZeroUsize, path::Path, time::Duration};
+
+async fn wait_until_unready(reference: &gateway_core::runtime::extensions::ExtensionSetReference) {
+    tokio::time::timeout(Duration::from_secs(2), async {
+        while reference.is_ready() {
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .expect("worker exit observed");
+}
+
+fn startup_count(marker: &Path) -> usize {
+    std::fs::read_to_string(marker)
+        .map(|content| content.lines().count())
+        .unwrap_or_default()
+}
+
+#[tokio::test]
+async fn runtime_shutdown_reaps_live_generation_and_rejects_late_preparation() {
+    let (cache, store, runtime) = super::setup().await;
+    let published = ExtensionPreparationPort::prepare(&runtime, ConfigRevision::new(1).unwrap())
+        .await
+        .unwrap();
+    assert!(published.is_ready());
+    assert_eq!(std::fs::read_dir(cache.path()).unwrap().count(), 1);
+
+    runtime.shutdown().await;
+    assert!(!published.is_ready());
+    super::wait_until_empty(cache.path()).await;
+    assert!(
+        ExtensionPreparationPort::prepare(&runtime, ConfigRevision::new(1).unwrap())
+            .await
+            .is_err()
+    );
+    runtime.shutdown().await;
+
+    drop(published);
+    drop(store);
+}
+
+#[tokio::test]
+async fn management_needs_no_binding_and_rejects_stale_execution_identity_configuration() {
+    let (_cache, store, runtime) =
+        super::setup_with_contributions(Contributions::from([crate::support::contribution(
+            Capability::Management,
+            vec![Stage::Management],
+            Vec::new(),
+            Vec::new(),
+        )]))
+        .await;
+    let mut instance = store.snapshot.lock().unwrap().instances[0].clone();
+    assert!(
+        PluginPreparation::validate(&runtime, instance.clone())
+            .await
+            .is_ok()
+    );
+    instance.bindings = vec![PluginCapabilityBinding {
+        contribution: "test.example.management".into(),
+        stage: "management".into(),
+        order: 0,
+        failure_policy: PluginFailurePolicy::Reject,
+        client_key_ids: vec!["key-one".into(), "key-two".into()],
+        account_group_ids: Vec::new(),
+        provider_ids: Vec::new(),
+        models: Vec::new(),
+        identity_bindings: Vec::new(),
+    }];
+    assert!(
+        PluginPreparation::validate(&runtime, instance.clone())
+            .await
+            .is_err()
+    );
+    instance.enabled = false;
+    assert!(
+        PluginPreparation::validate(&runtime, instance)
+            .await
+            .is_err()
+    );
+}
+
+#[tokio::test]
+async fn registration_with_a_changed_contribution_id_is_rejected() {
+    let (cache, store, runtime) =
+        super::setup_with_contributions(Contributions::from([crate::support::contribution(
+            Capability::Usage,
+            vec![Stage::Observation],
+            Vec::new(),
+            Vec::new(),
+        )]))
+        .await;
+    let mut snapshot = store.snapshot.lock().unwrap().clone();
+    let candidate =
+        PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+            .await
+            .expect("the declared contribution prepares before its registration id changes");
+    drop(candidate);
+    super::wait_until_empty(cache.path()).await;
+
+    snapshot.instances[0].configuration = serde_json::json!({"registration_mismatch":true});
+    let error = PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot)
+        .await
+        .expect_err("a changed registration contribution id must be rejected");
+    assert!(
+        error.to_string().contains("插件注册结果与清单不符"),
+        "unexpected preparation failure: {error}"
+    );
+}
+
+#[tokio::test]
+async fn candidate_is_reused_after_commit_and_released_when_no_generation_owner_remains() {
+    let (cache, store, runtime) = super::setup().await;
+    let mut snapshot = store.snapshot.lock().unwrap().clone();
+    snapshot.instances[0].configuration =
+        serde_json::from_str(r#"{"z":1,"a":{"z":2,"a":3}}"#).unwrap();
+    let candidate =
+        PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+            .await
+            .unwrap();
+    assert!(
+        runtime.observer_registry().resolve(&candidate).is_none(),
+        "没有观察绑定时不应编译派发计划"
+    );
+    snapshot.instances[0].configuration =
+        serde_json::from_str(r#"{"a":{"a":3,"z":2},"z":1}"#).unwrap();
+    snapshot.config_revision = Revision::new(2).unwrap();
+    *store.snapshot.lock().unwrap() = snapshot;
+    let published = ExtensionPreparationPort::prepare(&runtime, ConfigRevision::new(2).unwrap())
+        .await
+        .unwrap();
+    assert_eq!(candidate.id(), published.id());
+    assert!(published.is_ready());
+    drop(candidate);
+    assert_eq!(std::fs::read_dir(cache.path()).unwrap().count(), 1);
+    drop(published);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn diagnostics_distinguish_running_failed_preparation_and_draining_generations() {
+    let (cache, store, runtime) = super::setup().await;
+    let snapshot = store.snapshot.lock().unwrap().clone();
+    let active = PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+        .await
+        .unwrap();
+
+    let running = PluginPreparation::runtime_diagnostics(
+        &runtime,
+        &snapshot,
+        Some(snapshot.config_revision.get()),
+        Some(&active),
+    )
+    .await
+    .expect("runtime diagnostics");
+    let running = &running["instance-one"];
+    assert_eq!(running.status, PluginInstanceRuntimeStatus::Running);
+    assert_eq!(running.actual_revision, Some(1));
+    assert_eq!(
+        running.actual_artifact_sha256.as_deref(),
+        Some(snapshot.instances[0].artifact_sha256.as_str())
+    );
+    assert!(running.failure.is_none());
+
+    let mut failed = snapshot.clone();
+    failed.config_revision = Revision::new(2).unwrap();
+    failed.instances[0].revision = Revision::new(2).unwrap();
+    failed.instances[0].configuration = serde_json::json!({"startup":"fail"});
+    assert!(
+        PluginPreparation::prepare(&runtime, snapshot.config_revision, failed.clone())
+            .await
+            .is_err()
+    );
+    let diagnostics = PluginPreparation::runtime_diagnostics(
+        &runtime,
+        &failed,
+        Some(snapshot.config_revision.get()),
+        Some(&active),
+    )
+    .await
+    .expect("failed preparation diagnostics");
+    let failed_runtime = &diagnostics["instance-one"];
+    assert_eq!(
+        failed_runtime.status,
+        PluginInstanceRuntimeStatus::PreparationFailed
+    );
+    assert!(failed_runtime.failure.is_some());
+    assert_eq!(failed_runtime.actual_revision, Some(1));
+
+    let mut disabled = failed;
+    disabled.config_revision = Revision::new(3).unwrap();
+    disabled.instances[0].revision = Revision::new(3).unwrap();
+    disabled.instances[0].enabled = false;
+    let diagnostics = PluginPreparation::runtime_diagnostics(
+        &runtime,
+        &disabled,
+        Some(snapshot.config_revision.get()),
+        Some(&active),
+    )
+    .await
+    .expect("draining diagnostics");
+    let draining = &diagnostics["instance-one"];
+    assert_eq!(draining.status, PluginInstanceRuntimeStatus::Draining);
+    assert_eq!(draining.draining_revisions, [1]);
+
+    drop(active);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn preparing_diagnostics_never_wait_for_the_serialized_prepare_io() {
+    let (cache, store, runtime) = super::setup().await;
+    let source = store.snapshot.lock().unwrap().clone();
+    let mut candidate = source.clone();
+    candidate.config_revision = Revision::new(2).unwrap();
+    candidate.instances[0].revision = Revision::new(2).unwrap();
+    candidate.instances[0].configuration = serde_json::json!({"startup_delay_ms":400});
+    let diagnostic_snapshot = candidate.clone();
+    let mut preparation = Box::pin(PluginPreparation::prepare(
+        &runtime,
+        source.config_revision,
+        candidate,
+    ));
+    assert!(futures::poll!(preparation.as_mut()).is_pending());
+
+    let diagnostics = tokio::time::timeout(
+        std::time::Duration::from_millis(100),
+        PluginPreparation::runtime_diagnostics(&runtime, &diagnostic_snapshot, None, None),
+    )
+    .await
+    .expect("diagnostics must not wait for plugin startup")
+    .expect("runtime diagnostics");
+    assert_eq!(
+        diagnostics["instance-one"].status,
+        PluginInstanceRuntimeStatus::Preparing
+    );
+
+    let candidate = preparation.await.expect("delayed candidate");
+    drop(candidate);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn diagnostics_report_a_published_process_fault_without_plugin_details() {
+    let (cache, store, runtime) = super::setup().await;
+    let mut snapshot = store.snapshot.lock().unwrap().clone();
+    snapshot.instances[0].configuration = serde_json::json!({"exit_after_ready_ms":20});
+    let active = PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+        .await
+        .expect("candidate starts before the controlled exit");
+    tokio::time::timeout(std::time::Duration::from_secs(2), async {
+        while active.is_ready() {
+            tokio::time::sleep(std::time::Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .expect("worker exit observed");
+
+    let diagnostics = PluginPreparation::runtime_diagnostics(
+        &runtime,
+        &snapshot,
+        Some(snapshot.config_revision.get()),
+        Some(&active),
+    )
+    .await
+    .expect("runtime diagnostics");
+    let fault = &diagnostics["instance-one"];
+    assert_eq!(fault.status, PluginInstanceRuntimeStatus::Faulted);
+    assert_eq!(
+        fault.failure.as_ref().map(|failure| failure.code.as_str()),
+        Some("closed")
+    );
+    assert_eq!(
+        fault
+            .failure
+            .as_ref()
+            .map(|failure| failure.message.as_str()),
+        Some("插件进程或传输已停止")
+    );
+
+    drop(active);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn restart_circuit_caps_short_lived_crashes_and_a_new_revision_recovers() {
+    let restart_circuit = gateway_plugin_runtime::PluginRestartCircuitConfig {
+        maximum_failures: NonZeroUsize::new(3).unwrap(),
+        stability_window: Duration::from_secs(1),
+    };
+    let (cache, store, runtime) = super::setup_with_restart_circuit(restart_circuit).await;
+    let controls = tempfile::tempdir().unwrap();
+    let marker = controls.path().join("starts.jsonl");
+    let mut snapshot = store.snapshot.lock().unwrap().clone();
+    snapshot.instances[0].configuration = serde_json::json!({
+        "startup_marker": marker,
+        "exit_after_ready_ms": 20,
+    });
+    let mut active =
+        PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+            .await
+            .expect("first incarnation");
+    for expected_start in 2..=3 {
+        wait_until_unready(&active).await;
+        let replacement =
+            PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+                .await
+                .expect("failure budget still permits a restart");
+        drop(active);
+        active = replacement;
+        assert_eq!(startup_count(&marker), expected_start);
+    }
+    wait_until_unready(&active).await;
+    assert!(
+        PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+            .await
+            .is_err(),
+        "the fourth incarnation must not start"
+    );
+    assert_eq!(startup_count(&marker), 3);
+
+    let diagnostics = PluginPreparation::runtime_diagnostics(
+        &runtime,
+        &snapshot,
+        Some(snapshot.config_revision.get()),
+        Some(&active),
+    )
+    .await
+    .expect("runtime diagnostics");
+    assert_eq!(
+        diagnostics["instance-one"]
+            .failure
+            .as_ref()
+            .map(|failure| failure.code.as_str()),
+        Some("restart_circuit_open")
+    );
+
+    let mut disabled = snapshot;
+    disabled.config_revision = Revision::new(2).unwrap();
+    disabled.instances[0].revision = Revision::new(2).unwrap();
+    disabled.instances[0].enabled = false;
+    let disabled_generation =
+        PluginPreparation::prepare(&runtime, Revision::new(1).unwrap(), disabled.clone())
+            .await
+            .expect("disabling the instance does not reuse its open circuit");
+    assert_eq!(startup_count(&marker), 3);
+
+    let mut repaired = disabled;
+    repaired.config_revision = Revision::new(3).unwrap();
+    repaired.instances[0].revision = Revision::new(3).unwrap();
+    repaired.instances[0].enabled = true;
+    repaired.instances[0].configuration = serde_json::json!({"startup_marker":marker});
+    let replacement = PluginPreparation::prepare(&runtime, Revision::new(1).unwrap(), repaired)
+        .await
+        .expect("a new instance revision has an independent failure budget");
+    assert!(replacement.is_ready());
+    assert_eq!(startup_count(&marker), 4);
+
+    drop(active);
+    drop(disabled_generation);
+    drop(replacement);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn restart_circuit_resets_after_a_stable_incarnation() {
+    let restart_circuit = gateway_plugin_runtime::PluginRestartCircuitConfig {
+        maximum_failures: NonZeroUsize::new(3).unwrap(),
+        stability_window: Duration::from_millis(80),
+    };
+    let (cache, store, runtime) = super::setup_with_restart_circuit(restart_circuit).await;
+    let controls = tempfile::tempdir().unwrap();
+    let marker = controls.path().join("stable-reset-starts.jsonl");
+    let exit = controls.path().join("stable-exit");
+    let mut snapshot = store.snapshot.lock().unwrap().clone();
+    snapshot.instances[0].configuration = serde_json::json!({
+        "startup_marker":marker,
+        "startup_failures":[true,true,false,true,true],
+        "exit_after_ready_signals":[null,null,exit],
+    });
+    // 握手前失败的有效运行时间固定为零；不能用短 sleep 假定宿主一定及时观察到退出。
+    for _ in 0..2 {
+        assert!(
+            PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+                .await
+                .is_err()
+        );
+    }
+    let active = PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+        .await
+        .expect("the third incarnation starts before the circuit opens");
+    assert!(active.is_ready());
+    // 明确等到稳定窗口之后才允许第三个进程退出；调度变慢不会把短命进程误变为稳定进程。
+    tokio::time::sleep(restart_circuit.stability_window).await;
+    tokio::fs::write(exit, b"exit").await.unwrap();
+    wait_until_unready(&active).await;
+    for expected_start in 4..=5 {
+        assert!(
+            PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+                .await
+                .is_err()
+        );
+        assert_eq!(startup_count(&marker), expected_start);
+    }
+    assert!(
+        PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot)
+            .await
+            .is_err(),
+        "three new failures after the stable incarnation reopen the circuit"
+    );
+    assert_eq!(startup_count(&marker), 5);
+
+    drop(active);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn restart_circuit_ignores_planned_generation_shutdown() {
+    let restart_circuit = gateway_plugin_runtime::PluginRestartCircuitConfig {
+        maximum_failures: NonZeroUsize::MIN,
+        stability_window: Duration::from_secs(60),
+    };
+    let (cache, store, runtime) = super::setup_with_restart_circuit(restart_circuit).await;
+    let controls = tempfile::tempdir().unwrap();
+    let marker = controls.path().join("planned-shutdown-starts.jsonl");
+    let mut snapshot = store.snapshot.lock().unwrap().clone();
+    snapshot.instances[0].configuration = serde_json::json!({"startup_marker":marker});
+    let first = PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+        .await
+        .expect("first generation");
+    let instance = &snapshot.instances[0];
+    PluginPreparation::quiesce_instance(
+        &runtime,
+        &instance.id,
+        &instance.artifact_sha256,
+        instance.revision,
+    )
+    .await;
+    assert!(!first.is_ready());
+
+    let second = PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot)
+        .await
+        .expect("planned shutdown must not open the one-failure circuit");
+    assert!(second.is_ready());
+    assert_eq!(startup_count(&marker), 2);
+
+    drop(first);
+    drop(second);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn restart_circuit_counts_exit_before_the_candidate_is_indexed() {
+    let restart_circuit = gateway_plugin_runtime::PluginRestartCircuitConfig {
+        maximum_failures: NonZeroUsize::new(3).unwrap(),
+        stability_window: Duration::from_secs(1),
+    };
+    let (cache, store, runtime) = super::setup_with_restart_circuit(restart_circuit).await;
+    let controls = tempfile::tempdir().unwrap();
+    let marker = controls.path().join("registration-exits.jsonl");
+    let mut snapshot = store.snapshot.lock().unwrap().clone();
+    snapshot.instances[0].configuration = serde_json::json!({
+        "startup_marker":marker,
+        "exit_during_registration":true,
+    });
+    for _ in 0..3 {
+        assert!(
+            PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+                .await
+                .is_err()
+        );
+    }
+    assert_eq!(startup_count(&marker), 3);
+    assert!(
+        PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+            .await
+            .is_err()
+    );
+    assert_eq!(
+        startup_count(&marker),
+        3,
+        "open circuit must gate process spawn"
+    );
+
+    let diagnostics = PluginPreparation::runtime_diagnostics(&runtime, &snapshot, None, None)
+        .await
+        .expect("runtime diagnostics");
+    assert_eq!(
+        diagnostics["instance-one"]
+            .failure
+            .as_ref()
+            .map(|failure| failure.code.as_str()),
+        Some("restart_circuit_open")
+    );
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn restart_circuit_counts_a_started_process_that_exits_during_handshake() {
+    let restart_circuit = gateway_plugin_runtime::PluginRestartCircuitConfig {
+        maximum_failures: NonZeroUsize::new(2).unwrap(),
+        stability_window: Duration::from_millis(10),
+    };
+    let (cache, store, runtime) = super::setup_with_restart_circuit(restart_circuit).await;
+    let controls = tempfile::tempdir().unwrap();
+    let marker = controls.path().join("handshake-exits.jsonl");
+    let mut snapshot = store.snapshot.lock().unwrap().clone();
+    snapshot.instances[0].configuration = serde_json::json!({
+        "startup_marker":marker,
+        "startup":"fail",
+        "startup_fail_delay_ms":50,
+    });
+    for _ in 0..2 {
+        assert!(
+            PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+                .await
+                .is_err()
+        );
+    }
+    assert_eq!(startup_count(&marker), 2);
+    assert!(
+        PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot)
+            .await
+            .is_err()
+    );
+    assert_eq!(
+        startup_count(&marker),
+        2,
+        "host-side gating must happen before another process spawn"
+    );
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn restart_circuit_does_not_let_an_older_generation_clear_newer_failures() {
+    let restart_circuit = gateway_plugin_runtime::PluginRestartCircuitConfig {
+        maximum_failures: NonZeroUsize::new(3).unwrap(),
+        stability_window: Duration::from_millis(50),
+    };
+    let (cache, store, runtime) = super::setup_with_restart_circuit(restart_circuit).await;
+    let controls = tempfile::tempdir().unwrap();
+    let marker = controls.path().join("overlapping-generations.jsonl");
+    let old_exit = controls.path().join("old-generation-exit");
+    let mut snapshot = store.snapshot.lock().unwrap().clone();
+    snapshot.instances[0].configuration = serde_json::json!({
+        "startup_marker":marker,
+        "exit_after_ready_delays_ms":[null,15,15,15],
+        "exit_after_ready_signals":[old_exit,null,null,null],
+    });
+    let mut other = snapshot.instances[0].clone();
+    other.id = "other-instance".into();
+    other.name = "Other".into();
+    other.configuration = serde_json::json!({});
+    snapshot.instances.push(other);
+    let published =
+        PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+            .await
+            .expect("published generation");
+    assert!(published.is_ready());
+
+    let mut failed_candidate = None;
+    for revision in 2..=4 {
+        snapshot.config_revision = Revision::new(revision).unwrap();
+        snapshot.instances[1].revision = Revision::new(revision).unwrap();
+        snapshot.instances[1].configuration = serde_json::json!({"revision":revision});
+        let candidate =
+            PluginPreparation::prepare(&runtime, Revision::new(1).unwrap(), snapshot.clone())
+                .await
+                .expect("newer candidate starts before its controlled exit");
+        wait_until_unready(&candidate).await;
+        drop(failed_candidate.replace(candidate));
+        assert!(published.is_ready(), "the older generation remains healthy");
+    }
+    drop(failed_candidate.take());
+    std::fs::write(&old_exit, b"exit").unwrap();
+    wait_until_unready(&published).await;
+    snapshot.config_revision = Revision::new(5).unwrap();
+    snapshot.instances[1].revision = Revision::new(5).unwrap();
+    snapshot.instances[1].configuration = serde_json::json!({"revision":5});
+    assert!(
+        PluginPreparation::prepare(&runtime, Revision::new(1).unwrap(), snapshot)
+            .await
+            .is_err(),
+        "the older healthy session must not erase newer failures for the same identity"
+    );
+    assert_eq!(startup_count(&marker), 4);
+
+    drop(published);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn restart_circuit_restores_an_older_failure_after_candidate_shutdown() {
+    let restart_circuit = gateway_plugin_runtime::PluginRestartCircuitConfig {
+        maximum_failures: NonZeroUsize::MIN,
+        stability_window: Duration::from_secs(1),
+    };
+    let (cache, store, runtime) = super::setup_with_restart_circuit(restart_circuit).await;
+    let controls = tempfile::tempdir().unwrap();
+    let marker = controls.path().join("abandoned-candidate.jsonl");
+    let old_exit = controls.path().join("abandoned-candidate-old-exit");
+    let mut snapshot = store.snapshot.lock().unwrap().clone();
+    snapshot.instances[0].configuration = serde_json::json!({
+        "startup_marker":marker,
+        "exit_after_ready_delays_ms":[null,null],
+        "exit_after_ready_signals":[old_exit,null],
+    });
+    let mut other = snapshot.instances[0].clone();
+    other.id = "other-instance".into();
+    other.name = "Other".into();
+    other.configuration = serde_json::json!({});
+    snapshot.instances.push(other);
+    let published =
+        PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+            .await
+            .expect("published generation");
+
+    snapshot.config_revision = Revision::new(2).unwrap();
+    snapshot.instances[1].revision = Revision::new(2).unwrap();
+    snapshot.instances[1].configuration = serde_json::json!({"revision":2});
+    let candidate =
+        PluginPreparation::prepare(&runtime, Revision::new(1).unwrap(), snapshot.clone())
+            .await
+            .expect("healthy replacement candidate");
+    std::fs::write(&old_exit, b"exit").unwrap();
+    wait_until_unready(&published).await;
+    assert!(candidate.is_ready());
+    drop(candidate);
+
+    tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            let diagnostics = PluginPreparation::runtime_diagnostics(
+                &runtime,
+                &snapshot,
+                Some(1),
+                Some(&published),
+            )
+            .await
+            .expect("runtime diagnostics");
+            if diagnostics["instance-one"]
+                .failure
+                .as_ref()
+                .is_some_and(|failure| failure.code == "restart_circuit_open")
+            {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .expect("older failure is restored after candidate shutdown");
+
+    snapshot.config_revision = Revision::new(3).unwrap();
+    snapshot.instances[1].revision = Revision::new(3).unwrap();
+    snapshot.instances[1].configuration = serde_json::json!({"revision":3});
+    assert!(
+        PluginPreparation::prepare(&runtime, Revision::new(1).unwrap(), snapshot)
+            .await
+            .is_err()
+    );
+    assert_eq!(startup_count(&marker), 2);
+
+    drop(published);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn failed_candidate_leaves_the_previous_generation_ready() {
+    let (cache, store, runtime) = super::setup().await;
+    let snapshot = store.snapshot.lock().unwrap().clone();
+    let active = PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot.clone())
+        .await
+        .unwrap();
+    let mut candidate = snapshot;
+    candidate.instances[0].configuration = serde_json::json!({"startup":"fail"});
+    assert!(
+        PluginPreparation::prepare(&runtime, candidate.config_revision, candidate)
+            .await
+            .is_err()
+    );
+    assert!(active.is_ready());
+    drop(active);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn disabled_missing_artifacts_do_not_block_the_remaining_generation_or_offline_recovery() {
+    let (cache, store, runtime) = super::setup().await;
+    let mut snapshot = store.snapshot.lock().unwrap().clone();
+    let mut missing = snapshot.instances[0].clone();
+    missing.id = "missing".into();
+    missing.enabled = false;
+    missing.artifact_sha256 = "0".repeat(64);
+    snapshot.instances.push(missing);
+    let active = PluginPreparation::prepare(&runtime, snapshot.config_revision, snapshot)
+        .await
+        .unwrap();
+    assert!(active.is_ready());
+    drop(active);
+    super::wait_until_empty(cache.path()).await;
+    let restored = ExtensionPreparationPort::prepare(&runtime, ConfigRevision::new(1).unwrap())
+        .await
+        .unwrap();
+    assert!(restored.is_ready());
+    drop(restored);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn preparation_cannot_mix_a_newer_persisted_revision_with_an_older_snapshot() {
+    let (_cache, _store, runtime) = super::setup().await;
+    assert!(
+        ExtensionPreparationPort::prepare(&runtime, ConfigRevision::new(2).unwrap())
+            .await
+            .is_err()
+    );
+}
+
+#[tokio::test]
+async fn restoring_a_failed_plugin_keeps_other_instances_ready_and_reports_only_its_failure() {
+    let (cache, store, runtime) = super::setup().await;
+    let snapshot = {
+        let mut snapshot = store.snapshot.lock().unwrap();
+        let mut failed = snapshot.instances[0].clone();
+        failed.id = "failed-plugin".into();
+        failed.configuration = serde_json::json!({"startup":"fail"});
+        snapshot.instances.insert(0, failed);
+        snapshot.clone()
+    };
+    let generation = ExtensionPreparationPort::prepare(&runtime, ConfigRevision::new(1).unwrap())
+        .await
+        .expect("one failed plugin must not stop restoration");
+    assert!(generation.can_serve());
+    let diagnostics =
+        PluginPreparation::runtime_diagnostics(&runtime, &snapshot, Some(1), Some(&generation))
+            .await
+            .unwrap();
+    assert_eq!(
+        diagnostics["failed-plugin"].status,
+        PluginInstanceRuntimeStatus::PreparationFailed
+    );
+    assert!(diagnostics["failed-plugin"].failure.is_some());
+    assert_eq!(
+        diagnostics["instance-one"].status,
+        PluginInstanceRuntimeStatus::Running
+    );
+    let reused = ExtensionPreparationPort::prepare(&runtime, ConfigRevision::new(1).unwrap())
+        .await
+        .unwrap();
+    assert_eq!(
+        generation.id(),
+        reused.id(),
+        "quarantined failures do not restart on every request"
+    );
+    drop(reused);
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn a_published_process_crash_preserves_the_serving_snapshot_and_other_plugin_status() {
+    let (cache, store, runtime) = super::setup().await;
+    let snapshot = {
+        let mut snapshot = store.snapshot.lock().unwrap();
+        let mut failed = snapshot.instances[0].clone();
+        failed.id = "crashing-plugin".into();
+        failed.configuration = serde_json::json!({"exit_after_ready_ms":100});
+        snapshot.instances.push(failed);
+        snapshot.clone()
+    };
+    let generation = ExtensionPreparationPort::prepare(&runtime, ConfigRevision::new(1).unwrap())
+        .await
+        .unwrap();
+    wait_until_unready(&generation).await;
+    assert!(generation.can_serve());
+    assert!(
+        runtime
+            .provider_registry()
+            .for_extensions(Some(&generation))
+            .is_ok()
+    );
+    assert!(!generation.is_ready());
+    let diagnostics =
+        PluginPreparation::runtime_diagnostics(&runtime, &snapshot, Some(1), Some(&generation))
+            .await
+            .unwrap();
+    assert_eq!(
+        diagnostics["instance-one"].status,
+        PluginInstanceRuntimeStatus::Running
+    );
+    assert_eq!(
+        diagnostics["crashing-plugin"].status,
+        PluginInstanceRuntimeStatus::Faulted
+    );
+    drop(generation);
+    super::wait_until_empty(cache.path()).await;
+}
+
+#[tokio::test]
+async fn an_incompatible_host_quarantines_the_plugin_with_a_specific_version_error() {
+    use std::sync::Arc;
+    let (cache, store, _) = super::setup().await;
+    let runtime = gateway_plugin_runtime::PluginRuntime::new(
+        store.clone(),
+        store.clone(),
+        gateway_plugin_runtime::PluginRuntimeConfig {
+            cache_directory: cache.path().to_owned(),
+            host_version: "3.0.0".parse().unwrap(),
+            package_limits: Default::default(),
+            rpc_limits: Default::default(),
+            continuation_drain: Default::default(),
+            restart_circuit: Default::default(),
+        },
+        Default::default(),
+        gateway_admin::ports::provider::ProviderAdminRegistry::new([]).unwrap(),
+        Arc::new(gateway_host::outbound::HttpClient::new().unwrap()),
+        Arc::new(gateway_host::process::ProcessSupervisor::default()),
+    );
+    let restored = ExtensionPreparationPort::prepare(&runtime, ConfigRevision::new(1).unwrap())
+        .await
+        .unwrap();
+    assert!(restored.can_serve());
+    let snapshot = store.snapshot.lock().unwrap().clone();
+    let diagnostics =
+        PluginPreparation::runtime_diagnostics(&runtime, &snapshot, Some(1), Some(&restored))
+            .await
+            .unwrap();
+    let failure = diagnostics["instance-one"].failure.as_ref().unwrap();
+    assert!(
+        failure
+            .message
+            .contains("插件要求宿主 >=1.0.0, <2.0.0，当前为 3.0.0")
+    );
+    assert!(
+        std::fs::read_dir(cache.path()).unwrap().next().is_none(),
+        "incompatible packages never start"
+    );
+}
+
+#[tokio::test]
+async fn an_existing_failed_plugin_does_not_prevent_editing_an_unrelated_instance() {
+    let (cache, store, runtime) = super::setup().await;
+    let mut snapshot = store.snapshot.lock().unwrap().clone();
+    let mut failed = snapshot.instances[0].clone();
+    failed.id = "failed-plugin".into();
+    failed.configuration = serde_json::json!({"startup":"fail"});
+    snapshot.instances.push(failed);
+    snapshot.config_revision = Revision::new(2).unwrap();
+    snapshot.instances[0].revision = snapshot.config_revision;
+    let candidate = PluginPreparation::prepare(&runtime, Revision::new(1).unwrap(), snapshot)
+        .await
+        .expect("only the instance being changed must successfully prepare");
+    assert!(candidate.can_serve());
+    drop(candidate);
+    super::wait_until_empty(cache.path()).await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/generation/private_state.rs b/backend/crates/gateway-plugin/runtime/tests/generation/private_state.rs
new file mode 100644
index 000000000..f588d3766
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/generation/private_state.rs
@@ -0,0 +1,346 @@
+use std::{
+    collections::BTreeMap,
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicU64, Ordering},
+    },
+    time::{Duration, SystemTime},
+};
+
+use async_trait::async_trait;
+use gateway_admin::{
+    model::{
+        Revision,
+        plugins::{
+            instances::{
+                PluginCapabilityBinding, PluginFailurePolicy, PluginInstance,
+                PluginInstanceSnapshot,
+            },
+            state::{
+                ApplyPluginStateMigration, DeletePluginState, PluginStateConfiguration,
+                PluginStateMigrationBatch, PluginStateNamespaceOwner, PluginStateOwner,
+                PluginStateOwnerRequest, PluginStateRecord, PluginStateTransition,
+                PluginStateWrite, PutPluginState,
+            },
+        },
+    },
+    ports::plugins::{
+        PluginPackageInspector, PluginStateStore, PluginStateStoreError, PluginStateStoreErrorKind,
+        PluginStateStoreResult,
+    },
+};
+use gateway_core::{
+    engine::{
+        ModelRequestId,
+        observation::{RequestObservation, RequestObservationOutcome},
+        provider::ProviderRegistry,
+    },
+    identity::ProviderKind,
+    operation::OperationKind,
+    routing::{ConfigRevision, PublicModelId},
+    runtime::extensions::ExtensionPreparationPort,
+    upstream::UpstreamSendState,
+};
+use gateway_plugin_runtime::{
+    PackageInspector, PackageLimits, PluginRuntime, PluginRuntimeConfig, RpcLimits,
+};
+use gateway_plugin_sdk::{Capability, Contributions, Stage, StateNamespace};
+use serde_json::json;
+
+use crate::support::store::Store;
+
+struct StoredRecord {
+    value: serde_json::Value,
+    version: u64,
+}
+
+#[derive(Default)]
+struct StateStore {
+    records: Mutex<BTreeMap<(String, String), StoredRecord>>,
+    calls: Mutex<Vec<String>>,
+    next_version: AtomicU64,
+}
+
+impl StateStore {
+    fn error(kind: PluginStateStoreErrorKind) -> PluginStateStoreError {
+        PluginStateStoreError::new(kind)
+    }
+
+    fn calls(&self) -> Vec<String> {
+        self.calls.lock().unwrap().clone()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.records.lock().unwrap().is_empty()
+    }
+}
+
+#[async_trait]
+impl PluginStateStore for StateStore {
+    async fn load_owner(
+        &self,
+        request: PluginStateOwnerRequest,
+    ) -> PluginStateStoreResult<Option<PluginStateOwner>> {
+        let namespaces = request
+            .configuration
+            .namespaces
+            .iter()
+            .map(|schema| {
+                (
+                    schema.namespace.clone(),
+                    PluginStateNamespaceOwner::from_store(
+                        format!("generation-{}", schema.namespace),
+                        format!("fence-{}", schema.namespace),
+                        schema.schema_version,
+                    ),
+                )
+            })
+            .collect();
+        Ok(Some(PluginStateOwner::from_store(
+            request.instance_id,
+            request.artifact_sha256,
+            request.instance_revision,
+            namespaces,
+        )))
+    }
+
+    async fn get(
+        &self,
+        owner: &PluginStateOwner,
+        namespace: &str,
+        key: &str,
+    ) -> PluginStateStoreResult<Option<PluginStateRecord>> {
+        let namespace_owner = owner
+            .namespace(namespace)
+            .ok_or_else(|| Self::error(PluginStateStoreErrorKind::PermissionDenied))?;
+        self.calls.lock().unwrap().push(format!("get:{namespace}"));
+        Ok(self
+            .records
+            .lock()
+            .unwrap()
+            .get(&(namespace.into(), key.into()))
+            .map(|record| PluginStateRecord {
+                key: key.into(),
+                value: record.value.clone(),
+                version: record.version,
+                schema_version: namespace_owner.schema_version(),
+            }))
+    }
+
+    async fn put(
+        &self,
+        owner: &PluginStateOwner,
+        command: PutPluginState,
+    ) -> PluginStateStoreResult<PluginStateWrite> {
+        owner
+            .namespace(&command.namespace)
+            .ok_or_else(|| Self::error(PluginStateStoreErrorKind::PermissionDenied))?;
+        let key = (command.namespace.clone(), command.key.clone());
+        let mut records = self.records.lock().unwrap();
+        let current = records.get(&key).map(|record| record.version);
+        if command.expected_version != current {
+            return Err(Self::error(PluginStateStoreErrorKind::Conflict));
+        }
+        let version = self.next_version.fetch_add(1, Ordering::Relaxed) + 1;
+        records.insert(
+            key,
+            StoredRecord {
+                value: command.value,
+                version,
+            },
+        );
+        self.calls
+            .lock()
+            .unwrap()
+            .push(format!("put:{}", command.namespace));
+        Ok(PluginStateWrite { version })
+    }
+
+    async fn delete(
+        &self,
+        owner: &PluginStateOwner,
+        command: DeletePluginState,
+    ) -> PluginStateStoreResult<bool> {
+        owner
+            .namespace(&command.namespace)
+            .ok_or_else(|| Self::error(PluginStateStoreErrorKind::PermissionDenied))?;
+        let key = (command.namespace.clone(), command.key);
+        let mut records = self.records.lock().unwrap();
+        let Some(current) = records.get(&key) else {
+            return Ok(false);
+        };
+        if current.version != command.expected_version {
+            return Err(Self::error(PluginStateStoreErrorKind::Conflict));
+        }
+        records.remove(&key);
+        self.calls
+            .lock()
+            .unwrap()
+            .push(format!("delete:{}", command.namespace));
+        Ok(true)
+    }
+
+    async fn transition_required(
+        &self,
+        _: &str,
+        _: &PluginStateConfiguration,
+    ) -> PluginStateStoreResult<bool> {
+        Ok(false)
+    }
+
+    async fn begin_transition(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &str,
+        _: PluginStateConfiguration,
+    ) -> PluginStateStoreResult<PluginStateTransition> {
+        Err(Self::error(PluginStateStoreErrorKind::Unavailable))
+    }
+
+    async fn migration_batch(
+        &self,
+        _: &str,
+        _: &str,
+        _: u32,
+    ) -> PluginStateStoreResult<PluginStateMigrationBatch> {
+        Err(Self::error(PluginStateStoreErrorKind::Unavailable))
+    }
+
+    async fn apply_migration_batch(
+        &self,
+        _: ApplyPluginStateMigration,
+    ) -> PluginStateStoreResult<()> {
+        Err(Self::error(PluginStateStoreErrorKind::Unavailable))
+    }
+
+    async fn abort_transition(&self, _: &str) -> PluginStateStoreResult<()> {
+        Ok(())
+    }
+}
+
+#[tokio::test]
+async fn observation_callbacks_use_typed_state_crud_and_reject_undeclared_namespaces() {
+    let cache = tempfile::tempdir().unwrap();
+    let marker = cache.path().join("state.jsonl");
+    let contributes = Contributions::from([crate::support::contribution(
+        Capability::RequestLifecycle,
+        vec![Stage::Observation],
+        vec![],
+        vec![],
+    )]);
+    let state_namespace = StateNamespace {
+        namespace: "cache".into(),
+        schema_version: 1,
+        schema: json!({
+            "type": "object",
+            "required": ["value"],
+            "properties": {"value": {"type": "integer"}},
+            "additionalProperties": false,
+        }),
+        maximum_records: 8,
+        maximum_bytes: 1024,
+        maximum_value_bytes: 128,
+        migrates_from: vec![],
+    };
+    let archive = crate::support::package_with_contributions_and_state(
+        crate::support::worker(),
+        vec![],
+        contributes,
+        vec![state_namespace],
+    );
+    let artifact = PackageInspector::new(PackageLimits::default(), "1.0.0".parse().unwrap())
+        .inspect(archive, None)
+        .await
+        .unwrap();
+    let digest = artifact.metadata.sha256.clone();
+    let instance = PluginInstance {
+        id: "state-instance".into(),
+        name: "state-instance".into(),
+        artifact_sha256: digest.clone(),
+        enabled: true,
+        trusted_process: true,
+        configuration: json!({
+            "state_fixture": {
+                "namespace": "cache",
+                "denied_namespace": "private",
+                "key": "request",
+                "value": {"value": 7},
+            },
+            "state_marker": marker,
+        }),
+        secrets: BTreeMap::new(),
+        grants: vec![],
+        bindings: vec![PluginCapabilityBinding {
+            contribution: "test.example.requestLifecycle".into(),
+            stage: "observation".into(),
+            order: 0,
+            failure_policy: PluginFailurePolicy::Observe,
+            client_key_ids: vec![],
+            account_group_ids: vec![],
+            provider_ids: vec!["openai".into()],
+            models: vec!["gpt-state".into()],
+            identity_bindings: vec![],
+        }],
+        revision: Revision::new(1).unwrap(),
+    };
+    let store = Arc::new(Store {
+        artifacts: BTreeMap::from([(digest, artifact)]),
+        snapshot: Mutex::new(PluginInstanceSnapshot {
+            config_revision: Revision::new(1).unwrap(),
+            instances: vec![instance],
+        }),
+    });
+    let state = Arc::new(StateStore::default());
+    let runtime = PluginRuntime::new(
+        store,
+        state.clone(),
+        PluginRuntimeConfig {
+            cache_directory: cache.path().join("packages"),
+            host_version: "1.0.0".parse().unwrap(),
+            package_limits: PackageLimits::default(),
+            rpc_limits: RpcLimits::default(),
+            continuation_drain: Default::default(),
+            restart_circuit: Default::default(),
+        },
+        ProviderRegistry::default(),
+        gateway_admin::ports::provider::ProviderAdminRegistry::new([]).unwrap(),
+        Arc::new(gateway_host::outbound::HttpClient::new().unwrap()),
+        Arc::new(gateway_host::process::ProcessSupervisor::new(
+            std::num::NonZeroUsize::new(16).unwrap(),
+        )),
+    );
+    let generation = ExtensionPreparationPort::prepare(&runtime, ConfigRevision::new(1).unwrap())
+        .await
+        .unwrap();
+    let plan = runtime.observer_registry().resolve(&generation).unwrap();
+    plan.dispatch(
+        generation.clone(),
+        RequestObservation::new(
+            ModelRequestId::new("req_state").unwrap(),
+            ConfigRevision::new(1).unwrap(),
+            OperationKind::Generate,
+            RequestObservationOutcome::Succeeded,
+            UpstreamSendState::Sent,
+            SystemTime::now(),
+        )
+        .with_requested_model(PublicModelId::new("gpt-state").unwrap())
+        .with_provider(ProviderKind::new("openai").unwrap()),
+    );
+    tokio::time::timeout(Duration::from_secs(3), async {
+        while !marker.exists() {
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .unwrap();
+    assert_eq!(state.calls(), ["put:cache", "get:cache", "delete:cache"]);
+    assert!(state.is_empty());
+    let marker = std::fs::read_to_string(marker).unwrap();
+    assert!(marker.contains("\"version\":1"));
+    assert!(marker.contains("\"schema_version\":1"));
+
+    drop(plan);
+    drop(generation);
+    super::wait_until_empty(cache.path().join("packages").as_path()).await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/generation/worker.rs b/backend/crates/gateway-plugin/runtime/tests/generation/worker.rs
new file mode 100644
index 000000000..0fd1180b1
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/generation/worker.rs
@@ -0,0 +1,554 @@
+use std::{sync::Arc, time::Duration};
+
+use gateway_admin::{
+    CredentialsService,
+    model::{
+        plugins::instances::{PluginCapabilityBinding, PluginFailurePolicy},
+        provider_credentials::{
+            CredentialMutation, ImportCredentials, ProviderDocument, RotateCredential,
+        },
+    },
+};
+use gateway_core::{
+    account::OpaqueProviderData,
+    lifecycle::CancellationToken,
+    routing::{ConfigRevision, ProviderKind},
+    task::{ScheduledTask, WorkerContribution, WorkerCycleContext, WorkerRunnable},
+};
+use serde_json::{Value, json};
+
+use crate::support::environment::{Environment, account_grant, mutation};
+
+fn task(
+    runtime: &Arc<gateway_plugin_runtime::PluginRuntime>,
+    core: &gateway_core::CoreBundle,
+    owner: &str,
+) -> (Box<dyn ScheduledTask>, WorkerCycleContext) {
+    let definitions = runtime.worker_contributions(core.snapshots()).unwrap();
+    assert_eq!(definitions.len(), 4);
+    for definition in definitions {
+        definition.validate().unwrap();
+        let WorkerContribution::Registration(registration) = definition else {
+            panic!("scheduled worker");
+        };
+        if registration.id.owner() != owner {
+            continue;
+        }
+        let WorkerRunnable::Scheduled {
+            schedule,
+            lease,
+            task,
+        } = registration.runnable
+        else {
+            panic!("scheduled worker");
+        };
+        assert!(lease.is_some());
+        assert!(schedule.leader_lease_renewal_interval() < schedule.leader_lease_ttl());
+        return (
+            task,
+            WorkerCycleContext::new(registration.id, None, CancellationToken::new()),
+        );
+    }
+    panic!("missing worker {owner}")
+}
+
+fn http_grants() -> Vec<gateway_admin::model::plugins::instances::PluginPermissionGrant> {
+    vec![account_grant("accounts"), account_grant("network")]
+}
+
+async fn enable_maintenance(
+    environment: &Environment,
+    core: &gateway_core::CoreBundle,
+    enabled: bool,
+) {
+    let store = environment.store.admin_ports().plugins();
+    let snapshot = store.load_instances().await.unwrap();
+    let mut instance = snapshot.instances.into_iter().next().unwrap();
+    instance
+        .bindings
+        .retain(|binding| binding.contribution != "test.example.maintenance");
+    if enabled {
+        instance.bindings.push(PluginCapabilityBinding {
+            contribution: "test.example.maintenance".into(),
+            stage: "maintenance".into(),
+            order: 0,
+            failure_policy: PluginFailurePolicy::Reject,
+            client_key_ids: vec![],
+            account_group_ids: vec![],
+            provider_ids: vec![],
+            models: vec![],
+            identity_bindings: vec![],
+        });
+    }
+    let saved = store
+        .save_instance(instance, snapshot.config_revision, &mutation())
+        .await
+        .unwrap();
+    core.snapshot_control()
+        .publish_committed(ConfigRevision::new(saved.config_revision.get()).unwrap())
+        .await;
+}
+
+#[tokio::test]
+async fn maintenance_requires_binding_and_stops_dispatch_after_revocation() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let server = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::header(
+        "authorization",
+        "Bearer test-only",
+    ))
+    .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(
+        json!({"plan_type":"maintained", "access":{"kind":"allowed"}, "windows":[]}),
+    ))
+    .expect(1)
+    .mount(&server)
+    .await;
+    let account = environment.account(None).await;
+    let (runtime, core) = environment.provider(json!({"maintenance":true,"quota_url":server.uri(),"expected_maintenance_methods":["provider.quota"]}), http_grants()).await;
+    let (task, context) = task(&runtime, &core, "plugin-quota");
+    enable_maintenance(&environment, &core, false).await;
+    task.run_cycle(context.clone()).await.unwrap();
+    assert!(server.received_requests().await.unwrap().is_empty());
+    enable_maintenance(&environment, &core, true).await;
+    task.run_cycle(context.clone()).await.unwrap();
+    let quotas = environment
+        .store
+        .provider_ports()
+        .accounts()
+        .get_quotas(std::slice::from_ref(&account))
+        .await
+        .unwrap();
+    assert_eq!(quotas.len(), 1);
+    assert_eq!(quotas[0].plan_type.as_deref(), Some("maintained"));
+    enable_maintenance(&environment, &core, false).await;
+    task.run_cycle(context).await.unwrap();
+    assert_eq!(server.received_requests().await.unwrap().len(), 1);
+    drop(task);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn cancelled_maintenance_drops_rpc_and_does_not_commit_late_quota() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let server = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::any())
+        .respond_with(
+            wiremock::ResponseTemplate::new(200)
+                .set_delay(Duration::from_secs(2))
+                .set_body_json(json!({"access":{"kind":"allowed"},"windows":[]})),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+    let account = environment.account(None).await;
+    let (runtime, core) = environment
+        .provider(
+            json!({"maintenance":true,"quota_url":server.uri()}),
+            http_grants(),
+        )
+        .await;
+    let (task, context) = task(&runtime, &core, "plugin-quota");
+    let cancellation = context.cancellation().clone();
+    let running = tokio::spawn(async move { task.run_cycle(context).await });
+    tokio::time::timeout(Duration::from_secs(5), async {
+        while server.received_requests().await.unwrap().is_empty() {
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .unwrap();
+    cancellation.cancel();
+    tokio::time::timeout(Duration::from_secs(1), running)
+        .await
+        .unwrap()
+        .unwrap()
+        .unwrap();
+    tokio::time::sleep(Duration::from_millis(2100)).await;
+    assert!(
+        environment
+            .store
+            .provider_ports()
+            .accounts()
+            .get_quotas(&[account])
+            .await
+            .unwrap()
+            .is_empty()
+    );
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn late_maintenance_quota_cannot_overwrite_rotated_credentials() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let mut server = crate::support::http::GatedResponse::start(json!({
+        "access":{"kind":"exhausted","evidence":"usage_limit_reached"},"windows":[]
+    }))
+    .await;
+    let account = environment.account(None).await;
+    let (runtime, core) = environment
+        .provider(
+            json!({"maintenance":true,"quota_url":server.uri()}),
+            http_grants(),
+        )
+        .await;
+    let (task, context) = task(&runtime, &core, "plugin-quota");
+    let running = tokio::spawn(async move { task.run_cycle(context).await });
+    server.received().await;
+    let service = CredentialsService::new(
+        runtime.admin_registry(core.snapshots()),
+        environment.store.admin_ports().accounts(),
+        environment.store.admin_ports().proxies(),
+        core.snapshot_control(),
+    );
+    service
+        .for_provider(&ProviderKind::new("example").unwrap())
+        .unwrap()
+        .rotate(RotateCredential {
+            mutation: CredentialMutation {
+                account_id: account.clone(),
+                context: mutation(),
+            },
+            provider_material: ProviderDocument::new(OpaqueProviderData::new(
+                json!({"key":"new-test-key"}).as_object().unwrap().clone(),
+            )),
+            settings: None,
+        })
+        .await
+        .unwrap();
+    server.respond().await;
+    // 旧修订的结果属于正常竞争；本周期结束，但不能把旧额度写到新凭据上。
+    running.await.unwrap().unwrap();
+    let accounts = environment.store.provider_ports().accounts();
+    let current = accounts.load_current_credential(&account).await.unwrap();
+    assert_eq!(current.account.revision().get(), 2);
+    assert_eq!(
+        current.credential.expose_to_provider()["key"],
+        "new-test-key"
+    );
+    assert!(accounts.get_quotas(&[account]).await.unwrap().is_empty());
+    drop(accounts);
+    drop(service);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn disabled_accounts_are_not_dispatched_from_an_already_loaded_page() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let mut server = crate::support::http::GatedResponse::start_batch(
+        json!({"access":{"kind":"allowed"},"windows":[]}),
+        4,
+    )
+    .await;
+    let mut account_ids = Vec::new();
+    for _ in 0..8 {
+        account_ids.push(environment.account(None).await.as_str().to_owned());
+    }
+    let marker = environment
+        .directory
+        .path()
+        .join("queued-maintenance.jsonl");
+    let (runtime, core) = environment.provider(
+        json!({"maintenance":true,"quota_url":server.uri(),"maintenance_context_marker":marker}),
+        http_grants(),
+    ).await;
+    let (task, context) = task(&runtime, &core, "plugin-quota");
+    let running = tokio::spawn(async move { task.run_cycle(context).await });
+    server.received().await;
+    // 第一组已发出，剩余账号还在这一页的并发队列中；持久化停用事实先于快照通知。
+    environment
+        .store
+        .admin_ports()
+        .accounts()
+        .batch_update_accounts(
+            gateway_admin::model::accounts::BatchUpdateAccounts {
+                account_ids,
+                enabled: Some(false),
+                concurrency_limit: None,
+                weight: None,
+                model_access: None,
+                group_ids: None,
+                outbound_proxy: None,
+            },
+            &mutation(),
+        )
+        .await
+        .unwrap();
+    server.respond().await;
+    tokio::time::timeout(Duration::from_secs(5), running)
+        .await
+        .unwrap()
+        .unwrap()
+        .unwrap();
+    let calls = std::fs::read_to_string(marker)
+        .unwrap()
+        .lines()
+        .map(|line| serde_json::from_str::<Value>(line).unwrap())
+        .filter(|entry| entry["method"] == "provider.quota" && entry["stage"] == "maintenance")
+        .count();
+    assert_eq!(calls, 4, "已停用的排队账号不得收到新的插件调用");
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn maintenance_refresh_commits_due_credentials_and_preserves_admin_profile() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment.provider(json!({"maintenance":true,"expected_maintenance_methods":["provider.credentials.refresh"]}), vec![account_grant("accounts"), account_grant("accounts")]).await;
+    let service = CredentialsService::new(
+        runtime.admin_registry(core.snapshots()),
+        environment.store.admin_ports().accounts(),
+        environment.store.admin_ports().proxies(),
+        core.snapshot_control(),
+    );
+    let kind = ProviderKind::new("example").unwrap();
+    let now = chrono::Utc::now().timestamp_millis();
+    let imported = service.for_provider(&kind).unwrap().import_document(ImportCredentials {
+        outbound_proxy_id: None, settings: None, context: mutation(), document: ProviderDocument::new(OpaqueProviderData::new(json!({"accounts":[
+            {"name":"kept admin profile","authentication_kind":"oauth","material":{"key":"original-test-key"},"has_refresh_token":true,"access_token_expires_at_ms":now-1000,"next_refresh_at_ms":now-1000},
+            {"name":"scheduled without expiry","authentication_kind":"oauth","material":{"key":"original-test-key"},"has_refresh_token":true,"next_refresh_at_ms":now-1000},
+            {"name":"not due","authentication_kind":"oauth","material":{"key":"future-test-key"},"has_refresh_token":true,"access_token_expires_at_ms":now+86_400_000,"next_refresh_at_ms":now+86_400_000}
+        ]}).as_object().unwrap().clone())),
+    }).await.unwrap();
+    assert_eq!(imported.credential_ids.len(), 3);
+    let (task, context) = task(&runtime, &core, "plugin-credentials");
+    task.run_cycle(context).await.unwrap();
+    let accounts = environment.store.provider_ports().accounts();
+    for id in imported.credential_ids {
+        let current = accounts.load_current_credential(&id).await.unwrap();
+        if matches!(
+            current.account.name(),
+            "kept admin profile" | "scheduled without expiry"
+        ) {
+            assert_eq!(current.account.revision().get(), 2);
+            assert_eq!(
+                current.credential.expose_to_provider()["key"],
+                "refreshed-test-key"
+            );
+        } else {
+            assert_eq!(current.account.name(), "not due");
+            assert_eq!(current.account.revision().get(), 1);
+            assert_eq!(
+                current.credential.expose_to_provider()["key"],
+                "future-test-key"
+            );
+        }
+    }
+    drop(accounts);
+    drop(task);
+    drop(service);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+fn profiles(version: &str) -> Value {
+    json!({"default_configuration":{"channel":"stable"},"options":[{
+        "id":"stable","label":"稳定版","configuration":{"channel":"stable"},"resolved":{"version":version},
+        "presentation":{"product":"Maintenance Fixture","version":version,"target":{"os_type":"linux","os_version":"6","arch":"x86_64","terminal":"test"},"user_agent":format!("Fixture/{version}"),"attributes":[]}
+    }]})
+}
+
+#[tokio::test]
+async fn profile_maintenance_requires_an_initial_stable_directory() {
+    use gateway_admin::{
+        model::{AdminErrorKind, Revision},
+        ports::plugins::PluginPreparation as _,
+    };
+
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let (runtime, core) = environment
+        .provider(
+            json!({"maintenance":true,"request_profiles":profiles("1"),"request_profile_refresh":{"sequence":2,"profiles":profiles("2")}}),
+            vec![account_grant("accounts")],
+        )
+        .await;
+    let mut candidate = environment
+        .store
+        .admin_ports()
+        .plugins()
+        .load_instances()
+        .await
+        .unwrap();
+    let source = candidate.config_revision;
+    candidate.config_revision = Revision::new(source.get() + 1).unwrap();
+    candidate.instances[0].revision = candidate.config_revision;
+    candidate.instances[0]
+        .configuration
+        .as_object_mut()
+        .unwrap()
+        .remove("request_profiles");
+    let error = runtime.prepare(source, candidate).await.unwrap_err();
+    assert_eq!(error.kind(), AdminErrorKind::Invalid);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn model_maintenance_pages_all_provider_accounts_without_prebinding() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    for _ in 0..20 {
+        environment.account(None).await;
+    }
+    let extra_account = environment.account(None).await;
+    let marker = environment
+        .directory
+        .path()
+        .join("maintenance-context.jsonl");
+    let credentials = account_grant("accounts");
+    let (runtime, core) = environment.provider(json!({
+        "maintenance":true,"maintenance_context_marker":marker,
+        "model_discovery":{"include_static":false,"cache_ttl_seconds":60},
+        "discovered_catalog":{"models":[{"id":"discovered-model","operations":["generate"]}],"exhaustive":true}
+    }), vec![credentials]).await;
+    let (task, context) = task(&runtime, &core, "plugin-models");
+    let calls = || {
+        std::fs::read_to_string(&marker)
+            .unwrap()
+            .lines()
+            .map(|line| serde_json::from_str::<Value>(line).unwrap())
+            .filter(|entry| entry["method"] == "provider.models" && entry["stage"] == "maintenance")
+            .collect::<Vec<_>>()
+    };
+    task.run_cycle(context.clone()).await.unwrap();
+    assert_eq!(calls().len(), 16);
+    task.run_cycle(context).await.unwrap();
+    let calls = calls();
+    assert_eq!(calls.len(), 21);
+    let visited = calls
+        .iter()
+        .map(|entry| entry["account_id"].as_str().unwrap())
+        .collect::<std::collections::BTreeSet<_>>();
+    assert_eq!(visited.len(), 21);
+    assert!(visited.contains(extra_account.as_str()));
+    for call in calls {
+        assert_eq!(call["credential_revision"], 1);
+        assert!(call["request_id"].as_str().unwrap().starts_with("worker:"));
+    }
+    drop(task);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
+
+#[tokio::test]
+async fn refreshed_profiles_are_monotonic_cached_and_do_not_change_frozen_requests() {
+    let Some(environment) = Environment::create().await else {
+        eprintln!("SKIP: plugin integration environment absent");
+        return;
+    };
+    let mut changed_choice = profiles("3");
+    changed_choice["default_configuration"]["channel"] = json!("changed");
+    changed_choice["options"][0]["configuration"]["channel"] = json!("changed");
+    let mut oversized = profiles("3");
+    oversized["options"][0]["resolved"]["large"] = json!("x".repeat(16 * 1024));
+    let invalid = vec![
+        json!({"sequence":2,"profiles":profiles("illegal-same-sequence")}),
+        json!({"sequence":3,"profiles":changed_choice}),
+        json!({"sequence":0,"profiles":profiles("3")}),
+        json!({"sequence":1_u64 << 53,"profiles":profiles("3")}),
+        json!({"sequence":3,"profiles":oversized}),
+    ];
+    let invalid_count = invalid.len();
+    let mut refreshes = vec![
+        json!({"sequence":2,"profiles":profiles("2")}),
+        json!({"sequence":1,"profiles":profiles("1")}),
+    ];
+    refreshes.extend(invalid);
+    let (runtime, core) = environment.provider(json!({"maintenance":true,"request_profiles":profiles("1"),"request_profile_refresh":{"sequence":2,"profiles":profiles("2")},
+        "request_profile_refresh_responses":refreshes,
+        "expected_maintenance_methods":["provider.request_profiles.refresh"]}), vec![account_grant("accounts")]).await;
+    let kind = ProviderKind::new("example").unwrap();
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&kind)
+        .unwrap();
+    let choice = OpaqueProviderData::new(json!({"channel":"stable"}).as_object().unwrap().clone());
+    let snapshot = core.snapshots().acquire().unwrap();
+    let executors = runtime
+        .provider_registry()
+        .for_extensions(snapshot.extensions())
+        .unwrap();
+    let executor = executors.get(&kind).unwrap();
+    let frozen = executor.resolve_request_profile(&choice).unwrap();
+    let (task, context) = task(&runtime, &core, "plugin-request-profiles");
+    task.run_cycle(context.clone()).await.unwrap();
+    assert_eq!(frozen.expose_to_provider()["version"], "1");
+    assert_eq!(
+        provider
+            .preview_client_profile(&choice)
+            .unwrap()
+            .expose_to_provider()["version"],
+        "2"
+    );
+    assert_eq!(provider.default_client_profile(), Some(choice.clone()));
+    task.run_cycle(context.clone()).await.unwrap();
+    assert_eq!(
+        executor
+            .resolve_request_profile(&choice)
+            .unwrap()
+            .expose_to_provider()["version"],
+        "2"
+    );
+    for _ in 0..invalid_count {
+        assert!(task.run_cycle(context.clone()).await.is_err());
+        assert_eq!(
+            executor
+                .resolve_request_profile(&choice)
+                .unwrap()
+                .expose_to_provider()["version"],
+            "2"
+        );
+    }
+    task.run_cycle(context).await.unwrap();
+    drop(executors);
+    drop(snapshot);
+    drop(task);
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    let (runtime, core) = environment.runtime().await;
+    let provider = runtime
+        .admin_registry(core.snapshots())
+        .require(&kind)
+        .unwrap();
+    assert_eq!(
+        provider
+            .preview_client_profile(&choice)
+            .unwrap()
+            .expose_to_provider()["version"],
+        "2"
+    );
+    drop(provider);
+    drop(core);
+    drop(runtime);
+    environment.close().await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/main.rs b/backend/crates/gateway-plugin/runtime/tests/main.rs
new file mode 100644
index 000000000..ccbc3aafb
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/main.rs
@@ -0,0 +1,7 @@
+mod adapter;
+mod callback;
+mod generation;
+mod package;
+#[cfg(unix)]
+mod rpc;
+mod support;
diff --git a/backend/crates/gateway-plugin/runtime/tests/package/cache.rs b/backend/crates/gateway-plugin/runtime/tests/package/cache.rs
new file mode 100644
index 000000000..0e6aee392
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/package/cache.rs
@@ -0,0 +1,27 @@
+use std::sync::Arc;
+
+use gateway_plugin_runtime::{PackageLimits, ValidatedPackage};
+
+#[test]
+fn new_preparation_never_modifies_an_existing_version_and_cache_is_reclaimable() {
+    let cache = tempfile::tempdir().unwrap();
+    let package = Arc::new(
+        ValidatedPackage::read(
+            crate::support::package(b"hello"),
+            None,
+            PackageLimits::default(),
+        )
+        .unwrap(),
+    );
+    let first = package
+        .prepare(cache.path(), &"1.0.0".parse().unwrap())
+        .unwrap();
+    let second = package
+        .prepare(cache.path(), &"1.0.0".parse().unwrap())
+        .unwrap();
+    assert_ne!(first.directory(), second.directory());
+    let first_path = first.directory().to_owned();
+    drop(first);
+    assert!(!first_path.exists());
+    assert_eq!(std::fs::read(second.executable()).unwrap(), b"hello");
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/package/compatibility.rs b/backend/crates/gateway-plugin/runtime/tests/package/compatibility.rs
new file mode 100644
index 000000000..cdd08ab6b
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/package/compatibility.rs
@@ -0,0 +1,125 @@
+use gateway_admin::{
+    model::plugins::PluginHostCompatibility, ports::plugins::PluginPackageInspector as _,
+};
+use gateway_plugin_runtime::{PackageInspector, PackageLimits};
+use gateway_plugin_sdk::{Capability, Contributions, Permission, Stage};
+use sha2::{Digest as _, Sha256};
+
+#[test]
+fn host_compatibility_covers_every_sdk_capability_and_permission() {
+    let compatibility: PluginHostCompatibility =
+        serde_json::from_str(include_str!("../../plugin-host-compatibility.json"))
+            .expect("compatibility JSON");
+    assert!(compatibility.is_valid());
+
+    for capability in all_capabilities() {
+        assert_exhaustive_capability(capability);
+        let identifier = identifier(capability);
+        assert!(
+            compatibility.supports_capability(&identifier, 1),
+            "missing capability {identifier}"
+        );
+    }
+    for permission in Permission::ALL {
+        assert_exhaustive_permission(permission);
+        let identifier = identifier(permission);
+        assert!(
+            compatibility.supports_permission(&identifier),
+            "missing permission {identifier}"
+        );
+    }
+}
+
+#[tokio::test]
+async fn package_inspector_returns_static_requirements_without_starting_the_plugin() {
+    let archive = crate::support::package_with_contributions(
+        b"not-an-executable",
+        vec![],
+        Contributions::from([crate::support::contribution(
+            Capability::Executor,
+            vec![Stage::Execution],
+            vec!["openai".into()],
+            vec!["openai".into()],
+        )]),
+    );
+    let digest = hex::encode(Sha256::digest(archive.as_ref()));
+    let inspector = PackageInspector::new(PackageLimits::default(), semver::Version::new(3, 13, 0));
+
+    let requirements = inspector
+        .compatibility(archive, digest)
+        .await
+        .expect("compatibility requirements");
+    assert_eq!(requirements.host_version, ">=1.0.0, <2.0.0");
+    assert_eq!(
+        requirements.manifest_schema_version,
+        gateway_plugin_sdk::MANIFEST_VERSION
+    );
+    assert_eq!(
+        requirements.protocol_version,
+        gateway_plugin_sdk::PROTOCOL_VERSION
+    );
+    assert_eq!(requirements.capabilities, vec![("executor".into(), 1)]);
+    assert!(requirements.permissions.is_empty());
+}
+
+fn identifier(value: impl serde::Serialize) -> String {
+    serde_json::to_value(value)
+        .expect("serialize identifier")
+        .as_str()
+        .expect("string identifier")
+        .to_owned()
+}
+
+fn assert_exhaustive_capability(capability: Capability) {
+    match capability {
+        Capability::Models
+        | Capability::Authentication
+        | Capability::FrontendAuthentication
+        | Capability::Scheduler
+        | Capability::ModelRouter
+        | Capability::Executor
+        | Capability::Middleware
+        | Capability::RequestLifecycle
+        | Capability::WebSocketObserver
+        | Capability::Usage
+        | Capability::CommandLine
+        | Capability::Management
+        | Capability::Quota
+        | Capability::RequestProfile
+        | Capability::AccountManagement
+        | Capability::Billing
+        | Capability::Maintenance => {}
+    }
+}
+
+fn assert_exhaustive_permission(permission: Permission) {
+    match permission {
+        Permission::Network
+        | Permission::Requests
+        | Permission::Models
+        | Permission::Accounts
+        | Permission::PublicEndpoints => {}
+    }
+}
+
+fn all_capabilities() -> [Capability; 17] {
+    [
+        Capability::Models,
+        Capability::Authentication,
+        Capability::FrontendAuthentication,
+        Capability::Scheduler,
+        Capability::ModelRouter,
+        Capability::Executor,
+        Capability::Middleware,
+        Capability::RequestLifecycle,
+        Capability::WebSocketObserver,
+        Capability::Usage,
+        Capability::CommandLine,
+        Capability::Management,
+        Capability::Quota,
+        Capability::RequestProfile,
+        Capability::AccountManagement,
+        Capability::Billing,
+        Capability::Maintenance,
+    ]
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/package/inspection.rs b/backend/crates/gateway-plugin/runtime/tests/package/inspection.rs
new file mode 100644
index 000000000..52ab31669
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/package/inspection.rs
@@ -0,0 +1,18 @@
+use gateway_admin::ports::plugins::PluginPackageInspector;
+use gateway_plugin_runtime::{PackageInspector, PackageLimits};
+use gateway_plugin_sdk::Permission;
+
+#[test]
+fn permission_presentations_come_from_the_current_sdk_without_an_archive() {
+    let inspector = PackageInspector::new(PackageLimits::default(), "3.14.0".parse().unwrap());
+    let permissions = vec!["models".to_owned(), "future_permission".to_owned()];
+    let descriptions = inspector.permission_descriptions(&permissions);
+    assert_eq!(descriptions[0].permission, "models");
+    assert_eq!(descriptions[0].label, Permission::Models.label());
+    assert_eq!(
+        descriptions[0].description,
+        Permission::Models.description()
+    );
+    assert_eq!(descriptions[1].label, "future_permission");
+    assert!(descriptions[1].description.is_empty());
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/package/mod.rs b/backend/crates/gateway-plugin/runtime/tests/package/mod.rs
new file mode 100644
index 000000000..aabaed817
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/package/mod.rs
@@ -0,0 +1,4 @@
+mod cache;
+mod compatibility;
+mod inspection;
+mod validation;
diff --git a/backend/crates/gateway-plugin/runtime/tests/package/validation.rs b/backend/crates/gateway-plugin/runtime/tests/package/validation.rs
new file mode 100644
index 000000000..7c992c960
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/package/validation.rs
@@ -0,0 +1,356 @@
+use std::collections::BTreeMap;
+
+use gateway_admin::{
+    model::plugins::{PluginArtifactIcon, PluginIconTheme},
+    ports::plugins::PluginPackageInspector as _,
+};
+use gateway_plugin_runtime::{PackageError, PackageInspector, PackageLimits, ValidatedPackage};
+use image::{
+    DynamicImage, ExtendedColorType, Frame, ImageEncoder as _, ImageFormat, RgbaImage,
+    codecs::{gif::GifEncoder, png::PngEncoder},
+};
+use sha2::{Digest as _, Sha256};
+
+fn png(width: u32, height: u32) -> Vec<u8> {
+    let mut encoded = Vec::new();
+    PngEncoder::new(&mut encoded)
+        .write_image(
+            &vec![0; width as usize * height as usize * 4],
+            width,
+            height,
+            ExtendedColorType::Rgba8,
+        )
+        .unwrap();
+    encoded
+}
+
+fn raster(format: ImageFormat) -> Vec<u8> {
+    let mut output = std::io::Cursor::new(Vec::new());
+    let image = if format == ImageFormat::Jpeg {
+        DynamicImage::new_rgb8(2, 3)
+    } else {
+        DynamicImage::new_rgba8(2, 3)
+    };
+    image.write_to(&mut output, format).unwrap();
+    output.into_inner()
+}
+
+fn gif(frames: usize) -> Vec<u8> {
+    let mut output = Vec::new();
+    {
+        let mut encoder = GifEncoder::new(&mut output);
+        for _ in 0..frames {
+            encoder
+                .encode_frame(Frame::new(RgbaImage::new(2, 3)))
+                .unwrap();
+        }
+    }
+    output
+}
+
+fn package_with_icon(path: &str, content_type: &str, icon: Vec<u8>) -> std::sync::Arc<[u8]> {
+    let worker = b"worker".to_vec();
+    let package_files = BTreeMap::from([
+        (
+            "bin/worker".to_owned(),
+            hex::encode(Sha256::digest(&worker)),
+        ),
+        (path.to_owned(), hex::encode(Sha256::digest(&icon))),
+    ]);
+    let resources = BTreeMap::from([(path.to_owned(), content_type.to_owned())]);
+    let manifest = serde_json::json!({
+        "manifestVersion": 3,
+        "name": "icon",
+        "displayName": "Icon",
+        "publisher": "test",
+        "version": "1.0.0",
+        "description": "Icon fixture",
+        "license": "MIT",
+        "engines": {"codex-proxy-rs": ">=1.0.0, <2.0.0"},
+        "main": "bin/worker",
+        "runtime": "trustedProcess",
+        "contributes": {},
+        "resources": resources,
+        "icon": path,
+        "package": {
+            "protocolVersion": 4,
+            "target": {
+                "os": std::env::consts::OS,
+                "architecture": std::env::consts::ARCH
+            },
+            "files": package_files
+        }
+    });
+    crate::support::archive(BTreeMap::from([
+        ("plugin.json".into(), serde_json::to_vec(&manifest).unwrap()),
+        ("bin/worker".into(), worker),
+        (path.to_owned(), icon),
+    ]))
+}
+
+#[test]
+fn expected_digest_is_checked_before_archive_parsing() {
+    assert!(matches!(
+        ValidatedPackage::read(
+            b"invalid".as_slice().into(),
+            Some(&"0".repeat(64)),
+            PackageLimits::default()
+        ),
+        Err(PackageError::Digest)
+    ));
+}
+
+#[test]
+fn unlisted_content_is_rejected() {
+    let bytes = crate::support::archive(BTreeMap::from([("surprise".into(), b"code".to_vec())]));
+    assert!(matches!(
+        ValidatedPackage::read(bytes, None, PackageLimits::default()),
+        Err(PackageError::Archive)
+    ));
+}
+
+#[test]
+fn decompression_limit_includes_archive_overhead() {
+    let bytes = crate::support::package(&[0; 4096]);
+    assert!(matches!(
+        ValidatedPackage::read(
+            bytes,
+            None,
+            PackageLimits {
+                expanded_bytes: 1024,
+                ..PackageLimits::default()
+            }
+        ),
+        Err(PackageError::Limit)
+    ));
+}
+
+#[test]
+fn package_retains_the_exact_verified_archive_for_recovery() {
+    let bytes = crate::support::package(b"hello");
+    let package = ValidatedPackage::read(bytes.clone(), None, PackageLimits::default()).unwrap();
+    assert_eq!(package.archive(), bytes);
+    assert_eq!(package.manifest().plugin_id().unwrap(), "test.example");
+}
+
+#[tokio::test]
+async fn validated_icon_is_exposed_from_the_digest_bound_archive() {
+    let bytes = package_with_icon("assets/icon.png", "image/png", png(2, 3));
+    let digest = hex::encode(Sha256::digest(&bytes));
+    let inspector = PackageInspector::new(PackageLimits::default(), "1.0.0".parse().unwrap());
+    let artifact = inspector
+        .inspect(bytes, Some(digest.clone()))
+        .await
+        .unwrap();
+    assert_eq!(
+        artifact.metadata.icon,
+        Some(PluginArtifactIcon::Path("assets/icon.png".into()))
+    );
+    let icon = inspector
+        .icon(artifact.archive, digest, PluginIconTheme::Dark)
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(icon.content_type, "image/png");
+    assert!(!icon.body.is_empty());
+}
+
+#[tokio::test]
+async fn common_icon_formats_are_verified_and_returned_without_transcoding() {
+    for (path, mime, bytes) in [
+        ("assets/icon.PNG", "image/png", png(2, 3)),
+        ("assets/icon.jpeg", "image/jpeg", raster(ImageFormat::Jpeg)),
+        ("assets/icon.jfif", "image/jpeg", raster(ImageFormat::Jpeg)),
+        ("assets/icon.WebP", "image/webp", raster(ImageFormat::WebP)),
+        ("assets/icon.gif", "image/gif", gif(2)),
+        ("assets/icon.ico", "image/x-icon", raster(ImageFormat::Ico)),
+        (
+            "assets/icon.ICO",
+            "image/vnd.microsoft.icon",
+            raster(ImageFormat::Ico),
+        ),
+        ("assets/icon.bmp", "image/bmp", raster(ImageFormat::Bmp)),
+        (
+            "assets/icon.BMP",
+            "image/x-ms-bmp",
+            raster(ImageFormat::Bmp),
+        ),
+        (
+            "assets/icon.SVG",
+            "image/svg+xml",
+            br##"<?xml version="1.0" encoding="UTF-8"?>
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+              <style>.icon { fill: url(#paint); }</style>
+              <defs><linearGradient id="paint"><stop stop-color="#58f"/>
+                <stop offset="1" stop-color="#8ef"/></linearGradient></defs>
+              <path class="icon" d="M2 2h20v20H2z"/>
+            </svg>"##
+                .to_vec(),
+        ),
+    ] {
+        let archive = package_with_icon(path, mime, bytes.clone());
+        let digest = hex::encode(Sha256::digest(&archive));
+        let inspector = PackageInspector::new(PackageLimits::default(), "1.0.0".parse().unwrap());
+        let artifact = inspector
+            .inspect(archive, Some(digest.clone()))
+            .await
+            .unwrap_or_else(|error| panic!("{path}: {error:?}"));
+        for theme in [PluginIconTheme::Light, PluginIconTheme::Dark] {
+            let icon = inspector
+                .icon(artifact.archive.clone(), digest.clone(), theme)
+                .await
+                .unwrap()
+                .unwrap();
+            assert_eq!(icon.content_type, mime, "{path}");
+            assert_eq!(icon.body, bytes, "{path}");
+        }
+    }
+}
+
+#[test]
+fn svg_icons_reject_malformed_xml_non_svg_roots_and_external_entities() {
+    for bytes in [
+        b"not an image".as_slice(),
+        b"<svg xmlns=\"http://www.w3.org/2000/svg\"><path></svg>",
+        b"<html xmlns=\"http://www.w3.org/1999/xhtml\"/>",
+        b"<svg xmlns=\"https://invalid.example/svg\"/>",
+        br#"<!DOCTYPE svg [<!ENTITY external SYSTEM "file:///etc/passwd">]>
+            <svg xmlns="http://www.w3.org/2000/svg">&external;</svg>"#,
+        br#"<?xml-stylesheet href="https://invalid.example/transform.xsl"?>
+            <svg xmlns="http://www.w3.org/2000/svg"/>"#,
+    ] {
+        let archive = package_with_icon("assets/icon.svg", "image/svg+xml", bytes.to_vec());
+        assert_eq!(
+            ValidatedPackage::read(archive, None, PackageLimits::default()).err(),
+            Some(PackageError::Archive),
+            "{}",
+            String::from_utf8_lossy(bytes)
+        );
+    }
+}
+
+#[test]
+fn icon_validation_keeps_byte_node_and_animation_budgets() {
+    let large_svg = format!(
+        "<svg xmlns=\"http://www.w3.org/2000/svg\"><!--{}--></svg>",
+        "x".repeat(512 * 1024)
+    );
+    let many_nodes = format!(
+        "<svg xmlns=\"http://www.w3.org/2000/svg\">{}</svg>",
+        "<path/>".repeat(16_384)
+    );
+    for (path, mime, bytes) in [
+        ("assets/icon.svg", "image/svg+xml", large_svg.into_bytes()),
+        ("assets/icon.svg", "image/svg+xml", many_nodes.into_bytes()),
+        ("assets/icon.gif", "image/gif", gif(257)),
+    ] {
+        let archive = package_with_icon(path, mime, bytes);
+        assert_eq!(
+            ValidatedPackage::read(archive, None, PackageLimits::default()).err(),
+            Some(PackageError::Limit),
+            "{path}"
+        );
+    }
+}
+
+#[test]
+fn icon_content_must_fully_decode_match_its_type_and_fit_dimensions() {
+    let valid_png = png(2, 3);
+    let wrong_type = package_with_icon("assets/icon.jpg", "image/jpeg", valid_png.clone());
+    assert_eq!(
+        ValidatedPackage::read(wrong_type, None, PackageLimits::default()).err(),
+        Some(PackageError::Archive)
+    );
+
+    let truncated = package_with_icon("assets/icon.png", "image/png", valid_png[..32].to_vec());
+    assert_eq!(
+        ValidatedPackage::read(truncated, None, PackageLimits::default()).err(),
+        Some(PackageError::Archive)
+    );
+
+    let oversized = package_with_icon("assets/icon.png", "image/png", png(4097, 1));
+    assert_eq!(
+        ValidatedPackage::read(oversized, None, PackageLimits::default()).err(),
+        Some(PackageError::Limit)
+    );
+}
+
+#[test]
+fn obsolete_manifest_fields_are_rejected_without_aliases() {
+    let manifest = serde_json::json!({
+        "manifestVersion": 3,
+        "name": "example",
+        "displayName": "Example",
+        "publisher": "test",
+        "version": "1.0.0",
+        "description": "Example",
+        "license": "MIT",
+        "engines": {"codex-proxy-rs": ">=1.0.0, <2.0.0"},
+        "main": "bin/worker",
+        "runtime": "trustedProcess",
+        "capabilities": [{"capability":"request_normalizer"}]
+    });
+    let archive = crate::support::archive(BTreeMap::from([(
+        "plugin.json".to_owned(),
+        serde_json::to_vec(&manifest).unwrap(),
+    )]));
+    assert_eq!(
+        ValidatedPackage::read(archive, None, PackageLimits::default()).err(),
+        Some(PackageError::Archive)
+    );
+}
+
+#[test]
+fn source_manifest_cannot_be_installed_without_package_metadata() {
+    let manifest = serde_json::json!({
+        "manifestVersion": 3,
+        "name": "example",
+        "displayName": "Example",
+        "publisher": "test",
+        "version": "1.0.0",
+        "description": "Example",
+        "license": "MIT",
+        "engines": {"codex-proxy-rs": "*"},
+        "main": "bin/worker",
+        "runtime": "trustedProcess",
+        "contributes": {}
+    });
+    let archive = crate::support::archive(BTreeMap::from([(
+        "plugin.json".to_owned(),
+        serde_json::to_vec(&manifest).unwrap(),
+    )]));
+    assert_eq!(
+        ValidatedPackage::read(archive, None, PackageLimits::default()).err(),
+        Some(PackageError::Manifest(
+            gateway_plugin_sdk::ManifestError::Invalid
+        ))
+    );
+}
+
+#[test]
+fn duplicate_contribution_keys_are_rejected_before_map_overwrite() {
+    let manifest = br#"{
+        "manifestVersion":3,
+        "name":"example",
+        "displayName":"Example",
+        "publisher":"test",
+        "version":"1.0.0",
+        "description":"Example",
+        "license":"MIT",
+        "engines":{"codex-proxy-rs":"*"},
+        "main":"bin/worker",
+        "runtime":"trustedProcess",
+        "contributes":{
+            "middleware":{"id":"test.example.first","version":1,"stages":["request"]},
+            "middleware":{"id":"test.example.second","version":1,"stages":["request"]}
+        }
+    }"#;
+    let archive = crate::support::archive(BTreeMap::from([(
+        "plugin.json".to_owned(),
+        manifest.to_vec(),
+    )]));
+    assert_eq!(
+        ValidatedPackage::read(archive, None, PackageLimits::default()).err(),
+        Some(PackageError::Archive)
+    );
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/rpc/dispatch.rs b/backend/crates/gateway-plugin/runtime/tests/rpc/dispatch.rs
new file mode 100644
index 000000000..605d3df60
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/rpc/dispatch.rs
@@ -0,0 +1,238 @@
+use std::{
+    sync::{
+        Arc,
+        atomic::{AtomicUsize, Ordering},
+    },
+    time::Duration,
+};
+
+use futures::future::BoxFuture;
+use gateway_plugin_runtime::{
+    CallbackHandler, PackageLimits, RpcError, RpcLimits, RpcReply, RpcSession, ValidatedPackage,
+};
+use gateway_plugin_sdk::{CallContext, ErrorCode, Handshake, Permission, PluginFault, Stage};
+use serde_json::json;
+
+const CALLBACK_PERMISSIONS: [(&str, Permission); 8] = [
+    ("host.http.do", Permission::Network),
+    ("host.model.execute", Permission::Models),
+    ("host.auth.list", Permission::Accounts),
+    ("host.auth.get", Permission::Accounts),
+    ("host.auth.save", Permission::Accounts),
+    ("host.affinity.lookup", Permission::Requests),
+    ("host.models.list", Permission::Models),
+    ("host.keys.list", Permission::Models),
+];
+
+#[derive(Default)]
+struct Callbacks {
+    called: AtomicUsize,
+}
+
+impl CallbackHandler for Callbacks {
+    fn call(
+        &self,
+        _context: CallContext,
+        _method: String,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+    ) -> BoxFuture<'static, Result<RpcReply, PluginFault>> {
+        self.called.fetch_add(1, Ordering::Relaxed);
+        Box::pin(async move {
+            Ok(RpcReply {
+                result: params,
+                payload,
+            })
+        })
+    }
+}
+
+async fn session(callbacks: Arc<Callbacks>) -> (tempfile::TempDir, Arc<RpcSession>) {
+    session_with_permissions(callbacks, Permission::ALL.to_vec()).await
+}
+
+async fn session_with_permissions(
+    callbacks: Arc<Callbacks>,
+    permissions: Vec<Permission>,
+) -> (tempfile::TempDir, Arc<RpcSession>) {
+    let cache = tempfile::tempdir().unwrap();
+    let package = Arc::new(
+        ValidatedPackage::read(
+            crate::support::package_with_permissions(crate::support::worker(), permissions.clone()),
+            None,
+            PackageLimits::default(),
+        )
+        .unwrap(),
+    );
+    let prepared = Arc::new(
+        package
+            .prepare(cache.path(), &"1.0.0".parse().unwrap())
+            .unwrap(),
+    );
+    let handshake = Handshake {
+        protocol_version: gateway_plugin_sdk::PROTOCOL_VERSION,
+        artifact_sha256: package.digest().into(),
+        plugin_id: package.manifest().plugin_id().unwrap(),
+        instance_id: "test-instance".into(),
+        generation: 1,
+        incarnation: uuid::Uuid::new_v4().to_string(),
+        configuration: json!({}),
+        contributes: gateway_plugin_sdk::Contributions::new(),
+        permissions,
+    };
+    let processes =
+        gateway_host::process::ProcessSupervisor::new(std::num::NonZeroUsize::new(128).unwrap());
+    let session = RpcSession::start(
+        prepared,
+        handshake,
+        RpcLimits::default(),
+        &processes,
+        callbacks,
+    )
+    .await
+    .unwrap();
+    (cache, Arc::new(session))
+}
+
+async fn invoke_callback(
+    session: &RpcSession,
+    stage: Stage,
+    method: &str,
+) -> Result<RpcReply, RpcError> {
+    session
+        .call(
+            "callback_method",
+            session.context(stage, Duration::from_secs(2)),
+            json!({"method": method}),
+            vec![],
+        )
+        .await
+}
+
+fn assert_permission_denied(reply: Result<RpcReply, RpcError>) {
+    assert!(matches!(
+        reply,
+        Err(RpcError::Remote(PluginFault {
+            code: ErrorCode::PermissionDenied,
+            ..
+        }))
+    ));
+}
+
+#[tokio::test]
+async fn public_management_cannot_inherit_any_granted_host_callback_permission() {
+    let callbacks = Arc::new(Callbacks::default());
+    let (_cache, session) = session(Arc::clone(&callbacks)).await;
+    for (method, _) in CALLBACK_PERMISSIONS {
+        assert_permission_denied(invoke_callback(&session, Stage::PublicManagement, method).await);
+    }
+    for method in ["host.log", "host.state.get"] {
+        assert_permission_denied(invoke_callback(&session, Stage::PublicManagement, method).await);
+    }
+    assert_eq!(callbacks.called.load(Ordering::Relaxed), 0);
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test]
+async fn registration_and_configuration_reject_network_and_model_callbacks() {
+    let callbacks = Arc::new(Callbacks::default());
+    let (_cache, session) = session(Arc::clone(&callbacks)).await;
+
+    for stage in [Stage::Registration, Stage::Configuration] {
+        assert_permission_denied(invoke_callback(&session, stage, "host.http.do").await);
+        assert_permission_denied(invoke_callback(&session, stage, "host.model.execute").await);
+    }
+    assert_eq!(callbacks.called.load(Ordering::Relaxed), 0);
+
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test]
+async fn active_stages_use_resource_domains_without_operation_whitelists() {
+    let callbacks = Arc::new(Callbacks::default());
+    let (_cache, session) = session(Arc::clone(&callbacks)).await;
+
+    for stage in [
+        Stage::Routing,
+        Stage::Scheduling,
+        Stage::Request,
+        Stage::Attempt,
+        Stage::Observation,
+        Stage::Authentication,
+        Stage::Execution,
+        Stage::Management,
+        Stage::Maintenance,
+        Stage::CommandLine,
+    ] {
+        for (method, _) in CALLBACK_PERMISSIONS {
+            assert!(
+                invoke_callback(&session, stage, method).await.is_ok(),
+                "{method} domain should be available during {stage:?}"
+            );
+        }
+    }
+    assert_eq!(
+        callbacks.called.load(Ordering::Relaxed),
+        10 * CALLBACK_PERMISSIONS.len()
+    );
+
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test]
+async fn missing_domains_are_denied_before_dispatch() {
+    let callbacks = Arc::new(Callbacks::default());
+    let (_cache, session) = session_with_permissions(Arc::clone(&callbacks), vec![]).await;
+
+    for (method, _) in CALLBACK_PERMISSIONS {
+        assert_permission_denied(invoke_callback(&session, Stage::Observation, method).await);
+    }
+    assert_eq!(callbacks.called.load(Ordering::Relaxed), 0);
+
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test]
+async fn logs_and_own_state_are_infrastructure_without_permissions() {
+    let callbacks = Arc::new(Callbacks::default());
+    let (_cache, session) = session_with_permissions(Arc::clone(&callbacks), vec![]).await;
+
+    for stage in [
+        Stage::Registration,
+        Stage::Configuration,
+        Stage::Observation,
+        Stage::Management,
+        Stage::Authentication,
+    ] {
+        assert!(invoke_callback(&session, stage, "host.log").await.is_ok());
+        if matches!(stage, Stage::Registration | Stage::Configuration) {
+            assert_permission_denied(invoke_callback(&session, stage, "host.state.get").await);
+        } else {
+            assert!(
+                invoke_callback(&session, stage, "host.state.get")
+                    .await
+                    .is_ok()
+            );
+        }
+    }
+    assert_eq!(callbacks.called.load(Ordering::Relaxed), 8);
+
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test]
+async fn execution_allows_each_declared_callback_permission() {
+    let callbacks = Arc::new(Callbacks::default());
+    let (_cache, session) = session(Arc::clone(&callbacks)).await;
+
+    for (method, _) in CALLBACK_PERMISSIONS {
+        let reply = invoke_callback(&session, Stage::Execution, method).await;
+        assert!(reply.is_ok(), "{method} should be allowed during execution");
+    }
+    assert_eq!(
+        callbacks.called.load(Ordering::Relaxed),
+        CALLBACK_PERMISSIONS.len()
+    );
+
+    session.shutdown(Duration::from_secs(1)).await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/rpc/mod.rs b/backend/crates/gateway-plugin/runtime/tests/rpc/mod.rs
new file mode 100644
index 000000000..b1f386708
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/rpc/mod.rs
@@ -0,0 +1,2 @@
+mod dispatch;
+mod session;
diff --git a/backend/crates/gateway-plugin/runtime/tests/rpc/session.rs b/backend/crates/gateway-plugin/runtime/tests/rpc/session.rs
new file mode 100644
index 000000000..f58e5e53b
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/rpc/session.rs
@@ -0,0 +1,648 @@
+use std::{
+    sync::{
+        Arc, Condvar, Mutex, Weak,
+        atomic::{AtomicUsize, Ordering},
+    },
+    time::Duration,
+};
+
+use futures::future::BoxFuture;
+use gateway_plugin_runtime::{
+    CallbackHandler, PackageLimits, RpcError, RpcLimits, RpcReply, RpcSession, ValidatedPackage,
+};
+use gateway_plugin_sdk::{CallContext, ErrorCode, Handshake, Permission, PluginFault, Stage};
+use serde_json::json;
+use tokio::sync::{Barrier, Notify};
+
+#[derive(Default)]
+struct Callbacks {
+    called: AtomicUsize,
+    nested: Mutex<Option<Weak<RpcSession>>>,
+}
+
+#[derive(Default)]
+struct BlockingCallbacks {
+    started: Arc<Notify>,
+    dropped: Arc<std::sync::atomic::AtomicBool>,
+}
+
+#[derive(Default)]
+struct LifecycleCallbacks {
+    begun: AtomicUsize,
+    finished: AtomicUsize,
+}
+
+struct CallbackDrop(Arc<std::sync::atomic::AtomicBool>);
+
+#[derive(Default)]
+struct GatedFirstBegin {
+    entered: Notify,
+    released: Mutex<bool>,
+    release: Condvar,
+}
+
+impl GatedFirstBegin {
+    fn release(&self) {
+        *self.released.lock().unwrap() = true;
+        self.release.notify_one();
+    }
+}
+
+impl Drop for CallbackDrop {
+    fn drop(&mut self) {
+        self.0.store(true, Ordering::Release);
+    }
+}
+
+impl CallbackHandler for BlockingCallbacks {
+    fn call(
+        &self,
+        _context: CallContext,
+        _method: String,
+        _params: serde_json::Value,
+        _payload: Vec<u8>,
+    ) -> BoxFuture<'static, Result<RpcReply, PluginFault>> {
+        let started = Arc::clone(&self.started);
+        let dropped = Arc::clone(&self.dropped);
+        Box::pin(async move {
+            let _drop = CallbackDrop(dropped);
+            started.notify_one();
+            futures::future::pending().await
+        })
+    }
+}
+
+impl CallbackHandler for LifecycleCallbacks {
+    fn begin(&self, _context: &CallContext) {
+        self.begun.fetch_add(1, Ordering::Relaxed);
+    }
+
+    fn finish(&self, _context: &CallContext) {
+        self.finished.fetch_add(1, Ordering::Relaxed);
+    }
+
+    fn call(
+        &self,
+        _context: CallContext,
+        _method: String,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+    ) -> BoxFuture<'static, Result<RpcReply, PluginFault>> {
+        Box::pin(async move {
+            Ok(RpcReply {
+                result: params,
+                payload,
+            })
+        })
+    }
+}
+
+impl CallbackHandler for GatedFirstBegin {
+    fn begin(&self, context: &CallContext) {
+        if context.call_id == 1 {
+            self.entered.notify_one();
+            let released = self.released.lock().unwrap();
+            drop(
+                self.release
+                    .wait_while(released, |released| !*released)
+                    .unwrap(),
+            );
+        }
+    }
+
+    fn call(
+        &self,
+        _context: CallContext,
+        _method: String,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+    ) -> BoxFuture<'static, Result<RpcReply, PluginFault>> {
+        Box::pin(async move {
+            Ok(RpcReply {
+                result: params,
+                payload,
+            })
+        })
+    }
+}
+
+impl CallbackHandler for Callbacks {
+    fn call(
+        &self,
+        context: CallContext,
+        _method: String,
+        params: serde_json::Value,
+        payload: Vec<u8>,
+    ) -> BoxFuture<'static, Result<RpcReply, PluginFault>> {
+        self.called.fetch_add(1, Ordering::Relaxed);
+        let nested = self.nested.lock().unwrap().as_ref().and_then(Weak::upgrade);
+        Box::pin(async move {
+            if let Some(nested) = nested {
+                nested
+                    .call("echo", context, params, payload)
+                    .await
+                    .map_err(|_| PluginFault::new(ErrorCode::Fault, "nested call failed"))
+            } else {
+                Ok(RpcReply {
+                    result: params,
+                    payload,
+                })
+            }
+        })
+    }
+}
+
+async fn session<C>(
+    permissions: Vec<Permission>,
+    callbacks: Arc<C>,
+) -> (tempfile::TempDir, Arc<RpcSession>)
+where
+    C: CallbackHandler + 'static,
+{
+    let cache = tempfile::tempdir().unwrap();
+    let package = Arc::new(
+        ValidatedPackage::read(
+            crate::support::package_with_permissions(crate::support::worker(), permissions.clone()),
+            None,
+            PackageLimits::default(),
+        )
+        .unwrap(),
+    );
+    let prepared = Arc::new(
+        package
+            .prepare(cache.path(), &"1.0.0".parse().unwrap())
+            .unwrap(),
+    );
+    let handshake = Handshake {
+        protocol_version: gateway_plugin_sdk::PROTOCOL_VERSION,
+        artifact_sha256: package.digest().into(),
+        plugin_id: package.manifest().plugin_id().unwrap(),
+        instance_id: "test-instance".into(),
+        generation: 1,
+        incarnation: uuid::Uuid::new_v4().to_string(),
+        configuration: json!({}),
+        contributes: gateway_plugin_sdk::Contributions::new(),
+        permissions,
+    };
+    let processes =
+        gateway_host::process::ProcessSupervisor::new(std::num::NonZeroUsize::new(128).unwrap());
+    let session = RpcSession::start(
+        prepared,
+        handshake,
+        RpcLimits::default(),
+        &processes,
+        callbacks,
+    )
+    .await
+    .unwrap();
+    (cache, Arc::new(session))
+}
+
+#[tokio::test]
+async fn shutdown_returns_after_in_flight_callback_future_is_dropped() {
+    let callbacks = Arc::new(BlockingCallbacks::default());
+    let (_cache, session) = session(vec![], Arc::clone(&callbacks)).await;
+    let callback_started = callbacks.started.notified();
+    let calling = {
+        let session = Arc::clone(&session);
+        tokio::spawn(async move {
+            session
+                .call(
+                    "callback",
+                    session.context(Stage::Management, Duration::from_secs(30)),
+                    json!({}),
+                    vec![],
+                )
+                .await
+        })
+    };
+    callback_started.await;
+
+    session.quiesce();
+    tokio::time::timeout(
+        Duration::from_secs(2),
+        session.shutdown(Duration::from_secs(1)),
+    )
+    .await
+    .expect("session shutdown");
+    assert!(callbacks.dropped.load(Ordering::Acquire));
+    assert!(matches!(calling.await.unwrap(), Err(RpcError::Closed)));
+}
+
+#[tokio::test]
+async fn real_process_round_trips_raw_bytes_and_reentrant_callbacks() {
+    let callbacks = Arc::new(Callbacks::default());
+    let (_cache, session) = session(vec![], Arc::clone(&callbacks)).await;
+    assert_eq!(
+        session
+            .context(Stage::Registration, Duration::MAX)
+            .timeout_ms,
+        u64::try_from(RpcLimits::default().maximum_call_timeout.as_millis()).unwrap()
+    );
+    *callbacks.nested.lock().unwrap() = Some(Arc::downgrade(&session));
+    let context = session.context(Stage::Management, Duration::from_secs(2));
+    let reply = session
+        .call(
+            "callback",
+            context,
+            json!({"hello": "世界"}),
+            vec![0, 255, 128],
+        )
+        .await
+        .unwrap();
+    assert_eq!(reply.result, json!({"hello": "世界"}));
+    assert_eq!(reply.payload, [0, 255, 128]);
+    assert_eq!(callbacks.called.load(Ordering::Relaxed), 1);
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test]
+async fn slow_management_call_does_not_block_an_independent_call() {
+    let (_cache, session) = session(vec![], Arc::new(Callbacks::default())).await;
+    let context = session.context(Stage::Management, Duration::from_secs(2));
+    let slow_session = Arc::clone(&session);
+    let slow =
+        tokio::spawn(async move { slow_session.call("slow", context, json!({}), vec![]).await });
+    tokio::time::sleep(Duration::from_millis(40)).await;
+    let fast = session.call(
+        "echo",
+        session.context(Stage::Execution, Duration::from_millis(250)),
+        json!({}),
+        vec![],
+    );
+    assert!(fast.await.is_ok());
+    assert!(!slow.is_finished());
+    assert!(slow.await.unwrap().is_ok());
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn concurrent_calls_keep_their_wire_ids_monotonic() {
+    let callbacks = Arc::new(GatedFirstBegin::default());
+    let entered = callbacks.entered.notified();
+    let (_cache, session) = session(vec![], Arc::clone(&callbacks)).await;
+    let ready = Arc::new(Barrier::new(17));
+    let mut calls = Vec::with_capacity(16);
+    for index in 0..16 {
+        let session = Arc::clone(&session);
+        let ready = Arc::clone(&ready);
+        calls.push(tokio::spawn(async move {
+            ready.wait().await;
+            if index % 2 == 0 {
+                session
+                    .call(
+                        "echo",
+                        session.context(Stage::Execution, Duration::from_secs(5)),
+                        json!({"index": index}),
+                        vec![],
+                    )
+                    .await?;
+            } else {
+                let mut stream = session
+                    .call_stream(
+                        "stream",
+                        session.context(Stage::Execution, Duration::from_secs(5)),
+                        json!({"index": index}),
+                        vec![],
+                    )
+                    .await?;
+                while stream.next().await?.is_some() {}
+            }
+            Ok::<(), RpcError>(())
+        }));
+    }
+    ready.wait().await;
+    entered.await;
+    // 旧实现会在 begin 前分配后续 ID；等其他线程进入该窗口后再释放首调用。
+    tokio::time::sleep(Duration::from_millis(20)).await;
+    callbacks.release();
+    for call in calls {
+        assert!(call.await.unwrap().is_ok());
+    }
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn cancelling_a_call_waiting_for_send_order_does_not_block_following_calls() {
+    let callbacks = Arc::new(GatedFirstBegin::default());
+    let entered = callbacks.entered.notified();
+    let (_cache, session) = session(vec![], Arc::clone(&callbacks)).await;
+    let first = {
+        let session = Arc::clone(&session);
+        tokio::spawn(async move {
+            session
+                .call(
+                    "echo",
+                    session.context(Stage::Execution, Duration::from_secs(2)),
+                    json!("first"),
+                    vec![],
+                )
+                .await
+        })
+    };
+    entered.await;
+
+    let queued = {
+        let session = Arc::clone(&session);
+        tokio::spawn(async move {
+            session
+                .call(
+                    "echo",
+                    session.context(Stage::Execution, Duration::from_secs(2)),
+                    json!("cancelled"),
+                    vec![],
+                )
+                .await
+        })
+    };
+    tokio::time::sleep(Duration::from_millis(20)).await;
+    queued.abort();
+    assert!(matches!(queued.await, Err(error) if error.is_cancelled()));
+
+    let following = {
+        let session = Arc::clone(&session);
+        tokio::spawn(async move {
+            session
+                .call(
+                    "echo",
+                    session.context(Stage::Execution, Duration::from_secs(2)),
+                    json!("following"),
+                    vec![],
+                )
+                .await
+        })
+    };
+    callbacks.release();
+    assert_eq!(first.await.unwrap().unwrap().result, json!("first"));
+    assert_eq!(following.await.unwrap().unwrap().result, json!("following"));
+    assert!(session.is_ready());
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn waiting_for_send_order_consumes_the_original_call_deadline() {
+    let callbacks = Arc::new(GatedFirstBegin::default());
+    let entered = callbacks.entered.notified();
+    let (_cache, session) = session(vec![], Arc::clone(&callbacks)).await;
+    let first = {
+        let session = Arc::clone(&session);
+        tokio::spawn(async move {
+            session
+                .call(
+                    "echo",
+                    session.context(Stage::Execution, Duration::from_secs(2)),
+                    json!("first"),
+                    vec![],
+                )
+                .await
+        })
+    };
+    entered.await;
+
+    let waiting = session
+        .call(
+            "echo",
+            session.context(Stage::Execution, Duration::from_millis(30)),
+            json!("expired"),
+            vec![],
+        )
+        .await;
+    assert!(matches!(waiting, Err(RpcError::Timeout)));
+
+    callbacks.release();
+    assert!(first.await.unwrap().is_ok());
+    assert!(
+        session
+            .call(
+                "echo",
+                session.context(Stage::Execution, Duration::from_secs(1)),
+                json!("following"),
+                vec![],
+            )
+            .await
+            .is_ok()
+    );
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test]
+async fn undeclared_callback_permission_never_reaches_the_host_handler() {
+    let callbacks = Arc::new(Callbacks::default());
+    let (_cache, session) = session(vec![], Arc::clone(&callbacks)).await;
+    let reply = session
+        .call(
+            "callback_method",
+            session.context(Stage::Management, Duration::from_secs(2)),
+            json!({"method":"host.http.do"}),
+            vec![],
+        )
+        .await;
+    assert!(matches!(
+        reply,
+        Err(RpcError::Remote(PluginFault {
+            code: ErrorCode::PermissionDenied,
+            ..
+        }))
+    ));
+    assert_eq!(callbacks.called.load(Ordering::Relaxed), 0);
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test]
+async fn unknown_parent_cannot_borrow_another_calls_permissions() {
+    let callbacks = Arc::new(Callbacks::default());
+    let (_cache, session) = session(vec![], Arc::clone(&callbacks)).await;
+    let reply = session
+        .call(
+            "forged_callback",
+            session.context(Stage::Management, Duration::from_secs(2)),
+            json!({}),
+            vec![],
+        )
+        .await;
+    assert!(matches!(reply, Err(RpcError::Protocol)));
+    assert_eq!(callbacks.called.load(Ordering::Relaxed), 0);
+}
+
+#[tokio::test]
+async fn explicit_policy_denial_keeps_its_error_kind_and_status() {
+    let (_cache, session) = session(vec![], Arc::new(Callbacks::default())).await;
+    let reply = session
+        .call(
+            "deny",
+            session.context(Stage::Request, Duration::from_secs(2)),
+            json!({}),
+            vec![],
+        )
+        .await;
+    assert!(matches!(
+        reply,
+        Err(RpcError::Remote(PluginFault {
+            code: ErrorCode::Rejected,
+            http_status: Some(403),
+            ..
+        }))
+    ));
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test]
+async fn ignored_cancellation_closes_the_incarnation_and_settles_other_calls() {
+    let (_cache, session) = session(vec![], Arc::new(Callbacks::default())).await;
+    let first = session.call(
+        "hang_uncancellable",
+        session.context(Stage::Execution, Duration::from_millis(100)),
+        json!({}),
+        vec![],
+    );
+    let second = session.call(
+        "hang",
+        session.context(Stage::Execution, Duration::from_secs(2)),
+        json!({}),
+        vec![],
+    );
+    let (first, second) = tokio::join!(first, second);
+    assert!(matches!(first, Err(RpcError::Timeout)));
+    assert!(matches!(second, Err(RpcError::Timeout)));
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test]
+async fn child_crash_fails_the_call_without_waiting_for_its_deadline() {
+    let (_cache, session) = session(vec![], Arc::new(Callbacks::default())).await;
+    let call = session.call(
+        "crash",
+        session.context(Stage::Execution, Duration::from_secs(30)),
+        json!({}),
+        vec![],
+    );
+    let result = tokio::time::timeout(Duration::from_secs(2), call)
+        .await
+        .unwrap();
+    assert!(matches!(result, Err(RpcError::Closed)));
+}
+
+#[tokio::test]
+async fn malformed_worker_frames_fail_boundedly_and_release_call_resources() {
+    for method in ["malformed_truncated_frame", "malformed_frame_length"] {
+        let callbacks = Arc::new(LifecycleCallbacks::default());
+        let (_cache, session) = session(vec![], Arc::clone(&callbacks)).await;
+        let result = tokio::time::timeout(
+            Duration::from_secs(2),
+            session.call(
+                method,
+                session.context(Stage::Execution, Duration::from_secs(30)),
+                json!({}),
+                vec![],
+            ),
+        )
+        .await
+        .expect("malformed worker output must fail within the process boundary");
+        assert!(matches!(result, Err(RpcError::Closed)));
+        assert!(!session.is_ready());
+        assert_eq!(callbacks.begun.load(Ordering::Relaxed), 1);
+        assert_eq!(callbacks.finished.load(Ordering::Relaxed), 1);
+        session.shutdown(Duration::from_secs(1)).await;
+    }
+}
+
+#[tokio::test]
+async fn slow_stream_consumer_backpressures_the_child_without_blocking_control_calls() {
+    let (_cache, session) = session(vec![], Arc::new(Callbacks::default())).await;
+    let mut stream = session
+        .call_stream(
+            "stream",
+            session.context(Stage::Execution, Duration::from_secs(5)),
+            json!({}),
+            vec![],
+        )
+        .await
+        .unwrap();
+    tokio::time::sleep(Duration::from_millis(100)).await;
+    // 消费者停止读取时对端会耗尽窗口；另一个请求仍能通过独立读写循环完成。
+    let echo = session
+        .call(
+            "echo",
+            session.context(Stage::Management, Duration::from_millis(500)),
+            json!("ready"),
+            vec![],
+        )
+        .await
+        .unwrap();
+    assert_eq!(echo.result, json!("ready"));
+    let mut count = 0;
+    while let Some(chunk) = stream.next().await.unwrap() {
+        assert_eq!(chunk, vec![count as u8; 8192]);
+        count += 1;
+    }
+    assert_eq!(count, 128);
+    assert!(stream.next().await.unwrap().is_none());
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test]
+async fn stream_window_and_sequence_violations_fail_closed() {
+    for method in ["stream_overflow", "stream_sequence"] {
+        let (_cache, session) = session(vec![], Arc::new(Callbacks::default())).await;
+        let mut stream = session
+            .call_stream(
+                method,
+                session.context(Stage::Execution, Duration::from_secs(2)),
+                json!({}),
+                vec![],
+            )
+            .await
+            .unwrap();
+        assert!(matches!(stream.next().await, Err(RpcError::Protocol)));
+        session.shutdown(Duration::from_secs(1)).await;
+    }
+}
+
+#[tokio::test]
+async fn dropping_a_backpressured_stream_cancels_only_that_call() {
+    let (_cache, session) = session(vec![], Arc::new(Callbacks::default())).await;
+    let stream = session
+        .call_stream(
+            "stream",
+            session.context(Stage::Execution, Duration::from_secs(5)),
+            json!({}),
+            vec![],
+        )
+        .await
+        .unwrap();
+    drop(stream);
+    let reply = session
+        .call(
+            "echo",
+            session.context(Stage::Execution, Duration::from_secs(1)),
+            json!({}),
+            vec![],
+        )
+        .await;
+    assert!(reply.is_ok());
+    tokio::time::sleep(Duration::from_millis(300)).await;
+    assert!(session.is_ready());
+    session.shutdown(Duration::from_secs(1)).await;
+}
+
+#[tokio::test]
+async fn acknowledged_timeout_does_not_interrupt_another_call() {
+    let (_cache, session) = session(vec![], Arc::new(Callbacks::default())).await;
+    let first = session.call(
+        "hang",
+        session.context(Stage::Management, Duration::from_millis(100)),
+        json!({}),
+        vec![],
+    );
+    let second = session.call(
+        "slow",
+        session.context(Stage::Management, Duration::from_secs(2)),
+        json!("survived"),
+        vec![],
+    );
+    let (first, second) = tokio::join!(first, second);
+    assert!(matches!(first, Err(RpcError::Timeout)));
+    assert_eq!(second.unwrap().result, json!("survived"));
+    assert!(session.is_ready());
+    session.shutdown(Duration::from_secs(1)).await;
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/support/diagnostics.rs b/backend/crates/gateway-plugin/runtime/tests/support/diagnostics.rs
new file mode 100644
index 000000000..8d05e7c76
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/support/diagnostics.rs
@@ -0,0 +1,58 @@
+use std::{
+    collections::{BTreeMap, VecDeque},
+    sync::{Arc, Mutex},
+};
+
+#[derive(Clone, Default)]
+pub struct Diagnostics(Arc<Mutex<VecDeque<BTreeMap<String, String>>>>);
+
+impl Diagnostics {
+    pub fn install(&self) -> tracing::subscriber::DefaultGuard {
+        // 仅当前测试线程，不替换其他测试（尤其插件日志测试）的全局订阅者。
+        tracing::subscriber::set_default(self.clone())
+    }
+
+    pub fn records(&self) -> Vec<BTreeMap<String, String>> {
+        self.0.lock().unwrap().iter().cloned().collect()
+    }
+}
+
+struct Fields(BTreeMap<String, String>);
+
+impl tracing::field::Visit for Fields {
+    fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn std::fmt::Debug) {
+        self.0.insert(field.name().into(), format!("{value:?}"));
+    }
+}
+
+impl tracing::Subscriber for Diagnostics {
+    fn enabled(&self, metadata: &tracing::Metadata<'_>) -> bool {
+        metadata.is_event()
+            && metadata.level() <= &tracing::Level::WARN
+            && metadata.target().starts_with("gateway_plugin_runtime::")
+    }
+
+    fn new_span(&self, _: &tracing::span::Attributes<'_>) -> tracing::span::Id {
+        tracing::span::Id::from_u64(1)
+    }
+
+    fn record(&self, _: &tracing::span::Id, _: &tracing::span::Record<'_>) {}
+    fn record_follows_from(&self, _: &tracing::span::Id, _: &tracing::span::Id) {}
+    fn enter(&self, _: &tracing::span::Id) {}
+    fn exit(&self, _: &tracing::span::Id) {}
+
+    fn event(&self, event: &tracing::Event<'_>) {
+        if !self.enabled(event.metadata()) {
+            return;
+        }
+        let mut fields = Fields(BTreeMap::new());
+        event.record(&mut fields);
+        eprintln!("{}: {:?}", event.metadata().target(), fields.0);
+        let mut records = self.0.lock().unwrap();
+        // 压测和故障场景只保留最近的诊断，不积累无界日志。
+        if records.len() == 128 {
+            records.pop_front();
+        }
+        records.push_back(fields.0);
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/support/environment.rs b/backend/crates/gateway-plugin/runtime/tests/support/environment.rs
new file mode 100644
index 000000000..b5912095e
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/support/environment.rs
@@ -0,0 +1,1013 @@
+use std::{collections::BTreeMap, sync::Arc};
+
+use async_trait::async_trait;
+use gateway_admin::{
+    AdminConfig, ClientConfig, InitialAdminPassword,
+    model::{
+        AdminError, MutationActor, MutationContext,
+        client_distribution::CodexDesktopWindowsDownloads,
+        plugins::{
+            PluginSource,
+            distribution::{
+                DownloadedPlugin, GithubReleaseQuery, PluginRelease, PluginUpdateSource,
+                RemotePluginLocation, SourceCredential,
+            },
+            instances::{
+                PluginCapabilityBinding, PluginFailurePolicy, PluginFrontendIdentityBinding,
+                PluginInstance, PluginPermissionGrant,
+            },
+        },
+        pricing::PricingSyncPreview,
+        proxies::ProxyTestResult,
+        system::{SystemOperationAccepted, SystemUpdateDetail, SystemUpdateStatus, SystemVersion},
+    },
+    ports::{
+        client_distribution::ClientDistributionResolver,
+        plugin_accounts::PluginAccountAccess,
+        plugins::{PluginDistribution, PluginPackageInspector},
+        pricing::PricingSource,
+        provider::ProviderAdminRegistry,
+        proxy::ProxyProbe,
+        system::{SystemOperationError, SystemOperations, SystemUpdateEventStream},
+    },
+};
+use gateway_plugin_runtime::{
+    ContinuationDrainConfig, PackageInspector, PackageLimits, PluginRuntime, PluginRuntimeConfig,
+    RpcLimits,
+};
+use gateway_plugin_sdk::{Capability, Contributions, Stage};
+use gateway_store::{StoreBundle, StoreConfig};
+use serde_json::json;
+use sqlx::postgres::PgPoolOptions;
+
+pub struct Environment {
+    pub store: StoreBundle,
+    pub directory: tempfile::TempDir,
+    admin: sqlx::PgPool,
+    schema: String,
+    plugin_accounts: std::sync::Mutex<BTreeMap<usize, Arc<dyn PluginAccountAccess>>>,
+}
+
+#[derive(Debug, PartialEq, Eq)]
+pub struct ModelRequestLedgerFact {
+    pub request_id: String,
+    pub provider_kind: Option<String>,
+    pub request_kind: Option<String>,
+    pub subagent_kind: Option<String>,
+    pub outcome: String,
+    pub completed: bool,
+    pub cost_source: String,
+    pub cost_amount: Option<String>,
+    pub charged_amount: Option<String>,
+}
+
+type ModelRequestLedgerRow = (
+    String,
+    Option<String>,
+    Option<String>,
+    Option<String>,
+    String,
+    bool,
+    String,
+    Option<String>,
+    Option<String>,
+);
+
+impl Environment {
+    pub async fn client_key(&self, id: &str, plaintext: &str) {
+        self.client_key_with_limits(id, plaintext, gateway_core::policy::RateLimits::unlimited())
+            .await;
+    }
+
+    pub async fn client_key_with_limits(
+        &self,
+        id: &str,
+        plaintext: &str,
+        limits: gateway_core::policy::RateLimits,
+    ) {
+        self.client_key_with_limits_and_groups(id, plaintext, limits, Vec::new())
+            .await;
+    }
+
+    pub async fn client_key_with_limits_and_groups(
+        &self,
+        id: &str,
+        plaintext: &str,
+        limits: gateway_core::policy::RateLimits,
+        group_ids: Vec<gateway_core::routing::AccountGroupId>,
+    ) {
+        use gateway_admin::model::client_keys::NewClientKey;
+        use gateway_core::{engine::budget::ClientBudgetLimits, policy::ClientApiKeyId};
+
+        self.store
+            .admin_ports()
+            .client_keys()
+            .create_client_key(
+                NewClientKey {
+                    request_profile_overrides: BTreeMap::new(),
+                    id: ClientApiKeyId::new(id).unwrap(),
+                    name: format!("fixture {id}"),
+                    label: None,
+                    group_ids,
+                    limits,
+                    budget: ClientBudgetLimits::default(),
+                    plaintext: plaintext.to_owned(),
+                },
+                &mutation(),
+            )
+            .await
+            .unwrap();
+    }
+
+    pub async fn account_group_with_account(
+        &self,
+        account: &gateway_core::account::ProviderAccountId,
+    ) -> gateway_core::routing::AccountGroupId {
+        use gateway_admin::model::account_groups::{AccountGroupColor, NewAccountGroup};
+        use gateway_core::routing::AccountGroupId;
+
+        let id = AccountGroupId::new(format!("grp_{}", uuid::Uuid::new_v4().simple())).unwrap();
+        self.store
+            .admin_ports()
+            .account_groups()
+            .create_account_group(
+                NewAccountGroup {
+                    disable_fast: false,
+                    id: id.clone(),
+                    name: format!("fixture {}", id.as_str()),
+                    description: None,
+                    color: AccountGroupColor::parse("#2563EBFF").unwrap(),
+                },
+                &mutation(),
+            )
+            .await
+            .unwrap();
+        sqlx::query(sqlx::AssertSqlSafe(format!(
+            "insert into {}.account_group_accounts
+             (account_group_id, provider_account_id, created_at) values ($1, $2, now())",
+            self.schema
+        )))
+        .bind(id.as_str())
+        .bind(account.as_str())
+        .execute(&self.admin)
+        .await
+        .unwrap();
+        id
+    }
+
+    pub async fn set_account_group_enabled(
+        &self,
+        id: gateway_core::routing::AccountGroupId,
+        enabled: bool,
+    ) {
+        use gateway_admin::model::account_groups::SetAccountGroupEnabled;
+
+        self.store
+            .admin_ports()
+            .account_groups()
+            .set_account_group_enabled(SetAccountGroupEnabled { id, enabled }, &mutation())
+            .await
+            .unwrap();
+    }
+
+    pub async fn set_request_profile(
+        &self,
+        provider: &str,
+        profile: serde_json::Map<String, serde_json::Value>,
+    ) -> u64 {
+        let revision = sqlx::query_scalar::<_, i64>(sqlx::AssertSqlSafe(format!(
+            "update {}.runtime_settings
+             set provider_request_profiles_json = jsonb_set(
+                   provider_request_profiles_json, array[$1], $2::jsonb
+                 ),
+                 config_revision = config_revision + 1,
+                 updated_at = now()
+             where id = 1
+             returning config_revision",
+            self.schema
+        )))
+        .bind(provider)
+        .bind(sqlx::types::Json(profile))
+        .fetch_one(&self.admin)
+        .await
+        .unwrap();
+        u64::try_from(revision).unwrap()
+    }
+
+    pub async fn provider(
+        &self,
+        configuration: serde_json::Value,
+        grants: Vec<PluginPermissionGrant>,
+    ) -> (Arc<PluginRuntime>, gateway_core::CoreBundle) {
+        self.install_provider(configuration, grants).await;
+        self.runtime().await
+    }
+
+    pub async fn install_provider(
+        &self,
+        configuration: serde_json::Value,
+        grants: Vec<PluginPermissionGrant>,
+    ) {
+        let plugin_id = configuration
+            .get("plugin_id")
+            .and_then(serde_json::Value::as_str)
+            .map(str::to_owned)
+            .unwrap_or_else(|| {
+                format!(
+                    "test.{}",
+                    configuration
+                        .get("provider_id")
+                        .and_then(serde_json::Value::as_str)
+                        .unwrap_or("example")
+                )
+            });
+        let permissions = grants
+            .iter()
+            .map(|grant| serde_json::from_value(json!(grant.permission)).unwrap())
+            .collect();
+        let mut contributes = Contributions::from([
+            super::contribution_for_id(
+                &plugin_id,
+                Capability::Executor,
+                vec![Stage::Execution],
+                configuration
+                    .get("input_formats")
+                    .map(|value| serde_json::from_value(value.clone()).unwrap())
+                    .unwrap_or_else(|| vec!["openai".into()]),
+                configuration
+                    .get("output_formats")
+                    .map(|value| serde_json::from_value(value.clone()).unwrap())
+                    .unwrap_or_else(|| vec!["canonical".into()]),
+            ),
+            super::contribution_for_id(
+                &plugin_id,
+                Capability::Authentication,
+                Capability::Authentication.fixed_stages().to_vec(),
+                vec![],
+                vec![],
+            ),
+        ]);
+        if configuration.get("quota_url").is_some() {
+            contributes.extend([super::contribution_for_id(
+                &plugin_id,
+                Capability::Quota,
+                Capability::Quota.fixed_stages().to_vec(),
+                vec![],
+                vec![],
+            )]);
+        }
+        let maintenance = configuration["maintenance"].as_bool().unwrap_or(false);
+        if maintenance {
+            contributes.extend([super::contribution_for_id(
+                &plugin_id,
+                Capability::Maintenance,
+                vec![Stage::Maintenance],
+                vec![],
+                vec![],
+            )]);
+        }
+        if configuration.get("request_profile_refresh").is_some() {
+            contributes.extend([super::contribution_for_id(
+                &plugin_id,
+                Capability::RequestProfile,
+                vec![Stage::Maintenance],
+                vec![],
+                vec![],
+            )]);
+        }
+        if configuration.get("account_operations").is_some() {
+            contributes.extend([super::contribution_for_id(
+                &plugin_id,
+                Capability::AccountManagement,
+                Capability::AccountManagement.fixed_stages().to_vec(),
+                vec![],
+                vec![],
+            )]);
+        }
+        if configuration.get("billing").is_some() {
+            contributes.extend([super::contribution_for_id(
+                &plugin_id,
+                Capability::Billing,
+                vec![Stage::Execution],
+                vec![],
+                vec![],
+            )]);
+        }
+        if configuration.get("model_discovery").is_some() {
+            contributes.extend([super::contribution_for_id(
+                &plugin_id,
+                Capability::Models,
+                Capability::Models.fixed_stages().to_vec(),
+                vec![],
+                vec![],
+            )]);
+        }
+        if configuration.get("command_registration").is_some() {
+            contributes.extend([super::contribution_for_id(
+                &plugin_id,
+                Capability::CommandLine,
+                vec![Stage::CommandLine],
+                vec![],
+                vec![],
+            )]);
+        }
+        if configuration.get("management_registration").is_some() {
+            contributes.extend([super::contribution_for_id(
+                &plugin_id,
+                Capability::Management,
+                vec![Stage::Management],
+                vec![],
+                vec![],
+            )]);
+        }
+        let has_middleware = configuration.get("middleware_marker").is_some();
+        if has_middleware {
+            contributes.extend([super::contribution_for_id(
+                &plugin_id,
+                Capability::Middleware,
+                vec![Stage::Request],
+                vec!["openai".into()],
+                vec!["openai".into()],
+            )]);
+        }
+        let frontend_authentication = configuration
+            .get("frontend_authentication_result")
+            .is_some()
+            .then(|| {
+                (
+                    configuration["frontend_authentication_principal"]
+                        .as_str()
+                        .unwrap_or("fixture-principal")
+                        .to_owned(),
+                    configuration["frontend_authentication_client_key_id"]
+                        .as_str()
+                        .expect("frontend auth fixture client key ID")
+                        .to_owned(),
+                    configuration["frontend_authentication_exclusive"]
+                        .as_bool()
+                        .unwrap_or(false),
+                )
+            });
+        if frontend_authentication.is_some() {
+            contributes.extend([super::contribution_for_id(
+                &plugin_id,
+                Capability::FrontendAuthentication,
+                vec![Stage::Authentication],
+                vec![],
+                vec![],
+            )]);
+        }
+        let has_model_router = configuration.get("route_decision").is_some()
+            || configuration.get("nested_model_fixture").is_some()
+            || configuration.get("affinity_fixture").is_some();
+        if has_model_router {
+            contributes.extend([super::contribution_for_id(
+                &plugin_id,
+                Capability::ModelRouter,
+                vec![Stage::Routing],
+                vec![],
+                vec![],
+            )]);
+        }
+        let has_scheduler = configuration.get("schedule_decision").is_some()
+            || configuration.get("schedule_pick_index").is_some()
+            || configuration.get("schedule_fault").is_some();
+        if has_scheduler {
+            contributes.extend([super::contribution_for_id(
+                &plugin_id,
+                Capability::Scheduler,
+                vec![Stage::Scheduling],
+                vec![],
+                vec![],
+            )]);
+        }
+        let archive = super::package_with_contributions_for_id(
+            super::worker(),
+            &plugin_id,
+            permissions,
+            contributes,
+        );
+        let inspector = PackageInspector::new(PackageLimits::default(), "1.0.0".parse().unwrap());
+        let artifact = inspector
+            .inspect(Arc::clone(&archive), None)
+            .await
+            .unwrap_or_else(|error| {
+                let validation = gateway_plugin_runtime::ValidatedPackage::read(
+                    archive,
+                    None,
+                    PackageLimits::default(),
+                )
+                .err();
+                panic!("测试插件包校验失败：{error:?}; {validation:?}");
+            });
+        let store = self.store.admin_ports().plugins();
+        let mutation = mutation();
+        let installed = store
+            .install_artifact(artifact, PluginSource::Upload, &mutation)
+            .await
+            .unwrap();
+        let installed = store
+            .accept_artifact(&installed.artifact.metadata.sha256, &mutation)
+            .await
+            .unwrap();
+        let grants = installed
+            .artifact
+            .metadata
+            .requested_permissions
+            .iter()
+            .cloned()
+            .map(|permission| PluginPermissionGrant { permission })
+            .collect();
+        let instance = PluginInstance {
+            id: uuid::Uuid::new_v4().to_string(),
+            name: "provider".into(),
+            artifact_sha256: installed.artifact.metadata.sha256,
+            enabled: true,
+            trusted_process: true,
+            configuration,
+            secrets: BTreeMap::new(),
+            grants,
+            bindings: [
+                has_model_router.then(|| PluginCapabilityBinding {
+                    contribution: format!("{plugin_id}.modelRouter"),
+                    stage: "routing".into(),
+                    order: 0,
+                    failure_policy: PluginFailurePolicy::Reject,
+                    client_key_ids: vec![],
+                    account_group_ids: vec![],
+                    provider_ids: vec![],
+                    models: vec![],
+                    identity_bindings: vec![],
+                }),
+                maintenance.then(|| PluginCapabilityBinding {
+                    contribution: format!("{plugin_id}.maintenance"),
+                    stage: "maintenance".into(),
+                    order: 0,
+                    failure_policy: PluginFailurePolicy::Reject,
+                    client_key_ids: vec![],
+                    account_group_ids: vec![],
+                    provider_ids: vec![],
+                    models: vec![],
+                    identity_bindings: vec![],
+                }),
+                has_scheduler.then(|| PluginCapabilityBinding {
+                    contribution: format!("{plugin_id}.scheduler"),
+                    stage: "scheduling".into(),
+                    order: 0,
+                    failure_policy: PluginFailurePolicy::Reject,
+                    client_key_ids: vec![],
+                    account_group_ids: vec![],
+                    provider_ids: vec![],
+                    models: vec![],
+                    identity_bindings: vec![],
+                }),
+                frontend_authentication
+                    .as_ref()
+                    .map(|(principal, key_id, exclusive)| PluginCapabilityBinding {
+                        contribution: format!("{plugin_id}.frontendAuthentication"),
+                        stage: "authentication".into(),
+                        order: 0,
+                        failure_policy: if *exclusive {
+                            PluginFailurePolicy::Reject
+                        } else {
+                            PluginFailurePolicy::Delegate
+                        },
+                        client_key_ids: vec![],
+                        account_group_ids: vec![],
+                        provider_ids: vec![],
+                        models: vec![],
+                        identity_bindings: vec![PluginFrontendIdentityBinding {
+                            principal: principal.clone(),
+                            client_key_id: key_id.clone(),
+                        }],
+                    }),
+                has_middleware.then(|| PluginCapabilityBinding {
+                    contribution: format!("{plugin_id}.middleware"),
+                    stage: "request".into(),
+                    order: 0,
+                    failure_policy: PluginFailurePolicy::Reject,
+                    client_key_ids: vec![],
+                    account_group_ids: vec![],
+                    provider_ids: vec![],
+                    models: vec![],
+                    identity_bindings: vec![],
+                }),
+            ]
+            .into_iter()
+            .flatten()
+            .collect(),
+            revision: installed.config_revision,
+        };
+        store
+            .save_instance(instance, installed.config_revision, &mutation)
+            .await
+            .unwrap();
+    }
+
+    pub async fn runtime(&self) -> (Arc<PluginRuntime>, gateway_core::CoreBundle) {
+        self.runtime_with_ports(self.store.provider_ports()).await
+    }
+
+    pub async fn runtime_with_ports(
+        &self,
+        ports: gateway_core::provider_ports::ProviderStorePorts,
+    ) -> (Arc<PluginRuntime>, gateway_core::CoreBundle) {
+        self.runtime_with_ports_and_drain(ports, ContinuationDrainConfig::default())
+            .await
+    }
+
+    pub async fn runtime_with_continuation_drain(
+        &self,
+        drain: ContinuationDrainConfig,
+    ) -> (Arc<PluginRuntime>, gateway_core::CoreBundle) {
+        self.runtime_with_ports_and_drain(self.store.provider_ports(), drain)
+            .await
+    }
+
+    async fn runtime_with_ports_and_drain(
+        &self,
+        ports: gateway_core::provider_ports::ProviderStorePorts,
+        continuation_drain: ContinuationDrainConfig,
+    ) -> (Arc<PluginRuntime>, gateway_core::CoreBundle) {
+        let runtime = self.plugin_runtime(ports, continuation_drain);
+        let core = gateway_core::prepare(
+            self.store.core_ports(),
+            runtime.provider_registry(),
+            Some(runtime.clone()),
+            Some(runtime.observer_registry()),
+            Some(runtime.policy_registry()),
+            Some(runtime.middleware_registry()),
+            Some(runtime.frontend_authentication_registry()),
+        );
+        let access = gateway_admin::initialize_plugin_accounts(
+            runtime.admin_registry(core.snapshots()),
+            self.store.admin_ports().accounts(),
+            core.snapshot_control(),
+        );
+        runtime.bind_account_ports(&access).unwrap();
+        self.plugin_accounts
+            .lock()
+            .unwrap()
+            .insert(Arc::as_ptr(&runtime) as usize, access);
+        let core = core.activate().await.unwrap();
+        let nested_models = core.nested_model_execution_port();
+        let affinity_lookup = core.affinity_lookup_port();
+        runtime
+            .bind_model_ports(&nested_models, &affinity_lookup)
+            .unwrap();
+        (runtime, core)
+    }
+
+    pub async fn command_plane(
+        &self,
+    ) -> (Arc<PluginRuntime>, gateway_core::CoreCommandPlaneBundle) {
+        let runtime = self.plugin_runtime(
+            self.store.provider_ports(),
+            ContinuationDrainConfig::default(),
+        );
+        let core = gateway_core::prepare_command_plane(
+            self.store.core_ports(),
+            runtime.provider_registry(),
+            Some(runtime.clone()),
+            Some(runtime.observer_registry()),
+            Some(runtime.policy_registry()),
+            Some(runtime.middleware_registry()),
+        )
+        .activate()
+        .await
+        .unwrap();
+        runtime
+            .bind_model_ports(
+                &core.nested_model_execution_port(),
+                &core.affinity_lookup_port(),
+            )
+            .unwrap();
+        (runtime, core)
+    }
+
+    fn plugin_runtime(
+        &self,
+        ports: gateway_core::provider_ports::ProviderStorePorts,
+        continuation_drain: ContinuationDrainConfig,
+    ) -> Arc<PluginRuntime> {
+        Arc::new(
+            PluginRuntime::new(
+                self.store.admin_ports().plugins(),
+                self.store.admin_ports().plugin_state(),
+                PluginRuntimeConfig {
+                    cache_directory: self.directory.path().join("cache"),
+                    host_version: "1.0.0".parse().unwrap(),
+                    package_limits: PackageLimits::default(),
+                    rpc_limits: RpcLimits::default(),
+                    continuation_drain,
+                    restart_circuit: Default::default(),
+                },
+                gateway_core::engine::provider::ProviderRegistry::default(),
+                ProviderAdminRegistry::new([]).unwrap(),
+                Arc::new(gateway_host::outbound::HttpClient::new().unwrap()),
+                Arc::new(gateway_host::process::ProcessSupervisor::new(
+                    std::num::NonZeroUsize::new(128).unwrap(),
+                )),
+            )
+            .with_provider_ports(ports)
+            .with_network_policy(
+                gateway_host::outbound::NetworkPolicy::new(&[
+                    "127.0.0.0/8".into(),
+                    "::1/128".into(),
+                ])
+                .unwrap(),
+            ),
+        )
+    }
+
+    pub async fn bind_admin_accounts(
+        &self,
+        runtime: &Arc<PluginRuntime>,
+        core: &gateway_core::CoreBundle,
+    ) -> gateway_admin::AdminBundle {
+        let unavailable = Arc::new(UnusedAdminRuntime);
+        let access = self
+            .plugin_accounts
+            .lock()
+            .unwrap()
+            .remove(&(Arc::as_ptr(runtime) as usize))
+            .expect("runtime account access");
+        gateway_admin::initialize_with_plugin_accounts(
+            AdminConfig {
+                session_ttl_minutes: 60,
+                default_username: "plugin-test-admin".to_owned(),
+                default_password: InitialAdminPassword::new("plugin-test-password"),
+            },
+            ClientConfig::default(),
+            self.store.admin_ports(),
+            gateway_admin::AdminRuntimePorts {
+                plugin_preparation: runtime.clone(),
+                plugin_management: runtime.clone(),
+                published_snapshot: core.snapshots(),
+                plugin_distribution: unavailable.clone(),
+                plugin_inspector: Arc::new(PackageInspector::new(
+                    PackageLimits::default(),
+                    "1.0.0".parse().unwrap(),
+                )),
+                pricing_source: unavailable.clone(),
+                providers: runtime.admin_registry(core.snapshots()),
+                snapshot: core.snapshot_control(),
+                account_probe: core.account_probe(),
+                proxy_probe: unavailable.clone(),
+                client_distribution: unavailable.clone(),
+                system: unavailable,
+                client_key_verifier: core.client_key_verifier(),
+            },
+            access,
+        )
+        .await
+        .unwrap()
+    }
+
+    pub fn release_plugin_accounts(&self, runtime: &Arc<PluginRuntime>) {
+        self.plugin_accounts
+            .lock()
+            .unwrap()
+            .remove(&(Arc::as_ptr(runtime) as usize))
+            .expect("runtime account access");
+    }
+
+    pub async fn account(
+        &self,
+        proxy: Option<gateway_core::account::OutboundProxy>,
+    ) -> gateway_core::account::ProviderAccountId {
+        self.account_for("example", proxy).await
+    }
+
+    pub async fn account_for(
+        &self,
+        provider: &str,
+        proxy: Option<gateway_core::account::OutboundProxy>,
+    ) -> gateway_core::account::ProviderAccountId {
+        self.account_for_with_concurrency(provider, proxy, None)
+            .await
+    }
+
+    pub async fn account_for_with_concurrency(
+        &self,
+        provider: &str,
+        proxy: Option<gateway_core::account::OutboundProxy>,
+        maximum_concurrency: Option<u32>,
+    ) -> gateway_core::account::ProviderAccountId {
+        use gateway_core::{
+            account::{
+                AccountConcurrencyLimit, AccountWeight, CredentialRevision, CredentialState,
+                NewProviderAccount, PlaintextCredential, ProviderAccount, ProviderAccountId,
+                QuotaState,
+            },
+            routing::ProviderKind,
+        };
+        let id = ProviderAccountId::new(format!("acct_{}", uuid::Uuid::new_v4().simple())).unwrap();
+        let account = ProviderAccount::new(
+            id.clone(),
+            ProviderKind::new(provider).unwrap(),
+            "plugin account".into(),
+            None,
+            "api_key".into(),
+            CredentialRevision::new(1).unwrap(),
+            None,
+        )
+        .with_outbound_proxy(proxy)
+        .with_scheduling(
+            maximum_concurrency.and_then(AccountConcurrencyLimit::new),
+            AccountWeight::DEFAULT,
+        )
+        .with_account_facts(
+            true,
+            CredentialState::Ready,
+            QuotaState::unknown(),
+            None,
+            None,
+        );
+        self.store
+            .provider_ports()
+            .accounts()
+            .create_account(NewProviderAccount {
+                account,
+                credential: PlaintextCredential::new(
+                    json!({"key":"test-only"}).as_object().unwrap().clone(),
+                ),
+                model_access: None,
+            })
+            .await
+            .unwrap();
+        id
+    }
+
+    pub async fn create() -> Option<Self> {
+        Self::create_with_store_mode(false).await
+    }
+
+    pub async fn create_command() -> Option<Self> {
+        Self::create_with_store_mode(true).await
+    }
+
+    async fn create_with_store_mode(command_line: bool) -> Option<Self> {
+        let database = std::env::var("CPR_PLUGIN_TEST_DATABASE_URL").ok()?;
+        let redis = std::env::var("CPR_PLUGIN_TEST_REDIS_URL").expect("isolated plugin Redis URL");
+        let schema = format!("cpr_plugin_{}", uuid::Uuid::new_v4().simple());
+        let admin = PgPoolOptions::new()
+            .max_connections(1)
+            .connect(&database)
+            .await
+            .unwrap();
+        sqlx::raw_sql(sqlx::AssertSqlSafe(format!("create schema {schema}")))
+            .execute(&admin)
+            .await
+            .unwrap();
+        let mut database = url::Url::parse(&database).unwrap();
+        database
+            .query_pairs_mut()
+            .append_pair("options", &format!("-csearch_path={schema}"));
+        let connection = |mut url: url::Url| {
+            let password = url.password().expect("test password").to_owned();
+            url.set_password(None).unwrap();
+            json!({"url":url.as_str(), "password":password})
+        };
+        let mut config: StoreConfig = serde_json::from_value(json!({
+            "database":connection(database), "redis":connection(url::Url::parse(&redis).unwrap()),
+        }))
+        .unwrap();
+        let directory = tempfile::tempdir().unwrap();
+        config.resolve_and_validate(directory.path()).unwrap();
+        let store = if command_line {
+            gateway_store::initialize_command_line(config)
+                .await
+                .unwrap()
+        } else {
+            gateway_store::initialize(config).await.unwrap()
+        };
+        // 迁移可能已创建默认行；该场景只测租约释放，明确关闭相邻请求的间隔限制。
+        sqlx::raw_sql(sqlx::AssertSqlSafe(format!("insert into {schema}.runtime_settings(id, config_revision, request_interval_ms, updated_at) values (1,1,0,now()) on conflict (id) do update set request_interval_ms=0")))
+            .execute(&admin).await.unwrap();
+        Some(Self {
+            store,
+            directory,
+            admin,
+            schema,
+            plugin_accounts: std::sync::Mutex::new(BTreeMap::new()),
+        })
+    }
+
+    pub async fn close(self) {
+        drop(self.store);
+        sqlx::raw_sql(sqlx::AssertSqlSafe(format!(
+            "drop schema {} cascade",
+            self.schema
+        )))
+        .execute(&self.admin)
+        .await
+        .unwrap();
+        self.admin.close().await;
+    }
+
+    pub async fn administrator(&self, id: &str) {
+        sqlx::query(sqlx::AssertSqlSafe(format!("insert into {}.admin_users(id, password_hash, created_at, updated_at) values ($1, 'test-only-disabled-password', now(), now())", self.schema)))
+            .bind(id).execute(&self.admin).await.unwrap();
+    }
+
+    pub async fn audit_requests(&self, action: &str) -> Vec<String> {
+        sqlx::query_scalar(sqlx::AssertSqlSafe(format!(
+            "select admin_request_id from {}.admin_audit_events where action = $1 order by created_at",
+            self.schema
+        )))
+        .bind(action)
+        .fetch_all(&self.admin)
+        .await
+        .unwrap()
+    }
+
+    pub async fn bound_model_requests(&self, client_key_id: &str) -> Vec<(String, String)> {
+        sqlx::query_as(sqlx::AssertSqlSafe(format!(
+            "select request_kind, subagent_kind from {}.model_requests
+             where client_api_key_ref = $1 order by started_at, id",
+            self.schema
+        )))
+        .bind(client_key_id)
+        .fetch_all(&self.admin)
+        .await
+        .unwrap()
+    }
+
+    pub async fn model_request_ledger(&self, client_key_id: &str) -> Vec<ModelRequestLedgerFact> {
+        let rows: Vec<ModelRequestLedgerRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
+            "select model_request.id, model_request.provider_kind, model_request.request_kind,
+                    model_request.subagent_kind, model_request.outcome,
+                    model_request.completed_at is not null, model_request.cost_source,
+                    model_request.cost_amount::text, charge.amount_usd::text
+             from {}.model_requests model_request
+             left join {}.client_key_charge_events charge
+               on charge.request_id = model_request.id
+             where model_request.client_api_key_ref = $1
+             order by model_request.started_at, model_request.id",
+            self.schema, self.schema
+        )))
+        .bind(client_key_id)
+        .fetch_all(&self.admin)
+        .await
+        .unwrap();
+        rows.into_iter()
+            .map(
+                |(
+                    request_id,
+                    provider_kind,
+                    request_kind,
+                    subagent_kind,
+                    outcome,
+                    completed,
+                    cost_source,
+                    cost_amount,
+                    charged_amount,
+                )| ModelRequestLedgerFact {
+                    request_id,
+                    provider_kind,
+                    request_kind,
+                    subagent_kind,
+                    outcome,
+                    completed,
+                    cost_source,
+                    cost_amount,
+                    charged_amount,
+                },
+            )
+            .collect()
+    }
+
+    pub async fn wait_for_bound_model_requests(
+        &self,
+        client_key_id: &str,
+        expected: usize,
+    ) -> Vec<(String, String)> {
+        tokio::time::timeout(std::time::Duration::from_secs(3), async {
+            loop {
+                let requests = self.bound_model_requests(client_key_id).await;
+                if requests.len() >= expected {
+                    break requests;
+                }
+                tokio::time::sleep(std::time::Duration::from_millis(20)).await;
+            }
+        })
+        .await
+        .unwrap()
+    }
+}
+
+struct UnusedAdminRuntime;
+
+#[async_trait]
+impl PluginDistribution for UnusedAdminRuntime {
+    fn validate_source(&self, _: &PluginUpdateSource) -> Result<(), AdminError> {
+        Err(AdminError::unavailable("unused plugin distribution"))
+    }
+
+    fn validate_credential(&self, _: &SourceCredential) -> Result<(), AdminError> {
+        Err(AdminError::unavailable("unused plugin distribution"))
+    }
+
+    async fn query_release(
+        &self,
+        _: GithubReleaseQuery,
+        _: Vec<SourceCredential>,
+        _: Option<gateway_admin::model::plugins::distribution::PluginDistributionEgress>,
+    ) -> Result<PluginRelease, AdminError> {
+        Err(AdminError::unavailable("unused plugin distribution"))
+    }
+
+    async fn download(
+        &self,
+        _: RemotePluginLocation,
+        _: Vec<SourceCredential>,
+        _: Option<gateway_admin::model::plugins::distribution::PluginDistributionEgress>,
+    ) -> Result<DownloadedPlugin, AdminError> {
+        Err(AdminError::unavailable("unused plugin distribution"))
+    }
+}
+
+#[async_trait]
+impl PricingSource for UnusedAdminRuntime {
+    async fn fetch(&self) -> Result<PricingSyncPreview, AdminError> {
+        Err(AdminError::unavailable("unused pricing source"))
+    }
+}
+
+#[async_trait]
+impl ProxyProbe for UnusedAdminRuntime {
+    async fn test(&self, _: &gateway_core::account::OutboundProxy) -> ProxyTestResult {
+        panic!("unexpected proxy probe")
+    }
+}
+
+#[async_trait]
+impl ClientDistributionResolver for UnusedAdminRuntime {
+    async fn resolve_codex_desktop_windows(&self, _: bool) -> CodexDesktopWindowsDownloads {
+        CodexDesktopWindowsDownloads {
+            resolved_at: chrono::Utc::now(),
+            cached: false,
+            warning: None,
+            packages: Vec::new(),
+        }
+    }
+}
+
+#[async_trait]
+impl SystemOperations for UnusedAdminRuntime {
+    async fn version(&self) -> Result<SystemVersion, SystemOperationError> {
+        Err(unused_system())
+    }
+
+    async fn update_detail(&self, _: bool) -> Result<SystemUpdateDetail, SystemOperationError> {
+        Err(unused_system())
+    }
+
+    fn update_events(&self) -> SystemUpdateEventStream {
+        Box::pin(futures::stream::empty())
+    }
+
+    async fn perform_update(
+        &self,
+        _: Option<String>,
+        _: Arc<dyn gateway_admin::ports::system::SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError> {
+        Err(unused_system())
+    }
+
+    async fn update_status(&self) -> Result<SystemUpdateStatus, SystemOperationError> {
+        Err(unused_system())
+    }
+
+    async fn rollback(
+        &self,
+        _: Arc<dyn gateway_admin::ports::system::SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError> {
+        Err(unused_system())
+    }
+
+    async fn restart(&self) -> Result<SystemOperationAccepted, SystemOperationError> {
+        Err(unused_system())
+    }
+}
+
+fn unused_system() -> SystemOperationError {
+    SystemOperationError::new(
+        gateway_admin::ports::system::SystemOperationErrorKind::Internal,
+        "unused system operation",
+    )
+}
+
+pub fn mutation() -> MutationContext {
+    MutationContext {
+        actor: MutationActor::System,
+        request_id: "plugin-provider-test".into(),
+    }
+}
+
+pub fn account_grant(permission: &str) -> PluginPermissionGrant {
+    PluginPermissionGrant {
+        permission: permission.into(),
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/support/http.rs b/backend/crates/gateway-plugin/runtime/tests/support/http.rs
new file mode 100644
index 000000000..7ff868f03
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/support/http.rs
@@ -0,0 +1,91 @@
+use std::time::Duration;
+
+use serde_json::Value;
+use tokio::{
+    io::{AsyncReadExt as _, AsyncWriteExt as _},
+    net::TcpListener,
+    sync::oneshot,
+    task::JoinHandle,
+};
+
+/// 用明确的响应屏障验证并发顺序，不依赖数据库操作恰好快于固定延迟。
+pub struct GatedResponse {
+    uri: String,
+    received: Option<oneshot::Receiver<()>>,
+    release: Option<oneshot::Sender<()>>,
+    task: Option<JoinHandle<()>>,
+}
+
+impl GatedResponse {
+    pub async fn start(body: Value) -> Self {
+        Self::start_batch(body, 1).await
+    }
+
+    pub async fn start_batch(body: Value, requests: usize) -> Self {
+        assert!((1..=16).contains(&requests));
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let uri = format!("http://{}", listener.local_addr().unwrap());
+        let (received_tx, received) = oneshot::channel();
+        let (release, release_rx) = oneshot::channel();
+        let task = tokio::spawn(async move {
+            let sockets = futures::future::join_all((0..requests).map(|_| async {
+                let (mut socket, _) = listener.accept().await.unwrap();
+                let mut request = Vec::new();
+                let mut buffer = [0; 1024];
+                while !request.windows(4).any(|window| window == b"\r\n\r\n") {
+                    let count = socket.read(&mut buffer).await.unwrap();
+                    assert!(count > 0, "测试请求未发送完整请求头");
+                    request.extend_from_slice(&buffer[..count]);
+                    assert!(request.len() <= 16 * 1024, "测试请求头超出预算");
+                }
+                socket
+            }))
+            .await;
+            received_tx.send(()).unwrap();
+            release_rx.await.unwrap();
+            let body = serde_json::to_vec(&body).unwrap();
+            let headers = format!(
+                "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
+                body.len()
+            );
+            for mut socket in sockets {
+                socket.write_all(headers.as_bytes()).await.unwrap();
+                socket.write_all(&body).await.unwrap();
+                socket.shutdown().await.unwrap();
+            }
+        });
+        Self {
+            uri,
+            received: Some(received),
+            release: Some(release),
+            task: Some(task),
+        }
+    }
+
+    pub fn uri(&self) -> &str {
+        &self.uri
+    }
+
+    pub async fn received(&mut self) {
+        tokio::time::timeout(Duration::from_secs(5), self.received.take().unwrap())
+            .await
+            .expect("上游应收到请求后再进行并发变更")
+            .unwrap();
+    }
+
+    pub async fn respond(&mut self) {
+        self.release.take().unwrap().send(()).unwrap();
+        tokio::time::timeout(Duration::from_secs(5), self.task.take().unwrap())
+            .await
+            .expect("上游应在屏障解除后发送响应")
+            .unwrap();
+    }
+}
+
+impl Drop for GatedResponse {
+    fn drop(&mut self) {
+        if let Some(task) = self.task.take() {
+            task.abort();
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/support/middleware.rs b/backend/crates/gateway-plugin/runtime/tests/support/middleware.rs
new file mode 100644
index 000000000..290d34db3
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/support/middleware.rs
@@ -0,0 +1,38 @@
+use gateway_plugin_sdk::{
+    Capability, ContributionDeclaration, Contributions, Stage,
+    client::{MiddlewareCall, MiddlewarePlugin, PluginSession, SessionConfig},
+};
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let plugin = MiddlewarePlugin::new(
+        &Contributions::from([(
+            Capability::Middleware,
+            ContributionDeclaration {
+                id: "test.example.middleware".into(),
+                version: 1,
+                stages: vec![Stage::Request],
+                input_formats: vec!["openai".into()],
+                output_formats: vec!["openai".into()],
+            },
+        )]),
+        |call: MiddlewareCall| async move {
+            let mut response = call.next.run(call.request).await?;
+            response.append_header("x-sdk-plugin", b"active".to_vec());
+            response.body = response.body.map_frames(|mut frame| {
+                frame.payload.push(b' ');
+                Ok(vec![frame])
+            })?;
+            Ok(response)
+        },
+    )?;
+    PluginSession::accept(
+        tokio::io::stdin(),
+        tokio::io::stdout(),
+        SessionConfig::default(),
+    )
+    .await?
+    .run(plugin)
+    .await?;
+    Ok(())
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/support/mod.rs b/backend/crates/gateway-plugin/runtime/tests/support/mod.rs
new file mode 100644
index 000000000..e7e405a0a
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/support/mod.rs
@@ -0,0 +1,212 @@
+use std::{
+    collections::{BTreeMap, BTreeSet, VecDeque},
+    io::Write as _,
+    sync::{Arc, Mutex, OnceLock},
+};
+
+use flate2::{Compression, write::GzEncoder};
+use gateway_plugin_sdk::{
+    Capability, ContributionDeclaration, Contributions, Engines, Manifest, PROTOCOL_VERSION,
+    Package, PackageTarget, RuntimeKind, Stage,
+};
+use sha2::{Digest as _, Sha256};
+pub mod diagnostics;
+pub mod environment;
+pub mod http;
+pub mod store;
+
+pub const DEFAULT_PLUGIN_ID: &str = "test.example";
+
+pub fn contribution(
+    capability: Capability,
+    stages: Vec<Stage>,
+    input_formats: Vec<String>,
+    output_formats: Vec<String>,
+) -> (Capability, ContributionDeclaration) {
+    contribution_for_id(
+        DEFAULT_PLUGIN_ID,
+        capability,
+        stages,
+        input_formats,
+        output_formats,
+    )
+}
+
+pub fn contribution_for_id(
+    plugin_id: &str,
+    capability: Capability,
+    stages: Vec<Stage>,
+    input_formats: Vec<String>,
+    output_formats: Vec<String>,
+) -> (Capability, ContributionDeclaration) {
+    let local_id = match capability {
+        Capability::Models => "models",
+        Capability::Authentication => "authentication",
+        Capability::FrontendAuthentication => "frontendAuthentication",
+        Capability::Scheduler => "scheduler",
+        Capability::ModelRouter => "modelRouter",
+        Capability::Executor => "executor",
+        Capability::Middleware => "middleware",
+        Capability::RequestLifecycle => "requestLifecycle",
+        Capability::WebSocketObserver => "webSocketObserver",
+        Capability::Usage => "usage",
+        Capability::CommandLine => "commandLine",
+        Capability::Management => "management",
+        Capability::Quota => "quota",
+        Capability::RequestProfile => "requestProfile",
+        Capability::AccountManagement => "accountManagement",
+        Capability::Billing => "billing",
+        Capability::Maintenance => "maintenance",
+    };
+    (
+        capability,
+        ContributionDeclaration {
+            id: format!("{plugin_id}.{local_id}"),
+            version: 1,
+            stages,
+            input_formats,
+            output_formats,
+        },
+    )
+}
+
+struct WorkerFixture {
+    bytes: Vec<u8>,
+    digest: String,
+}
+
+fn worker_fixture() -> &'static WorkerFixture {
+    static WORKER: OnceLock<WorkerFixture> = OnceLock::new();
+    WORKER.get_or_init(|| {
+        let bytes = std::fs::read(env!("CARGO_BIN_EXE_gateway-plugin-test-worker"))
+            .expect("Cargo 应为集成测试构建 Rust 测试插件");
+        let digest = hex::encode(Sha256::digest(&bytes));
+        WorkerFixture { bytes, digest }
+    })
+}
+
+pub fn worker() -> &'static [u8] {
+    &worker_fixture().bytes
+}
+
+pub fn package(worker: &[u8]) -> Arc<[u8]> {
+    package_with_permissions(worker, Vec::new())
+}
+
+pub fn package_with_permissions(
+    worker: &[u8],
+    permissions: Vec<gateway_plugin_sdk::Permission>,
+) -> Arc<[u8]> {
+    package_with_contributions(worker, permissions, Contributions::new())
+}
+
+pub fn package_with_contributions(
+    worker: &[u8],
+    permissions: Vec<gateway_plugin_sdk::Permission>,
+    contributes: Contributions,
+) -> Arc<[u8]> {
+    package_with_contributions_and_state(worker, permissions, contributes, vec![])
+}
+
+pub fn package_with_contributions_for_id(
+    worker: &[u8],
+    plugin_id: &str,
+    permissions: Vec<gateway_plugin_sdk::Permission>,
+    contributes: Contributions,
+) -> Arc<[u8]> {
+    package_with_identity_and_state(worker, plugin_id, permissions, contributes, vec![])
+}
+
+pub fn package_with_contributions_and_state(
+    worker: &[u8],
+    permissions: Vec<gateway_plugin_sdk::Permission>,
+    contributes: Contributions,
+    state: Vec<gateway_plugin_sdk::StateNamespace>,
+) -> Arc<[u8]> {
+    package_with_identity_and_state(worker, DEFAULT_PLUGIN_ID, permissions, contributes, state)
+}
+
+fn package_with_identity_and_state(
+    worker: &[u8],
+    plugin_id: &str,
+    permissions: Vec<gateway_plugin_sdk::Permission>,
+    contributes: Contributions,
+    state: Vec<gateway_plugin_sdk::StateNamespace>,
+) -> Arc<[u8]> {
+    let (publisher, name) = plugin_id
+        .split_once('.')
+        .expect("测试插件 ID 必须使用 publisher.name");
+    let digest = if std::ptr::eq(worker, self::worker()) {
+        worker_fixture().digest.clone()
+    } else {
+        hex::encode(Sha256::digest(worker))
+    };
+    let files = BTreeMap::from([("bin/worker".to_owned(), digest)]);
+    let manifest = Manifest {
+        manifest_version: gateway_plugin_sdk::MANIFEST_VERSION,
+        name: name.to_owned(),
+        display_name: "示例".to_owned(),
+        publisher: publisher.to_owned(),
+        version: "1.0.0".parse().unwrap(),
+        description: "测试插件".to_owned(),
+        license: "MIT".to_owned(),
+        author: Some("test".to_owned()),
+        engines: Engines {
+            codex_proxy_rs: ">=1.0.0, <2.0.0".parse().unwrap(),
+        },
+        main: "bin/worker".to_owned(),
+        runtime: RuntimeKind::TrustedProcess,
+        contributes,
+        permissions: permissions.into_iter().collect::<BTreeSet<_>>(),
+        configuration_schema: serde_json::json!({}),
+        secret_fields: BTreeSet::new(),
+        resources: BTreeMap::new(),
+        icon: None,
+        state,
+        package: Some(Package {
+            protocol_version: PROTOCOL_VERSION,
+            target: PackageTarget {
+                os: std::env::consts::OS.to_owned(),
+                architecture: std::env::consts::ARCH.to_owned(),
+            },
+            files,
+        }),
+    };
+    let manifest = serde_json::to_vec(&manifest).unwrap();
+    let key: [u8; 32] = Sha256::digest(&manifest).into();
+    type PackageCache = VecDeque<([u8; 32], Arc<[u8]>)>;
+    static PACKAGES: Mutex<PackageCache> = Mutex::new(VecDeque::new());
+    // 缓存的只是不可变制品；各用例仍独立校验、解包、启动进程和创建数据库 schema。
+    // 同时保留至多 8 个制品，避免复杂清单用例累积常驻内存。
+    let mut packages = PACKAGES.lock().unwrap();
+    if let Some(index) = packages.iter().position(|(existing, _)| *existing == key) {
+        let entry = packages.remove(index).unwrap();
+        let package = entry.1.clone();
+        packages.push_back(entry);
+        return package;
+    }
+    let package = archive(BTreeMap::from([
+        ("plugin.json".into(), manifest),
+        ("bin/worker".into(), worker.to_vec()),
+    ]));
+    if packages.len() == 8 {
+        packages.pop_front();
+    }
+    packages.push_back((key, package.clone()));
+    package
+}
+
+pub fn archive(files: BTreeMap<String, Vec<u8>>) -> Arc<[u8]> {
+    let mut tar = tar::Builder::new(Vec::new());
+    for (path, bytes) in files {
+        let mut header = tar::Header::new_gnu();
+        header.set_size(bytes.len() as u64);
+        header.set_mode(0o700);
+        header.set_cksum();
+        tar.append_data(&mut header, path, bytes.as_slice())
+            .unwrap();
+    }
+    let mut gzip = GzEncoder::new(Vec::new(), Compression::fast());
+    gzip.write_all(&tar.into_inner().unwrap()).unwrap();
+    gzip.finish().unwrap().into()
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/support/store.rs b/backend/crates/gateway-plugin/runtime/tests/support/store.rs
new file mode 100644
index 000000000..6f7c1f93e
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/support/store.rs
@@ -0,0 +1,238 @@
+use std::{collections::BTreeMap, sync::Mutex};
+
+use async_trait::async_trait;
+use gateway_admin::{
+    model::{
+        MutationContext, Revision,
+        plugins::{
+            InspectedPluginArtifact, InstalledPluginArtifact, PluginArtifactMutation, PluginSource,
+            distribution::{PluginSourceBinding, SourceCredential, SourceCredentialInfo},
+            instances::{PluginInstance, PluginInstanceMutation, PluginInstanceSnapshot},
+            state::{
+                ApplyPluginStateMigration, DeletePluginState, PluginStateConfiguration,
+                PluginStateMigrationBatch, PluginStateOwner, PluginStateOwnerRequest,
+                PluginStateRecord, PluginStateTransition, PluginStateWrite, PutPluginState,
+            },
+        },
+    },
+    ports::{
+        plugins::{PluginStateStore, PluginStateStoreResult, PluginStore},
+        store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult},
+    },
+};
+
+pub struct Store {
+    pub artifacts: BTreeMap<String, InspectedPluginArtifact>,
+    pub snapshot: Mutex<PluginInstanceSnapshot>,
+}
+
+#[async_trait]
+impl PluginStateStore for Store {
+    async fn load_owner(
+        &self,
+        request: PluginStateOwnerRequest,
+    ) -> PluginStateStoreResult<Option<PluginStateOwner>> {
+        if !request.configuration.namespaces.is_empty() {
+            return Ok(None);
+        }
+        Ok(Some(PluginStateOwner::from_store(
+            request.instance_id,
+            request.artifact_sha256,
+            request.instance_revision,
+            BTreeMap::new(),
+        )))
+    }
+
+    async fn get(
+        &self,
+        _: &PluginStateOwner,
+        _: &str,
+        _: &str,
+    ) -> PluginStateStoreResult<Option<PluginStateRecord>> {
+        Err(gateway_admin::ports::plugins::PluginStateStoreError::new(
+            gateway_admin::ports::plugins::PluginStateStoreErrorKind::Unavailable,
+        ))
+    }
+
+    async fn put(
+        &self,
+        _: &PluginStateOwner,
+        _: PutPluginState,
+    ) -> PluginStateStoreResult<PluginStateWrite> {
+        Err(gateway_admin::ports::plugins::PluginStateStoreError::new(
+            gateway_admin::ports::plugins::PluginStateStoreErrorKind::Unavailable,
+        ))
+    }
+
+    async fn delete(
+        &self,
+        _: &PluginStateOwner,
+        _: DeletePluginState,
+    ) -> PluginStateStoreResult<bool> {
+        Err(gateway_admin::ports::plugins::PluginStateStoreError::new(
+            gateway_admin::ports::plugins::PluginStateStoreErrorKind::Unavailable,
+        ))
+    }
+
+    async fn transition_required(
+        &self,
+        _: &str,
+        _: &PluginStateConfiguration,
+    ) -> PluginStateStoreResult<bool> {
+        Ok(false)
+    }
+
+    async fn begin_transition(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &str,
+        _: PluginStateConfiguration,
+    ) -> PluginStateStoreResult<PluginStateTransition> {
+        Err(gateway_admin::ports::plugins::PluginStateStoreError::new(
+            gateway_admin::ports::plugins::PluginStateStoreErrorKind::Unavailable,
+        ))
+    }
+
+    async fn migration_batch(
+        &self,
+        _: &str,
+        _: &str,
+        _: u32,
+    ) -> PluginStateStoreResult<PluginStateMigrationBatch> {
+        Err(gateway_admin::ports::plugins::PluginStateStoreError::new(
+            gateway_admin::ports::plugins::PluginStateStoreErrorKind::Unavailable,
+        ))
+    }
+
+    async fn apply_migration_batch(
+        &self,
+        _: ApplyPluginStateMigration,
+    ) -> PluginStateStoreResult<()> {
+        Err(gateway_admin::ports::plugins::PluginStateStoreError::new(
+            gateway_admin::ports::plugins::PluginStateStoreErrorKind::Unavailable,
+        ))
+    }
+
+    async fn abort_transition(&self, _: &str) -> PluginStateStoreResult<()> {
+        Ok(())
+    }
+}
+
+fn unused() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Unavailable,
+        "plugin",
+        "unused test operation",
+    )
+}
+
+#[async_trait]
+impl PluginStore for Store {
+    async fn management_target_is_current(
+        &self,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+    ) -> AdminStoreResult<bool> {
+        Ok(self
+            .load_instances()
+            .await?
+            .instances
+            .iter()
+            .any(|instance| {
+                instance.enabled
+                    && instance.trusted_process
+                    && instance.id == target.instance_id
+                    && instance.artifact_sha256 == target.artifact_sha256
+                    && instance.revision.get() == target.revision
+            }))
+    }
+    async fn accept_artifact(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        Err(unused())
+    }
+    async fn list_artifacts(&self) -> AdminStoreResult<Vec<InstalledPluginArtifact>> {
+        Err(unused())
+    }
+    async fn load_artifact(&self, digest: &str) -> AdminStoreResult<InspectedPluginArtifact> {
+        self.artifacts.get(digest).cloned().ok_or_else(unused)
+    }
+    async fn install_artifact(
+        &self,
+        _: InspectedPluginArtifact,
+        _: PluginSource,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        Err(unused())
+    }
+    async fn delete_artifact(&self, _: &str, _: &MutationContext) -> AdminStoreResult<Revision> {
+        Err(unused())
+    }
+    async fn list_source_credentials(&self) -> AdminStoreResult<Vec<SourceCredentialInfo>> {
+        Err(unused())
+    }
+    async fn load_source_credential(&self, _: &str) -> AdminStoreResult<SourceCredential> {
+        Err(unused())
+    }
+    async fn save_source_credential(
+        &self,
+        _: SourceCredential,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unused())
+    }
+    async fn delete_source_credential(
+        &self,
+        _: &str,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unused())
+    }
+    async fn list_update_sources(&self) -> AdminStoreResult<Vec<PluginSourceBinding>> {
+        Err(unused())
+    }
+    async fn change_update_source(
+        &self,
+        _: PluginSourceBinding,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unused())
+    }
+    async fn load_instances(&self) -> AdminStoreResult<PluginInstanceSnapshot> {
+        Ok(self.snapshot.lock().unwrap().clone())
+    }
+    async fn save_instance(
+        &self,
+        mut instance: PluginInstance,
+        expected: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        let mut snapshot = self.snapshot.lock().unwrap();
+        if snapshot.config_revision != expected {
+            return Err(AdminStoreError::new(
+                AdminStoreErrorKind::Conflict,
+                "plugin",
+                "configuration changed",
+            ));
+        }
+        let next = Revision::new(expected.get() + 1).unwrap();
+        instance.revision = next;
+        snapshot.config_revision = next;
+        snapshot.instances.retain(|item| item.id != instance.id);
+        snapshot.instances.push(instance.clone());
+        Ok(PluginInstanceMutation {
+            config_revision: next,
+            instance,
+        })
+    }
+    async fn delete_instance(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(unused())
+    }
+}
diff --git a/backend/crates/gateway-plugin/runtime/tests/support/worker.rs b/backend/crates/gateway-plugin/runtime/tests/support/worker.rs
new file mode 100644
index 000000000..6afd04025
--- /dev/null
+++ b/backend/crates/gateway-plugin/runtime/tests/support/worker.rs
@@ -0,0 +1,2192 @@
+//! 真实子进程协议对端；只依赖公开 SDK，Cargo 为集成测试构建此辅助二进制。
+
+use std::{
+    collections::BTreeMap,
+    io::Write as _,
+    sync::{
+        Arc,
+        atomic::{AtomicU64, Ordering},
+    },
+    time::Duration,
+};
+
+use gateway_plugin_sdk::{
+    ErrorCode, Frame, Message, PluginFault,
+    client::{read_frame, write_frame},
+};
+use serde_json::{Value, json};
+use tokio::io::AsyncWriteExt as _;
+use tokio::sync::{Mutex, Notify, mpsc, oneshot};
+
+type CallbackResult = Result<(Value, Vec<u8>), PluginFault>;
+struct PendingCallback {
+    parent: u64,
+    response: Option<oneshot::Sender<CallbackResult>>,
+}
+
+fn record_startup(configuration: &Value) -> usize {
+    let Some(path) = configuration.get("startup_marker").and_then(Value::as_str) else {
+        return 0;
+    };
+    let startup = std::fs::read_to_string(path)
+        .map(|content| content.lines().count())
+        .unwrap_or_default();
+    let mut file = std::fs::OpenOptions::new()
+        .create(true)
+        .append(true)
+        .open(path)
+        .unwrap();
+    serde_json::to_writer(&mut file, &json!({"startup":startup + 1})).unwrap();
+    file.write_all(b"\n").unwrap();
+    startup
+}
+
+#[derive(Default)]
+struct Credits {
+    available: Mutex<(u64, u64)>,
+    changed: Notify,
+}
+
+impl Credits {
+    async fn take(&self, bytes: u64) {
+        loop {
+            let changed = self.changed.notified();
+            {
+                let mut available = self.available.lock().await;
+                if available.0 >= bytes && available.1 > 0 {
+                    available.0 -= bytes;
+                    available.1 -= 1;
+                    return;
+                }
+            }
+            changed.await;
+        }
+    }
+
+    async fn grant(&self, bytes: u32, frames: u32) {
+        let mut available = self.available.lock().await;
+        available.0 += u64::from(bytes);
+        available.1 += u64::from(frames);
+        self.changed.notify_one();
+    }
+}
+
+struct Peer {
+    registration: gateway_plugin_sdk::call::provider::Registration,
+    configuration: Value,
+    prepared: Mutex<BTreeMap<String, gateway_plugin_sdk::call::provider::PrepareExecution>>,
+    output: mpsc::Sender<Frame>,
+    callbacks: Mutex<BTreeMap<u64, PendingCallback>>,
+    next_callback: AtomicU64,
+    model_queries: AtomicU64,
+    profile_queries: AtomicU64,
+    streams: Mutex<BTreeMap<u64, Arc<Credits>>>,
+}
+
+impl Peer {
+    async fn log_fixture(&self, id: u64) {
+        let Some(entries) = self
+            .configuration
+            .get("log_entries")
+            .and_then(Value::as_array)
+        else {
+            return;
+        };
+        let mut results = Vec::new();
+        for entry in entries {
+            if let Some(delay) = entry.get("delay_ms").and_then(Value::as_u64) {
+                tokio::time::sleep(Duration::from_millis(delay)).await;
+            }
+            for _ in 0..entry.get("repeat").and_then(Value::as_u64).unwrap_or(1) {
+                let payload = if entry["with_payload"] == true {
+                    vec![1]
+                } else {
+                    vec![]
+                };
+                results.push(
+                    match self
+                        .callback_payload(id, "host.log", entry["params"].clone(), payload)
+                        .await
+                    {
+                        Ok((result, _)) => result,
+                        Err(error) => json!({"error":error.code}),
+                    },
+                );
+            }
+        }
+        self.append_observation_marker("log_marker", &json!(results));
+    }
+
+    fn append_observation_marker(&self, field: &str, value: &Value) {
+        let Some(path) = self.configuration.get(field).and_then(Value::as_str) else {
+            return;
+        };
+        let mut file = std::fs::OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(path)
+            .unwrap();
+        let mut record = serde_json::to_vec(value).unwrap();
+        record.push(b'\n');
+        file.write_all(&record).unwrap();
+    }
+
+    async fn reset_credits(&self, id: u64, method: &str, payload: &[u8]) {
+        let operation = method.strip_prefix("provider.").unwrap();
+        let (account, body) = if operation == "consume_reset_credit" {
+            let input: gateway_plugin_sdk::call::provider::reset_credits::ConsumeRequest =
+                serde_json::from_slice(payload).unwrap();
+            (
+                input.account,
+                Some(
+                    json!({"credit_id":input.credit_id, "redeem_request_id":input.redeem_request_id}),
+                ),
+            )
+        } else {
+            (
+                serde_json::from_slice::<gateway_plugin_sdk::call::provider::account::AccountRequest>(payload)
+                    .unwrap(),
+                None,
+            )
+        };
+        let reply = if let Some(url) = self.configuration.get(format!("{operation}_url")) {
+            let request = json!({"method":if body.is_some() {"POST"} else {"GET"}, "url":url,
+                "headers":[["authorization",format!("Bearer {}",account.credential["key"].as_str().unwrap())],["content-type","application/json"]]});
+            match self
+                .callback_payload(
+                    id,
+                    "host.http.do",
+                    request,
+                    body.map(|body| serde_json::to_vec(&body).unwrap())
+                        .unwrap_or_default(),
+                )
+                .await
+            {
+                Ok((response, payload)) => match response["status"].as_u64().unwrap() {
+                    401 => json!({"outcome":"credential_refresh_required"}),
+                    400.. => json!({"outcome":"rejected"}),
+                    _ => {
+                        json!({"outcome":"completed", "result":serde_json::from_slice::<Value>(&payload).unwrap()})
+                    }
+                },
+                Err(error) => {
+                    self.send(Message::Error { id, error }, vec![]).await;
+                    return;
+                }
+            }
+        } else {
+            self.configuration[operation].clone()
+        };
+        if self.configuration[format!("{operation}_crash")].as_bool() == Some(true) {
+            std::process::exit(23);
+        }
+        if let Some(error) = self.configuration.get(format!("{operation}_fault")) {
+            self.send(
+                Message::Error {
+                    id,
+                    error: serde_json::from_value(error.clone()).unwrap(),
+                },
+                vec![],
+            )
+            .await;
+            return;
+        }
+        self.send(
+            Message::Result {
+                id,
+                result: json!({}),
+            },
+            serde_json::to_vec(&reply).unwrap(),
+        )
+        .await;
+    }
+
+    async fn account_query(&self, id: u64, method: &str, payload: &[u8]) {
+        let input: gateway_plugin_sdk::call::provider::account::AccountRequest =
+            serde_json::from_slice(payload).unwrap();
+        let operation = method.strip_prefix("provider.").unwrap();
+        let payload = if let Some(url) = self.configuration.get(format!("{operation}_url")) {
+            match self.callback(id, "host.http.do", json!({
+                "method":"GET", "url":url,
+                "headers":[["authorization", format!("Bearer {}", input.credential["key"].as_str().unwrap())]],
+            })).await {
+                Ok((_, payload)) => payload,
+                Err(error) => {
+                    self.send(Message::Error { id, error }, vec![]).await;
+                    return;
+                }
+            }
+        } else if operation == "avatar" {
+            vec![
+                42;
+                self.configuration["avatar_bytes"]
+                    .as_u64()
+                    .unwrap_or(524288) as usize
+            ]
+        } else {
+            serde_json::to_vec(&self.configuration[operation]).unwrap()
+        };
+        if operation != "avatar" {
+            self.send(
+                Message::Result {
+                    id,
+                    result: json!({}),
+                },
+                payload,
+            )
+            .await;
+            return;
+        }
+        let metadata = self.configuration.get("avatar_metadata").cloned().unwrap_or_else(|| json!({
+            "content_type":"image/png", "content_length":payload.len(), "etag":"\"fixture-avatar\"",
+        }));
+        self.send(
+            Message::Result {
+                id,
+                result: metadata,
+            },
+            vec![],
+        )
+        .await;
+        let credits = self.streams.lock().await.get(&id).unwrap().clone();
+        for (sequence, chunk) in payload.chunks(8192).enumerate() {
+            credits.take(chunk.len() as u64).await;
+            self.send(
+                Message::Stream {
+                    id,
+                    sequence: sequence as u64,
+                },
+                chunk.to_vec(),
+            )
+            .await;
+        }
+        let error = self.configuration["avatar_end_error"]
+            .as_bool()
+            .unwrap_or(false)
+            .then(|| PluginFault::new(ErrorCode::Upstream, "fixture stream interrupted"));
+        self.send(Message::End { id, error }, vec![]).await;
+    }
+
+    async fn account_callback_fixture(
+        &self,
+        id: u64,
+        input: &gateway_plugin_sdk::call::provider::account::AccountRequest,
+        query_number: u64,
+    ) -> Result<(), PluginFault> {
+        let Some(fixture) = self.configuration.get("account_callback_fixture") else {
+            return Ok(());
+        };
+        if query_number <= fixture["after_models"].as_u64().unwrap_or(u64::MAX) {
+            return Ok(());
+        }
+        let path = fixture["marker"].as_str().unwrap();
+        let mut marker = match std::fs::OpenOptions::new()
+            .create_new(true)
+            .write(true)
+            .open(path)
+        {
+            Ok(marker) => marker,
+            Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => return Ok(()),
+            Err(error) => panic!("create account callback marker: {error}"),
+        };
+        let (_, list_payload) = self
+            .callback_payload(
+                id,
+                "host.auth.list",
+                json!({}),
+                serde_json::to_vec(&gateway_plugin_sdk::call::host::AuthListRequest {
+                    provider_id: Some(
+                        self.configuration
+                            .get("provider_id")
+                            .and_then(Value::as_str)
+                            .unwrap_or("example")
+                            .to_owned(),
+                    ),
+                    cursor: None,
+                    limit: 20,
+                })
+                .unwrap(),
+            )
+            .await?;
+        let list: gateway_plugin_sdk::call::host::AuthListResult =
+            serde_json::from_slice(&list_payload).unwrap();
+        assert!(
+            list.accounts
+                .iter()
+                .any(|account| account.account_id == input.account_id)
+        );
+        let request = gateway_plugin_sdk::call::host::AuthGetRequest {
+            account_id: input.account_id.clone(),
+        };
+        let cross_account_readable =
+            if let Some(account_id) = fixture.get("other_account_id").and_then(Value::as_str) {
+                let (_, payload) = self
+                    .callback_payload(
+                        id,
+                        "host.auth.get_runtime",
+                        json!({}),
+                        serde_json::to_vec(&gateway_plugin_sdk::call::host::AuthGetRequest {
+                            account_id: account_id.to_owned(),
+                        })
+                        .unwrap(),
+                    )
+                    .await?;
+                let account: gateway_plugin_sdk::call::host::AuthRuntimeAccount =
+                    serde_json::from_slice(&payload).unwrap();
+                assert_eq!(account.account_id, account_id);
+                true
+            } else {
+                false
+            };
+        let (_, runtime_payload) = self
+            .callback_payload(
+                id,
+                "host.auth.get_runtime",
+                json!({}),
+                serde_json::to_vec(&request).unwrap(),
+            )
+            .await?;
+        let runtime: gateway_plugin_sdk::call::host::AuthRuntimeAccount =
+            serde_json::from_slice(&runtime_payload).unwrap();
+        let (_, credential_payload) = self
+            .callback_payload(
+                id,
+                "host.auth.get",
+                json!({}),
+                serde_json::to_vec(&request).unwrap(),
+            )
+            .await?;
+        let credential: gateway_plugin_sdk::call::host::AuthCredential =
+            serde_json::from_slice(&credential_payload).unwrap();
+        assert_eq!(credential.facts.material["key"], fixture["expected_key"]);
+        let mut facts = credential.facts;
+        facts.name = "callback rotated account".into();
+        facts.material = json!({"key":fixture["replacement_key"]})
+            .as_object()
+            .unwrap()
+            .clone();
+        let save = gateway_plugin_sdk::call::host::AuthSaveRequest::Replace {
+            account_id: input.account_id.clone(),
+            credential_revision: input.credential_revision,
+            facts,
+        };
+        let (_, save_payload) = self
+            .callback_payload(
+                id,
+                "host.auth.save",
+                json!({}),
+                serde_json::to_vec(&save).unwrap(),
+            )
+            .await?;
+        let saved: gateway_plugin_sdk::call::host::AuthSaveResult =
+            serde_json::from_slice(&save_payload).unwrap();
+        serde_json::to_writer(
+            &mut marker,
+            &json!({
+                "listed":list.accounts.len(),
+                "account_id":runtime.account_id,
+                "cross_account_readable":cross_account_readable,
+                "read_revision":credential.credential_revision,
+                "saved_revision":saved.credential_revision,
+            }),
+        )
+        .unwrap();
+        marker.write_all(b"\n").unwrap();
+        Ok(())
+    }
+
+    async fn callback(&self, parent: u64, method: &str, params: Value) -> CallbackResult {
+        self.callback_payload(parent, method, params, vec![]).await
+    }
+
+    async fn callback_payload(
+        &self,
+        parent: u64,
+        method: &str,
+        params: Value,
+        payload: Vec<u8>,
+    ) -> CallbackResult {
+        let (response, received) = oneshot::channel();
+        {
+            let mut callbacks = self.callbacks.lock().await;
+            let id = self.next_callback.fetch_add(2, Ordering::Relaxed);
+            callbacks.insert(
+                id,
+                PendingCallback {
+                    parent,
+                    response: Some(response),
+                },
+            );
+            self.send(
+                Message::Callback {
+                    id,
+                    parent_id: parent,
+                    method: method.into(),
+                    params,
+                },
+                payload,
+            )
+            .await;
+        }
+        received.await.unwrap()
+    }
+
+    async fn run_nested_model_fixture(
+        &self,
+        parent: u64,
+        fixture_field: &str,
+        marker_field: &str,
+    ) -> Result<(), PluginFault> {
+        let Some(fixture) = self.configuration.get(fixture_field) else {
+            return Ok(());
+        };
+        if fixture["stream_until_after_provider_cost"] == true || fixture["stream"] == true {
+            let (result, payload) = self
+                .callback_payload(
+                    parent,
+                    "host.model.execute_stream",
+                    fixture["request"].clone(),
+                    serde_json::to_vec(&fixture["body"]).unwrap(),
+                )
+                .await?;
+            assert!(payload.is_empty());
+            let stream: gateway_plugin_sdk::call::host::ModelStreamResult =
+                serde_json::from_value(result).unwrap();
+            self.append_observation_marker(
+                "nested_stream_trace_marker",
+                &json!({"phase":"opened","request_id":stream.request_id.as_str()}),
+            );
+            let mut event_count = 0_u64;
+            loop {
+                self.append_observation_marker(
+                    "nested_stream_trace_marker",
+                    &json!({"phase":"read_started"}),
+                );
+                let (result, payload) = self
+                    .callback(
+                        parent,
+                        "host.model.stream_read",
+                        json!({"stream":stream.stream.as_str(),"maximum_bytes":65536}),
+                    )
+                    .await?;
+                let result: gateway_plugin_sdk::call::host::ModelStreamReadResult =
+                    serde_json::from_value(result).unwrap();
+                let events = if result.end {
+                    assert!(payload.is_empty());
+                    gateway_plugin_sdk::call::host::ModelEventBatch { events: Vec::new() }
+                } else {
+                    gateway_plugin_sdk::call::host::ModelEventBatch::decode(&payload).unwrap()
+                };
+                assert_eq!(usize::try_from(result.events).unwrap(), events.events.len());
+                event_count += u64::from(result.events);
+                self.append_observation_marker(
+                    "nested_stream_trace_marker",
+                    &json!({
+                        "phase":"read_completed",
+                        "events":result.events,
+                        "end":result.end,
+                        "batch":serde_json::to_value(&events.events).unwrap()
+                    }),
+                );
+                if fixture["stream_until_after_provider_cost"] == true
+                    && events.events.iter().any(|event| {
+                        event.facts.iter().any(|fact| {
+                            matches!(
+                                fact,
+                                gateway_plugin_sdk::call::provider::CanonicalEvent::TextDelta { .. }
+                            )
+                        })
+                    })
+                {
+                    self.append_observation_marker(
+                        marker_field,
+                        &json!({
+                            "request_id":stream.request_id.as_str(),
+                            "after_provider_cost_consumed":true
+                        }),
+                    );
+                    // 费用事实不会投影给父插件；读到后继文本事实证明 Core 已按序消费费用。
+                    // 此后保持子流活跃，父调用取消后由宿主关闭流并回收其执行任务。
+                    std::future::pending::<()>().await;
+                }
+                if result.end {
+                    assert_ne!(
+                        fixture["stream_until_after_provider_cost"], true,
+                        "fixture child ended before the post-cost processing barrier"
+                    );
+                    self.append_observation_marker(
+                        marker_field,
+                        &json!({
+                            "request_id":stream.request_id.as_str(), "events":event_count,
+                        }),
+                    );
+                    return Ok(());
+                }
+            }
+        }
+        let callback = self
+            .callback_payload(
+                parent,
+                "host.model.execute",
+                fixture["request"].clone(),
+                serde_json::to_vec(&fixture["body"]).unwrap(),
+            )
+            .await;
+        match callback {
+            Ok((result, callback_payload)) => {
+                let result: gateway_plugin_sdk::call::host::ModelExecuteResult =
+                    serde_json::from_value(result).unwrap();
+                let events =
+                    gateway_plugin_sdk::call::host::ModelEventBatch::decode(&callback_payload)
+                        .unwrap();
+                assert_eq!(usize::try_from(result.events).unwrap(), events.events.len());
+                self.append_observation_marker(
+                    marker_field,
+                    &json!({"request_id":result.request_id,"events":result.events}),
+                );
+                Ok(())
+            }
+            Err(error) if fixture["expect_error"] == true => {
+                self.append_observation_marker(marker_field, &json!({"error":error.code}));
+                Ok(())
+            }
+            Err(error) => {
+                self.append_observation_marker(marker_field, &json!({"error":error.code}));
+                Err(error)
+            }
+        }
+    }
+
+    async fn send(&self, message: Message, payload: Vec<u8>) {
+        self.output.send(Frame { message, payload }).await.unwrap();
+    }
+
+    async fn respond(&self, id: u64, method: String, params: Value, payload: Vec<u8>) {
+        if self.configuration["log_method"].as_str() == Some(method.as_str()) {
+            self.log_fixture(id).await;
+        }
+        if method.starts_with("stream") {
+            self.send(
+                Message::Result {
+                    id,
+                    result: json!({"stream":true}),
+                },
+                vec![],
+            )
+            .await;
+            let credits = self.streams.lock().await.get(&id).unwrap().clone();
+            for sequence in 0..128_u64 {
+                credits.take(8192).await;
+                let payload = if method == "stream_overflow" {
+                    vec![b'x'; 256 * 1024 + 1]
+                } else {
+                    vec![sequence as u8; 8192]
+                };
+                let sequence = sequence + u64::from(method == "stream_sequence");
+                self.send(Message::Stream { id, sequence }, payload).await;
+            }
+            self.send(Message::End { id, error: None }, vec![]).await;
+            return;
+        }
+        match method.as_str() {
+            "frontend_auth.identifier" => {
+                self.send(
+                    Message::Result {
+                        id,
+                        result: serde_json::to_value(
+                            gateway_plugin_sdk::call::frontend_authentication::FrontendAuthenticationIdentifier {
+                                identifier: self
+                                    .configuration
+                                    .get("frontend_authentication_identifier")
+                                    .and_then(Value::as_str)
+                                    .unwrap_or("fixture-auth")
+                                    .to_owned(),
+                            },
+                        )
+                        .unwrap(),
+                    },
+                    vec![],
+                )
+                .await;
+                return;
+            }
+            "frontend_auth.authenticate" => {
+                assert_eq!(params, json!({}));
+                let input: gateway_plugin_sdk::call::frontend_authentication::FrontendAuthenticationRequest =
+                    serde_json::from_slice(&payload).unwrap();
+                if let Some(expected) = self
+                    .configuration
+                    .get("expected_frontend_authorization")
+                    .and_then(Value::as_str)
+                {
+                    assert_eq!(input.authorization, expected);
+                }
+                self.append_observation_marker(
+                    "frontend_authentication_marker",
+                    &json!({"called":true}),
+                );
+                let result = self
+                    .configuration
+                    .get("frontend_authentication_result")
+                    .cloned()
+                    .unwrap_or_else(|| json!({"outcome":"not_matched"}));
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    },
+                    serde_json::to_vec(&result).unwrap(),
+                )
+                .await;
+                return;
+            }
+            "management.register" => {
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    },
+                    serde_json::to_vec(&self.configuration["management_registration"]).unwrap(),
+                )
+                .await;
+                return;
+            }
+            "management.handle" => {
+                let request: gateway_plugin_sdk::call::management::ManagementRequest =
+                    serde_json::from_value(params).unwrap();
+                self.append_observation_marker(
+                    "management_marker",
+                    &json!({"method":request.method,"path":request.path}),
+                );
+                if let Err(error) = self
+                    .run_nested_model_fixture(
+                        id,
+                        "management_nested_model_fixture",
+                        "management_nested_model_marker",
+                    )
+                    .await
+                {
+                    self.send(Message::Error { id, error }, vec![]).await;
+                    return;
+                }
+                let response = self
+                    .configuration
+                    .get("management_response")
+                    .cloned()
+                    .unwrap_or_else(
+                        || json!({"status":200,"content_type":"application/octet-stream"}),
+                    );
+                self.send(
+                    Message::Result {
+                        id,
+                        result: response,
+                    },
+                    payload,
+                )
+                .await;
+                return;
+            }
+            "management.callback" => {
+                for method in [
+                    "host.auth.list",
+                    "host.auth.save",
+                    "host.http.do",
+                    "host.state.get",
+                    "host.log",
+                ] {
+                    assert!(
+                        matches!(self.callback(id, method, json!({})).await, Err(error) if error.code == ErrorCode::PermissionDenied)
+                    );
+                }
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({"status":200,"content_type":"text/plain"}),
+                    },
+                    b"callback received".to_vec(),
+                )
+                .await;
+                return;
+            }
+            "command_line.register" => {
+                if self.configuration["command_registration_probe"] == true {
+                    for method in ["host.http.do", "host.auth.save", "host.state.put"] {
+                        let reply = self.callback(id, method, json!({})).await;
+                        assert!(
+                            matches!(reply, Err(ref error) if error.code == ErrorCode::PermissionDenied)
+                        );
+                    }
+                }
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    },
+                    serde_json::to_vec(&self.configuration["command_registration"]).unwrap(),
+                )
+                .await;
+                return;
+            }
+            "command_line.execute" => {
+                let invocation: gateway_plugin_sdk::call::management::CommandInvocation =
+                    serde_json::from_slice(&payload).unwrap();
+                self.append_observation_marker(
+                    "command_marker",
+                    &json!({"name":invocation.name,"pid":std::process::id()}),
+                );
+                if self.configuration["command_crash"] == true {
+                    std::process::exit(29);
+                }
+                if self.configuration["command_wait"] == true {
+                    std::future::pending::<()>().await;
+                }
+                if let Err(error) = self
+                    .run_nested_model_fixture(
+                        id,
+                        "command_nested_model_fixture",
+                        "command_nested_model_marker",
+                    )
+                    .await
+                {
+                    self.send(Message::Error { id, error }, vec![]).await;
+                    return;
+                }
+                if self.configuration["command_error_after_nested_model"].as_str()
+                    == Some(invocation.name.as_str())
+                {
+                    self.send(
+                        Message::Error {
+                            id,
+                            error: PluginFault::new(
+                                ErrorCode::Fault,
+                                "synthetic failure after nested model",
+                            ),
+                        },
+                        vec![],
+                    )
+                    .await;
+                    return;
+                }
+                let result = if self.configuration["command_echo"] == true {
+                    json!({"stdout":serde_json::to_string(&invocation).unwrap(),"stderr":"typed command\n","exit_code":0})
+                } else {
+                    self.configuration["command_result"].clone()
+                };
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    },
+                    serde_json::to_vec(&result).unwrap(),
+                )
+                .await;
+                return;
+            }
+            "provider.models" => {
+                let input: gateway_plugin_sdk::call::provider::account::AccountRequest =
+                    serde_json::from_slice(&payload).unwrap();
+                self.append_observation_marker("models_marker", &json!({"account_id":input.account_id, "credential_revision":input.credential_revision}));
+                let query_number = self.model_queries.fetch_add(1, Ordering::Relaxed) + 1;
+                if let Err(error) = self
+                    .account_callback_fixture(id, &input, query_number)
+                    .await
+                {
+                    self.send(Message::Error { id, error }, vec![]).await;
+                    return;
+                }
+                let response = if let Some(url) = self.configuration.get("models_url") {
+                    match self.callback(id, "host.http.do", json!({"method":"GET", "url":url, "headers":[["authorization",format!("Bearer {}",input.credential["key"].as_str().unwrap())]]})).await {
+                        Ok((_, payload)) => payload,
+                        Err(error) => { self.send(Message::Error { id, error }, vec![]).await; return; }
+                    }
+                } else {
+                    let mut catalog = self.configuration["account_catalogs"]
+                        .get(&input.account_id)
+                        .unwrap_or(&self.configuration["discovered_catalog"])
+                        .clone();
+                    let after = self.configuration["prepared_facts_after_models"]
+                        .as_u64()
+                        .unwrap_or(u64::MAX);
+                    if query_number > after
+                        && let Some(facts) = self.configuration.get("prepared_account_facts")
+                    {
+                        catalog["prepared_account_facts"] = facts.clone();
+                    }
+                    serde_json::to_vec(&catalog).unwrap()
+                };
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    },
+                    response,
+                )
+                .await;
+                return;
+            }
+            "policy.route_model" => {
+                let request: gateway_plugin_sdk::call::policy::ModelRouteRequest =
+                    serde_json::from_value(params).unwrap();
+                self.append_observation_marker(
+                    "route_marker",
+                    &json!({
+                        "request": request,
+                        "body": String::from_utf8_lossy(&payload),
+                    }),
+                );
+                if let Some(fixture) = self.configuration.get("affinity_fixture") {
+                    let callback = self
+                        .callback(id, "host.affinity.lookup", fixture["request"].clone())
+                        .await;
+                    match callback {
+                        Ok((result, callback_payload)) if callback_payload.is_empty() => {
+                            self.append_observation_marker(
+                                "affinity_marker",
+                                &json!({"result":result}),
+                            );
+                        }
+                        Ok(_) => panic!("affinity callback returned an unexpected payload"),
+                        Err(error) => {
+                            self.send(Message::Error { id, error }, vec![]).await;
+                            return;
+                        }
+                    }
+                }
+                if let Some(fixture) = self.configuration.get("nested_model_fixture") {
+                    let callback = self
+                        .callback_payload(
+                            id,
+                            "host.model.execute",
+                            fixture["request"].clone(),
+                            serde_json::to_vec(&fixture["body"]).unwrap(),
+                        )
+                        .await;
+                    match callback {
+                        Ok((result, callback_payload)) => {
+                            let result: gateway_plugin_sdk::call::host::ModelExecuteResult =
+                                serde_json::from_value(result).unwrap();
+                            let events = gateway_plugin_sdk::call::host::ModelEventBatch::decode(
+                                &callback_payload,
+                            )
+                            .unwrap();
+                            assert_eq!(
+                                usize::try_from(result.events).unwrap(),
+                                events.events.len()
+                            );
+                            self.append_observation_marker(
+                                "nested_model_marker",
+                                &json!({
+                                    "request_id":result.request_id,
+                                    "events":result.events,
+                                }),
+                            );
+                        }
+                        Err(error) if fixture["expect_error"] == true => {
+                            self.append_observation_marker(
+                                "nested_model_marker",
+                                &json!({"error":error.code}),
+                            );
+                        }
+                        Err(error) => {
+                            self.append_observation_marker(
+                                "nested_model_marker",
+                                &json!({"error":error.code}),
+                            );
+                            self.send(Message::Error { id, error }, vec![]).await;
+                            return;
+                        }
+                    }
+                }
+                if let Some(delay) = self.configuration["route_delay_ms"].as_u64() {
+                    tokio::time::sleep(Duration::from_millis(delay)).await;
+                }
+                if let Some(url) = self.configuration["route_http_url"].as_str() {
+                    self.callback(id, "host.http.do", json!({"method":"GET", "url":url}))
+                        .await
+                        .unwrap();
+                }
+                if self.configuration["route_fault"] == true {
+                    self.send(
+                        Message::Error {
+                            id,
+                            error: PluginFault::new(ErrorCode::Fault, "fixture route failure"),
+                        },
+                        vec![],
+                    )
+                    .await;
+                    return;
+                }
+                let result = self
+                    .configuration
+                    .get("route_decision")
+                    .cloned()
+                    .unwrap_or_else(|| json!({"decision":"unhandled"}));
+                let payload = self.configuration["route_reply_payload"]
+                    .as_bool()
+                    .unwrap_or(false)
+                    .then_some(vec![1])
+                    .unwrap_or_default();
+                self.send(Message::Result { id, result }, payload).await;
+                return;
+            }
+            "policy.schedule_account" => {
+                let request: gateway_plugin_sdk::call::policy::AccountScheduleRequest =
+                    serde_json::from_value(params).unwrap();
+                self.append_observation_marker("schedule_marker", &json!({"request":request}));
+                if let Some(delay) = self.configuration["schedule_delay_ms"].as_u64() {
+                    tokio::time::sleep(Duration::from_millis(delay)).await;
+                }
+                if self.configuration["schedule_fault"] == true {
+                    self.send(
+                        Message::Error {
+                            id,
+                            error: PluginFault::new(ErrorCode::Fault, "fixture schedule failure"),
+                        },
+                        vec![],
+                    )
+                    .await;
+                    return;
+                }
+                let result = self
+                    .configuration
+                    .get("schedule_pick_index")
+                    .and_then(Value::as_u64)
+                    .and_then(|index| request.candidates.get(index as usize))
+                    .map_or_else(
+                        || {
+                            self.configuration
+                                .get("schedule_decision")
+                                .cloned()
+                                .unwrap_or_else(|| json!({"decision":"delegate"}))
+                        },
+                        |candidate| json!({"decision":"pick","account_id":candidate.account_id}),
+                    );
+                let payload = self.configuration["schedule_reply_payload"]
+                    .as_bool()
+                    .unwrap_or(false)
+                    .then_some(vec![1])
+                    .unwrap_or_default();
+                self.send(Message::Result { id, result }, payload).await;
+                return;
+            }
+            "middleware.handle" => {
+                use gateway_plugin_sdk::call::middleware::{
+                    BODY_READ_METHOD, MiddlewareBodyRead, MiddlewareBodyReadResult,
+                    MiddlewareNextRequest, MiddlewareNextResponse, MiddlewareRequestBody,
+                    MiddlewareRequestHead, MiddlewareResponseBody, MiddlewareResponseHead,
+                    NEXT_METHOD,
+                };
+
+                let request: MiddlewareRequestHead = serde_json::from_value(params).unwrap();
+                self.append_observation_marker(
+                    "middleware_marker",
+                    &json!({
+                        "request_id":request.request_id,
+                        "mount":request.mount,
+                        "protocol":request.protocol,
+                        "headers":request.headers,
+                        "body_visible":request.body_visible,
+                        "body":String::from_utf8_lossy(&payload),
+                    }),
+                );
+                if let Some(url) = self.configuration["middleware_http_url"].as_str() {
+                    self.callback(id, "host.http.do", json!({"method":"GET", "url":url}))
+                        .await
+                        .unwrap();
+                }
+                if self.configuration["middleware_fault_before_next"] == true {
+                    self.send(
+                        Message::Error {
+                            id,
+                            error: PluginFault::new(ErrorCode::Fault, "fixture middleware failure"),
+                        },
+                        vec![],
+                    )
+                    .await;
+                    return;
+                }
+                let (result, callback_payload) = self
+                    .callback_payload(
+                        id,
+                        NEXT_METHOD,
+                        serde_json::to_value(MiddlewareNextRequest {
+                            protocol: None,
+                            header_mutations: Vec::new(),
+                            body: MiddlewareRequestBody::Preserve,
+                        })
+                        .unwrap(),
+                        vec![],
+                    )
+                    .await
+                    .unwrap();
+                assert!(callback_payload.is_empty());
+                let downstream: MiddlewareNextResponse = serde_json::from_value(result).unwrap();
+                if self.configuration["middleware_map_body"] == true {
+                    let body = downstream.body.clone().unwrap();
+                    let (result, mut source) = self
+                        .callback_payload(
+                            id,
+                            BODY_READ_METHOD,
+                            serde_json::to_value(MiddlewareBodyRead {
+                                handle: body.handle,
+                                maximum_bytes: 64 * 1024,
+                            })
+                            .unwrap(),
+                            vec![],
+                        )
+                        .await
+                        .unwrap();
+                    let read: MiddlewareBodyReadResult = serde_json::from_value(result).unwrap();
+                    assert!(!read.eof && read.source_id != 0);
+                    source.push(b' ');
+                    let response = MiddlewareResponseHead {
+                        response: Some(downstream.response),
+                        protocol: None,
+                        status: None,
+                        header_mutations: Vec::new(),
+                        body: MiddlewareResponseBody::Stream {
+                            framing: read.framing,
+                        },
+                    };
+                    self.send(
+                        Message::Result {
+                            id,
+                            result: serde_json::to_value(response).unwrap(),
+                        },
+                        vec![],
+                    )
+                    .await;
+                    let mut mapped = Vec::with_capacity(14 + source.len());
+                    mapped.extend_from_slice(b"GMB1");
+                    mapped.push(1); // Only: 一个输出消费完整源 frame。
+                    mapped.extend_from_slice(&read.source_id.to_be_bytes());
+                    mapped.push(0); // mapped frame 的 terminal 由 Runtime 从源事实恢复。
+                    mapped.extend_from_slice(&source);
+                    let credits = self.streams.lock().await.get(&id).unwrap().clone();
+                    credits.take(mapped.len() as u64).await;
+                    self.send(Message::Stream { id, sequence: 0 }, mapped).await;
+                    if self.configuration["middleware_chunk_after_terminal"] == true {
+                        credits.take(1).await;
+                        self.send(Message::Stream { id, sequence: 1 }, vec![0])
+                            .await;
+                    }
+                    let error = self.configuration["middleware_error_after_terminal"]
+                        .as_bool()
+                        .unwrap_or(false)
+                        .then(|| {
+                            PluginFault::new(
+                                ErrorCode::Upstream,
+                                "fixture middleware stream interrupted after terminal frame",
+                            )
+                        });
+                    self.send(Message::End { id, error }, vec![]).await;
+                    return;
+                }
+                let response = MiddlewareResponseHead {
+                    response: Some(downstream.response),
+                    protocol: None,
+                    status: None,
+                    header_mutations: Vec::new(),
+                    body: MiddlewareResponseBody::PassThrough {
+                        body: downstream.body.unwrap(),
+                    },
+                };
+                self.send(
+                    Message::Result {
+                        id,
+                        result: serde_json::to_value(response).unwrap(),
+                    },
+                    vec![],
+                )
+                .await;
+                self.send(Message::End { id, error: None }, vec![]).await;
+                return;
+            }
+            "provider.account_changed" => {
+                assert_eq!(params, json!({}));
+                let event: gateway_plugin_sdk::call::provider::account::AccountInvalidation =
+                    serde_json::from_slice(&payload).unwrap();
+                self.append_observation_marker("invalidation_marker", &json!(event));
+                if let Some(delay) = self.configuration["invalidation_delay_ms"].as_u64() {
+                    tokio::time::sleep(Duration::from_millis(delay)).await;
+                }
+                if let Some(url) = self.configuration.get("invalidation_http_url") {
+                    let result = self
+                        .callback(id, "host.http.do", json!({"method":"GET", "url":url}))
+                        .await;
+                    assert!(
+                        matches!(result, Err(error) if error.code == ErrorCode::PermissionDenied)
+                    );
+                    self.append_observation_marker("invalidation_denied_marker", &json!(true));
+                }
+                let message = if self.configuration["invalidation_fault"] == true {
+                    Message::Error {
+                        id,
+                        error: PluginFault::new(ErrorCode::Fault, "fixture notification failure"),
+                    }
+                } else {
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    }
+                };
+                self.send(message, vec![]).await;
+                return;
+            }
+            "websocket.response_event" => {
+                let observation: gateway_plugin_sdk::call::observation::ObserveWebSocketResponse =
+                    serde_json::from_value(params).unwrap();
+                let payload_text = (payload.len() <= 4096)
+                    .then(|| std::str::from_utf8(&payload).ok())
+                    .flatten();
+                let marked = json!({
+                    "label": self.configuration.get("observation_label"),
+                    "observation": observation,
+                    "payload_bytes": payload.len(),
+                    "payload_text": payload_text,
+                });
+                self.append_observation_marker("websocket_observation_started_marker", &marked);
+                if let Some(delay) = self
+                    .configuration
+                    .get("websocket_observation_delay_ms")
+                    .and_then(Value::as_u64)
+                {
+                    tokio::time::sleep(Duration::from_millis(delay)).await;
+                }
+                self.append_observation_marker("websocket_observation_marker", &marked);
+                if self.configuration.get("websocket_observation_fault") == Some(&Value::Bool(true))
+                {
+                    self.send(
+                        Message::Error {
+                            id,
+                            error: PluginFault::new(
+                                ErrorCode::Fault,
+                                "fixture WebSocket observation failure",
+                            ),
+                        },
+                        vec![],
+                    )
+                    .await;
+                    return;
+                }
+                self.send(
+                    Message::Result {
+                        id,
+                        result: Value::Null,
+                    },
+                    vec![],
+                )
+                .await;
+                return;
+            }
+            "policy.observe_request" => {
+                let observation: gateway_plugin_sdk::call::policy::ObserveRequest =
+                    serde_json::from_slice(&payload).unwrap();
+                let marked = json!({
+                    "label": self.configuration.get("observation_label"),
+                    "observation": observation,
+                });
+                self.append_observation_marker("observation_started_marker", &marked);
+                if let Some(fixture) = self.configuration.get("state_fixture") {
+                    let namespace = fixture["namespace"].as_str().unwrap();
+                    let key = fixture["key"].as_str().unwrap();
+                    let value = fixture["value"].clone();
+                    let put = gateway_plugin_sdk::call::host::StatePutRequest {
+                        namespace: namespace.into(),
+                        key: key.into(),
+                        value: value.clone(),
+                        expected_version: None,
+                    };
+                    let put = match self
+                        .callback(id, "host.state.put", serde_json::to_value(put).unwrap())
+                        .await
+                    {
+                        Ok((result, payload)) if payload.is_empty() => serde_json::from_value::<
+                            gateway_plugin_sdk::call::host::StatePutResult,
+                        >(
+                            result
+                        )
+                        .unwrap(),
+                        Ok(_) => panic!("state put returned an unexpected payload"),
+                        Err(error) => {
+                            self.send(Message::Error { id, error }, vec![]).await;
+                            return;
+                        }
+                    };
+                    let get = gateway_plugin_sdk::call::host::StateGetRequest {
+                        namespace: namespace.into(),
+                        key: key.into(),
+                    };
+                    let get = match self
+                        .callback(id, "host.state.get", serde_json::to_value(get).unwrap())
+                        .await
+                    {
+                        Ok((result, payload)) if payload.is_empty() => serde_json::from_value::<
+                            gateway_plugin_sdk::call::host::StateGetResult,
+                        >(
+                            result
+                        )
+                        .unwrap(),
+                        Ok(_) => panic!("state get returned an unexpected payload"),
+                        Err(error) => {
+                            self.send(Message::Error { id, error }, vec![]).await;
+                            return;
+                        }
+                    };
+                    let record = get.record.unwrap();
+                    assert_eq!(record.value, value);
+                    assert_eq!(record.version, put.version);
+                    if let Some(denied_namespace) =
+                        fixture.get("denied_namespace").and_then(Value::as_str)
+                    {
+                        let denied = self
+                            .callback(
+                                id,
+                                "host.state.get",
+                                serde_json::to_value(
+                                    gateway_plugin_sdk::call::host::StateGetRequest {
+                                        namespace: denied_namespace.into(),
+                                        key: key.into(),
+                                    },
+                                )
+                                .unwrap(),
+                            )
+                            .await;
+                        assert!(matches!(
+                            denied,
+                            Err(error) if error.code == ErrorCode::PermissionDenied
+                        ));
+                    }
+                    let deleted = match self
+                        .callback(
+                            id,
+                            "host.state.delete",
+                            serde_json::to_value(
+                                gateway_plugin_sdk::call::host::StateDeleteRequest {
+                                    namespace: namespace.into(),
+                                    key: key.into(),
+                                    expected_version: put.version,
+                                },
+                            )
+                            .unwrap(),
+                        )
+                        .await
+                    {
+                        Ok((result, payload)) if payload.is_empty() => {
+                            serde_json::from_value::<
+                                gateway_plugin_sdk::call::host::StateDeleteResult,
+                            >(result)
+                            .unwrap()
+                        }
+                        Ok(_) => panic!("state delete returned an unexpected payload"),
+                        Err(error) => {
+                            self.send(Message::Error { id, error }, vec![]).await;
+                            return;
+                        }
+                    };
+                    assert!(deleted.deleted);
+                    self.append_observation_marker(
+                        "state_marker",
+                        &json!({"version": put.version, "schema_version": record.schema_version}),
+                    );
+                }
+                if let Some(delay) = self
+                    .configuration
+                    .get("observation_delay_ms")
+                    .and_then(Value::as_u64)
+                {
+                    tokio::time::sleep(Duration::from_millis(delay)).await;
+                }
+                self.append_observation_marker("observation_marker", &marked);
+                if self.configuration.get("observation_fault") == Some(&Value::Bool(true)) {
+                    self.send(
+                        Message::Error {
+                            id,
+                            error: PluginFault::new(
+                                ErrorCode::Fault,
+                                "fixture observation failure",
+                            ),
+                        },
+                        vec![],
+                    )
+                    .await;
+                    return;
+                }
+                self.send(
+                    Message::Result {
+                        id,
+                        result: Value::Null,
+                    },
+                    vec![],
+                )
+                .await;
+                return;
+            }
+            "provider.reset_credits" | "provider.consume_reset_credit" => {
+                self.reset_credits(id, &method, &payload).await;
+                return;
+            }
+            "provider.profile" | "provider.subscription" | "provider.avatar" => {
+                self.account_query(id, &method, &payload).await;
+                return;
+            }
+            "provider.login.start" => {
+                if let Some(error) = self.configuration.get("login_fault") {
+                    self.send(
+                        Message::Error {
+                            id,
+                            error: serde_json::from_value(error.clone()).unwrap(),
+                        },
+                        vec![],
+                    )
+                    .await;
+                    return;
+                }
+                let input: gateway_plugin_sdk::call::auth::LoginStart =
+                    serde_json::from_slice(&payload).unwrap();
+                if let Some(expected) = self.configuration.get("expected_login_input") {
+                    assert_eq!(serde_json::to_value(&input.input).unwrap(), *expected);
+                }
+                let now = std::time::SystemTime::now()
+                    .duration_since(std::time::UNIX_EPOCH)
+                    .unwrap()
+                    .as_millis() as i64;
+                let started = gateway_plugin_sdk::call::auth::LoginStarted {
+                    authorization_url: "https://example.test/login?code=test-only".into(),
+                    expires_at_ms: now + self.configuration["login_ttl_ms"].as_i64().unwrap_or(60_000),
+                    state: json!({
+                        "accounts":self.configuration.get("login_accounts").cloned().unwrap_or_else(|| json!([
+                            {"name":input.name.unwrap_or_else(|| "upstream profile".into()), "authentication_kind":"api_key", "material":{"key":"login-test-only"}}
+                        ])),
+                        "retry_after_ms":self.configuration["login_retry_ms"].as_u64().unwrap_or(1000),
+                    }).as_object().unwrap().clone(),
+                };
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    },
+                    serde_json::to_vec(&started).unwrap(),
+                )
+                .await;
+                return;
+            }
+            "provider.login.poll" => {
+                let input: gateway_plugin_sdk::call::auth::LoginPoll =
+                    serde_json::from_slice(&payload).unwrap();
+                let result = if input.callback_url.as_deref() == Some("ready") {
+                    gateway_plugin_sdk::call::auth::LoginPollResult::Complete {
+                        accounts: serde_json::from_value(input.state["accounts"].clone()).unwrap(),
+                    }
+                } else {
+                    gateway_plugin_sdk::call::auth::LoginPollResult::Pending {
+                        retry_after_ms: input.state["retry_after_ms"].as_u64().unwrap(),
+                    }
+                };
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    },
+                    serde_json::to_vec(&result).unwrap(),
+                )
+                .await;
+                return;
+            }
+            "provider.quota" => {
+                let input: Value = serde_json::from_slice(&payload).unwrap();
+                let result = self.callback(id, "host.http.do", json!({"method":"GET", "url":self.configuration["quota_url"], "headers":[["authorization",format!("Bearer {}", input["credential"]["key"].as_str().unwrap())]]})).await;
+                match result {
+                    Ok((_, payload)) => {
+                        self.send(
+                            Message::Result {
+                                id,
+                                result: json!({}),
+                            },
+                            payload,
+                        )
+                        .await
+                    }
+                    Err(error) => self.send(Message::Error { id, error }, vec![]).await,
+                }
+                return;
+            }
+            "provider.request_profiles.refresh" => {
+                let index =
+                    usize::try_from(self.profile_queries.fetch_add(1, Ordering::Relaxed)).unwrap();
+                let refreshed = self.configuration["request_profile_refresh_responses"]
+                    .as_array()
+                    .and_then(|responses| responses.get(index))
+                    .unwrap_or(&self.configuration["request_profile_refresh"])
+                    .clone();
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    },
+                    serde_json::to_vec(&refreshed).unwrap(),
+                )
+                .await;
+                return;
+            }
+            "provider.account_configuration" => {
+                let input: gateway_plugin_sdk::call::provider::account::AccountRequest =
+                    serde_json::from_slice(&payload).unwrap();
+                self.append_observation_marker(
+                    "account_configuration_started_marker",
+                    &json!({
+                        "account_id": input.account_id,
+                        "credential_revision": input.credential_revision,
+                    }),
+                );
+                if let Some(expected) = self.configuration.get("expected_account_configuration") {
+                    assert_eq!(
+                        json!({
+                            "account_id": input.account_id,
+                            "credential_revision": input.credential_revision,
+                            "credential": input.credential,
+                        }),
+                        *expected
+                    );
+                }
+                if let Some(release) = self
+                    .configuration
+                    .get("account_configuration_release_marker")
+                    .and_then(Value::as_str)
+                {
+                    while !std::path::Path::new(release).exists() {
+                        tokio::time::sleep(Duration::from_millis(5)).await;
+                    }
+                }
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    },
+                    serde_json::to_vec(
+                        &gateway_plugin_sdk::call::provider::account::AccountConfiguration {
+                            values: self.configuration["account_configuration_result"]
+                                .as_object()
+                                .cloned()
+                                .unwrap_or_default(),
+                        },
+                    )
+                    .unwrap(),
+                )
+                .await;
+                return;
+            }
+            "provider.credentials.rotate" | "provider.credentials.refresh" => {
+                let input: gateway_plugin_sdk::call::auth::RotateCredential =
+                    serde_json::from_slice(&payload).unwrap();
+                if let Some(expected) = self.configuration.get("expected_rotation_input") {
+                    assert_eq!(serde_json::to_value(&input.replacement).unwrap(), *expected);
+                }
+                if let Some(url) = self.configuration.get("management_url") {
+                    let result = self.callback(id, "host.http.do", json!({"method":"POST", "url":url, "headers":[["authorization",format!("Bearer {}", input.current.facts.material["key"].as_str().unwrap())]]})).await;
+                    let (_, payload) = match result {
+                        Ok(response) => response,
+                        Err(error) => {
+                            self.send(Message::Error { id, error }, vec![]).await;
+                            return;
+                        }
+                    };
+                    if self.configuration.get("management_error_after_http")
+                        == Some(&Value::Bool(true))
+                    {
+                        self.send(
+                            Message::Error {
+                                id,
+                                error: PluginFault::new(
+                                    ErrorCode::Upstream,
+                                    "plugin claims no mutation",
+                                ),
+                            },
+                            vec![],
+                        )
+                        .await;
+                    } else {
+                        self.send(
+                            Message::Result {
+                                id,
+                                result: json!({}),
+                            },
+                            payload,
+                        )
+                        .await;
+                    }
+                } else {
+                    let mut facts = input.current.facts;
+                    facts.material = input.replacement.unwrap_or_else(|| {
+                        json!({"key":"refreshed-test-key"})
+                            .as_object()
+                            .unwrap()
+                            .clone()
+                    });
+                    facts.name = "plugin proposes a profile change".into();
+                    self.send(
+                        Message::Result {
+                            id,
+                            result: json!({}),
+                        },
+                        serde_json::to_vec(&facts).unwrap(),
+                    )
+                    .await;
+                }
+                return;
+            }
+            "provider.credentials.import" => {
+                if let Some(expected) = self.configuration.get("expected_import_input") {
+                    assert_eq!(
+                        serde_json::from_slice::<Value>(&payload).unwrap(),
+                        *expected
+                    );
+                }
+                if let Some(marker_path) = self
+                    .configuration
+                    .get("account_create_marker")
+                    .and_then(Value::as_str)
+                {
+                    let imported: gateway_plugin_sdk::call::auth::ImportedCredentials =
+                        serde_json::from_slice(&payload).unwrap();
+                    let save = gateway_plugin_sdk::call::host::AuthSaveRequest::Create {
+                        provider_id: self
+                            .configuration
+                            .get("provider_id")
+                            .and_then(Value::as_str)
+                            .unwrap_or("example")
+                            .to_owned(),
+                        facts: imported.accounts[0].clone(),
+                    };
+                    let (_, saved_payload) = match self
+                        .callback_payload(
+                            id,
+                            "host.auth.save",
+                            json!({}),
+                            serde_json::to_vec(&save).unwrap(),
+                        )
+                        .await
+                    {
+                        Ok(reply) => reply,
+                        Err(error) => {
+                            self.send(Message::Error { id, error }, vec![]).await;
+                            return;
+                        }
+                    };
+                    let saved: gateway_plugin_sdk::call::host::AuthSaveResult =
+                        serde_json::from_slice(&saved_payload).unwrap();
+                    let mut marker = std::fs::OpenOptions::new()
+                        .create(true)
+                        .append(true)
+                        .open(marker_path)
+                        .unwrap();
+                    serde_json::to_writer(
+                        &mut marker,
+                        &json!({
+                            "account_id":saved.account_id,
+                            "credential_revision":saved.credential_revision,
+                        }),
+                    )
+                    .unwrap();
+                    marker.write_all(b"\n").unwrap();
+                }
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    },
+                    payload,
+                )
+                .await;
+                return;
+            }
+            "provider.credentials.export" => {
+                let credentials: Vec<gateway_plugin_sdk::call::auth::ExportCredential> =
+                    serde_json::from_slice(&payload).unwrap();
+                let accounts: Vec<_> = credentials
+                    .into_iter()
+                    .map(|credential| credential.facts)
+                    .collect();
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    },
+                    serde_json::to_vec(&gateway_plugin_sdk::call::auth::ImportedCredentials {
+                        accounts,
+                    })
+                    .unwrap(),
+                )
+                .await;
+                return;
+            }
+            "provider.connection_test" => {
+                self.send(Message::Result { id, result: json!({"protocol":"openai", "body":{"model":params["model"],"input":params["input"],"plugin_generation":self.configuration["generation_marker"]}}) }, vec![]).await;
+                return;
+            }
+            "provider.discard" => {
+                let token: gateway_plugin_sdk::call::provider::ExecutePrepared =
+                    serde_json::from_value(params).unwrap();
+                self.prepared.lock().await.remove(&token.token);
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({}),
+                    },
+                    vec![],
+                )
+                .await;
+                return;
+            }
+            "provider.prepare" => {
+                assert_eq!(params, json!({}), "执行私有数据不能放入控制元数据");
+                let input =
+                    gateway_plugin_sdk::call::provider::ExecutionInput::decode(&payload).unwrap();
+                if let Some(marker) = self
+                    .configuration
+                    .get("prepare_request_marker")
+                    .and_then(Value::as_str)
+                {
+                    std::fs::write(marker, &input.body).unwrap();
+                }
+                if let Ok(request) = serde_json::from_slice::<Value>(&input.body)
+                    && let Some(generation) = request.get("plugin_generation")
+                {
+                    assert_eq!(
+                        generation, &self.configuration["generation_marker"],
+                        "管理准备和实际执行必须使用同一代次"
+                    );
+                }
+                if let Some(url) = self.configuration.get("http_url") {
+                    let error = self
+                        .callback(id, "host.http.do", json!({"method":"GET","url":url}))
+                        .await
+                        .err()
+                        .unwrap();
+                    assert_eq!(error.code, ErrorCode::PermissionDenied);
+                }
+                let prepared = input.request;
+                if let Some(marker) = self
+                    .configuration
+                    .get("prepare_http_request_marker")
+                    .and_then(Value::as_str)
+                {
+                    let credential_matches_fixture = prepared.credential.len() == 1
+                        && prepared.credential.get("key").and_then(Value::as_str)
+                            == Some("test-only");
+                    std::fs::write(
+                        marker,
+                        serde_json::to_vec(&json!({
+                            "credential_matches_fixture":credential_matches_fixture,
+                            "protocol":&prepared.protocol,
+                            "operation":prepared.operation,
+                            "context":&prepared.context,
+                            "http_request":&prepared.http_request,
+                        }))
+                        .unwrap(),
+                    )
+                    .unwrap();
+                }
+                if let Some(marker) = self
+                    .configuration
+                    .get("request_profile_marker")
+                    .and_then(Value::as_str)
+                {
+                    std::fs::write(
+                        marker,
+                        serde_json::to_vec(&prepared.request_profile).unwrap(),
+                    )
+                    .unwrap();
+                }
+                let token = format!("prepared-{id}");
+                self.prepared.lock().await.insert(token.clone(), prepared);
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({"token":token,"transport":"plugin"}),
+                    },
+                    vec![],
+                )
+                .await;
+                return;
+            }
+            "provider.execute" => {
+                let token: gateway_plugin_sdk::call::provider::ExecutePrepared =
+                    serde_json::from_value(params).unwrap();
+                let prepared = self.prepared.lock().await.remove(&token.token).unwrap();
+                self.append_observation_marker("execution_calls_marker", &json!({"call_id":id}));
+                if let Some(marker) = self
+                    .configuration
+                    .get("execution_marker")
+                    .and_then(Value::as_str)
+                {
+                    std::fs::write(marker, prepared.account_id).unwrap();
+                }
+                self.send(
+                    Message::Result {
+                        id,
+                        result: json!({"stream":true}),
+                    },
+                    vec![],
+                )
+                .await;
+                if let Err(error) = self
+                    .run_nested_model_fixture(
+                        id,
+                        "execution_nested_model_fixture",
+                        "execution_nested_model_marker",
+                    )
+                    .await
+                {
+                    self.send(
+                        Message::End {
+                            id,
+                            error: Some(error),
+                        },
+                        vec![],
+                    )
+                    .await;
+                    return;
+                }
+                if self.configuration["error_after_nested_model"] == true {
+                    self.send(
+                        Message::End {
+                            id,
+                            error: Some(PluginFault::new(
+                                ErrorCode::Upstream,
+                                "plugin claims not sent after nested model execution",
+                            )),
+                        },
+                        vec![],
+                    )
+                    .await;
+                    return;
+                }
+                let text = if let Some(url) = self.configuration.get("http_url") {
+                    let result = self.callback(id, "host.http.do_stream", json!({"method":"GET","url":url,"headers":[["user-agent","codex-proxy-plugin-test"]]})).await;
+                    let (reply, _) = match result {
+                        Ok(reply) => reply,
+                        Err(error) => {
+                            self.send(
+                                Message::End {
+                                    id,
+                                    error: Some(error),
+                                },
+                                vec![],
+                            )
+                            .await;
+                            return;
+                        }
+                    };
+                    let handle = reply.get("stream").unwrap().as_str().unwrap();
+                    let mut content = Vec::new();
+                    loop {
+                        let (reply, payload) = self
+                            .callback(
+                                id,
+                                "host.http.stream_read",
+                                json!({"stream":handle,"maximum_bytes":257}),
+                            )
+                            .await
+                            .unwrap();
+                        content.extend(payload);
+                        if reply["eof"] == true {
+                            break;
+                        }
+                    }
+                    if self.configuration.get("error_after_http") == Some(&Value::Bool(true)) {
+                        self.send(
+                            Message::End {
+                                id,
+                                error: Some(PluginFault::new(
+                                    ErrorCode::Upstream,
+                                    "plugin claims not sent",
+                                )),
+                            },
+                            vec![],
+                        )
+                        .await;
+                        return;
+                    }
+                    String::from_utf8(content).unwrap()
+                } else {
+                    "Rust plugin response".into()
+                };
+                let credits = self.streams.lock().await.get(&id).unwrap().clone();
+                let events = self.configuration.get("execution_events").and_then(Value::as_array).cloned().unwrap_or_else(|| vec![
+                    json!({"facts":[{"type":"started","id":"response-plugin","model":prepared.model}]}),
+                    json!({"facts":[{"type":"content_added","index":0,"kind":"text"}]}),
+                    json!({"facts":[{"type":"text_delta","index":0,"text":text}]}),
+                    json!({"facts":[{"type":"provider_cost","amount":"0.0125","currency":"USD"}]}),
+                    json!({"facts":[{"type":"completed","id":"response-plugin","model":prepared.model,"reason":"stop"}]}),
+                ]);
+                for (sequence, mut event) in events.into_iter().enumerate() {
+                    if self
+                        .configuration
+                        .get("oversize_session_payload")
+                        .and_then(Value::as_bool)
+                        == Some(true)
+                    {
+                        // 在插件进程构造越界响应，避免先撞到宿主配置控制帧上限。
+                        event["session_update"]["payload"]["too_large"] = json!("x".repeat(65536));
+                    }
+                    let payload = serde_json::from_value::<
+                        gateway_plugin_sdk::call::provider::ExecutionEvent,
+                    >(event)
+                    .unwrap()
+                    .encode()
+                    .unwrap();
+                    credits.take(payload.len() as u64).await;
+                    self.send(
+                        Message::Stream {
+                            id,
+                            sequence: sequence as u64,
+                        },
+                        payload,
+                    )
+                    .await;
+                }
+                if self
+                    .configuration
+                    .get("execution_wait_for_cancel_marker")
+                    .and_then(Value::as_str)
+                    .is_some()
+                {
+                    self.append_observation_marker(
+                        "execution_wait_for_cancel_marker",
+                        &json!({"call_id":id}),
+                    );
+                    std::future::pending::<()>().await;
+                }
+                self.send(Message::End { id, error: None }, vec![]).await;
+                return;
+            }
+            "slow" => tokio::time::sleep(Duration::from_millis(400)).await,
+            "hang" | "hang_uncancellable" => return,
+            "crash" => std::process::exit(7),
+            "callback" | "callback_method" | "forged_callback" => {
+                let callback_method = if method == "callback_method" {
+                    params["method"].as_str().unwrap().to_owned()
+                } else {
+                    "host.log".into()
+                };
+                // 分配与入队保持同一顺序，避免并发回调制造不合法 ID 序列。
+                let mut callbacks = self.callbacks.lock().await;
+                let callback = self.next_callback.fetch_add(2, Ordering::Relaxed);
+                callbacks.insert(
+                    callback,
+                    PendingCallback {
+                        parent: id,
+                        response: None,
+                    },
+                );
+                self.send(
+                    Message::Callback {
+                        id: callback,
+                        parent_id: if method == "forged_callback" {
+                            999999
+                        } else {
+                            id
+                        },
+                        method: callback_method,
+                        params,
+                    },
+                    payload,
+                )
+                .await;
+                return;
+            }
+            "deny" => {
+                let mut error = PluginFault::new(ErrorCode::Rejected, "policy denied");
+                error.http_status = Some(403);
+                self.send(Message::Error { id, error }, vec![]).await;
+                return;
+            }
+            "plugin.register" => {
+                if self.configuration["exit_during_registration"] == true {
+                    std::process::exit(31);
+                }
+                self.send(
+                    Message::Result {
+                        id,
+                        result: serde_json::to_value(&self.registration).unwrap(),
+                    },
+                    vec![],
+                )
+                .await;
+                return;
+            }
+            _ => {}
+        }
+        self.send(Message::Result { id, result: params }, payload)
+            .await;
+    }
+}
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() {
+    let mut input = tokio::io::stdin();
+    let (output, mut frames) = mpsc::channel::<Frame>(64);
+    tokio::spawn(async move {
+        let mut output = tokio::io::stdout();
+        while let Some(frame) = frames.recv().await {
+            write_frame(&mut output, &frame, 1024 * 1024).await.unwrap();
+        }
+    });
+    let hello = read_frame(&mut input, 1024 * 1024).await.unwrap();
+    let Message::Hello { mut handshake } = hello.message else {
+        panic!("expected handshake")
+    };
+    if let Some(events) = handshake
+        .configuration
+        .get("execution_events_by_artifact")
+        .and_then(Value::as_object)
+        .and_then(|events| events.get(&handshake.artifact_sha256))
+        .cloned()
+    {
+        handshake.configuration["execution_events"] = events;
+    }
+    let startup = record_startup(&handshake.configuration);
+    if handshake
+        .configuration
+        .get("startup")
+        .and_then(Value::as_str)
+        == Some("fail")
+        || handshake.configuration["startup_failures"]
+            .as_array()
+            .and_then(|failures| failures.get(startup))
+            .and_then(Value::as_bool)
+            == Some(true)
+    {
+        if let Some(delay) = handshake.configuration["startup_fail_delay_ms"].as_u64() {
+            tokio::time::sleep(Duration::from_millis(delay)).await;
+        }
+        std::process::exit(9)
+    }
+    if let Some(delay) = handshake
+        .configuration
+        .get("startup_delay_ms")
+        .and_then(Value::as_u64)
+    {
+        tokio::time::sleep(Duration::from_millis(delay)).await;
+    }
+    let has_provider = handshake
+        .contributes
+        .contains_key(&gateway_plugin_sdk::Capability::Executor);
+    let credential_operations = if handshake
+        .contributes
+        .contains_key(&gateway_plugin_sdk::Capability::Authentication)
+    {
+        vec!["import", "export", "rotate", "refresh", "login"]
+    } else {
+        vec![]
+    };
+    let continuation_state = handshake
+        .configuration
+        .get("continuation_state_by_artifact")
+        .and_then(Value::as_object)
+        .and_then(|states| states.get(&handshake.artifact_sha256))
+        .or_else(|| handshake.configuration.get("continuation_state"))
+        .cloned();
+    let mut contributes = handshake.contributes.clone();
+    if handshake.configuration["registration_mismatch"] == true
+        && let Some(declaration) = contributes.values_mut().next()
+    {
+        declaration.id.push_str(".unexpected");
+    }
+    let registration = gateway_plugin_sdk::call::provider::Registration {
+        contributes,
+        provider: has_provider.then(|| {
+            serde_json::from_value(json!({
+                "id":handshake.configuration.get("provider_id").and_then(Value::as_str).unwrap_or("example"), "exhaustive":true,
+                "credential_operations":credential_operations,
+                "credential_input_schemas":handshake.configuration.get("credential_input_schemas").cloned().unwrap_or_else(|| json!({})),
+                "account_configuration":handshake.configuration.get("account_configuration").cloned(),
+                "account_operations":handshake.configuration.get("account_operations").cloned().unwrap_or_else(|| json!([])),
+                "billing":handshake.configuration.get("billing").cloned(),
+                "request_profiles":handshake.configuration.get("request_profiles").cloned(),
+                "model_discovery":handshake.configuration.get("model_discovery").cloned(),
+                "http_endpoints":handshake.configuration.get("http_endpoints").cloned().unwrap_or_else(|| json!([])),
+                "continuation_state":continuation_state,
+                "models":handshake.configuration.get("static_models").cloned().unwrap_or_else(|| {
+                    if handshake.configuration["model_discovery"]["include_static"] == false { json!([]) }
+                    else { json!([{"id":"plugin-model", "operations":["generate"]}]) }
+                }),
+            }))
+            .unwrap()
+        }),
+    };
+    let peer = Arc::new(Peer {
+        registration,
+        configuration: handshake.configuration,
+        prepared: Mutex::new(BTreeMap::new()),
+        output,
+        callbacks: Mutex::new(BTreeMap::new()),
+        next_callback: AtomicU64::new(2),
+        model_queries: AtomicU64::new(0),
+        profile_queries: AtomicU64::new(0),
+        streams: Mutex::new(BTreeMap::new()),
+    });
+    let exit_after_ready = peer.configuration["exit_after_ready_delays_ms"]
+        .as_array()
+        .and_then(|delays| delays.get(startup))
+        .and_then(Value::as_u64)
+        .or_else(|| peer.configuration["exit_after_ready_ms"].as_u64());
+    let exit_after_ready_signal = peer.configuration["exit_after_ready_signals"]
+        .as_array()
+        .and_then(|signals| signals.get(startup))
+        .and_then(Value::as_str)
+        .map(ToOwned::to_owned);
+    peer.send(
+        Message::Ready {
+            protocol_version: gateway_plugin_sdk::PROTOCOL_VERSION,
+            incarnation: handshake.incarnation,
+        },
+        vec![],
+    )
+    .await;
+    if let Some(delay) = exit_after_ready {
+        tokio::spawn(async move {
+            tokio::time::sleep(Duration::from_millis(delay)).await;
+            std::process::exit(7);
+        });
+    } else if let Some(signal) = exit_after_ready_signal {
+        tokio::spawn(async move {
+            while !std::path::Path::new(&signal).exists() {
+                tokio::time::sleep(Duration::from_millis(5)).await;
+            }
+            std::process::exit(7);
+        });
+    }
+    let mut tasks = BTreeMap::new();
+    let mut uncancellable = std::collections::BTreeSet::new();
+    let mut last_call = 0;
+    while let Ok(frame) = read_frame(&mut input, 1024 * 1024).await {
+        match frame.message {
+            Message::Call {
+                id,
+                method,
+                params,
+                context,
+            } => {
+                assert!(id > last_call && !id.is_multiple_of(2) && context.call_id == id);
+                last_call = id;
+                if matches!(
+                    method.as_str(),
+                    "malformed_truncated_frame" | "malformed_frame_length"
+                ) {
+                    let bytes: &[u8] = if method == "malformed_truncated_frame" {
+                        // 声明 16 字节元数据，却只写入一个字节后退出。
+                        &[0, 0, 0, 16, 0, 0, 0, 0, b'{']
+                    } else {
+                        // 元数据长度超过公开的 64 KiB 上限，读取端必须在分配前拒绝。
+                        &[0, 1, 0, 1, 0, 0, 0, 0]
+                    };
+                    let mut output = tokio::io::stdout();
+                    output.write_all(bytes).await.unwrap();
+                    output.flush().await.unwrap();
+                    std::process::exit(42);
+                }
+                peer.append_observation_marker("maintenance_context_marker", &json!({"method":method,"stage":context.stage,"account_id":context.account_id,"credential_revision":context.credential_revision,"request_id":context.request_id}));
+                if peer.configuration["expected_maintenance_methods"]
+                    .as_array()
+                    .is_some_and(|methods| {
+                        methods
+                            .iter()
+                            .any(|expected| expected.as_str() == Some(&method))
+                    })
+                {
+                    assert_eq!(context.stage, gateway_plugin_sdk::Stage::Maintenance);
+                    assert!(
+                        context
+                            .request_id
+                            .as_deref()
+                            .is_some_and(|request| request.starts_with("worker:"))
+                    );
+                }
+                tasks.retain(|_, task: &mut tokio::task::JoinHandle<()>| !task.is_finished());
+                if method == "hang_uncancellable" {
+                    uncancellable.insert(id);
+                }
+                if method.starts_with("stream")
+                    || matches!(
+                        method.as_str(),
+                        "provider.execute" | "provider.avatar" | "middleware.handle"
+                    )
+                {
+                    peer.streams
+                        .lock()
+                        .await
+                        .insert(id, Arc::new(Credits::default()));
+                }
+                let peer = Arc::clone(&peer);
+                tasks.insert(
+                    id,
+                    tokio::spawn(
+                        async move { peer.respond(id, method, params, frame.payload).await },
+                    ),
+                );
+            }
+            Message::Cancel { id } => {
+                if uncancellable.contains(&id) {
+                    continue;
+                }
+                if let Some(task) = tasks.remove(&id) {
+                    task.abort();
+                    let _ = task.await;
+                }
+                peer.streams.lock().await.remove(&id);
+                peer.callbacks
+                    .lock()
+                    .await
+                    .retain(|_, callback| callback.parent != id);
+                peer.append_observation_marker(
+                    "execution_cancelled_marker",
+                    &json!({"call_id":id}),
+                );
+                peer.send(Message::Cancelled { id }, vec![]).await;
+            }
+            Message::Credit { id, bytes, frames } => {
+                if let Some(credits) = peer.streams.lock().await.get(&id) {
+                    credits.grant(bytes, frames).await;
+                }
+            }
+            Message::Result { id, result } => {
+                let parent = peer.callbacks.lock().await.remove(&id);
+                if let Some(callback) = parent {
+                    if let Some(response) = callback.response {
+                        let _ = response.send(Ok((result, frame.payload)));
+                    } else {
+                        peer.send(
+                            Message::Result {
+                                id: callback.parent,
+                                result,
+                            },
+                            frame.payload,
+                        )
+                        .await;
+                    }
+                }
+            }
+            Message::Error { id, error } => {
+                let parent = peer.callbacks.lock().await.remove(&id);
+                if let Some(callback) = parent {
+                    if let Some(response) = callback.response {
+                        let _ = response.send(Err(error));
+                    } else {
+                        peer.send(
+                            Message::Error {
+                                id: callback.parent,
+                                error,
+                            },
+                            frame.payload,
+                        )
+                        .await;
+                    }
+                }
+            }
+            Message::Shutdown => break,
+            _ => {}
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/Cargo.toml b/backend/crates/gateway-plugin/sdk/Cargo.toml
new file mode 100644
index 000000000..a70a37582
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/Cargo.toml
@@ -0,0 +1,29 @@
+[package]
+name = "gateway-plugin-sdk"
+version = "0.4.0"
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+rust-version.workspace = true
+autotests = false
+
+[features]
+default = []
+io = ["dep:tokio"]
+
+[dependencies]
+semver = { version = "1.0.27", features = ["serde"] }
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.150"
+thiserror = "2.0.18"
+tokio = { version = "1.52.3", optional = true, default-features = false, features = ["io-util", "macros", "rt", "sync", "time"] }
+
+[dev-dependencies]
+tokio = { version = "1.52.3", default-features = false, features = ["io-util", "macros", "rt", "sync", "time"] }
+
+[[test]]
+name = "main"
+path = "tests/main.rs"
+
+[lints]
+workspace = true
diff --git a/backend/crates/gateway-plugin/sdk/README.md b/backend/crates/gateway-plugin/sdk/README.md
new file mode 100644
index 000000000..039e09a30
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/README.md
@@ -0,0 +1,103 @@
+# Gateway Plugin SDK
+
+用于编写 Codex Proxy 插件的 Rust 合同与可选会话辅助。插件只依赖本包，不依赖宿主 Core、Admin、Store 或 Host。
+SDK 仍处于实验阶段；能力是否可用取决于宿主支持、清单声明、实际注册和安装时接受的访问域，
+而不只是枚举中存在该名称。
+
+| 版本 | 当前值 | 用途 |
+| --- | --- | --- |
+| SDK 包 | `0.4.0` | Rust 开发依赖，独立于网关版本 |
+| `manifestVersion` | `3` | 安装清单格式 |
+| `package.protocolVersion` | `4` | 宿主与插件的进程通信 |
+| `contributes.*.version` | `1` | 单项能力合同 |
+
+开发顺序：编写[清单](docs/manifest.md) → 实现[能力处理器](docs/capabilities.md) → 用 [CLI](../../../apps/plugin-cli/README.md)
+打包 → [安装、配置与启用](../../../../docs/plugins.md)。完整可运行示例位于独立仓库
+`codex-proxy-plugins` 的 `examples/workbench`。
+
+使用 AI 协作开发时，可调用仓库技能 [`$plugin-dev`](../../../../.agents/skills/plugin-dev/SKILL.md)，按任务定位合同、示例和验证入口。
+
+## 模块与依赖
+
+| 入口 | 职责 |
+| --- | --- |
+| 根门面 | 清单、能力声明、调用上下文、消息与帧、公开错误 |
+| `call::auth` | 凭据导入、导出、轮换、刷新和登录的数据合同 |
+| `call::frontend_authentication` | 数据面认证信封、认证器标识与外部 principal 结果 |
+| `call::provider` | 注册、模型、执行、计费；子模块 `account`、`quota`、`reset_credits` 提供账号资料、额度和重置卡合同 |
+| `call::middleware` | 洋葱中间件请求/响应 head、single-use next 与惰性正文 frame 合同 |
+| `call::policy` | 模型路由、账号调度及终态用量观察合同 |
+| `call::observation` | 实际上游 WebSocket 响应帧的只读观察合同 |
+| `call::host` | 账号、私有状态、受管 HTTP、模型、亲和、日志及调用内流的宿主回调合同 |
+| `call::management` | 管理 API、页面与资源声明、公开回调，以及 CLI 命令与待保存账号 |
+| `client` | 通过 `io` feature 开启的 `PluginBuilder`、会话、中间件与异步帧收发 |
+
+`call/` 按业务能力组织数据，`message.rs` 定义消息与帧。请求／响应改写、协议转换和思考参数映射统一使用
+`call::middleware`；WebSocket 观察接口不能改写连接。
+
+插件使用的导入路径例如：
+
+```rust
+use gateway_plugin_sdk::{Frame, Message, PluginFault};
+use gateway_plugin_sdk::call::{auth::LoginPollResult, provider::ExecutionEvent};
+// 需要 Cargo 依赖声明启用 features = ["io"]。
+use gateway_plugin_sdk::client::{read_frame, write_frame};
+```
+
+默认 feature 不引入异步运行时。`io` 除帧编解码外，还提供 `PluginBuilder`、
+`PluginSession::accept/run` 和 `PluginHandler`。组合插件从作者清单建立类型化方法，SDK 自动生成
+`plugin.register`；作者不需要复制贡献项或手写方法名、阶段和敏感载荷编解码。
+会话管理握手、有界并发、父调用关联、回调、流信用、取消、排空与关闭。
+`ResponseStream::channel` 提供有界流生产入口；`PluginCall` 的宿主客户端只代表当前父调用，
+不能用另一调用的 ID 扩大权限。插件程序自行选择运行时和启动入口，不会启动网关。
+`SessionConfig` 默认帧上限与宿主默认值一致，为 1 MiB；部署调整宿主帧上限时，插件应同步配置，
+当前握手不自动协商该限制。流式分块还必须满足宿主实际授予的信用窗口。
+
+## 通信边界
+
+启用 `io` 时优先用 [`PluginBuilder`](docs/capabilities.md#类型化作者入口) 组合业务处理器，再交给
+`PluginSession::run`。仅实现中间件时也可直接使用
+[`MiddlewarePlugin`](docs/capabilities.md#洋葱中间件)。
+
+```mermaid
+sequenceDiagram
+  participant H as 宿主 Runtime
+  participant P as 插件会话
+  H->>P: Hello
+  P-->>H: Ready（相同 incarnation）
+  H->>P: 注册能力，核对清单
+  P-->>H: 注册结果
+  H->>P: Call（ID、上下文、载荷）
+  opt 需要宿主资源且已获授权
+    P->>H: 回调（关联父调用 ID）
+    H-->>P: 回调结果
+  end
+  P-->>H: 结果或错误；流以 End 结束
+```
+
+### 帧与会话
+
+每帧以两个大端 `u32` 分别声明 JSON 元数据和二进制载荷的长度，随后依次传输两部分。
+调用方提供总长度上限；元数据另有 64 KiB 上限。读取在分配内存前校验长度，截断帧和
+无效元数据返回 `FrameError`。这些函数不自动重试调用；部分读取或写入中断后，不应
+把同一字节位置误当作新帧边界。
+底层 `read_frame` / `write_frame` 不是取消安全的；自行编排会话时，不能在 `select!` 的其他分支完成后
+重建半途中的帧读写。`PluginSession` 会在处理调用完成通知时保留同一个读取 future，直到完整帧到达或会话关闭。
+
+会话由宿主发送 `Hello`，插件校验协议后返回携带相同 incarnation 的 `Ready`。
+注册结果必须与清单中的能力一致。一次 `Call` 的结果、错误和流帧按 ID 关联；回调必须
+携带当前父调用 ID。实例、代次、阶段、账号或资源 ID 是关联数据，不能自行充当授权。
+
+## 本地验证
+
+从仓库根目录执行：
+
+```bash
+RUST_MIN_STACK=16777216 cargo +1.97.0 test --manifest-path backend/Cargo.toml -p gateway-plugin-sdk --no-default-features --locked
+RUST_MIN_STACK=16777216 cargo +1.97.0 test --manifest-path backend/Cargo.toml -p gateway-plugin-sdk --all-features --locked
+RUST_MIN_STACK=16777216 RUSTDOCFLAGS='-D warnings' cargo +1.97.0 doc --manifest-path backend/Cargo.toml -p gateway-plugin-sdk --all-features --no-deps --locked
+```
+
+源码中的类型和字段是当前合同；宿主接入、目录边界与 Runtime 集成验证见
+[系统架构](../../../../docs/architecture.md)。Provider 实现只依赖公开 SDK 合同，宿主不按插件 ID 特判。
+单元测试与文档构建不代替目标平台上的安装、授权及实际能力验证。
diff --git a/backend/crates/gateway-plugin/sdk/docs/capabilities.md b/backend/crates/gateway-plugin/sdk/docs/capabilities.md
new file mode 100644
index 000000000..dc8dad25b
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/docs/capabilities.md
@@ -0,0 +1,257 @@
+# 插件能力与回调
+
+[返回 SDK](../README.md) · [清单与图标](manifest.md)
+
+`contributes` 声明插件提供什么功能，`permissions` 声明插件需要访问哪些宿主资源。两者不是同一件事：
+管理页面可以调用现有模型而不实现 Provider；Provider 也只有在需要额外访问宿主资源时才声明对应权限。
+
+## 类型化作者入口
+
+启用 `io` feature 后，组合插件优先使用 `client::PluginBuilder`：
+
+```rust,ignore
+use gateway_plugin_sdk::client::{PluginBuilder, methods};
+
+let plugin = PluginBuilder::from_json(include_bytes!("../plugin.json"))?
+    .management(management_registration(), handle_management)?
+    .command_line(command_registration(), handle_command)?
+    .on(methods::ROUTE_MODEL, route_model)?
+    .build()?;
+
+session.run(plugin).await?;
+```
+
+`PluginBuilder::from_json` 与 `cpr-plugin package` 使用同一个作者清单规范化入口。构建器负责：
+
+- 自动响应 `plugin.register`，注册内容直接来自规范化后的清单
+- 按方法合同解码控制参数和二进制载荷，并在进入业务处理器前检查调用阶段
+- 保留 `TypedCall` 中的调用上下文、宿主客户端和取消信号
+- 按方法合同编码 `TypedReply`，流式结果继续复用有界 `ResponseStream`
+- 在 `build()` 时核对能力、必需处理器及 Provider 描述，避免清单与分派表漂移
+
+`management`、`command_line` 和 `middleware` 是常用组合入口；其余能力使用
+`on(methods::..., handler)`。方法常量固定请求、响应、阶段与载荷位置，作者不手写 RPC 方法名。
+状态迁移不是 capability：清单任一 `state[]` 声明了 `migratesFrom` 时，注册
+`methods::STATE_MIGRATE`，构建器也会要求该处理器存在。
+
+类型化合同故意区分三种数据：普通控制元数据、可能敏感的 JSON 二进制载荷、原始字节。
+例如 CLI 参数、账号凭据和状态迁移批次使用二进制 JSON，管理 HTTP 正文保持原始字节，
+Provider 准备输入使用 `GPQ1`。错误地把敏感载荷放进控制参数会在业务处理器运行前被拒绝。
+
+## 能力与方法
+
+Provider 业务组包含 `executor`，并可选择 `models`、`authentication`、`quota`、
+`request_profile`、`account_management`、`billing`、`maintenance`。作者清单的简写见
+[Provider 业务组](manifest.md#provider-业务组)。独立能力如下：
+
+| 能力 | 类型化方法 |
+| --- | --- |
+| `middleware` | `PluginBuilder::middleware` / `middleware.handle` |
+| `model_router` | `methods::ROUTE_MODEL` |
+| `scheduler` | `methods::SCHEDULE_ACCOUNT` |
+| `request_lifecycle`、`usage` | `methods::OBSERVE_REQUEST`，同一实例的终态订阅合并调用 |
+| `web_socket_observer` | `methods::OBSERVE_WEBSOCKET`，线方法为 `websocket.response_event` |
+| `frontend_authentication` | `methods::FRONTEND_IDENTIFIER`、`methods::FRONTEND_AUTHENTICATE` |
+| `management` | `PluginBuilder::management`；公开回调另用 `methods::MANAGEMENT_CALLBACK` |
+| `command_line` | `PluginBuilder::command_line` |
+
+## 五个访问域
+
+安装时接受清单声明的访问域，不存在另一套逐方法、逐用途或资源 ID 白名单。宿主仍会检查父调用、阶段、
+期限、实例代次、资源归属，以及 Key、账号和 Provider 自身的业务规则。
+
+| 权限 | 开放的宿主能力 |
+| --- | --- |
+| `network` | 通过 `host.http.*` 使用宿主受管出站网络；仍受统一代理、超时、大小和流控规则约束 |
+| `models` | 列出非秘密 Key、按所选 Key 查询模型，以及通过 `host.model.*` 调用模型；调用可能产生消耗 |
+| `accounts` | 查询账号、读取原始凭据及创建或替换账号；写入仍经过 revision CAS、审计和发布事务 |
+| `requests` | 参与请求／响应处理、路由、调度、观察及亲和查询 |
+| `public_endpoints` | 提供无需登录即可访问的已声明静态资源或一次性票据回调 |
+
+`host.log` 和本插件声明的 `host.state.*` 是基础设施，不需要额外 permission。公开调用阶段不开放任何
+宿主回调；权限也不能把一个父调用的句柄、流或上下文转移到另一个调用。
+
+## Provider
+
+调用 `.provider(ProviderDescriptor)` 冻结 Provider 的模型、认证操作、账号操作、计费与画像描述。
+`build()` 会要求 `executor` 的准备、执行、释放和连接测试处理器齐全，并根据描述符中选择的操作要求
+对应凭据、账号、模型、额度或画像处理器；描述符与能力不一致会直接失败。
+Provider 执行使用宿主选择的账号和凭据，因此 Provider 清单需要 `accounts` 访问域；需要宿主代发 HTTP 时再声明
+`network`。这里的权限开放宿主端口，不替代 Provider 描述和处理器声明。
+
+Provider 执行分为：
+
+1. `provider.prepare` 在 `attempt` 阶段接收 `ExecutionInput`，只准备执行并返回 `PreparedExecution`，不能发送推理请求。
+2. `provider.execute` 在 `execution` 阶段使用准备 token，返回 `ResponseStream`；SDK 固定初始结果为 `{"stream":true}`。
+3. `provider.discard` 在 `attempt` 阶段释放没有执行或已经结束的准备 token。
+4. `provider.connection_test` 在 `configuration` 阶段生成由宿主执行的探测操作。
+
+`ExecutionInput` 与 `ExecutionEvent` 分别使用 `GPQ1`、`GPE1` 长度编码，把请求正文、原始 wire 和失败正文
+保留在独立二进制段。流必须遵守宿主授予的字节／帧信用，不能用分片绕过单片、聚合总量或终态检查。
+`PrepareExecution.headers` 只包含 Attempt 中间件追加并经宿主复核的业务 header，不能覆盖认证、目标或传输字段。
+
+静态模型放在 `ProviderDescriptor.models`；声明 `models` 时还要提供账号模型发现描述和
+`provider.models`。认证操作由 `credential_operations` 决定；账号资料、订阅、头像和重置卡由
+`account_operations` 决定。插件只返回准备事实，账号 ID 分配、凭据 revision、提交事务、计费和审计仍由宿主拥有。
+
+`continuation_state` 可声明稳定格式、当前写版本和可读版本集合。兼容声明只允许当前执行器解释旧检查点，
+不会放宽插件、实例、配置、账号、凭据 revision 或当前请求身份的复核。
+
+## 宿主资源回调
+
+所有回调都通过当前 `TypedCall.host` 发起，并受父调用截止时间和取消信号约束。
+
+### 账号与凭据
+
+`accounts` 域开放 `host.auth.list/get_runtime/get/save`：
+
+- `list` 可用 `provider_id` 过滤并分页，返回不含原始凭据的运行投影
+- `get` 的原始凭据只放在二进制载荷中
+- `save` 新建时显式提供 Provider，由宿主生成账号 ID；替换时必须提交精确 credential revision
+
+插件可以自行选择其业务需要的账号和 Provider，不需要安装器预先配置允许列表。宿主仍校验账号归属、资格、
+凭据版本和并发事务；原始凭据不得进入日志、审计正文或控制元数据。
+
+### Key、模型与模型调用
+
+`models` 域开放：
+
+- `host.keys.list`：只返回 `{id, name, enabled}`，不返回 Key 明文、前缀或隐藏 scope
+- `host.models.list`：以显式 `client_key_id` 查询该 Key 当前可见的模型目录
+- `host.model.execute[_stream]`：交给 Core 的路由、准入、租约、重试、账本和计费链路执行
+- `host.model.stream_read/close`：读取或关闭当前父调用创建的有界流
+
+`management`、`command_line`、`maintenance`、`authentication` 和 `observation` 阶段调用模型时，在
+`ModelExecuteRequest.client_key_id` 中显式选择执行 Key；`request`、`attempt`、`execution`、`routing` 和
+`scheduling` 阶段将该字段留空并继承父请求身份，不能切换 Key。Key 的启用状态、模型规则、账号组、并发和预算
+始终使用调用时的当前事实。
+插件不能读取 Key 明文，也不能用一个 Key 查询结果替另一个 Key 执行。
+
+非流式模型结果通过 `ModelEventBatch` 的 `HME1` 二进制批次返回；流式句柄只在创建它的父调用内有效。
+发起回调的插件实例在子调用中跳过，Core 还会限制递归深度、总数和并发，避免插件调用自身形成环。
+
+`host.affinity.lookup` 属于 `requests` 域，只查询 Provider 已持久化的真实亲和键。命中只是账号偏好，
+后续执行仍重新检查当前 Key 规则、账号资格和租约。
+
+### 网络
+
+`network` 域通过 `host.http.do/do_stream` 和流读取／关闭方法提供受管 HTTP。URL、header 和正文可能含敏感数据，
+正文使用独立二进制载荷。宿主统一施加代理、超时、帧与流限制；插件不能绕过宿主端口取得额外调用身份。
+地址被拒绝返回 `permission_denied`，期限耗尽返回 `timeout`，解析、连接或响应读取失败返回 `upstream`。
+这些 HTTP 业务错误的 `message` 是宿主生成的安全分类提示，不包含目标 URL、凭据或上游错误正文，
+插件可以在相应操作中展示；协议故障不应直接展示内部消息。Fake-IP 环境按[部署排障](../../../../../deploy/README.md#插件取文与-fake-ip-dns)
+调整 DNS，不通过放宽地址范围解决。
+
+## 请求扩展
+
+### 洋葱中间件
+
+`middleware` 的 `request` mount 在逻辑请求外层执行一次，`attempt` mount 在每次选定 Provider 和账号后重建。
+作者必须在清单中显式选择一个或两个阶段。`PluginBuilder::middleware` 接收 `MiddlewareCall`，其中
+`next.run(request)` 是 single-use continuation；响应按相反顺序穿过中间件。
+
+请求正文和响应帧受 `requests` 域保护。没有正文时仍要区分“保持原正文”和“替换为空”：默认使用
+`MiddlewareRequestBody::Preserve`，只有 `replace_body(Vec::new())` 才表示清空。Header 修改采用增量
+remove/append，保留合法多值。`MiddlewareBody::map_frames` 复用会话的流控和唯一终态，不建立插件全局流表。
+
+仅实现中间件时也可使用轻量的 `MiddlewarePlugin`；需要与管理、Provider 或其他方法组合时使用
+`PluginBuilder`，两者复用相同的 `MiddlewareCall` 和 `MiddlewareResponse`。
+
+### 路由、调度与观察
+
+`policy.route_model` 和 `policy.schedule_account` 只提出决定，宿主随后复核 Key 规则、模型能力、账号资格和租约。
+`policy.observe_request` 接收一次最终请求事实；`request_lifecycle` 提供终态，`usage` 提供最终标准化用量、费用和耗时。
+缺失值表示宿主没有该事实，不等于零，也不能由插件重新计价。
+
+`websocket.response_event` 只读观察真实上游 WS 事件，元数据与原始帧分开传输。事件序号在请求内单调递增；
+有界队列丢弃可能产生间隔。观察超时、过载或插件失败不改变业务响应，插件也不能修改 WS 帧。
+
+观察计划在请求开始时冻结，最终事件最多派发一次。`Handshake`、`Message`、`Frame` 和 `PluginFault` 的
+调试输出会隐藏配置、载荷与错误正文；插件自己的日志同样不能输出凭据或完整请求。
+
+## 状态、日志与迁移
+
+清单 `state[]` 声明命名空间、`schemaVersion`、JSON schema、记录与字节配额。运行时用
+`host.state.get/put/delete` 访问；创建要求键不存在，更新和删除必须提供精确版本。状态始终绑定当前
+插件实例、制品和 schema，不能直接读写宿主数据库。
+
+不兼容升级由宿主停用并排空旧会话，再调用 `plugin.state.migrate` 分批迁移到暂存状态。插件逐项返回
+keep、replace 或 delete；全部完成后宿主才原子提交新配置与状态，失败时丢弃暂存结果。
+
+`host.log` 接收固定事件名、级别和有界字段。宿主脱敏并限制速率；`recorded: true` 只表示已交给有界日志任务。
+日志和私有状态无需 permission，但注册、配置与公开管理阶段仍受各自的回调生命周期限制。
+
+## 管理页面、公开入口与 CLI
+
+`PluginBuilder::management` 同时冻结 `ManagementRegistration` 并绑定 `management.handle`。请求元数据在控制参数，
+原始 HTTP 正文在二进制载荷；响应同样分离。宿主不转交管理 Cookie、Authorization 或任意 header，插件也不能
+返回任意响应 header。账号操作通过 `accounts` 域调用宿主，资源由调用参数选择，不在路由注册中固定 Provider。
+
+页面运行在隔离 iframe 中，静态资源必须同时出现在清单 `resources` 和管理注册中。标记为公开的资源及一次性
+票据回调需要 `public_endpoints`；`management.callback` 使用 `public_management` 阶段，并且不能调用账号、
+网络、模型、状态或日志端口。
+
+宿主自动注入尺寸监听与上报脚本，为 `body` 设置扣除页面头部和外侧留白后的最小高度，整页滚动由管理端承接。
+插件无需调用 resize、发送尺寸消息或安装桥接依赖；Vue 等框架的根容器需要延续最小高度时，使用普通 CSS `min-height: inherit`。
+页面使用自然文档流，内容增加或减少时自动同步高度；不使用 `100vh`、`height: 100%`、整页固定定位或内部滚动容器代替文档流。
+编辑器、日志等局部区域可自行限高滚动，脱离文档流的浮层不会用于撑高页面。
+
+### 页面宿主桥 v2
+
+宿主注入只读的 `window.codexProxyPlugin`。`request({ method, path, query?, contentType?, body? })` 只能访问当前版本
+已注册的管理路由，返回 `{ status, contentType, body: ArrayBuffer }`；`callbackTicket({ path, ttlSeconds })` 为已注册
+回调签发 1–600 秒的一次性地址；`resourceUrl(path)` 只解析同一制品已注册的非 HTML 资源。`theme` 为当前
+`light` / `dark` 值，变化时触发 `codex-proxy-themechange`。页面不能指定其他实例、制品、版本、URL 或请求 header。
+
+普通模型请求使用标准 `Response` 接口：
+
+```ts
+interface PluginModelsBridge {
+  responses(input: {
+    clientKeyId: string
+    body: Record<string, unknown>
+    signal?: AbortSignal
+  }): Promise<Response>
+}
+
+interface CodexProxyPluginBridge {
+  readonly version: 2
+  readonly models: PluginModelsBridge
+}
+
+declare global {
+  interface Window {
+    readonly codexProxyPlugin: CodexProxyPluginBridge
+  }
+}
+
+const controller = new AbortController()
+const response = await window.codexProxyPlugin.models.responses({
+  clientKeyId: selectedClientKeyId,
+  body: { model: 'gpt-5', input: 'Hello', stream: true },
+  signal: controller.signal,
+})
+if (!response.ok)
+  throw new Error(await response.text())
+for await (const chunk of response.body!) {
+  // chunk 是原生 Responses JSON 或 SSE 字节流的一部分。
+}
+```
+
+`clientKeyId` 是管理端 Key 标识，不是 Key 原文；页面可通过自己的已注册管理路由调用 `host.keys.list` 和
+`host.models.list` 获取 Key 候选及其可见模型，但桥不会读取或返回秘密。该请求进入普通 Responses 数据面，
+因此当前实例自己的 middleware、router、scheduler 和
+observer 也按常规计划执行；它不是插件执行期间的嵌套 `host.model` 回调。正文最多 8 MiB，每页最多 4 个并发模型
+请求，总时限 10 分钟；响应以不超过 64 KiB 的单块 pull/ack 传输。页面 30 秒不继续消费响应、调用
+`AbortController.abort()` / `ReadableStream.cancel()`，或页面被切换、停用、换版时，宿主都会取消请求。桥不接受
+任意 URL、header 或 Key 原文；只转交响应状态、安全 header 以及原生 JSON / SSE 正文。
+
+`PluginBuilder::command_line` 冻结命令帮助并绑定执行函数。注册和执行的 JSON 都位于二进制载荷，控制信封为 `{}`。
+命令若返回待保存账号，需要 `accounts` 域；只有退出码为零时宿主才按顺序执行各自独立的 CAS 提交。
+模型命令通过 `host.keys.list` 展示非秘密 Key，再显式选择 Key 查询模型和执行，不依赖安装时预绑定。
+
+## 数据面入口认证
+
+`frontend_auth.identifier` 返回稳定认证器标识；`frontend_auth.authenticate` 接收敏感的 Authorization 载荷并返回
+外部 principal。插件不能指定 Client Key，宿主根据当前入口配置完成映射，并继续检查 Key 的启用状态、模型规则、
+账号组、并发和预算。该能力只处理数据面身份，不接管管理端登录。
diff --git a/backend/crates/gateway-plugin/sdk/docs/manifest.md b/backend/crates/gateway-plugin/sdk/docs/manifest.md
new file mode 100644
index 000000000..2e9ec501a
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/docs/manifest.md
@@ -0,0 +1,155 @@
+# 插件清单
+
+[返回 SDK](../README.md) · [能力与回调](capabilities.md)
+
+`Manifest` 对应包内 `plugin.json`。作者源清单由 `Manifest::from_author_slice` 读取，CLI 打包也调用同一入口；
+因此本地构建器、生成的安装清单和运行注册共享一份规范化结果。
+
+| 字段 | 规则 |
+| --- | --- |
+| `publisher` + `name` | 发布者命名空间与机器短名；`plugin_id()` 派生唯一 ID，如 `acme.echo` |
+| `displayName` / `author` | 人类可读名称 / 可选作者文字，不参与身份与授权 |
+| `version` / `engines` | 插件业务版本 / 宿主版本范围；安装包不能使用全版本通配 `*` |
+| `contributes` | 插件提供的扩展能力；作者可省略可推导字段，并可使用 Provider 业务组简写 |
+| `permissions` | 需要访问的宿主资源域；安装即接受该版本声明的域 |
+| `configurationSchema` / `secretFields` | 普通设置的 schema / 单独保存的敏感字段 |
+| `main` / `resources` | 包内可执行文件 / 资源路径与 MIME 类型 |
+| `state` | [私有状态](capabilities.md#状态日志与迁移)的命名空间、schema 与配额 |
+| `package` | CLI 生成的协议版本、单一目标平台与文件摘要，不需作者手写 |
+
+作者清单不能包含 `package`。使用 `Manifest::from_author_slice()` 校验并规范化；直接反序列化的 `Manifest`
+代表完整合同，不会隐式补全作者字段。打包后，`main` 和所有资源都必须进入 `package.files`；宿主用
+`package_for(host, os, architecture)` 检查版本与平台。运行模式仅为 `trustedProcess`：插件拥有与宿主
+相同的系统身份，**不是进程沙箱**。
+
+## 扩展项简写
+
+普通作者声明可以省略 `id`、`version` 和固定阶段：
+
+```json
+{
+  "contributes": {
+    "management": {},
+    "command_line": {},
+    "middleware": {
+      "stages": ["request"],
+      "inputFormats": ["openai"],
+      "outputFormats": ["openai"]
+    }
+  }
+}
+```
+
+默认扩展项 ID 为 `<publisher>.<name>.<capability-kebab>`，版本固定为 `1`。除 `middleware` 外，阶段由
+capability 固定并由工具生成：
+
+| 阶段 | 能力 |
+| --- | --- |
+| `management` + `maintenance` | `models`、`authentication`、`quota` |
+| `execution` | `executor`、`billing` |
+| `management` + `observation` | `account_management` |
+| `maintenance` | `request_profile`、`maintenance` |
+| `authentication` / `routing` / `scheduling` | `frontend_authentication` / `model_router` / `scheduler` |
+| `observation` | `request_lifecycle`、`web_socket_observer`、`usage` |
+| `management` / `command_line` | `management` / `command_line` |
+
+`middleware` 必须显式选择 `request`、`attempt` 或两者；协议格式等真实业务选择也不能省略。
+安装清单若携带不同的固定阶段会被拒绝，而不是在加载时静默改写。
+
+### Provider 业务组
+
+Provider 作者用一个业务组声明执行协议和可选功能，无需重复 `id`、`version` 与阶段：
+
+```json
+{
+  "contributes": {
+    "provider": {
+      "capabilities": [
+        "models",
+        "authentication",
+        "quota",
+        "account_management",
+        "maintenance"
+      ],
+      "inputFormats": ["openai"],
+      "outputFormats": ["openai"]
+    }
+  }
+}
+```
+
+该简写始终展开 `executor`，并展开所列的 Provider 子能力。可选值只有 `models`、`authentication`、
+`quota`、`request_profile`、`account_management`、`billing`、`maintenance`；协议列表必须非空。
+同一清单不能再显式声明展开得到的能力。简写只存在于作者入口，CLI 会把归档中的 `plugin.json` 写成完整
+`contributes`，`PluginBuilder` 再用同一结果自动注册。
+
+## 权限
+
+权限只有五个稳定访问域：
+
+| 标识 | 含义 |
+| --- | --- |
+| `network` | 使用宿主受管网络 |
+| `models` | 查询非秘密 Key 与模型并调用模型，可能产生消耗 |
+| `accounts` | 查询、读取原始凭据和修改账号 |
+| `requests` | 查看和处理请求、响应、路由、调度与观察事实 |
+| `public_endpoints` | 提供无需登录即可访问的资源或回调 |
+
+安装时统一接受清单声明的域，不再填写逐方法、用途、Key、账号或 Provider 白名单。日志与清单声明的
+本插件私有状态是基础设施，无需单独 permission。权限并不替代方法阶段、父调用、Key 规则、账号 revision、
+资源归属和流生命周期校验，具体接口见[能力与回调](capabilities.md#五个访问域)。
+
+## 插件图标
+
+`icon` 指定管理端展示的插件图标。值可以是一个包内文件路径，也可以是包含 `light`、`dark` 两个路径的对象。
+使用单个路径时，浅色和深色主题共用同一张图；使用主题对象时，管理端按当前主题选择，两项都必须填写。
+不填写 `icon` 时显示通用图标。图标路径不是远程 URL，也不接受内置图标名称。
+
+在 `plugin.json` 中同时设置 `icon` 和对应的 `resources` 项。以下是单图标配置片段：
+
+```json
+{
+  "icon": "assets/icon.svg",
+  "resources": {
+    "assets/icon.svg": "image/svg+xml"
+  }
+}
+```
+
+浅色和深色主题可以使用不同格式的图片：
+
+```json
+{
+  "icon": {
+    "light": "assets/icon-light.svg",
+    "dark": "assets/icon-dark.webp"
+  },
+  "resources": {
+    "assets/icon-light.svg": "image/svg+xml",
+    "assets/icon-dark.webp": "image/webp"
+  }
+}
+```
+
+文件扩展名不区分大小写，文件内容、扩展名与声明的 MIME 类型必须一致：
+
+| 格式 | 扩展名 | `resources` 中的 MIME 类型 |
+| --- | --- | --- |
+| SVG | `.svg` | `image/svg+xml` |
+| PNG / APNG | `.png` | `image/png` |
+| JPEG | `.jpg`、`.jpeg`、`.jfif` | `image/jpeg` |
+| WebP | `.webp` | `image/webp` |
+| GIF | `.gif` | `image/gif` |
+| ICO | `.ico` | `image/vnd.microsoft.icon` 或 `image/x-icon` |
+| BMP | `.bmp` | `image/bmp` 或 `image/x-ms-bmp` |
+
+资源要求：
+
+- 每个图标文件不超过 512 KiB；位图宽、高各为 1–4096 像素
+- GIF、APNG 和 WebP 可以包含动画，每个文件最多 256 帧，累计解码数据不超过 128 MiB
+- SVG 使用 UTF-8 编码，根元素为 SVG 命名空间中的 `<svg>`，XML 节点不超过 16384 个；不使用 DTD 实体或 XML 处理指令
+- SVG 保留矢量、渐变、内联样式和 data URL 内嵌图片；图标不能依赖脚本、外部图片、外部样式或外部字体
+
+将图标文件与清单一同交给 [插件 CLI](../../../../apps/plugin-cli/README.md) 打包。工具收集 `resources` 声明的文件，
+生成 `package.files` 摘要；宿主在安装时验证图标内容。管理端通过 [图标读取接口](../../../../../docs/api.md#12-插件管理)
+以图片方式展示，不将 SVG 源码插入页面 HTML。
diff --git a/backend/crates/gateway-plugin/sdk/src/call/auth.rs b/backend/crates/gateway-plugin/sdk/src/call/auth.rs
new file mode 100644
index 000000000..9e052784e
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/auth.rs
@@ -0,0 +1,85 @@
+//! 认证与凭据调用合同；输入输出放在帧载荷中，账号 ID、版本和提交事务由宿主生成。
+
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CredentialOperation {
+    Import,
+    Export,
+    Rotate,
+    Refresh,
+    Login,
+}
+
+// 凭据文档与账号资料不可通过 Debug 写入诊断。
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CredentialFacts {
+    pub name: String,
+    pub authentication_kind: String,
+    pub material: Map<String, Value>,
+    pub email: Option<String>,
+    pub upstream_user_id: Option<String>,
+    pub upstream_account_id: Option<String>,
+    pub plan_type: Option<String>,
+    #[serde(default)]
+    pub has_refresh_token: bool,
+    pub access_token_expires_at_ms: Option<i64>,
+    pub next_refresh_at_ms: Option<i64>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ImportedCredentials {
+    pub accounts: Vec<CredentialFacts>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExportCredential {
+    pub account_id: String,
+    pub credential_revision: u64,
+    pub facts: CredentialFacts,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RotateCredential {
+    pub current: ExportCredential,
+    pub replacement: Option<Map<String, Value>>,
+}
+
+/// 登录上下文不包含管理员身份；流程与账号归属由宿主绑定。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct LoginStart {
+    pub name: Option<String>,
+    pub account_id: Option<String>,
+    #[serde(default)]
+    pub input: Map<String, Value>,
+}
+
+/// state 只在加密临时存储与插件载荷间流转，不返回浏览器。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct LoginStarted {
+    pub authorization_url: String,
+    pub expires_at_ms: i64,
+    pub state: Map<String, Value>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct LoginPoll {
+    pub state: Map<String, Value>,
+    pub callback_url: Option<String>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(tag = "status", rename_all = "snake_case", deny_unknown_fields)]
+pub enum LoginPollResult {
+    Pending { retry_after_ms: u64 },
+    Complete { accounts: Vec<CredentialFacts> },
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/frontend_authentication.rs b/backend/crates/gateway-plugin/sdk/src/call/frontend_authentication.rs
new file mode 100644
index 000000000..0b944ff9a
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/frontend_authentication.rs
@@ -0,0 +1,50 @@
+//! 数据面入口认证合同；宿主拥有 principal 到执行身份的映射。
+
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+
+/// 插件在注册阶段返回的稳定认证器标识。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct FrontendAuthenticationIdentifier {
+    pub identifier: String,
+}
+
+/// API 提取的有界认证信封；Cookie、管理会话及客户端画像不进入插件调用。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct FrontendAuthenticationRequest {
+    pub authorization: String,
+}
+
+impl fmt::Debug for FrontendAuthenticationRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("FrontendAuthenticationRequest")
+            .field("authorization", &"[REDACTED]")
+            .finish()
+    }
+}
+
+/// 插件只声明外部 principal，不得选择宿主 Client Key。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "outcome", rename_all = "snake_case", deny_unknown_fields)]
+pub enum FrontendAuthenticationResult {
+    Authenticated { principal: String },
+    NotMatched {},
+    Rejected {},
+}
+
+impl fmt::Debug for FrontendAuthenticationResult {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Authenticated { .. } => formatter
+                .debug_struct("Authenticated")
+                .field("principal", &"[REDACTED]")
+                .finish(),
+            Self::NotMatched {} => formatter.write_str("NotMatched"),
+            Self::Rejected {} => formatter.write_str("Rejected"),
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/host.rs b/backend/crates/gateway-plugin/sdk/src/call/host.rs
new file mode 100644
index 000000000..a9d8b510b
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/host.rs
@@ -0,0 +1,457 @@
+//! 宿主回调的数据合同；这里只传递数据，不持有宿主服务或执行资源。
+
+use serde::{Deserialize, Serialize};
+
+use super::auth::CredentialFacts;
+use super::provider::ExecutionEvent;
+
+const MODEL_EVENT_BATCH_PREFIX: [u8; 4] = *b"HME1";
+const MAX_MODEL_EVENT_BATCH_BYTES: usize = 8 * 1024 * 1024;
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum LogLevel {
+    Debug,
+    #[default]
+    Info,
+    Warn,
+    Error,
+}
+
+/// event 必须是代码中固定的事件标识，不能填入凭据、URL 或请求内容。
+/// 宿主只记录 event 的长度和摘要，不因标识字符合法而放行明文。
+/// fields 由宿主按诊断规则脱敏；不能通过自定义字段声明内容可信。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct LogRequest {
+    pub event: String,
+    #[serde(default)]
+    pub level: LogLevel,
+    #[serde(default)]
+    pub fields: std::collections::BTreeMap<String, serde_json::Value>,
+}
+
+/// 超出日志预算时直接丢弃，不等待、不排队，插件不应重试。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct LogResult {
+    /// 是否交给有界异步日志写入；不保证立即落盘，最终级别过滤仍由宿主决定。
+    pub recorded: bool,
+}
+
+/// URL、头和正文可能携带敏感材料，不提供内容型 Debug。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct HttpRequest {
+    pub method: String,
+    pub url: String,
+    #[serde(default)]
+    pub headers: Vec<(String, String)>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct HttpResponse {
+    pub status: u16,
+    pub headers: Vec<(String, String)>,
+    pub stream: Option<String>,
+}
+
+/// 宿主账号列表查询；cursor 是上次结果返回的稳定账号 ID。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AuthListRequest {
+    pub provider_id: Option<String>,
+    pub cursor: Option<String>,
+    pub limit: u16,
+}
+
+/// 不含原始凭据的账号运行投影。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AuthRuntimeAccount {
+    pub account_id: String,
+    pub provider_id: String,
+    pub credential_revision: u64,
+    pub name: String,
+    pub email: Option<String>,
+    pub upstream_user_id: Option<String>,
+    pub upstream_account_id: Option<String>,
+    pub plan_type: Option<String>,
+    pub authentication_kind: String,
+    pub enabled: bool,
+    pub credential_state: String,
+    pub has_refresh_token: bool,
+    pub access_token_expires_at_ms: Option<i64>,
+    pub next_refresh_at_ms: Option<i64>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AuthListResult {
+    pub accounts: Vec<AuthRuntimeAccount>,
+    pub next_cursor: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AuthGetRequest {
+    pub account_id: String,
+}
+
+/// 原始凭据只在 RPC 二进制载荷中传输，故意不实现 `Debug`。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AuthCredential {
+    pub account_id: String,
+    pub provider_id: String,
+    pub credential_revision: u64,
+    pub facts: CredentialFacts,
+}
+
+/// 新建账号由宿主生成 ID；替换账号必须提交精确 credential revision。
+/// 凭据只在 RPC 二进制载荷中传输，故意不实现 `Debug`。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(tag = "action", rename_all = "snake_case", deny_unknown_fields)]
+pub enum AuthSaveRequest {
+    Create {
+        provider_id: String,
+        facts: CredentialFacts,
+    },
+    Replace {
+        account_id: String,
+        credential_revision: u64,
+        facts: CredentialFacts,
+    },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AuthSaveResult {
+    pub account_id: String,
+    pub credential_revision: u64,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StreamRead {
+    pub stream: String,
+    pub maximum_bytes: u32,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StreamClose {
+    pub stream: String,
+}
+
+/// 模型执行回调可交给 Core 的稳定操作；Provider 私有端点不属于模型回调。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ModelOperation {
+    Generate,
+    GenerateImage,
+    EditImage,
+    Search,
+}
+
+/// 模型执行回调的请求元数据；正文始终使用 RPC 的独立二进制载荷。
+///
+/// Provider/账号是进一步收窄，不是绕过父请求 Key 范围的授权凭证。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ModelExecuteRequest {
+    /// 管理、命令、维护、认证与观察调用显式选择 Key；数据请求内的子调用继承父请求身份。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub client_key_id: Option<String>,
+    pub model: String,
+    pub protocol: String,
+    pub operation: ModelOperation,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub provider: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub account_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub previous_response_id: Option<String>,
+}
+
+/// 按本次选择的 Key 查询可见模型，不读取或返回 Key 明文。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ModelListRequest {
+    pub client_key_id: String,
+    pub protocol: String,
+    pub client_version: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ModelListResult {
+    pub models: Vec<String>,
+}
+
+/// 分页读取 Key 的非秘密信息，用于管理页和命令行选择执行身份。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct KeyListRequest {
+    pub cursor: Option<String>,
+    pub limit: u16,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ClientKey {
+    pub id: String,
+    pub name: String,
+    pub enabled: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct KeyListResult {
+    pub keys: Vec<ClientKey>,
+    pub next_cursor: Option<String>,
+}
+
+/// 非流式子请求已经完成并由 Core 提交；事件位于二进制载荷中的一个 HME1 批次。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ModelExecuteResult {
+    pub request_id: String,
+    pub events: u32,
+}
+
+/// 流式子请求句柄只能在创建它的父调用上下文中使用。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ModelStreamResult {
+    pub request_id: String,
+    pub stream: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ModelStreamReadRequest {
+    pub stream: String,
+    pub maximum_bytes: u32,
+}
+
+/// `end=true` 表示 Core 已完成终态与结算，载荷可以为空。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ModelStreamReadResult {
+    pub events: u32,
+    pub end: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ModelStreamCloseRequest {
+    pub stream: String,
+}
+
+/// 查询 Provider 已经保存的不可逆亲和键；宿主不会从任意会话文本推导假命中。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AffinityLookupRequest {
+    pub provider: String,
+    pub key: String,
+}
+
+/// 命中只返回账号偏好；后续模型调用仍由 Core 复核账号资格并取得租约。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AffinityLookupResult {
+    pub account_id: Option<String>,
+}
+
+/// 模型执行回调的有界事件批次。单个事件沿用 Provider 事件的 GPE1 封套，批次只增加
+/// 长度索引，不把原生正文改写成 JSON/base64。
+#[derive(Clone, Default)]
+pub struct ModelEventBatch {
+    pub events: Vec<ExecutionEvent>,
+}
+
+impl ModelEventBatch {
+    /// # Errors
+    ///
+    /// 事件编码无效、数量/长度溢出或总批次超过 8 MiB 时返回错误。
+    pub fn encode(self) -> Result<Vec<u8>, ModelEventBatchError> {
+        let count = u32::try_from(self.events.len()).map_err(|_| ModelEventBatchError)?;
+        let mut encoded = Vec::with_capacity(self.events.len());
+        let mut total = 8_usize
+            .checked_add(
+                self.events
+                    .len()
+                    .checked_mul(4)
+                    .ok_or(ModelEventBatchError)?,
+            )
+            .ok_or(ModelEventBatchError)?;
+        for event in self.events {
+            let event = event.encode().map_err(|_| ModelEventBatchError)?;
+            let _ = u32::try_from(event.len()).map_err(|_| ModelEventBatchError)?;
+            total = total.checked_add(event.len()).ok_or(ModelEventBatchError)?;
+            if total > MAX_MODEL_EVENT_BATCH_BYTES {
+                return Err(ModelEventBatchError);
+            }
+            encoded.push(event);
+        }
+        let mut bytes = Vec::with_capacity(total);
+        bytes.extend_from_slice(&MODEL_EVENT_BATCH_PREFIX);
+        bytes.extend_from_slice(&count.to_be_bytes());
+        for event in &encoded {
+            bytes.extend_from_slice(
+                &u32::try_from(event.len())
+                    .map_err(|_| ModelEventBatchError)?
+                    .to_be_bytes(),
+            );
+        }
+        for event in encoded {
+            bytes.extend_from_slice(&event);
+        }
+        Ok(bytes)
+    }
+
+    /// # Errors
+    ///
+    /// 版本、长度索引、事件封套或总批次无效时返回错误。
+    pub fn decode(bytes: &[u8]) -> Result<Self, ModelEventBatchError> {
+        if bytes.len() < 8
+            || bytes.len() > MAX_MODEL_EVENT_BATCH_BYTES
+            || bytes[..4] != MODEL_EVENT_BATCH_PREFIX
+        {
+            return Err(ModelEventBatchError);
+        }
+        let count = usize::try_from(u32::from_be_bytes(
+            bytes[4..8].try_into().map_err(|_| ModelEventBatchError)?,
+        ))
+        .map_err(|_| ModelEventBatchError)?;
+        let payload_start = 8_usize
+            .checked_add(count.checked_mul(4).ok_or(ModelEventBatchError)?)
+            .ok_or(ModelEventBatchError)?;
+        if payload_start > bytes.len() {
+            return Err(ModelEventBatchError);
+        }
+        let mut cursor = payload_start;
+        let mut events = Vec::with_capacity(count);
+        for chunk in bytes[8..payload_start].chunks_exact(4) {
+            let length = usize::try_from(u32::from_be_bytes(
+                chunk.try_into().map_err(|_| ModelEventBatchError)?,
+            ))
+            .map_err(|_| ModelEventBatchError)?;
+            let end = cursor.checked_add(length).ok_or(ModelEventBatchError)?;
+            let event = bytes.get(cursor..end).ok_or(ModelEventBatchError)?;
+            events.push(ExecutionEvent::decode(event).map_err(|_| ModelEventBatchError)?);
+            cursor = end;
+        }
+        if cursor != bytes.len() || events.len() != count {
+            return Err(ModelEventBatchError);
+        }
+        Ok(Self { events })
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+#[error("host model event batch is invalid or exceeds its limit")]
+pub struct ModelEventBatchError;
+
+/// 私有状态读取；值只通过宿主绑定的实例与命名空间解析。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateGetRequest {
+    pub namespace: String,
+    pub key: String,
+}
+
+/// 状态值可能包含敏感插件数据，故意不实现 `Debug`。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateRecord {
+    pub value: serde_json::Value,
+    pub version: u64,
+    pub schema_version: u32,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateGetResult {
+    pub record: Option<StateRecord>,
+}
+
+/// `expected_version = None` 表示仅当键不存在时创建；更新必须提交精确版本。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StatePutRequest {
+    pub namespace: String,
+    pub key: String,
+    pub value: serde_json::Value,
+    pub expected_version: Option<u64>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StatePutResult {
+    pub version: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateDeleteRequest {
+    pub namespace: String,
+    pub key: String,
+    pub expected_version: u64,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateDeleteResult {
+    pub deleted: bool,
+}
+
+/// 宿主控制的迁移批次；插件不能选择源记录、目标实例或提交边界。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateMigrationRequest {
+    pub namespace: String,
+    pub from_schema_version: u32,
+    pub to_schema_version: u32,
+    pub records: Vec<StateMigrationRecord>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateMigrationRecord {
+    pub key: String,
+    pub value: serde_json::Value,
+    pub version: u64,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateMigrationResult {
+    pub changes: Vec<StateMigrationChange>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(tag = "action", rename_all = "snake_case", deny_unknown_fields)]
+pub enum StateMigrationChange {
+    Keep {
+        key: String,
+    },
+    Replace {
+        key: String,
+        value: serde_json::Value,
+    },
+    Delete {
+        key: String,
+    },
+}
+
+impl StateMigrationChange {
+    #[must_use]
+    pub fn key(&self) -> &str {
+        match self {
+            Self::Keep { key } | Self::Replace { key, .. } | Self::Delete { key } => key,
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/management.rs b/backend/crates/gateway-plugin/sdk/src/call/management.rs
new file mode 100644
index 000000000..2b82184bf
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/management.rs
@@ -0,0 +1,157 @@
+//! 管理与 CLI 的跨进程数据；参数和命令结果只通过有界二进制载荷传输。
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+use super::host::AuthSaveRequest;
+
+/// `management.register` 冻结的路由与页面；路径均相对插件实例命名空间。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ManagementRegistration {
+    #[serde(default)]
+    pub routes: Vec<ManagementRoute>,
+    #[serde(default)]
+    pub resources: Vec<ManagementResource>,
+    #[serde(default)]
+    pub pages: Vec<ManagementPage>,
+    #[serde(default)]
+    pub callbacks: Vec<ManagementCallback>,
+}
+
+/// 仅接受宿主签发的一次性 state；回调不能访问账号、网络或私有状态宿主端口。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ManagementCallback {
+    pub path: String,
+    pub response_content_types: Vec<String>,
+}
+
+/// 管理 handler 默认且始终要求管理员身份；浏览器 Cookie、Authorization 不会传入插件。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ManagementRoute {
+    pub method: String,
+    pub path: String,
+    #[serde(default)]
+    pub request_content_types: Vec<String>,
+    pub response_content_types: Vec<String>,
+}
+
+/// 资源必须已在包清单 resources 中声明并校验摘要，公开资源还须单独获得授权。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ManagementResource {
+    pub path: String,
+    #[serde(default)]
+    pub public: bool,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ManagementPage {
+    pub id: String,
+    pub title: String,
+    /// 页面目录直接提供副标题，避免加载静态资源后再替换宿主标题区。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    pub entry: String,
+    pub icon: Option<String>,
+}
+
+/// `management.handle` 元数据；原始请求体独立放在帧 payload，不进行 JSON 二次编码。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ManagementRequest {
+    pub method: String,
+    pub path: String,
+    pub query: String,
+    pub content_type: Option<String>,
+}
+
+/// 原始响应体独立放在帧 payload；宿主拥有 CSP、安全头及大小限制。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ManagementResponse {
+    pub status: u16,
+    pub content_type: String,
+}
+
+/// `command_line.register` 的只读结果；注册和帮助查询不能执行命令或登录。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CommandRegistration {
+    pub commands: Vec<CommandDescriptor>,
+}
+
+/// 命令名只在插件实例的命名空间内生效，不注册宿主全局启动参数。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CommandDescriptor {
+    pub name: String,
+    pub description: String,
+    #[serde(default)]
+    pub parameters: Vec<CommandParameter>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CommandParameter {
+    pub name: String,
+    pub description: String,
+    pub value_type: CommandParameterType,
+    #[serde(default)]
+    pub required: bool,
+    #[serde(default)]
+    pub sensitive: bool,
+    pub default: Option<CommandValue>,
+}
+
+/// `int` 固定为 32 位，duration 固定为有符号纳秒，避免随部署平台改变合同。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CommandParameterType {
+    Bool,
+    String,
+    Int,
+    Int64,
+    Float64,
+    Duration,
+}
+
+/// 参数可能含登录材料，故意不实现内容型 Debug。
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+#[serde(
+    tag = "type",
+    content = "value",
+    rename_all = "snake_case",
+    deny_unknown_fields
+)]
+pub enum CommandValue {
+    Bool(bool),
+    String(String),
+    Int(i32),
+    Int64(i64),
+    Float64(f64),
+    Duration(i64),
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CommandInvocation {
+    pub name: String,
+    pub arguments: BTreeMap<String, CommandValue>,
+}
+
+/// 输出由宿主原样交付 CLI 调用方，不进入普通诊断。
+/// 待保存账号仅在退出码为零时按顺序经 Admin 提交；每项独立 CAS，失败不自动重试。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CommandResult {
+    pub stdout: String,
+    pub stderr: String,
+    pub exit_code: u8,
+    #[serde(default)]
+    pub accounts: Vec<AuthSaveRequest>,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/middleware.rs b/backend/crates/gateway-plugin/sdk/src/call/middleware.rs
new file mode 100644
index 000000000..d65e15346
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/middleware.rs
@@ -0,0 +1,322 @@
+//! 统一请求/响应中间件的跨进程数据合同。
+
+use serde::{Deserialize, Serialize};
+
+pub const HANDLE_METHOD: &str = "middleware.handle";
+pub const NEXT_METHOD: &str = "host.middleware.next";
+pub const BODY_READ_METHOD: &str = "host.middleware.body_read";
+pub const BODY_CLOSE_METHOD: &str = "host.middleware.body_close";
+
+const BODY_FRAME_PREFIX: [u8; 4] = *b"GMB1";
+
+/// 中间件在逻辑请求外层或单次 Provider attempt 内层执行。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MiddlewareMount {
+    Request,
+    Attempt,
+}
+
+/// 客户端交付形态；它不授予插件访问底层 HTTP 或 WebSocket 连接。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MiddlewareTransport {
+    HttpJson,
+    HttpSse,
+    WebSocket,
+    Internal,
+}
+
+/// 正文读取边界。结构化正文只按完整文档或完整 SSE 事件交付。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MiddlewareBodyFraming {
+    JsonDocument,
+    SseEvent,
+    RawBytes,
+}
+
+/// 一个保留顺序与重复项的 HTTP header。
+///
+/// Header 值可能包含不适合日志的客户端数据，因此故意不实现 `Debug`。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MiddlewareHeader {
+    pub name: String,
+    pub value: Vec<u8>,
+}
+
+/// 对宿主保存的原始 header 集合做增量修改；未列出的项保持原样。
+///
+/// Header 值可能包含不适合日志的客户端数据，因此故意不实现 `Debug`。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "operation", rename_all = "snake_case", deny_unknown_fields)]
+pub enum MiddlewareHeaderMutation {
+    Remove { name: String },
+    Append { name: String, value: Vec<u8> },
+}
+
+/// `middleware.handle` 的请求头。正文位于 RPC binary payload；未授权读取时为空。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MiddlewareRequestHead {
+    pub request_id: String,
+    pub mount: MiddlewareMount,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub attempt_index: Option<u32>,
+    pub operation: String,
+    pub protocol: String,
+    pub endpoint: String,
+    pub transport: MiddlewareTransport,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub provider: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub account_id: Option<String>,
+    #[serde(default)]
+    pub headers: Vec<MiddlewareHeader>,
+    /// `true` 表示 binary payload 是完整请求正文；`false` 表示正文未向插件投影。
+    pub body_visible: bool,
+}
+
+/// 调用 next 时如何处理宿主保存的原始请求正文。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MiddlewareRequestBody {
+    Preserve,
+    Replace,
+}
+
+/// 单次 `host.middleware.next` 调用。`Replace` 的完整正文位于 binary payload。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MiddlewareNextRequest {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub protocol: Option<String>,
+    #[serde(default)]
+    pub header_mutations: Vec<MiddlewareHeaderMutation>,
+    pub body: MiddlewareRequestBody,
+}
+
+/// 受父调用约束的不透明响应正文句柄。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MiddlewareBodyHandle {
+    pub handle: String,
+    pub framing: MiddlewareBodyFraming,
+}
+
+/// `host.middleware.next` 返回的响应头。正文必须通过句柄惰性读取或原样返还。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MiddlewareNextResponse {
+    /// 绑定本次 next 结果的宿主响应身份；只能在当前父调用内返还。
+    pub response: String,
+    pub protocol: String,
+    pub status: u16,
+    #[serde(default)]
+    pub headers: Vec<MiddlewareHeader>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub body: Option<MiddlewareBodyHandle>,
+}
+
+/// 最终正文来源。`PassThrough` 不读取正文，也不要求响应正文读写授权。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum MiddlewareResponseBody {
+    Empty,
+    PassThrough { body: MiddlewareBodyHandle },
+    Stream { framing: MiddlewareBodyFraming },
+}
+
+/// `middleware.handle` 的最终响应头；插件输出流仍使用既有 RPC Stream/Credit/End。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MiddlewareResponseHead {
+    /// `Some` 表示基于本层 next 返回的原响应；`None` 表示中间件短路响应。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub response: Option<String>,
+    /// 缺省时保留原响应协议；短路响应必须填写。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub protocol: Option<String>,
+    /// 缺省时保留原状态；短路响应必须填写。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub status: Option<u16>,
+    #[serde(default)]
+    pub header_mutations: Vec<MiddlewareHeaderMutation>,
+    pub body: MiddlewareResponseBody,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MiddlewareBodyRead {
+    pub handle: String,
+    pub maximum_bytes: u32,
+}
+
+/// `eof` 只在空 payload 时成立；结构化 frame 不拆成任意网络分块。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MiddlewareBodyReadResult {
+    pub framing: MiddlewareBodyFraming,
+    /// Runtime 为每个输入 frame 分配的非零单调标识；EOF 时必须为零。
+    pub source_id: u64,
+    pub eof: bool,
+    pub terminal: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MiddlewareBodyClose {
+    pub handle: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MiddlewareBodyCloseResult {}
+
+/// 一个输出 frame 与其来源的 wire disposition。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+pub enum MiddlewareBodyDisposition {
+    Standalone = 0,
+    Only = 1,
+    First = 2,
+    More = 3,
+    Last = 4,
+    Drop = 5,
+}
+
+/// 插件替换正文流中的一个完整 frame；正文不进入 JSON metadata。
+#[derive(Clone, PartialEq, Eq)]
+pub struct MiddlewareBodyFrame {
+    pub payload: Vec<u8>,
+    pub terminal: bool,
+    source_id: u64,
+    disposition: MiddlewareBodyDisposition,
+}
+
+impl MiddlewareBodyFrame {
+    #[must_use]
+    pub fn new(payload: Vec<u8>, terminal: bool) -> Self {
+        Self {
+            payload,
+            terminal,
+            source_id: 0,
+            disposition: MiddlewareBodyDisposition::Standalone,
+        }
+    }
+
+    #[cfg(feature = "io")]
+    pub(crate) fn from_source(
+        payload: Vec<u8>,
+        terminal: bool,
+        source_id: u64,
+    ) -> Result<Self, MiddlewareBodyFrameError> {
+        if source_id == 0 {
+            return Err(MiddlewareBodyFrameError);
+        }
+        Ok(Self {
+            payload,
+            terminal,
+            source_id,
+            disposition: MiddlewareBodyDisposition::Only,
+        })
+    }
+
+    #[cfg(feature = "io")]
+    pub(crate) fn map_to_source(
+        mut self,
+        source_id: u64,
+        disposition: MiddlewareBodyDisposition,
+    ) -> Result<Self, MiddlewareBodyFrameError> {
+        if source_id == 0
+            || matches!(disposition, MiddlewareBodyDisposition::Standalone)
+            || (matches!(disposition, MiddlewareBodyDisposition::Drop) && !self.payload.is_empty())
+        {
+            return Err(MiddlewareBodyFrameError);
+        }
+        self.source_id = source_id;
+        self.disposition = disposition;
+        // Mapped frame 的终态只由 Runtime 保存的源 frame 派生。
+        self.terminal = false;
+        Ok(self)
+    }
+
+    #[must_use]
+    pub const fn source_id(&self) -> u64 {
+        self.source_id
+    }
+
+    #[must_use]
+    pub const fn disposition(&self) -> MiddlewareBodyDisposition {
+        self.disposition
+    }
+
+    /// 将 frame 元数据与原始正文编码到一个 RPC stream chunk。
+    #[must_use]
+    pub fn encode(self) -> Vec<u8> {
+        let mut encoded = Vec::with_capacity(14 + self.payload.len());
+        encoded.extend_from_slice(&BODY_FRAME_PREFIX);
+        encoded.push(self.disposition as u8);
+        encoded.extend_from_slice(&self.source_id.to_be_bytes());
+        encoded.push(u8::from(self.terminal));
+        encoded.extend_from_slice(&self.payload);
+        encoded
+    }
+
+    /// 解码一个完整的中间件正文 frame。
+    ///
+    /// # Errors
+    ///
+    /// 魔数或 flags 无效时返回错误。
+    pub fn decode(bytes: &[u8]) -> Result<Self, MiddlewareBodyFrameError> {
+        if bytes.len() < 14 || bytes[..4] != BODY_FRAME_PREFIX || bytes[13] > 1 {
+            return Err(MiddlewareBodyFrameError);
+        }
+        let disposition = match bytes[4] {
+            0 => MiddlewareBodyDisposition::Standalone,
+            1 => MiddlewareBodyDisposition::Only,
+            2 => MiddlewareBodyDisposition::First,
+            3 => MiddlewareBodyDisposition::More,
+            4 => MiddlewareBodyDisposition::Last,
+            5 => MiddlewareBodyDisposition::Drop,
+            _ => return Err(MiddlewareBodyFrameError),
+        };
+        let source_id = u64::from_be_bytes(
+            bytes[5..13]
+                .try_into()
+                .map_err(|_| MiddlewareBodyFrameError)?,
+        );
+        let terminal = bytes[13] == 1;
+        if (source_id == 0) != matches!(disposition, MiddlewareBodyDisposition::Standalone)
+            || (source_id != 0 && terminal)
+            || (matches!(disposition, MiddlewareBodyDisposition::Drop) && bytes.len() != 14)
+        {
+            return Err(MiddlewareBodyFrameError);
+        }
+        Ok(Self {
+            payload: bytes[14..].to_vec(),
+            terminal,
+            source_id,
+            disposition,
+        })
+    }
+}
+
+impl std::fmt::Debug for MiddlewareBodyFrame {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("MiddlewareBodyFrame")
+            .field("payload_bytes", &self.payload.len())
+            .field("terminal", &self.terminal)
+            .field("source_id", &self.source_id)
+            .field("disposition", &self.disposition)
+            .finish()
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+#[error("middleware body frame is invalid")]
+pub struct MiddlewareBodyFrameError;
diff --git a/backend/crates/gateway-plugin/sdk/src/call/mod.rs b/backend/crates/gateway-plugin/sdk/src/call/mod.rs
new file mode 100644
index 000000000..6e4f0d402
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/mod.rs
@@ -0,0 +1,10 @@
+//! 按业务职责组织的跨进程调用数据，不依赖网关领域类型。
+
+pub mod auth;
+pub mod frontend_authentication;
+pub mod host;
+pub mod management;
+pub mod middleware;
+pub mod observation;
+pub mod policy;
+pub mod provider;
diff --git a/backend/crates/gateway-plugin/sdk/src/call/observation.rs b/backend/crates/gateway-plugin/sdk/src/call/observation.rs
new file mode 100644
index 000000000..87945cecf
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/observation.rs
@@ -0,0 +1,30 @@
+//! 只读响应观察调用的数据合同。
+
+use serde::{Deserialize, Serialize};
+
+/// 实际上游 WebSocket 响应事件。
+///
+/// 原始 JSON 在 RPC 二进制载荷中独立传递。载荷未纳入本次有界观察时
+/// `payload_included=false`、载荷为空，且不会通过事件名或头字段旁路泄漏正文。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ObserveWebSocketResponse {
+    pub event_id: String,
+    pub request_id: String,
+    pub config_revision: u64,
+    pub operation: String,
+    pub protocol: String,
+    pub provider: String,
+    pub attempt_index: u32,
+    /// 请求内从 1 开始单调递增，切换 attempt 时不重置；有界投递可能产生间隔。
+    pub sequence: u64,
+    pub payload_included: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub requested_model: Option<String>,
+    /// 实际 attempt 选择的账号；属于 requests 域的请求处理事实，不包含账号资料或凭据。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub account_id: Option<String>,
+    /// 事件名属于原始响应内容，只在 `payload_included=true` 时提供。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub event_type: Option<String>,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/policy/mod.rs b/backend/crates/gateway-plugin/sdk/src/call/policy/mod.rs
new file mode 100644
index 000000000..808bc7066
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/policy/mod.rs
@@ -0,0 +1,242 @@
+//! 路由、调度与最终观测调用的跨进程数据合同。
+
+use serde::{Deserialize, Serialize};
+
+use crate::SendState;
+
+/// 策略插件可见的安全 HTTP 头；值使用 base64 保留非 UTF-8 字节。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PolicyHeader {
+    pub name: String,
+    pub value_base64: String,
+}
+
+/// 模型路由调用。原始正文在 RPC 二进制载荷中独立传递；无正文读取授权时载荷为空。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ModelRouteRequest {
+    pub request_id: String,
+    pub operation: String,
+    pub protocol: String,
+    pub model: String,
+    #[serde(default)]
+    pub available_providers: Vec<String>,
+    #[serde(default)]
+    pub headers: Vec<PolicyHeader>,
+}
+
+/// 模型路由决定；宿主仍会复核目标、Key 权限和模型能力。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "decision", rename_all = "snake_case", deny_unknown_fields)]
+pub enum ModelRouteDecision {
+    Unhandled,
+    Route {
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        provider: Option<String>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        model: Option<String>,
+    },
+    Reject,
+}
+
+/// 账号调度器可见的安全候选事实，不包含 credential 或账号资料。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AccountScheduleCandidate {
+    pub account_id: String,
+    pub weight: u16,
+    pub in_flight: u32,
+    pub maximum_concurrency: u32,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_started_at_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub quota_reset_at_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub quota_remaining_rank: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub failure_rate_basis_points: Option<u16>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub first_output_latency_ms: Option<u64>,
+}
+
+/// 账号调度调用。Key 与账号组仅供宿主匹配绑定，不发送给插件。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AccountScheduleRequest {
+    pub request_id: String,
+    pub attempt_index: u32,
+    pub provider: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    pub candidates: Vec<AccountScheduleCandidate>,
+}
+
+/// 账号调度结果；账号租约始终由宿主在决定返回后取得。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "decision", rename_all = "snake_case", deny_unknown_fields)]
+pub enum AccountScheduleDecision {
+    Pick { account_id: String },
+    Delegate,
+    Reject,
+}
+
+/// 请求终态分类；`rejected` 表示请求在进入 Provider 执行前被宿主拒绝。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RequestOutcome {
+    Succeeded,
+    Failed,
+    Rejected,
+    Cancelled,
+    Incomplete,
+}
+
+/// Core 对单次请求最终费用的可信程度。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RequestCostStatus {
+    Known,
+    Unknown,
+}
+
+/// 最终费用事实的来源；Usage 插件只消费结果，不重新计价。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RequestCostSource {
+    ProviderReported,
+    Calculated,
+    Unavailable,
+}
+
+/// 精确十进制金额；字符串保留宿主的定点精度。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestMoney {
+    pub amount: String,
+    pub currency: String,
+}
+
+/// 用量观察取得的最终费用；未知费用没有 `total`，不得解释为零。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestCost {
+    pub status: RequestCostStatus,
+    pub source: RequestCostSource,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub total: Option<RequestMoney>,
+}
+
+/// 用量观察取得的毫秒级阶段耗时；缺失字段表示宿主没有该项事实。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestTimings {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub transport_decision_wait_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub connect_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub headers_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub first_event_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub first_reasoning_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub first_text_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub first_token_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub provider_processing_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub latency_ms: Option<u64>,
+}
+
+/// 非成功请求的安全摘要，不包含错误消息、原始正文或诊断载荷。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestFailure {
+    pub outcome: RequestOutcome,
+    pub send_state: SendState,
+    pub attempt_count: u32,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub client_status_code: Option<u16>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub upstream_status_code: Option<u16>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub error_code: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub retry_after_ms: Option<u64>,
+}
+
+/// 请求生命周期观察取得的最终宿主事实。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestTerminal {
+    pub outcome: RequestOutcome,
+    pub send_state: SendState,
+    pub attempt_count: u32,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub client_status_code: Option<u16>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub error_code: Option<String>,
+}
+
+/// 用量观察取得的最终标准化用量；缺失字段表示宿主没有该项事实。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestUsage {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_tokens: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_tokens: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cached_tokens: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_write_tokens: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reasoning_tokens: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub image_input_tokens: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub image_output_tokens: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub total_tokens: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cost: Option<RequestCost>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timings: Option<RequestTimings>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub failure: Option<RequestFailure>,
+}
+
+/// 同一实例的请求生命周期与用量订阅合并为一个最终观测调用。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ObserveRequest {
+    /// 不重投时仍保持稳定，供插件自行去重和关联日志。
+    pub event_id: String,
+    pub request_id: String,
+    pub config_revision: u64,
+    pub operation: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub client_key_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub account_id: Option<String>,
+    /// 本次实际选中账号使用的上游模型，未进入上游时可能不存在。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub upstream_model: Option<String>,
+    /// 上游响应报告的模型，与请求中的模型名称分开保存。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub response_model: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub service_tier: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub requested_model: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub provider: Option<String>,
+    pub completed_at_ms: u64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub terminal: Option<RequestTerminal>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub usage: Option<RequestUsage>,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/account.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/account.rs
new file mode 100644
index 000000000..f553a744e
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/account.rs
@@ -0,0 +1,147 @@
+//! 按需账号管理能力；资料操作不携带账号写入或额度更新指令。
+//!
+//! 注册时在 `ProviderDescriptor.account_operations` 声明可选操作，同时在清单中声明
+//! `account_management` 能力。资料调用使用 Management 阶段和 profile 用途的凭据/HTTP 授权，
+//! 重置卡查询及消费的用途与副作用合同见 [`super::reset_credits`]。
+//! `provider.profile`、`provider.subscription`、`provider.avatar` 的请求都是 [`AccountRequest`]，
+//! 编码为 JSON 二进制载荷，控制参数为空对象。前两个方法的控制结果为空对象，二进制结果
+//! 分别为 [`Profile`] 与可空 [`Subscription`]；avatar 的控制结果为 [`Avatar`]，初始载荷为空，
+//! 后续通过受信用窗口约束的流帧传递字节，声明了长度时必须与正常结束时的实际字节数一致。
+//!
+//! 文本字段最多 1024 字节且不含控制字符，日统计与调用排行各最多 4096 项，百分比在 0–100 内。
+//! 时间戳以 Unix 毫秒表示，订阅开始时间不得晚于结束时间。结果不更新宿主账号或额度缓存；
+//! 凭据版本或上游身份在查询期间发生变化时，宿主拒绝交付旧结果。
+//! 返回头像标识须声明 avatar 操作；URL 必须有 HTTP(S) 主机且不含 userinfo。
+//! 头像元数据的文本仅允许可打印 ASCII，图像正文不另设累计大小上限。
+
+use serde::{Deserialize, Serialize};
+
+/// 账号连接设置的显式公开字段。
+///
+/// 字段必须同时存在于凭据轮换 schema，并且其完整 schema 子树不得包含 secret 标记或
+/// 间接组合。宿主只接受这些字段的有界投影；未声明时不会调用连接设置 RPC。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AccountConfigurationDescriptor {
+    pub public_fields: Vec<String>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AccountOperation {
+    /// 已提交停用、冻结或删除后的资源失效通知，不读取凭据。
+    Unavailable,
+    /// 已提交账号事实变更后的派生缓存失效通知，不读取凭据。
+    FactsChanged,
+    Profile,
+    Subscription,
+    Avatar,
+    ResetCredits,
+    ConsumeResetCredit,
+}
+
+/// `provider.account_changed` 的 JSON 二进制输入，控制参数和成功结果均为空对象。
+///
+/// 声明任一通知操作时，account_management 必须包含 observation 阶段。通知只包含
+/// 本实例获准访问的账号 ID，最多 256 个，不能恢复资格或写回账号。事务已经提交；
+/// 宿主在两秒总预算内按顺序发送有界批次，不自动重试，也不因通知失败回滚事务。
+/// 插件只释放连接或使派生缓存失效；需要重新查询事实时使用后续独立、已授权调用。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum AccountInvalidation {
+    Unavailable { account_id: String },
+    FactsChanged { account_ids: Vec<String> },
+}
+
+// 凭据只能放在 RPC 二进制载荷内，不参与 Debug 或控制帧诊断。
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AccountRequest {
+    pub account_id: String,
+    pub credential_revision: u64,
+    pub credential: serde_json::Map<String, serde_json::Value>,
+}
+
+/// `provider.account_configuration` 的只读结果。
+///
+/// 结果只包含描述符显式声明的非敏感连接字段。类型故意不实现 `Debug`，即使插件违反
+/// 合同返回敏感值，宿主也不会在校验失败时把正文写入诊断。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AccountConfiguration {
+    pub values: serde_json::Map<String, serde_json::Value>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Subscription {
+    pub starts_at_ms: Option<i64>,
+    pub expires_at_ms: i64,
+    pub will_renew: Option<bool>,
+    pub billing_period: Option<String>,
+    pub billing_currency: Option<String>,
+    pub observed_at_ms: i64,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Profile {
+    pub display_name: Option<String>,
+    pub username: Option<String>,
+    /// 可公开的 HTTP(S) 头像标识，不得包含认证材料；宿主不请求此 URL，图像走 avatar 流。
+    pub image_url: Option<String>,
+    pub has_stats_error: bool,
+    pub summary: ProfileSummary,
+    pub daily_usage: Option<Vec<ProfileDailyUsage>>,
+    pub activity_insights: ProfileActivityInsights,
+}
+
+#[derive(Clone, Default, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ProfileSummary {
+    pub total_text_tokens: Option<u64>,
+    pub peak_tokens: Option<u64>,
+    pub longest_task_duration_ms: Option<u64>,
+    pub current_streak_days: Option<u64>,
+    pub longest_streak_days: Option<u64>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ProfileDailyUsage {
+    /// 严格的 YYYY-MM-DD 日历日期，同一天只能出现一次。
+    pub date: String,
+    pub tokens: u64,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ProfileInvocation {
+    pub invocation_type: String,
+    pub plugin_id: Option<String>,
+    pub plugin_name: Option<String>,
+    pub skill_id: Option<String>,
+    pub skill_name: Option<String>,
+    pub usage_count: Option<u64>,
+}
+
+#[derive(Clone, Default, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ProfileActivityInsights {
+    pub fast_mode_percent: Option<f64>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_effort_percent: Option<f64>,
+    pub skills_explored: Option<u64>,
+    pub total_skills_used: Option<u64>,
+    pub total_threads: Option<u64>,
+    pub invocations: Option<Vec<ProfileInvocation>>,
+}
+
+/// avatar 调用的初始结果，后续 Stream 帧直接传递原始图像字节。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Avatar {
+    pub content_type: Option<String>,
+    pub content_length: Option<u64>,
+    pub etag: Option<String>,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/billing.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/billing.rs
new file mode 100644
index 000000000..a45fe3da1
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/billing.rs
@@ -0,0 +1,37 @@
+//! 声明式 Token 计价；宿主冻结价目并保存计算明细，插件不写账本。
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+/// `token_v1` 只适用于费用完全由 Token 构成的响应；工具费等额外费用应上报实际总额。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "rule", rename_all = "snake_case", deny_unknown_fields)]
+pub enum BillingDescriptor {
+    TokenV1 {
+        /// 精确上游模型 ID 到各档单价；不得用公开别名或响应模型覆盖实际发送模型。
+        prices: BTreeMap<String, BTreeMap<PriceBand, TokenPrices>>,
+    },
+}
+
+/// 完整单价，单位为 USD / 百万 Token；宿主校验非负、上限及最多四位小数。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct TokenPrices {
+    pub input: String,
+    pub output: String,
+    pub cache_read: String,
+    pub cache_write: String,
+}
+
+/// Provider 确认的实际计费档位，不能由响应文本或宿主当前配置推测。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PriceBand {
+    Standard,
+    Fast,
+    Flex,
+    LongStandard,
+    LongFast,
+    LongFlex,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/codec.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/codec.rs
new file mode 100644
index 000000000..d568996a8
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/codec.rs
@@ -0,0 +1,127 @@
+use serde::{Serialize, de::DeserializeOwned};
+
+use super::{ExecutionEvent, ExecutionInput, WirePayload};
+
+/// 宿主与插件还会施加更低的帧、队列及可用信用上限。
+pub const MAX_EXECUTION_PAYLOAD_BYTES: usize = 8 * 1024 * 1024;
+
+#[derive(Debug, thiserror::Error)]
+#[error("plugin execution payload has invalid encoding or exceeds its limit")]
+pub struct ExecutionEncodingError;
+
+pub(super) fn encode_event(mut event: ExecutionEvent) -> Result<Vec<u8>, ExecutionEncodingError> {
+    let wire = raw_wire(&mut event).map(std::mem::take).unwrap_or_default();
+    let failure = raw_failure(&mut event)
+        .map(std::mem::take)
+        .unwrap_or_default();
+    pack(*b"GPE1", &event, [wire, failure])
+}
+
+pub(super) fn decode_event(bytes: &[u8]) -> Result<ExecutionEvent, ExecutionEncodingError> {
+    let (mut event, [wire, failure]) = unpack(*b"GPE1", bytes)?;
+    attach(raw_wire(&mut event), wire)?;
+    attach(raw_failure(&mut event), failure)?;
+    Ok(event)
+}
+
+pub(super) fn encode_input(input: ExecutionInput) -> Result<Vec<u8>, ExecutionEncodingError> {
+    pack(*b"GPQ1", &input.request, [input.body])
+}
+
+pub(super) fn decode_input(bytes: &[u8]) -> Result<ExecutionInput, ExecutionEncodingError> {
+    let (request, [body]) = unpack(*b"GPQ1", bytes)?;
+    Ok(ExecutionInput {
+        request,
+        body: body.to_vec(),
+    })
+}
+
+fn pack<T: Serialize, const N: usize>(
+    prefix: [u8; 4],
+    metadata: &T,
+    payloads: [Vec<u8>; N],
+) -> Result<Vec<u8>, ExecutionEncodingError> {
+    let header_bytes = 4 + 4 * (N + 1);
+    let raw_bytes = payloads
+        .iter()
+        .fold(0usize, |total, bytes| total.saturating_add(bytes.len()));
+    if raw_bytes > MAX_EXECUTION_PAYLOAD_BYTES {
+        return Err(ExecutionEncodingError);
+    }
+    let metadata = serde_json::to_vec(metadata).map_err(|_| ExecutionEncodingError)?;
+    let total = header_bytes
+        .saturating_add(metadata.len())
+        .saturating_add(raw_bytes);
+    if total > MAX_EXECUTION_PAYLOAD_BYTES {
+        return Err(ExecutionEncodingError);
+    }
+    let mut result = Vec::with_capacity(total);
+    result.extend_from_slice(&prefix);
+    for length in std::iter::once(metadata.len()).chain(payloads.iter().map(Vec::len)) {
+        result.extend_from_slice(
+            &u32::try_from(length)
+                .map_err(|_| ExecutionEncodingError)?
+                .to_be_bytes(),
+        );
+    }
+    result.extend_from_slice(&metadata);
+    for bytes in payloads {
+        result.extend_from_slice(&bytes);
+    }
+    Ok(result)
+}
+
+fn unpack<T: DeserializeOwned, const N: usize>(
+    prefix: [u8; 4],
+    bytes: &[u8],
+) -> Result<(T, [&[u8]; N]), ExecutionEncodingError> {
+    let header_bytes = 4 + 4 * (N + 1);
+    if bytes.len() < header_bytes
+        || bytes.len() > MAX_EXECUTION_PAYLOAD_BYTES
+        || bytes[..4] != prefix
+    {
+        return Err(ExecutionEncodingError);
+    }
+    let mut cursor = header_bytes;
+    let mut metadata = &[][..];
+    let mut payloads = [&[][..]; N];
+    // 先验证全部分段边界，不能根据对端的长度声明直接分配。
+    for (chunk, target) in bytes[4..header_bytes]
+        .chunks_exact(4)
+        .zip(std::iter::once(&mut metadata).chain(payloads.iter_mut()))
+    {
+        let length = usize::try_from(u32::from_be_bytes(
+            chunk.try_into().map_err(|_| ExecutionEncodingError)?,
+        ))
+        .map_err(|_| ExecutionEncodingError)?;
+        let end = cursor.checked_add(length).ok_or(ExecutionEncodingError)?;
+        *target = bytes.get(cursor..end).ok_or(ExecutionEncodingError)?;
+        cursor = end;
+    }
+    if cursor != bytes.len() {
+        return Err(ExecutionEncodingError);
+    }
+    let metadata = serde_json::from_slice(metadata).map_err(|_| ExecutionEncodingError)?;
+    Ok((metadata, payloads))
+}
+
+fn attach(target: Option<&mut Vec<u8>>, bytes: &[u8]) -> Result<(), ExecutionEncodingError> {
+    match target {
+        Some(target) if target.is_empty() => target.extend_from_slice(bytes),
+        None if bytes.is_empty() => {}
+        _ => return Err(ExecutionEncodingError),
+    }
+    Ok(())
+}
+
+fn raw_wire(event: &mut ExecutionEvent) -> Option<&mut Vec<u8>> {
+    match &mut event.wire.as_mut()?.payload {
+        WirePayload::Json { raw_sse, .. } => raw_sse.as_mut(),
+        WirePayload::RawSse { frame } => Some(frame),
+        WirePayload::RawJson { body } | WirePayload::RawBody { body } => Some(body),
+    }
+}
+
+fn raw_failure(event: &mut ExecutionEvent) -> Option<&mut Vec<u8>> {
+    Some(&mut event.failure.as_mut()?.response.as_mut()?.body)
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/event.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/event.rs
new file mode 100644
index 000000000..5b437c6b5
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/event.rs
@@ -0,0 +1,178 @@
+//! 同一个上游事件的业务事实、原生表达与私有续写检查点。
+
+use serde::{Deserialize, Serialize};
+
+use super::{ContentKind, ExecutionFailure, FinishReason, ResponseObservation, Usage};
+
+/// 每个流分块是一个完整封套；同一 wire 的事实必须合并，避免重复交付客户端。
+/// 载荷及私有状态不实现 Debug，且不能用拆分封套绕过宿主大小和序列检查。
+#[derive(Clone, Default, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExecutionEvent {
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub facts: Vec<CanonicalEvent>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub wire: Option<WireEvent>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub observation: Option<ResponseObservation>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub session_update: Option<SessionUpdate>,
+    /// 失败时可附尚未交付的 wire；不能同时上报成功终态或续写检查点。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub failure: Option<ExecutionFailure>,
+}
+
+impl ExecutionEvent {
+    /// 编码为带长度与版本的事件载荷；原始 wire/错误正文不经过 JSON 数组或 base64。
+    ///
+    /// # Errors
+    /// 总长度超过事件上限或元数据无法序列化时返回错误。
+    pub fn encode(self) -> Result<Vec<u8>, super::ExecutionEncodingError> {
+        super::codec::encode_event(self)
+    }
+
+    /// 从完整的执行流载荷解码，先验证各段长度再解析元数据。
+    ///
+    /// # Errors
+    /// 版本、长度、元数据或二进制段声明不一致时返回错误。
+    pub fn decode(bytes: &[u8]) -> Result<Self, super::ExecutionEncodingError> {
+        super::codec::decode_event(bytes)
+    }
+
+    #[must_use]
+    pub fn failure(failure: ExecutionFailure) -> Self {
+        Self {
+            failure: Some(failure),
+            ..Self::default()
+        }
+    }
+
+    #[must_use]
+    pub fn with_failure(mut self, failure: ExecutionFailure) -> Self {
+        self.failure = Some(failure);
+        self
+    }
+    #[must_use]
+    pub fn canonical(fact: CanonicalEvent) -> Self {
+        Self {
+            facts: vec![fact],
+            ..Self::default()
+        }
+    }
+
+    #[must_use]
+    pub fn wire(wire: WireEvent) -> Self {
+        Self {
+            wire: Some(wire),
+            ..Self::default()
+        }
+    }
+
+    #[must_use]
+    pub fn observation(observation: ResponseObservation) -> Self {
+        Self {
+            observation: Some(observation),
+            ..Self::default()
+        }
+    }
+
+    #[must_use]
+    pub fn with_fact(mut self, fact: CanonicalEvent) -> Self {
+        self.facts.push(fact);
+        self
+    }
+
+    #[must_use]
+    pub fn with_observation(mut self, observation: ResponseObservation) -> Self {
+        self.observation = Some(observation);
+        self
+    }
+
+    #[must_use]
+    pub fn with_session_update(mut self, update: SessionUpdate) -> Self {
+        self.session_update = Some(update);
+        self
+    }
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
+pub enum CanonicalEvent {
+    Started {
+        id: String,
+        model: Option<String>,
+    },
+    ContentAdded {
+        index: u32,
+        kind: ContentKind,
+    },
+    TextDelta {
+        index: u32,
+        text: String,
+    },
+    ReasoningDelta {
+        index: u32,
+        text: String,
+    },
+    ToolCallDelta {
+        index: u32,
+        id: String,
+        name: Option<String>,
+        arguments: String,
+    },
+    Usage {
+        usage: Usage,
+    },
+    /// 明确确认仅按 Token 计费的累计用量；缺少必要事实时仍保持费用未知。
+    BillableUsage {
+        usage: Usage,
+        band: super::billing::PriceBand,
+    },
+    ProviderCost {
+        amount: String,
+        currency: String,
+    },
+    Completed {
+        id: String,
+        model: Option<String>,
+        reason: FinishReason,
+    },
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct WireEvent {
+    pub protocol: String,
+    pub payload: WirePayload,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum WirePayload {
+    Json {
+        event: Option<String>,
+        data: serde_json::Value,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        id: Option<String>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        retry: Option<u64>,
+        /// 一个完整 SSE 帧的原字节；存在时必须与解析后的 data 和元数据一致。
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        raw_sse: Option<Vec<u8>>,
+    },
+    /// 注释、非 JSON data 等原生 SSE 表达，不能夹带第二个帧。
+    RawSse { frame: Vec<u8> },
+    /// 一个完整的非流式 JSON 响应正文，保留空白与字段顺序。
+    RawJson { body: Vec<u8> },
+    /// 非流式 HTTP 响应正文的一个有序片段；Content-Type 与状态在首片 observation 中传递。
+    /// 客户端 adapter 必须同时限制单片与聚合后的总字节数。
+    RawBody { body: Vec<u8> },
+}
+
+/// 只可附在 Completed 事实所在的封套；最多 64 KiB。
+/// 状态必须能跨连接恢复，不代表宿主提供连接池或允许切换账号。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct SessionUpdate {
+    pub payload: serde_json::Map<String, serde_json::Value>,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/execution.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/execution.rs
new file mode 100644
index 000000000..f7dccf3bf
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/execution.rs
@@ -0,0 +1,210 @@
+//! Provider 的版本化数据合同；请求正文通过帧的独立二进制载荷传递。
+
+use serde::{Deserialize, Serialize};
+
+use crate::{Contributions, call::auth::CredentialOperation};
+
+use super::account::AccountOperation;
+
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ProbeOperation {
+    pub protocol: String,
+    pub body: serde_json::Map<String, serde_json::Value>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Registration {
+    #[serde(deserialize_with = "crate::capability::deserialize_contributions")]
+    pub contributes: Contributions,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub provider: Option<ProviderDescriptor>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ProviderDescriptor {
+    pub id: String,
+    pub models: Vec<ModelDescriptor>,
+    #[serde(default)]
+    pub credential_operations: Vec<CredentialOperation>,
+    /// 输入结构与表单提示；只能为已声明的 import、rotate、login 操作提供对象 schema。
+    /// 每份最多 64 KiB，仅允许文档内部引用；缺省的 login 接受空对象，import/rotate 接受任意对象。
+    #[serde(default)]
+    pub credential_input_schemas:
+        std::collections::BTreeMap<CredentialOperation, serde_json::Value>,
+    /// 从当前凭据投影到账号页的非敏感连接字段；写入仍复用 rotate schema 与事务。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub account_configuration: Option<super::account::AccountConfigurationDescriptor>,
+    /// 可选的账号管理操作；必须同时声明 account_management 能力。
+    #[serde(default)]
+    pub account_operations: Vec<AccountOperation>,
+    #[serde(default)]
+    pub exhaustive: bool,
+    /// 已校验的本地计价数据；必须同时声明 billing 能力。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub billing: Option<super::billing::BillingDescriptor>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model_discovery: Option<super::models::ModelDiscovery>,
+    /// 可选的请求画像目录；宿主准备后在请求同步路径中本地解析。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub request_profiles: Option<super::request_profile::RequestProfileDescriptor>,
+    /// 由 Provider 显式登记的账号认证 HTTP 操作。`id` 只是符号名，不能是 URL。
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub http_endpoints: Vec<ProviderHttpEndpoint>,
+    /// 原生续写状态的显式兼容合同；缺省时任何制品或实例 revision 变化都严格拒绝旧状态。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub continuation_state: Option<ContinuationStateDescriptor>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ContinuationStateDescriptor {
+    /// 插件与宿主都视为不透明的稳定格式标识。
+    pub format: String,
+    /// 当前版本写入检查点时使用的非零格式版本。
+    pub write_version: u32,
+    /// 当前版本能够读取的格式版本；必须有界、去重并包含 `write_version`。
+    pub readable_versions: Vec<u32>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ModelDescriptor {
+    pub id: String,
+    pub operations: Vec<OperationKind>,
+    #[serde(default)]
+    pub features: Vec<ModelFeature>,
+    #[serde(default)]
+    pub maximum_output_tokens: Option<u64>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum OperationKind {
+    Generate,
+    GenerateImage,
+    Search,
+    CountTokens,
+    ProviderHttp,
+}
+
+/// 插件公开的一个受限 HTTP 操作。实际 origin 与路径只由插件实现持有。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ProviderHttpEndpoint {
+    pub id: String,
+    pub methods: Vec<ProviderHttpMethod>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ProviderHttpMethod {
+    Get,
+    Post,
+}
+
+/// API 已过滤的入口 HTTP 信封；凭据、origin 与最终路径不由客户端提供。
+///
+/// Header 值可能包含不适合日志的客户端数据，因此该类型故意不实现 `Debug`。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ProviderHttpRequest {
+    pub endpoint: String,
+    pub method: ProviderHttpMethod,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub query: Option<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub headers: Vec<ProviderHttpHeader>,
+}
+
+/// 保留多值 header 的单个有序项。
+///
+/// 值按 HTTP 原始字节保存，因此该类型故意不实现 `Debug`。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ProviderHttpHeader {
+    pub name: String,
+    pub value: Vec<u8>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ModelFeature {
+    Tools,
+    Vision,
+    Reasoning,
+    JsonSchema,
+    /// Provider 能使用自己的响应标识与状态继续调用；不代表 WS 连接内保活。
+    NativeContinuation,
+}
+
+// 不派生 Debug：配置、上下文及凭据内容不进入宿主或插件诊断。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PrepareExecution {
+    pub protocol: String,
+    pub operation: OperationKind,
+    pub model: Option<String>,
+    pub account_id: String,
+    pub credential_revision: u64,
+    pub credential: serde_json::Map<String, serde_json::Value>,
+    pub context: serde_json::Map<String, serde_json::Value>,
+    pub request_profile: Option<serde_json::Value>,
+    /// Attempt 中间件追加且经宿主复核的业务 header；不含凭据或传输管理字段。
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub headers: Vec<ProviderHttpHeader>,
+    /// 宿主校验账号、凭据版本及实例授权后恢复的插件私有状态，不包含宿主绑定信息。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub provider_session_state: Option<serde_json::Map<String, serde_json::Value>>,
+    /// 只有 [`OperationKind::ProviderHttp`] 可携带该信封。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub http_request: Option<ProviderHttpRequest>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PreparedExecution {
+    pub token: String,
+    pub transport: String,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExecutePrepared {
+    pub token: String,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ContentKind {
+    Text,
+    Reasoning,
+    ToolCall,
+    Image,
+    Audio,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum FinishReason {
+    Stop,
+    Length,
+    ToolCall,
+    ContentFilter,
+    Other,
+}
+
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Usage {
+    pub input_tokens: Option<u64>,
+    pub output_tokens: Option<u64>,
+    pub cached_tokens: Option<u64>,
+    pub cache_write_tokens: Option<u64>,
+    pub reasoning_tokens: Option<u64>,
+    pub image_input_tokens: Option<u64>,
+    pub image_output_tokens: Option<u64>,
+    pub total_tokens: Option<u64>,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/failure.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/failure.rs
new file mode 100644
index 000000000..a548e3645
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/failure.rs
@@ -0,0 +1,40 @@
+//! 执行失败的稳定分类及仅供原请求方使用的响应载荷。
+
+use serde::{Deserialize, Serialize};
+
+/// 放在执行事件的二进制载荷中，不通过控制面 fault 或诊断日志传递正文。
+/// 实际状态码、请求 ID、公开响应头复用同一封套的 observation。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExecutionFailure {
+    pub kind: ExecutionFailureKind,
+    pub send_state: crate::SendState,
+    pub code: Option<String>,
+    pub retry_after_ms: Option<u64>,
+    pub response: Option<FailureResponse>,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ExecutionFailureKind {
+    InvalidRequest,
+    Unsupported,
+    Authentication,
+    PermissionDenied,
+    RateLimited,
+    QuotaExhausted,
+    Unavailable,
+    Protocol,
+    Timeout,
+    Cancelled,
+}
+
+/// 最多 64 KiB；只能包含当前上游响应，不能放入凭据或请求上下文。
+/// response.status 可表示客户端投影状态，不覆盖 observation.status 中的真实上游事实。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct FailureResponse {
+    pub status: u16,
+    pub content_type: Option<Vec<u8>>,
+    pub body: Vec<u8>,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/input.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/input.rs
new file mode 100644
index 000000000..8a0792877
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/input.rs
@@ -0,0 +1,22 @@
+use super::{ExecutionEncodingError, PrepareExecution};
+
+/// provider.prepare 的完整二进制载荷，控制 params 必须为空对象。
+/// 凭据、上下文和恢复状态不进入控制元数据，正文保持原始字节。
+pub struct ExecutionInput {
+    pub request: PrepareExecution,
+    pub body: Vec<u8>,
+}
+
+impl ExecutionInput {
+    /// # Errors
+    /// 元数据无法编码或总长度超过执行载荷上限时返回错误。
+    pub fn encode(self) -> Result<Vec<u8>, ExecutionEncodingError> {
+        super::codec::encode_input(self)
+    }
+
+    /// # Errors
+    /// 版本、分段长度或准备数据不合法时返回错误。
+    pub fn decode(bytes: &[u8]) -> Result<Self, ExecutionEncodingError> {
+        super::codec::decode_input(bytes)
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/maintenance.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/maintenance.rs
new file mode 100644
index 000000000..1145ad475
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/maintenance.rs
@@ -0,0 +1,28 @@
+//! 版本资料属于 Provider；宿主只接收完整、可校验、单调更新的目录。
+
+use serde::{Deserialize, Serialize};
+
+/// `provider.request_profiles.refresh` 的结果。序号必须大于零，且同一序号内容不可变。
+/// 用户配置与默认选择不能随后台刷新变化，只更新其解析资料与展示事实。
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestProfileRefresh {
+    pub sequence: u64,
+    pub profiles: super::RequestProfileDescriptor,
+}
+
+impl RequestProfileRefresh {
+    /// 对齐宿主版本资料缓存的有界文档合同。
+    pub const MAX_BYTES: usize = 16 * 1024;
+    /// 序号需可由跨进程缓存精确比较。
+    pub const MAX_SEQUENCE: u64 = (1_u64 << 53) - 1;
+}
+
+impl std::fmt::Debug for RequestProfileRefresh {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("RequestProfileRefresh")
+            .field("sequence", &self.sequence)
+            .finish_non_exhaustive()
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/mod.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/mod.rs
new file mode 100644
index 000000000..4167e7b9d
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/mod.rs
@@ -0,0 +1,33 @@
+//! Provider 执行与管理事实；宿主继续拥有账号、额度及提交事务。
+
+pub mod account;
+pub mod billing;
+mod codec;
+mod event;
+mod execution;
+mod failure;
+mod input;
+mod maintenance;
+pub mod models;
+mod observation;
+pub mod quota;
+mod request_profile;
+pub mod reset_credits;
+
+pub use codec::{ExecutionEncodingError, MAX_EXECUTION_PAYLOAD_BYTES};
+pub use event::{CanonicalEvent, ExecutionEvent, SessionUpdate, WireEvent, WirePayload};
+pub use execution::{
+    ContentKind, ContinuationStateDescriptor, ExecutePrepared, FinishReason, ModelDescriptor,
+    ModelFeature, OperationKind, PrepareExecution, PreparedExecution, ProbeOperation,
+    ProviderDescriptor, ProviderHttpEndpoint, ProviderHttpHeader, ProviderHttpMethod,
+    ProviderHttpRequest, Registration, Usage,
+};
+pub use failure::{ExecutionFailure, ExecutionFailureKind, FailureResponse};
+pub use input::ExecutionInput;
+pub use maintenance::RequestProfileRefresh;
+pub use observation::{HttpVersion, ResponseHeader, ResponseObservation, ResponseTimings};
+pub use request_profile::{
+    RequestProfileAttribute, RequestProfileDescriptor, RequestProfileOption,
+    RequestProfilePresentation, RequestProfileRelease, RequestProfileReleaseStatus,
+    RequestProfileTarget,
+};
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/models.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/models.rs
new file mode 100644
index 000000000..fb4708233
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/models.rs
@@ -0,0 +1,45 @@
+//! 账号模型发现；`provider.models` 以 [`super::account::AccountRequest`] 为二进制输入，
+//! 返回 [`AccountModels`] JSON 二进制载荷，控制参数和结果均为空对象。
+//!
+//! 未声明发现时只使用注册的静态 models。声明发现需要 models 能力以及 accounts 访问域；
+//! 若插件通过宿主 HTTP 查询上游，还需要 network 访问域。目录结果不携带账号写入，
+//! 更新凭据或其他权威事实必须经过独立的 prepared facts 与宿主提交合同。
+
+use serde::{Deserialize, Serialize};
+
+use super::ModelDescriptor;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ModelDiscovery {
+    /// 为 true 时静态模型适用于每个账号；同 ID 的发现结果覆盖该账号的静态声明。
+    pub include_static: bool,
+    /// 目录缓存有效期，必须在 1–3600 秒内；账号事实变化会提前失效。
+    pub cache_ttl_seconds: u32,
+}
+
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AccountModels {
+    /// 每次最多 4096 项；模型 ID、操作、特性均不得重复。
+    pub models: Vec<ModelDescriptor>,
+    /// 只有完整目录能因缺项拒绝账号；发现型目录的未知模型交由上游验证。
+    pub exhaustive: bool,
+    /// 可选的已准备账号事实；目标账号、Provider 和 revision 由宿主调用上下文绑定。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub prepared_account_facts: Option<crate::call::auth::CredentialFacts>,
+}
+
+impl std::fmt::Debug for AccountModels {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("AccountModels")
+            .field("models", &self.models)
+            .field("exhaustive", &self.exhaustive)
+            .field(
+                "prepared_account_facts",
+                &self.prepared_account_facts.as_ref().map(|_| "[PREPARED]"),
+            )
+            .finish()
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/observation.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/observation.rs
new file mode 100644
index 000000000..85410a081
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/observation.rs
@@ -0,0 +1,53 @@
+//! Provider 上游响应的安全观测；不会直接作为客户端正文输出。
+
+use serde::{Deserialize, Serialize};
+
+/// 不实现 Debug：请求标识及响应头属于上游私有数据。
+/// transport 由宿主采用已准备调用的值，插件不能改写执行身份。
+#[derive(Clone, Default, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ResponseObservation {
+    pub status: Option<u16>,
+    pub request_id: Option<String>,
+    pub service_tier: Option<String>,
+    pub response_model: Option<String>,
+    pub http_version: Option<HttpVersion>,
+    #[serde(default)]
+    pub timings: ResponseTimings,
+    /// 仅交付已筛选的客户端可公开头；宿主仍校验格式及禁止敏感/逐跳头。
+    #[serde(default)]
+    pub client_headers: Vec<ResponseHeader>,
+    /// 同次上游响应的额度进度，仅供历史配对预测；不改变账号准入、用量或账单。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub quota_forecast: Option<super::quota::QuotaForecast>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ResponseHeader {
+    pub name: String,
+    pub value: Vec<u8>,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum HttpVersion {
+    Http09,
+    Http10,
+    Http11,
+    Http2,
+    Http3,
+}
+
+#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ResponseTimings {
+    pub transport_decision_wait_ms: Option<u64>,
+    pub connect_ms: Option<u64>,
+    pub headers_ms: Option<u64>,
+    pub first_event_ms: Option<u64>,
+    pub first_reasoning_ms: Option<u64>,
+    pub first_text_ms: Option<u64>,
+    pub first_token_ms: Option<u64>,
+    pub provider_processing_ms: Option<u64>,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/quota.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/quota.rs
new file mode 100644
index 000000000..838cfda69
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/quota.rs
@@ -0,0 +1,87 @@
+//! Provider 额度合同；展示窗口与账号准入事实分别声明，宿主不从百分比推断是否禁止调度。
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Quota {
+    pub plan_type: Option<String>,
+    pub refresh_token_expires_at_ms: Option<i64>,
+    pub access: QuotaAccess,
+    pub windows: Vec<QuotaWindow>,
+    pub provider_data: Option<serde_json::Map<String, serde_json::Value>>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum QuotaAccess {
+    Unknown,
+    Allowed,
+    Exhausted {
+        evidence: QuotaEvidence,
+        reset_at_ms: Option<i64>,
+    },
+}
+
+#[derive(Clone, Copy, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum QuotaEvidence {
+    ProviderDenied,
+    AccountLimitReached,
+    UsageLimitReached,
+    PaymentRequired,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct QuotaWindow {
+    pub key: String,
+    pub group: String,
+    pub label: String,
+    pub limit_id: Option<String>,
+    pub limit_name: Option<String>,
+    pub role: Option<QuotaWindowRole>,
+    #[serde(default)]
+    pub account_wide: bool,
+    pub window_seconds: Option<u64>,
+    pub used_percent: Option<f64>,
+    pub reset_at_ms: Option<i64>,
+    pub limit_reached: bool,
+    pub provider_data: Option<serde_json::Map<String, serde_json::Value>>,
+}
+
+#[derive(Clone, Copy, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum QuotaWindowRole {
+    Primary,
+    Secondary,
+    Monthly,
+}
+
+/// 已筛选的上游额度观测，不携带凭据、任意响应头或供应商原始文档。
+///
+/// 宿主最多接受 64 个窗口及 32 KiB 持久化元数据；未知事实应省略整份观测。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct QuotaForecast {
+    pub plan_type: Option<String>,
+    pub windows: Vec<QuotaForecastWindow>,
+}
+
+/// 窗口身份必须与 `provider.quota` 的对应窗口完全一致；不以显示名称猜测关联。
+///
+/// `account_wide` 只有在本账号的所有模型用量均可归入该窗口时才能为 true。
+/// 观测不含账号或 Provider 标识，关联身份由宿主实际执行上下文确定。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct QuotaForecastWindow {
+    pub key: String,
+    pub group: String,
+    pub limit_id: Option<String>,
+    pub role: Option<QuotaWindowRole>,
+    #[serde(default)]
+    pub account_wide: bool,
+    pub window_seconds: u64,
+    pub used_percent: f64,
+    pub reset_at_ms: i64,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/request_profile.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/request_profile.rs
new file mode 100644
index 000000000..38652206b
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/request_profile.rs
@@ -0,0 +1,120 @@
+//! Provider 声明的请求画像选项；宿主在准备阶段校验并冻结本地解析目录。
+
+use serde::{Deserialize, Serialize};
+
+/// 一个 Provider 的有界请求画像目录。
+///
+/// `configuration` 是持久化的稳定选择，`resolved` 是本次请求交给插件的实际画像。
+/// 插件刷新版本资料时应保留 configuration，并在新目录中替换 resolved/presentation。
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestProfileDescriptor {
+    pub default_configuration: serde_json::Map<String, serde_json::Value>,
+    pub options: Vec<RequestProfileOption>,
+}
+
+impl std::fmt::Debug for RequestProfileDescriptor {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("RequestProfileDescriptor")
+            .field("default_configuration", &"[REDACTED]")
+            .field("options", &self.options)
+            .finish()
+    }
+}
+
+/// 一个可选画像；宿主不解释 Provider-owned 的 configuration/resolved 字段。
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestProfileOption {
+    pub id: String,
+    pub label: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    pub configuration: serde_json::Map<String, serde_json::Value>,
+    pub resolved: serde_json::Map<String, serde_json::Value>,
+    pub presentation: RequestProfilePresentation,
+}
+
+impl std::fmt::Debug for RequestProfileOption {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("RequestProfileOption")
+            .field("id", &self.id)
+            .field("label", &self.label)
+            .field("description", &self.description)
+            .field("configuration", &"[REDACTED]")
+            .field("resolved", &"[REDACTED]")
+            .field("presentation", &self.presentation)
+            .finish()
+    }
+}
+
+/// Provider 已生成的实际上游身份展示；宿主不从 resolved 字段重新推导这些值。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestProfilePresentation {
+    pub product: String,
+    pub version: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub build: Option<String>,
+    pub target: RequestProfileTarget,
+    pub user_agent: String,
+    #[serde(default)]
+    pub attributes: Vec<RequestProfileAttribute>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub verified_at_ms: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub release: Option<RequestProfileRelease>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestProfileTarget {
+    pub os_type: String,
+    pub os_version: String,
+    pub arch: String,
+    pub terminal: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestProfileAttribute {
+    pub label: String,
+    pub value: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RequestProfileRelease {
+    pub status: RequestProfileReleaseStatus,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub checked_at_ms: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub latest_version: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub latest_build: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub published_at_ms: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub minimum_system_version: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hardware_requirements: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub download_url: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub download_size: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub signature_present: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub error: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RequestProfileReleaseStatus {
+    Unchecked,
+    Current,
+    UpdateAvailable,
+    Failed,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/call/provider/reset_credits.rs b/backend/crates/gateway-plugin/sdk/src/call/provider/reset_credits.rs
new file mode 100644
index 000000000..353f38e16
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/call/provider/reset_credits.rs
@@ -0,0 +1,63 @@
+//! 主动额度重置卡合同；查询不保存库存，消费不直接更改宿主额度或账号状态。
+//!
+//! `account_management` 能力通过 `account_operations` 分别声明 `reset_credits` 和
+//! `consume_reset_credit`。Management 阶段的 `provider.reset_credits` 与
+//! `provider.consume_reset_credit` 分别接受 [`super::account::AccountRequest`] 与 [`ConsumeRequest`]；
+//! 控制参数与结果均为空对象，输入输出使用 JSON 二进制载荷。
+//! 两项操作都需要 accounts 访问域；消费仍由宿主按账号与凭据 revision 约束调用。
+//!
+//! 两项调用返回 [`Reply`]，数据分别为 [`Credits`] 和 [`ConsumeResult`]。明确上游拒绝与凭据需刷新
+//! 属于已完成的业务响应；只有确认本次没有消费时才能返回这两种结果。传输中断、超时或无法判断上游
+//! 是否完成必须返回 uncertain 错误，不能伪装为拒绝。通信层不自动重试消费，重试必须保留原始账号、
+//! credit_id 和 canonical UUIDv4 redeem_request_id。插件须将该键传给支持幂等的上游，不能自行换键。
+//!
+//! 文本最多 1024 字节且不含控制字符，列表最多 4096 张卡且 ID 非空、不重复，时间为 Unix 毫秒。
+//! code 使用宿主公共语义：reset、already_redeemed、no_credit、nothing_to_reset；未知公开结果保留原值。
+//! available_count 可以大于返回的卡片数，以支持上游只提供数量或部分清单的情形。
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ConsumeRequest {
+    pub account: super::account::AccountRequest,
+    pub credit_id: Option<String>,
+    pub redeem_request_id: String,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(
+    tag = "outcome",
+    content = "result",
+    rename_all = "snake_case",
+    deny_unknown_fields
+)]
+pub enum Reply<T> {
+    Completed(T),
+    CredentialRefreshRequired,
+    Rejected,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Credit {
+    pub id: String,
+    pub status: Option<String>,
+    pub title: Option<String>,
+    pub expires_at_ms: Option<i64>,
+    pub reset_type: Option<String>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Credits {
+    pub available_count: u64,
+    pub credits: Vec<Credit>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ConsumeResult {
+    pub code: String,
+    pub credit: Option<Credit>,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/capability.rs b/backend/crates/gateway-plugin/sdk/src/capability.rs
new file mode 100644
index 000000000..f31ef9f42
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/capability.rs
@@ -0,0 +1,209 @@
+use std::{collections::BTreeMap, fmt};
+
+use serde::{Deserialize, Deserializer, Serialize, de};
+
+/// 能力只声明可提供的行为，不等于管理员授予的回调权限。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Capability {
+    Models,
+    Authentication,
+    FrontendAuthentication,
+    Scheduler,
+    ModelRouter,
+    Executor,
+    Middleware,
+    RequestLifecycle,
+    WebSocketObserver,
+    Usage,
+    CommandLine,
+    Management,
+    Quota,
+    RequestProfile,
+    AccountManagement,
+    Billing,
+    Maintenance,
+}
+
+impl Capability {
+    /// 稳定能力标识；默认扩展项 ID 由它派生，不受显示名称影响。
+    #[must_use]
+    pub const fn identifier(self) -> &'static str {
+        match self {
+            Self::Models => "models",
+            Self::Authentication => "authentication",
+            Self::FrontendAuthentication => "frontend_authentication",
+            Self::Scheduler => "scheduler",
+            Self::ModelRouter => "model_router",
+            Self::Executor => "executor",
+            Self::Middleware => "middleware",
+            Self::RequestLifecycle => "request_lifecycle",
+            Self::WebSocketObserver => "web_socket_observer",
+            Self::Usage => "usage",
+            Self::CommandLine => "command_line",
+            Self::Management => "management",
+            Self::Quota => "quota",
+            Self::RequestProfile => "request_profile",
+            Self::AccountManagement => "account_management",
+            Self::Billing => "billing",
+            Self::Maintenance => "maintenance",
+        }
+    }
+
+    /// 固定调用阶段；只有中间件需要作者显式选择 request／attempt。
+    #[must_use]
+    pub const fn fixed_stages(self) -> &'static [Stage] {
+        match self {
+            Self::Models | Self::Authentication | Self::Quota => {
+                &[Stage::Management, Stage::Maintenance]
+            }
+            Self::FrontendAuthentication => &[Stage::Authentication],
+            Self::Scheduler => &[Stage::Scheduling],
+            Self::ModelRouter => &[Stage::Routing],
+            Self::Executor | Self::Billing => &[Stage::Execution],
+            Self::Middleware => &[],
+            Self::RequestLifecycle | Self::WebSocketObserver | Self::Usage => &[Stage::Observation],
+            Self::CommandLine => &[Stage::CommandLine],
+            Self::Management => &[Stage::Management],
+            Self::AccountManagement => &[Stage::Management, Stage::Observation],
+            Self::RequestProfile | Self::Maintenance => &[Stage::Maintenance],
+        }
+    }
+}
+
+/// 调用阶段由宿主签发，插件不能通过方法参数提升阶段。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Stage {
+    Registration,
+    Configuration,
+    Authentication,
+    Routing,
+    Scheduling,
+    Request,
+    Attempt,
+    Execution,
+    Observation,
+    Management,
+    CommandLine,
+    Maintenance,
+    /// 公共登录回调不继承插件实例的任何宿主回调权限。
+    PublicManagement,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum FailurePolicy {
+    Reject,
+    Delegate,
+    Observe,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct ContributionDeclaration {
+    #[serde(default)]
+    pub id: String,
+    #[serde(default = "default_capability_version")]
+    pub version: u32,
+    #[serde(default)]
+    pub stages: Vec<Stage>,
+    #[serde(default)]
+    pub input_formats: Vec<String>,
+    #[serde(default)]
+    pub output_formats: Vec<String>,
+}
+
+const fn default_capability_version() -> u32 {
+    1
+}
+
+/// 插件按能力标识索引的扩展项声明；每种能力至多声明一个处理器。
+pub type Contributions = BTreeMap<Capability, ContributionDeclaration>;
+
+pub(crate) fn deserialize_contributions<'de, D>(deserializer: D) -> Result<Contributions, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    struct ContributionsVisitor;
+
+    impl<'de> de::Visitor<'de> for ContributionsVisitor {
+        type Value = Contributions;
+
+        fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+            formatter.write_str("a map with one declaration per plugin capability")
+        }
+
+        fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
+        where
+            A: de::MapAccess<'de>,
+        {
+            let mut contributions = Contributions::new();
+            while let Some((capability, declaration)) = map.next_entry()? {
+                if contributions.insert(capability, declaration).is_some() {
+                    return Err(de::Error::custom("duplicate plugin capability declaration"));
+                }
+            }
+            Ok(contributions)
+        }
+    }
+
+    deserializer.deserialize_map(ContributionsVisitor)
+}
+
+/// 插件可访问的稳定资源域；动作与后续资源限制由接口合同表达，不编码在域名中。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Permission {
+    Network,
+    Models,
+    Accounts,
+    Requests,
+    PublicEndpoints,
+}
+
+impl Permission {
+    /// 当前公开访问域，安装摘要与授权校验复用同一集合。
+    pub const ALL: [Self; 5] = [
+        Self::Network,
+        Self::Models,
+        Self::Accounts,
+        Self::Requests,
+        Self::PublicEndpoints,
+    ];
+
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Network => "network",
+            Self::Models => "models",
+            Self::Accounts => "accounts",
+            Self::Requests => "requests",
+            Self::PublicEndpoints => "public_endpoints",
+        }
+    }
+
+    /// 安装摘要显示名。
+    #[must_use]
+    pub const fn label(self) -> &'static str {
+        match self {
+            Self::Network => "联网",
+            Self::Models => "模型调用",
+            Self::Accounts => "账号与凭据",
+            Self::Requests => "请求处理",
+            Self::PublicEndpoints => "公开入口",
+        }
+    }
+
+    /// 面向安装确认的访问含义；账号域明确包含原始凭据和修改权限。
+    #[must_use]
+    pub const fn description(self) -> &'static str {
+        match self {
+            Self::Network => "访问网络",
+            Self::Models => "查询模型与 API Key 信息并调用模型，可能产生消耗",
+            Self::Accounts => "读取和修改账号，包括访问原始凭据",
+            Self::Requests => "查看和处理请求、响应、路由及账号选择",
+            Self::PublicEndpoints => "提供无需登录即可访问的资源与回调入口",
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/client/frame.rs b/backend/crates/gateway-plugin/sdk/src/client/frame.rs
new file mode 100644
index 000000000..ce3832814
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/client/frame.rs
@@ -0,0 +1,63 @@
+use tokio::io::{AsyncRead, AsyncReadExt as _, AsyncWrite, AsyncWriteExt as _};
+
+use crate::{Frame, FrameError, Message};
+
+const MAX_METADATA_BYTES: usize = 64 * 1024;
+
+/// 八字节头分别是元数据和载荷的 u32 大端长度，分配内存前校验两者总量。
+pub async fn read_frame<R: AsyncRead + Unpin>(
+    reader: &mut R,
+    maximum: usize,
+) -> Result<Frame, FrameError> {
+    let metadata_len = reader.read_u32().await? as usize;
+    let payload_len = reader.read_u32().await? as usize;
+    check_lengths(metadata_len, payload_len, maximum)?;
+    let mut metadata = vec![0; metadata_len];
+    reader.read_exact(&mut metadata).await?;
+    let message = serde_json::from_slice(&metadata).map_err(|_| FrameError::Metadata)?;
+    let mut payload = vec![0; payload_len];
+    reader.read_exact(&mut payload).await?;
+    Ok(Frame { message, payload })
+}
+
+pub async fn write_frame<W: AsyncWrite + Unpin>(
+    writer: &mut W,
+    frame: &Frame,
+    maximum: usize,
+) -> Result<(), FrameError> {
+    let metadata = serde_json::to_vec(&frame.message).map_err(|_| FrameError::Metadata)?;
+    check_lengths(metadata.len(), frame.payload.len(), maximum)?;
+    let metadata_len = u32::try_from(metadata.len()).map_err(|_| FrameError::Length)?;
+    let payload_len = u32::try_from(frame.payload.len()).map_err(|_| FrameError::Length)?;
+    writer.write_u32(metadata_len).await?;
+    writer.write_u32(payload_len).await?;
+    writer.write_all(&metadata).await?;
+    writer.write_all(&frame.payload).await?;
+    writer.flush().await?;
+    Ok(())
+}
+
+pub(super) fn validate_frame(frame: &Frame, maximum: usize) -> Result<(), FrameError> {
+    validate_message(&frame.message, frame.payload.len(), maximum)
+}
+
+pub(super) fn validate_message(
+    message: &Message,
+    payload_len: usize,
+    maximum: usize,
+) -> Result<(), FrameError> {
+    let metadata = serde_json::to_vec(message).map_err(|_| FrameError::Metadata)?;
+    check_lengths(metadata.len(), payload_len, maximum)
+}
+
+fn check_lengths(metadata: usize, payload: usize, maximum: usize) -> Result<(), FrameError> {
+    if metadata == 0
+        || metadata > MAX_METADATA_BYTES
+        || metadata
+            .checked_add(payload)
+            .is_none_or(|total| total > maximum)
+    {
+        return Err(FrameError::Length);
+    }
+    Ok(())
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/client/middleware/body.rs b/backend/crates/gateway-plugin/sdk/src/client/middleware/body.rs
new file mode 100644
index 000000000..a49880c37
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/client/middleware/body.rs
@@ -0,0 +1,338 @@
+use std::{collections::VecDeque, num::NonZeroUsize};
+
+use crate::{
+    ErrorCode, PluginFault,
+    call::middleware::{
+        BODY_CLOSE_METHOD, BODY_READ_METHOD, MiddlewareBodyClose, MiddlewareBodyCloseResult,
+        MiddlewareBodyDisposition, MiddlewareBodyFrame, MiddlewareBodyFraming,
+        MiddlewareBodyHandle, MiddlewareBodyRead, MiddlewareBodyReadResult, MiddlewareResponseBody,
+    },
+};
+
+use super::super::session::{
+    HostClient, PullResponseFuture, PullResponseStream, ResponseStream, SessionError, StreamSender,
+};
+use super::invalid_input;
+
+const MAXIMUM_MAPPED_FRAMES_PER_SOURCE: usize = 64;
+const MAXIMUM_MAPPED_BYTES_PER_SOURCE: usize = 8 * 1024 * 1024;
+
+/// 惰性正文的一次完整 frame。
+pub struct MiddlewareBody {
+    source: MiddlewareBodySource,
+}
+
+enum MiddlewareBodySource {
+    Empty,
+    Host {
+        body: MiddlewareBodyHandle,
+        host: HostClient,
+        touched: bool,
+        last_source_id: u64,
+    },
+    Plugin {
+        framing: MiddlewareBodyFraming,
+        stream: ResponseStream,
+    },
+}
+
+impl MiddlewareBody {
+    #[must_use]
+    pub fn empty() -> Self {
+        Self {
+            source: MiddlewareBodySource::Empty,
+        }
+    }
+
+    /// 从已编码完整 frame 构造有界插件输出流。
+    #[must_use]
+    pub fn from_frames(framing: MiddlewareBodyFraming, frames: Vec<MiddlewareBodyFrame>) -> Self {
+        Self {
+            source: MiddlewareBodySource::Plugin {
+                framing,
+                stream: ResponseStream::from_chunks(
+                    frames
+                        .into_iter()
+                        .map(MiddlewareBodyFrame::encode)
+                        .collect(),
+                ),
+            },
+        }
+    }
+
+    /// 创建插件生产的有界正文流。
+    #[must_use]
+    pub fn channel(
+        framing: MiddlewareBodyFraming,
+        capacity: NonZeroUsize,
+    ) -> (MiddlewareBodySender, Self) {
+        let (sender, stream) = ResponseStream::channel(capacity);
+        (
+            MiddlewareBodySender { sender },
+            Self {
+                source: MiddlewareBodySource::Plugin { framing, stream },
+            },
+        )
+    }
+
+    #[must_use]
+    pub const fn framing(&self) -> Option<MiddlewareBodyFraming> {
+        match &self.source {
+            MiddlewareBodySource::Empty => None,
+            MiddlewareBodySource::Host { body, .. } => Some(body.framing),
+            MiddlewareBodySource::Plugin { framing, .. } => Some(*framing),
+        }
+    }
+
+    /// 拉取下一完整 frame。调用后该 opaque handle 不能再作为未读直通返回。
+    pub async fn read(&mut self) -> Result<Option<MiddlewareBodyFrame>, PluginFault> {
+        let MiddlewareBodySource::Host {
+            body,
+            host,
+            touched,
+            last_source_id,
+        } = &mut self.source
+        else {
+            return Err(PluginFault::new(
+                ErrorCode::InvalidInput,
+                "middleware body is not a downstream handle",
+            ));
+        };
+        *touched = true;
+        let maximum_bytes =
+            u32::try_from(host.maximum_frame_bytes()).map_err(|_| invalid_input())?;
+        let reply = host
+            .call(
+                BODY_READ_METHOD,
+                serde_json::to_value(MiddlewareBodyRead {
+                    handle: body.handle.clone(),
+                    maximum_bytes,
+                })
+                .map_err(|_| invalid_input())?,
+                Vec::new(),
+            )
+            .await
+            .map_err(SessionError::into_plugin_fault)?;
+        let result: MiddlewareBodyReadResult =
+            serde_json::from_value(reply.result).map_err(|_| invalid_input())?;
+        if result.framing != body.framing
+            || (result.eof && result.source_id != 0)
+            || (!result.eof && (result.source_id == 0 || result.source_id <= *last_source_id))
+        {
+            return Err(invalid_input());
+        }
+        if result.eof {
+            if result.terminal || !reply.payload.is_empty() {
+                return Err(invalid_input());
+            }
+            return Ok(None);
+        }
+        *last_source_id = result.source_id;
+        MiddlewareBodyFrame::from_source(reply.payload, result.terminal, result.source_id)
+            .map(Some)
+            .map_err(|_| invalid_input())
+    }
+
+    /// 提前关闭宿主正文句柄。父调用取消或结束也会由 Runtime 兜底回收。
+    pub async fn close(&mut self) -> Result<(), PluginFault> {
+        let MiddlewareBodySource::Host { body, host, .. } = &self.source else {
+            self.source = MiddlewareBodySource::Empty;
+            return Ok(());
+        };
+        let reply = host
+            .call(
+                BODY_CLOSE_METHOD,
+                serde_json::to_value(MiddlewareBodyClose {
+                    handle: body.handle.clone(),
+                })
+                .map_err(|_| invalid_input())?,
+                Vec::new(),
+            )
+            .await
+            .map_err(SessionError::into_plugin_fault)?;
+        if !reply.payload.is_empty()
+            || serde_json::from_value::<MiddlewareBodyCloseResult>(reply.result).is_err()
+        {
+            return Err(invalid_input());
+        }
+        self.source = MiddlewareBodySource::Empty;
+        Ok(())
+    }
+
+    /// 按下游 Credit 惰性拉取并映射完整 frame；闭包可在单次调用内持有状态。
+    ///
+    /// 每个输入可生成零个、一个或多个输出。SDK 不预读或另起后台任务；Runtime
+    /// 继续复核 frame 大小、源终态与输出终态的一致性。
+    pub fn map_frames<F>(self, transform: F) -> Result<Self, PluginFault>
+    where
+        F: FnMut(MiddlewareBodyFrame) -> Result<Vec<MiddlewareBodyFrame>, PluginFault>
+            + Send
+            + 'static,
+    {
+        let Some(framing) = self.framing() else {
+            return Ok(Self::empty());
+        };
+        if !matches!(&self.source, MiddlewareBodySource::Host { .. }) {
+            return Err(PluginFault::new(
+                ErrorCode::InvalidInput,
+                "only a downstream middleware body can be mapped",
+            ));
+        }
+        Ok(Self {
+            source: MiddlewareBodySource::Plugin {
+                framing,
+                stream: ResponseStream::pull(Box::new(MappedBody {
+                    input: self,
+                    transform,
+                    buffered: VecDeque::new(),
+                    finished: false,
+                })),
+            },
+        })
+    }
+
+    pub(super) fn from_host(body: MiddlewareBodyHandle, host: HostClient) -> Self {
+        Self {
+            source: MiddlewareBodySource::Host {
+                body,
+                host,
+                touched: false,
+                last_source_id: 0,
+            },
+        }
+    }
+
+    pub(super) fn into_wire(self) -> Result<(MiddlewareResponseBody, ResponseStream), PluginFault> {
+        match self.source {
+            MiddlewareBodySource::Empty => Ok((
+                MiddlewareResponseBody::Empty,
+                ResponseStream::from_chunks(Vec::new()),
+            )),
+            MiddlewareBodySource::Host {
+                body,
+                touched: false,
+                ..
+            } => Ok((
+                MiddlewareResponseBody::PassThrough { body },
+                ResponseStream::from_chunks(Vec::new()),
+            )),
+            MiddlewareBodySource::Host { touched: true, .. } => Err(PluginFault::new(
+                ErrorCode::InvalidInput,
+                "a consumed middleware body cannot be passed through",
+            )),
+            MiddlewareBodySource::Plugin { framing, stream } => {
+                Ok((MiddlewareResponseBody::Stream { framing }, stream))
+            }
+        }
+    }
+}
+
+struct MappedBody<F> {
+    input: MiddlewareBody,
+    transform: F,
+    buffered: VecDeque<MiddlewareBodyFrame>,
+    finished: bool,
+}
+
+impl<F> PullResponseStream for MappedBody<F>
+where
+    F: FnMut(MiddlewareBodyFrame) -> Result<Vec<MiddlewareBodyFrame>, PluginFault> + Send + 'static,
+{
+    fn next(&mut self) -> PullResponseFuture<'_> {
+        Box::pin(async move {
+            loop {
+                if let Some(frame) = self.buffered.pop_front() {
+                    return Some(Ok(frame.encode()));
+                }
+                if self.finished {
+                    return None;
+                }
+                let frame = match self.input.read().await {
+                    Ok(Some(frame)) => frame,
+                    Ok(None) => {
+                        self.finished = true;
+                        return None;
+                    }
+                    Err(error) => {
+                        self.finished = true;
+                        return Some(Err(error));
+                    }
+                };
+                let source_id = frame.source_id();
+                match (self.transform)(frame) {
+                    Ok(frames) => {
+                        let count = frames.len();
+                        let mapped_bytes = frames.iter().try_fold(0_usize, |total, frame| {
+                            total.checked_add(frame.payload.len())
+                        });
+                        if count > MAXIMUM_MAPPED_FRAMES_PER_SOURCE
+                            || mapped_bytes
+                                .is_none_or(|bytes| bytes > MAXIMUM_MAPPED_BYTES_PER_SOURCE)
+                        {
+                            self.finished = true;
+                            let _ = self.input.close().await;
+                            return Some(Err(PluginFault::new(
+                                ErrorCode::Capacity,
+                                "middleware frame expansion exceeds the limit",
+                            )));
+                        }
+                        if count == 0 {
+                            let marker = MiddlewareBodyFrame::new(Vec::new(), false)
+                                .map_to_source(source_id, MiddlewareBodyDisposition::Drop)
+                                .map_err(|_| invalid_input());
+                            match marker {
+                                Ok(marker) => self.buffered.push_back(marker),
+                                Err(error) => {
+                                    self.finished = true;
+                                    let _ = self.input.close().await;
+                                    return Some(Err(error));
+                                }
+                            }
+                        } else {
+                            for (index, frame) in frames.into_iter().enumerate() {
+                                let disposition = if count == 1 {
+                                    MiddlewareBodyDisposition::Only
+                                } else if index == 0 {
+                                    MiddlewareBodyDisposition::First
+                                } else if index + 1 == count {
+                                    MiddlewareBodyDisposition::Last
+                                } else {
+                                    MiddlewareBodyDisposition::More
+                                };
+                                match frame.map_to_source(source_id, disposition) {
+                                    Ok(frame) => self.buffered.push_back(frame),
+                                    Err(_) => {
+                                        self.finished = true;
+                                        let _ = self.input.close().await;
+                                        return Some(Err(invalid_input()));
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    Err(error) => {
+                        self.finished = true;
+                        let _ = self.input.close().await;
+                        return Some(Err(error));
+                    }
+                }
+            }
+        })
+    }
+}
+
+/// 插件输出正文的有界生产端；每个发送项必须是完整 frame。
+#[derive(Clone)]
+pub struct MiddlewareBodySender {
+    sender: StreamSender,
+}
+
+impl MiddlewareBodySender {
+    pub async fn send(&self, frame: MiddlewareBodyFrame) -> Result<(), SessionError> {
+        self.sender.send(frame.encode()).await
+    }
+
+    pub async fn fail(&self, fault: PluginFault) -> Result<(), SessionError> {
+        self.sender.fail(fault).await
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/client/middleware/mod.rs b/backend/crates/gateway-plugin/sdk/src/client/middleware/mod.rs
new file mode 100644
index 000000000..558c20c34
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/client/middleware/mod.rs
@@ -0,0 +1,331 @@
+mod body;
+mod plugin;
+
+pub use body::{MiddlewareBody, MiddlewareBodySender};
+pub use plugin::MiddlewarePlugin;
+
+use crate::{
+    CallContext, ErrorCode, PluginFault, Stage,
+    call::middleware::{
+        HANDLE_METHOD, MiddlewareHeader, MiddlewareHeaderMutation, MiddlewareMount,
+        MiddlewareNextRequest, MiddlewareNextResponse, MiddlewareRequestBody,
+        MiddlewareRequestHead, MiddlewareResponseHead, NEXT_METHOD,
+    },
+};
+
+use super::session::{CallCancellation, CallReply, HostClient, PluginCall, SessionError};
+
+/// 作者可读取并按授权修改的一次中间件请求。
+///
+/// 直接修改公开的 `head`/`body` 会由 [`MiddlewareNext::run`] 与原投影比较；
+/// `replace_body` 还可明确表达“替换为空正文”。
+pub struct MiddlewareRequest {
+    pub head: MiddlewareRequestHead,
+    pub body: Vec<u8>,
+    original_protocol: String,
+    original_headers: Vec<MiddlewareHeader>,
+    original_body: Vec<u8>,
+    body_visible: bool,
+    body_replaced: bool,
+    header_mutations: Vec<MiddlewareHeaderMutation>,
+}
+
+impl MiddlewareRequest {
+    /// 明确替换请求正文；空 Vec 也表示 replace-empty，而不是保留原正文。
+    pub fn replace_body(&mut self, body: Vec<u8>) {
+        self.body = body;
+        self.body_replaced = true;
+    }
+
+    /// 删除原始集合中同名的全部 header。
+    pub fn remove_header(&mut self, name: impl Into<String>) {
+        let name = name.into();
+        self.head
+            .headers
+            .retain(|header| !header.name.eq_ignore_ascii_case(&name));
+        self.header_mutations
+            .push(MiddlewareHeaderMutation::Remove { name });
+    }
+
+    /// 在原始集合之后追加一个 header，保留同名多值。
+    pub fn append_header(&mut self, name: impl Into<String>, value: Vec<u8>) {
+        let name = name.into();
+        self.head.headers.push(MiddlewareHeader {
+            name: name.clone(),
+            value: value.clone(),
+        });
+        self.header_mutations
+            .push(MiddlewareHeaderMutation::Append { name, value });
+    }
+
+    fn into_next_parts(self) -> (MiddlewareNextRequest, Vec<u8>) {
+        let protocol = (self.head.protocol != self.original_protocol).then_some(self.head.protocol);
+        let header_mutations = finish_header_mutations(
+            &self.original_headers,
+            self.header_mutations,
+            self.head.headers,
+        );
+        let changed_body = self.body_replaced
+            || self.body != self.original_body
+            || (!self.body_visible && !self.body.is_empty());
+        let (body, payload) = if changed_body {
+            (MiddlewareRequestBody::Replace, self.body)
+        } else {
+            (MiddlewareRequestBody::Preserve, Vec::new())
+        };
+        (
+            MiddlewareNextRequest {
+                protocol,
+                header_mutations,
+                body,
+            },
+            payload,
+        )
+    }
+}
+
+fn replace_headers(
+    original: &[MiddlewareHeader],
+    replacement: Vec<MiddlewareHeader>,
+) -> Vec<MiddlewareHeaderMutation> {
+    let mut removed = Vec::<String>::new();
+    for header in original {
+        if !removed
+            .iter()
+            .any(|name| name.eq_ignore_ascii_case(&header.name))
+        {
+            removed.push(header.name.clone());
+        }
+    }
+    let mut mutations = removed
+        .into_iter()
+        .map(|name| MiddlewareHeaderMutation::Remove { name })
+        .collect::<Vec<_>>();
+    mutations.extend(
+        replacement
+            .into_iter()
+            .map(|header| MiddlewareHeaderMutation::Append {
+                name: header.name,
+                value: header.value,
+            }),
+    );
+    mutations
+}
+
+fn finish_header_mutations(
+    original: &[MiddlewareHeader],
+    mut mutations: Vec<MiddlewareHeaderMutation>,
+    replacement: Vec<MiddlewareHeader>,
+) -> Vec<MiddlewareHeaderMutation> {
+    let mut projected = original.to_vec();
+    for mutation in &mutations {
+        match mutation {
+            MiddlewareHeaderMutation::Remove { name } => {
+                projected.retain(|header| !header.name.eq_ignore_ascii_case(name));
+            }
+            MiddlewareHeaderMutation::Append { name, value } => {
+                projected.push(MiddlewareHeader {
+                    name: name.clone(),
+                    value: value.clone(),
+                });
+            }
+        }
+    }
+    if projected != replacement {
+        mutations.extend(replace_headers(&projected, replacement));
+    }
+    mutations
+}
+
+/// 绑定当前父调用的 single-use continuation。
+pub struct MiddlewareNext {
+    host: HostClient,
+}
+
+impl MiddlewareNext {
+    /// 消费 continuation 并进入链中下一层。Rust 所有权阻止安全代码重复调用；
+    /// Runtime 仍会拒绝恶意手写 RPC 的第二次调用。
+    pub async fn run(self, request: MiddlewareRequest) -> Result<MiddlewareResponse, PluginFault> {
+        let (request, payload) = request.into_next_parts();
+        let reply = self
+            .host
+            .call(
+                NEXT_METHOD,
+                serde_json::to_value(request).map_err(|_| invalid_input())?,
+                payload,
+            )
+            .await
+            .map_err(SessionError::into_plugin_fault)?;
+        if !reply.payload.is_empty() {
+            return Err(invalid_input());
+        }
+        let response: MiddlewareNextResponse =
+            serde_json::from_value(reply.result).map_err(|_| invalid_input())?;
+        MiddlewareResponse::from_next(response, self.host)
+    }
+}
+
+/// 作者返回的响应；原 next 响应头以增量方式修改，隐藏字段仍由 Runtime 保存。
+pub struct MiddlewareResponse {
+    pub protocol: String,
+    pub status: u16,
+    pub headers: Vec<MiddlewareHeader>,
+    pub body: MiddlewareBody,
+    source: Option<String>,
+    original_protocol: Option<String>,
+    original_status: Option<u16>,
+    original_headers: Vec<MiddlewareHeader>,
+    header_mutations: Vec<MiddlewareHeaderMutation>,
+}
+
+impl MiddlewareResponse {
+    fn from_next(response: MiddlewareNextResponse, host: HostClient) -> Result<Self, PluginFault> {
+        if response.response.is_empty()
+            || response.protocol.is_empty()
+            || !(100..=599).contains(&response.status)
+            || response
+                .body
+                .as_ref()
+                .is_some_and(|body| body.handle.is_empty())
+        {
+            return Err(invalid_input());
+        }
+        let body = response.body.map_or_else(MiddlewareBody::empty, |body| {
+            MiddlewareBody::from_host(body, host)
+        });
+        Ok(Self {
+            protocol: response.protocol.clone(),
+            status: response.status,
+            headers: response.headers.clone(),
+            body,
+            source: Some(response.response),
+            original_protocol: Some(response.protocol),
+            original_status: Some(response.status),
+            original_headers: response.headers,
+            header_mutations: Vec::new(),
+        })
+    }
+
+    /// 创建不调用 next 的短路响应。
+    #[must_use]
+    pub fn direct(
+        protocol: impl Into<String>,
+        status: u16,
+        headers: Vec<MiddlewareHeader>,
+        body: MiddlewareBody,
+    ) -> Self {
+        Self {
+            protocol: protocol.into(),
+            status,
+            headers,
+            body,
+            source: None,
+            original_protocol: None,
+            original_status: None,
+            original_headers: Vec::new(),
+            header_mutations: Vec::new(),
+        }
+    }
+
+    pub fn remove_header(&mut self, name: impl Into<String>) {
+        let name = name.into();
+        self.headers
+            .retain(|header| !header.name.eq_ignore_ascii_case(&name));
+        self.header_mutations
+            .push(MiddlewareHeaderMutation::Remove { name });
+    }
+
+    pub fn append_header(&mut self, name: impl Into<String>, value: Vec<u8>) {
+        let name = name.into();
+        self.headers.push(MiddlewareHeader {
+            name: name.clone(),
+            value: value.clone(),
+        });
+        self.header_mutations
+            .push(MiddlewareHeaderMutation::Append { name, value });
+    }
+
+    /// 转为现有 RPC reply。即使正文 opaque 直通或为空也使用空 stream，确保单一 End。
+    pub fn into_reply(self) -> Result<CallReply, PluginFault> {
+        if self.protocol.is_empty() || !(100..=599).contains(&self.status) {
+            return Err(invalid_input());
+        }
+        let header_mutations =
+            finish_header_mutations(&self.original_headers, self.header_mutations, self.headers);
+        let protocol = (self.original_protocol.as_deref() != Some(self.protocol.as_str()))
+            .then_some(self.protocol);
+        let status = (self.original_status != Some(self.status)).then_some(self.status);
+        let (body, stream) = self.body.into_wire()?;
+        let result = serde_json::to_value(MiddlewareResponseHead {
+            response: self.source,
+            protocol,
+            status,
+            header_mutations,
+            body,
+        })
+        .map_err(|_| invalid_input())?;
+        Ok(CallReply::stream(result, Vec::new(), stream))
+    }
+}
+
+/// 交给中间件作者的一次真实调用。
+pub struct MiddlewareCall {
+    pub context: CallContext,
+    pub request: MiddlewareRequest,
+    pub next: MiddlewareNext,
+    pub cancellation: CallCancellation,
+    pub host: HostClient,
+}
+
+impl MiddlewareCall {
+    /// 从 `middleware.handle` RPC 解码并交叉检查宿主签发的 mount/身份。
+    pub fn try_from(call: PluginCall) -> Result<Self, PluginFault> {
+        if call.method != HANDLE_METHOD {
+            return Err(PluginFault::new(
+                ErrorCode::Unsupported,
+                "plugin method is not supported",
+            ));
+        }
+        let head: MiddlewareRequestHead =
+            serde_json::from_value(call.params).map_err(|_| invalid_input())?;
+        let mount = match call.context.stage {
+            Stage::Request => MiddlewareMount::Request,
+            Stage::Attempt => MiddlewareMount::Attempt,
+            _ => return Err(invalid_input()),
+        };
+        if head.mount != mount
+            || call.context.request_id.as_deref() != Some(head.request_id.as_str())
+            || call.context.account_id != head.account_id
+            || (mount == MiddlewareMount::Request && head.attempt_index.is_some())
+            || (mount == MiddlewareMount::Attempt
+                && head.attempt_index.is_none_or(|attempt| attempt == 0))
+            || !head.body_visible && !call.payload.is_empty()
+        {
+            return Err(invalid_input());
+        }
+        let original_body = call.payload.clone();
+        let original_protocol = head.protocol.clone();
+        let original_headers = head.headers.clone();
+        let host = call.host;
+        Ok(Self {
+            context: call.context,
+            request: MiddlewareRequest {
+                body: call.payload,
+                original_body,
+                body_visible: head.body_visible,
+                body_replaced: false,
+                original_protocol,
+                original_headers,
+                header_mutations: Vec::new(),
+                head,
+            },
+            next: MiddlewareNext { host: host.clone() },
+            cancellation: call.cancellation,
+            host,
+        })
+    }
+}
+
+fn invalid_input() -> PluginFault {
+    PluginFault::new(ErrorCode::InvalidInput, "middleware input is invalid")
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/client/middleware/plugin.rs b/backend/crates/gateway-plugin/sdk/src/client/middleware/plugin.rs
new file mode 100644
index 000000000..53e04fccc
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/client/middleware/plugin.rs
@@ -0,0 +1,125 @@
+use std::future::Future;
+
+use crate::{
+    Capability, Contributions, ErrorCode, PluginFault, Stage,
+    call::{middleware::HANDLE_METHOD, provider::Registration},
+};
+
+use super::{
+    super::session::{CallFuture, CallReply, PluginCall, PluginHandler, SessionError},
+    MiddlewareCall, MiddlewareResponse,
+};
+
+/// 单个中间件插件的作者入口；自动注册并将 RPC 分派到类型化业务函数。
+///
+/// 传入作者清单的完整能力列表，不从宿主握手照抄未实现的能力。此入口仅承载
+/// 一个 middleware 处理器；复合插件仍使用 [`PluginHandler`]，不能虚报其他能力。
+/// 会话、授权和生命周期分别由既有 SDK 会话与宿主负责，不在此建立第二套状态。
+///
+/// # Examples
+///
+/// ```
+/// use gateway_plugin_sdk::{Capability, ContributionDeclaration, Contributions, Stage};
+/// use gateway_plugin_sdk::client::{MiddlewareCall, MiddlewarePlugin};
+///
+/// let contributes = Contributions::from([(Capability::Middleware, ContributionDeclaration {
+///     id: "acme.request-tags.tagRequest".into(),
+///     version: 1,
+///     stages: vec![Stage::Request],
+///     input_formats: vec!["openai".into()],
+///     output_formats: vec!["openai".into()],
+/// })]);
+/// let plugin = MiddlewarePlugin::new(&contributes, |call: MiddlewareCall| async move {
+///     let MiddlewareCall { mut request, next, .. } = call;
+///     request.append_header("x-team", b"research".to_vec());
+///     next.run(request).await
+/// })?;
+/// // 将 plugin 交给 PluginSession::run；请求头修改仍需管理员授权。
+/// # Ok::<(), gateway_plugin_sdk::client::SessionError>(())
+/// ```
+pub struct MiddlewarePlugin<F> {
+    contributes: Contributions,
+    handler: F,
+}
+
+impl<F, Fut> MiddlewarePlugin<F>
+where
+    F: Fn(MiddlewareCall) -> Fut + Send + Sync + 'static,
+    Fut: Future<Output = Result<MiddlewareResponse, PluginFault>> + Send + 'static,
+{
+    /// 绑定清单中唯一的中间件声明与业务处理函数。
+    ///
+    /// # Errors
+    ///
+    /// 空声明、其他能力、重复能力、不支持的能力版本或挂载阶段返回配置错误。
+    /// 包格式、资源和权限仍由宿主校验；此处不根据代码推断或扩张授权。
+    pub fn new(contributes: &Contributions, handler: F) -> Result<Self, SessionError> {
+        let Some(declaration) = contributes.get(&Capability::Middleware) else {
+            return Err(SessionError::Configuration);
+        };
+        if contributes.len() != 1
+            || declaration.version != 1
+            || declaration.stages.is_empty()
+            || declaration.stages.len() > 2
+            || declaration
+                .stages
+                .iter()
+                .any(|stage| !matches!(stage, Stage::Request | Stage::Attempt))
+            || (declaration.stages.len() == 2 && declaration.stages[0] == declaration.stages[1])
+        {
+            return Err(SessionError::Configuration);
+        }
+        Ok(Self {
+            contributes: contributes.clone(),
+            handler,
+        })
+    }
+}
+
+impl<F, Fut> PluginHandler for MiddlewarePlugin<F>
+where
+    F: Fn(MiddlewareCall) -> Fut + Send + Sync + 'static,
+    Fut: Future<Output = Result<MiddlewareResponse, PluginFault>> + Send + 'static,
+{
+    fn call(&self, call: PluginCall) -> CallFuture<'_> {
+        Box::pin(async move {
+            let Some(declaration) = self.contributes.get(&Capability::Middleware) else {
+                return Err(PluginFault::new(
+                    ErrorCode::Fault,
+                    "plugin middleware declaration is unavailable",
+                ));
+            };
+            match call.method.as_str() {
+                "plugin.register" => {
+                    if call.context.stage != Stage::Registration
+                        || !call
+                            .params
+                            .as_object()
+                            .is_some_and(serde_json::Map::is_empty)
+                        || !call.payload.is_empty()
+                    {
+                        return Err(super::invalid_input());
+                    }
+                    let registration = Registration {
+                        contributes: self.contributes.clone(),
+                        provider: None,
+                    };
+                    let result =
+                        serde_json::to_value(registration).map_err(|_| super::invalid_input())?;
+                    Ok(CallReply::unary(result, Vec::new()))
+                }
+                HANDLE_METHOD => {
+                    if !declaration.stages.contains(&call.context.stage) {
+                        return Err(super::invalid_input());
+                    }
+                    let call = MiddlewareCall::try_from(call)?;
+                    (self.handler)(call).await?.into_reply()
+                }
+                _ => Err(PluginFault::new(
+                    ErrorCode::Unsupported,
+                    "plugin method is not supported",
+                )),
+            }
+        })
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/client/mod.rs b/backend/crates/gateway-plugin/sdk/src/client/mod.rs
new file mode 100644
index 000000000..11b1a5457
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/client/mod.rs
@@ -0,0 +1,19 @@
+//! 可选的插件侧异步传输与会话辅助；SDK 不启动网关服务。
+
+mod frame;
+mod middleware;
+mod plugin;
+mod session;
+
+pub use frame::{read_frame, write_frame};
+pub use middleware::{
+    MiddlewareBody, MiddlewareBodySender, MiddlewareCall, MiddlewareNext, MiddlewarePlugin,
+    MiddlewareRequest, MiddlewareResponse,
+};
+pub use plugin::{
+    AuthorError, ComposedPlugin, Empty, Method, PluginBuilder, TypedCall, TypedReply, methods,
+};
+pub use session::{
+    CallCancellation, CallFuture, CallReply, HostClient, HostReply, PluginCall, PluginHandler,
+    PluginSession, ResponseStream, SessionConfig, SessionError, StreamSender,
+};
diff --git a/backend/crates/gateway-plugin/sdk/src/client/plugin/methods.rs b/backend/crates/gateway-plugin/sdk/src/client/plugin/methods.rs
new file mode 100644
index 000000000..749685531
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/client/plugin/methods.rs
@@ -0,0 +1,283 @@
+//! 类型化业务方法目录；控制参数、敏感载荷、阶段与响应流在此固定。
+
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+
+use crate::{
+    Capability as C, Stage as S,
+    call::{
+        auth, frontend_authentication as frontend, host, management, observation, policy, provider,
+    },
+};
+
+use super::{
+    Empty, Method,
+    typed::{
+        decode_execution_input, decode_metadata, decode_metadata_without_payload, decode_payload,
+        encode_execution_stream, encode_metadata, encode_metadata_stream,
+        encode_metadata_with_payload, encode_payload,
+    },
+};
+
+pub const MANAGEMENT_REGISTER: Method<Empty, management::ManagementRegistration> = Method::new(
+    "management.register",
+    &[C::Management],
+    &[S::Registration],
+    decode_metadata_without_payload,
+    encode_payload,
+);
+pub const MANAGEMENT_HANDLE: Method<management::ManagementRequest, management::ManagementResponse> =
+    Method::new(
+        "management.handle",
+        &[C::Management],
+        &[S::Management],
+        decode_metadata,
+        encode_metadata_with_payload,
+    );
+pub const MANAGEMENT_CALLBACK: Method<
+    management::ManagementRequest,
+    management::ManagementResponse,
+> = Method::new(
+    "management.callback",
+    &[C::Management],
+    &[S::PublicManagement],
+    decode_metadata_without_payload,
+    encode_metadata_with_payload,
+);
+pub const COMMAND_LINE_REGISTER: Method<Empty, management::CommandRegistration> = Method::new(
+    "command_line.register",
+    &[C::CommandLine],
+    &[S::Registration],
+    decode_metadata_without_payload,
+    encode_payload,
+);
+pub const COMMAND_LINE_EXECUTE: Method<management::CommandInvocation, management::CommandResult> =
+    Method::new(
+        "command_line.execute",
+        &[C::CommandLine],
+        &[S::CommandLine],
+        decode_payload,
+        encode_payload,
+    );
+pub const ROUTE_MODEL: Method<policy::ModelRouteRequest, policy::ModelRouteDecision> = Method::new(
+    "policy.route_model",
+    &[C::ModelRouter],
+    &[S::Routing],
+    decode_metadata,
+    encode_metadata,
+);
+pub const SCHEDULE_ACCOUNT: Method<
+    policy::AccountScheduleRequest,
+    policy::AccountScheduleDecision,
+> = Method::new(
+    "policy.schedule_account",
+    &[C::Scheduler],
+    &[S::Scheduling],
+    decode_metadata_without_payload,
+    encode_metadata,
+);
+pub const OBSERVE_REQUEST: Method<policy::ObserveRequest, Empty> = Method::new(
+    "policy.observe_request",
+    &[C::RequestLifecycle, C::Usage],
+    &[S::Observation],
+    decode_payload,
+    encode_metadata,
+);
+pub const OBSERVE_WEBSOCKET: Method<observation::ObserveWebSocketResponse, Empty> = Method::new(
+    "websocket.response_event",
+    &[C::WebSocketObserver],
+    &[S::Observation],
+    decode_metadata,
+    encode_metadata,
+);
+pub const FRONTEND_IDENTIFIER: Method<Empty, frontend::FrontendAuthenticationIdentifier> =
+    Method::new(
+        "frontend_auth.identifier",
+        &[C::FrontendAuthentication],
+        &[S::Registration],
+        decode_metadata_without_payload,
+        encode_metadata,
+    );
+pub const FRONTEND_AUTHENTICATE: Method<
+    frontend::FrontendAuthenticationRequest,
+    frontend::FrontendAuthenticationResult,
+> = Method::new(
+    "frontend_auth.authenticate",
+    &[C::FrontendAuthentication],
+    &[S::Authentication],
+    decode_payload,
+    encode_payload,
+);
+pub const STATE_MIGRATE: Method<host::StateMigrationRequest, host::StateMigrationResult> =
+    Method::new(
+        "plugin.state.migrate",
+        &[],
+        &[S::Configuration],
+        decode_payload,
+        encode_payload,
+    );
+
+pub const PREPARE_EXECUTION: Method<provider::ExecutionInput, provider::PreparedExecution> =
+    Method::new(
+        "provider.prepare",
+        &[C::Executor],
+        &[S::Attempt],
+        decode_execution_input,
+        encode_metadata,
+    );
+pub const EXECUTE: Method<provider::ExecutePrepared, Empty> = Method::new(
+    "provider.execute",
+    &[C::Executor],
+    &[S::Execution],
+    decode_metadata_without_payload,
+    encode_execution_stream,
+);
+pub const DISCARD_EXECUTION: Method<provider::ExecutePrepared, Empty> = Method::new(
+    "provider.discard",
+    &[C::Executor],
+    &[S::Attempt],
+    decode_metadata_without_payload,
+    encode_metadata,
+);
+pub const CONNECTION_TEST: Method<ConnectionTest, provider::ProbeOperation> = Method::new(
+    "provider.connection_test",
+    &[C::Executor],
+    &[S::Configuration],
+    decode_metadata_without_payload,
+    encode_metadata,
+);
+pub const MODELS: Method<provider::account::AccountRequest, provider::models::AccountModels> =
+    Method::new(
+        "provider.models",
+        &[C::Models],
+        &[S::Management, S::Maintenance],
+        decode_payload,
+        encode_payload,
+    );
+pub const QUOTA: Method<provider::account::AccountRequest, provider::quota::Quota> = Method::new(
+    "provider.quota",
+    &[C::Quota],
+    &[S::Management, S::Maintenance],
+    decode_payload,
+    encode_payload,
+);
+pub const IMPORT_CREDENTIALS: Method<Map<String, Value>, auth::ImportedCredentials> = Method::new(
+    "provider.credentials.import",
+    &[C::Authentication],
+    &[S::Management],
+    decode_payload,
+    encode_payload,
+);
+pub const EXPORT_CREDENTIALS: Method<Vec<auth::ExportCredential>, Map<String, Value>> = Method::new(
+    "provider.credentials.export",
+    &[C::Authentication],
+    &[S::Management],
+    decode_payload,
+    encode_payload,
+);
+pub const ROTATE_CREDENTIALS: Method<auth::RotateCredential, auth::CredentialFacts> = Method::new(
+    "provider.credentials.rotate",
+    &[C::Authentication],
+    &[S::Management],
+    decode_payload,
+    encode_payload,
+);
+pub const REFRESH_CREDENTIALS: Method<auth::RotateCredential, auth::CredentialFacts> = Method::new(
+    "provider.credentials.refresh",
+    &[C::Authentication],
+    &[S::Management, S::Maintenance],
+    decode_payload,
+    encode_payload,
+);
+pub const LOGIN_START: Method<auth::LoginStart, auth::LoginStarted> = Method::new(
+    "provider.login.start",
+    &[C::Authentication],
+    &[S::Management],
+    decode_payload,
+    encode_payload,
+);
+pub const LOGIN_POLL: Method<auth::LoginPoll, auth::LoginPollResult> = Method::new(
+    "provider.login.poll",
+    &[C::Authentication],
+    &[S::Management],
+    decode_payload,
+    encode_payload,
+);
+pub const ACCOUNT_CONFIGURATION: Method<
+    provider::account::AccountRequest,
+    provider::account::AccountConfiguration,
+> = Method::new(
+    "provider.account_configuration",
+    &[C::Authentication],
+    &[S::Configuration],
+    decode_payload,
+    encode_payload,
+);
+pub const ACCOUNT_CHANGED: Method<provider::account::AccountInvalidation, Empty> = Method::new(
+    "provider.account_changed",
+    &[C::AccountManagement],
+    &[S::Observation],
+    decode_payload,
+    encode_metadata,
+);
+pub const PROFILE: Method<provider::account::AccountRequest, provider::account::Profile> =
+    Method::new(
+        "provider.profile",
+        &[C::AccountManagement],
+        &[S::Management],
+        decode_payload,
+        encode_payload,
+    );
+pub const SUBSCRIPTION: Method<
+    provider::account::AccountRequest,
+    Option<provider::account::Subscription>,
+> = Method::new(
+    "provider.subscription",
+    &[C::AccountManagement],
+    &[S::Management],
+    decode_payload,
+    encode_payload,
+);
+pub const AVATAR: Method<provider::account::AccountRequest, provider::account::Avatar> =
+    Method::new(
+        "provider.avatar",
+        &[C::AccountManagement],
+        &[S::Management],
+        decode_payload,
+        encode_metadata_stream,
+    );
+pub const RESET_CREDITS: Method<
+    provider::account::AccountRequest,
+    provider::reset_credits::Reply<provider::reset_credits::Credits>,
+> = Method::new(
+    "provider.reset_credits",
+    &[C::AccountManagement],
+    &[S::Management],
+    decode_payload,
+    encode_payload,
+);
+pub const CONSUME_RESET_CREDIT: Method<
+    provider::reset_credits::ConsumeRequest,
+    provider::reset_credits::Reply<provider::reset_credits::ConsumeResult>,
+> = Method::new(
+    "provider.consume_reset_credit",
+    &[C::AccountManagement],
+    &[S::Management],
+    decode_payload,
+    encode_payload,
+);
+pub const REFRESH_REQUEST_PROFILES: Method<Empty, provider::RequestProfileRefresh> = Method::new(
+    "provider.request_profiles.refresh",
+    &[C::RequestProfile],
+    &[S::Maintenance],
+    decode_payload,
+    encode_payload,
+);
+
+/// 宿主连接测试的非敏感业务参数。
+#[derive(Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ConnectionTest {
+    pub model: String,
+    pub input: String,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/client/plugin/mod.rs b/backend/crates/gateway-plugin/sdk/src/client/plugin/mod.rs
new file mode 100644
index 000000000..b8d27562d
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/client/plugin/mod.rs
@@ -0,0 +1,249 @@
+//! 可组合的类型化作者入口，注册事实始终来自同一份规范化清单。
+
+pub mod methods;
+mod typed;
+mod validation;
+
+use std::{collections::BTreeMap, future::Future, sync::Arc};
+
+use crate::{
+    Capability, ErrorCode, Manifest, PluginFault, Stage,
+    call::{
+        management::{
+            CommandInvocation, CommandRegistration, CommandResult, ManagementRegistration,
+            ManagementRequest, ManagementResponse,
+        },
+        provider::{ProviderDescriptor, Registration},
+    },
+};
+
+use super::{CallFuture, CallReply, MiddlewareCall, MiddlewareResponse, PluginCall, PluginHandler};
+
+pub use typed::{Empty, Method, TypedCall, TypedReply};
+
+type Handler = Arc<dyn Fn(PluginCall) -> CallFuture<'static> + Send + Sync>;
+
+/// 作者配置错误只包含方法与能力标识，不输出清单中的敏感业务数据。
+#[derive(Debug, thiserror::Error)]
+pub enum AuthorError {
+    #[error("plugin author manifest is invalid: {0}")]
+    Manifest(#[from] crate::ManifestError),
+    #[error("plugin method is duplicated or not declared: {0}")]
+    Method(&'static str),
+    #[error("plugin method is required: {0}")]
+    MissingMethod(&'static str),
+    #[error("plugin provider descriptor does not match the declared capabilities")]
+    Provider,
+}
+
+/// 从作者清单组合处理器；不手写 `plugin.register` 或复制宿主握手的能力。
+pub struct PluginBuilder {
+    manifest: Manifest,
+    provider: Option<ProviderDescriptor>,
+    handlers: BTreeMap<&'static str, Handler>,
+}
+
+impl PluginBuilder {
+    /// 读取与 `cpr-plugin package --manifest` 相同的作者清单。
+    ///
+    /// # Errors
+    ///
+    /// 作者清单无效、含构建元数据或未显式选择中间件阶段时失败。
+    pub fn from_json(source: &[u8]) -> Result<Self, AuthorError> {
+        Self::from_manifest(Manifest::from_author_slice(source)?)
+    }
+
+    /// 使用已经规范化的清单。通常优先使用 `from_json(include_bytes!(...))`。
+    ///
+    /// # Errors
+    ///
+    /// 清单校验失败时返回错误。
+    pub fn from_manifest(manifest: Manifest) -> Result<Self, AuthorError> {
+        manifest.validate()?;
+        Ok(Self {
+            manifest,
+            provider: None,
+            handlers: BTreeMap::new(),
+        })
+    }
+
+    /// 配置一个 Provider 业务组；注册由 SDK 生成，不另写注册分支。
+    #[must_use]
+    pub fn provider(mut self, descriptor: ProviderDescriptor) -> Self {
+        self.provider = Some(descriptor);
+        self
+    }
+
+    /// 注册 SDK 定义的类型化方法，参数／载荷编码由方法合同决定。
+    ///
+    /// # Errors
+    ///
+    /// 重复注册或对应能力未在作者清单声明时失败。
+    pub fn on<P, R, F, Fut>(mut self, method: Method<P, R>, handler: F) -> Result<Self, AuthorError>
+    where
+        P: Send + 'static,
+        R: Send + 'static,
+        F: Fn(TypedCall<P>) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = Result<TypedReply<R>, PluginFault>> + Send + 'static,
+    {
+        let declared = if method.capabilities.is_empty() {
+            method.name == methods::STATE_MIGRATE.name
+                && self
+                    .manifest
+                    .state
+                    .iter()
+                    .any(|namespace| !namespace.migrates_from.is_empty())
+        } else {
+            method
+                .capabilities
+                .iter()
+                .any(|capability| self.manifest.contributes.contains_key(capability))
+        };
+        if !declared {
+            return Err(AuthorError::Method(method.name));
+        }
+        let handler = Arc::new(handler);
+        self.insert(
+            method.name,
+            Arc::new(move |call| {
+                let handler = Arc::clone(&handler);
+                Box::pin(async move {
+                    let call = (method.decode)(call, method.stages)?;
+                    (method.encode)(handler(call).await?)
+                })
+            }),
+        )?;
+        Ok(self)
+    }
+
+    /// 组合洋葱中间件，沿用 single-use next 与惰性正文，不建立另一套流式机制。
+    ///
+    /// # Errors
+    ///
+    /// 未声明中间件或重复注册时失败。
+    pub fn middleware<F, Fut>(mut self, handler: F) -> Result<Self, AuthorError>
+    where
+        F: Fn(MiddlewareCall) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = Result<MiddlewareResponse, PluginFault>> + Send + 'static,
+    {
+        let declaration = self
+            .manifest
+            .contributes
+            .get(&Capability::Middleware)
+            .ok_or(AuthorError::Method(crate::call::middleware::HANDLE_METHOD))?;
+        let stages = declaration.stages.clone();
+        let handler = Arc::new(handler);
+        self.insert(
+            crate::call::middleware::HANDLE_METHOD,
+            Arc::new(move |call| {
+                let handler = Arc::clone(&handler);
+                let allowed = stages.contains(&call.context.stage);
+                Box::pin(async move {
+                    if !allowed {
+                        return Err(typed::invalid_input());
+                    }
+                    handler(MiddlewareCall::try_from(call)?).await?.into_reply()
+                })
+            }),
+        )?;
+        Ok(self)
+    }
+
+    /// 冻结管理页面／路由描述并绑定类型化业务函数。
+    ///
+    /// # Errors
+    ///
+    /// 未声明管理能力或重复注册时失败。
+    pub fn management<F, Fut>(
+        self,
+        registration: ManagementRegistration,
+        handler: F,
+    ) -> Result<Self, AuthorError>
+    where
+        F: Fn(TypedCall<ManagementRequest>) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = Result<TypedReply<ManagementResponse>, PluginFault>> + Send + 'static,
+    {
+        self.on(methods::MANAGEMENT_REGISTER, move |_| {
+            let registration = registration.clone();
+            async move { Ok(TypedReply::new(registration)) }
+        })?
+        .on(methods::MANAGEMENT_HANDLE, handler)
+    }
+
+    /// 冻结命令帮助并绑定类型化命令执行函数。
+    ///
+    /// # Errors
+    ///
+    /// 未声明命令行能力或重复注册时失败。
+    pub fn command_line<F, Fut>(
+        self,
+        registration: CommandRegistration,
+        handler: F,
+    ) -> Result<Self, AuthorError>
+    where
+        F: Fn(TypedCall<CommandInvocation>) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = Result<TypedReply<CommandResult>, PluginFault>> + Send + 'static,
+    {
+        self.on(methods::COMMAND_LINE_REGISTER, move |_| {
+            let registration = registration.clone();
+            async move { Ok(TypedReply::new(registration)) }
+        })?
+        .on(methods::COMMAND_LINE_EXECUTE, handler)
+    }
+
+    /// 检查声明与实际处理器后生成可交给 `PluginSession::run` 的插件。
+    ///
+    /// # Errors
+    ///
+    /// 声明缺少处理器，或 Provider 的功能描述与能力不一致时失败。
+    pub fn build(self) -> Result<ComposedPlugin, AuthorError> {
+        validation::validate(&self.manifest, self.provider.as_ref(), &self.handlers)?;
+        Ok(ComposedPlugin {
+            registration: Registration {
+                contributes: self.manifest.contributes,
+                provider: self.provider,
+            },
+            handlers: self.handlers,
+        })
+    }
+
+    fn insert(&mut self, method: &'static str, handler: Handler) -> Result<(), AuthorError> {
+        if self.handlers.contains_key(method) {
+            return Err(AuthorError::Method(method));
+        }
+        self.handlers.insert(method, handler);
+        Ok(())
+    }
+}
+
+/// 已校验的业务处理器集合；会话仍负责取消、回调和流控。
+pub struct ComposedPlugin {
+    registration: Registration,
+    handlers: BTreeMap<&'static str, Handler>,
+}
+
+impl PluginHandler for ComposedPlugin {
+    fn call(&self, call: PluginCall) -> CallFuture<'_> {
+        Box::pin(async move {
+            if call.method == "plugin.register" {
+                if call.context.stage != Stage::Registration
+                    || !call.payload.is_empty()
+                    || !call
+                        .params
+                        .as_object()
+                        .is_some_and(serde_json::Map::is_empty)
+                {
+                    return Err(typed::invalid_input());
+                }
+                return Ok(CallReply::unary(
+                    serde_json::to_value(&self.registration).map_err(|_| typed::invalid_input())?,
+                    Vec::new(),
+                ));
+            }
+            let handler = self.handlers.get(call.method.as_str()).ok_or_else(|| {
+                PluginFault::new(ErrorCode::Unsupported, "plugin method is not supported")
+            })?;
+            handler(call).await
+        })
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/client/plugin/typed.rs b/backend/crates/gateway-plugin/sdk/src/client/plugin/typed.rs
new file mode 100644
index 000000000..b391decbe
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/client/plugin/typed.rs
@@ -0,0 +1,251 @@
+use std::marker::PhantomData;
+
+use serde::{Deserialize, Serialize, de::DeserializeOwned};
+
+use crate::{
+    CallContext, Capability, ErrorCode, PluginFault, Stage, call::provider::ExecutionInput,
+};
+
+use super::super::{CallCancellation, CallReply, HostClient, PluginCall, ResponseStream};
+
+/// RPC 的空控制对象，不使用会编码为 `null` 的 Rust 单元类型。
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Empty {}
+
+pub(super) type Decoder<P> = fn(PluginCall, &'static [Stage]) -> Result<TypedCall<P>, PluginFault>;
+pub(super) type Encoder<R> = fn(TypedReply<R>) -> Result<CallReply, PluginFault>;
+
+/// SDK 方法标识与请求／响应类型；只能使用 [`super::methods`] 中的合同常量。
+pub struct Method<P, R> {
+    pub(super) name: &'static str,
+    pub(super) capabilities: &'static [Capability],
+    pub(super) stages: &'static [Stage],
+    pub(super) decode: Decoder<P>,
+    pub(super) encode: Encoder<R>,
+    marker: PhantomData<fn(P) -> R>,
+}
+
+impl<P, R> Copy for Method<P, R> {}
+
+impl<P, R> Clone for Method<P, R> {
+    fn clone(&self) -> Self {
+        *self
+    }
+}
+
+impl<P, R> Method<P, R> {
+    pub(super) const fn new(
+        name: &'static str,
+        capabilities: &'static [Capability],
+        stages: &'static [Stage],
+        decode: Decoder<P>,
+        encode: Encoder<R>,
+    ) -> Self {
+        Self {
+            name,
+            capabilities,
+            stages,
+            decode,
+            encode,
+            marker: PhantomData,
+        }
+    }
+}
+
+/// 业务请求、宿主上下文与当前父调用内的服务句柄；不实现内容型 `Debug`。
+pub struct TypedCall<P> {
+    pub request: P,
+    /// 只有合同明确保留原始正文的方法才会在此提供字节。
+    pub payload: Vec<u8>,
+    pub context: CallContext,
+    pub host: HostClient,
+    pub cancellation: CallCancellation,
+}
+
+/// 类型化结果，可复用现有有界响应流；敏感 JSON 按方法合同写入二进制载荷。
+pub struct TypedReply<R> {
+    pub result: R,
+    pub payload: Vec<u8>,
+    pub stream: Option<ResponseStream>,
+}
+
+impl<R> TypedReply<R> {
+    #[must_use]
+    pub const fn new(result: R) -> Self {
+        Self {
+            result,
+            payload: Vec::new(),
+            stream: None,
+        }
+    }
+
+    #[must_use]
+    pub fn with_payload(mut self, payload: Vec<u8>) -> Self {
+        self.payload = payload;
+        self
+    }
+
+    #[must_use]
+    pub fn with_stream(mut self, stream: ResponseStream) -> Self {
+        self.stream = Some(stream);
+        self
+    }
+}
+
+pub(super) fn decode_metadata<P: DeserializeOwned>(
+    mut call: PluginCall,
+    stages: &'static [Stage],
+) -> Result<TypedCall<P>, PluginFault> {
+    validate_stage(&call, stages)?;
+    let request =
+        serde_json::from_value(std::mem::take(&mut call.params)).map_err(|_| invalid_input())?;
+    Ok(typed_call(call, request, true))
+}
+
+pub(super) fn decode_metadata_without_payload<P: DeserializeOwned>(
+    mut call: PluginCall,
+    stages: &'static [Stage],
+) -> Result<TypedCall<P>, PluginFault> {
+    validate_stage(&call, stages)?;
+    if !call.payload.is_empty() {
+        return Err(invalid_input());
+    }
+    let request =
+        serde_json::from_value(std::mem::take(&mut call.params)).map_err(|_| invalid_input())?;
+    Ok(typed_call(call, request, false))
+}
+
+pub(super) fn decode_payload<P: DeserializeOwned>(
+    call: PluginCall,
+    stages: &'static [Stage],
+) -> Result<TypedCall<P>, PluginFault> {
+    validate_stage(&call, stages)?;
+    if !empty_object(&call.params) {
+        return Err(invalid_input());
+    }
+    let request = serde_json::from_slice(&call.payload).map_err(|_| invalid_input())?;
+    Ok(typed_call(call, request, false))
+}
+
+pub(super) fn decode_execution_input(
+    call: PluginCall,
+    stages: &'static [Stage],
+) -> Result<TypedCall<ExecutionInput>, PluginFault> {
+    validate_stage(&call, stages)?;
+    if !empty_object(&call.params) {
+        return Err(invalid_input());
+    }
+    let request = ExecutionInput::decode(&call.payload).map_err(|_| invalid_input())?;
+    Ok(typed_call(call, request, false))
+}
+
+pub(super) fn encode_metadata<R: Serialize>(
+    reply: TypedReply<R>,
+) -> Result<CallReply, PluginFault> {
+    let TypedReply {
+        result,
+        payload,
+        stream,
+    } = reply;
+    if !payload.is_empty() || stream.is_some() {
+        return Err(invalid_input());
+    }
+    let result = serde_json::to_value(result).map_err(|_| invalid_input())?;
+    Ok(CallReply::unary(result, Vec::new()))
+}
+
+pub(super) fn encode_metadata_with_payload<R: Serialize>(
+    reply: TypedReply<R>,
+) -> Result<CallReply, PluginFault> {
+    let TypedReply {
+        result,
+        payload,
+        stream,
+    } = reply;
+    if stream.is_some() {
+        return Err(invalid_input());
+    }
+    let result = serde_json::to_value(result).map_err(|_| invalid_input())?;
+    Ok(CallReply::unary(result, payload))
+}
+
+pub(super) fn encode_payload<R: Serialize>(reply: TypedReply<R>) -> Result<CallReply, PluginFault> {
+    let TypedReply {
+        result,
+        payload,
+        stream,
+    } = reply;
+    if !payload.is_empty() || stream.is_some() {
+        return Err(invalid_input());
+    }
+    let payload = serde_json::to_vec(&result).map_err(|_| invalid_input())?;
+    Ok(CallReply::unary(serde_json::json!({}), payload))
+}
+
+pub(super) fn encode_metadata_stream<R: Serialize>(
+    reply: TypedReply<R>,
+) -> Result<CallReply, PluginFault> {
+    let TypedReply {
+        result,
+        payload,
+        stream,
+    } = reply;
+    if !payload.is_empty() {
+        return Err(invalid_input());
+    }
+    let stream = stream.ok_or_else(invalid_input)?;
+    let result = serde_json::to_value(result).map_err(|_| invalid_input())?;
+    Ok(CallReply::stream(result, Vec::new(), stream))
+}
+
+pub(super) fn encode_execution_stream(reply: TypedReply<Empty>) -> Result<CallReply, PluginFault> {
+    let TypedReply {
+        result: _,
+        payload,
+        stream,
+    } = reply;
+    if !payload.is_empty() {
+        return Err(invalid_input());
+    }
+    let stream = stream.ok_or_else(invalid_input)?;
+    Ok(CallReply::stream(
+        serde_json::json!({"stream": true}),
+        Vec::new(),
+        stream,
+    ))
+}
+
+fn typed_call<P>(mut call: PluginCall, request: P, keep_payload: bool) -> TypedCall<P> {
+    let payload = if keep_payload {
+        std::mem::take(&mut call.payload)
+    } else {
+        Vec::new()
+    };
+    TypedCall {
+        request,
+        payload,
+        context: call.context,
+        host: call.host,
+        cancellation: call.cancellation,
+    }
+}
+
+fn validate_stage(call: &PluginCall, stages: &[Stage]) -> Result<(), PluginFault> {
+    if stages.contains(&call.context.stage) {
+        Ok(())
+    } else {
+        Err(invalid_input())
+    }
+}
+
+fn empty_object(value: &serde_json::Value) -> bool {
+    value.as_object().is_some_and(serde_json::Map::is_empty)
+}
+
+pub(super) fn invalid_input() -> PluginFault {
+    PluginFault::new(
+        ErrorCode::InvalidInput,
+        "plugin typed method input or result is invalid",
+    )
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/client/plugin/validation.rs b/backend/crates/gateway-plugin/sdk/src/client/plugin/validation.rs
new file mode 100644
index 000000000..d93b7650f
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/client/plugin/validation.rs
@@ -0,0 +1,178 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use crate::{
+    Capability as C, Manifest,
+    call::{
+        auth::CredentialOperation,
+        provider::{ProviderDescriptor, account::AccountOperation},
+    },
+};
+
+use super::{AuthorError, Handler, methods};
+
+pub(super) fn validate(
+    manifest: &Manifest,
+    provider: Option<&ProviderDescriptor>,
+    handlers: &BTreeMap<&'static str, Handler>,
+) -> Result<(), AuthorError> {
+    let required = |method| {
+        handlers
+            .contains_key(method)
+            .then_some(())
+            .ok_or(AuthorError::MissingMethod(method))
+    };
+    let matches_handler = |method, expected| match (handlers.contains_key(method), expected) {
+        (true, true) | (false, false) => Ok(()),
+        (false, true) => Err(AuthorError::MissingMethod(method)),
+        (true, false) => Err(AuthorError::Provider),
+    };
+    let has = |capability| manifest.contributes.contains_key(&capability);
+
+    for capability in manifest.contributes.keys() {
+        match capability {
+            C::Middleware => required(crate::call::middleware::HANDLE_METHOD)?,
+            C::ModelRouter => required(methods::ROUTE_MODEL.name)?,
+            C::Scheduler => required(methods::SCHEDULE_ACCOUNT.name)?,
+            C::RequestLifecycle | C::Usage => required(methods::OBSERVE_REQUEST.name)?,
+            C::WebSocketObserver => required(methods::OBSERVE_WEBSOCKET.name)?,
+            C::Management => {
+                required(methods::MANAGEMENT_REGISTER.name)?;
+                required(methods::MANAGEMENT_HANDLE.name)?;
+            }
+            C::CommandLine => {
+                required(methods::COMMAND_LINE_REGISTER.name)?;
+                required(methods::COMMAND_LINE_EXECUTE.name)?;
+            }
+            C::FrontendAuthentication => {
+                required(methods::FRONTEND_IDENTIFIER.name)?;
+                required(methods::FRONTEND_AUTHENTICATE.name)?;
+            }
+            C::Executor => {
+                required(methods::PREPARE_EXECUTION.name)?;
+                required(methods::EXECUTE.name)?;
+                required(methods::DISCARD_EXECUTION.name)?;
+                required(methods::CONNECTION_TEST.name)?;
+            }
+            C::Models => required(methods::MODELS.name)?,
+            C::Quota => required(methods::QUOTA.name)?,
+            C::RequestProfile => required(methods::REFRESH_REQUEST_PROFILES.name)?,
+            C::Authentication | C::AccountManagement | C::Billing | C::Maintenance => {}
+        }
+    }
+    if manifest
+        .state
+        .iter()
+        .any(|namespace| !namespace.migrates_from.is_empty())
+    {
+        required(methods::STATE_MIGRATE.name)?;
+    }
+
+    let has_provider_capability = manifest.contributes.keys().any(|capability| {
+        matches!(
+            capability,
+            C::Models
+                | C::Authentication
+                | C::Executor
+                | C::Quota
+                | C::AccountManagement
+                | C::Billing
+                | C::RequestProfile
+                | C::Maintenance
+        )
+    });
+    if provider.is_some() != has(C::Executor) || provider.is_none() && has_provider_capability {
+        return Err(AuthorError::Provider);
+    }
+    let Some(provider) = provider else {
+        return Ok(());
+    };
+    validate_provider(provider, &has, &matches_handler)
+}
+
+fn validate_provider(
+    provider: &ProviderDescriptor,
+    has: &impl Fn(C) -> bool,
+    matches_handler: &impl Fn(&'static str, bool) -> Result<(), AuthorError>,
+) -> Result<(), AuthorError> {
+    let credential_operations = provider
+        .credential_operations
+        .iter()
+        .copied()
+        .collect::<BTreeSet<_>>();
+    let account_operations = provider
+        .account_operations
+        .iter()
+        .copied()
+        .collect::<BTreeSet<_>>();
+    let supports_maintenance = credential_operations.contains(&CredentialOperation::Refresh)
+        || has(C::Quota)
+        || has(C::Models)
+        || has(C::RequestProfile);
+    if provider.id.trim().is_empty()
+        || credential_operations.len() != provider.credential_operations.len()
+        || account_operations.len() != provider.account_operations.len()
+        || credential_operations.is_empty() == has(C::Authentication)
+        || account_operations.is_empty() == has(C::AccountManagement)
+        || provider.billing.is_some() != has(C::Billing)
+        || provider.model_discovery.is_some() != has(C::Models)
+        || has(C::RequestProfile) && provider.request_profiles.is_none()
+        || has(C::Maintenance) && !supports_maintenance
+        || provider
+            .credential_input_schemas
+            .keys()
+            .any(|operation| !credential_operations.contains(operation))
+        || provider.account_configuration.is_some()
+            && !credential_operations.contains(&CredentialOperation::Rotate)
+    {
+        return Err(AuthorError::Provider);
+    }
+
+    matches_handler(
+        methods::ACCOUNT_CONFIGURATION.name,
+        provider.account_configuration.is_some(),
+    )?;
+    matches_handler(
+        methods::IMPORT_CREDENTIALS.name,
+        credential_operations.contains(&CredentialOperation::Import),
+    )?;
+    matches_handler(
+        methods::EXPORT_CREDENTIALS.name,
+        credential_operations.contains(&CredentialOperation::Export),
+    )?;
+    matches_handler(
+        methods::ROTATE_CREDENTIALS.name,
+        credential_operations.contains(&CredentialOperation::Rotate),
+    )?;
+    matches_handler(
+        methods::REFRESH_CREDENTIALS.name,
+        credential_operations.contains(&CredentialOperation::Refresh),
+    )?;
+    let login = credential_operations.contains(&CredentialOperation::Login);
+    matches_handler(methods::LOGIN_START.name, login)?;
+    matches_handler(methods::LOGIN_POLL.name, login)?;
+
+    let invalidation = account_operations.contains(&AccountOperation::Unavailable)
+        || account_operations.contains(&AccountOperation::FactsChanged);
+    matches_handler(methods::ACCOUNT_CHANGED.name, invalidation)?;
+    matches_handler(
+        methods::PROFILE.name,
+        account_operations.contains(&AccountOperation::Profile),
+    )?;
+    matches_handler(
+        methods::SUBSCRIPTION.name,
+        account_operations.contains(&AccountOperation::Subscription),
+    )?;
+    matches_handler(
+        methods::AVATAR.name,
+        account_operations.contains(&AccountOperation::Avatar),
+    )?;
+    matches_handler(
+        methods::RESET_CREDITS.name,
+        account_operations.contains(&AccountOperation::ResetCredits),
+    )?;
+    matches_handler(
+        methods::CONSUME_RESET_CREDIT.name,
+        account_operations.contains(&AccountOperation::ConsumeResetCredit),
+    )?;
+    Ok(())
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/client/session.rs b/backend/crates/gateway-plugin/sdk/src/client/session.rs
new file mode 100644
index 000000000..ecd5db823
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/client/session.rs
@@ -0,0 +1,1448 @@
+use std::{
+    collections::{BTreeMap, BTreeSet, VecDeque},
+    future::Future,
+    num::NonZeroUsize,
+    pin::Pin,
+    sync::{Arc, Mutex},
+    time::Duration,
+};
+
+use serde_json::Value;
+use tokio::{
+    io::{AsyncRead, AsyncWrite},
+    sync::{OwnedSemaphorePermit, Semaphore, mpsc, oneshot, watch},
+    task::JoinHandle,
+    time::Instant,
+};
+
+use crate::{
+    CallContext, ErrorCode, Frame, FrameError, Handshake, Message, PROTOCOL_VERSION, PluginFault,
+};
+
+use super::frame::{read_frame, validate_frame, validate_message, write_frame};
+
+const MAXIMUM_FRAME_BYTES: usize = 16 * 1024 * 1024;
+const MAXIMUM_CONCURRENCY: usize = 256;
+const MAXIMUM_BUFFERED_STREAM_CHUNKS: usize = 65_536;
+
+/// 插件侧会话的内存、并发与期限边界。
+#[derive(Debug, Clone, Copy)]
+pub struct SessionConfig {
+    pub maximum_frame_bytes: usize,
+    pub maximum_calls: usize,
+    pub maximum_callbacks: usize,
+    pub maximum_buffered_stream_chunks: usize,
+    pub handshake_timeout: Duration,
+    pub maximum_call_timeout: Duration,
+}
+
+impl Default for SessionConfig {
+    fn default() -> Self {
+        Self {
+            // 与宿主默认帧预算一致，避免正文回调以本地较大上限申请后被拒绝。
+            maximum_frame_bytes: 1024 * 1024,
+            maximum_calls: 32,
+            maximum_callbacks: 32,
+            maximum_buffered_stream_chunks: 1_024,
+            handshake_timeout: Duration::from_secs(5),
+            maximum_call_timeout: Duration::from_secs(120),
+        }
+    }
+}
+
+impl SessionConfig {
+    fn validate(self) -> Result<Self, SessionError> {
+        if self.maximum_frame_bytes < 1_024
+            || self.maximum_frame_bytes > MAXIMUM_FRAME_BYTES
+            || self.maximum_calls == 0
+            || self.maximum_calls > MAXIMUM_CONCURRENCY
+            || self.maximum_callbacks == 0
+            || self.maximum_callbacks > MAXIMUM_CONCURRENCY
+            || self.maximum_buffered_stream_chunks == 0
+            || self.maximum_buffered_stream_chunks > MAXIMUM_BUFFERED_STREAM_CHUNKS
+            || self.handshake_timeout.is_zero()
+            || self.maximum_call_timeout.is_zero()
+        {
+            return Err(SessionError::Configuration);
+        }
+        Ok(self)
+    }
+}
+
+/// 插件侧传输和会话错误。
+#[derive(Debug, thiserror::Error)]
+pub enum SessionError {
+    #[error("plugin session configuration is invalid")]
+    Configuration,
+    #[error("plugin handshake is invalid")]
+    Handshake,
+    #[error("plugin protocol is invalid")]
+    Protocol,
+    #[error("plugin transport is closed")]
+    Closed,
+    #[error("plugin operation exceeded its deadline")]
+    Timeout,
+    #[error("plugin call was cancelled")]
+    Cancelled,
+    #[error("plugin session capacity is exhausted")]
+    Capacity,
+    #[error("plugin handler stopped unexpectedly")]
+    HandlerStopped,
+    #[error("host callback returned an error: {0:?}")]
+    Remote(PluginFault),
+    #[error(transparent)]
+    Frame(#[from] FrameError),
+}
+
+impl SessionError {
+    /// 将本地会话失败收敛为可返回宿主的稳定插件错误。
+    #[must_use]
+    pub fn into_plugin_fault(self) -> PluginFault {
+        match self {
+            Self::Remote(fault) => fault,
+            Self::Timeout => PluginFault::new(ErrorCode::Timeout, "host callback timed out"),
+            Self::Cancelled => PluginFault::new(ErrorCode::Cancelled, "parent call was cancelled"),
+            Self::Capacity => PluginFault::new(ErrorCode::Capacity, "plugin capacity is exhausted"),
+            Self::Configuration | Self::Protocol | Self::Handshake | Self::Frame(_) => {
+                PluginFault::new(ErrorCode::InvalidInput, "plugin session input is invalid")
+            }
+            Self::Closed | Self::HandlerStopped => {
+                PluginFault::new(ErrorCode::Fault, "plugin session is unavailable")
+            }
+        }
+    }
+}
+
+/// 一次宿主调用的可克隆取消信号。
+#[derive(Clone)]
+pub struct CallCancellation {
+    receiver: watch::Receiver<bool>,
+}
+
+impl CallCancellation {
+    #[must_use]
+    pub fn is_cancelled(&self) -> bool {
+        *self.receiver.borrow()
+    }
+
+    pub async fn cancelled(&self) {
+        let mut receiver = self.receiver.clone();
+        if *receiver.borrow() {
+            return;
+        }
+        while receiver.changed().await.is_ok() {
+            if *receiver.borrow() {
+                return;
+            }
+        }
+    }
+}
+
+struct CancellationSource {
+    sender: watch::Sender<bool>,
+}
+
+impl CancellationSource {
+    fn new() -> (Self, CallCancellation) {
+        let (sender, receiver) = watch::channel(false);
+        (Self { sender }, CallCancellation { receiver })
+    }
+
+    fn cancel(&self) {
+        self.sender.send_replace(true);
+    }
+}
+
+/// 宿主回调的成功结果；不实现 `Debug`，避免载荷进入普通诊断。
+pub struct HostReply {
+    pub result: Value,
+    pub payload: Vec<u8>,
+}
+
+/// 绑定父调用、期限和取消信号的宿主回调客户端。
+#[derive(Clone)]
+pub struct HostClient {
+    parent_id: u64,
+    deadline: Instant,
+    cancellation: CallCancellation,
+    callbacks: Arc<CallbackRegistry>,
+    output: Output,
+    maximum_frame_bytes: usize,
+}
+
+impl HostClient {
+    pub(crate) const fn maximum_frame_bytes(&self) -> usize {
+        self.maximum_frame_bytes
+    }
+
+    /// 发起一次与父调用关联的宿主回调。
+    ///
+    /// # Errors
+    ///
+    /// 方法或帧无效、容量耗尽、父调用取消、期限到达、连接关闭或宿主返回错误时失败。
+    pub async fn call(
+        &self,
+        method: impl Into<String>,
+        params: Value,
+        payload: Vec<u8>,
+    ) -> Result<HostReply, SessionError> {
+        let method = method.into();
+        if method.is_empty() || method.len() > 128 {
+            return Err(SessionError::Protocol);
+        }
+        let ordered = self.callbacks.order.lock().await;
+        let (id, received) = self.callbacks.begin(self.parent_id)?;
+        let frame = Frame {
+            message: Message::Callback {
+                id,
+                parent_id: self.parent_id,
+                method,
+                params,
+            },
+            payload,
+        };
+        if validate_frame(&frame, self.maximum_frame_bytes).is_err() {
+            self.callbacks.retire(id);
+            return Err(SessionError::Protocol);
+        }
+        let sent = tokio::select! {
+            biased;
+            () = self.cancellation.cancelled() => Err(SessionError::Cancelled),
+            () = tokio::time::sleep_until(self.deadline) => Err(SessionError::Timeout),
+            result = self.output.send_data(frame) => result,
+        };
+        if let Err(error) = sent {
+            self.callbacks.retire(id);
+            return Err(error);
+        }
+        drop(ordered);
+        tokio::select! {
+            biased;
+            () = self.cancellation.cancelled() => {
+                self.callbacks.retire(id);
+                Err(SessionError::Cancelled)
+            }
+            () = tokio::time::sleep_until(self.deadline) => {
+                self.callbacks.retire(id);
+                Err(SessionError::Timeout)
+            }
+            result = received => result.map_err(|_| SessionError::Closed)?,
+        }
+    }
+}
+
+/// 交给插件业务处理器的一次宿主调用；不实现 `Debug`，避免敏感载荷泄露。
+pub struct PluginCall {
+    pub method: String,
+    pub context: CallContext,
+    pub params: Value,
+    pub payload: Vec<u8>,
+    pub host: HostClient,
+    pub cancellation: CallCancellation,
+}
+
+/// 插件业务调用 future。
+pub type CallFuture<'a> = Pin<Box<dyn Future<Output = Result<CallReply, PluginFault>> + Send + 'a>>;
+
+/// 插件只实现业务调用；会话负责握手、关联、流控、取消和关闭。
+pub trait PluginHandler: Send + Sync + 'static {
+    fn call(&self, call: PluginCall) -> CallFuture<'_>;
+
+    /// 取消时释放只属于该调用的临时业务状态。实现必须幂等、快速且不得执行阻塞 I/O。
+    fn cancel(&self, _context: &CallContext) {}
+
+    /// 会话停止接收新调用时触发。实现必须幂等、快速且不得执行阻塞 I/O。
+    fn quiesce(&self) {}
+
+    /// 会话关闭时释放插件自有临时状态。实现必须幂等、快速且不得执行阻塞 I/O。
+    fn shutdown(&self) {}
+}
+
+/// 一次业务成功结果；`stream` 存在时 SDK 自动产生单一流终态。
+pub struct CallReply {
+    result: Value,
+    payload: Vec<u8>,
+    stream: Option<ResponseStream>,
+}
+
+impl CallReply {
+    #[must_use]
+    pub fn unary(result: Value, payload: Vec<u8>) -> Self {
+        Self {
+            result,
+            payload,
+            stream: None,
+        }
+    }
+
+    #[must_use]
+    pub fn stream(result: Value, payload: Vec<u8>, stream: ResponseStream) -> Self {
+        Self {
+            result,
+            payload,
+            stream: Some(stream),
+        }
+    }
+}
+
+enum StreamSource {
+    Buffered(VecDeque<Vec<u8>>),
+    Channel(mpsc::Receiver<Result<Vec<u8>, PluginFault>>),
+    Pull(Box<dyn PullResponseStream>),
+}
+
+pub(crate) type PullResponseFuture<'a> =
+    Pin<Box<dyn Future<Output = Option<Result<Vec<u8>, PluginFault>>> + Send + 'a>>;
+
+pub(crate) trait PullResponseStream: Send {
+    fn next(&mut self) -> PullResponseFuture<'_>;
+}
+
+/// SDK 管理 sequence、Credit 和终态的响应流。
+pub struct ResponseStream {
+    source: StreamSource,
+    declared_capacity: usize,
+}
+
+impl ResponseStream {
+    /// 从已完成业务校验的有限分块构造流；SDK 会在发送 `Result` 前预检全部分块。
+    #[must_use]
+    pub fn from_chunks(chunks: Vec<Vec<u8>>) -> Self {
+        let declared_capacity = chunks.len().max(1);
+        Self {
+            source: StreamSource::Buffered(chunks.into()),
+            declared_capacity,
+        }
+    }
+
+    /// 创建由生产者驱动的有界流队列。
+    #[must_use]
+    pub fn channel(capacity: NonZeroUsize) -> (StreamSender, Self) {
+        let (sender, receiver) = mpsc::channel(capacity.get());
+        (
+            StreamSender { sender },
+            Self {
+                source: StreamSource::Channel(receiver),
+                declared_capacity: capacity.get(),
+            },
+        )
+    }
+
+    pub(crate) fn pull(source: Box<dyn PullResponseStream>) -> Self {
+        Self {
+            source: StreamSource::Pull(source),
+            declared_capacity: 1,
+        }
+    }
+
+    fn validate_buffered(
+        &self,
+        maximum_chunks: usize,
+        maximum_frame_bytes: usize,
+        window_bytes: u64,
+    ) -> Result<(), PluginFault> {
+        if self.declared_capacity > maximum_chunks {
+            return Err(capacity_fault(
+                "response stream exceeds the local queue limit",
+            ));
+        }
+        if let StreamSource::Buffered(chunks) = &self.source {
+            for chunk in chunks {
+                validate_stream_chunk(chunk, maximum_frame_bytes, window_bytes)?;
+            }
+        }
+        Ok(())
+    }
+
+    async fn next(&mut self) -> Option<Result<Vec<u8>, PluginFault>> {
+        match &mut self.source {
+            StreamSource::Buffered(chunks) => chunks.pop_front().map(Ok),
+            StreamSource::Channel(receiver) => receiver.recv().await,
+            StreamSource::Pull(source) => source.next().await,
+        }
+    }
+}
+
+/// 动态响应流的有界生产端；最后一个 sender 被释放表示成功终态。
+#[derive(Clone)]
+pub struct StreamSender {
+    sender: mpsc::Sender<Result<Vec<u8>, PluginFault>>,
+}
+
+impl StreamSender {
+    /// 排队一个业务分块；实际线协议流控由会话完成。
+    pub async fn send(&self, payload: Vec<u8>) -> Result<(), SessionError> {
+        self.sender
+            .send(Ok(payload))
+            .await
+            .map_err(|_| SessionError::Closed)
+    }
+
+    /// 以业务错误结束动态流。
+    pub async fn fail(&self, fault: PluginFault) -> Result<(), SessionError> {
+        self.sender
+            .send(Err(fault))
+            .await
+            .map_err(|_| SessionError::Closed)
+    }
+}
+
+/// 已读取并校验 Hello、尚未向宿主发送 Ready 的插件会话。
+pub struct PluginSession<R, W> {
+    reader: R,
+    writer: W,
+    handshake: Handshake,
+    config: SessionConfig,
+}
+
+impl<R, W> PluginSession<R, W>
+where
+    R: AsyncRead + Unpin + Send + 'static,
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    /// 读取并校验宿主握手。业务处理器可以在 `run` 前读取不可变 Handshake 构造注册描述。
+    ///
+    /// # Errors
+    ///
+    /// 配置无效、握手超时、传输关闭或 Hello 不符合协议时失败。
+    pub async fn accept(
+        mut reader: R,
+        writer: W,
+        config: SessionConfig,
+    ) -> Result<Self, SessionError> {
+        let config = config.validate()?;
+        let frame = tokio::time::timeout(
+            config.handshake_timeout,
+            read_frame(&mut reader, config.maximum_frame_bytes),
+        )
+        .await
+        .map_err(|_| SessionError::Timeout)??;
+        let Message::Hello { handshake } = frame.message else {
+            return Err(SessionError::Handshake);
+        };
+        if !frame.payload.is_empty()
+            || handshake.protocol_version != PROTOCOL_VERSION
+            || handshake.plugin_id.is_empty()
+            || handshake.instance_id.is_empty()
+            || handshake.generation == 0
+            || handshake.incarnation.is_empty()
+        {
+            return Err(SessionError::Handshake);
+        }
+        Ok(Self {
+            reader,
+            writer,
+            handshake,
+            config,
+        })
+    }
+
+    #[must_use]
+    pub const fn handshake(&self) -> &Handshake {
+        &self.handshake
+    }
+
+    /// 发送 Ready 并持续处理调用、回调、流控、取消与关闭。
+    ///
+    /// # Errors
+    ///
+    /// 帧损坏、协议违规、处理器异常停止或传输关闭时失败。
+    pub async fn run<H>(mut self, handler: H) -> Result<(), SessionError>
+    where
+        H: PluginHandler,
+    {
+        let data_capacity = self
+            .config
+            .maximum_calls
+            .checked_add(self.config.maximum_callbacks)
+            .ok_or(SessionError::Configuration)?;
+        let control_reserve = self
+            .config
+            .maximum_calls
+            .checked_add(8)
+            .ok_or(SessionError::Configuration)?;
+        let queue_capacity = data_capacity
+            .checked_add(control_reserve)
+            .ok_or(SessionError::Configuration)?;
+        let (outbound, received) = mpsc::channel(queue_capacity);
+        let output = Output {
+            sender: outbound,
+            data_slots: Arc::new(Semaphore::new(data_capacity)),
+            maximum_frame_bytes: self.config.maximum_frame_bytes,
+        };
+        let callbacks = Arc::new(CallbackRegistry::new(self.config.maximum_callbacks));
+        let handler: Arc<dyn PluginHandler> = Arc::new(handler);
+        let lifecycle = LifecycleHooks::new(Arc::clone(&handler), control_reserve)?;
+        write_frame(
+            &mut self.writer,
+            &Frame::control(Message::Ready {
+                protocol_version: PROTOCOL_VERSION,
+                incarnation: self.handshake.incarnation.clone(),
+            }),
+            self.config.maximum_frame_bytes,
+        )
+        .await?;
+        let writer = tokio::spawn(writer_loop(
+            self.writer,
+            received,
+            self.config.maximum_frame_bytes,
+        ));
+        let (completed, completions) = mpsc::channel(self.config.maximum_calls);
+        let mut driver = SessionDriver {
+            config: self.config,
+            instance_id: self.handshake.instance_id,
+            generation: self.handshake.generation,
+            incarnation: self.handshake.incarnation,
+            output,
+            callbacks,
+            handler,
+            lifecycle,
+            writer,
+            completed,
+            completions,
+            active: BTreeMap::new(),
+            last_call: 0,
+            quiescing: false,
+        };
+        let result = driver.drive(self.reader).await;
+        driver.close().await;
+        result
+    }
+}
+
+struct Output {
+    sender: mpsc::Sender<Outbound>,
+    data_slots: Arc<Semaphore>,
+    maximum_frame_bytes: usize,
+}
+
+impl Clone for Output {
+    fn clone(&self) -> Self {
+        Self {
+            sender: self.sender.clone(),
+            data_slots: Arc::clone(&self.data_slots),
+            maximum_frame_bytes: self.maximum_frame_bytes,
+        }
+    }
+}
+
+impl Output {
+    async fn send_data(&self, frame: Frame) -> Result<(), SessionError> {
+        validate_frame(&frame, self.maximum_frame_bytes)?;
+        let permit = Arc::clone(&self.data_slots)
+            .acquire_owned()
+            .await
+            .map_err(|_| SessionError::Closed)?;
+        self.sender
+            .send(Outbound {
+                frame,
+                _data_slot: Some(permit),
+            })
+            .await
+            .map_err(|_| SessionError::Closed)
+    }
+
+    async fn send_data_until(
+        &self,
+        frame: Frame,
+        deadline: Instant,
+        cancellation: &CallCancellation,
+    ) -> Result<(), SessionError> {
+        tokio::select! {
+            biased;
+            () = cancellation.cancelled() => Err(SessionError::Cancelled),
+            () = tokio::time::sleep_until(deadline) => Err(SessionError::Timeout),
+            result = self.send_data(frame) => result,
+        }
+    }
+
+    fn send_control(&self, frame: Frame) -> Result<(), SessionError> {
+        validate_frame(&frame, self.maximum_frame_bytes)?;
+        self.sender
+            .try_send(Outbound {
+                frame,
+                _data_slot: None,
+            })
+            .map_err(|_| SessionError::Capacity)
+    }
+}
+
+struct Outbound {
+    frame: Frame,
+    _data_slot: Option<OwnedSemaphorePermit>,
+}
+
+async fn writer_loop<W: AsyncWrite + Unpin>(
+    mut writer: W,
+    mut received: mpsc::Receiver<Outbound>,
+    maximum_frame_bytes: usize,
+) -> Result<(), SessionError> {
+    while let Some(outbound) = received.recv().await {
+        write_frame(&mut writer, &outbound.frame, maximum_frame_bytes).await?;
+    }
+    Ok(())
+}
+
+struct CallbackRegistry {
+    state: Mutex<CallbackState>,
+    order: tokio::sync::Mutex<()>,
+    maximum: usize,
+    maximum_retired: usize,
+}
+
+struct CallbackState {
+    next_id: u64,
+    pending: BTreeMap<u64, PendingCallback>,
+    retired: BTreeSet<u64>,
+    retired_order: VecDeque<u64>,
+}
+
+struct PendingCallback {
+    parent_id: u64,
+    result: oneshot::Sender<Result<HostReply, SessionError>>,
+}
+
+impl CallbackRegistry {
+    fn new(maximum: usize) -> Self {
+        Self {
+            state: Mutex::new(CallbackState {
+                next_id: 2,
+                pending: BTreeMap::new(),
+                retired: BTreeSet::new(),
+                retired_order: VecDeque::new(),
+            }),
+            order: tokio::sync::Mutex::new(()),
+            maximum,
+            maximum_retired: maximum.saturating_mul(2),
+        }
+    }
+
+    fn begin(
+        &self,
+        parent_id: u64,
+    ) -> Result<(u64, oneshot::Receiver<Result<HostReply, SessionError>>), SessionError> {
+        let mut state = lock_unpoisoned(&self.state);
+        if state.pending.len() >= self.maximum {
+            return Err(SessionError::Capacity);
+        }
+        let id = state.next_id;
+        state.next_id = state.next_id.checked_add(2).ok_or(SessionError::Capacity)?;
+        let (result, received) = oneshot::channel();
+        state
+            .pending
+            .insert(id, PendingCallback { parent_id, result });
+        Ok((id, received))
+    }
+
+    fn resolve(&self, frame: Frame) -> Result<(), SessionError> {
+        let id = match &frame.message {
+            Message::Result { id, .. } | Message::Error { id, .. } => *id,
+            _ => return Err(SessionError::Protocol),
+        };
+        let pending = {
+            let mut state = lock_unpoisoned(&self.state);
+            if let Some(pending) = state.pending.remove(&id) {
+                Some(pending)
+            } else if state.retired.remove(&id) {
+                state.retired_order.retain(|retired| *retired != id);
+                None
+            } else {
+                return Err(SessionError::Protocol);
+            }
+        };
+        let Some(pending) = pending else {
+            return Ok(());
+        };
+        let result = match frame.message {
+            Message::Result { result, .. } => Ok(HostReply {
+                result,
+                payload: frame.payload,
+            }),
+            Message::Error { error, .. } if frame.payload.is_empty() => {
+                Err(SessionError::Remote(error))
+            }
+            _ => return Err(SessionError::Protocol),
+        };
+        let _ = pending.result.send(result);
+        Ok(())
+    }
+
+    fn retire(&self, id: u64) {
+        let mut state = lock_unpoisoned(&self.state);
+        if state.pending.remove(&id).is_some() {
+            retire_callback(&mut state, id, self.maximum_retired);
+        }
+    }
+
+    fn finish_parent(&self, parent_id: u64) {
+        let pending = {
+            let mut state = lock_unpoisoned(&self.state);
+            let mut remaining = BTreeMap::new();
+            let mut finished = Vec::new();
+            for (id, pending) in std::mem::take(&mut state.pending) {
+                if pending.parent_id == parent_id {
+                    retire_callback(&mut state, id, self.maximum_retired);
+                    finished.push(pending);
+                } else {
+                    remaining.insert(id, pending);
+                }
+            }
+            state.pending = remaining;
+            finished
+        };
+        for pending in pending {
+            let _ = pending.result.send(Err(SessionError::Cancelled));
+        }
+    }
+
+    fn close(&self) {
+        let pending = {
+            let mut state = lock_unpoisoned(&self.state);
+            std::mem::take(&mut state.pending)
+        };
+        for pending in pending.into_values() {
+            let _ = pending.result.send(Err(SessionError::Closed));
+        }
+    }
+}
+
+fn retire_callback(state: &mut CallbackState, id: u64, maximum: usize) {
+    if state.retired.insert(id) {
+        state.retired_order.push_back(id);
+    }
+    while state.retired_order.len() > maximum {
+        if let Some(expired) = state.retired_order.pop_front() {
+            state.retired.remove(&expired);
+        }
+    }
+}
+
+enum LifecycleEvent {
+    Cancel(CallContext),
+    Quiesce,
+    Shutdown,
+}
+
+#[derive(Clone)]
+struct LifecycleHooks {
+    events: std::sync::mpsc::SyncSender<LifecycleEvent>,
+}
+
+impl LifecycleHooks {
+    fn new(handler: Arc<dyn PluginHandler>, capacity: usize) -> Result<Self, SessionError> {
+        let (events, received) = std::sync::mpsc::sync_channel(capacity);
+        std::thread::Builder::new()
+            .name("gateway-plugin-sdk-lifecycle".into())
+            .spawn(move || {
+                while let Ok(event) = received.recv() {
+                    match event {
+                        LifecycleEvent::Cancel(context) => handler.cancel(&context),
+                        LifecycleEvent::Quiesce => handler.quiesce(),
+                        LifecycleEvent::Shutdown => {
+                            handler.shutdown();
+                            break;
+                        }
+                    }
+                }
+            })
+            .map_err(|_| SessionError::Closed)?;
+        Ok(Self { events })
+    }
+
+    fn cancel(&self, context: CallContext) {
+        let _ = self.events.try_send(LifecycleEvent::Cancel(context));
+    }
+
+    fn quiesce(&self) {
+        let _ = self.events.try_send(LifecycleEvent::Quiesce);
+    }
+
+    fn shutdown(&self) {
+        let _ = self.events.try_send(LifecycleEvent::Shutdown);
+    }
+}
+
+struct ActiveCall {
+    context: CallContext,
+    credits: Arc<CreditWindow>,
+    cancellation: CancellationSource,
+    task: JoinHandle<()>,
+}
+
+#[derive(Clone, Copy)]
+enum CallTaskOutcome {
+    Complete,
+    TransportFailed,
+    HandlerStopped,
+}
+
+struct CallFinished {
+    id: u64,
+    outcome: CallTaskOutcome,
+}
+
+struct CompletionGuard {
+    id: u64,
+    completed: mpsc::Sender<CallFinished>,
+    armed: bool,
+}
+
+impl CompletionGuard {
+    fn new(id: u64, completed: mpsc::Sender<CallFinished>) -> Self {
+        Self {
+            id,
+            completed,
+            armed: true,
+        }
+    }
+
+    fn finish(mut self, outcome: CallTaskOutcome) {
+        self.armed = false;
+        let _ = self.completed.try_send(CallFinished {
+            id: self.id,
+            outcome,
+        });
+    }
+}
+
+impl Drop for CompletionGuard {
+    fn drop(&mut self) {
+        if self.armed {
+            let _ = self.completed.try_send(CallFinished {
+                id: self.id,
+                outcome: CallTaskOutcome::HandlerStopped,
+            });
+        }
+    }
+}
+
+struct SessionDriver {
+    config: SessionConfig,
+    instance_id: String,
+    generation: u64,
+    incarnation: String,
+    output: Output,
+    callbacks: Arc<CallbackRegistry>,
+    handler: Arc<dyn PluginHandler>,
+    lifecycle: LifecycleHooks,
+    writer: JoinHandle<Result<(), SessionError>>,
+    completed: mpsc::Sender<CallFinished>,
+    completions: mpsc::Receiver<CallFinished>,
+    active: BTreeMap<u64, ActiveCall>,
+    last_call: u64,
+    quiescing: bool,
+}
+
+impl SessionDriver {
+    async fn drive<R: AsyncRead + Unpin>(&mut self, mut reader: R) -> Result<(), SessionError> {
+        loop {
+            // read_exact 不是取消安全的；完成通知可以穿插处理，但必须保留同一个半帧读取 future。
+            let incoming = read_frame(&mut reader, self.config.maximum_frame_bytes);
+            tokio::pin!(incoming);
+            let frame = loop {
+                tokio::select! {
+                    biased;
+                    writer = &mut self.writer => {
+                        return writer.map_err(|_| SessionError::Closed)?;
+                    }
+                    Some(finished) = self.completions.recv() => {
+                        self.finish_call(finished)?;
+                    }
+                    frame = &mut incoming => {
+                        break frame.map_err(|error| match error {
+                            FrameError::Io(io_error)
+                                if io_error.kind() == std::io::ErrorKind::UnexpectedEof =>
+                            {
+                                SessionError::Closed
+                            }
+                            error => SessionError::Frame(error),
+                        })?;
+                    }
+                }
+            };
+            if self.handle_frame(frame)? {
+                return Ok(());
+            }
+        }
+    }
+
+    fn handle_frame(&mut self, frame: Frame) -> Result<bool, SessionError> {
+        match frame.message {
+            Message::Call {
+                id,
+                method,
+                context,
+                params,
+            } => {
+                self.start_call(id, method, context, params, frame.payload)?;
+                Ok(false)
+            }
+            Message::Credit { id, bytes, frames } if frame.payload.is_empty() => {
+                if id == 0
+                    || id.is_multiple_of(2)
+                    || id > self.last_call
+                    || bytes == 0
+                    || frames == 0
+                {
+                    return Err(SessionError::Protocol);
+                }
+                // End/Cancelled 已进入同一 FIFO 后，宿主先前为已消费分块排队的
+                // Credit 仍可能稍晚抵达。此时调用资源已经回收，忽略迟到信用即可；
+                // 未来或回调 ID 仍按协议错误处理。
+                if let Some(active) = self.active.get(&id) {
+                    active.credits.grant(bytes, frames)?;
+                }
+                Ok(false)
+            }
+            Message::Cancel { id } if frame.payload.is_empty() => {
+                self.cancel_call(id)?;
+                Ok(false)
+            }
+            Message::Result { id, result } => {
+                self.callbacks.resolve(Frame {
+                    message: Message::Result { id, result },
+                    payload: frame.payload,
+                })?;
+                Ok(false)
+            }
+            Message::Error { id, error } => {
+                self.callbacks.resolve(Frame {
+                    message: Message::Error { id, error },
+                    payload: frame.payload,
+                })?;
+                Ok(false)
+            }
+            Message::Quiesce if frame.payload.is_empty() => {
+                if !self.quiescing {
+                    self.quiescing = true;
+                    self.lifecycle.quiesce();
+                }
+                Ok(false)
+            }
+            Message::Shutdown if frame.payload.is_empty() => Ok(true),
+            _ => Err(SessionError::Protocol),
+        }
+    }
+
+    fn start_call(
+        &mut self,
+        id: u64,
+        method: String,
+        context: CallContext,
+        params: Value,
+        payload: Vec<u8>,
+    ) -> Result<(), SessionError> {
+        if id == 0
+            || id.is_multiple_of(2)
+            || id <= self.last_call
+            || context.call_id != id
+            || context.instance_id != self.instance_id
+            || context.generation != self.generation
+            || context.incarnation != self.incarnation
+            || context.timeout_ms == 0
+            || Duration::from_millis(context.timeout_ms) > self.config.maximum_call_timeout
+            || method.is_empty()
+            || method.len() > 128
+        {
+            return Err(SessionError::Protocol);
+        }
+        self.last_call = id;
+        if self.quiescing {
+            return self.output.send_control(fault_frame(
+                id,
+                PluginFault::new(ErrorCode::Capacity, "plugin is quiescing"),
+            ));
+        }
+        if self.active.len() >= self.config.maximum_calls {
+            return self.output.send_control(fault_frame(
+                id,
+                PluginFault::new(ErrorCode::Capacity, "plugin call capacity is exhausted"),
+            ));
+        }
+        let deadline = Instant::now()
+            .checked_add(Duration::from_millis(context.timeout_ms))
+            .ok_or(SessionError::Protocol)?;
+        let credits = Arc::new(CreditWindow::default());
+        let (cancellation, cancellation_signal) = CancellationSource::new();
+        let host = HostClient {
+            parent_id: id,
+            deadline,
+            cancellation: cancellation_signal.clone(),
+            callbacks: Arc::clone(&self.callbacks),
+            output: self.output.clone(),
+            maximum_frame_bytes: self.config.maximum_frame_bytes,
+        };
+        let call = PluginCall {
+            method,
+            context: context.clone(),
+            params,
+            payload,
+            host,
+            cancellation: cancellation_signal,
+        };
+        let handler = Arc::clone(&self.handler);
+        let output = self.output.clone();
+        let completed = self.completed.clone();
+        let task_credits = Arc::clone(&credits);
+        let maximum_frame_bytes = self.config.maximum_frame_bytes;
+        let maximum_chunks = self.config.maximum_buffered_stream_chunks;
+        let task_context = context.clone();
+        let lifecycle = self.lifecycle.clone();
+        let task = tokio::spawn(async move {
+            let guard = CompletionGuard::new(id, completed);
+            let result = run_call(
+                handler,
+                call,
+                task_context,
+                task_credits,
+                output,
+                lifecycle,
+                deadline,
+                maximum_frame_bytes,
+                maximum_chunks,
+            )
+            .await;
+            guard.finish(if result.is_ok() {
+                CallTaskOutcome::Complete
+            } else {
+                CallTaskOutcome::TransportFailed
+            });
+        });
+        self.active.insert(
+            id,
+            ActiveCall {
+                context,
+                credits,
+                cancellation,
+                task,
+            },
+        );
+        Ok(())
+    }
+
+    fn cancel_call(&mut self, id: u64) -> Result<(), SessionError> {
+        if id == 0 || id.is_multiple_of(2) || id > self.last_call {
+            return Err(SessionError::Protocol);
+        }
+        if let Some(active) = self.active.remove(&id) {
+            active.cancellation.cancel();
+            self.callbacks.finish_parent(id);
+            self.lifecycle.cancel(active.context);
+            active.task.abort();
+        }
+        self.output
+            .send_control(Frame::control(Message::Cancelled { id }))
+    }
+
+    fn finish_call(&mut self, finished: CallFinished) -> Result<(), SessionError> {
+        let Some(_active) = self.active.remove(&finished.id) else {
+            return Ok(());
+        };
+        self.callbacks.finish_parent(finished.id);
+        match finished.outcome {
+            CallTaskOutcome::Complete => Ok(()),
+            CallTaskOutcome::TransportFailed => Err(SessionError::Closed),
+            CallTaskOutcome::HandlerStopped => Err(SessionError::HandlerStopped),
+        }
+    }
+
+    async fn close(&mut self) {
+        for (id, active) in std::mem::take(&mut self.active) {
+            active.cancellation.cancel();
+            self.callbacks.finish_parent(id);
+            self.lifecycle.cancel(active.context);
+            active.task.abort();
+        }
+        self.callbacks.close();
+        self.lifecycle.shutdown();
+        self.writer.abort();
+        let _ = (&mut self.writer).await;
+    }
+}
+
+#[expect(
+    clippy::too_many_arguments,
+    reason = "调用任务显式接收其完整资源边界，避免隐藏第二份会话状态"
+)]
+async fn run_call(
+    handler: Arc<dyn PluginHandler>,
+    call: PluginCall,
+    context: CallContext,
+    credits: Arc<CreditWindow>,
+    output: Output,
+    lifecycle: LifecycleHooks,
+    deadline: Instant,
+    maximum_frame_bytes: usize,
+    maximum_chunks: usize,
+) -> Result<(), SessionError> {
+    let id = context.call_id;
+    let cancellation = call.cancellation.clone();
+    let response = tokio::select! {
+        biased;
+        () = cancellation.cancelled() => return Ok(()),
+        () = tokio::time::sleep_until(deadline) => {
+            lifecycle.cancel(context.clone());
+            output.send_control(fault_frame(
+                id,
+                PluginFault::new(ErrorCode::Timeout, "plugin call timed out"),
+            ))?;
+            return Ok(());
+        }
+        response = handler.call(call) => response,
+    };
+    let mut reply = match response {
+        Ok(reply) => reply,
+        Err(error) => {
+            let _ = send_initial(
+                &output,
+                bounded_fault_frame(id, error, maximum_frame_bytes),
+                &context,
+                &lifecycle,
+                deadline,
+                &cancellation,
+            )
+            .await?;
+            return Ok(());
+        }
+    };
+    let initial = Frame {
+        message: Message::Result {
+            id,
+            result: reply.result,
+        },
+        payload: reply.payload,
+    };
+    if validate_frame(&initial, maximum_frame_bytes).is_err() {
+        output.send_control(fault_frame(
+            id,
+            PluginFault::new(
+                ErrorCode::InvalidInput,
+                "plugin response exceeds the frame limit",
+            ),
+        ))?;
+        return Ok(());
+    }
+    let Some(mut stream) = reply.stream.take() else {
+        let _ = send_initial(
+            &output,
+            initial,
+            &context,
+            &lifecycle,
+            deadline,
+            &cancellation,
+        )
+        .await?;
+        return Ok(());
+    };
+    let window_bytes = match credits.initial_window(deadline, &cancellation).await {
+        Ok(window) => window,
+        Err(SessionError::Timeout) => {
+            lifecycle.cancel(context.clone());
+            output.send_control(fault_frame(
+                id,
+                PluginFault::new(ErrorCode::Timeout, "stream credit timed out"),
+            ))?;
+            return Ok(());
+        }
+        Err(SessionError::Cancelled) => return Ok(()),
+        Err(error) => return Err(error),
+    };
+    if let Err(fault) = stream.validate_buffered(maximum_chunks, maximum_frame_bytes, window_bytes)
+    {
+        output.send_control(fault_frame(id, fault))?;
+        return Ok(());
+    }
+    if !send_initial(
+        &output,
+        initial,
+        &context,
+        &lifecycle,
+        deadline,
+        &cancellation,
+    )
+    .await?
+    {
+        return Ok(());
+    }
+    let mut sequence = 0_u64;
+    loop {
+        let item = tokio::select! {
+            biased;
+            () = cancellation.cancelled() => return Ok(()),
+            () = tokio::time::sleep_until(deadline) => {
+                lifecycle.cancel(context.clone());
+                output.send_control(end_frame(
+                    id,
+                    Some(PluginFault::new(ErrorCode::Timeout, "plugin stream timed out")),
+                ))?;
+                return Ok(());
+            }
+            item = stream.next() => item,
+        };
+        let Some(item) = item else {
+            output.send_control(end_frame(id, None))?;
+            return Ok(());
+        };
+        let payload = match item {
+            Ok(payload) => payload,
+            Err(fault) => {
+                output.send_control(bounded_end_frame(id, fault, maximum_frame_bytes))?;
+                return Ok(());
+            }
+        };
+        if let Err(fault) = validate_stream_chunk(&payload, maximum_frame_bytes, window_bytes) {
+            output.send_control(end_frame(id, Some(fault)))?;
+            return Ok(());
+        }
+        match credits
+            .take(payload.len() as u64, deadline, &cancellation)
+            .await
+        {
+            Ok(()) => {}
+            Err(SessionError::Timeout) => {
+                lifecycle.cancel(context.clone());
+                output.send_control(end_frame(
+                    id,
+                    Some(PluginFault::new(
+                        ErrorCode::Timeout,
+                        "stream credit timed out",
+                    )),
+                ))?;
+                return Ok(());
+            }
+            Err(SessionError::Cancelled) => return Ok(()),
+            Err(error) => return Err(error),
+        }
+        let frame = Frame {
+            message: Message::Stream { id, sequence },
+            payload,
+        };
+        if !send_stream_data(
+            &output,
+            frame,
+            id,
+            &context,
+            &lifecycle,
+            deadline,
+            &cancellation,
+        )
+        .await?
+        {
+            return Ok(());
+        }
+        sequence = sequence.checked_add(1).ok_or(SessionError::Protocol)?;
+    }
+}
+
+async fn send_initial(
+    output: &Output,
+    frame: Frame,
+    context: &CallContext,
+    lifecycle: &LifecycleHooks,
+    deadline: Instant,
+    cancellation: &CallCancellation,
+) -> Result<bool, SessionError> {
+    match output.send_data_until(frame, deadline, cancellation).await {
+        Ok(()) => Ok(true),
+        Err(SessionError::Cancelled) => Ok(false),
+        Err(SessionError::Timeout) => {
+            lifecycle.cancel(context.clone());
+            output.send_control(fault_frame(
+                context.call_id,
+                PluginFault::new(ErrorCode::Timeout, "plugin call timed out"),
+            ))?;
+            Ok(false)
+        }
+        Err(error) => Err(error),
+    }
+}
+
+async fn send_stream_data(
+    output: &Output,
+    frame: Frame,
+    id: u64,
+    context: &CallContext,
+    lifecycle: &LifecycleHooks,
+    deadline: Instant,
+    cancellation: &CallCancellation,
+) -> Result<bool, SessionError> {
+    match output.send_data_until(frame, deadline, cancellation).await {
+        Ok(()) => Ok(true),
+        Err(SessionError::Cancelled) => Ok(false),
+        Err(SessionError::Timeout) => {
+            lifecycle.cancel(context.clone());
+            output.send_control(end_frame(
+                id,
+                Some(PluginFault::new(
+                    ErrorCode::Timeout,
+                    "plugin stream timed out",
+                )),
+            ))?;
+            Ok(false)
+        }
+        Err(error) => Err(error),
+    }
+}
+
+#[derive(Default)]
+struct CreditWindow {
+    state: Mutex<CreditState>,
+    changed: tokio::sync::Notify,
+}
+
+#[derive(Default)]
+struct CreditState {
+    bytes: u64,
+    frames: u64,
+    maximum_bytes: u64,
+}
+
+impl CreditWindow {
+    fn grant(&self, bytes: u32, frames: u32) -> Result<(), SessionError> {
+        if bytes == 0 || frames == 0 {
+            return Err(SessionError::Protocol);
+        }
+        let mut state = lock_unpoisoned(&self.state);
+        state.bytes = state
+            .bytes
+            .checked_add(u64::from(bytes))
+            .ok_or(SessionError::Protocol)?;
+        state.frames = state
+            .frames
+            .checked_add(u64::from(frames))
+            .ok_or(SessionError::Protocol)?;
+        state.maximum_bytes = state.maximum_bytes.max(state.bytes);
+        drop(state);
+        // 每个调用只有一个顺序消费 Credit 的任务；notify_one 会保留许可，避免
+        // grant 恰好发生在状态检查和等待注册之间时丢失唤醒。
+        self.changed.notify_one();
+        Ok(())
+    }
+
+    async fn initial_window(
+        &self,
+        deadline: Instant,
+        cancellation: &CallCancellation,
+    ) -> Result<u64, SessionError> {
+        loop {
+            let changed = self.changed.notified();
+            {
+                let state = lock_unpoisoned(&self.state);
+                if state.bytes > 0 && state.frames > 0 {
+                    return Ok(state.maximum_bytes);
+                }
+            }
+            tokio::select! {
+                biased;
+                () = cancellation.cancelled() => return Err(SessionError::Cancelled),
+                () = tokio::time::sleep_until(deadline) => return Err(SessionError::Timeout),
+                () = changed => {}
+            }
+        }
+    }
+
+    async fn take(
+        &self,
+        bytes: u64,
+        deadline: Instant,
+        cancellation: &CallCancellation,
+    ) -> Result<(), SessionError> {
+        loop {
+            let changed = self.changed.notified();
+            {
+                let mut state = lock_unpoisoned(&self.state);
+                if bytes > state.maximum_bytes {
+                    return Err(SessionError::Protocol);
+                }
+                if state.bytes >= bytes && state.frames > 0 {
+                    state.bytes -= bytes;
+                    state.frames -= 1;
+                    return Ok(());
+                }
+            }
+            tokio::select! {
+                biased;
+                () = cancellation.cancelled() => return Err(SessionError::Cancelled),
+                () = tokio::time::sleep_until(deadline) => return Err(SessionError::Timeout),
+                () = changed => {}
+            }
+        }
+    }
+}
+
+fn validate_stream_chunk(
+    payload: &[u8],
+    maximum_frame_bytes: usize,
+    window_bytes: u64,
+) -> Result<(), PluginFault> {
+    if payload.is_empty() {
+        return Err(PluginFault::new(
+            ErrorCode::InvalidInput,
+            "stream chunks must not be empty",
+        ));
+    }
+    if payload.len() as u64 > window_bytes {
+        return Err(PluginFault::new(
+            ErrorCode::InvalidInput,
+            "response event exceeds the host stream credit window",
+        ));
+    }
+    if validate_message(
+        &Message::Stream { id: 1, sequence: 0 },
+        payload.len(),
+        maximum_frame_bytes,
+    )
+    .is_err()
+    {
+        return Err(PluginFault::new(
+            ErrorCode::InvalidInput,
+            "response event exceeds the frame limit",
+        ));
+    }
+    Ok(())
+}
+
+fn capacity_fault(message: &'static str) -> PluginFault {
+    PluginFault::new(ErrorCode::Capacity, message)
+}
+
+fn fault_frame(id: u64, error: PluginFault) -> Frame {
+    Frame::control(Message::Error { id, error })
+}
+
+fn end_frame(id: u64, error: Option<PluginFault>) -> Frame {
+    Frame::control(Message::End { id, error })
+}
+
+fn bounded_fault_frame(id: u64, error: PluginFault, maximum_frame_bytes: usize) -> Frame {
+    let frame = fault_frame(id, error);
+    if validate_frame(&frame, maximum_frame_bytes).is_ok() {
+        frame
+    } else {
+        fault_frame(
+            id,
+            PluginFault::new(ErrorCode::Fault, "plugin error exceeds the frame limit"),
+        )
+    }
+}
+
+fn bounded_end_frame(id: u64, error: PluginFault, maximum_frame_bytes: usize) -> Frame {
+    let frame = end_frame(id, Some(error));
+    if validate_frame(&frame, maximum_frame_bytes).is_ok() {
+        frame
+    } else {
+        end_frame(
+            id,
+            Some(PluginFault::new(
+                ErrorCode::Fault,
+                "plugin stream error exceeds the frame limit",
+            )),
+        )
+    }
+}
+
+fn lock_unpoisoned<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
+    mutex
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/context.rs b/backend/crates/gateway-plugin/sdk/src/context.rs
new file mode 100644
index 000000000..f55e8c14a
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/context.rs
@@ -0,0 +1,53 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{Contributions, Permission, Stage};
+
+/// 一次会话绑定不可变制品与配置；重启必须使用新的 incarnation。
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Handshake {
+    pub protocol_version: u32,
+    pub artifact_sha256: String,
+    pub plugin_id: String,
+    pub instance_id: String,
+    pub generation: u64,
+    pub incarnation: String,
+    pub configuration: serde_json::Value,
+    pub permissions: Vec<Permission>,
+    #[serde(deserialize_with = "crate::capability::deserialize_contributions")]
+    pub contributes: Contributions,
+}
+
+impl std::fmt::Debug for Handshake {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("Handshake")
+            .field("protocol_version", &self.protocol_version)
+            .field("plugin_id", &self.plugin_id)
+            .field("instance_id", &self.instance_id)
+            .field("generation", &self.generation)
+            .field("incarnation", &self.incarnation)
+            .finish_non_exhaustive()
+    }
+}
+
+/// 仅携带安全关联信息；这些标识本身不是宿主资源的访问凭证。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CallContext {
+    pub call_id: u64,
+    pub instance_id: String,
+    pub generation: u64,
+    pub incarnation: String,
+    pub stage: Stage,
+    pub timeout_ms: u64,
+    pub resource_scope_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub request_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub attempt_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub account_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub credential_revision: Option<u64>,
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/error.rs b/backend/crates/gateway-plugin/sdk/src/error.rs
new file mode 100644
index 000000000..61c9759ba
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/error.rs
@@ -0,0 +1,59 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ErrorCode {
+    Unsupported,
+    Rejected,
+    InvalidInput,
+    PermissionDenied,
+    Upstream,
+    Fault,
+    Timeout,
+    Cancelled,
+    Uncertain,
+    Capacity,
+    Conflict,
+}
+
+/// 发送事实由宿主取单调上界，不能由插件降回未发送。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SendState {
+    NotSent,
+    Sent,
+    Ambiguous,
+}
+
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PluginFault {
+    pub code: ErrorCode,
+    pub message: String,
+    pub send_state: SendState,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub http_status: Option<u16>,
+}
+
+impl std::fmt::Debug for PluginFault {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("PluginFault")
+            .field("code", &self.code)
+            .field("send_state", &self.send_state)
+            .field("http_status", &self.http_status)
+            .finish_non_exhaustive()
+    }
+}
+
+impl PluginFault {
+    #[must_use]
+    pub fn new(code: ErrorCode, message: impl Into<String>) -> Self {
+        Self {
+            code,
+            message: message.into(),
+            send_state: SendState::NotSent,
+            http_status: None,
+        }
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/lib.rs b/backend/crates/gateway-plugin/sdk/src/lib.rs
new file mode 100644
index 000000000..b08afd6f5
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/lib.rs
@@ -0,0 +1,21 @@
+//! 实验性插件线协议；不依赖网关领域或基础设施类型。
+
+pub mod call;
+mod capability;
+#[cfg(feature = "io")]
+pub mod client;
+mod context;
+mod error;
+mod manifest;
+mod message;
+
+pub use capability::{
+    Capability, ContributionDeclaration, Contributions, FailurePolicy, Permission, Stage,
+};
+pub use context::{CallContext, Handshake};
+pub use error::{ErrorCode, PluginFault, SendState};
+pub use manifest::{
+    Engines, MANIFEST_VERSION, Manifest, ManifestError, Package, PackageTarget, PluginIcon,
+    PluginIconVariants, RuntimeKind, StateNamespace, valid_package_path,
+};
+pub use message::{Frame, FrameError, Message, PROTOCOL_VERSION};
diff --git a/backend/crates/gateway-plugin/sdk/src/manifest.rs b/backend/crates/gateway-plugin/sdk/src/manifest.rs
new file mode 100644
index 000000000..ddfa23296
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/manifest.rs
@@ -0,0 +1,699 @@
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    fmt,
+};
+
+use semver::{Version, VersionReq};
+use serde::{
+    Deserialize, Deserializer, Serialize,
+    de::{self, MapAccess, SeqAccess, Visitor},
+};
+use serde_json::Value;
+
+use crate::{
+    Capability, ContributionDeclaration, Contributions, PROTOCOL_VERSION, Permission, Stage,
+};
+
+/// 当前插件清单格式版本。
+pub const MANIFEST_VERSION: u32 = 3;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum RuntimeKind {
+    TrustedProcess,
+}
+
+/// 插件展示图标；路径始终引用同一清单中声明的包资源。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum PluginIcon {
+    Path(String),
+    Themed(PluginIconVariants),
+}
+
+/// 为浅色与深色界面分别声明的插件图标。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PluginIconVariants {
+    pub light: String,
+    pub dark: String,
+}
+
+/// 宿主版本兼容范围。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Engines {
+    #[serde(rename = "codex-proxy-rs")]
+    pub codex_proxy_rs: VersionReq,
+}
+
+/// 安装包的唯一目标平台。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PackageTarget {
+    pub os: String,
+    pub architecture: String,
+}
+
+/// 构建生成的安装包元数据；作者源清单可以省略。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct Package {
+    pub protocol_version: u32,
+    pub target: PackageTarget,
+    pub files: BTreeMap<String, String>,
+}
+
+/// 插件私有状态的单个命名空间声明；宿主仍会施加更严格的全局上限。
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct StateNamespace {
+    pub namespace: String,
+    pub schema_version: u32,
+    pub schema: serde_json::Value,
+    pub maximum_records: u32,
+    pub maximum_bytes: u64,
+    pub maximum_value_bytes: u32,
+    #[serde(default)]
+    pub migrates_from: Vec<u32>,
+}
+
+impl fmt::Debug for StateNamespace {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("StateNamespace")
+            .field("namespace", &self.namespace)
+            .field("schema_version", &self.schema_version)
+            .field("schema", &"[REDACTED]")
+            .field("maximum_records", &self.maximum_records)
+            .field("maximum_bytes", &self.maximum_bytes)
+            .field("maximum_value_bytes", &self.maximum_value_bytes)
+            .field("migrates_from", &self.migrates_from)
+            .finish()
+    }
+}
+
+/// 插件作者清单。`package` 缺省时表示尚未构建的源清单。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct Manifest {
+    pub manifest_version: u32,
+    pub name: String,
+    pub display_name: String,
+    pub publisher: String,
+    pub version: Version,
+    pub description: String,
+    pub license: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub author: Option<String>,
+    pub engines: Engines,
+    pub main: String,
+    pub runtime: RuntimeKind,
+    #[serde(deserialize_with = "crate::capability::deserialize_contributions")]
+    pub contributes: Contributions,
+    #[serde(default)]
+    pub permissions: BTreeSet<Permission>,
+    #[serde(default = "empty_configuration_schema")]
+    pub configuration_schema: serde_json::Value,
+    #[serde(default)]
+    pub secret_fields: BTreeSet<String>,
+    #[serde(default)]
+    pub resources: BTreeMap<String, String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub icon: Option<PluginIcon>,
+    #[serde(default)]
+    pub state: Vec<StateNamespace>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub package: Option<Package>,
+}
+
+fn empty_configuration_schema() -> serde_json::Value {
+    serde_json::json!({})
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+pub enum ManifestError {
+    #[error("plugin manifest is invalid")]
+    Invalid,
+    #[error("plugin protocol or manifest version is incompatible")]
+    Incompatible,
+    #[error("plugin does not support the host version or platform")]
+    Platform,
+}
+
+impl Manifest {
+    /// 读取作者清单并生成与 CLI、运行注册一致的完整声明。
+    ///
+    /// # Errors
+    ///
+    /// JSON、版本、能力声明或安装包字段不符合作者合同时返回错误。
+    pub fn from_author_slice(bytes: &[u8]) -> Result<Self, ManifestError> {
+        let UniqueValue(mut source) =
+            serde_json::from_slice(bytes).map_err(|_| ManifestError::Invalid)?;
+        expand_author_provider(&mut source)?;
+        let mut manifest: Self =
+            serde_json::from_value(source).map_err(|_| ManifestError::Invalid)?;
+        manifest.normalize_author()?;
+        Ok(manifest)
+    }
+
+    /// 作者清单允许省略扩展项 ID、能力版本和固定阶段，安装清单不隐式补全。
+    ///
+    /// # Errors
+    ///
+    /// 已含构建元数据、阶段与固定合同冲突或规范化后清单无效时返回错误。
+    pub fn normalize_author(&mut self) -> Result<(), ManifestError> {
+        if self.package.is_some() {
+            return Err(ManifestError::Invalid);
+        }
+        let plugin_id = self.plugin_id()?;
+        for (capability, declaration) in &mut self.contributes {
+            if declaration.id.is_empty() {
+                declaration.id =
+                    format!("{plugin_id}.{}", capability.identifier().replace('_', "-"));
+            }
+            if *capability != Capability::Middleware {
+                if !declaration.stages.is_empty() && declaration.stages != capability.fixed_stages()
+                {
+                    return Err(ManifestError::Invalid);
+                }
+                declaration.stages = capability.fixed_stages().to_vec();
+            }
+        }
+        self.validate()
+    }
+
+    /// 派生并校验稳定插件 ID。
+    ///
+    /// # Errors
+    ///
+    /// 发布者、机器短名或派生后的完整 ID 不符合命名边界时返回错误。
+    pub fn plugin_id(&self) -> Result<String, ManifestError> {
+        if !valid_plugin_segment(&self.publisher) || !valid_plugin_segment(&self.name) {
+            return Err(ManifestError::Invalid);
+        }
+        let plugin_id = format!("{}.{}", self.publisher, self.name);
+        if plugin_id.len() > 64 {
+            return Err(ManifestError::Invalid);
+        }
+        Ok(plugin_id)
+    }
+
+    /// 校验源清单，并在 `package` 存在时同时执行严格安装包结构校验。
+    ///
+    /// # Errors
+    ///
+    /// 清单版本、身份、声明、路径、摘要、状态或安装包元数据不符合合同时返回错误。
+    pub fn validate(&self) -> Result<(), ManifestError> {
+        if self.manifest_version != MANIFEST_VERSION {
+            return Err(ManifestError::Incompatible);
+        }
+        let plugin_id = self.plugin_id()?;
+        if [&self.display_name, &self.description, &self.license]
+            .iter()
+            .any(|text| !valid_text(text))
+            || self.author.as_ref().is_some_and(|text| !valid_text(text))
+            || !valid_package_path(&self.main)
+            || self.main == "plugin.json"
+            || self.contributes.len() > 64
+            || self.resources.len() > 128
+            || self.secret_fields.len() > 64
+            || self.state.len() > 16
+        {
+            return Err(ManifestError::Invalid);
+        }
+        self.validate_contributions(&plugin_id)?;
+        self.validate_resources()?;
+        self.validate_icon()?;
+        self.validate_state()?;
+        if let Some(package) = &self.package {
+            self.validate_package(package)?;
+        }
+        Ok(())
+    }
+
+    /// 返回与当前宿主及平台匹配的安装包元数据。
+    ///
+    /// # Errors
+    ///
+    /// 源清单尚无安装包、清单无效、宿主版本不匹配或目标平台不同时返回错误。
+    pub fn package_for(
+        &self,
+        host: &Version,
+        os: &str,
+        architecture: &str,
+    ) -> Result<&Package, ManifestError> {
+        self.validate()?;
+        let package = self.package.as_ref().ok_or(ManifestError::Invalid)?;
+        if !self.engines.codex_proxy_rs.matches(host)
+            || package.target.os != os
+            || package.target.architecture != architecture
+        {
+            return Err(ManifestError::Platform);
+        }
+        Ok(package)
+    }
+
+    fn validate_contributions(&self, plugin_id: &str) -> Result<(), ManifestError> {
+        let mut contribution_ids = BTreeSet::new();
+        let prefix = format!("{plugin_id}.");
+        for (capability, declaration) in &self.contributes {
+            let Some(local_id) = declaration.id.strip_prefix(&prefix) else {
+                return Err(ManifestError::Invalid);
+            };
+            let stages = declaration.stages.iter().copied().collect::<BTreeSet<_>>();
+            let input_formats = declaration.input_formats.iter().collect::<BTreeSet<_>>();
+            let output_formats = declaration.output_formats.iter().collect::<BTreeSet<_>>();
+            if declaration.version != 1
+                || declaration.id.len() > 128
+                || local_id.is_empty()
+                || !local_id.is_ascii()
+                || !local_id
+                    .bytes()
+                    .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-'))
+                || !contribution_ids.insert(&declaration.id)
+                || declaration.stages.len() > 32
+                || stages.len() != declaration.stages.len()
+                || input_formats.len() != declaration.input_formats.len()
+                || output_formats.len() != declaration.output_formats.len()
+                || declaration
+                    .input_formats
+                    .iter()
+                    .chain(&declaration.output_formats)
+                    .any(|format| !platform_component(format))
+                || (*capability == Capability::Middleware
+                    && (declaration.stages.is_empty()
+                        || declaration
+                            .stages
+                            .iter()
+                            .any(|stage| !matches!(stage, Stage::Request | Stage::Attempt))))
+                || (*capability != Capability::Middleware
+                    && declaration.stages != capability.fixed_stages())
+                || (*capability == Capability::Executor
+                    && (declaration.input_formats.is_empty()
+                        || declaration.output_formats.is_empty()))
+            {
+                return Err(ManifestError::Invalid);
+            }
+        }
+        if !self.contributes.contains_key(&Capability::Executor)
+            && self.contributes.keys().any(|capability| {
+                matches!(
+                    capability,
+                    Capability::Models
+                        | Capability::Authentication
+                        | Capability::Quota
+                        | Capability::RequestProfile
+                        | Capability::AccountManagement
+                        | Capability::Billing
+                        | Capability::Maintenance
+                )
+            })
+        {
+            return Err(ManifestError::Invalid);
+        }
+        Ok(())
+    }
+
+    fn validate_resources(&self) -> Result<(), ManifestError> {
+        for (path, content_type) in &self.resources {
+            if !valid_package_path(path)
+                || path == "plugin.json"
+                || content_type.is_empty()
+                || content_type.len() > 128
+                || !content_type.is_ascii()
+                || content_type.chars().any(char::is_control)
+            {
+                return Err(ManifestError::Invalid);
+            }
+        }
+        if self
+            .secret_fields
+            .iter()
+            .any(|field| !platform_component(field))
+        {
+            return Err(ManifestError::Invalid);
+        }
+        Ok(())
+    }
+
+    fn validate_icon(&self) -> Result<(), ManifestError> {
+        let Some(icon) = &self.icon else {
+            return Ok(());
+        };
+        let valid = |path: &str| {
+            let extension = path.rsplit('.').next().unwrap_or_default();
+            let content_types: &[&str] = match extension.to_ascii_lowercase().as_str() {
+                "svg" => &["image/svg+xml"],
+                "png" => &["image/png"],
+                "jpg" | "jpeg" | "jfif" => &["image/jpeg"],
+                "webp" => &["image/webp"],
+                "gif" => &["image/gif"],
+                "ico" => &["image/vnd.microsoft.icon", "image/x-icon"],
+                "bmp" => &["image/bmp", "image/x-ms-bmp"],
+                _ => &[],
+            };
+            valid_package_path(path)
+                && self
+                    .resources
+                    .get(path)
+                    .is_some_and(|actual| content_types.contains(&actual.as_str()))
+        };
+        let valid = match icon {
+            PluginIcon::Path(path) => valid(path),
+            PluginIcon::Themed(variants) => valid(&variants.light) && valid(&variants.dark),
+        };
+        valid.then_some(()).ok_or(ManifestError::Invalid)
+    }
+
+    fn validate_state(&self) -> Result<(), ManifestError> {
+        let mut state_namespaces = BTreeSet::new();
+        for state in &self.state {
+            let schema_bytes =
+                serde_json::to_vec(&state.schema).map_err(|_| ManifestError::Invalid)?;
+            let migrations = state.migrates_from.iter().copied().collect::<BTreeSet<_>>();
+            if !valid_namespace(&state.namespace)
+                || !state_namespaces.insert(&state.namespace)
+                || state.schema_version == 0
+                || !state.schema.is_object()
+                || schema_bytes.len() > 32 * 1024
+                || state.maximum_records == 0
+                || state.maximum_records > 10_000
+                || state.maximum_bytes == 0
+                || state.maximum_bytes > 16 * 1024 * 1024
+                || state.maximum_value_bytes == 0
+                || state.maximum_value_bytes > 256 * 1024
+                || u64::from(state.maximum_value_bytes) > state.maximum_bytes
+                || migrations.len() != state.migrates_from.len()
+                || migrations.contains(&0)
+                || migrations.contains(&state.schema_version)
+            {
+                return Err(ManifestError::Invalid);
+            }
+        }
+        Ok(())
+    }
+
+    fn validate_package(&self, package: &Package) -> Result<(), ManifestError> {
+        if package.protocol_version != PROTOCOL_VERSION {
+            return Err(ManifestError::Incompatible);
+        }
+        // semver 将全版本 `*` 表示为空 comparator；`1.*` 仍有明确的主版本边界。
+        if self.engines.codex_proxy_rs.comparators.is_empty()
+            || !platform_component(&package.target.os)
+            || !platform_component(&package.target.architecture)
+            || package.files.is_empty()
+            || package.files.len() > 256
+            || !package.files.contains_key(&self.main)
+            || self
+                .resources
+                .keys()
+                .any(|path| !package.files.contains_key(path))
+        {
+            return Err(ManifestError::Invalid);
+        }
+        for (path, digest) in &package.files {
+            if !valid_package_path(path)
+                || path == "plugin.json"
+                || digest.len() != 64
+                || !digest
+                    .bytes()
+                    .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+            {
+                return Err(ManifestError::Invalid);
+            }
+            // 文件不能同时充当父目录，避免跨平台路径覆盖与解压顺序歧义。
+            if path
+                .split('/')
+                .scan(String::new(), |parent, part| {
+                    if !parent.is_empty() {
+                        parent.push('/');
+                    }
+                    parent.push_str(part);
+                    Some(parent.clone())
+                })
+                .any(|parent| parent != *path && package.files.contains_key(&parent))
+            {
+                return Err(ManifestError::Invalid);
+            }
+        }
+        Ok(())
+    }
+}
+
+/// `serde_json::Value` 默认保留重复对象键的最后一个值；作者清单不能让同一声明因解析入口而改变含义。
+struct UniqueValue(Value);
+
+impl<'de> Deserialize<'de> for UniqueValue {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        deserializer.deserialize_any(UniqueValueVisitor)
+    }
+}
+
+struct UniqueValueVisitor;
+
+impl<'de> Visitor<'de> for UniqueValueVisitor {
+    type Value = UniqueValue;
+
+    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("JSON without duplicate object keys")
+    }
+
+    fn visit_bool<E>(self, value: bool) -> Result<Self::Value, E> {
+        Ok(UniqueValue(Value::Bool(value)))
+    }
+
+    fn visit_i64<E>(self, value: i64) -> Result<Self::Value, E> {
+        Ok(UniqueValue(Value::Number(value.into())))
+    }
+
+    fn visit_u64<E>(self, value: u64) -> Result<Self::Value, E> {
+        Ok(UniqueValue(Value::Number(value.into())))
+    }
+
+    fn visit_f64<E>(self, value: f64) -> Result<Self::Value, E>
+    where
+        E: de::Error,
+    {
+        serde_json::Number::from_f64(value)
+            .map(Value::Number)
+            .map(UniqueValue)
+            .ok_or_else(|| E::custom("JSON number is not finite"))
+    }
+
+    fn visit_str<E>(self, value: &str) -> Result<Self::Value, E> {
+        Ok(UniqueValue(Value::String(value.to_owned())))
+    }
+
+    fn visit_string<E>(self, value: String) -> Result<Self::Value, E> {
+        Ok(UniqueValue(Value::String(value)))
+    }
+
+    fn visit_none<E>(self) -> Result<Self::Value, E> {
+        Ok(UniqueValue(Value::Null))
+    }
+
+    fn visit_unit<E>(self) -> Result<Self::Value, E> {
+        Ok(UniqueValue(Value::Null))
+    }
+
+    fn visit_some<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        UniqueValue::deserialize(deserializer)
+    }
+
+    fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
+    where
+        A: SeqAccess<'de>,
+    {
+        let mut values = Vec::new();
+        while let Some(UniqueValue(value)) = sequence.next_element()? {
+            values.push(value);
+        }
+        Ok(UniqueValue(Value::Array(values)))
+    }
+
+    fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
+    where
+        A: MapAccess<'de>,
+    {
+        let mut values = serde_json::Map::new();
+        while let Some((key, UniqueValue(value))) = entries.next_entry()? {
+            if values.insert(key, value).is_some() {
+                return Err(de::Error::custom("duplicate JSON object key"));
+            }
+        }
+        Ok(UniqueValue(Value::Object(values)))
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct AuthorProviderContribution {
+    #[serde(default)]
+    capabilities: Vec<Capability>,
+    #[serde(default)]
+    input_formats: Vec<String>,
+    #[serde(default)]
+    output_formats: Vec<String>,
+}
+
+fn expand_author_provider(source: &mut Value) -> Result<(), ManifestError> {
+    let Some(contributes) = source
+        .as_object_mut()
+        .and_then(|manifest| manifest.get_mut("contributes"))
+        .and_then(Value::as_object_mut)
+    else {
+        return Err(ManifestError::Invalid);
+    };
+    let Some(provider) = contributes.remove("provider") else {
+        return Ok(());
+    };
+    let provider: AuthorProviderContribution =
+        serde_json::from_value(provider).map_err(|_| ManifestError::Invalid)?;
+    let capabilities = provider
+        .capabilities
+        .iter()
+        .copied()
+        .collect::<BTreeSet<_>>();
+    if capabilities.len() != provider.capabilities.len()
+        || provider.input_formats.is_empty()
+        || provider.output_formats.is_empty()
+        || capabilities.iter().any(|capability| {
+            !matches!(
+                capability,
+                Capability::Models
+                    | Capability::Authentication
+                    | Capability::Quota
+                    | Capability::RequestProfile
+                    | Capability::AccountManagement
+                    | Capability::Billing
+                    | Capability::Maintenance
+            )
+        })
+    {
+        return Err(ManifestError::Invalid);
+    }
+    let executor = ContributionDeclaration {
+        id: String::new(),
+        version: 1,
+        stages: Vec::new(),
+        input_formats: provider.input_formats,
+        output_formats: provider.output_formats,
+    };
+    insert_author_contribution(contributes, Capability::Executor, executor)?;
+    for capability in capabilities {
+        insert_author_contribution(
+            contributes,
+            capability,
+            ContributionDeclaration {
+                id: String::new(),
+                version: 1,
+                stages: Vec::new(),
+                input_formats: Vec::new(),
+                output_formats: Vec::new(),
+            },
+        )?;
+    }
+    Ok(())
+}
+
+fn insert_author_contribution(
+    contributes: &mut serde_json::Map<String, Value>,
+    capability: Capability,
+    declaration: ContributionDeclaration,
+) -> Result<(), ManifestError> {
+    let identifier = capability.identifier().to_owned();
+    if contributes.contains_key(&identifier) {
+        return Err(ManifestError::Invalid);
+    }
+    let declaration = serde_json::to_value(declaration).map_err(|_| ManifestError::Invalid)?;
+    contributes.insert(identifier, declaration);
+    Ok(())
+}
+
+fn valid_text(value: &str) -> bool {
+    !value.trim().is_empty() && value.len() <= 4096 && !value.chars().any(char::is_control)
+}
+
+fn valid_plugin_segment(value: &str) -> bool {
+    let Some(first) = value.as_bytes().first() else {
+        return false;
+    };
+    let Some(last) = value.as_bytes().last() else {
+        return false;
+    };
+    first.is_ascii_alphanumeric()
+        && last.is_ascii_alphanumeric()
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
+}
+
+fn valid_namespace(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 64
+        && value.as_bytes()[0].is_ascii_lowercase()
+        && value.bytes().all(|byte| {
+            byte.is_ascii_lowercase() || byte.is_ascii_digit() || b"-_.".contains(&byte)
+        })
+}
+
+fn platform_component(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 64
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || b"-_.".contains(&byte))
+}
+
+/// 逐个检查原始路径段，不能让操作系统先规范化掉 `.`、空段或反斜线。
+#[must_use]
+pub fn valid_package_path(path: &str) -> bool {
+    !path.is_empty()
+        && path.len() <= 240
+        && path.is_ascii()
+        && path.split('/').all(|part| {
+            !part.is_empty()
+                && part != "."
+                && part != ".."
+                && !part.ends_with(['.', ' '])
+                && part
+                    .bytes()
+                    .all(|byte| byte.is_ascii_alphanumeric() || b"-_.".contains(&byte))
+                && !matches!(
+                    part.split('.')
+                        .next()
+                        .unwrap_or("")
+                        .to_ascii_uppercase()
+                        .as_str(),
+                    "CON"
+                        | "PRN"
+                        | "AUX"
+                        | "NUL"
+                        | "COM1"
+                        | "COM2"
+                        | "COM3"
+                        | "COM4"
+                        | "COM5"
+                        | "COM6"
+                        | "COM7"
+                        | "COM8"
+                        | "COM9"
+                        | "LPT1"
+                        | "LPT2"
+                        | "LPT3"
+                        | "LPT4"
+                        | "LPT5"
+                        | "LPT6"
+                        | "LPT7"
+                        | "LPT8"
+                        | "LPT9"
+                )
+        })
+}
diff --git a/backend/crates/gateway-plugin/sdk/src/message.rs b/backend/crates/gateway-plugin/sdk/src/message.rs
new file mode 100644
index 000000000..645117237
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/src/message.rs
@@ -0,0 +1,120 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{CallContext, Handshake, PluginFault};
+
+pub const PROTOCOL_VERSION: u32 = 4;
+
+/// 元数据与二进制载荷分开，流分块不经过 JSON/base64。
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
+pub enum Message {
+    Hello {
+        handshake: Handshake,
+    },
+    Ready {
+        protocol_version: u32,
+        incarnation: String,
+    },
+    Call {
+        id: u64,
+        method: String,
+        context: CallContext,
+        params: serde_json::Value,
+    },
+    Result {
+        id: u64,
+        result: serde_json::Value,
+    },
+    Error {
+        id: u64,
+        error: PluginFault,
+    },
+    Callback {
+        id: u64,
+        parent_id: u64,
+        method: String,
+        params: serde_json::Value,
+    },
+    Cancel {
+        id: u64,
+    },
+    Cancelled {
+        id: u64,
+    },
+    Stream {
+        id: u64,
+        sequence: u64,
+    },
+    Credit {
+        id: u64,
+        bytes: u32,
+        frames: u32,
+    },
+    End {
+        id: u64,
+        error: Option<PluginFault>,
+    },
+    Quiesce,
+    Shutdown,
+}
+
+#[derive(Clone, PartialEq)]
+pub struct Frame {
+    pub message: Message,
+    pub payload: Vec<u8>,
+}
+
+impl std::fmt::Debug for Message {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        // 配置、调用参数和结果都可能包含凭据；诊断仅暴露消息类别及关联 ID。
+        let (kind, id) = match self {
+            Self::Hello { .. } => ("Hello", None),
+            Self::Ready { .. } => ("Ready", None),
+            Self::Call { id, .. } => ("Call", Some(id)),
+            Self::Result { id, .. } => ("Result", Some(id)),
+            Self::Error { id, .. } => ("Error", Some(id)),
+            Self::Callback { id, .. } => ("Callback", Some(id)),
+            Self::Cancel { id } => ("Cancel", Some(id)),
+            Self::Cancelled { id } => ("Cancelled", Some(id)),
+            Self::Stream { id, .. } => ("Stream", Some(id)),
+            Self::Credit { id, .. } => ("Credit", Some(id)),
+            Self::End { id, .. } => ("End", Some(id)),
+            Self::Quiesce => ("Quiesce", None),
+            Self::Shutdown => ("Shutdown", None),
+        };
+        formatter
+            .debug_struct(kind)
+            .field("id", &id)
+            .finish_non_exhaustive()
+    }
+}
+
+impl std::fmt::Debug for Frame {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("Frame")
+            .field("message", &self.message)
+            .field("payload_bytes", &self.payload.len())
+            .finish()
+    }
+}
+
+impl Frame {
+    #[must_use]
+    pub fn control(message: Message) -> Self {
+        Self {
+            message,
+            payload: Vec::new(),
+        }
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum FrameError {
+    #[error("plugin frame exceeds its limit or has invalid lengths")]
+    Length,
+    #[error("plugin frame metadata is invalid")]
+    Metadata,
+    #[error("plugin transport is closed or incomplete")]
+    Io(#[from] std::io::Error),
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/frontend_authentication.rs b/backend/crates/gateway-plugin/sdk/tests/call/frontend_authentication.rs
new file mode 100644
index 000000000..fbf1d09d8
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/frontend_authentication.rs
@@ -0,0 +1,28 @@
+use gateway_plugin_sdk::call::frontend_authentication::{
+    FrontendAuthenticationRequest, FrontendAuthenticationResult,
+};
+use serde_json::json;
+
+#[test]
+fn authentication_contract_never_accepts_a_plugin_selected_client_key() {
+    let result = serde_json::from_value::<FrontendAuthenticationResult>(json!({
+        "outcome":"authenticated",
+        "principal":"controlled-principal",
+        "client_key_id":"attacker-selected-key"
+    }));
+    assert!(result.is_err());
+}
+
+#[test]
+fn authentication_debug_output_redacts_credentials_and_principals() {
+    let request = FrontendAuthenticationRequest {
+        authorization: "Bearer controlled-secret".into(),
+    };
+    let result = FrontendAuthenticationResult::Authenticated {
+        principal: "private-principal".into(),
+    };
+    let request_debug = format!("{request:?}");
+    let result_debug = format!("{result:?}");
+    assert!(!request_debug.contains("controlled-secret"));
+    assert!(!result_debug.contains("private-principal"));
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/host.rs b/backend/crates/gateway-plugin/sdk/tests/call/host.rs
new file mode 100644
index 000000000..f8e69c12c
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/host.rs
@@ -0,0 +1,204 @@
+use gateway_plugin_sdk::call::host::{
+    AffinityLookupRequest, AuthCredential, AuthListRequest, AuthSaveRequest, LogLevel, LogRequest,
+    LogResult, ModelEventBatch, ModelExecuteRequest, ModelOperation, StateDeleteRequest,
+    StateMigrationChange, StateMigrationResult, StatePutRequest,
+};
+use gateway_plugin_sdk::call::provider::{CanonicalEvent, ExecutionEvent, WireEvent, WirePayload};
+use serde_json::json;
+
+#[test]
+fn log_contract_defaults_and_closed_fields_are_stable() {
+    let request: LogRequest =
+        serde_json::from_value(json!({"event":"provider.connected"})).unwrap();
+    assert_eq!(request.level, LogLevel::Info);
+    assert!(request.fields.is_empty());
+    for level in ["debug", "info", "warn", "error"] {
+        let request: LogRequest = serde_json::from_value(
+            json!({"event":"provider.connected","level":level,"fields":{"status":200}}),
+        )
+        .unwrap();
+        assert_eq!(serde_json::to_value(request).unwrap()["level"], level);
+    }
+    assert!(
+        serde_json::from_value::<LogRequest>(
+            json!({"event":"provider.connected","request_id":"forged"})
+        )
+        .is_err()
+    );
+    assert!(
+        serde_json::from_value::<LogRequest>(json!({"event":"provider.connected","level":"trace"}))
+            .is_err()
+    );
+    assert_eq!(
+        serde_json::to_value(LogResult { recorded: false }).unwrap(),
+        json!({"recorded":false})
+    );
+}
+
+#[test]
+fn private_state_contract_keeps_cas_and_migration_actions_explicit() {
+    let create: StatePutRequest = serde_json::from_value(json!({
+        "namespace":"cache", "key":"answer", "value":{"value":42},
+        "expected_version":null
+    }))
+    .unwrap();
+    assert!(create.expected_version.is_none());
+    assert!(
+        serde_json::from_value::<StateDeleteRequest>(json!({
+            "namespace":"cache", "key":"answer"
+        }))
+        .is_err()
+    );
+    let result: StateMigrationResult = serde_json::from_value(json!({"changes":[
+        {"action":"keep","key":"a"},
+        {"action":"replace","key":"b","value":{"version":2}},
+        {"action":"delete","key":"c"}
+    ]}))
+    .unwrap();
+    assert_eq!(
+        result
+            .changes
+            .iter()
+            .map(StateMigrationChange::key)
+            .collect::<Vec<_>>(),
+        ["a", "b", "c"]
+    );
+}
+
+#[test]
+fn account_callbacks_keep_credentials_in_the_binary_contract_and_require_cas() {
+    let list: AuthListRequest = serde_json::from_value(json!({"cursor":null,"limit":20})).unwrap();
+    assert_eq!(list.limit, 20);
+    assert_eq!(list.provider_id, None);
+    let filtered: AuthListRequest =
+        serde_json::from_value(json!({"cursor":null,"limit":20,"provider_id":"example"})).unwrap();
+    assert_eq!(filtered.provider_id.as_deref(), Some("example"));
+    assert!(
+        serde_json::from_value::<AuthListRequest>(
+            json!({"cursor":null,"limit":20,"grants":["forged"]})
+        )
+        .is_err()
+    );
+
+    let credential: AuthCredential = serde_json::from_value(json!({
+        "account_id":"acct_test",
+        "provider_id":"example",
+        "credential_revision":3,
+        "facts":{
+            "name":"test",
+            "authentication_kind":"api_key",
+            "material":{"key":"controlled-test-value"},
+            "email":null,
+            "upstream_user_id":null,
+            "upstream_account_id":null,
+            "plan_type":null,
+            "access_token_expires_at_ms":null,
+            "next_refresh_at_ms":null
+        }
+    }))
+    .unwrap();
+    assert_eq!(credential.credential_revision, 3);
+
+    let replace: AuthSaveRequest = serde_json::from_value(json!({
+        "action":"replace",
+        "account_id":"acct_test",
+        "credential_revision":3,
+        "facts":{
+            "name":"test",
+            "authentication_kind":"api_key",
+            "material":{"key":"controlled-test-value"},
+            "email":null,
+            "upstream_user_id":null,
+            "upstream_account_id":null,
+            "plan_type":null,
+            "access_token_expires_at_ms":null,
+            "next_refresh_at_ms":null
+        }
+    }))
+    .unwrap();
+    assert!(matches!(
+        replace,
+        AuthSaveRequest::Replace {
+            credential_revision: 3,
+            ..
+        }
+    ));
+    assert!(
+        serde_json::from_value::<AuthSaveRequest>(json!({
+            "action":"replace",
+            "account_id":"acct_test",
+            "facts":{
+                "name":"test",
+                "authentication_kind":"api_key",
+                "material":{"key":"controlled-test-value"},
+                "email":null,
+                "upstream_user_id":null,
+                "upstream_account_id":null,
+                "plan_type":null,
+                "access_token_expires_at_ms":null,
+                "next_refresh_at_ms":null
+            }
+        }))
+        .is_err()
+    );
+}
+
+#[test]
+fn model_and_affinity_callbacks_keep_targets_explicit_and_closed() {
+    let request: ModelExecuteRequest = serde_json::from_value(json!({
+        "model":"gpt-test",
+        "protocol":"openai",
+        "operation":"generate",
+        "provider":"example",
+        "account_id":"acct_test",
+        "client_key_id":"key_fixture",
+        "previous_response_id":null
+    }))
+    .unwrap();
+    assert_eq!(request.operation, ModelOperation::Generate);
+    assert_eq!(request.provider.as_deref(), Some("example"));
+    assert_eq!(request.client_key_id.as_deref(), Some("key_fixture"));
+    assert!(
+        serde_json::from_value::<ModelExecuteRequest>(json!({
+            "model":"gpt-test", "protocol":"openai", "operation":"generate",
+            "execution_identity":"forged"
+        }))
+        .is_err()
+    );
+
+    let affinity: AffinityLookupRequest =
+        serde_json::from_value(json!({"provider":"example","key":"opaque-hash"})).unwrap();
+    assert_eq!(affinity.provider, "example");
+    assert_eq!(affinity.key, "opaque-hash");
+}
+
+#[test]
+fn model_event_batch_preserves_binary_wire_and_rejects_trailing_data() {
+    let batch = ModelEventBatch {
+        events: vec![ExecutionEvent {
+            facts: vec![CanonicalEvent::TextDelta {
+                index: 0,
+                text: "hello".to_owned(),
+            }],
+            wire: Some(WireEvent {
+                protocol: "openai".to_owned(),
+                payload: WirePayload::RawJson {
+                    body: br#"{"output":"hello"}"#.to_vec(),
+                },
+            }),
+            ..ExecutionEvent::default()
+        }],
+    };
+    let encoded = batch.encode().unwrap();
+    let decoded = ModelEventBatch::decode(&encoded).unwrap();
+    assert_eq!(decoded.events.len(), 1);
+    let wire = decoded.events[0].wire.as_ref().unwrap();
+    assert!(matches!(
+        &wire.payload,
+        WirePayload::RawJson { body } if body == br#"{"output":"hello"}"#
+    ));
+
+    let mut trailing = encoded;
+    trailing.push(0);
+    assert!(ModelEventBatch::decode(&trailing).is_err());
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/management.rs b/backend/crates/gateway-plugin/sdk/tests/call/management.rs
new file mode 100644
index 000000000..641cb4175
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/management.rs
@@ -0,0 +1,86 @@
+use gateway_plugin_sdk::call::management::{CommandRegistration, CommandResult, CommandValue};
+use serde_json::json;
+
+#[test]
+fn management_contract_keeps_http_bodies_separate_and_rejects_authority_headers() {
+    use gateway_plugin_sdk::call::management::{
+        ManagementRegistration, ManagementRequest, ManagementResponse,
+    };
+    let registration: ManagementRegistration = serde_json::from_value(json!({
+        "routes":[{"method":"POST","path":"report","response_content_types":["application/json"]}],
+        "resources":[{"path":"index.html"}],"pages":[{"id":"report","title":"报告","entry":"index.html"}],
+    })).unwrap();
+    assert!(!registration.resources[0].public);
+    assert!(registration.pages[0].description.is_none());
+    let request =
+        json!({"method":"POST","path":"report","query":"","content_type":"application/json"});
+    assert!(serde_json::from_value::<ManagementRequest>(request.clone()).is_ok());
+    let mut forged = request;
+    forged["headers"] = json!({"Cookie":"must-not-cross-wire"});
+    assert!(serde_json::from_value::<ManagementRequest>(forged).is_err());
+    assert!(
+        serde_json::from_value::<ManagementResponse>(
+            json!({"status":200,"content_type":"text/html","set_cookie":"forged"})
+        )
+        .is_err()
+    );
+}
+
+#[test]
+fn management_page_description_round_trips_with_the_directory() {
+    use gateway_plugin_sdk::call::management::ManagementPage;
+
+    let page = json!({
+        "id":"report", "title":"报告", "description":"查看请求处理状态",
+        "entry":"index.html", "icon":null
+    });
+    let parsed: ManagementPage = serde_json::from_value(page.clone()).unwrap();
+    assert_eq!(parsed.description.as_deref(), Some("查看请求处理状态"));
+    assert_eq!(serde_json::to_value(parsed).unwrap(), page);
+}
+
+#[test]
+fn command_values_preserve_types_and_portable_numeric_boundaries() {
+    for value in [
+        CommandValue::Bool(false),
+        CommandValue::String("private-argument".into()),
+        CommandValue::Int(i32::MIN),
+        CommandValue::Int64(i64::MAX),
+        CommandValue::Float64(0.25),
+        CommandValue::Duration(-1_500_000_000),
+    ] {
+        let encoded = serde_json::to_vec(&value).unwrap();
+        assert!(serde_json::from_slice::<CommandValue>(&encoded).unwrap() == value);
+    }
+    for invalid in [
+        json!({"type":"int","value":2147483648_i64}),
+        json!({"type":"duration","value":0.5}),
+        json!({"type":"bool","value":"true"}),
+        json!({"type":"string","value":"test","authority":"admin"}),
+    ] {
+        assert!(serde_json::from_value::<CommandValue>(invalid).is_err());
+    }
+}
+
+#[test]
+fn command_registration_and_result_reject_unknown_authority_fields() {
+    let registration = json!({"commands":[{
+        "name":"login", "description":"登录", "parameters":[{
+            "name":"timeout", "description":"等待时长", "value_type":"duration",
+            "default":{"type":"duration","value":30_000_000_000_i64}
+        }]
+    }]});
+    let value: CommandRegistration = serde_json::from_value(registration.clone()).unwrap();
+    assert_eq!(value.commands[0].name, "login");
+    let mut invalid = registration;
+    invalid["commands"][0]["admin_id"] = json!("forged");
+    assert!(serde_json::from_value::<CommandRegistration>(invalid).is_err());
+    let result: CommandResult =
+        serde_json::from_value(json!({"stdout":"out\n","stderr":"err\n","exit_code":17})).unwrap();
+    assert_eq!(result.exit_code, 17);
+    assert!(result.accounts.is_empty());
+    assert!(
+        serde_json::from_value::<CommandResult>(json!({"stdout":"","stderr":"","exit_code":256}))
+            .is_err()
+    );
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/middleware.rs b/backend/crates/gateway-plugin/sdk/tests/call/middleware.rs
new file mode 100644
index 000000000..d1eb1405c
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/middleware.rs
@@ -0,0 +1,168 @@
+use gateway_plugin_sdk::{
+    Capability, Stage,
+    call::middleware::{
+        MiddlewareBodyDisposition, MiddlewareBodyFrame, MiddlewareBodyFraming,
+        MiddlewareBodyHandle, MiddlewareBodyReadResult, MiddlewareHeader, MiddlewareHeaderMutation,
+        MiddlewareMount, MiddlewareNextRequest, MiddlewareNextResponse, MiddlewareRequestBody,
+        MiddlewareRequestHead, MiddlewareResponseBody, MiddlewareResponseHead, MiddlewareTransport,
+    },
+};
+use serde_json::json;
+
+#[test]
+fn middleware_capability_and_mounts_have_one_stable_wire_vocabulary() {
+    assert_eq!(
+        serde_json::to_value(Capability::Middleware).unwrap(),
+        "middleware"
+    );
+    assert_eq!(serde_json::to_value(Stage::Request).unwrap(), "request");
+    assert_eq!(serde_json::to_value(Stage::Attempt).unwrap(), "attempt");
+    assert_eq!(
+        serde_json::to_value(MiddlewareMount::Request).unwrap(),
+        "request"
+    );
+    assert_eq!(
+        serde_json::to_value(MiddlewareMount::Attempt).unwrap(),
+        "attempt"
+    );
+}
+
+#[test]
+fn middleware_request_keeps_body_out_of_json_and_rejects_unknown_fields() {
+    let request = MiddlewareRequestHead {
+        request_id: "request-1".into(),
+        mount: MiddlewareMount::Attempt,
+        attempt_index: Some(2),
+        operation: "generate".into(),
+        protocol: "openai".into(),
+        endpoint: "responses".into(),
+        transport: MiddlewareTransport::HttpSse,
+        provider: Some("openai".into()),
+        model: Some("gpt-5".into()),
+        account_id: Some("account-1".into()),
+        headers: vec![MiddlewareHeader {
+            name: "x-feature".into(),
+            value: b"enabled".to_vec(),
+        }],
+        body_visible: true,
+    };
+    let wire = serde_json::to_value(&request).unwrap();
+    assert_eq!(wire["mount"], "attempt");
+    assert_eq!(wire["transport"], "http_sse");
+    assert_eq!(
+        wire["headers"][0]["value"],
+        json!([101, 110, 97, 98, 108, 101, 100])
+    );
+    assert!(wire.get("body").is_none());
+    assert!(serde_json::from_value::<MiddlewareRequestHead>(wire.clone()).is_ok());
+
+    let mut unknown = wire;
+    unknown["credential_revision"] = json!(7);
+    assert!(serde_json::from_value::<MiddlewareRequestHead>(unknown).is_err());
+}
+
+#[test]
+fn next_distinguishes_preserve_from_replace_empty_and_uses_incremental_headers() {
+    let preserve = MiddlewareNextRequest {
+        protocol: None,
+        header_mutations: Vec::new(),
+        body: MiddlewareRequestBody::Preserve,
+    };
+    assert_eq!(
+        serde_json::to_value(preserve).unwrap(),
+        json!({"header_mutations":[],"body":"preserve"})
+    );
+
+    let replace = MiddlewareNextRequest {
+        protocol: Some("xai".into()),
+        header_mutations: vec![
+            MiddlewareHeaderMutation::Remove {
+                name: "x-old".into(),
+            },
+            MiddlewareHeaderMutation::Append {
+                name: "x-new".into(),
+                value: b"new".to_vec(),
+            },
+        ],
+        body: MiddlewareRequestBody::Replace,
+    };
+    assert_eq!(
+        serde_json::to_value(replace).unwrap(),
+        json!({
+            "protocol":"xai",
+            "header_mutations":[
+                {"operation":"remove","name":"x-old"},
+                {"operation":"append","name":"x-new","value":[110,101,119]}
+            ],
+            "body":"replace"
+        })
+    );
+}
+
+#[test]
+fn response_body_modes_distinguish_transfer_empty_and_plugin_stream() {
+    let handle = MiddlewareBodyHandle {
+        handle: "opaque-response-body".into(),
+        framing: MiddlewareBodyFraming::SseEvent,
+    };
+    let next = MiddlewareNextResponse {
+        response: "opaque-response".into(),
+        protocol: "openai".into(),
+        status: 200,
+        headers: Vec::new(),
+        body: Some(handle.clone()),
+    };
+    let next_wire = serde_json::to_value(next).unwrap();
+    assert_eq!(next_wire["body"]["framing"], "sse_event");
+    assert!(next_wire.get("usage").is_none());
+
+    let pass_through = MiddlewareResponseHead {
+        response: Some("opaque-response".into()),
+        protocol: None,
+        status: None,
+        header_mutations: Vec::new(),
+        body: MiddlewareResponseBody::PassThrough { body: handle },
+    };
+    assert_eq!(
+        serde_json::to_value(pass_through).unwrap()["body"]["kind"],
+        "pass_through"
+    );
+    assert_eq!(
+        serde_json::to_value(MiddlewareResponseBody::Empty).unwrap(),
+        json!({"kind":"empty"})
+    );
+    assert_eq!(
+        serde_json::to_value(MiddlewareResponseBody::Stream {
+            framing: MiddlewareBodyFraming::JsonDocument,
+        })
+        .unwrap(),
+        json!({"kind":"stream","framing":"json_document"})
+    );
+}
+
+#[test]
+fn body_read_metadata_and_binary_frame_keep_raw_bytes_out_of_json() {
+    let metadata = MiddlewareBodyReadResult {
+        framing: MiddlewareBodyFraming::RawBytes,
+        source_id: 9,
+        eof: false,
+        terminal: true,
+    };
+    assert_eq!(
+        serde_json::to_value(metadata).unwrap(),
+        json!({"framing":"raw_bytes","source_id":9,"eof":false,"terminal":true})
+    );
+
+    let encoded = MiddlewareBodyFrame::new(vec![0, 255, 10], true).encode();
+    assert_eq!(
+        &encoded[..14],
+        b"GMB1\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"
+    );
+    let decoded = MiddlewareBodyFrame::decode(&encoded).unwrap();
+    assert_eq!(decoded.payload, vec![0, 255, 10]);
+    assert!(decoded.terminal);
+    assert_eq!(decoded.source_id(), 0);
+    assert_eq!(decoded.disposition(), MiddlewareBodyDisposition::Standalone);
+    assert!(MiddlewareBodyFrame::decode(b"GMB1\x06bad").is_err());
+    assert!(MiddlewareBodyFrame::decode(b"GMB").is_err());
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/mod.rs b/backend/crates/gateway-plugin/sdk/tests/call/mod.rs
new file mode 100644
index 000000000..558548916
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/mod.rs
@@ -0,0 +1,7 @@
+mod frontend_authentication;
+mod host;
+mod management;
+mod middleware;
+mod observation;
+mod policy;
+mod provider;
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/observation.rs b/backend/crates/gateway-plugin/sdk/tests/call/observation.rs
new file mode 100644
index 000000000..c6e2f46d4
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/observation.rs
@@ -0,0 +1,46 @@
+use gateway_plugin_sdk::call::observation::ObserveWebSocketResponse;
+use serde_json::json;
+
+#[test]
+fn websocket_response_observation_keeps_payload_out_of_json_and_rejects_unknown_fields() {
+    let event = ObserveWebSocketResponse {
+        event_id: "req_observed:websocket:2:7".into(),
+        request_id: "req_observed".into(),
+        config_revision: 9,
+        operation: "generate".into(),
+        protocol: "openai".into(),
+        provider: "openai".into(),
+        attempt_index: 2,
+        sequence: 7,
+        payload_included: false,
+        requested_model: Some("public-model".into()),
+        account_id: None,
+        event_type: None,
+    };
+    let encoded = serde_json::to_value(&event).unwrap();
+    assert_eq!(encoded["payload_included"], false);
+    assert!(encoded.get("account_id").is_none());
+    assert!(encoded.get("event_type").is_none());
+    assert!(encoded.get("headers").is_none());
+    assert!(encoded.get("body").is_none());
+    assert_eq!(
+        serde_json::from_value::<ObserveWebSocketResponse>(encoded).unwrap(),
+        event
+    );
+
+    assert!(
+        serde_json::from_value::<ObserveWebSocketResponse>(json!({
+            "event_id":"req_observed:websocket:2:7",
+            "request_id":"req_observed",
+            "config_revision":9,
+            "operation":"generate",
+            "protocol":"openai",
+            "provider":"openai",
+            "attempt_index":2,
+            "sequence":7,
+            "payload_included":false,
+            "content_hint":"must not be accepted"
+        }))
+        .is_err()
+    );
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/policy/mod.rs b/backend/crates/gateway-plugin/sdk/tests/call/policy/mod.rs
new file mode 100644
index 000000000..e67c0f812
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/policy/mod.rs
@@ -0,0 +1,288 @@
+use gateway_plugin_sdk::{
+    SendState,
+    call::policy::{
+        AccountScheduleCandidate, AccountScheduleDecision, AccountScheduleRequest,
+        ModelRouteDecision, ModelRouteRequest, ObserveRequest, PolicyHeader, RequestCost,
+        RequestCostSource, RequestCostStatus, RequestFailure, RequestMoney, RequestOutcome,
+        RequestTerminal, RequestTimings, RequestUsage,
+    },
+};
+use serde_json::json;
+
+fn observation() -> ObserveRequest {
+    ObserveRequest {
+        event_id: "request-42:terminal".into(),
+        request_id: "request-42".into(),
+        config_revision: 7,
+        operation: "generate".into(),
+        requested_model: Some("public-model".into()),
+        client_key_id: Some("key_fixture".into()),
+        account_id: Some("acct_fixture".into()),
+        upstream_model: Some("upstream-model".into()),
+        response_model: Some("reported-model".into()),
+        service_tier: Some("default".into()),
+        provider: None,
+        completed_at_ms: 1234,
+        terminal: None,
+        usage: None,
+    }
+}
+
+#[test]
+fn terminal_outcomes_have_stable_wire_names() {
+    for (outcome, name) in [
+        (RequestOutcome::Succeeded, "succeeded"),
+        (RequestOutcome::Failed, "failed"),
+        (RequestOutcome::Rejected, "rejected"),
+        (RequestOutcome::Cancelled, "cancelled"),
+        (RequestOutcome::Incomplete, "incomplete"),
+    ] {
+        let terminal = RequestTerminal {
+            outcome,
+            send_state: SendState::NotSent,
+            attempt_count: 0,
+            client_status_code: None,
+            error_code: None,
+        };
+        let wire = serde_json::to_value(&terminal).unwrap();
+        assert_eq!(
+            wire,
+            json!({"outcome": name, "send_state": "not_sent", "attempt_count": 0})
+        );
+        assert_eq!(
+            serde_json::from_value::<RequestTerminal>(wire).unwrap(),
+            terminal
+        );
+    }
+}
+
+#[test]
+fn observation_exposes_selected_and_reported_facts_without_inventing_values() {
+    let mut request = observation();
+    let wire = serde_json::to_value(&request).unwrap();
+    assert_eq!(wire["client_key_id"], "key_fixture");
+    assert_eq!(wire["account_id"], "acct_fixture");
+    assert_eq!(wire["upstream_model"], "upstream-model");
+    assert_eq!(wire["response_model"], "reported-model");
+    assert_eq!(wire["service_tier"], "default");
+    request.account_id = None;
+    request.upstream_model = None;
+    request.response_model = None;
+    request.service_tier = None;
+    let wire = serde_json::to_value(request).unwrap();
+    for field in [
+        "account_id",
+        "upstream_model",
+        "response_model",
+        "service_tier",
+    ] {
+        assert!(wire.get(field).is_none(), "unknown {field} must be omitted");
+    }
+}
+
+#[test]
+fn observation_sections_are_independent_and_omitted_when_not_subscribed() {
+    let mut request = observation();
+    request.usage = Some(RequestUsage {
+        input_tokens: Some(0),
+        output_tokens: Some(12),
+        ..RequestUsage::default()
+    });
+    let usage_only = serde_json::to_value(&request).unwrap();
+    assert!(usage_only.get("terminal").is_none());
+    assert!(usage_only.get("provider").is_none());
+    assert_eq!(
+        usage_only["usage"],
+        json!({"input_tokens": 0, "output_tokens": 12})
+    );
+    assert_eq!(
+        serde_json::from_value::<ObserveRequest>(usage_only).unwrap(),
+        request
+    );
+
+    request.usage = None;
+    request.terminal = Some(RequestTerminal {
+        outcome: RequestOutcome::Rejected,
+        send_state: SendState::NotSent,
+        attempt_count: 0,
+        client_status_code: None,
+        error_code: Some("invalid_request".into()),
+    });
+    let lifecycle_only = serde_json::to_value(&request).unwrap();
+    assert!(lifecycle_only.get("usage").is_none());
+    assert_eq!(
+        serde_json::from_value::<ObserveRequest>(lifecycle_only).unwrap(),
+        request
+    );
+
+    request.provider = Some("example-provider".into());
+    request.usage = Some(RequestUsage::default());
+    let combined = serde_json::to_value(&request).unwrap();
+    assert!(combined.get("terminal").is_some());
+    assert_eq!(combined["usage"], json!({}));
+    assert_eq!(
+        serde_json::from_value::<ObserveRequest>(combined).unwrap(),
+        request
+    );
+}
+
+#[test]
+fn missing_usage_is_not_invented_as_zero_or_derived_totals() {
+    let usage: RequestUsage = serde_json::from_value(json!({"input_tokens": 0})).unwrap();
+    assert_eq!(usage.input_tokens, Some(0));
+    assert_eq!(usage.output_tokens, None);
+    assert_eq!(usage.total_tokens, None);
+    assert_eq!(
+        serde_json::to_value(usage).unwrap(),
+        json!({"input_tokens": 0})
+    );
+
+    assert!(serde_json::from_value::<RequestUsage>(json!({"output_tokens": -1})).is_err());
+}
+
+#[test]
+fn observation_contract_rejects_unrecognized_fields_and_outcomes() {
+    let mut request = serde_json::to_value(observation()).unwrap();
+    request["request_body"] = json!({});
+    assert!(serde_json::from_value::<ObserveRequest>(request).is_err());
+    assert!(serde_json::from_value::<RequestUsage>(json!({"custom_tokens": 1})).is_err());
+    assert!(
+        serde_json::from_value::<RequestTerminal>(json!({
+            "outcome": "succeeded", "send_state": "sent", "attempt_count": 1,
+            "internal_error": "not a public observation field"
+        }))
+        .is_err()
+    );
+    assert!(serde_json::from_value::<RequestOutcome>(json!("running")).is_err());
+}
+
+#[test]
+fn cost_timings_and_failure_keep_unknown_facts_explicit_and_safe() {
+    let unknown = RequestCost {
+        status: RequestCostStatus::Unknown,
+        source: RequestCostSource::Unavailable,
+        total: None,
+    };
+    assert_eq!(
+        serde_json::to_value(&unknown).unwrap(),
+        json!({"status":"unknown","source":"unavailable"})
+    );
+    let known = RequestCost {
+        status: RequestCostStatus::Known,
+        source: RequestCostSource::ProviderReported,
+        total: Some(RequestMoney {
+            amount: "0.0123".into(),
+            currency: "USD".into(),
+        }),
+    };
+    assert_eq!(
+        serde_json::from_value::<RequestCost>(serde_json::to_value(&known).unwrap()).unwrap(),
+        known
+    );
+
+    let timings = RequestTimings {
+        first_text_ms: Some(12),
+        latency_ms: Some(34),
+        ..RequestTimings::default()
+    };
+    assert_eq!(
+        serde_json::to_value(&timings).unwrap(),
+        json!({"first_text_ms":12,"latency_ms":34})
+    );
+
+    let failure = RequestFailure {
+        outcome: RequestOutcome::Failed,
+        send_state: SendState::Sent,
+        attempt_count: 2,
+        client_status_code: Some(502),
+        upstream_status_code: Some(503),
+        error_code: Some("upstream_unavailable".into()),
+        retry_after_ms: Some(1_000),
+    };
+    let wire = serde_json::to_value(&failure).unwrap();
+    assert!(wire.get("message").is_none());
+    assert!(wire.get("raw_upstream_error").is_none());
+    let mut unsafe_wire = wire.clone();
+    unsafe_wire["provider_error_code"] = json!("opaque-upstream-value");
+    assert!(serde_json::from_value::<RequestFailure>(unsafe_wire).is_err());
+    assert_eq!(
+        serde_json::from_value::<RequestFailure>(wire).unwrap(),
+        failure
+    );
+
+    let usage = RequestUsage {
+        cost: Some(known),
+        timings: Some(timings),
+        failure: Some(failure),
+        ..RequestUsage::default()
+    };
+    let wire = serde_json::to_value(&usage).unwrap();
+    assert!(wire.get("input_tokens").is_none());
+    assert_eq!(wire["cost"]["total"]["amount"], "0.0123");
+    assert_eq!(wire["timings"]["latency_ms"], 34);
+    assert!(wire["failure"].get("provider_error_code").is_none());
+    assert_eq!(serde_json::from_value::<RequestUsage>(wire).unwrap(), usage);
+}
+
+#[test]
+fn route_and_scheduler_decisions_are_explicit_and_strict() {
+    let route = ModelRouteRequest {
+        request_id: "req_policy".into(),
+        operation: "generate".into(),
+        protocol: "openai".into(),
+        model: "public-model".into(),
+        available_providers: vec!["openai".into()],
+        headers: vec![PolicyHeader {
+            name: "x-feature".into(),
+            value_base64: "b24=".into(),
+        }],
+    };
+    assert_eq!(
+        serde_json::from_value::<ModelRouteRequest>(serde_json::to_value(&route).unwrap()).unwrap(),
+        route
+    );
+    assert_eq!(
+        serde_json::to_value(ModelRouteDecision::Route {
+            provider: Some("openai".into()),
+            model: None,
+        })
+        .unwrap(),
+        json!({"decision":"route","provider":"openai"})
+    );
+    assert!(
+        serde_json::from_value::<ModelRouteDecision>(
+            json!({"decision":"route","provider":"openai","unexpected":true})
+        )
+        .is_err()
+    );
+
+    let schedule = AccountScheduleRequest {
+        request_id: "req_policy".into(),
+        attempt_index: 2,
+        provider: "openai".into(),
+        model: Some("gpt-5".into()),
+        candidates: vec![AccountScheduleCandidate {
+            account_id: "acct_candidate".into(),
+            weight: 10,
+            in_flight: 1,
+            maximum_concurrency: 4,
+            last_started_at_ms: None,
+            quota_reset_at_ms: None,
+            quota_remaining_rank: Some(9_000),
+            failure_rate_basis_points: None,
+            first_output_latency_ms: Some(20),
+        }],
+    };
+    assert_eq!(
+        serde_json::from_value::<AccountScheduleRequest>(serde_json::to_value(&schedule).unwrap())
+            .unwrap(),
+        schedule
+    );
+    assert_eq!(
+        serde_json::to_value(AccountScheduleDecision::Pick {
+            account_id: "acct_candidate".into(),
+        })
+        .unwrap(),
+        json!({"decision":"pick","account_id":"acct_candidate"})
+    );
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/provider/account.rs b/backend/crates/gateway-plugin/sdk/tests/call/provider/account.rs
new file mode 100644
index 000000000..656dd836f
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/provider/account.rs
@@ -0,0 +1,35 @@
+use gateway_plugin_sdk::call::provider::{
+    ProviderDescriptor,
+    account::{AccountConfiguration, AccountConfigurationDescriptor},
+};
+use serde_json::json;
+
+#[test]
+fn account_configuration_is_optional_and_preserves_only_the_declared_shape() {
+    let legacy: ProviderDescriptor =
+        serde_json::from_value(json!({"id":"example", "models":[]})).unwrap();
+    assert!(legacy.account_configuration.is_none());
+
+    let descriptor = AccountConfigurationDescriptor {
+        public_fields: vec!["base_url".into(), "transport".into()],
+    };
+    assert_eq!(
+        serde_json::to_value(&descriptor).unwrap(),
+        json!({"public_fields":["base_url", "transport"]})
+    );
+    assert!(
+        serde_json::from_value::<AccountConfigurationDescriptor>(
+            json!({"public_fields":[], "unexpected":true})
+        )
+        .is_err()
+    );
+
+    let result: AccountConfiguration = serde_json::from_value(json!({
+        "values":{"base_url":"https://example.test", "transport":"http"}
+    }))
+    .unwrap();
+    assert_eq!(
+        serde_json::to_value(result).unwrap(),
+        json!({"values":{"base_url":"https://example.test", "transport":"http"}})
+    );
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/provider/billing.rs b/backend/crates/gateway-plugin/sdk/tests/call/provider/billing.rs
new file mode 100644
index 000000000..7a696cd78
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/provider/billing.rs
@@ -0,0 +1,37 @@
+use gateway_plugin_sdk::call::provider::{CanonicalEvent, ProviderDescriptor};
+use serde_json::json;
+
+#[test]
+fn billing_prices_are_strings_and_the_algorithm_is_versioned() {
+    let value = json!({
+        "id":"example", "models":[],
+        "billing":{"rule":"token_v1", "prices":{"model":{
+            "standard":{"input":"1.25", "output":"2", "cache_read":"0", "cache_write":"0.5"}
+        }}}
+    });
+    let descriptor: ProviderDescriptor = serde_json::from_value(value.clone()).unwrap();
+    assert_eq!(
+        serde_json::to_value(descriptor).unwrap()["billing"],
+        value["billing"]
+    );
+    let mut invalid = value.clone();
+    invalid["billing"]["rule"] = json!("token_v2");
+    assert!(serde_json::from_value::<ProviderDescriptor>(invalid).is_err());
+    let mut invalid = value;
+    invalid["billing"]["prices"]["model"]["standard"]["input"] = json!(1.25);
+    assert!(serde_json::from_value::<ProviderDescriptor>(invalid).is_err());
+}
+
+#[test]
+fn billable_usage_does_not_fill_unknown_token_facts() {
+    let value = json!({
+        "type":"billable_usage", "band":"long_fast",
+        "usage":{"input_tokens":10, "output_tokens":20}
+    });
+    let event: CanonicalEvent = serde_json::from_value(value).unwrap();
+    let serialized = serde_json::to_value(event).unwrap();
+    assert_eq!(serialized["band"], "long_fast");
+    assert_eq!(serialized["usage"]["input_tokens"], 10);
+    assert!(serialized["usage"]["cached_tokens"].is_null());
+    assert!(serialized["usage"]["cache_write_tokens"].is_null());
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/provider/codec.rs b/backend/crates/gateway-plugin/sdk/tests/call/provider/codec.rs
new file mode 100644
index 000000000..cb97d83ed
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/provider/codec.rs
@@ -0,0 +1,109 @@
+use gateway_plugin_sdk::{
+    SendState,
+    call::provider::{
+        CanonicalEvent, ExecutionEvent, ExecutionFailure, ExecutionFailureKind, FailureResponse,
+        MAX_EXECUTION_PAYLOAD_BYTES, WireEvent, WirePayload,
+    },
+};
+use serde_json::json;
+
+#[test]
+fn raw_wire_and_failure_body_are_independent_binary_segments() {
+    let wire = b": comment\r\nevent: error\r\ndata: {\"error\":true}\r\n\r\n".to_vec();
+    let body = (0..=255).cycle().take(64 * 1024).collect::<Vec<u8>>();
+    let event = ExecutionEvent::wire(WireEvent {
+        protocol: "openai".into(),
+        payload: WirePayload::RawSse {
+            frame: wire.clone(),
+        },
+    })
+    .with_failure(ExecutionFailure {
+        kind: ExecutionFailureKind::Unavailable,
+        send_state: SendState::Sent,
+        code: None,
+        retry_after_ms: None,
+        response: Some(FailureResponse {
+            status: 502,
+            content_type: None,
+            body: body.clone(),
+        }),
+    });
+    let bytes = event.encode().unwrap();
+    assert_eq!(&bytes[..4], b"GPE1");
+    assert!(
+        bytes.len() < body.len() + wire.len() + 512,
+        "原始字节不能膨胀为 JSON 数组"
+    );
+    assert!(bytes.ends_with(&body));
+    let decoded = ExecutionEvent::decode(&bytes).unwrap();
+    let WirePayload::RawSse { frame } = decoded.wire.unwrap().payload else {
+        panic!("SSE expected")
+    };
+    assert_eq!(frame, wire);
+    assert_eq!(decoded.failure.unwrap().response.unwrap().body, body);
+}
+
+#[test]
+fn malformed_headers_lengths_truncation_and_extra_segments_are_rejected() {
+    let bytes = ExecutionEvent::canonical(CanonicalEvent::Started {
+        id: "response".into(),
+        model: None,
+    })
+    .encode()
+    .unwrap();
+    for length in 0..bytes.len() {
+        assert!(ExecutionEvent::decode(&bytes[..length]).is_err());
+    }
+    let mut invalid = bytes.clone();
+    invalid.push(0);
+    assert!(ExecutionEvent::decode(&invalid).is_err());
+    // 即使总长度自洽，元数据没有声明 wire 也不能附加字节。
+    invalid[8..12].copy_from_slice(&1u32.to_be_bytes());
+    assert!(ExecutionEvent::decode(&invalid).is_err());
+    for position in [4, 8, 12] {
+        let mut invalid = bytes.clone();
+        invalid[position..position + 4].copy_from_slice(&u32::MAX.to_be_bytes());
+        assert!(ExecutionEvent::decode(&invalid).is_err());
+    }
+    let mut invalid = bytes;
+    invalid[3] = b'2';
+    assert!(ExecutionEvent::decode(&invalid).is_err());
+}
+
+#[test]
+fn metadata_cannot_hide_binary_arrays_or_bypass_the_total_limit() {
+    let metadata = serde_json::to_vec(
+        &json!({"wire":{"protocol":"openai","payload":{"kind":"raw_json","body":[1,2,3]}}}),
+    )
+    .unwrap();
+    let mut bytes = b"GPE1".to_vec();
+    bytes.extend_from_slice(&u32::try_from(metadata.len()).unwrap().to_be_bytes());
+    bytes.extend_from_slice(&[0; 8]);
+    bytes.extend_from_slice(&metadata);
+    assert!(ExecutionEvent::decode(&bytes).is_err());
+    let event = ExecutionEvent::wire(WireEvent {
+        protocol: "openai".into(),
+        payload: WirePayload::RawJson {
+            body: vec![b' '; MAX_EXECUTION_PAYLOAD_BYTES],
+        },
+    });
+    assert!(event.encode().is_err());
+    assert!(ExecutionEvent::decode(&vec![0; MAX_EXECUTION_PAYLOAD_BYTES + 1]).is_err());
+}
+
+#[test]
+fn raw_http_body_uses_the_binary_segment_without_json_validation() {
+    let body = vec![0, 255, b'\n', b'{'];
+    let bytes = ExecutionEvent::wire(WireEvent {
+        protocol: "provider-http".into(),
+        payload: WirePayload::RawBody { body: body.clone() },
+    })
+    .encode()
+    .unwrap();
+    assert!(bytes.ends_with(&body));
+    let decoded = ExecutionEvent::decode(&bytes).unwrap();
+    let WirePayload::RawBody { body: decoded } = decoded.wire.unwrap().payload else {
+        panic!("raw HTTP body expected")
+    };
+    assert_eq!(decoded, body);
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/provider/event.rs b/backend/crates/gateway-plugin/sdk/tests/call/provider/event.rs
new file mode 100644
index 000000000..1ffb3ded0
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/provider/event.rs
@@ -0,0 +1,72 @@
+use gateway_plugin_sdk::call::provider::{
+    CanonicalEvent, ExecutionEvent, FinishReason, ResponseObservation, SessionUpdate, WireEvent,
+    WirePayload,
+};
+use serde_json::json;
+
+#[test]
+fn wire_facts_observation_and_checkpoint_share_one_envelope() {
+    let raw =
+        b"id: upstream\r\nevent: response.completed\r\ndata: {\"result\":true}\r\n\r\n".to_vec();
+    let event = ExecutionEvent::wire(WireEvent {
+        protocol: "openai".into(),
+        payload: WirePayload::Json {
+            event: Some("response.completed".into()),
+            data: json!({"result":true}),
+            id: Some("upstream".into()),
+            retry: None,
+            raw_sse: Some(raw.clone()),
+        },
+    })
+    .with_fact(CanonicalEvent::Completed {
+        id: "upstream-response".into(),
+        model: None,
+        reason: FinishReason::Stop,
+    })
+    .with_observation(ResponseObservation {
+        status: Some(200),
+        ..ResponseObservation::default()
+    })
+    .with_session_update(SessionUpdate {
+        payload: json!({"turn":"opaque"}).as_object().unwrap().clone(),
+    });
+    let bytes = serde_json::to_vec(&event).unwrap();
+    let decoded: ExecutionEvent = serde_json::from_slice(&bytes).unwrap();
+    assert_eq!(decoded.facts.len(), 1);
+    assert_eq!(decoded.observation.unwrap().status, Some(200));
+    assert_eq!(decoded.session_update.unwrap().payload["turn"], "opaque");
+    let WirePayload::Json { raw_sse, .. } = decoded.wire.unwrap().payload else {
+        panic!("JSON wire expected")
+    };
+    assert_eq!(raw_sse.unwrap(), raw);
+}
+
+#[test]
+fn unknown_envelope_and_host_identity_fields_are_rejected() {
+    for value in [
+        json!({"type":"started","id":"old"}),
+        json!({"facts":[],"account_id":"forged"}),
+        json!({"session_update":{"payload":{},"credential_revision":2}}),
+        json!({"observation":{"transport":"forged"}}),
+    ] {
+        assert!(serde_json::from_value::<ExecutionEvent>(value).is_err());
+    }
+}
+
+#[test]
+fn raw_json_remains_bytes_and_missing_usage_is_not_synthesized() {
+    let event = ExecutionEvent::wire(WireEvent {
+        protocol: "openai".into(),
+        payload: WirePayload::RawJson {
+            body: b"{ \"z\": 1, \"a\": 2 }\n".to_vec(),
+        },
+    });
+    let serialized = serde_json::to_value(event).unwrap();
+    assert!(serialized.get("facts").is_none());
+    assert!(serialized["wire"]["payload"]["body"].is_array());
+    let decoded: ExecutionEvent = serde_json::from_value(serialized).unwrap();
+    let WirePayload::RawJson { body } = decoded.wire.unwrap().payload else {
+        panic!("raw JSON expected")
+    };
+    assert_eq!(body, b"{ \"z\": 1, \"a\": 2 }\n");
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/provider/http.rs b/backend/crates/gateway-plugin/sdk/tests/call/provider/http.rs
new file mode 100644
index 000000000..565e5ef49
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/provider/http.rs
@@ -0,0 +1,59 @@
+use gateway_plugin_sdk::call::provider::{
+    OperationKind, PrepareExecution, ProviderDescriptor, ProviderHttpEndpoint, ProviderHttpMethod,
+    ProviderHttpRequest,
+};
+use serde_json::json;
+
+#[test]
+fn http_contract_defaults_to_closed_and_preserves_binary_headers() {
+    let descriptor: ProviderDescriptor = serde_json::from_value(json!({
+        "id": "example",
+        "models": []
+    }))
+    .unwrap();
+    assert!(descriptor.http_endpoints.is_empty());
+
+    let endpoint = ProviderHttpEndpoint {
+        id: "models".into(),
+        methods: vec![ProviderHttpMethod::Get],
+    };
+    let encoded = serde_json::to_value(&endpoint).unwrap();
+    assert_eq!(encoded, json!({"id":"models","methods":["get"]}));
+
+    let request: PrepareExecution = serde_json::from_value(json!({
+        "protocol": "provider-http",
+        "operation": "provider_http",
+        "model": null,
+        "account_id": "account",
+        "credential_revision": 7,
+        "credential": {},
+        "context": {},
+        "request_profile": null,
+        "http_request": {
+            "endpoint": "models",
+            "method": "get",
+            "query": "client_version=1",
+            "headers": [{"name":"x-opaque","value":[255,0,1]}]
+        }
+    }))
+    .unwrap();
+    assert_eq!(request.operation, OperationKind::ProviderHttp);
+    let http = request.http_request.unwrap();
+    assert_eq!(http.endpoint, "models");
+    assert_eq!(http.method, ProviderHttpMethod::Get);
+    assert_eq!(http.headers.len(), 1);
+    assert_eq!(http.headers[0].name, "x-opaque");
+    assert_eq!(http.headers[0].value, vec![255, 0, 1]);
+}
+
+#[test]
+fn unknown_http_fields_remain_rejected() {
+    assert!(
+        serde_json::from_value::<ProviderHttpRequest>(json!({
+            "endpoint":"models",
+            "method":"get",
+            "url":"https://example.invalid"
+        }))
+        .is_err()
+    );
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/provider/input.rs b/backend/crates/gateway-plugin/sdk/tests/call/provider/input.rs
new file mode 100644
index 000000000..cb786981d
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/provider/input.rs
@@ -0,0 +1,45 @@
+use gateway_plugin_sdk::call::provider::{ExecutionEvent, ExecutionInput, PrepareExecution};
+use serde_json::json;
+
+#[test]
+fn preparation_round_trips_large_checkpoint_credentials_and_raw_body_outside_control_metadata() {
+    let request: PrepareExecution = serde_json::from_value(json!({
+        "protocol":"openai","operation":"generate_image","model":"model","account_id":"account","credential_revision":9,
+        "credential":{"key":"test-only-credential"},"context":{"trace":"test-context"},
+        "provider_session_state":{"large":"x".repeat(65524)}
+    })).unwrap();
+    let body: Vec<u8> = (0..=255).cycle().take(32768).collect();
+    let bytes = ExecutionInput {
+        request,
+        body: body.clone(),
+    }
+    .encode()
+    .unwrap();
+    assert!(bytes.len() > 64 * 1024);
+    assert!(bytes.len() < 64 * 1024 + body.len() + 512);
+    assert_eq!(&bytes[..4], b"GPQ1");
+    assert!(bytes.ends_with(&body));
+    let decoded = ExecutionInput::decode(&bytes).unwrap();
+    assert_eq!(decoded.body, body);
+    assert_eq!(decoded.request.credential["key"], "test-only-credential");
+    assert_eq!(
+        decoded.request.provider_session_state.unwrap()["large"]
+            .as_str()
+            .unwrap()
+            .len(),
+        65524
+    );
+    assert!(
+        ExecutionEvent::decode(&bytes).is_err(),
+        "输入和输出不能混用消息类型"
+    );
+    for length in [0, 4, 11, bytes.len() - 1] {
+        assert!(ExecutionInput::decode(&bytes[..length]).is_err());
+    }
+    let mut invalid = bytes.clone();
+    invalid[4..8].copy_from_slice(&u32::MAX.to_be_bytes());
+    assert!(ExecutionInput::decode(&invalid).is_err());
+    let mut invalid = bytes;
+    invalid.push(0);
+    assert!(ExecutionInput::decode(&invalid).is_err());
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/provider/invalidation.rs b/backend/crates/gateway-plugin/sdk/tests/call/provider/invalidation.rs
new file mode 100644
index 000000000..fe4bcad43
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/provider/invalidation.rs
@@ -0,0 +1,16 @@
+use gateway_plugin_sdk::call::provider::account::AccountInvalidation;
+use serde_json::json;
+
+#[test]
+fn invalidations_contain_only_account_identifiers() {
+    for value in [
+        json!({"kind":"unavailable", "account_id":"acct_a"}),
+        json!({"kind":"facts_changed", "account_ids":["acct_a", "acct_b"]}),
+    ] {
+        let event: AccountInvalidation = serde_json::from_value(value.clone()).unwrap();
+        assert_eq!(serde_json::to_value(event).unwrap(), value);
+        let mut invalid = value;
+        invalid["credential"] = json!({"key":"test-only"});
+        assert!(serde_json::from_value::<AccountInvalidation>(invalid).is_err());
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/provider/maintenance.rs b/backend/crates/gateway-plugin/sdk/tests/call/provider/maintenance.rs
new file mode 100644
index 000000000..41d55ac9f
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/provider/maintenance.rs
@@ -0,0 +1,32 @@
+use gateway_plugin_sdk::call::provider::RequestProfileRefresh;
+use serde_json::Value;
+
+#[test]
+fn refresh_roundtrips_without_exposing_provider_documents_in_debug() {
+    let refresh = RequestProfileRefresh {
+        sequence: 2,
+        profiles: super::request_profile::descriptor(),
+    };
+    let encoded = serde_json::to_value(&refresh).unwrap();
+    assert_eq!(encoded["sequence"], 2);
+    let decoded: RequestProfileRefresh = serde_json::from_value(encoded).unwrap();
+    assert_eq!(decoded, refresh);
+    let debug = format!("{refresh:?}");
+    assert!(debug.contains("sequence: 2"));
+    assert!(!debug.contains("sensitive-shape"));
+    assert!(!debug.contains("authorizationShape"));
+}
+
+#[test]
+fn refresh_rejects_unknown_fields() {
+    let mut encoded = serde_json::to_value(RequestProfileRefresh {
+        sequence: 2,
+        profiles: super::request_profile::descriptor(),
+    })
+    .unwrap();
+    encoded
+        .as_object_mut()
+        .unwrap()
+        .insert("unexpected".into(), Value::Bool(true));
+    assert!(serde_json::from_value::<RequestProfileRefresh>(encoded).is_err());
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/provider/mod.rs b/backend/crates/gateway-plugin/sdk/tests/call/provider/mod.rs
new file mode 100644
index 000000000..bfadb46c9
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/provider/mod.rs
@@ -0,0 +1,11 @@
+mod account;
+mod billing;
+mod codec;
+mod event;
+mod http;
+mod input;
+mod invalidation;
+mod maintenance;
+mod models;
+mod quota;
+mod request_profile;
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/provider/models.rs b/backend/crates/gateway-plugin/sdk/tests/call/provider/models.rs
new file mode 100644
index 000000000..eb7d8c305
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/provider/models.rs
@@ -0,0 +1,133 @@
+use gateway_plugin_sdk::call::provider::{ProviderDescriptor, models::AccountModels};
+use serde_json::json;
+
+#[test]
+fn native_continuation_is_an_explicit_model_feature() {
+    use gateway_plugin_sdk::call::provider::{ModelDescriptor, ModelFeature};
+
+    let descriptor: ModelDescriptor = serde_json::from_value(json!({
+        "id":"continuation-model", "operations":["generate"], "features":["native_continuation"]
+    }))
+    .unwrap();
+    assert_eq!(descriptor.features, [ModelFeature::NativeContinuation]);
+    assert_eq!(
+        serde_json::to_value(&descriptor).unwrap()["features"],
+        json!(["native_continuation"])
+    );
+    let plain: ModelDescriptor = serde_json::from_value(json!({
+        "id":"plain-model", "operations":["generate"]
+    }))
+    .unwrap();
+    assert!(plain.features.is_empty());
+}
+
+#[test]
+fn account_discovery_is_optional_and_cannot_smuggle_account_writes() {
+    let static_provider: ProviderDescriptor =
+        serde_json::from_value(json!({"id":"example", "models":[]})).unwrap();
+    assert!(static_provider.model_discovery.is_none());
+    let provider: ProviderDescriptor = serde_json::from_value(json!({"id":"example", "models":[], "model_discovery":{"include_static":false,"cache_ttl_seconds":60}})).unwrap();
+    assert!(!provider.model_discovery.unwrap().include_static);
+    let mut catalog = json!({"models":[], "exhaustive":true});
+    assert!(
+        serde_json::from_value::<AccountModels>(catalog.clone())
+            .unwrap()
+            .exhaustive
+    );
+    catalog["credential"] = json!({"key":"test-only"});
+    assert!(serde_json::from_value::<AccountModels>(catalog).is_err());
+}
+
+#[test]
+fn continuation_state_compatibility_is_optional_and_closed() {
+    let legacy: ProviderDescriptor =
+        serde_json::from_value(json!({"id":"example", "models":[]})).unwrap();
+    assert!(legacy.continuation_state.is_none());
+
+    let provider: ProviderDescriptor = serde_json::from_value(json!({
+        "id":"example",
+        "models":[],
+        "continuation_state":{
+            "format":"example.responses",
+            "write_version":2,
+            "readable_versions":[1,2]
+        }
+    }))
+    .unwrap();
+    let state = provider.continuation_state.unwrap();
+    assert_eq!(state.format, "example.responses");
+    assert_eq!(state.write_version, 2);
+    assert_eq!(state.readable_versions, [1, 2]);
+
+    assert!(
+        serde_json::from_value::<ProviderDescriptor>(json!({
+            "id":"example",
+            "models":[],
+            "continuation_state":{
+                "format":"example.responses",
+                "write_version":1,
+                "readable_versions":[1],
+                "artifact":"must-not-be-plugin-selected"
+            }
+        }))
+        .is_err()
+    );
+}
+
+#[test]
+fn catalog_completeness_must_be_explicit() {
+    assert!(serde_json::from_value::<AccountModels>(json!({"models":[]})).is_err());
+    let discovered: AccountModels =
+        serde_json::from_value(json!({"models":[],"exhaustive":false})).unwrap();
+    assert!(!discovered.exhaustive);
+}
+
+#[test]
+fn prepared_account_facts_are_optional_and_closed() {
+    let legacy: AccountModels =
+        serde_json::from_value(json!({"models":[],"exhaustive":true})).unwrap();
+    assert!(legacy.prepared_account_facts.is_none());
+
+    let prepared: AccountModels = serde_json::from_value(json!({
+        "models":[],
+        "exhaustive":true,
+        "prepared_account_facts":{
+            "name":"refreshed",
+            "authentication_kind":"oauth",
+            "material":{"access_token":"controlled-test-value"},
+            "email":null,
+            "upstream_user_id":null,
+            "upstream_account_id":null,
+            "plan_type":null,
+            "access_token_expires_at_ms":null,
+            "next_refresh_at_ms":null
+        }
+    }))
+    .unwrap();
+    assert_eq!(
+        prepared
+            .prepared_account_facts
+            .as_ref()
+            .map(|facts| facts.name.as_str()),
+        Some("refreshed")
+    );
+    assert!(
+        serde_json::from_value::<AccountModels>(json!({
+            "models":[],
+            "exhaustive":true,
+            "prepared_account_facts":{
+                "name":"refreshed",
+                "authentication_kind":"oauth",
+                "material":{},
+                "email":null,
+                "upstream_user_id":null,
+                "upstream_account_id":null,
+                "plan_type":null,
+                "access_token_expires_at_ms":null,
+                "next_refresh_at_ms":null,
+                "account_id":"forged"
+            }
+        }))
+        .is_err()
+    );
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/provider/quota.rs b/backend/crates/gateway-plugin/sdk/tests/call/provider/quota.rs
new file mode 100644
index 000000000..d4ba3e4bc
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/provider/quota.rs
@@ -0,0 +1,48 @@
+use gateway_plugin_sdk::call::provider::{ExecutionEvent, ResponseObservation};
+use serde_json::json;
+
+#[test]
+fn quota_forecast_round_trips_without_changing_execution_facts() {
+    let value = json!({"observation":{"quota_forecast":{
+        "plan_type":"service-plan",
+        "windows":[{"key":"week","group":"chat","limit_id":"chat","role":"secondary",
+            "account_wide":true,"window_seconds":604800,"used_percent":0.0,"reset_at_ms":1800000000000_i64}]
+    }}});
+    let event: ExecutionEvent = serde_json::from_value(value.clone()).unwrap();
+    let decoded = ExecutionEvent::decode(&event.encode().unwrap()).unwrap();
+    assert!(decoded.facts.is_empty());
+    assert!(decoded.wire.is_none());
+    let observation = decoded.observation.unwrap();
+    let forecast = observation.quota_forecast.as_ref().unwrap();
+    assert_eq!(forecast.windows[0].used_percent, 0.0);
+    assert_eq!(
+        serde_json::to_value(observation).unwrap()["quota_forecast"],
+        value["observation"]["quota_forecast"]
+    );
+}
+
+#[test]
+fn quota_forecast_is_optional_and_rejects_arbitrary_identity_or_raw_documents() {
+    let legacy: ResponseObservation = serde_json::from_value(json!({"status":200})).unwrap();
+    assert!(legacy.quota_forecast.is_none());
+    assert!(
+        serde_json::to_value(legacy)
+            .unwrap()
+            .get("quota_forecast")
+            .is_none()
+    );
+    for field in [
+        "account_id",
+        "provider_id",
+        "credential",
+        "provider_data",
+        "headers",
+    ] {
+        let mut value = json!({"plan_type":null,"windows":[]});
+        value[field] = json!("private");
+        assert!(
+            serde_json::from_value::<ResponseObservation>(json!({"quota_forecast":value})).is_err(),
+            "{field}"
+        );
+    }
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/call/provider/request_profile.rs b/backend/crates/gateway-plugin/sdk/tests/call/provider/request_profile.rs
new file mode 100644
index 000000000..0edda7cef
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/call/provider/request_profile.rs
@@ -0,0 +1,77 @@
+use gateway_plugin_sdk::call::provider::{
+    RequestProfileAttribute, RequestProfileDescriptor, RequestProfileOption,
+    RequestProfilePresentation, RequestProfileRelease, RequestProfileReleaseStatus,
+    RequestProfileTarget,
+};
+use serde_json::{Map, Value, json};
+
+fn object(value: Value) -> Map<String, Value> {
+    value.as_object().expect("object fixture").clone()
+}
+
+pub(super) fn descriptor() -> RequestProfileDescriptor {
+    let configuration = object(json!({"channel": "stable"}));
+    RequestProfileDescriptor {
+        default_configuration: configuration.clone(),
+        options: vec![RequestProfileOption {
+            id: "stable".to_owned(),
+            label: "稳定版".to_owned(),
+            description: Some("跟随已核验版本".to_owned()),
+            configuration,
+            resolved: object(json!({"authorizationShape": "sensitive-shape"})),
+            presentation: RequestProfilePresentation {
+                product: "Example CLI".to_owned(),
+                version: "1.2.3".to_owned(),
+                build: Some("123".to_owned()),
+                target: RequestProfileTarget {
+                    os_type: "linux".to_owned(),
+                    os_version: "6.8".to_owned(),
+                    arch: "x86_64".to_owned(),
+                    terminal: "headless".to_owned(),
+                },
+                user_agent: "Example CLI/1.2.3".to_owned(),
+                attributes: vec![RequestProfileAttribute {
+                    label: "通道".to_owned(),
+                    value: "stable".to_owned(),
+                }],
+                verified_at_ms: Some(1_700_000_000_000),
+                release: Some(RequestProfileRelease {
+                    status: RequestProfileReleaseStatus::Current,
+                    checked_at_ms: Some(1_700_000_000_100),
+                    latest_version: Some("1.2.3".to_owned()),
+                    latest_build: Some("123".to_owned()),
+                    published_at_ms: None,
+                    minimum_system_version: None,
+                    hardware_requirements: None,
+                    download_url: None,
+                    download_size: None,
+                    signature_present: Some(true),
+                    error: None,
+                }),
+            },
+        }],
+    }
+}
+
+#[test]
+fn request_profile_descriptor_roundtrips_without_exposing_provider_documents_in_debug() {
+    let descriptor = descriptor();
+    let encoded = serde_json::to_value(&descriptor).expect("encode descriptor");
+    let decoded: RequestProfileDescriptor =
+        serde_json::from_value(encoded).expect("decode descriptor");
+    assert_eq!(decoded, descriptor);
+
+    let debug = format!("{descriptor:?}");
+    assert!(!debug.contains("sensitive-shape"));
+    assert!(debug.contains("[REDACTED]"));
+}
+
+#[test]
+fn request_profile_descriptor_rejects_unknown_fields() {
+    let mut encoded = serde_json::to_value(descriptor()).expect("encode descriptor");
+    encoded
+        .as_object_mut()
+        .expect("descriptor object")
+        .insert("unexpected".to_owned(), Value::Bool(true));
+    assert!(serde_json::from_value::<RequestProfileDescriptor>(encoded).is_err());
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/client/mod.rs b/backend/crates/gateway-plugin/sdk/tests/client/mod.rs
new file mode 100644
index 000000000..37047b2dc
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/client/mod.rs
@@ -0,0 +1,2 @@
+mod plugin;
+mod session;
diff --git a/backend/crates/gateway-plugin/sdk/tests/client/plugin/mod.rs b/backend/crates/gateway-plugin/sdk/tests/client/plugin/mod.rs
new file mode 100644
index 000000000..9cce7751e
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/client/plugin/mod.rs
@@ -0,0 +1,562 @@
+use std::{
+    collections::BTreeMap,
+    sync::{
+        Arc,
+        atomic::{AtomicUsize, Ordering},
+    },
+    time::Duration,
+};
+
+use gateway_plugin_sdk::{
+    CallContext, Contributions, ErrorCode, Frame, Handshake, Message, PROTOCOL_VERSION, Stage,
+    call::{
+        auth::ImportedCredentials,
+        host::StateMigrationResult,
+        management::{
+            CommandDescriptor, CommandInvocation, CommandRegistration, CommandResult,
+            ManagementRegistration, ManagementRequest, ManagementResponse, ManagementRoute,
+        },
+        provider::{PreparedExecution, ProbeOperation, ProviderDescriptor, Registration},
+    },
+    client::{
+        AuthorError, Empty, PluginBuilder, PluginHandler, PluginSession, ResponseStream,
+        SessionConfig, SessionError, TypedReply, methods, read_frame, write_frame,
+    },
+};
+use serde_json::{Value, json};
+use tokio::{
+    io::{DuplexStream, ReadHalf, WriteHalf},
+    task::JoinHandle,
+};
+
+const MAXIMUM_FRAME_BYTES: usize = 64 * 1024;
+
+fn author_manifest(contributes: Value, state: Value) -> Vec<u8> {
+    serde_json::to_vec(&json!({
+        "manifestVersion": 3,
+        "name": "composed",
+        "displayName": "Composed",
+        "publisher": "9acme",
+        "version": "1.0.0",
+        "description": "Composed plugin",
+        "license": "MIT",
+        "engines": {"codex-proxy-rs": "*"},
+        "main": "bin/plugin",
+        "runtime": "trustedProcess",
+        "contributes": contributes,
+        "state": state,
+    }))
+    .unwrap()
+}
+
+fn management_registration() -> ManagementRegistration {
+    ManagementRegistration {
+        routes: vec![ManagementRoute {
+            method: "POST".into(),
+            path: "echo".into(),
+            request_content_types: vec!["application/octet-stream".into()],
+            response_content_types: vec!["application/octet-stream".into()],
+        }],
+        resources: Vec::new(),
+        pages: Vec::new(),
+        callbacks: Vec::new(),
+    }
+}
+
+fn command_registration() -> CommandRegistration {
+    CommandRegistration {
+        commands: vec![CommandDescriptor {
+            name: "echo".into(),
+            description: "Echo a value".into(),
+            parameters: Vec::new(),
+        }],
+    }
+}
+
+fn with_executor_handlers(builder: PluginBuilder) -> PluginBuilder {
+    builder
+        .on(methods::PREPARE_EXECUTION, |_| async {
+            Ok(TypedReply::new(PreparedExecution {
+                token: "prepared".into(),
+                transport: "http_sse".into(),
+            }))
+        })
+        .unwrap()
+        .on(methods::EXECUTE, |_| async {
+            Ok(TypedReply::new(Empty {}).with_stream(ResponseStream::from_chunks(Vec::new())))
+        })
+        .unwrap()
+        .on(methods::DISCARD_EXECUTION, |_| async {
+            Ok(TypedReply::new(Empty {}))
+        })
+        .unwrap()
+        .on(methods::CONNECTION_TEST, |_| async {
+            Ok(TypedReply::new(ProbeOperation {
+                protocol: "openai".into(),
+                body: serde_json::Map::new(),
+            }))
+        })
+        .unwrap()
+}
+
+#[tokio::test]
+async fn composed_plugin_registers_and_dispatches_multiple_typed_entries() {
+    let source = author_manifest(
+        json!({
+            "management": {},
+            "command_line": {},
+        }),
+        json!([]),
+    );
+    let manifest = gateway_plugin_sdk::Manifest::from_author_slice(&source).unwrap();
+    let contributions = manifest.contributes.clone();
+    let management_calls = Arc::new(AtomicUsize::new(0));
+    let management_calls_for_handler = Arc::clone(&management_calls);
+    let plugin = PluginBuilder::from_manifest(manifest)
+        .unwrap()
+        .management(management_registration(), move |call| {
+            let management_calls = Arc::clone(&management_calls_for_handler);
+            async move {
+                management_calls.fetch_add(1, Ordering::Relaxed);
+                Ok(TypedReply::new(ManagementResponse {
+                    status: 201,
+                    content_type: call
+                        .request
+                        .content_type
+                        .unwrap_or_else(|| "application/octet-stream".into()),
+                })
+                .with_payload(call.payload))
+            }
+        })
+        .unwrap()
+        .command_line(command_registration(), |call| async move {
+            Ok(TypedReply::new(CommandResult {
+                stdout: call.request.name,
+                stderr: String::new(),
+                exit_code: 0,
+                accounts: Vec::new(),
+            }))
+        })
+        .unwrap()
+        .build()
+        .unwrap();
+    let (mut host, task) = start_session(plugin, contributions.clone()).await;
+
+    send_call(
+        &mut host,
+        1,
+        "plugin.register",
+        Stage::Registration,
+        json!({}),
+        Vec::new(),
+    )
+    .await;
+    let (result, payload) = unwrap_result(receive(&mut host).await, 1);
+    let registration: Registration = serde_json::from_value(result).unwrap();
+    assert_eq!(registration.contributes, contributions);
+    assert!(registration.provider.is_none());
+    assert!(payload.is_empty());
+
+    send_call(
+        &mut host,
+        3,
+        "management.register",
+        Stage::Registration,
+        json!({}),
+        Vec::new(),
+    )
+    .await;
+    let (result, payload) = unwrap_result(receive(&mut host).await, 3);
+    assert_eq!(result, json!({}));
+    let registration: ManagementRegistration = serde_json::from_slice(&payload).unwrap();
+    assert_eq!(registration.routes.len(), 1);
+    assert_eq!(registration.routes[0].path, "echo");
+
+    send_call(
+        &mut host,
+        5,
+        "management.handle",
+        Stage::Management,
+        serde_json::to_value(ManagementRequest {
+            method: "POST".into(),
+            path: "echo".into(),
+            query: String::new(),
+            content_type: Some("text/plain".into()),
+        })
+        .unwrap(),
+        b"typed body".to_vec(),
+    )
+    .await;
+    let (result, payload) = unwrap_result(receive(&mut host).await, 5);
+    let response: ManagementResponse = serde_json::from_value(result).unwrap();
+    assert_eq!(response.status, 201);
+    assert_eq!(response.content_type, "text/plain");
+    assert_eq!(payload, b"typed body");
+    assert_eq!(management_calls.load(Ordering::Relaxed), 1);
+
+    send_call(
+        &mut host,
+        7,
+        "command_line.register",
+        Stage::Registration,
+        json!({}),
+        Vec::new(),
+    )
+    .await;
+    let (result, payload) = unwrap_result(receive(&mut host).await, 7);
+    assert_eq!(result, json!({}));
+    let registration: CommandRegistration = serde_json::from_slice(&payload).unwrap();
+    assert_eq!(registration.commands.len(), 1);
+    assert_eq!(registration.commands[0].name, "echo");
+
+    let invocation = CommandInvocation {
+        name: "echo".into(),
+        arguments: BTreeMap::new(),
+    };
+    send_call(
+        &mut host,
+        9,
+        "command_line.execute",
+        Stage::CommandLine,
+        json!({}),
+        serde_json::to_vec(&invocation).unwrap(),
+    )
+    .await;
+    let (result, payload) = unwrap_result(receive(&mut host).await, 9);
+    assert_eq!(result, json!({}));
+    let output: CommandResult = serde_json::from_slice(&payload).unwrap();
+    assert_eq!(output.stdout, "echo");
+    assert_eq!(output.exit_code, 0);
+
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn typed_dispatch_rejects_wrong_stage_and_payload_shape_before_handler() {
+    let source = author_manifest(json!({"command_line": {}}), json!([]));
+    let manifest = gateway_plugin_sdk::Manifest::from_author_slice(&source).unwrap();
+    let contributions = manifest.contributes.clone();
+    let calls = Arc::new(AtomicUsize::new(0));
+    let calls_for_handler = Arc::clone(&calls);
+    let plugin = PluginBuilder::from_manifest(manifest)
+        .unwrap()
+        .command_line(command_registration(), move |_| {
+            let calls = Arc::clone(&calls_for_handler);
+            async move {
+                calls.fetch_add(1, Ordering::Relaxed);
+                Ok(TypedReply::new(CommandResult {
+                    stdout: String::new(),
+                    stderr: String::new(),
+                    exit_code: 0,
+                    accounts: Vec::new(),
+                }))
+            }
+        })
+        .unwrap()
+        .build()
+        .unwrap();
+    let (mut host, task) = start_session(plugin, contributions).await;
+    let invocation = serde_json::to_vec(&CommandInvocation {
+        name: "echo".into(),
+        arguments: BTreeMap::new(),
+    })
+    .unwrap();
+
+    send_call(
+        &mut host,
+        1,
+        "command_line.execute",
+        Stage::Management,
+        json!({}),
+        invocation.clone(),
+    )
+    .await;
+    assert_invalid_input(receive(&mut host).await, 1);
+
+    send_call(
+        &mut host,
+        3,
+        "command_line.execute",
+        Stage::CommandLine,
+        json!({"name": "must-not-be-control-metadata"}),
+        invocation,
+    )
+    .await;
+    assert_invalid_input(receive(&mut host).await, 3);
+
+    send_call(
+        &mut host,
+        5,
+        "command_line.execute",
+        Stage::CommandLine,
+        json!({}),
+        b"not json".to_vec(),
+    )
+    .await;
+    assert_invalid_input(receive(&mut host).await, 5);
+    assert_eq!(calls.load(Ordering::Relaxed), 0);
+
+    shutdown(&mut host, task).await;
+}
+
+#[test]
+fn build_reports_missing_declared_handler() {
+    let source = author_manifest(json!({"management": {}}), json!([]));
+    let result = PluginBuilder::from_json(&source).unwrap().build();
+    assert!(matches!(
+        result,
+        Err(AuthorError::MissingMethod("management.register"))
+    ));
+}
+
+#[test]
+fn state_migration_is_a_base_method_gated_by_the_state_declaration() {
+    let state = json!([{
+        "namespace": "documents",
+        "schemaVersion": 2,
+        "schema": {"type": "object"},
+        "maximumRecords": 16,
+        "maximumBytes": 4096,
+        "maximumValueBytes": 1024,
+        "migratesFrom": [1]
+    }]);
+    let source = author_manifest(json!({}), state);
+    let missing = PluginBuilder::from_json(&source).unwrap().build();
+    assert!(matches!(
+        missing,
+        Err(AuthorError::MissingMethod("plugin.state.migrate"))
+    ));
+
+    let plugin = PluginBuilder::from_json(&source)
+        .unwrap()
+        .on(methods::STATE_MIGRATE, |_| async {
+            Ok(TypedReply::new(StateMigrationResult {
+                changes: Vec::new(),
+            }))
+        })
+        .unwrap()
+        .build();
+    assert!(plugin.is_ok());
+
+    let source_without_migration = author_manifest(json!({}), json!([]));
+    let undeclared = PluginBuilder::from_json(&source_without_migration)
+        .unwrap()
+        .on(methods::STATE_MIGRATE, |_| async {
+            Ok(TypedReply::new(StateMigrationResult {
+                changes: Vec::new(),
+            }))
+        });
+    assert!(matches!(
+        undeclared,
+        Err(AuthorError::Method("plugin.state.migrate"))
+    ));
+}
+
+#[test]
+fn provider_group_requires_both_descriptor_and_execution_handlers() {
+    let source = author_manifest(
+        json!({
+            "provider": {
+                "capabilities": [],
+                "inputFormats": ["openai"],
+                "outputFormats": ["openai"]
+            }
+        }),
+        json!([]),
+    );
+    let descriptor: ProviderDescriptor = serde_json::from_value(json!({
+        "id": "echo",
+        "models": []
+    }))
+    .unwrap();
+    let missing_handler = PluginBuilder::from_json(&source)
+        .unwrap()
+        .provider(descriptor)
+        .build();
+    assert!(matches!(
+        missing_handler,
+        Err(AuthorError::MissingMethod("provider.prepare"))
+    ));
+
+    let missing_descriptor =
+        with_executor_handlers(PluginBuilder::from_json(&source).unwrap()).build();
+    assert!(matches!(missing_descriptor, Err(AuthorError::Provider)));
+}
+
+#[test]
+fn provider_descriptor_rejects_handlers_for_unadvertised_operations() {
+    let source = author_manifest(
+        json!({
+            "provider": {
+                "capabilities": ["authentication"],
+                "inputFormats": ["openai"],
+                "outputFormats": ["openai"]
+            }
+        }),
+        json!([]),
+    );
+    let descriptor: ProviderDescriptor = serde_json::from_value(json!({
+        "id": "echo",
+        "models": [],
+        "credential_operations": ["import"]
+    }))
+    .unwrap();
+    let plugin = with_executor_handlers(PluginBuilder::from_json(&source).unwrap())
+        .on(methods::IMPORT_CREDENTIALS, |_| async {
+            Ok(TypedReply::new(ImportedCredentials {
+                accounts: Vec::new(),
+            }))
+        })
+        .unwrap()
+        .on(methods::EXPORT_CREDENTIALS, |_| async {
+            Ok(TypedReply::new(serde_json::Map::new()))
+        })
+        .unwrap()
+        .provider(descriptor)
+        .build();
+    assert!(matches!(plugin, Err(AuthorError::Provider)));
+}
+
+struct HostPeer {
+    reader: ReadHalf<DuplexStream>,
+    writer: WriteHalf<DuplexStream>,
+}
+
+async fn start_session<H: PluginHandler + 'static>(
+    handler: H,
+    contributes: Contributions,
+) -> (HostPeer, JoinHandle<Result<(), SessionError>>) {
+    let (host, plugin) = tokio::io::duplex(MAXIMUM_FRAME_BYTES * 2);
+    let (plugin_reader, plugin_writer) = tokio::io::split(plugin);
+    let task = tokio::spawn(async move {
+        PluginSession::accept(
+            plugin_reader,
+            plugin_writer,
+            SessionConfig {
+                maximum_frame_bytes: MAXIMUM_FRAME_BYTES,
+                maximum_calls: 4,
+                maximum_callbacks: 4,
+                maximum_buffered_stream_chunks: 16,
+                handshake_timeout: Duration::from_secs(1),
+                maximum_call_timeout: Duration::from_secs(2),
+            },
+        )
+        .await?
+        .run(handler)
+        .await
+    });
+    let (mut reader, mut writer) = tokio::io::split(host);
+    write_frame(
+        &mut writer,
+        &Frame::control(Message::Hello {
+            handshake: Handshake {
+                protocol_version: PROTOCOL_VERSION,
+                artifact_sha256: "a".repeat(64),
+                plugin_id: "9acme.composed".into(),
+                instance_id: "test-instance".into(),
+                generation: 1,
+                incarnation: "test-incarnation".into(),
+                configuration: json!({}),
+                permissions: Vec::new(),
+                contributes,
+            },
+        }),
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+    let ready = read_frame(&mut reader, MAXIMUM_FRAME_BYTES).await.unwrap();
+    assert!(matches!(
+        ready,
+        Frame {
+            message: Message::Ready {
+                protocol_version: PROTOCOL_VERSION,
+                ref incarnation,
+            },
+            ref payload,
+        } if incarnation == "test-incarnation" && payload.is_empty()
+    ));
+    (HostPeer { reader, writer }, task)
+}
+
+async fn send_call(
+    host: &mut HostPeer,
+    id: u64,
+    method: &str,
+    stage: Stage,
+    params: Value,
+    payload: Vec<u8>,
+) {
+    write_frame(
+        &mut host.writer,
+        &Frame {
+            message: Message::Call {
+                id,
+                method: method.into(),
+                context: CallContext {
+                    call_id: id,
+                    instance_id: "test-instance".into(),
+                    generation: 1,
+                    incarnation: "test-incarnation".into(),
+                    stage,
+                    timeout_ms: 1_000,
+                    resource_scope_id: format!("scope-{id}"),
+                    request_id: None,
+                    attempt_id: None,
+                    account_id: None,
+                    credential_revision: None,
+                },
+                params,
+            },
+            payload,
+        },
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+}
+
+async fn receive(host: &mut HostPeer) -> Frame {
+    tokio::time::timeout(
+        Duration::from_secs(1),
+        read_frame(&mut host.reader, MAXIMUM_FRAME_BYTES),
+    )
+    .await
+    .expect("plugin response timed out")
+    .expect("plugin response frame must be valid")
+}
+
+fn unwrap_result(frame: Frame, expected_id: u64) -> (Value, Vec<u8>) {
+    match frame {
+        Frame {
+            message: Message::Result { id, result },
+            payload,
+        } if id == expected_id => (result, payload),
+        unexpected => panic!("unexpected plugin response: {unexpected:?}"),
+    }
+}
+
+fn assert_invalid_input(frame: Frame, expected_id: u64) {
+    assert!(matches!(
+        frame,
+        Frame {
+            message: Message::Error { id, error },
+            ref payload,
+        } if id == expected_id && error.code == ErrorCode::InvalidInput && payload.is_empty()
+    ));
+}
+
+async fn shutdown(host: &mut HostPeer, task: JoinHandle<Result<(), SessionError>>) {
+    write_frame(
+        &mut host.writer,
+        &Frame::control(Message::Shutdown),
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+    tokio::time::timeout(Duration::from_secs(1), task)
+        .await
+        .expect("plugin session did not shut down")
+        .expect("plugin session task panicked")
+        .expect("plugin session shutdown failed");
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/client/session.rs b/backend/crates/gateway-plugin/sdk/tests/client/session.rs
new file mode 100644
index 000000000..3a69087b1
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/client/session.rs
@@ -0,0 +1,1422 @@
+use std::{
+    future::pending,
+    num::NonZeroUsize,
+    sync::{
+        Arc,
+        atomic::{AtomicBool, AtomicUsize, Ordering},
+    },
+    time::Duration,
+};
+
+use gateway_plugin_sdk::{
+    CallContext, Capability, ContributionDeclaration, Contributions, ErrorCode, Frame, FrameError,
+    Handshake, Message, PROTOCOL_VERSION, PluginFault, Stage,
+    call::middleware::{
+        BODY_READ_METHOD, HANDLE_METHOD, MiddlewareBodyDisposition, MiddlewareBodyFrame,
+        MiddlewareBodyFraming, MiddlewareBodyHandle, MiddlewareBodyReadResult, MiddlewareHeader,
+        MiddlewareHeaderMutation, MiddlewareMount, MiddlewareNextRequest, MiddlewareNextResponse,
+        MiddlewareRequestBody, MiddlewareRequestHead, MiddlewareResponseBody,
+        MiddlewareResponseHead, MiddlewareTransport, NEXT_METHOD,
+    },
+    client::{
+        CallFuture, CallReply, MiddlewareCall, MiddlewarePlugin, PluginCall, PluginHandler,
+        PluginSession, ResponseStream, SessionConfig, SessionError, read_frame, write_frame,
+    },
+};
+use serde_json::{Value, json};
+use tokio::{
+    io::{AsyncWriteExt, DuplexStream, ReadHalf, WriteHalf},
+    task::JoinHandle,
+};
+
+const MAXIMUM_FRAME_BYTES: usize = 64 * 1024;
+
+#[tokio::test]
+async fn binary_payload_round_trips_without_json_encoding() {
+    let frame = Frame {
+        message: Message::Stream {
+            id: 17,
+            sequence: 2,
+        },
+        payload: vec![0, 255, 13, 10, 128],
+    };
+    let mut bytes = Vec::new();
+    write_frame(&mut bytes, &frame, 1024).await.unwrap();
+    assert!(bytes.ends_with(&frame.payload));
+    assert_eq!(
+        read_frame(&mut bytes.as_slice(), 1024).await.unwrap(),
+        frame
+    );
+}
+
+#[tokio::test]
+async fn malicious_lengths_fail_before_reading_or_allocating_payload() {
+    let bytes = [0, 0, 0, 1, 255, 255, 255, 255];
+    assert!(matches!(
+        read_frame(&mut bytes.as_slice(), 1024).await,
+        Err(FrameError::Length)
+    ));
+}
+
+#[tokio::test]
+async fn truncated_frame_never_becomes_a_successful_message() {
+    let mut bytes = Vec::new();
+    write_frame(&mut bytes, &Frame::control(Message::Cancel { id: 3 }), 1024)
+        .await
+        .unwrap();
+    bytes.pop();
+    assert!(matches!(
+        read_frame(&mut bytes.as_slice(), 1024).await,
+        Err(FrameError::Io(_))
+    ));
+}
+
+#[derive(Clone, Default)]
+struct TestHandler {
+    lifecycle: Arc<LifecycleState>,
+    cancel_delay: Option<Duration>,
+}
+
+#[derive(Default)]
+struct LifecycleState {
+    cancel_started: AtomicBool,
+    cancelled: AtomicUsize,
+    quiesced: AtomicBool,
+    shutdown: AtomicBool,
+}
+
+impl PluginHandler for TestHandler {
+    fn call(&self, call: PluginCall) -> CallFuture<'_> {
+        Box::pin(async move {
+            match call.method.as_str() {
+                "echo" => Ok(CallReply::unary(call.params, call.payload)),
+                "slow" => {
+                    tokio::time::sleep(Duration::from_millis(80)).await;
+                    Ok(CallReply::unary(call.params, call.payload))
+                }
+                "callback" => {
+                    let reply = call
+                        .host
+                        .call("host.log", call.params, call.payload)
+                        .await
+                        .map_err(SessionError::into_plugin_fault)?;
+                    Ok(CallReply::unary(reply.result, reply.payload))
+                }
+                "stream" => Ok(CallReply::stream(
+                    json!({"stream": true}),
+                    Vec::new(),
+                    ResponseStream::from_chunks(vec![b"abcd".to_vec(), b"efgh".to_vec()]),
+                )),
+                "long_stream" => Ok(CallReply::stream(
+                    json!({"stream": true}),
+                    Vec::new(),
+                    ResponseStream::from_chunks(vec![b"x".to_vec(); 16]),
+                )),
+                "oversized_stream" => Ok(CallReply::stream(
+                    json!({"stream": true}),
+                    Vec::new(),
+                    ResponseStream::from_chunks(vec![b"abcde".to_vec()]),
+                )),
+                "too_many_chunks" => Ok(CallReply::stream(
+                    json!({"stream": true}),
+                    Vec::new(),
+                    ResponseStream::from_chunks(vec![b"x".to_vec(); 17]),
+                )),
+                "dynamic_oversized_stream" => {
+                    let (sender, stream) = ResponseStream::channel(NonZeroUsize::new(1).unwrap());
+                    tokio::spawn(async move {
+                        let _ = sender.send(b"abcde".to_vec()).await;
+                    });
+                    Ok(CallReply::stream(
+                        json!({"stream": true}),
+                        Vec::new(),
+                        stream,
+                    ))
+                }
+                "oversized_fault" => Err(PluginFault::new(
+                    ErrorCode::Upstream,
+                    "x".repeat(MAXIMUM_FRAME_BYTES),
+                )),
+                "oversized_result" => Ok(CallReply::unary(
+                    Value::String("x".repeat(MAXIMUM_FRAME_BYTES)),
+                    Vec::new(),
+                )),
+                "dynamic_oversized_fault" => {
+                    let (sender, stream) = ResponseStream::channel(NonZeroUsize::new(1).unwrap());
+                    tokio::spawn(async move {
+                        let _ = sender
+                            .fail(PluginFault::new(
+                                ErrorCode::Upstream,
+                                "x".repeat(MAXIMUM_FRAME_BYTES),
+                            ))
+                            .await;
+                    });
+                    Ok(CallReply::stream(
+                        json!({"stream": true}),
+                        Vec::new(),
+                        stream,
+                    ))
+                }
+                "pending" => pending::<Result<CallReply, PluginFault>>().await,
+                _ => Err(PluginFault::new(
+                    ErrorCode::Unsupported,
+                    "unsupported test method",
+                )),
+            }
+        })
+    }
+
+    fn cancel(&self, _context: &CallContext) {
+        self.lifecycle.cancel_started.store(true, Ordering::Release);
+        if let Some(delay) = self.cancel_delay {
+            std::thread::sleep(delay);
+        }
+        self.lifecycle.cancelled.fetch_add(1, Ordering::Relaxed);
+    }
+
+    fn quiesce(&self) {
+        self.lifecycle.quiesced.store(true, Ordering::Release);
+    }
+
+    fn shutdown(&self) {
+        self.lifecycle.shutdown.store(true, Ordering::Release);
+    }
+}
+
+struct HostPeer {
+    reader: ReadHalf<DuplexStream>,
+    writer: WriteHalf<DuplexStream>,
+}
+
+async fn start_session<H: PluginHandler>(
+    handler: H,
+) -> (HostPeer, JoinHandle<Result<(), SessionError>>) {
+    start_session_with_capacity(handler, MAXIMUM_FRAME_BYTES * 2).await
+}
+
+async fn start_session_with_capacity<H: PluginHandler>(
+    handler: H,
+    capacity: usize,
+) -> (HostPeer, JoinHandle<Result<(), SessionError>>) {
+    let (host, plugin) = tokio::io::duplex(capacity);
+    let (plugin_reader, plugin_writer) = tokio::io::split(plugin);
+    let task = tokio::spawn(async move {
+        let session = PluginSession::accept(
+            plugin_reader,
+            plugin_writer,
+            SessionConfig {
+                maximum_frame_bytes: MAXIMUM_FRAME_BYTES,
+                maximum_calls: 4,
+                maximum_callbacks: 4,
+                maximum_buffered_stream_chunks: 16,
+                handshake_timeout: Duration::from_secs(1),
+                maximum_call_timeout: Duration::from_secs(2),
+            },
+        )
+        .await?;
+        session.run(handler).await
+    });
+    let (mut reader, mut writer) = tokio::io::split(host);
+    write_frame(
+        &mut writer,
+        &Frame::control(Message::Hello {
+            handshake: handshake(),
+        }),
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+    let ready = read_frame(&mut reader, MAXIMUM_FRAME_BYTES).await.unwrap();
+    assert!(matches!(
+        ready,
+        Frame {
+            message: Message::Ready {
+                protocol_version: PROTOCOL_VERSION,
+                ref incarnation,
+            },
+            ref payload,
+        } if incarnation == "test-incarnation" && payload.is_empty()
+    ));
+    (HostPeer { reader, writer }, task)
+}
+
+fn middleware_contributions() -> Contributions {
+    Contributions::from([(
+        Capability::Middleware,
+        ContributionDeclaration {
+            id: "test.example.middleware".into(),
+            version: 1,
+            stages: vec![Stage::Request],
+            input_formats: vec!["openai".into()],
+            output_formats: vec!["openai".into()],
+        },
+    )])
+}
+
+fn middleware_plugin(map_response: bool) -> impl PluginHandler {
+    MiddlewarePlugin::new(
+        &middleware_contributions(),
+        move |call: MiddlewareCall| async move {
+            let MiddlewareCall {
+                mut request, next, ..
+            } = call;
+            if map_response {
+                request.body.push(b'!');
+                request.remove_header("x-old");
+                request.head.headers.push(MiddlewareHeader {
+                    name: "x-direct".into(),
+                    value: b"request".to_vec(),
+                });
+            }
+            let mut response = next.run(request).await?;
+            if map_response {
+                response.remove_header("x-upstream");
+                response.headers.push(MiddlewareHeader {
+                    name: "x-direct-response".into(),
+                    value: b"response".to_vec(),
+                });
+                response.body = response.body.map_frames(|mut frame| {
+                    frame.payload.make_ascii_uppercase();
+                    Ok(vec![frame])
+                })?;
+            }
+            Ok(response)
+        },
+    )
+    .unwrap()
+}
+
+#[test]
+fn middleware_plugin_rejects_declarations_without_matching_handlers() {
+    let declaration = middleware_contributions()
+        .remove(&Capability::Middleware)
+        .unwrap();
+    let mut invalid = vec![Contributions::new()];
+    invalid.push(Contributions::from([(
+        Capability::Executor,
+        declaration.clone(),
+    )]));
+    invalid.push(Contributions::from([
+        (Capability::Middleware, declaration.clone()),
+        (Capability::Executor, declaration.clone()),
+    ]));
+    let mut unsupported = declaration.clone();
+    unsupported.version = 2;
+    invalid.push(Contributions::from([(Capability::Middleware, unsupported)]));
+    for stages in [
+        vec![],
+        vec![Stage::Execution],
+        vec![Stage::Request, Stage::Request],
+        vec![Stage::Request, Stage::Attempt, Stage::Request],
+    ] {
+        let mut invalid_stage = declaration.clone();
+        invalid_stage.stages = stages;
+        invalid.push(Contributions::from([(
+            Capability::Middleware,
+            invalid_stage,
+        )]));
+    }
+    for contributes in invalid {
+        let result = MiddlewarePlugin::new(&contributes, |call: MiddlewareCall| async move {
+            call.next.run(call.request).await
+        });
+        assert!(matches!(result, Err(SessionError::Configuration)));
+    }
+    let mut both_mounts = declaration;
+    both_mounts.stages.push(Stage::Attempt);
+    let contributes = Contributions::from([(Capability::Middleware, both_mounts)]);
+    assert!(
+        MiddlewarePlugin::new(&contributes, |call: MiddlewareCall| async move {
+            call.next.run(call.request).await
+        })
+        .is_ok()
+    );
+}
+
+#[tokio::test]
+async fn middleware_plugin_registers_without_invoking_business_handler() {
+    let contributes = middleware_contributions();
+    let plugin = MiddlewarePlugin::new(&contributes, |_| async {
+        panic!("registration must not invoke middleware")
+    })
+    .unwrap();
+    let (mut host, task) = start_session(plugin).await;
+    let mut registration_context = context(1, Duration::from_secs(1));
+    registration_context.stage = Stage::Registration;
+    write_frame(
+        &mut host.writer,
+        &Frame {
+            message: Message::Call {
+                id: 1,
+                method: "plugin.register".into(),
+                context: registration_context,
+                params: json!({}),
+            },
+            payload: vec![],
+        },
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+    let reply = receive(&mut host).await;
+    let Message::Result { id: 1, result } = reply.message else {
+        panic!("expected registration result")
+    };
+    let registration: gateway_plugin_sdk::call::provider::Registration =
+        serde_json::from_value(result).unwrap();
+    assert_eq!(registration.contributes, contributes);
+    assert!(registration.provider.is_none());
+    assert!(reply.payload.is_empty());
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn middleware_plugin_rejects_invalid_calls_before_business_dispatch() {
+    let plugin = MiddlewarePlugin::new(&middleware_contributions(), |_| async {
+        panic!("invalid call must not invoke middleware")
+    })
+    .unwrap();
+    let (mut host, task) = start_session(plugin).await;
+    let cases = [
+        ("plugin.register", Stage::Request, json!({}), vec![]),
+        ("plugin.register", Stage::Registration, json!(null), vec![]),
+        (
+            "plugin.register",
+            Stage::Registration,
+            json!({"extra":true}),
+            vec![],
+        ),
+        ("plugin.register", Stage::Registration, json!({}), vec![1]),
+        (HANDLE_METHOD, Stage::Attempt, json!({}), vec![]),
+        (HANDLE_METHOD, Stage::Request, json!({}), vec![]),
+        ("provider.execute", Stage::Execution, json!({}), vec![]),
+    ];
+    for (index, (method, stage, params, payload)) in cases.into_iter().enumerate() {
+        let id = u64::try_from(index).unwrap() * 2 + 1;
+        let mut call_context = middleware_context(id);
+        call_context.stage = stage;
+        write_frame(
+            &mut host.writer,
+            &Frame {
+                message: Message::Call {
+                    id,
+                    method: method.into(),
+                    context: call_context,
+                    params,
+                },
+                payload,
+            },
+            MAXIMUM_FRAME_BYTES,
+        )
+        .await
+        .unwrap();
+        let reply = receive(&mut host).await;
+        let Message::Error {
+            id: reply_id,
+            error,
+        } = reply.message
+        else {
+            panic!("expected invalid call error")
+        };
+        assert_eq!(reply_id, id);
+        assert_eq!(
+            error.code,
+            if method == "provider.execute" {
+                ErrorCode::Unsupported
+            } else {
+                ErrorCode::InvalidInput
+            }
+        );
+    }
+    shutdown(&mut host, task).await;
+}
+
+fn handshake() -> Handshake {
+    Handshake {
+        protocol_version: PROTOCOL_VERSION,
+        artifact_sha256: "a".repeat(64),
+        plugin_id: "test.example".into(),
+        instance_id: "test-instance".into(),
+        generation: 7,
+        incarnation: "test-incarnation".into(),
+        configuration: json!({}),
+        permissions: Vec::new(),
+        contributes: Contributions::new(),
+    }
+}
+
+fn context(id: u64, timeout: Duration) -> CallContext {
+    CallContext {
+        call_id: id,
+        instance_id: "test-instance".into(),
+        generation: 7,
+        incarnation: "test-incarnation".into(),
+        stage: Stage::Execution,
+        timeout_ms: timeout.as_millis() as u64,
+        resource_scope_id: format!("scope-{id}"),
+        request_id: None,
+        attempt_id: None,
+        account_id: None,
+        credential_revision: None,
+    }
+}
+
+fn middleware_context(id: u64) -> CallContext {
+    CallContext {
+        stage: Stage::Request,
+        request_id: Some("request-middleware".into()),
+        ..context(id, Duration::from_secs(1))
+    }
+}
+
+fn middleware_request() -> MiddlewareRequestHead {
+    MiddlewareRequestHead {
+        request_id: "request-middleware".into(),
+        mount: MiddlewareMount::Request,
+        attempt_index: None,
+        operation: "generate".into(),
+        protocol: "openai".into(),
+        endpoint: "responses".into(),
+        transport: MiddlewareTransport::HttpSse,
+        provider: None,
+        model: Some("public-model".into()),
+        account_id: None,
+        headers: vec![MiddlewareHeader {
+            name: "x-old".into(),
+            value: b"old".to_vec(),
+        }],
+        body_visible: true,
+    }
+}
+
+async fn send_call(host: &mut HostPeer, id: u64, method: &str, params: Value, payload: Vec<u8>) {
+    send_call_with_timeout(host, id, method, params, payload, Duration::from_secs(1)).await;
+}
+
+async fn send_call_with_timeout(
+    host: &mut HostPeer,
+    id: u64,
+    method: &str,
+    params: Value,
+    payload: Vec<u8>,
+    timeout: Duration,
+) {
+    write_frame(
+        &mut host.writer,
+        &Frame {
+            message: Message::Call {
+                id,
+                method: method.into(),
+                context: context(id, timeout),
+                params,
+            },
+            payload,
+        },
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+}
+
+async fn send_control(host: &mut HostPeer, message: Message) {
+    write_frame(
+        &mut host.writer,
+        &Frame::control(message),
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+}
+
+async fn receive(host: &mut HostPeer) -> Frame {
+    tokio::time::timeout(
+        Duration::from_secs(1),
+        read_frame(&mut host.reader, MAXIMUM_FRAME_BYTES),
+    )
+    .await
+    .expect("plugin response timed out")
+    .expect("plugin response frame must be valid")
+}
+
+async fn shutdown(host: &mut HostPeer, task: JoinHandle<Result<(), SessionError>>) {
+    send_control(host, Message::Shutdown).await;
+    tokio::time::timeout(Duration::from_secs(1), task)
+        .await
+        .expect("plugin session did not shut down")
+        .expect("plugin session task panicked")
+        .expect("plugin session shutdown failed");
+}
+
+#[tokio::test]
+async fn independent_calls_complete_concurrently() {
+    let (mut host, task) = start_session(TestHandler::default()).await;
+    send_call(&mut host, 1, "slow", json!("slow"), vec![1]).await;
+    send_call(&mut host, 3, "echo", json!("fast"), vec![3]).await;
+
+    let fast = receive(&mut host).await;
+    let slow = receive(&mut host).await;
+    assert!(matches!(
+        fast,
+        Frame {
+            message: Message::Result { id: 3, result },
+            payload,
+        } if result == json!("fast") && payload == [3]
+    ));
+    assert!(matches!(
+        slow,
+        Frame {
+            message: Message::Result { id: 1, result },
+            payload,
+        } if result == json!("slow") && payload == [1]
+    ));
+
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn completed_call_does_not_discard_a_partially_read_next_frame() {
+    let next = Frame {
+        message: Message::Call {
+            id: 3,
+            method: "echo".into(),
+            context: context(3, Duration::from_secs(1)),
+            params: json!({"fragmented": true}),
+        },
+        payload: vec![0, 255, 13, 10, 128],
+    };
+    let mut encoded = Vec::new();
+    write_frame(&mut encoded, &next, MAXIMUM_FRAME_BYTES)
+        .await
+        .unwrap();
+    let payload_start = encoded.len() - next.payload.len();
+    for split in [2, 6, 10, payload_start + 2] {
+        tokio::time::timeout(Duration::from_secs(2), async {
+            // 单字节缓冲保证前缀已经进入读取 future，而不是仍滞留在传输队列。
+            let (mut host, task) = start_session_with_capacity(TestHandler::default(), 1).await;
+            send_call(&mut host, 1, "slow", json!("first"), Vec::new()).await;
+            host.writer.write_all(&encoded[..split]).await.unwrap();
+            assert!(matches!(
+                receive(&mut host).await.message,
+                Message::Result { id: 1, .. }
+            ));
+            host.writer.write_all(&encoded[split..]).await.unwrap();
+            assert_eq!(
+                receive(&mut host).await,
+                Frame {
+                    message: Message::Result {
+                        id: 3,
+                        result: json!({"fragmented": true})
+                    },
+                    payload: next.payload.clone(),
+                }
+            );
+            shutdown(&mut host, task).await;
+        })
+        .await
+        .expect("fragmented frame must survive concurrent call completion");
+    }
+}
+
+#[tokio::test]
+async fn host_callback_round_trips_while_parent_call_is_waiting() {
+    let (mut host, task) = start_session(TestHandler::default()).await;
+    send_call(&mut host, 1, "callback", json!({"event": "ready"}), vec![7]).await;
+
+    let callback = receive(&mut host).await;
+    let callback_id = match callback.message {
+        Message::Callback {
+            id,
+            parent_id: 1,
+            ref method,
+            ref params,
+        } if id.is_multiple_of(2)
+            && method == "host.log"
+            && params == &json!({"event": "ready"}) =>
+        {
+            id
+        }
+        message => panic!("unexpected callback frame: {message:?}"),
+    };
+    assert_eq!(callback.payload, [7]);
+    write_frame(
+        &mut host.writer,
+        &Frame {
+            message: Message::Result {
+                id: callback_id,
+                result: json!({"recorded": true}),
+            },
+            payload: vec![9],
+        },
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+
+    let result = receive(&mut host).await;
+    assert!(matches!(
+        result,
+        Frame {
+            message: Message::Result { id: 1, result },
+            payload,
+        } if result == json!({"recorded": true}) && payload == [9]
+    ));
+
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn callbacks_from_concurrent_calls_remain_correlated() {
+    let (mut host, task) = start_session(TestHandler::default()).await;
+    send_call(&mut host, 1, "callback", json!({"parent": 1}), vec![1]).await;
+    send_call(&mut host, 3, "callback", json!({"parent": 3}), vec![3]).await;
+
+    let mut callbacks = Vec::new();
+    for _ in 0..2 {
+        let frame = receive(&mut host).await;
+        let Message::Callback {
+            id,
+            parent_id,
+            method,
+            params,
+        } = frame.message
+        else {
+            panic!("expected callback")
+        };
+        assert_eq!(method, "host.log");
+        assert_eq!(params, json!({"parent": parent_id}));
+        assert_eq!(frame.payload, [parent_id as u8]);
+        callbacks.push((id, parent_id));
+    }
+    assert!(callbacks[0].0 < callbacks[1].0);
+    assert!(callbacks.iter().all(|(id, _)| id.is_multiple_of(2)));
+
+    for (callback_id, parent_id) in callbacks.into_iter().rev() {
+        write_frame(
+            &mut host.writer,
+            &Frame {
+                message: Message::Result {
+                    id: callback_id,
+                    result: json!({"parent": parent_id}),
+                },
+                payload: vec![parent_id as u8],
+            },
+            MAXIMUM_FRAME_BYTES,
+        )
+        .await
+        .unwrap();
+    }
+    let mut completed = Vec::new();
+    for _ in 0..2 {
+        let frame = receive(&mut host).await;
+        let Message::Result { id, result } = frame.message else {
+            panic!("expected parent result")
+        };
+        assert_eq!(result, json!({"parent": id}));
+        assert_eq!(frame.payload, [id as u8]);
+        completed.push(id);
+    }
+    completed.sort_unstable();
+    assert_eq!(completed, [1, 3]);
+
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn middleware_next_and_body_mapping_reuse_callback_and_credit_flow() {
+    let (mut host, task) = start_session(middleware_plugin(true)).await;
+    write_frame(
+        &mut host.writer,
+        &Frame {
+            message: Message::Call {
+                id: 1,
+                method: HANDLE_METHOD.into(),
+                context: middleware_context(1),
+                params: serde_json::to_value(middleware_request()).unwrap(),
+            },
+            payload: b"request".to_vec(),
+        },
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+
+    let next = receive(&mut host).await;
+    let next_id = match next.message {
+        Message::Callback {
+            id,
+            parent_id: 1,
+            ref method,
+            ref params,
+        } if method == NEXT_METHOD => {
+            let request: MiddlewareNextRequest = serde_json::from_value(params.clone()).unwrap();
+            assert_eq!(request.body, MiddlewareRequestBody::Replace);
+            assert!(request.protocol.is_none());
+            assert_eq!(request.header_mutations.len(), 2);
+            assert!(matches!(
+                &request.header_mutations[0],
+                MiddlewareHeaderMutation::Remove { name } if name == "x-old"
+            ));
+            assert!(matches!(
+                &request.header_mutations[1],
+                MiddlewareHeaderMutation::Append { name, value }
+                    if name == "x-direct" && value == b"request"
+            ));
+            id
+        }
+        message => panic!("unexpected middleware next frame: {message:?}"),
+    };
+    assert_eq!(next.payload, b"request!");
+    write_frame(
+        &mut host.writer,
+        &Frame {
+            message: Message::Result {
+                id: next_id,
+                result: serde_json::to_value(MiddlewareNextResponse {
+                    response: "response-1".into(),
+                    protocol: "openai".into(),
+                    status: 200,
+                    headers: vec![MiddlewareHeader {
+                        name: "x-upstream".into(),
+                        value: b"old".to_vec(),
+                    }],
+                    body: Some(MiddlewareBodyHandle {
+                        handle: "body-1".into(),
+                        framing: MiddlewareBodyFraming::SseEvent,
+                    }),
+                })
+                .unwrap(),
+            },
+            payload: Vec::new(),
+        },
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+    send_control(
+        &mut host,
+        Message::Credit {
+            id: 1,
+            bytes: 1_024,
+            frames: 2,
+        },
+    )
+    .await;
+
+    let initial = receive(&mut host).await;
+    let Message::Result { id: 1, result } = initial.message else {
+        panic!("expected middleware result")
+    };
+    let head: MiddlewareResponseHead = serde_json::from_value(result).unwrap();
+    assert_eq!(head.header_mutations.len(), 2);
+    assert!(matches!(
+        &head.header_mutations[0],
+        MiddlewareHeaderMutation::Remove { name } if name == "x-upstream"
+    ));
+    assert!(matches!(
+        &head.header_mutations[1],
+        MiddlewareHeaderMutation::Append { name, value }
+            if name == "x-direct-response" && value == b"response"
+    ));
+    assert!(matches!(
+        head.body,
+        MiddlewareResponseBody::Stream {
+            framing: MiddlewareBodyFraming::SseEvent
+        }
+    ));
+
+    let read = receive(&mut host).await;
+    let read_id = match read.message {
+        Message::Callback {
+            id,
+            parent_id: 1,
+            ref method,
+            ..
+        } if method == BODY_READ_METHOD => id,
+        message => panic!("unexpected middleware body read: {message:?}"),
+    };
+    write_frame(
+        &mut host.writer,
+        &Frame {
+            message: Message::Result {
+                id: read_id,
+                result: serde_json::to_value(MiddlewareBodyReadResult {
+                    framing: MiddlewareBodyFraming::SseEvent,
+                    source_id: 1,
+                    eof: false,
+                    terminal: true,
+                })
+                .unwrap(),
+            },
+            payload: b"data: done\n\n".to_vec(),
+        },
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+    let mapped = receive(&mut host).await;
+    let Frame {
+        message: Message::Stream { id: 1, sequence: 0 },
+        payload,
+    } = mapped
+    else {
+        panic!("expected mapped middleware frame")
+    };
+    let mapped = MiddlewareBodyFrame::decode(&payload).unwrap();
+    assert_eq!(mapped.payload, b"DATA: DONE\n\n");
+    assert!(!mapped.terminal);
+    assert_eq!(mapped.source_id(), 1);
+    assert_eq!(mapped.disposition(), MiddlewareBodyDisposition::Only);
+
+    let eof = receive(&mut host).await;
+    let eof_id = match eof.message {
+        Message::Callback {
+            id,
+            parent_id: 1,
+            ref method,
+            ..
+        } if method == BODY_READ_METHOD => id,
+        message => panic!("unexpected middleware eof read: {message:?}"),
+    };
+    write_frame(
+        &mut host.writer,
+        &Frame {
+            message: Message::Result {
+                id: eof_id,
+                result: serde_json::to_value(MiddlewareBodyReadResult {
+                    framing: MiddlewareBodyFraming::SseEvent,
+                    source_id: 0,
+                    eof: true,
+                    terminal: false,
+                })
+                .unwrap(),
+            },
+            payload: Vec::new(),
+        },
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::End { id: 1, error: None }
+    ));
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn untouched_middleware_response_transfers_opaque_body_without_reading_it() {
+    let (mut host, task) = start_session(middleware_plugin(false)).await;
+    write_frame(
+        &mut host.writer,
+        &Frame {
+            message: Message::Call {
+                id: 1,
+                method: HANDLE_METHOD.into(),
+                context: middleware_context(1),
+                params: serde_json::to_value(middleware_request()).unwrap(),
+            },
+            payload: b"hidden-by-preserve".to_vec(),
+        },
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+
+    let next = receive(&mut host).await;
+    let next_id = match next.message {
+        Message::Callback {
+            id,
+            parent_id: 1,
+            ref method,
+            ref params,
+        } if method == NEXT_METHOD => {
+            let request: MiddlewareNextRequest = serde_json::from_value(params.clone()).unwrap();
+            assert_eq!(request.body, MiddlewareRequestBody::Preserve);
+            id
+        }
+        message => panic!("unexpected middleware next frame: {message:?}"),
+    };
+    assert!(next.payload.is_empty());
+    write_frame(
+        &mut host.writer,
+        &Frame {
+            message: Message::Result {
+                id: next_id,
+                result: serde_json::to_value(MiddlewareNextResponse {
+                    response: "response-1".into(),
+                    protocol: "openai".into(),
+                    status: 200,
+                    headers: Vec::new(),
+                    body: Some(MiddlewareBodyHandle {
+                        handle: "body-pass-through".into(),
+                        framing: MiddlewareBodyFraming::RawBytes,
+                    }),
+                })
+                .unwrap(),
+            },
+            payload: Vec::new(),
+        },
+        MAXIMUM_FRAME_BYTES,
+    )
+    .await
+    .unwrap();
+    send_control(
+        &mut host,
+        Message::Credit {
+            id: 1,
+            bytes: 1,
+            frames: 1,
+        },
+    )
+    .await;
+
+    let initial = receive(&mut host).await;
+    let Message::Result { id: 1, result } = initial.message else {
+        panic!("expected middleware result")
+    };
+    let head: MiddlewareResponseHead = serde_json::from_value(result).unwrap();
+    assert!(matches!(
+        head.body,
+        MiddlewareResponseBody::PassThrough {
+            body: MiddlewareBodyHandle { ref handle, .. }
+        } if handle == "body-pass-through"
+    ));
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::End { id: 1, error: None }
+    ));
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn stream_waits_for_credit_and_rejects_uncreditable_buffered_chunk_before_result() {
+    let (mut host, task) = start_session(TestHandler::default()).await;
+    send_call(&mut host, 1, "stream", json!({}), Vec::new()).await;
+    assert!(
+        tokio::time::timeout(
+            Duration::from_millis(25),
+            read_frame(&mut host.reader, MAXIMUM_FRAME_BYTES)
+        )
+        .await
+        .is_err()
+    );
+    send_control(
+        &mut host,
+        Message::Credit {
+            id: 1,
+            bytes: 4,
+            frames: 1,
+        },
+    )
+    .await;
+
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Result { id: 1, .. }
+    ));
+    assert!(matches!(
+        receive(&mut host).await,
+        Frame {
+            message: Message::Stream { id: 1, sequence: 0 },
+            payload,
+        } if payload == b"abcd"
+    ));
+    assert!(
+        tokio::time::timeout(
+            Duration::from_millis(25),
+            read_frame(&mut host.reader, MAXIMUM_FRAME_BYTES)
+        )
+        .await
+        .is_err()
+    );
+    send_control(
+        &mut host,
+        Message::Credit {
+            id: 1,
+            bytes: 4,
+            frames: 1,
+        },
+    )
+    .await;
+    assert!(matches!(
+        receive(&mut host).await,
+        Frame {
+            message: Message::Stream { id: 1, sequence: 1 },
+            payload,
+        } if payload == b"efgh"
+    ));
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::End { id: 1, error: None }
+    ));
+
+    send_call(&mut host, 3, "oversized_stream", json!({}), Vec::new()).await;
+    send_control(
+        &mut host,
+        Message::Credit {
+            id: 3,
+            bytes: 4,
+            frames: 1,
+        },
+    )
+    .await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Error {
+            id: 3,
+            error: PluginFault {
+                code: ErrorCode::InvalidInput,
+                ..
+            },
+        }
+    ));
+
+    send_call(&mut host, 5, "too_many_chunks", json!({}), Vec::new()).await;
+    send_control(
+        &mut host,
+        Message::Credit {
+            id: 5,
+            bytes: 4,
+            frames: 1,
+        },
+    )
+    .await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Error {
+            id: 5,
+            error: PluginFault {
+                code: ErrorCode::Capacity,
+                ..
+            },
+        }
+    ));
+
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn late_credit_after_a_long_stream_terminal_does_not_close_the_session() {
+    let (mut host, task) = start_session(TestHandler::default()).await;
+    send_call(&mut host, 1, "long_stream", json!({}), Vec::new()).await;
+    send_control(
+        &mut host,
+        Message::Credit {
+            id: 1,
+            bytes: 1,
+            frames: 1,
+        },
+    )
+    .await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Result { id: 1, .. }
+    ));
+    for sequence in 0..16 {
+        assert!(matches!(
+            receive(&mut host).await,
+            Frame {
+                message: Message::Stream { id: 1, sequence: observed },
+                payload,
+            } if observed == sequence && payload == b"x"
+        ));
+        send_control(
+            &mut host,
+            Message::Credit {
+                id: 1,
+                bytes: 1,
+                frames: 1,
+            },
+        )
+        .await;
+    }
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::End { id: 1, error: None }
+    ));
+
+    send_call(&mut host, 3, "echo", json!("still-ready"), Vec::new()).await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Result { id: 3, result } if result == json!("still-ready")
+    ));
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn malformed_late_credit_remains_a_protocol_error() {
+    let (mut host, task) = start_session(TestHandler::default()).await;
+    send_call(&mut host, 1, "echo", json!({}), Vec::new()).await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Result { id: 1, .. }
+    ));
+
+    send_control(
+        &mut host,
+        Message::Credit {
+            id: 1,
+            bytes: 0,
+            frames: 1,
+        },
+    )
+    .await;
+    assert!(matches!(
+        tokio::time::timeout(Duration::from_secs(1), task)
+            .await
+            .expect("protocol error did not close the session")
+            .expect("plugin session task panicked"),
+        Err(SessionError::Protocol)
+    ));
+}
+
+#[tokio::test]
+async fn dynamic_stream_ends_with_one_error_when_a_later_chunk_cannot_fit_credit() {
+    let (mut host, task) = start_session(TestHandler::default()).await;
+    send_call(
+        &mut host,
+        1,
+        "dynamic_oversized_stream",
+        json!({}),
+        Vec::new(),
+    )
+    .await;
+    send_control(
+        &mut host,
+        Message::Credit {
+            id: 1,
+            bytes: 4,
+            frames: 1,
+        },
+    )
+    .await;
+
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Result { id: 1, .. }
+    ));
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::End {
+            id: 1,
+            error: Some(PluginFault {
+                code: ErrorCode::InvalidInput,
+                ..
+            }),
+        }
+    ));
+
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn oversized_handler_faults_are_replaced_without_closing_the_session() {
+    let (mut host, task) = start_session(TestHandler::default()).await;
+    send_call(&mut host, 1, "oversized_result", json!({}), Vec::new()).await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Error {
+            id: 1,
+            error: PluginFault {
+                code: ErrorCode::InvalidInput,
+                ..
+            },
+        }
+    ));
+
+    send_call(&mut host, 3, "oversized_fault", json!({}), Vec::new()).await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Error {
+            id: 3,
+            error: PluginFault {
+                code: ErrorCode::Fault,
+                ref message,
+                ..
+            },
+        } if message == "plugin error exceeds the frame limit"
+    ));
+
+    send_call(
+        &mut host,
+        5,
+        "dynamic_oversized_fault",
+        json!({}),
+        Vec::new(),
+    )
+    .await;
+    send_control(
+        &mut host,
+        Message::Credit {
+            id: 5,
+            bytes: 1_024,
+            frames: 1,
+        },
+    )
+    .await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Result { id: 5, .. }
+    ));
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::End {
+            id: 5,
+            error: Some(PluginFault {
+                code: ErrorCode::Fault,
+                ref message,
+                ..
+            }),
+        } if message == "plugin stream error exceeds the frame limit"
+    ));
+
+    send_call(&mut host, 7, "echo", json!("still-ready"), Vec::new()).await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Result { id: 7, result } if result == json!("still-ready")
+    ));
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn call_deadline_cancels_handler_and_keeps_the_session_available() {
+    let handler = TestHandler::default();
+    let state = Arc::clone(&handler.lifecycle);
+    let (mut host, task) = start_session(handler).await;
+    send_call_with_timeout(
+        &mut host,
+        1,
+        "pending",
+        json!({}),
+        Vec::new(),
+        Duration::from_millis(20),
+    )
+    .await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Error {
+            id: 1,
+            error: PluginFault {
+                code: ErrorCode::Timeout,
+                ..
+            },
+        }
+    ));
+    tokio::time::timeout(Duration::from_millis(100), async {
+        while !state.cancel_started.load(Ordering::Acquire) {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .expect("deadline did not notify the lifecycle hook");
+
+    send_call(&mut host, 3, "echo", json!("still-ready"), Vec::new()).await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Result { id: 3, result } if result == json!("still-ready")
+    ));
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn cancelling_parent_retires_callback_and_late_reply_does_not_close_session() {
+    let (mut host, task) = start_session(TestHandler::default()).await;
+    send_call(&mut host, 1, "callback", json!({}), Vec::new()).await;
+    let callback = receive(&mut host).await;
+    let Message::Callback {
+        id: callback_id, ..
+    } = callback.message
+    else {
+        panic!("expected callback")
+    };
+
+    send_control(&mut host, Message::Cancel { id: 1 }).await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Cancelled { id: 1 }
+    ));
+    send_control(
+        &mut host,
+        Message::Result {
+            id: callback_id,
+            result: json!({}),
+        },
+    )
+    .await;
+    send_call(&mut host, 3, "echo", json!("still-ready"), Vec::new()).await;
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Result { id: 3, result } if result == json!("still-ready")
+    ));
+
+    shutdown(&mut host, task).await;
+}
+
+#[tokio::test]
+async fn blocking_cancel_hook_cannot_delay_cancelled_or_eof_settlement() {
+    let handler = TestHandler {
+        cancel_delay: Some(Duration::from_millis(200)),
+        ..TestHandler::default()
+    };
+    let state = Arc::clone(&handler.lifecycle);
+    let (mut host, task) = start_session(handler).await;
+    send_call(&mut host, 1, "pending", json!({}), Vec::new()).await;
+    send_control(&mut host, Message::Cancel { id: 1 }).await;
+
+    let cancelled = tokio::time::timeout(Duration::from_millis(50), receive(&mut host))
+        .await
+        .expect("blocking lifecycle hook delayed Cancelled");
+    assert!(matches!(cancelled.message, Message::Cancelled { id: 1 }));
+    tokio::time::timeout(Duration::from_millis(50), async {
+        while !state.cancel_started.load(Ordering::Acquire) {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .expect("cancel hook never started");
+
+    host.writer.shutdown().await.unwrap();
+    let result = tokio::time::timeout(Duration::from_millis(50), task)
+        .await
+        .expect("blocking lifecycle hook delayed EOF settlement")
+        .expect("plugin session task panicked");
+    assert!(matches!(result, Err(SessionError::Closed)));
+}
+
+#[tokio::test]
+async fn quiesce_rejects_new_calls_and_shutdown_closes_the_session() {
+    let handler = TestHandler::default();
+    let state = Arc::clone(&handler.lifecycle);
+    let (mut host, task) = start_session(handler).await;
+    send_control(&mut host, Message::Quiesce).await;
+    send_call(&mut host, 1, "echo", json!({}), Vec::new()).await;
+
+    assert!(matches!(
+        receive(&mut host).await.message,
+        Message::Error {
+            id: 1,
+            error: PluginFault {
+                code: ErrorCode::Capacity,
+                ..
+            },
+        }
+    ));
+    send_control(
+        &mut host,
+        Message::Credit {
+            id: 1,
+            bytes: 1,
+            frames: 1,
+        },
+    )
+    .await;
+    tokio::time::timeout(Duration::from_millis(50), async {
+        while !state.quiesced.load(Ordering::Acquire) {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .expect("quiesce hook was not signalled");
+
+    shutdown(&mut host, task).await;
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/main.rs b/backend/crates/gateway-plugin/sdk/tests/main.rs
new file mode 100644
index 000000000..8d18b3e02
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/main.rs
@@ -0,0 +1,5 @@
+mod call;
+#[cfg(feature = "io")]
+mod client;
+mod manifest;
+mod message;
diff --git a/backend/crates/gateway-plugin/sdk/tests/manifest.rs b/backend/crates/gateway-plugin/sdk/tests/manifest.rs
new file mode 100644
index 000000000..2fc3a7ba5
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/manifest.rs
@@ -0,0 +1,487 @@
+use gateway_plugin_sdk::{
+    Capability, ContributionDeclaration, Engines, Handshake, MANIFEST_VERSION, Manifest,
+    ManifestError, PROTOCOL_VERSION, Package, PackageTarget, PluginIcon, PluginIconVariants, Stage,
+    call::provider::Registration, valid_package_path,
+};
+use serde_json::json;
+
+fn source_manifest() -> Manifest {
+    serde_json::from_value(json!({
+        "manifestVersion": 3,
+        "name": "request-tags",
+        "displayName": "请求标签",
+        "publisher": "9acme",
+        "version": "1.0.0",
+        "description": "测试插件",
+        "license": "MIT",
+        "author": "test",
+        "engines": {"codex-proxy-rs": "*"},
+        "main": "bin/worker",
+        "runtime": "trustedProcess",
+        "contributes": {
+            "middleware": {
+                "id": "9acme.request-tags.tagRequest",
+                "version": 1,
+                "stages": ["request"],
+                "inputFormats": ["openai"],
+                "outputFormats": ["openai"]
+            }
+        }
+    }))
+    .unwrap()
+}
+
+fn packaged_manifest() -> Manifest {
+    let mut manifest = source_manifest();
+    manifest.engines = Engines {
+        codex_proxy_rs: ">=1.0.0, <2.0.0".parse().unwrap(),
+    };
+    manifest.package = Some(Package {
+        protocol_version: PROTOCOL_VERSION,
+        target: PackageTarget {
+            os: "linux".into(),
+            architecture: "x86_64".into(),
+        },
+        files: [("bin/worker".into(), "a".repeat(64))]
+            .into_iter()
+            .collect(),
+    });
+    manifest
+}
+
+#[test]
+fn package_paths_reject_platform_escapes_and_ambiguous_names() {
+    for invalid in [
+        "/tmp/code",
+        "../code",
+        "a/../b",
+        "a/./b",
+        "a//b",
+        "C:/code",
+        "a\\b",
+        "NUL.txt",
+        "aux",
+        "bin/a.",
+        "bin/a ",
+    ] {
+        assert!(!valid_package_path(invalid), "{invalid}");
+    }
+    assert!(valid_package_path("bin/example-worker.exe"));
+}
+
+#[test]
+fn source_manifest_allows_missing_package_and_wildcard_engine() {
+    let manifest = source_manifest();
+    assert_eq!(manifest.plugin_id().unwrap(), "9acme.request-tags");
+    assert!(manifest.validate().is_ok());
+    assert_eq!(
+        manifest.package_for(&"1.2.0".parse().unwrap(), "linux", "x86_64"),
+        Err(ManifestError::Invalid)
+    );
+}
+
+#[test]
+fn author_manifest_fills_default_ids_versions_and_fixed_stages() {
+    let source = json!({
+        "manifestVersion": MANIFEST_VERSION,
+        "name": "request-tags",
+        "displayName": "请求标签",
+        "publisher": "9acme",
+        "version": "1.0.0",
+        "description": "测试插件",
+        "license": "MIT",
+        "engines": {"codex-proxy-rs": "*"},
+        "main": "bin/worker",
+        "runtime": "trustedProcess",
+        "contributes": {
+            "middleware": {"stages": ["attempt"]},
+            "management": {}
+        }
+    });
+    let manifest = Manifest::from_author_slice(&serde_json::to_vec(&source).unwrap()).unwrap();
+    let middleware = &manifest.contributes[&Capability::Middleware];
+    let management = &manifest.contributes[&Capability::Management];
+
+    assert_eq!(middleware.id, "9acme.request-tags.middleware");
+    assert_eq!(middleware.version, 1);
+    assert_eq!(middleware.stages, [Stage::Attempt]);
+    assert_eq!(management.id, "9acme.request-tags.management");
+    assert_eq!(management.version, 1);
+    assert_eq!(management.stages, [Stage::Management]);
+}
+
+#[test]
+fn author_provider_group_expands_once_with_protocols_on_executor() {
+    let source = json!({
+        "manifestVersion": MANIFEST_VERSION,
+        "name": "echo",
+        "displayName": "Echo",
+        "publisher": "9acme",
+        "version": "1.0.0",
+        "description": "Echo provider",
+        "license": "MIT",
+        "engines": {"codex-proxy-rs": "*"},
+        "main": "bin/worker",
+        "runtime": "trustedProcess",
+        "contributes": {
+            "provider": {
+                "capabilities": ["models", "authentication", "quota", "maintenance"],
+                "inputFormats": ["openai"],
+                "outputFormats": ["openai"]
+            }
+        },
+        "permissions": ["accounts", "network"]
+    });
+    let manifest = Manifest::from_author_slice(&serde_json::to_vec(&source).unwrap()).unwrap();
+    let executor = &manifest.contributes[&Capability::Executor];
+
+    assert_eq!(manifest.contributes.len(), 5);
+    assert_eq!(executor.id, "9acme.echo.executor");
+    assert_eq!(executor.stages, [Stage::Execution]);
+    assert_eq!(executor.input_formats, ["openai"]);
+    assert_eq!(executor.output_formats, ["openai"]);
+    assert_eq!(
+        manifest.contributes[&Capability::Models].stages,
+        [Stage::Management, Stage::Maintenance]
+    );
+}
+
+#[test]
+fn author_provider_group_rejects_duplicate_or_non_provider_capabilities() {
+    for capabilities in [
+        json!(["models", "models"]),
+        json!(["management"]),
+        json!(["executor"]),
+    ] {
+        let source = json!({
+            "manifestVersion": MANIFEST_VERSION,
+            "name": "echo",
+            "displayName": "Echo",
+            "publisher": "9acme",
+            "version": "1.0.0",
+            "description": "Echo provider",
+            "license": "MIT",
+            "engines": {"codex-proxy-rs": "*"},
+            "main": "bin/worker",
+            "runtime": "trustedProcess",
+            "contributes": {
+                "provider": {
+                    "capabilities": capabilities,
+                    "inputFormats": ["openai"],
+                    "outputFormats": ["openai"]
+                }
+            }
+        });
+        assert_eq!(
+            Manifest::from_author_slice(&serde_json::to_vec(&source).unwrap()),
+            Err(ManifestError::Invalid)
+        );
+    }
+
+    for (input_formats, output_formats) in [
+        (json!([]), json!(["openai"])),
+        (json!(["openai"]), json!([])),
+        (json!(["openai", "openai"]), json!(["openai"])),
+        (json!(["openai"]), json!(["openai", "openai"])),
+    ] {
+        let source = json!({
+            "manifestVersion": MANIFEST_VERSION,
+            "name": "echo",
+            "displayName": "Echo",
+            "publisher": "9acme",
+            "version": "1.0.0",
+            "description": "Echo provider",
+            "license": "MIT",
+            "engines": {"codex-proxy-rs": "*"},
+            "main": "bin/worker",
+            "runtime": "trustedProcess",
+            "contributes": {
+                "provider": {
+                    "inputFormats": input_formats,
+                    "outputFormats": output_formats
+                }
+            }
+        });
+        assert_eq!(
+            Manifest::from_author_slice(&serde_json::to_vec(&source).unwrap()),
+            Err(ManifestError::Invalid)
+        );
+    }
+}
+
+#[test]
+fn installation_checks_protocol_engine_and_target() {
+    let mut manifest = packaged_manifest();
+    let host = "1.2.0".parse().unwrap();
+    assert!(manifest.package_for(&host, "linux", "x86_64").is_ok());
+    assert_eq!(
+        manifest.package_for(&host, "windows", "aarch64"),
+        Err(ManifestError::Platform)
+    );
+    manifest.package.as_mut().unwrap().protocol_version = 2;
+    assert_eq!(manifest.validate(), Err(ManifestError::Incompatible));
+    manifest.package.as_mut().unwrap().protocol_version = PROTOCOL_VERSION;
+    manifest.engines.codex_proxy_rs = "*".parse().unwrap();
+    assert_eq!(manifest.validate(), Err(ManifestError::Invalid));
+}
+
+#[test]
+fn package_rejects_file_directory_conflicts_and_missing_declared_files() {
+    let mut manifest = packaged_manifest();
+    manifest
+        .package
+        .as_mut()
+        .unwrap()
+        .files
+        .insert("bin".into(), "b".repeat(64));
+    assert_eq!(manifest.validate(), Err(ManifestError::Invalid));
+
+    let mut manifest = packaged_manifest();
+    manifest
+        .resources
+        .insert("ui/index.html".into(), "text/html".into());
+    assert_eq!(manifest.validate(), Err(ManifestError::Invalid));
+
+    let mut manifest = packaged_manifest();
+    manifest.main = "bin/missing".into();
+    assert_eq!(manifest.validate(), Err(ManifestError::Invalid));
+}
+
+#[test]
+fn icon_accepts_declared_image_resources_and_rejects_unsafe_shapes() {
+    let mut manifest = source_manifest();
+    manifest
+        .resources
+        .insert("assets/icon.png".into(), "image/png".into());
+    manifest.icon = Some(PluginIcon::Path("assets/icon.png".into()));
+    assert!(manifest.validate().is_ok());
+
+    manifest
+        .resources
+        .insert("assets/icon-dark.webp".into(), "image/webp".into());
+    manifest.icon = Some(PluginIcon::Themed(PluginIconVariants {
+        light: "assets/icon.png".into(),
+        dark: "assets/icon-dark.webp".into(),
+    }));
+    assert!(manifest.validate().is_ok());
+
+    manifest.icon = Some(PluginIcon::Path("assets/missing.png".into()));
+    assert_eq!(manifest.validate(), Err(ManifestError::Invalid));
+    manifest
+        .resources
+        .insert("assets/icon.svg".into(), "image/svg+xml".into());
+    manifest.icon = Some(PluginIcon::Path("assets/icon.svg".into()));
+    assert!(manifest.validate().is_ok());
+    manifest.icon = Some(PluginIcon::Path("assets/icon.png".into()));
+    manifest
+        .resources
+        .insert("assets/icon.png".into(), "image/jpeg".into());
+    assert_eq!(manifest.validate(), Err(ManifestError::Invalid));
+}
+
+#[test]
+fn icon_accepts_common_extensions_and_mime_aliases() {
+    for (extension, mime) in [
+        ("SVG", "image/svg+xml"),
+        ("PNG", "image/png"),
+        ("jpeg", "image/jpeg"),
+        ("jfif", "image/jpeg"),
+        ("WebP", "image/webp"),
+        ("gif", "image/gif"),
+        ("ico", "image/x-icon"),
+        ("ICO", "image/vnd.microsoft.icon"),
+        ("bmp", "image/bmp"),
+        ("BMP", "image/x-ms-bmp"),
+    ] {
+        let mut manifest = source_manifest();
+        let path = format!("assets/icon.{extension}");
+        manifest.resources.insert(path.clone(), mime.into());
+        manifest.icon = Some(PluginIcon::Path(path));
+        assert!(manifest.validate().is_ok(), "{extension}: {mime}");
+    }
+}
+
+#[test]
+fn icon_rejects_non_image_resources_even_when_declared() {
+    for (path, mime) in [
+        ("assets/icon.html", "text/html"),
+        ("assets/icon.svg", "text/xml"),
+    ] {
+        let mut manifest = source_manifest();
+        manifest.resources.insert(path.into(), mime.into());
+        manifest.icon = Some(PluginIcon::Path(path.into()));
+        assert_eq!(manifest.validate(), Err(ManifestError::Invalid));
+    }
+}
+
+#[test]
+fn icon_wire_is_a_path_or_exact_light_dark_object() {
+    let mut manifest = source_manifest();
+    manifest
+        .resources
+        .insert("assets/icon.png".into(), "image/png".into());
+    manifest.icon = Some(PluginIcon::Path("assets/icon.png".into()));
+    assert_eq!(
+        serde_json::to_value(&manifest).unwrap()["icon"],
+        json!("assets/icon.png")
+    );
+
+    let mut value = serde_json::to_value(&manifest).unwrap();
+    value["icon"] = json!({
+        "light": "assets/icon.png",
+        "dark": "assets/icon.png",
+        "builtin": "puzzle"
+    });
+    assert!(serde_json::from_value::<Manifest>(value).is_err());
+}
+
+#[test]
+fn contribution_ids_are_owned_unique_and_stage_bounded() {
+    let mut manifest = source_manifest();
+    let middleware = manifest
+        .contributes
+        .get(&Capability::Middleware)
+        .unwrap()
+        .clone();
+    manifest
+        .contributes
+        .insert(Capability::Executor, middleware);
+    assert_eq!(manifest.validate(), Err(ManifestError::Invalid));
+
+    let mut manifest = source_manifest();
+    manifest
+        .contributes
+        .get_mut(&Capability::Middleware)
+        .unwrap()
+        .id = "other.request-tags.tagRequest".into();
+    assert_eq!(manifest.validate(), Err(ManifestError::Invalid));
+
+    let mut manifest = source_manifest();
+    manifest
+        .contributes
+        .get_mut(&Capability::Middleware)
+        .unwrap()
+        .stages = vec![Stage::Execution];
+    assert_eq!(manifest.validate(), Err(ManifestError::Invalid));
+}
+
+#[test]
+fn installed_manifest_rejects_non_middleware_stage_drift() {
+    let mut manifest = source_manifest();
+    manifest.contributes.insert(
+        Capability::Management,
+        ContributionDeclaration {
+            id: "9acme.request-tags.management".into(),
+            version: 1,
+            stages: vec![Stage::Registration],
+            input_formats: Vec::new(),
+            output_formats: Vec::new(),
+        },
+    );
+
+    assert_eq!(manifest.validate(), Err(ManifestError::Invalid));
+}
+
+#[test]
+fn plugin_identity_rejects_invalid_segments_and_overlong_ids() {
+    let mut manifest = source_manifest();
+    manifest.publisher = "Acme".into();
+    assert_eq!(manifest.plugin_id(), Err(ManifestError::Invalid));
+
+    let mut manifest = source_manifest();
+    manifest.name = "request-tags-".into();
+    assert_eq!(manifest.plugin_id(), Err(ManifestError::Invalid));
+
+    let mut manifest = source_manifest();
+    manifest.publisher = "a".repeat(32);
+    manifest.name = "b".repeat(32);
+    assert_eq!(manifest.plugin_id(), Err(ManifestError::Invalid));
+}
+
+#[test]
+fn state_namespaces_are_base_infrastructure_with_bounded_versions() {
+    let mut manifest = source_manifest();
+    manifest.state = vec![gateway_plugin_sdk::StateNamespace {
+        namespace: "cache.primary".into(),
+        schema_version: 2,
+        schema: json!({"type":"object"}),
+        maximum_records: 10,
+        maximum_bytes: 4096,
+        maximum_value_bytes: 1024,
+        migrates_from: vec![1],
+    }];
+    assert!(manifest.validate().is_ok());
+    manifest.state[0].migrates_from.push(2);
+    assert_eq!(manifest.validate(), Err(ManifestError::Invalid));
+}
+
+#[test]
+fn public_manifest_fields_use_only_the_v3_camel_case_shape() {
+    let value = serde_json::to_value(source_manifest()).unwrap();
+    assert!(value.get("manifestVersion").is_some());
+    assert!(value.get("displayName").is_some());
+    assert!(value.get("configurationSchema").is_some());
+    assert!(value.get("schema_version").is_none());
+
+    let mut old = value;
+    old.as_object_mut()
+        .unwrap()
+        .insert("schema_version".into(), json!(3));
+    assert!(serde_json::from_value::<Manifest>(old).is_err());
+}
+
+#[test]
+fn contributes_rejects_duplicate_capability_keys_in_direct_json_parsing() {
+    let declaration = r#"{
+        "id":"test.example.middleware","version":1,"stages":["request"],
+        "inputFormats":["openai"],"outputFormats":["openai"]
+    }"#;
+    let manifest = format!(
+        r#"{{
+            "manifestVersion":3,"name":"example","displayName":"Example","publisher":"test",
+            "version":"1.0.0","description":"Example","license":"MIT",
+            "engines":{{"codex-proxy-rs":"*"}},"main":"bin/worker","runtime":"trustedProcess",
+            "contributes":{{"middleware":{declaration},"middleware":{declaration}}}
+        }}"#
+    );
+    assert!(serde_json::from_str::<Manifest>(&manifest).is_err());
+    assert_eq!(
+        Manifest::from_author_slice(manifest.as_bytes()),
+        Err(ManifestError::Invalid)
+    );
+
+    let handshake = format!(
+        r#"{{
+            "protocol_version":4,"artifact_sha256":"digest","plugin_id":"test.example",
+            "instance_id":"instance","generation":1,"incarnation":"incarnation",
+            "configuration":{{}},"permissions":[],
+            "contributes":{{"middleware":{declaration},"middleware":{declaration}}}
+        }}"#
+    );
+    assert!(serde_json::from_str::<Handshake>(&handshake).is_err());
+
+    let registration =
+        format!(r#"{{"contributes":{{"middleware":{declaration},"middleware":{declaration}}}}}"#);
+    assert!(serde_json::from_str::<Registration>(&registration).is_err());
+}
+
+#[test]
+fn contribution_declaration_uses_camel_case_description_fields() {
+    let declaration = ContributionDeclaration {
+        id: "test.example.executor".into(),
+        version: 1,
+        stages: vec![Stage::Execution],
+        input_formats: vec!["openai".into()],
+        output_formats: vec!["openai".into()],
+    };
+    assert_eq!(
+        serde_json::to_value(declaration).unwrap(),
+        json!({
+            "id":"test.example.executor",
+            "version":1,
+            "stages":["execution"],
+            "inputFormats":["openai"],
+            "outputFormats":["openai"]
+        })
+    );
+}
diff --git a/backend/crates/gateway-plugin/sdk/tests/message.rs b/backend/crates/gateway-plugin/sdk/tests/message.rs
new file mode 100644
index 000000000..f27fabc80
--- /dev/null
+++ b/backend/crates/gateway-plugin/sdk/tests/message.rs
@@ -0,0 +1,15 @@
+use gateway_plugin_sdk::{Frame, Message};
+
+#[test]
+fn diagnostics_do_not_render_peer_payloads_or_error_details() {
+    let secret = "sensitive-fixture-value";
+    let fault = gateway_plugin_sdk::PluginFault::new(gateway_plugin_sdk::ErrorCode::Fault, secret);
+    let frame = Frame {
+        message: Message::Result {
+            id: 1,
+            result: serde_json::json!({"credential":secret}),
+        },
+        payload: secret.as_bytes().to_vec(),
+    };
+    assert!(!format!("{frame:?} {fault:?}").contains(secret));
+}
diff --git a/backend/crates/gateway-protocol/src/openai/headers.rs b/backend/crates/gateway-protocol/src/openai/headers.rs
index 6c773af74..8cf4419a4 100644
--- a/backend/crates/gateway-protocol/src/openai/headers.rs
+++ b/backend/crates/gateway-protocol/src/openai/headers.rs
@@ -27,3 +27,55 @@ pub fn is_transport_managed_request_header(name: &str) -> bool {
                 | "x-request-id"
         )
 }
+
+/// 判断上游响应头是否可由客户端 HTTP adapter 或插件读取/改写。
+///
+/// `connection_options` 来自同一响应的 `Connection` 字段，调用方应先按逗号拆分并
+/// 转成小写。此函数同时拒绝逐跳头、实体 framing、认证材料和账号身份字段；所有
+/// 响应边界共用这一份分类，避免观测、加工和最终转发出现不同的泄漏面。
+#[must_use]
+pub fn response_header_is_forwardable(name: &str, connection_options: &[String]) -> bool {
+    let name = name.trim().to_ascii_lowercase();
+    if connection_options
+        .iter()
+        .any(|option| option.eq_ignore_ascii_case(&name))
+        || name.starts_with("sec-websocket-")
+    {
+        return false;
+    }
+
+    !matches!(
+        name.as_str(),
+        "connection"
+            | "keep-alive"
+            | "proxy-connection"
+            | "te"
+            | "trailer"
+            | "transfer-encoding"
+            | "upgrade"
+            | "content-length"
+            | "content-type"
+            | "content-encoding"
+            | "authorization"
+            | "x-api-key"
+            | "www-authenticate"
+            | "authentication-info"
+            | "proxy-authenticate"
+            | "proxy-authorization"
+            | "proxy-authentication-info"
+            | "cookie"
+            | "cookie2"
+            | "set-cookie"
+            | "set-cookie2"
+            | "chatgpt-account-id"
+            | "chatgpt-organization-id"
+            | "chatgpt-org-id"
+            | "chatgpt-project-id"
+            | "openai-organization"
+            | "openai-project"
+            | "x-openai-organization"
+            | "x-openai-project"
+            | "x-codex-installation-id"
+            | "x-codex-turn-metadata"
+    )
+}
diff --git a/backend/crates/gateway-protocol/src/openai/mod.rs b/backend/crates/gateway-protocol/src/openai/mod.rs
index b5370c886..60963e5b5 100644
--- a/backend/crates/gateway-protocol/src/openai/mod.rs
+++ b/backend/crates/gateway-protocol/src/openai/mod.rs
@@ -21,4 +21,4 @@ pub use codex::{
     CodexResponsesRequestSemantics, codex_responses_request_semantics,
     codex_responses_request_semantics_with_turn_metadata, codex_session_id, codex_thread_id,
 };
-pub use headers::is_transport_managed_request_header;
+pub use headers::{is_transport_managed_request_header, response_header_is_forwardable};
diff --git a/backend/crates/gateway-protocol/tests/openai/headers.rs b/backend/crates/gateway-protocol/tests/openai/headers.rs
index 546c4a98b..ede8f6bde 100644
--- a/backend/crates/gateway-protocol/tests/openai/headers.rs
+++ b/backend/crates/gateway-protocol/tests/openai/headers.rs
@@ -1,4 +1,6 @@
-use gateway_protocol::openai::is_transport_managed_request_header;
+use gateway_protocol::openai::{
+    is_transport_managed_request_header, response_header_is_forwardable,
+};
 
 #[test]
 fn transport_headers_should_include_hop_fields_and_compression() {
@@ -66,3 +68,27 @@ fn transport_headers_should_leave_business_extensions_to_the_protocol_owner() {
         );
     }
 }
+
+#[test]
+fn response_headers_should_reject_hop_identity_and_dynamic_connection_fields() {
+    let connection_options = vec!["x-hop".to_owned()];
+    for name in [
+        "connection",
+        "x-hop",
+        "content-length",
+        "authorization",
+        "set-cookie",
+        "chatgpt-account-id",
+        "x-openai-project",
+        "sec-websocket-accept",
+    ] {
+        assert!(
+            !response_header_is_forwardable(name, &connection_options),
+            "unexpectedly exposed {name}"
+        );
+    }
+    assert!(response_header_is_forwardable(
+        "x-ratelimit-remaining-requests",
+        &connection_options
+    ));
+}
diff --git a/backend/crates/gateway-store/Cargo.toml b/backend/crates/gateway-store/Cargo.toml
index 417a8873d..9d814cf10 100644
--- a/backend/crates/gateway-store/Cargo.toml
+++ b/backend/crates/gateway-store/Cargo.toml
@@ -29,7 +29,7 @@ secrecy = "0.10"
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
 sha2 = "0.11.0"
-sqlx = { version = "0.9.0", default-features = false, features = ["runtime-tokio", "tls-rustls", "postgres", "chrono", "json", "macros", "migrate"] }
+sqlx = { version = "0.9.0", default-features = false, features = ["runtime-tokio", "tls-rustls", "postgres", "chrono", "json", "macros", "migrate", "uuid"] }
 thiserror = "2.0.18"
 tokio = { version = "1.52", default-features = false, features = ["fs", "io-std", "io-util", "macros", "process", "rt", "sync", "time"] }
 tracing = "0.1.44"
diff --git a/backend/crates/gateway-store/src/admin_adapter.rs b/backend/crates/gateway-store/src/admin_adapter.rs
index fa9a4264d..4268d36b6 100644
--- a/backend/crates/gateway-store/src/admin_adapter.rs
+++ b/backend/crates/gateway-store/src/admin_adapter.rs
@@ -86,8 +86,7 @@ impl SettingsStore for AdminSettingsStoreAdapter {
             .map_err(|error| admin_store_error("runtime settings", error))?;
         let replacement = postgres::ControlPlaneReplacement {
             settings: postgres::RuntimeSettingsUpdate {
-                openai_client_profile: command.openai_client_profile,
-                xai_client_profile: command.xai_client_profile,
+                request_profile_updates: command.request_profile_updates,
                 admin_api_key: current.settings.admin_api_key,
                 refresh_margin_seconds: command.refresh_margin_seconds,
                 refresh_concurrency: command.refresh_concurrency,
@@ -232,8 +231,7 @@ pub(crate) fn admin_runtime_settings(
         })
         .collect::<AdminStoreResult<ModelMappings>>()?;
     Ok(AdminRuntimeSettings {
-        openai_client_profile: settings.openai_client_profile,
-        xai_client_profile: settings.xai_client_profile,
+        request_profiles: settings.request_profiles,
         config_revision: admin_revision(settings.config_revision)?,
         request_location_enabled: settings.request_location_enabled,
         request_location: settings.request_location,
diff --git a/backend/crates/gateway-store/src/bundle.rs b/backend/crates/gateway-store/src/bundle.rs
index 5d3f9288b..721e597aa 100644
--- a/backend/crates/gateway-store/src/bundle.rs
+++ b/backend/crates/gateway-store/src/bundle.rs
@@ -13,6 +13,8 @@ pub struct StoreBundle {
     worker_leader_lease: Arc<dyn WorkerLeaderLeasePort>,
     health_probes: Vec<Arc<dyn HealthProbe>>,
     worker_contributions: Vec<WorkerContribution>,
+    command_writers: Option<CommandStoreWriters>,
+    command_drain: Option<CommandStoreDrain>,
 }
 
 impl StoreBundle {
@@ -44,14 +46,62 @@ impl StoreBundle {
     pub fn take_worker_contributions(&mut self) -> Vec<WorkerContribution> {
         std::mem::take(&mut self.worker_contributions)
     }
+
+    /// 在插件命令真正执行前启动四个必要写泵；不注册任何后台业务 Worker。
+    pub fn start_command_line_writes(&mut self) -> Result<(), CommandStoreDrainError> {
+        if self.command_drain.is_some() {
+            return Err(CommandStoreDrainError);
+        }
+        let writers = self.command_writers.take().ok_or(CommandStoreDrainError)?;
+        self.command_drain = Some(writers.start());
+        Ok(())
+    }
+
+    /// 命令成功、失败或取消后有界排空账本、Key 使用、准入释放与 circuit 反馈。
+    pub async fn shutdown_command_line_writes(&mut self) -> Result<(), CommandStoreDrainError> {
+        match self.command_drain.take() {
+            Some(drain) => drain.shutdown().await,
+            None if self.command_writers.is_some() => Ok(()),
+            None => Err(CommandStoreDrainError),
+        }
+    }
+}
+
+#[derive(Clone, Copy)]
+enum StoreMode {
+    Runtime,
+    CommandLine,
 }
 
 /// 在返回 Bundle 前完成全部 Store 启动屏障。
-pub async fn initialize(mut config: StoreConfig) -> StoreResult<StoreBundle> {
+pub async fn initialize(config: StoreConfig) -> StoreResult<StoreBundle> {
+    connect(config, false, StoreMode::Runtime).await
+}
+
+/// CLI 命令使用同一有界写队列，但不贡献恢复、保留、leader 或维护 Worker。
+pub async fn initialize_command_line(config: StoreConfig) -> StoreResult<StoreBundle> {
+    connect(config, false, StoreMode::CommandLine).await
+}
+
+/// 读取现有安装描述，不迁移数据库；该 Bundle 的 PostgreSQL 连接默认只读。
+pub async fn initialize_read_only(config: StoreConfig) -> StoreResult<StoreBundle> {
+    connect(config, true, StoreMode::Runtime).await
+}
+
+async fn connect(
+    mut config: StoreConfig,
+    read_only: bool,
+    mode: StoreMode,
+) -> StoreResult<StoreBundle> {
     const REDIS_NAMESPACE: &str = "codex-proxy-rs";
 
     config.validate_resolved()?;
-    let pool = postgres::connect_and_migrate(&config.database_url()?, config.pool).await?;
+    let database_url = config.database_url()?;
+    let pool = if read_only {
+        postgres::connect_read_only(&database_url, config.pool).await?
+    } else {
+        postgres::connect_and_migrate(&database_url, config.pool).await?
+    };
     let observability_query_budget = postgres::ObservabilityQueryBudget::try_new(
         config.pool.observability_max_connections(),
         config.pool.acquire_timeout(),
@@ -79,7 +129,9 @@ pub async fn initialize(mut config: StoreConfig) -> StoreResult<StoreBundle> {
     let provider_leases = Arc::new(redis::RedisProviderLeaseCoordinator::new(
         credential_leases.clone(),
     ));
-    let provider_session_affinity = Arc::new(redis::RedisProviderSessionAffinityRepository::new(
+    let provider_session_affinity: Arc<
+        dyn gateway_core::provider_ports::ProviderSessionAffinityPort,
+    > = Arc::new(redis::RedisProviderSessionAffinityRepository::new(
         redis_connection.clone(),
         REDIS_NAMESPACE,
     )?);
@@ -97,6 +149,7 @@ pub async fn initialize(mut config: StoreConfig) -> StoreResult<StoreBundle> {
         REDIS_NAMESPACE,
     )?);
 
+    let plugins = Arc::new(postgres::PgPluginStore::new(pool.clone()));
     let admin_ports = AdminStorePorts::new(
         AdminAccountStorePorts::new(
             Arc::new(postgres::PgAdminAccountStore::new(
@@ -125,6 +178,8 @@ pub async fn initialize(mut config: StoreConfig) -> StoreResult<StoreBundle> {
             control_plane: postgres::PgControlPlaneRepository::new(pool.clone()),
         }),
         backup_ports(pool.clone(), &config)?,
+        plugins.clone(),
+        plugins,
     );
 
     let execution_repository = Arc::new(postgres::PgExecutionStore::new(pool.clone()));
@@ -171,7 +226,8 @@ pub async fn initialize(mut config: StoreConfig) -> StoreResult<StoreBundle> {
         ),
         Arc::new(client_key_usage),
     )
-    .with_budget(Arc::new(postgres::PgClientBudgetStore::new(pool.clone())));
+    .with_budget(Arc::new(postgres::PgClientBudgetStore::new(pool.clone())))
+    .with_session_affinity(Arc::clone(&provider_session_affinity));
 
     let provider_ports = ProviderStorePorts::new(
         account_store,
@@ -200,14 +256,28 @@ pub async fn initialize(mut config: StoreConfig) -> StoreResult<StoreBundle> {
             connection: redis_connection,
         }),
     ];
-    let worker_contributions = store_worker_contributions(
-        execution_repository,
-        execution_writer,
-        client_key_usage_writer,
-        admission_release_writer,
-        circuit_feedback_writer,
-        retention,
-    )?;
+    let (worker_contributions, command_writers) = match mode {
+        StoreMode::Runtime => (
+            store_worker_contributions(
+                execution_repository,
+                execution_writer,
+                client_key_usage_writer,
+                admission_release_writer,
+                circuit_feedback_writer,
+                retention,
+            )?,
+            None,
+        ),
+        StoreMode::CommandLine => (
+            Vec::new(),
+            Some(CommandStoreWriters {
+                execution: execution_writer,
+                client_key_usage: client_key_usage_writer,
+                admission_release: admission_release_writer,
+                circuit_feedback: circuit_feedback_writer,
+            }),
+        ),
+    };
     Ok(StoreBundle {
         admin_ports,
         core_ports,
@@ -215,6 +285,8 @@ pub async fn initialize(mut config: StoreConfig) -> StoreResult<StoreBundle> {
         worker_leader_lease,
         health_probes,
         worker_contributions,
+        command_writers,
+        command_drain: None,
     })
 }
 
diff --git a/backend/crates/gateway-store/src/lib.rs b/backend/crates/gateway-store/src/lib.rs
index 28f6e2d0a..935bc2416 100644
--- a/backend/crates/gateway-store/src/lib.rs
+++ b/backend/crates/gateway-store/src/lib.rs
@@ -43,5 +43,5 @@ pub(crate) use admin_adapter::*;
 pub use bundle::*;
 pub use config::*;
 pub use value::*;
-pub use workers::PostgresHealthProbe;
 pub(crate) use workers::*;
+pub use workers::{CommandStoreDrainError, PostgresHealthProbe};
diff --git a/backend/crates/gateway-store/src/postgres/client_keys.rs b/backend/crates/gateway-store/src/postgres/client_keys.rs
index 677028789..36c36f5fd 100644
--- a/backend/crates/gateway-store/src/postgres/client_keys.rs
+++ b/backend/crates/gateway-store/src/postgres/client_keys.rs
@@ -27,6 +27,7 @@ use gateway_admin::{
     ports::store::{AdminStoreResult, ClientKeyStore},
 };
 use gateway_core::{
+    account::OpaqueProviderData,
     engine::budget::{ClientBudgetLimits, ClientBudgetStatus},
     engine::execution::ClientApiKeyUsageSink,
     lifecycle::CancellationToken,
@@ -111,8 +112,7 @@ impl fmt::Debug for ClientApiKeySecret {
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientApiKeyRecord {
-    pub openai_client_profile_override: Option<gateway_core::account::OpaqueProviderData>,
-    pub xai_client_profile_override: Option<gateway_core::account::OpaqueProviderData>,
+    pub request_profile_overrides: BTreeMap<ProviderKind, OpaqueProviderData>,
     pub id: String,
     pub name: String,
     pub label: Option<String>,
@@ -273,8 +273,7 @@ pub struct ClientApiKeyPage {
 
 #[derive(Clone)]
 pub struct NewClientApiKey {
-    pub openai_client_profile_override: Option<gateway_core::account::OpaqueProviderData>,
-    pub xai_client_profile_override: Option<gateway_core::account::OpaqueProviderData>,
+    pub request_profile_overrides: BTreeMap<ProviderKind, OpaqueProviderData>,
     pub id: String,
     pub name: String,
     pub label: Option<String>,
@@ -301,14 +300,14 @@ impl NewClientApiKey {
         require_nonempty(ENTITY, "id", &self.id)?;
         require_nonempty(ENTITY, "name", &self.name)?;
         validate_group_ids(&self.group_ids)?;
+        validate_request_profiles(self.request_profile_overrides.values())?;
         validate_key(&self.key)
     }
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UpdateClientApiKeyDetails {
-    pub openai_client_profile_override: Option<Option<gateway_core::account::OpaqueProviderData>>,
-    pub xai_client_profile_override: Option<Option<gateway_core::account::OpaqueProviderData>>,
+    pub request_profile_override_updates: BTreeMap<ProviderKind, Option<OpaqueProviderData>>,
     pub id: String,
     pub name: String,
     pub label: Option<String>,
@@ -324,6 +323,14 @@ impl UpdateClientApiKeyDetails {
         require_nonempty(ENTITY, "id", &self.id)?;
         require_nonempty(ENTITY, "name", &self.name)?;
         validate_group_ids(&self.group_ids)?;
+        if self.request_profile_override_updates.len() > 256 {
+            return Err(invalid("request profiles exceed the supported bounds"));
+        }
+        validate_request_profiles(
+            self.request_profile_override_updates
+                .values()
+                .filter_map(Option::as_ref),
+        )?;
         to_i64(self.max_concurrency)?;
         to_i64(self.requests_per_minute)?;
         Ok(())
@@ -365,8 +372,7 @@ impl ClientApiKeyRepository for PgClientApiKeyRepository {
         query.validate()?;
         let total = count_client_api_keys(&self.pool, query.search.as_deref()).await?;
         let mut statement = QueryBuilder::<Postgres>::new(
-            "select k.id, k.name, k.label, k.provider_request_profiles_json -> 'openai' as openai_client_profile_override,
-                    k.provider_request_profiles_json -> 'xai' as xai_client_profile_override,
+            "select k.id, k.name, k.label, k.provider_request_profiles_json as request_profile_overrides,
                     left(k.key, least(10, length(k.key) / 2)) as prefix, k.enabled,
                     k.max_concurrency, k.requests_per_minute, k.last_used_at, k.created_at,
                     k.updated_at, '[]'::jsonb as groups, '{}'::text[] as provider_kinds
@@ -426,8 +432,7 @@ impl ClientApiKeyRepository for PgClientApiKeyRepository {
     async fn get_client_api_key(&self, id: &str) -> StoreResult<Option<ClientApiKeyRecord>> {
         require_nonempty(ENTITY, "id", id)?;
         let record = sqlx::query(
-            "select k.id, k.name, k.label, k.provider_request_profiles_json -> 'openai' as openai_client_profile_override,
-                    k.provider_request_profiles_json -> 'xai' as xai_client_profile_override,
+            "select k.id, k.name, k.label, k.provider_request_profiles_json as request_profile_overrides,
                     left(k.key, least(10, length(k.key) / 2)) as prefix, k.enabled,
                     k.max_concurrency, k.requests_per_minute, k.last_used_at, k.created_at,
                     k.updated_at, coalesce(groups.groups, '[]'::jsonb) as groups,
@@ -773,8 +778,7 @@ impl ClientKeyStore for PgAdminClientKeyStore {
             .control_plane
             .create_client_api_key(
                 NewClientApiKey {
-                    openai_client_profile_override: command.openai_client_profile_override,
-                    xai_client_profile_override: command.xai_client_profile_override,
+                    request_profile_overrides: command.request_profile_overrides,
                     id: id.as_str().to_owned(),
                     name: command.name,
                     label: command.label,
@@ -825,8 +829,7 @@ impl ClientKeyStore for PgAdminClientKeyStore {
             .control_plane
             .update_client_api_key(
                 UpdateClientApiKeyDetails {
-                    openai_client_profile_override: command.openai_client_profile_override,
-                    xai_client_profile_override: command.xai_client_profile_override,
+                    request_profile_override_updates: command.request_profile_override_updates,
                     id: id.as_str().to_owned(),
                     name: command.name,
                     label: command.label,
@@ -984,8 +987,7 @@ fn admin_client_key_cursor(cursor: ClientApiKeyCursor) -> AdminStoreResult<Admin
 
 fn admin_client_key_record(record: ClientApiKeyRecord) -> AdminStoreResult<AdminClientKeyRecord> {
     Ok(AdminClientKeyRecord {
-        openai_client_profile_override: record.openai_client_profile_override,
-        xai_client_profile_override: record.xai_client_profile_override,
+        request_profile_overrides: record.request_profile_overrides,
         id: ClientApiKeyId::new(record.id)
             .map_err(|_| admin_store_error(ENTITY, invalid("invalid client key id")))?,
         name: record.name,
@@ -1033,12 +1035,12 @@ pub(crate) async fn insert_client_api_key_in_transaction(
 ) -> StoreResult<()> {
     key.validate()?;
     ensure_client_key_name_available(transaction, &key.id, key.name.trim()).await?;
+    let request_profile_overrides = encode_request_profiles(&key.request_profile_overrides);
     sqlx::query(
         "insert into client_api_keys (
            id, name, label, key, enabled, max_concurrency, requests_per_minute,
            last_used_at, created_at, updated_at, daily_limit_usd, weekly_limit_usd, provider_request_profiles_json
-         ) values ($1, $2, $3, $4, true, $5, $6, null, now(), now(), $7::text::numeric, $8::text::numeric, case when $9::jsonb is null then '{}'::jsonb else jsonb_build_object('openai', $9::jsonb) end
-             || case when $10::jsonb is null then '{}'::jsonb else jsonb_build_object('xai', $10::jsonb) end)",
+         ) values ($1, $2, $3, $4, true, $5, $6, null, now(), now(), $7::text::numeric, $8::text::numeric, $9::jsonb)",
     )
     .bind(&key.id)
     .bind(key.name.trim())
@@ -1048,8 +1050,7 @@ pub(crate) async fn insert_client_api_key_in_transaction(
     .bind(to_i64(key.requests_per_minute)?)
     .bind(key.budget.daily_usd.canonical())
     .bind(key.budget.weekly_usd.canonical())
-    .bind(key.openai_client_profile_override.as_ref().map(|profile| sqlx::types::Json(profile.expose_to_provider())))
-    .bind(key.xai_client_profile_override.as_ref().map(|profile| sqlx::types::Json(profile.expose_to_provider())))
+    .bind(sqlx::types::Json(request_profile_overrides))
     .execute(&mut **transaction)
     .await
     .map_err(|error| {
@@ -1076,17 +1077,31 @@ pub(crate) async fn update_client_api_key_in_transaction(
 ) -> StoreResult<()> {
     key.validate()?;
     ensure_client_key_name_available(transaction, &key.id, key.name.trim()).await?;
+    let removed_profiles = key
+        .request_profile_override_updates
+        .keys()
+        .map(|provider| provider.as_str().to_owned())
+        .collect::<Vec<_>>();
+    let replacement_profiles = key
+        .request_profile_override_updates
+        .iter()
+        .filter_map(|(provider, profile)| {
+            profile.as_ref().map(|profile| {
+                (
+                    provider.as_str().to_owned(),
+                    profile.expose_to_provider().clone(),
+                )
+            })
+        })
+        .collect::<BTreeMap<_, _>>();
     let result = sqlx::query(
         "update client_api_keys
          set name = $2, label = $3, max_concurrency = $4,
              requests_per_minute = $5, updated_at = now(),
              daily_limit_usd = coalesce($6::text::numeric, daily_limit_usd),
              weekly_limit_usd = coalesce($7::text::numeric, weekly_limit_usd),
-             provider_request_profiles_json = (provider_request_profiles_json
-                 - case when $8 then array['openai'] else array[]::text[] end
-                 - case when $10 then array['xai'] else array[]::text[] end)
-                 || case when $9::jsonb is null then '{}'::jsonb else jsonb_build_object('openai', $9::jsonb) end
-                 || case when $11::jsonb is null then '{}'::jsonb else jsonb_build_object('xai', $11::jsonb) end
+             provider_request_profiles_json = (provider_request_profiles_json - $8::text[])
+                 || $9::jsonb
          where id = $1",
     )
     .bind(&key.id)
@@ -1096,20 +1111,8 @@ pub(crate) async fn update_client_api_key_in_transaction(
     .bind(to_i64(key.requests_per_minute)?)
     .bind(key.daily_limit_usd.map(|amount| amount.canonical()))
     .bind(key.weekly_limit_usd.map(|amount| amount.canonical()))
-    .bind(key.openai_client_profile_override.is_some())
-    .bind(
-        key.openai_client_profile_override
-            .as_ref()
-            .and_then(Option::as_ref)
-            .map(|profile| sqlx::types::Json(profile.expose_to_provider())),
-    )
-    .bind(key.xai_client_profile_override.is_some())
-    .bind(
-        key.xai_client_profile_override
-            .as_ref()
-            .and_then(Option::as_ref)
-            .map(|profile| sqlx::types::Json(profile.expose_to_provider())),
-    )
+    .bind(removed_profiles)
+    .bind(sqlx::types::Json(replacement_profiles))
     .execute(&mut **transaction)
     .await
     .map_err(|_| postgres_unavailable("update client API key in transaction"))?;
@@ -1241,6 +1244,48 @@ fn validate_key(key: &str) -> StoreResult<()> {
         .map_err(|_| invalid("key must contain nonempty visible ASCII characters"))
 }
 
+fn validate_request_profiles<'a>(
+    profiles: impl IntoIterator<Item = &'a OpaqueProviderData>,
+) -> StoreResult<()> {
+    for (index, profile) in profiles.into_iter().enumerate() {
+        if index >= 256
+            || serde_json::to_vec(profile.expose_to_provider())
+                .map_or(true, |encoded| encoded.len() > 64 * 1024)
+        {
+            return Err(invalid("request profiles exceed the supported bounds"));
+        }
+    }
+    Ok(())
+}
+
+fn encode_request_profiles(
+    profiles: &BTreeMap<ProviderKind, OpaqueProviderData>,
+) -> BTreeMap<String, serde_json::Map<String, serde_json::Value>> {
+    profiles
+        .iter()
+        .map(|(provider, profile)| {
+            (
+                provider.as_str().to_owned(),
+                profile.expose_to_provider().clone(),
+            )
+        })
+        .collect()
+}
+
+fn decode_request_profiles(
+    profiles: BTreeMap<String, serde_json::Map<String, serde_json::Value>>,
+) -> StoreResult<BTreeMap<ProviderKind, OpaqueProviderData>> {
+    profiles
+        .into_iter()
+        .map(|(provider, profile)| {
+            Ok((
+                ProviderKind::new(provider).map_err(|_| invalid("invalid request profile key"))?,
+                OpaqueProviderData::new(profile),
+            ))
+        })
+        .collect()
+}
+
 fn client_secret_from_row(
     row: (String, String, bool, i64, i64),
 ) -> StoreResult<ClientApiKeySecret> {
@@ -1258,51 +1303,49 @@ fn client_record_from_row(row: &sqlx::postgres::PgRow) -> StoreResult<ClientApiK
     let groups: serde_json::Value = row
         .try_get("groups")
         .map_err(|_| invalid("invalid groups"))?;
-    Ok(ClientApiKeyRecord {
-        openai_client_profile_override: row
-            .try_get::<Option<sqlx::types::Json<serde_json::Map<String, serde_json::Value>>>, _>(
-                "openai_client_profile_override",
-            )
-            .map_err(|_| invalid("invalid request profile"))?
-            .map(|value| gateway_core::account::OpaqueProviderData::new(value.0)),
-        xai_client_profile_override: row
-            .try_get::<Option<sqlx::types::Json<serde_json::Map<String, serde_json::Value>>>, _>(
-                "xai_client_profile_override",
-            )
-            .map_err(|_| invalid("invalid request profile"))?
-            .map(|value| gateway_core::account::OpaqueProviderData::new(value.0)),
-        id: row.try_get("id").map_err(|_| invalid("invalid id"))?,
-        name: row.try_get("name").map_err(|_| invalid("invalid name"))?,
-        label: row.try_get("label").map_err(|_| invalid("invalid label"))?,
-        groups: serde_json::from_value(groups).map_err(|_| invalid("invalid groups"))?,
-        provider_kinds: row
-            .try_get("provider_kinds")
-            .map_err(|_| invalid("invalid provider kinds"))?,
-        prefix: row
-            .try_get("prefix")
-            .map_err(|_| invalid("invalid prefix"))?,
-        enabled: row
-            .try_get("enabled")
-            .map_err(|_| invalid("invalid enabled"))?,
-        max_concurrency: to_u64(
-            row.try_get("max_concurrency")
-                .map_err(|_| invalid("invalid max concurrency"))?,
-        )?,
-        requests_per_minute: to_u64(
-            row.try_get("requests_per_minute")
-                .map_err(|_| invalid("invalid requests per minute"))?,
-        )?,
-        budget: ClientBudgetStatus::default(),
-        last_used_at: row
-            .try_get("last_used_at")
-            .map_err(|_| invalid("invalid last used at"))?,
-        created_at: row
-            .try_get("created_at")
-            .map_err(|_| invalid("invalid created at"))?,
-        updated_at: row
-            .try_get("updated_at")
-            .map_err(|_| invalid("invalid updated at"))?,
-    })
+    Ok(
+        ClientApiKeyRecord {
+            request_profile_overrides:
+                decode_request_profiles(
+                    row.try_get::<sqlx::types::Json<
+                        BTreeMap<String, serde_json::Map<String, serde_json::Value>>,
+                    >, _>("request_profile_overrides")
+                        .map_err(|_| invalid("invalid request profiles"))?
+                        .0,
+                )?,
+            id: row.try_get("id").map_err(|_| invalid("invalid id"))?,
+            name: row.try_get("name").map_err(|_| invalid("invalid name"))?,
+            label: row.try_get("label").map_err(|_| invalid("invalid label"))?,
+            groups: serde_json::from_value(groups).map_err(|_| invalid("invalid groups"))?,
+            provider_kinds: row
+                .try_get("provider_kinds")
+                .map_err(|_| invalid("invalid provider kinds"))?,
+            prefix: row
+                .try_get("prefix")
+                .map_err(|_| invalid("invalid prefix"))?,
+            enabled: row
+                .try_get("enabled")
+                .map_err(|_| invalid("invalid enabled"))?,
+            max_concurrency: to_u64(
+                row.try_get("max_concurrency")
+                    .map_err(|_| invalid("invalid max concurrency"))?,
+            )?,
+            requests_per_minute: to_u64(
+                row.try_get("requests_per_minute")
+                    .map_err(|_| invalid("invalid requests per minute"))?,
+            )?,
+            budget: ClientBudgetStatus::default(),
+            last_used_at: row
+                .try_get("last_used_at")
+                .map_err(|_| invalid("invalid last used at"))?,
+            created_at: row
+                .try_get("created_at")
+                .map_err(|_| invalid("invalid created at"))?,
+            updated_at: row
+                .try_get("updated_at")
+                .map_err(|_| invalid("invalid updated at"))?,
+        },
+    )
 }
 
 async fn count_client_api_keys(pool: &PgPool, search: Option<&str>) -> StoreResult<u64> {
diff --git a/backend/crates/gateway-store/src/postgres/execution_buffer.rs b/backend/crates/gateway-store/src/postgres/execution_buffer.rs
index bda0856e2..0107671ee 100644
--- a/backend/crates/gateway-store/src/postgres/execution_buffer.rs
+++ b/backend/crates/gateway-store/src/postgres/execution_buffer.rs
@@ -2,11 +2,12 @@
 
 use std::mem::size_of;
 use std::num::NonZeroUsize;
-use std::sync::Arc;
 use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Arc, OnceLock};
 use std::time::{Duration, Instant, SystemTime};
 
 use async_trait::async_trait;
+use futures::future::try_join_all;
 use gateway_core::engine::{
     AttemptRecord, ExecutionStore, IntermediateFailure, ModelRequestFinalization, ModelRequestId,
     NewModelRequest, ProbeFailure, RecoveryReport,
@@ -15,10 +16,11 @@ use gateway_core::error::{ProviderError, StoreError};
 use gateway_core::lifecycle::CancellationToken;
 use gateway_core::task::{DaemonTask, WorkerTaskError};
 use gateway_core::upstream::UpstreamSendState;
-use tokio::sync::{Mutex, mpsc};
+use tokio::sync::{Mutex, Notify, mpsc};
 
 const DEFAULT_QUEUE_CAPACITY: usize = 4_096;
 const DEFAULT_QUEUE_BYTE_CAPACITY: usize = 64 * 1024 * 1024;
+const PERSISTENCE_LANES: usize = 4;
 const SHUTDOWN_DRAIN_TIMEOUT: Duration = Duration::from_secs(2);
 
 /// 执行观测缓冲区的进程内累计状态。
@@ -39,6 +41,7 @@ pub struct ExecutionBufferStats {
 }
 
 struct ExecutionBufferState {
+    maximum_queued_items: usize,
     maximum_queued_bytes: usize,
     queued_items: AtomicUsize,
     queued_bytes: AtomicUsize,
@@ -46,11 +49,13 @@ struct ExecutionBufferState {
     dropped_total: AtomicU64,
     persisted_total: AtomicU64,
     write_failure_total: AtomicU64,
+    idle: Notify,
 }
 
 impl ExecutionBufferState {
-    fn new(maximum_queued_bytes: NonZeroUsize) -> Self {
+    fn new(maximum_queued_items: NonZeroUsize, maximum_queued_bytes: NonZeroUsize) -> Self {
         Self {
+            maximum_queued_items: maximum_queued_items.get(),
             maximum_queued_bytes: maximum_queued_bytes.get(),
             queued_items: AtomicUsize::new(0),
             queued_bytes: AtomicUsize::new(0),
@@ -58,11 +63,19 @@ impl ExecutionBufferState {
             dropped_total: AtomicU64::new(0),
             persisted_total: AtomicU64::new(0),
             write_failure_total: AtomicU64::new(0),
+            idle: Notify::new(),
         }
     }
 
-    fn reserve(&self, bytes: usize) -> bool {
-        let reserved = self
+    fn reserve(&self, bytes: usize) -> Result<(), ReservationFailure> {
+        self.queued_items
+            .fetch_update(Ordering::AcqRel, Ordering::Acquire, |current| {
+                current
+                    .checked_add(1)
+                    .filter(|next| *next <= self.maximum_queued_items)
+            })
+            .map_err(|_| ReservationFailure::ItemCapacity)?;
+        let bytes_reserved = self
             .queued_bytes
             .fetch_update(Ordering::AcqRel, Ordering::Acquire, |current| {
                 current
@@ -70,15 +83,22 @@ impl ExecutionBufferState {
                     .filter(|next| *next <= self.maximum_queued_bytes)
             })
             .is_ok();
-        if reserved {
-            self.queued_items.fetch_add(1, Ordering::Relaxed);
+        if !bytes_reserved {
+            self.release_item();
+            return Err(ReservationFailure::ByteCapacity);
         }
-        reserved
+        Ok(())
     }
 
     fn release(&self, bytes: usize) {
         self.queued_bytes.fetch_sub(bytes, Ordering::AcqRel);
-        self.queued_items.fetch_sub(1, Ordering::AcqRel);
+        self.release_item();
+    }
+
+    fn release_item(&self) {
+        if self.queued_items.fetch_sub(1, Ordering::AcqRel) == 1 {
+            self.idle.notify_waiters();
+        }
     }
 
     fn record_enqueued(&self) {
@@ -112,6 +132,21 @@ impl ExecutionBufferState {
     }
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum ReservationFailure {
+    ItemCapacity,
+    ByteCapacity,
+}
+
+impl ReservationFailure {
+    const fn reason(self) -> &'static str {
+        match self {
+            Self::ItemCapacity => "item_capacity",
+            Self::ByteCapacity => "byte_capacity",
+        }
+    }
+}
+
 fn saturating_increment(counter: &AtomicU64, increment: u64) {
     let _ = counter.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
         Some(current.saturating_add(increment))
@@ -124,7 +159,10 @@ fn saturating_increment(counter: &AtomicU64, increment: u64) {
 /// 等待 PostgreSQL，也不会看到 Store 错误。启动恢复仍直接访问底层 Store。
 pub struct BufferedExecutionStore<S: ?Sized> {
     inner: Arc<S>,
-    sender: mpsc::Sender<QueuedExecutionObservation>,
+    // lane transport 本身没有独立容量；所有发送只能经 `enqueue` 的全局 item/byte
+    // 预留进入，`QueuedExecutionObservation::drop` 负责归还，不能增加旁路发送入口。
+    senders: Box<[mpsc::UnboundedSender<QueuedExecutionObservation>]>,
+    next_unkeyed_lane: AtomicUsize,
     state: Arc<ExecutionBufferState>,
 }
 
@@ -156,17 +194,20 @@ impl<S: ?Sized> BufferedExecutionStore<S> {
         capacity: NonZeroUsize,
         maximum_queued_bytes: NonZeroUsize,
     ) -> (Self, ExecutionObservationWriter<S>) {
-        let (sender, receiver) = mpsc::channel(capacity.get());
-        let state = Arc::new(ExecutionBufferState::new(maximum_queued_bytes));
+        let lane_count = PERSISTENCE_LANES.min(capacity.get());
+        let (senders, receivers): (Vec<_>, Vec<_>) =
+            (0..lane_count).map(|_| mpsc::unbounded_channel()).unzip();
+        let state = Arc::new(ExecutionBufferState::new(capacity, maximum_queued_bytes));
         (
             Self {
                 inner: Arc::clone(&inner),
-                sender,
+                senders: senders.into_boxed_slice(),
+                next_unkeyed_lane: AtomicUsize::new(0),
                 state: Arc::clone(&state),
             },
             ExecutionObservationWriter {
                 inner,
-                receiver: Mutex::new(receiver),
+                receivers: receivers.into_iter().map(Mutex::new).collect(),
                 state,
             },
         )
@@ -182,29 +223,30 @@ impl<S: ?Sized> BufferedExecutionStore<S> {
             .estimated_bytes()
             .saturating_add(write.request_id().map_or(0, str::len))
             .max(1);
-        if !self.state.reserve(estimated_bytes) {
+        if let Err(failure) = self.state.reserve(estimated_bytes) {
             self.state.record_dropped(1);
             let stats = self.state.snapshot();
             tracing::warn!(
                 operation = write.operation(),
                 request_id = ?write.request_id(),
-                reason = "byte_capacity",
+                reason = failure.reason(),
                 estimated_bytes,
+                maximum_queued_items = self.state.maximum_queued_items,
                 maximum_queued_bytes = self.state.maximum_queued_bytes,
+                queued_items = stats.queued_items,
+                queued_bytes = stats.queued_bytes,
                 dropped_total = stats.dropped_total,
-                "执行观测队列字节预算不足，已丢弃本次写入"
+                "执行观测队列容量不足，已丢弃本次写入"
             );
             return;
         }
         let queued =
             QueuedExecutionObservation::new(write, estimated_bytes, Arc::clone(&self.state));
-        match self.sender.try_send(queued) {
+        let lane = self.lane(queued.request_id());
+        match self.senders[lane].send(queued) {
             Ok(()) => self.state.record_enqueued(),
             Err(error) => {
-                let (reason, queued) = match error {
-                    mpsc::error::TrySendError::Full(queued) => ("full", queued),
-                    mpsc::error::TrySendError::Closed(queued) => ("closed", queued),
-                };
+                let queued = error.0;
                 let operation = queued.operation();
                 let request_id = queued.request_id().map(ToOwned::to_owned);
                 drop(queued);
@@ -213,7 +255,8 @@ impl<S: ?Sized> BufferedExecutionStore<S> {
                 tracing::warn!(
                     operation,
                     request_id = ?request_id,
-                    reason,
+                    reason = "closed",
+                    lane,
                     queued_items = stats.queued_items,
                     queued_bytes = stats.queued_bytes,
                     dropped_total = stats.dropped_total,
@@ -222,6 +265,23 @@ impl<S: ?Sized> BufferedExecutionStore<S> {
             }
         }
     }
+
+    fn lane(&self, request_id: Option<&str>) -> usize {
+        request_id.map_or_else(
+            || self.next_unkeyed_lane.fetch_add(1, Ordering::Relaxed) % self.senders.len(),
+            |request_id| request_lane(request_id, self.senders.len()),
+        )
+    }
+}
+
+fn request_lane(request_id: &str, lane_count: usize) -> usize {
+    // request ID 由 Core 生成，不含用户选择的散列输入；固定散列只用于进程内顺序亲和。
+    let hash = request_id
+        .bytes()
+        .fold(0xcbf2_9ce4_8422_2325_u64, |hash, byte| {
+            (hash ^ u64::from(byte)).wrapping_mul(0x0000_0100_0000_01b3)
+        });
+    usize::try_from(hash % u64::try_from(lane_count).unwrap_or(u64::MAX)).unwrap_or(0)
 }
 
 #[async_trait]
@@ -316,10 +376,16 @@ where
     }
 }
 
-/// 由 Host 监督的单消费者，保证同一请求的观测命令按入队顺序落库。
+/// 由 Host 监督的固定并行写泵；同一 request ID 固定落在一个 lane 并按入队顺序落库。
+///
+/// lane transport 共享 Store 的全局 item/byte 预留，正在写入的项目同样计入总上限。
 pub struct ExecutionObservationWriter<S: ?Sized> {
     inner: Arc<S>,
-    receiver: Mutex<mpsc::Receiver<QueuedExecutionObservation>>,
+    receivers: Box<[Mutex<mpsc::UnboundedReceiver<QueuedExecutionObservation>>]>,
+    state: Arc<ExecutionBufferState>,
+}
+
+pub(crate) struct ExecutionBufferIdle {
     state: Arc<ExecutionBufferState>,
 }
 
@@ -328,6 +394,47 @@ impl<S: ?Sized> ExecutionObservationWriter<S> {
     pub fn stats(&self) -> ExecutionBufferStats {
         self.state.snapshot()
     }
+
+    /// 等待所有已接收写入结束一次持久化尝试。
+    ///
+    /// 队列计数包含正在写入的项目；失败沿用现有 fail-open 计数且不会由本方法重试。
+    /// 返回 `false` 表示到达截止时间时仍有排队或正在写入的项目。
+    pub async fn wait_until_idle(&self, deadline: Instant) -> bool {
+        self.idle().wait_until(deadline).await
+    }
+
+    pub(crate) fn idle(&self) -> ExecutionBufferIdle {
+        ExecutionBufferIdle {
+            state: Arc::clone(&self.state),
+        }
+    }
+}
+
+impl ExecutionBufferIdle {
+    /// 等待所有已接收写入结束一次持久化尝试；队列计数包含正在写入的项目，
+    /// 写入失败沿用现有 fail-open 计数且不在关闭路径重试。
+    pub(crate) async fn wait_until(&self, deadline: Instant) -> bool {
+        loop {
+            if self.state.queued_items.load(Ordering::Acquire) == 0 {
+                return true;
+            }
+            let idle = self.state.idle.notified();
+            tokio::pin!(idle);
+            let _ = idle.as_mut().enable();
+            // 在订阅前后各检查一次，覆盖最后一个写入恰好在注册等待时结束的竞态。
+            if self.state.queued_items.load(Ordering::Acquire) == 0 {
+                return true;
+            }
+            let remaining = deadline.saturating_duration_since(Instant::now());
+            if remaining.is_zero()
+                || tokio::time::timeout(remaining, idle.as_mut())
+                    .await
+                    .is_err()
+            {
+                return false;
+            }
+        }
+    }
 }
 
 impl<S> DaemonTask for ExecutionObservationWriter<S>
@@ -339,28 +446,90 @@ where
         cancellation: CancellationToken,
     ) -> futures::future::BoxFuture<'_, Result<(), WorkerTaskError>> {
         Box::pin(async move {
-            let mut receiver = self.receiver.lock().await;
-            loop {
-                let queued = tokio::select! {
-                    () = cancellation.cancelled() => {
-                        drain_on_shutdown(
-                            &mut receiver,
-                            self.inner.as_ref(),
-                            self.state.as_ref(),
-                        ).await;
-                        return Ok(());
-                    },
-                    queued = receiver.recv() => queued,
-                };
-                let Some(queued) = queued else {
-                    return Err(WorkerTaskError::safe("execution observation queue closed"));
-                };
-                persist_queued(queued, self.inner.as_ref()).await;
-            }
+            let shutdown_deadline = OnceLock::new();
+            try_join_all(self.receivers.iter().enumerate().map(|(lane, receiver)| {
+                run_lane(
+                    lane,
+                    receiver,
+                    self.inner.as_ref(),
+                    self.state.as_ref(),
+                    cancellation.clone(),
+                    &shutdown_deadline,
+                )
+            }))
+            .await?;
+            Ok(())
         })
     }
 }
 
+async fn run_lane<S>(
+    lane: usize,
+    receiver: &Mutex<mpsc::UnboundedReceiver<QueuedExecutionObservation>>,
+    store: &S,
+    state: &ExecutionBufferState,
+    cancellation: CancellationToken,
+    shutdown_deadline: &OnceLock<Instant>,
+) -> Result<(), WorkerTaskError>
+where
+    S: ExecutionStore + ?Sized,
+{
+    let mut receiver = receiver.lock().await;
+    loop {
+        let queued = tokio::select! {
+            biased;
+            () = cancellation.cancelled() => {
+                drain_on_shutdown(
+                    lane,
+                    &mut receiver,
+                    store,
+                    state,
+                    shared_shutdown_deadline(shutdown_deadline),
+                ).await;
+                return Ok(());
+            },
+            queued = receiver.recv() => queued,
+        };
+        let Some(queued) = queued else {
+            return Err(WorkerTaskError::safe(
+                "execution observation queue lane closed",
+            ));
+        };
+        let operation = queued.operation();
+        let request_id = queued.request_id().map(ToOwned::to_owned);
+        let mut persistence = Box::pin(persist_queued(queued, store));
+        tokio::select! {
+            biased;
+            () = cancellation.cancelled() => {
+                let deadline = shared_shutdown_deadline(shutdown_deadline);
+                let remaining = deadline.saturating_duration_since(Instant::now());
+                if remaining.is_zero()
+                    || tokio::time::timeout(remaining, &mut persistence).await.is_err()
+                {
+                    state.record_dropped(1);
+                    let stats = state.snapshot();
+                    tracing::warn!(
+                        operation,
+                        request_id = ?request_id,
+                        lane,
+                        dropped_total = stats.dropped_total,
+                        drain_timeout_ms = u64::try_from(SHUTDOWN_DRAIN_TIMEOUT.as_millis())
+                            .unwrap_or(u64::MAX),
+                        "执行观测队列关闭时当前写入未在期限内完成，已停止等待"
+                    );
+                }
+                drain_on_shutdown(lane, &mut receiver, store, state, deadline).await;
+                return Ok(());
+            },
+            () = &mut persistence => {},
+        }
+    }
+}
+
+fn shared_shutdown_deadline(deadline: &OnceLock<Instant>) -> Instant {
+    *deadline.get_or_init(|| Instant::now() + SHUTDOWN_DRAIN_TIMEOUT)
+}
+
 async fn persist_queued<S>(mut queued: QueuedExecutionObservation, store: &S)
 where
     S: ExecutionStore + ?Sized,
@@ -396,19 +565,20 @@ where
 }
 
 async fn drain_on_shutdown<S>(
-    receiver: &mut mpsc::Receiver<QueuedExecutionObservation>,
+    lane: usize,
+    receiver: &mut mpsc::UnboundedReceiver<QueuedExecutionObservation>,
     store: &S,
     state: &ExecutionBufferState,
+    deadline: Instant,
 ) where
     S: ExecutionStore + ?Sized,
 {
     receiver.close();
     let queued_at_shutdown = receiver.len();
-    let started_at = Instant::now();
     let mut dropped = 0_usize;
 
     while let Some(queued) = receiver.recv().await {
-        let remaining = SHUTDOWN_DRAIN_TIMEOUT.saturating_sub(started_at.elapsed());
+        let remaining = deadline.saturating_duration_since(Instant::now());
         if remaining.is_zero() {
             drop(queued);
             dropped = dropped.saturating_add(1);
@@ -431,6 +601,7 @@ async fn drain_on_shutdown<S>(
         state.record_dropped(dropped);
         let stats = state.snapshot();
         tracing::warn!(
+            lane,
             queued_at_shutdown,
             dropped,
             dropped_total = stats.dropped_total,
@@ -439,7 +610,7 @@ async fn drain_on_shutdown<S>(
             "执行观测队列关闭排空超时，剩余写入已丢弃"
         );
     } else if queued_at_shutdown > 0 {
-        tracing::info!(queued_at_shutdown, "执行观测队列已在关闭前排空");
+        tracing::info!(lane, queued_at_shutdown, "执行观测队列已在关闭前排空");
     }
 }
 
diff --git a/backend/crates/gateway-store/src/postgres/mod.rs b/backend/crates/gateway-store/src/postgres/mod.rs
index 714926d4c..011e3463b 100644
--- a/backend/crates/gateway-store/src/postgres/mod.rs
+++ b/backend/crates/gateway-store/src/postgres/mod.rs
@@ -21,6 +21,7 @@ mod execution;
 mod execution_buffer;
 mod observability;
 mod ops_events;
+mod plugins;
 mod pricing;
 mod provider_accounts;
 mod proxies;
@@ -39,6 +40,7 @@ pub use execution::*;
 pub use execution_buffer::*;
 pub use observability::*;
 pub use ops_events::*;
+pub use plugins::PgPluginStore;
 pub use provider_accounts::*;
 pub use proxies::PgProxyRepository;
 pub use retention::*;
@@ -81,6 +83,26 @@ pub async fn connect_and_migrate(
     }
     migration_pool.close().await;
 
+    connect_pool(connect_options, pool_config, false).await
+}
+
+/// 帮助查询不执行迁移，并用连接默认只读事务阻止意外业务写入。
+pub(crate) async fn connect_read_only(
+    database_url: &str,
+    pool_config: StorePoolConfig,
+) -> StoreResult<PgPool> {
+    pool_config.validate()?;
+    let options = database_url
+        .parse::<PgConnectOptions>()
+        .map_err(|_| postgres_unavailable("parse PostgreSQL connection options"))?;
+    connect_pool(options, pool_config, true).await
+}
+
+async fn connect_pool(
+    connect_options: PgConnectOptions,
+    pool_config: StorePoolConfig,
+    read_only: bool,
+) -> StoreResult<PgPool> {
     let statement_timeout = postgres_duration_setting(POSTGRES_STATEMENT_TIMEOUT);
     let lock_timeout = postgres_duration_setting(POSTGRES_LOCK_TIMEOUT);
     let idle_in_transaction_session_timeout =
@@ -98,11 +120,13 @@ pub async fn connect_and_migrate(
                 sqlx::query(
                     "select set_config('statement_timeout', $1, false),
                             set_config('lock_timeout', $2, false),
-                            set_config('idle_in_transaction_session_timeout', $3, false)",
+                            set_config('idle_in_transaction_session_timeout', $3, false),
+                            set_config('default_transaction_read_only', $4, false)",
                 )
                 .bind(statement_timeout)
                 .bind(lock_timeout)
                 .bind(idle_in_transaction_session_timeout)
+                .bind(if read_only { "on" } else { "off" })
                 .execute(connection)
                 .await?;
                 Ok(())
diff --git a/backend/crates/gateway-store/src/postgres/observability/admin_adapter.rs b/backend/crates/gateway-store/src/postgres/observability/admin_adapter.rs
index 21f7c1421..1c031c9d6 100644
--- a/backend/crates/gateway-store/src/postgres/observability/admin_adapter.rs
+++ b/backend/crates/gateway-store/src/postgres/observability/admin_adapter.rs
@@ -212,6 +212,15 @@ impl ObservabilityRepository for PgObservabilityRepository {
             .await
     }
 
+    async fn usage_provider_kinds(&self, range: ObservabilityRange) -> StoreResult<Vec<String>> {
+        self.query_budget
+            .run(
+                "load usage providers",
+                usage_provider_kinds(&self.pool, range),
+            )
+            .await
+    }
+
     async fn usage_record_detail(&self, request_id: &str) -> StoreResult<UsageRecordDetail> {
         self.query_budget
             .run(
@@ -411,6 +420,16 @@ impl AdminObservabilityStore for PgAdminObservabilityStore {
         admin_usage_page(page)
     }
 
+    async fn usage_provider_kinds(
+        &self,
+        range: admin_observability::TimeRange,
+    ) -> AdminStoreResult<Vec<String>> {
+        self.repository
+            .usage_provider_kinds(store_range(range)?)
+            .await
+            .map_err(observability_error)
+    }
+
     async fn usage_record_detail(
         &self,
         request_id: &str,
diff --git a/backend/crates/gateway-store/src/postgres/observability/model.rs b/backend/crates/gateway-store/src/postgres/observability/model.rs
index 496f8336a..e3cdc6a7f 100644
--- a/backend/crates/gateway-store/src/postgres/observability/model.rs
+++ b/backend/crates/gateway-store/src/postgres/observability/model.rs
@@ -782,6 +782,7 @@ pub trait ObservabilityRepository: Send + Sync {
         query: ProviderAccountUsageQuery,
     ) -> StoreResult<Vec<ProviderAccountUsageObservation>>;
     async fn list_usage_records(&self, query: UsageRecordQuery) -> StoreResult<UsageRecordPage>;
+    async fn usage_provider_kinds(&self, range: ObservabilityRange) -> StoreResult<Vec<String>>;
     async fn usage_record_detail(&self, request_id: &str) -> StoreResult<UsageRecordDetail>;
     async fn usage_summary(
         &self,
diff --git a/backend/crates/gateway-store/src/postgres/observability/queries/ops.rs b/backend/crates/gateway-store/src/postgres/observability/queries/ops.rs
index 4f96344b1..ffe9f4f16 100644
--- a/backend/crates/gateway-store/src/postgres/observability/queries/ops.rs
+++ b/backend/crates/gateway-store/src/postgres/observability/queries/ops.rs
@@ -68,6 +68,32 @@ left join model_requests mr on mr.id = oe.model_request_id
 left join client_api_keys client_key on client_key.id = mr.client_api_key_ref
 where true";
 
+pub(crate) async fn usage_provider_kinds(
+    pool: &PgPool,
+    range: ObservabilityRange,
+) -> StoreResult<Vec<String>> {
+    let mut statement = QueryBuilder::<Postgres>::new(
+        "select provider_kind from (
+           select mr.provider_kind from model_requests mr where mr.provider_kind is not null",
+    );
+    push_range(&mut statement, "mr.started_at", range);
+    // 长请求可能在区间外开始、区间内报错，复用错误列表的完成时刻口径。
+    statement.push(
+        " union select mr.provider_kind from model_requests mr where mr.provider_kind is not null",
+    );
+    push_request_error_predicates(&mut statement, range, &OpsErrorFilter::default());
+    statement.push(
+        " union select oe.provider_kind from ops_events oe where oe.provider_kind is not null",
+    );
+    push_ops_event_predicates(&mut statement, range, &OpsErrorFilter::default());
+    statement.push(") providers order by provider_kind");
+    statement
+        .build_query_scalar()
+        .fetch_all(pool)
+        .await
+        .map_err(|_| postgres_unavailable("load usage providers"))
+}
+
 pub(crate) async fn list_ops_errors(
     pool: &PgPool,
     query: OpsErrorQuery,
diff --git a/backend/crates/gateway-store/src/postgres/plugins/artifacts.rs b/backend/crates/gateway-store/src/postgres/plugins/artifacts.rs
new file mode 100644
index 000000000..dfc79c2f0
--- /dev/null
+++ b/backend/crates/gateway-store/src/postgres/plugins/artifacts.rs
@@ -0,0 +1,392 @@
+use async_trait::async_trait;
+use gateway_admin::model::plugins::distribution::{SourceCredential, SourceCredentialInfo};
+use gateway_admin::{
+    model::{
+        MutationContext, Revision,
+        plugins::{
+            InspectedPluginArtifact, InstalledPluginArtifact, PluginArtifactMetadata,
+            PluginArtifactMutation, PluginSource,
+        },
+    },
+    ports::{
+        plugins::PluginStore,
+        store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult},
+    },
+};
+use sqlx::{PgPool, Row as _};
+
+use super::super::{append_admin_audit_event_in_transaction, bump_config_revision_in_transaction};
+use crate::{admin_revision, admin_store_error, mutation_audit};
+
+pub struct PgPluginStore {
+    pub(super) pool: PgPool,
+}
+
+impl PgPluginStore {
+    #[must_use]
+    pub fn new(pool: PgPool) -> Self {
+        Self { pool }
+    }
+}
+
+pub(super) fn unavailable() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Unavailable,
+        "plugin",
+        "plugin artifact store is unavailable",
+    )
+}
+pub(super) fn conflict() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Conflict,
+        "plugin",
+        "plugin artifact already exists with different content or source",
+    )
+}
+pub(super) fn not_found() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::NotFound,
+        "plugin",
+        "plugin artifact does not exist",
+    )
+}
+
+pub(super) fn decode_metadata(
+    row: &sqlx::postgres::PgRow,
+) -> AdminStoreResult<PluginArtifactMetadata> {
+    let mut metadata: serde_json::Value =
+        row.try_get("metadata_json").map_err(|_| unavailable())?;
+    // 兼容开发期已写入的展示说明；忽略这一旧字段，其他未知字段仍严格拒绝。
+    if let Some(metadata) = metadata.as_object_mut() {
+        metadata.remove("permissionDescriptions");
+    }
+    serde_json::from_value(metadata).map_err(|_| unavailable())
+}
+
+fn decode(row: &sqlx::postgres::PgRow) -> AdminStoreResult<InstalledPluginArtifact> {
+    let source: sqlx::types::Json<PluginSource> =
+        row.try_get("source_json").map_err(|_| unavailable())?;
+    Ok(InstalledPluginArtifact {
+        metadata: decode_metadata(row)?,
+        source: source.0,
+        installed_at: row.try_get("installed_at").map_err(|_| unavailable())?,
+        accepted_at: row.try_get("accepted_at").map_err(|_| unavailable())?,
+    })
+}
+
+#[async_trait]
+impl PluginStore for PgPluginStore {
+    async fn management_target_is_current(
+        &self,
+        target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+    ) -> AdminStoreResult<bool> {
+        super::instances::management_target_is_current(&self.pool, target).await
+    }
+    async fn load_instances(
+        &self,
+    ) -> AdminStoreResult<gateway_admin::model::plugins::instances::PluginInstanceSnapshot> {
+        super::instances::load(&self.pool).await
+    }
+    async fn load_version_configuration(
+        &self,
+        id: &str,
+        digest: &str,
+    ) -> AdminStoreResult<
+        Option<gateway_admin::model::plugins::instances::PluginVersionConfiguration>,
+    > {
+        super::instances::load_version_configuration(&self.pool, id, digest).await
+    }
+    async fn configuration_versions(&self, id: &str) -> AdminStoreResult<Vec<String>> {
+        super::instances::configuration_versions(&self.pool, id).await
+    }
+    async fn save_instance(
+        &self,
+        instance: gateway_admin::model::plugins::instances::PluginInstance,
+        expected: Revision,
+        context: &MutationContext,
+    ) -> AdminStoreResult<gateway_admin::model::plugins::instances::PluginInstanceMutation> {
+        super::instances::save(&self.pool, instance, expected, context).await
+    }
+    async fn save_instance_with_state(
+        &self,
+        instance: gateway_admin::model::plugins::instances::PluginInstance,
+        expected: Revision,
+        state: gateway_admin::model::plugins::state::PluginStateCommit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<gateway_admin::model::plugins::instances::PluginInstanceMutation> {
+        super::instances::save_with_state(&self.pool, instance, expected, &state, &[], context)
+            .await
+    }
+    async fn save_instance_replacing(
+        &self,
+        instance: gateway_admin::model::plugins::instances::PluginInstance,
+        expected: Revision,
+        state: gateway_admin::model::plugins::state::PluginStateCommit,
+        replacements: &[gateway_admin::model::plugins::instances::PluginInstanceReplacement],
+        context: &MutationContext,
+    ) -> AdminStoreResult<gateway_admin::model::plugins::instances::PluginInstanceMutation> {
+        super::instances::save_with_state(
+            &self.pool,
+            instance,
+            expected,
+            &state,
+            replacements,
+            context,
+        )
+        .await
+    }
+    async fn delete_instance(
+        &self,
+        id: &str,
+        expected: Revision,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        super::instances::delete(&self.pool, id, expected, context).await
+    }
+    async fn list_update_sources(
+        &self,
+    ) -> AdminStoreResult<Vec<gateway_admin::model::plugins::distribution::PluginSourceBinding>>
+    {
+        super::sources::list(&self.pool).await
+    }
+    async fn change_update_source(
+        &self,
+        binding: gateway_admin::model::plugins::distribution::PluginSourceBinding,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        super::sources::change(&self.pool, binding, context).await
+    }
+    async fn list_source_credentials(&self) -> AdminStoreResult<Vec<SourceCredentialInfo>> {
+        super::credentials::list(&self.pool).await
+    }
+    async fn load_source_credential(&self, id: &str) -> AdminStoreResult<SourceCredential> {
+        super::credentials::load(&self.pool, id).await
+    }
+    async fn save_source_credential(
+        &self,
+        credential: SourceCredential,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        super::credentials::save(&self.pool, credential, context).await
+    }
+    async fn delete_source_credential(
+        &self,
+        id: &str,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        super::credentials::delete(&self.pool, id, context).await
+    }
+    async fn list_artifacts(&self) -> AdminStoreResult<Vec<InstalledPluginArtifact>> {
+        let rows = sqlx::query("select metadata_json, source_json, installed_at, accepted_at from plugin_artifacts order by plugin_id, installed_at, sha256")
+            .fetch_all(&self.pool).await.map_err(|_| unavailable())?;
+        rows.iter().map(decode).collect()
+    }
+
+    async fn load_artifact(&self, digest: &str) -> AdminStoreResult<InspectedPluginArtifact> {
+        let row =
+            sqlx::query("select metadata_json, archive from plugin_artifacts where sha256 = $1")
+                .bind(digest)
+                .fetch_optional(&self.pool)
+                .await
+                .map_err(|_| unavailable())?
+                .ok_or_else(not_found)?;
+        let archive: Vec<u8> = row.try_get("archive").map_err(|_| unavailable())?;
+        Ok(InspectedPluginArtifact {
+            metadata: decode_metadata(&row)?,
+            archive: archive.into(),
+        })
+    }
+
+    async fn install_artifact(
+        &self,
+        artifact: InspectedPluginArtifact,
+        source: PluginSource,
+        context: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        let mut transaction = self.pool.begin().await.map_err(|_| unavailable())?;
+        let current_revision: i64 = sqlx::query_scalar(
+            "select config_revision from runtime_settings where id=1 for update",
+        )
+        .fetch_one(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?;
+        let metadata = artifact.metadata;
+        let outbound_proxy = source.outbound_proxy().cloned();
+        super::sources::bind(
+            &mut transaction,
+            &metadata.plugin_id,
+            (&source).into(),
+            outbound_proxy.as_ref(),
+        )
+        .await?;
+        if let Some(row) = sqlx::query(
+            "select metadata_json, source_json, installed_at, accepted_at from plugin_artifacts where sha256=$1",
+        )
+        .bind(&metadata.sha256)
+        .fetch_optional(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?
+        {
+            let artifact = decode(&row)?;
+            // 当前允许来源已由 bind 校验。同一包换用已授权的下载入口时保留首次出处，
+            // 但不能借重复安装把自定义包提升为内置包，或反向改写内置包的信任身份。
+            let same_trust_origin = matches!(&artifact.source, PluginSource::Builtin { .. })
+                == matches!(&source, PluginSource::Builtin { .. });
+            if artifact.metadata != metadata || !same_trust_origin {
+                return Err(conflict());
+            }
+            transaction.commit().await.map_err(|_| unavailable())?;
+            return Ok(PluginArtifactMutation {
+                config_revision: Revision::new(
+                    u64::try_from(current_revision).map_err(|_| unavailable())?,
+                )
+                .map_err(|_| unavailable())?,
+                artifact,
+            });
+        }
+        let revision = bump_config_revision_in_transaction(&mut transaction)
+            .await
+            .map_err(|error| admin_store_error("plugin", error))?;
+        let mut platforms = metadata.platforms.clone();
+        platforms.sort();
+        let row = sqlx::query("insert into plugin_artifacts (sha256, plugin_id, version, metadata_json, source_json, outbound_proxy_id, archive) values ($1,$2,$3,$4,$5,$6,$7) returning metadata_json, source_json, installed_at, accepted_at")
+            .bind(&metadata.sha256).bind(&metadata.plugin_id).bind(&metadata.version)
+            .bind(sqlx::types::Json(&metadata)).bind(sqlx::types::Json(&source))
+            .bind(outbound_proxy.map(|proxy| proxy.id)).bind(artifact.archive.as_ref())
+            .fetch_one(&mut *transaction).await.map_err(|error| {
+                if error.as_database_error().is_some_and(|error| error.is_unique_violation()) { conflict() } else { unavailable() }
+            })?;
+        for id in source.credential_ids() {
+            let id = uuid::Uuid::parse_str(id).map_err(|_| conflict())?;
+            sqlx::query("insert into plugin_artifact_credentials(artifact_sha256,credential_id) values ($1,$2)")
+                .bind(&metadata.sha256).bind(id).execute(&mut *transaction).await.map_err(|_| conflict())?;
+        }
+        for platform in platforms {
+            sqlx::query("insert into plugin_artifact_platforms (plugin_id, version, platform, artifact_sha256) values ($1,$2,$3,$4)")
+                .bind(&metadata.plugin_id).bind(&metadata.version).bind(platform).bind(&metadata.sha256)
+                .execute(&mut *transaction).await.map_err(|error| {
+                    if error.as_database_error().is_some_and(|error| error.is_unique_violation()) { conflict() } else { unavailable() }
+                })?;
+        }
+        append_admin_audit_event_in_transaction(
+            &mut transaction,
+            mutation_audit(
+                context,
+                "install",
+                "plugin_artifact",
+                &metadata.plugin_id,
+                vec!["artifact".into(), "source".into()],
+            ),
+            revision,
+        )
+        .await
+        .map_err(|error| admin_store_error("plugin", error))?;
+        let artifact = decode(&row)?;
+        transaction.commit().await.map_err(|_| unavailable())?;
+        Ok(PluginArtifactMutation {
+            config_revision: admin_revision(revision)?,
+            artifact,
+        })
+    }
+
+    async fn accept_artifact(
+        &self,
+        digest: &str,
+        context: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation> {
+        let mut transaction = self.pool.begin().await.map_err(|_| unavailable())?;
+        let current: i64 = sqlx::query_scalar(
+            "select config_revision from runtime_settings where id=1 for update",
+        )
+        .fetch_one(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?;
+        let row = sqlx::query("select metadata_json, source_json, installed_at, accepted_at from plugin_artifacts where sha256=$1 for update")
+            .bind(digest).fetch_optional(&mut *transaction).await.map_err(|_| unavailable())?
+            .ok_or_else(not_found)?;
+        let mut artifact = decode(&row)?;
+        let config_revision = if artifact.accepted_at.is_some() {
+            Revision::new(u64::try_from(current).map_err(|_| unavailable())?)
+                .map_err(|_| unavailable())?
+        } else {
+            let accepted_at: chrono::DateTime<chrono::Utc> = sqlx::query_scalar("update plugin_artifacts set accepted_at=now() where sha256=$1 returning accepted_at")
+                .bind(digest).fetch_one(&mut *transaction).await.map_err(|_| unavailable())?;
+            artifact.accepted_at = Some(accepted_at);
+            let revision = bump_config_revision_in_transaction(&mut transaction)
+                .await
+                .map_err(|error| admin_store_error("plugin", error))?;
+            append_admin_audit_event_in_transaction(
+                &mut transaction,
+                mutation_audit(
+                    context,
+                    "accept",
+                    "plugin_artifact",
+                    digest,
+                    vec!["permissions".into()],
+                ),
+                revision,
+            )
+            .await
+            .map_err(|error| admin_store_error("plugin", error))?;
+            admin_revision(revision)?
+        };
+        transaction.commit().await.map_err(|_| unavailable())?;
+        Ok(PluginArtifactMutation {
+            config_revision,
+            artifact,
+        })
+    }
+
+    async fn delete_artifact(
+        &self,
+        digest: &str,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        let mut transaction = self.pool.begin().await.map_err(|_| unavailable())?;
+        let revision = bump_config_revision_in_transaction(&mut transaction)
+            .await
+            .map_err(|error| admin_store_error("plugin", error))?;
+        // 制品删除会级联移除下载引用，先固定本次涉及的凭据，不能清扫无关的未使用凭据。
+        let credential_ids: Vec<uuid::Uuid> = sqlx::query_scalar(
+            "select credential_id from plugin_artifact_credentials where artifact_sha256=$1",
+        )
+        .bind(digest)
+        .fetch_all(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?;
+        let id: String = sqlx::query_scalar(
+            "delete from plugin_artifacts where sha256 = $1 returning plugin_id",
+        )
+        .bind(digest)
+        .fetch_optional(&mut *transaction)
+        .await
+        .map_err(|error| {
+            if error.as_database_error().is_some_and(|error| {
+                error.is_foreign_key_violation() || error.code().as_deref() == Some("23001")
+            }) {
+                conflict()
+            } else {
+                unavailable()
+            }
+        })?
+        .ok_or_else(not_found)?;
+        super::sources::delete_if_unused(&mut transaction, &id, context, revision).await?;
+        super::credentials::delete_unused(&mut transaction, &credential_ids, context, revision)
+            .await?;
+        append_admin_audit_event_in_transaction(
+            &mut transaction,
+            mutation_audit(
+                context,
+                "delete",
+                "plugin_artifact",
+                &id,
+                vec!["artifact".into()],
+            ),
+            revision,
+        )
+        .await
+        .map_err(|error| admin_store_error("plugin", error))?;
+        transaction.commit().await.map_err(|_| unavailable())?;
+        admin_revision(revision)
+    }
+}
diff --git a/backend/crates/gateway-store/src/postgres/plugins/credentials.rs b/backend/crates/gateway-store/src/postgres/plugins/credentials.rs
new file mode 100644
index 000000000..11cec8626
--- /dev/null
+++ b/backend/crates/gateway-store/src/postgres/plugins/credentials.rs
@@ -0,0 +1,169 @@
+use gateway_admin::{
+    model::{
+        MutationContext, Revision,
+        plugins::distribution::{SourceAuthentication, SourceCredential, SourceCredentialInfo},
+    },
+    ports::store::AdminStoreResult,
+};
+use secrecy::ExposeSecret as _;
+use sqlx::{PgPool, Postgres, Row as _, Transaction};
+
+use super::super::{append_admin_audit_event_in_transaction, bump_config_revision_in_transaction};
+use super::artifacts::{conflict, not_found, unavailable};
+use crate::{admin_revision, admin_store_error, mutation_audit};
+
+pub(super) async fn list(pool: &PgPool) -> AdminStoreResult<Vec<SourceCredentialInfo>> {
+    let rows: Vec<sqlx::types::Json<SourceCredentialInfo>> =
+        sqlx::query_scalar("select info_json from plugin_source_credentials order by id")
+            .fetch_all(pool)
+            .await
+            .map_err(|_| unavailable())?;
+    Ok(rows.into_iter().map(|row| row.0).collect())
+}
+
+pub(super) async fn load(pool: &PgPool, id: &str) -> AdminStoreResult<SourceCredential> {
+    let id = uuid::Uuid::parse_str(id).map_err(|_| not_found())?;
+    let row =
+        sqlx::query("select info_json, secret_json from plugin_source_credentials where id=$1")
+            .bind(id)
+            .fetch_optional(pool)
+            .await
+            .map_err(|_| unavailable())?
+            .ok_or_else(not_found)?;
+    let info: sqlx::types::Json<SourceCredentialInfo> =
+        row.try_get("info_json").map_err(|_| unavailable())?;
+    let authentication: sqlx::types::Json<SourceAuthentication> =
+        row.try_get("secret_json").map_err(|_| unavailable())?;
+    Ok(SourceCredential {
+        info: info.0,
+        authentication: authentication.0,
+    })
+}
+
+pub(super) async fn save(
+    pool: &PgPool,
+    credential: SourceCredential,
+    context: &MutationContext,
+) -> AdminStoreResult<Revision> {
+    let id = uuid::Uuid::parse_str(&credential.info.id).map_err(|_| unavailable())?;
+    // 只有持久化边界显式展开 secret，不给敏感领域类型实现通用 Serialize。
+    let secret = match &credential.authentication {
+        SourceAuthentication::Github { token } => {
+            serde_json::json!({"kind":"github", "token":token.expose_secret()})
+        }
+        SourceAuthentication::Bearer { token } => {
+            serde_json::json!({"kind":"bearer", "token":token.expose_secret()})
+        }
+        SourceAuthentication::Basic { username, password } => {
+            serde_json::json!({"kind":"basic", "username":username, "password":password.expose_secret()})
+        }
+        SourceAuthentication::Header { name, value } => {
+            serde_json::json!({"kind":"header", "name":name, "value":value.expose_secret()})
+        }
+    };
+    let mut tx = pool.begin().await.map_err(|_| unavailable())?;
+    let revision = bump_config_revision_in_transaction(&mut tx)
+        .await
+        .map_err(|e| admin_store_error("plugin", e))?;
+    sqlx::query(
+        "insert into plugin_source_credentials(id,info_json,secret_json) values ($1,$2,$3)",
+    )
+    .bind(id)
+    .bind(sqlx::types::Json(&credential.info))
+    .bind(secret)
+    .execute(&mut *tx)
+    .await
+    .map_err(|_| conflict())?;
+    append_admin_audit_event_in_transaction(
+        &mut tx,
+        mutation_audit(
+            context,
+            "create",
+            "plugin_source_credential",
+            &credential.info.id,
+            vec!["credential".into()],
+        ),
+        revision,
+    )
+    .await
+    .map_err(|e| admin_store_error("plugin", e))?;
+    tx.commit().await.map_err(|_| unavailable())?;
+    admin_revision(revision)
+}
+
+/// 只回收本次删除制品使用过且已无引用的凭据，保留其他插件共享的下载认证。
+pub(super) async fn delete_unused(
+    tx: &mut Transaction<'_, Postgres>,
+    ids: &[uuid::Uuid],
+    context: &MutationContext,
+    revision: crate::Revision,
+) -> AdminStoreResult<()> {
+    let removed: Vec<uuid::Uuid> = sqlx::query_scalar(
+        "delete from plugin_source_credentials c where c.id=any($1)
+         and not exists (select 1 from plugin_artifact_credentials r where r.credential_id=c.id)
+         returning c.id",
+    )
+    .bind(ids)
+    .fetch_all(&mut **tx)
+    .await
+    .map_err(|_| unavailable())?;
+    for id in removed {
+        append_admin_audit_event_in_transaction(
+            tx,
+            mutation_audit(
+                context,
+                "delete",
+                "plugin_source_credential",
+                &id.to_string(),
+                vec!["credential".into()],
+            ),
+            revision,
+        )
+        .await
+        .map_err(|error| admin_store_error("plugin", error))?;
+    }
+    Ok(())
+}
+
+pub(super) async fn delete(
+    pool: &PgPool,
+    id: &str,
+    context: &MutationContext,
+) -> AdminStoreResult<Revision> {
+    let key = uuid::Uuid::parse_str(id).map_err(|_| not_found())?;
+    let mut tx = pool.begin().await.map_err(|_| unavailable())?;
+    let revision = bump_config_revision_in_transaction(&mut tx)
+        .await
+        .map_err(|e| admin_store_error("plugin", e))?;
+    let result = sqlx::query("delete from plugin_source_credentials where id=$1")
+        .bind(key)
+        .execute(&mut *tx)
+        .await
+        .map_err(|e| {
+            if e.as_database_error()
+                .is_some_and(|e| e.is_foreign_key_violation())
+            {
+                conflict()
+            } else {
+                unavailable()
+            }
+        })?;
+    if result.rows_affected() == 0 {
+        return Err(not_found());
+    }
+    append_admin_audit_event_in_transaction(
+        &mut tx,
+        mutation_audit(
+            context,
+            "delete",
+            "plugin_source_credential",
+            id,
+            vec!["credential".into()],
+        ),
+        revision,
+    )
+    .await
+    .map_err(|e| admin_store_error("plugin", e))?;
+    tx.commit().await.map_err(|_| unavailable())?;
+    admin_revision(revision)
+}
diff --git a/backend/crates/gateway-store/src/postgres/plugins/instances.rs b/backend/crates/gateway-store/src/postgres/plugins/instances.rs
new file mode 100644
index 000000000..710af3669
--- /dev/null
+++ b/backend/crates/gateway-store/src/postgres/plugins/instances.rs
@@ -0,0 +1,422 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use gateway_admin::{
+    model::{
+        MutationContext, Revision,
+        plugins::{
+            instances::{
+                PluginInstance, PluginInstanceMutation, PluginInstanceReplacement,
+                PluginInstanceSnapshot, PluginPermissionGrant, PluginVersionConfiguration,
+            },
+            state::PluginStateCommit,
+        },
+    },
+    ports::store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult},
+};
+use secrecy::ExposeSecret as _;
+use sqlx::{PgPool, Postgres, Row as _, Transaction};
+
+use super::super::{append_admin_audit_event_in_transaction, bump_config_revision_in_transaction};
+use super::artifacts::{conflict, not_found, unavailable};
+use crate::{admin_revision, admin_store_error, mutation_audit};
+
+pub(super) async fn management_target_is_current(
+    pool: &PgPool,
+    target: &gateway_admin::model::plugins::management::PluginManagementTarget,
+) -> AdminStoreResult<bool> {
+    let (Ok(id), Ok(revision)) = (
+        uuid::Uuid::parse_str(&target.instance_id),
+        i64::try_from(target.revision),
+    ) else {
+        return Ok(false);
+    };
+    sqlx::query_scalar(
+        "select exists (select 1 from plugin_instances i \
+         join plugin_artifacts a on a.sha256=i.artifact_sha256 \
+         where i.id=$1 and i.artifact_sha256=$2 and i.revision=$3 \
+         and i.enabled and a.accepted_at is not null)",
+    )
+    .bind(id)
+    .bind(&target.artifact_sha256)
+    .bind(revision)
+    .fetch_one(pool)
+    .await
+    .map_err(|_| unavailable())
+}
+
+pub(super) async fn load(pool: &PgPool) -> AdminStoreResult<PluginInstanceSnapshot> {
+    let mut tx = pool.begin().await.map_err(|_| unavailable())?;
+    sqlx::query("set transaction isolation level repeatable read read only")
+        .execute(&mut *tx)
+        .await
+        .map_err(|_| unavailable())?;
+    let revision: i64 =
+        sqlx::query_scalar("select config_revision from runtime_settings where id=1")
+            .fetch_one(&mut *tx)
+            .await
+            .map_err(|_| unavailable())?;
+    let rows = sqlx::query("select i.*, a.metadata_json, a.accepted_at, coalesce(s.secrets_json, '{}'::jsonb) as secrets_json from plugin_instances i join plugin_artifacts a on a.sha256=i.artifact_sha256 left join plugin_instance_secrets s on s.instance_id=i.id order by i.id")
+        .fetch_all(&mut *tx).await.map_err(|_| unavailable())?;
+    let instances = rows.iter().map(decode).collect::<AdminStoreResult<_>>()?;
+    tx.commit().await.map_err(|_| unavailable())?;
+    Ok(PluginInstanceSnapshot {
+        config_revision: revision_from_i64(revision)?,
+        instances,
+    })
+}
+
+pub(super) async fn load_version_configuration(
+    pool: &PgPool,
+    id: &str,
+    digest: &str,
+) -> AdminStoreResult<Option<PluginVersionConfiguration>> {
+    let id = uuid::Uuid::parse_str(id).map_err(|_| not_found())?;
+    let row = sqlx::query("select configuration_json,secrets_json,bindings_json from plugin_version_configurations where instance_id=$1 and artifact_sha256=$2")
+        .bind(id).bind(digest).fetch_optional(pool).await.map_err(|_| unavailable())?;
+    row.map(|row| {
+        Ok(PluginVersionConfiguration {
+            configuration: row
+                .try_get("configuration_json")
+                .map_err(|_| unavailable())?,
+            secrets: row
+                .try_get::<sqlx::types::Json<_>, _>("secrets_json")
+                .map_err(|_| unavailable())?
+                .0,
+            bindings: row
+                .try_get::<sqlx::types::Json<_>, _>("bindings_json")
+                .map_err(|_| unavailable())?
+                .0,
+        })
+    })
+    .transpose()
+}
+
+pub(super) async fn configuration_versions(
+    pool: &PgPool,
+    id: &str,
+) -> AdminStoreResult<Vec<String>> {
+    let id = uuid::Uuid::parse_str(id).map_err(|_| not_found())?;
+    sqlx::query_scalar("select artifact_sha256 from plugin_version_configurations where instance_id=$1 order by artifact_sha256")
+        .bind(id).fetch_all(pool).await.map_err(|_| unavailable())
+}
+
+fn decode(row: &sqlx::postgres::PgRow) -> AdminStoreResult<PluginInstance> {
+    let id: uuid::Uuid = row.try_get("id").map_err(|_| unavailable())?;
+    let accepted = row
+        .try_get::<Option<chrono::DateTime<chrono::Utc>>, _>("accepted_at")
+        .map_err(|_| unavailable())?
+        .is_some();
+    let metadata = super::artifacts::decode_metadata(row)?;
+    Ok(PluginInstance {
+        id: id.to_string(),
+        name: row.try_get("name").map_err(|_| unavailable())?,
+        artifact_sha256: row.try_get("artifact_sha256").map_err(|_| unavailable())?,
+        enabled: row.try_get("enabled").map_err(|_| unavailable())?,
+        trusted_process: accepted,
+        configuration: row
+            .try_get("configuration_json")
+            .map_err(|_| unavailable())?,
+        secrets: row
+            .try_get::<sqlx::types::Json<_>, _>("secrets_json")
+            .map_err(|_| unavailable())?
+            .0,
+        grants: if accepted {
+            metadata
+                .requested_permissions
+                .into_iter()
+                .map(|permission| PluginPermissionGrant { permission })
+                .collect()
+        } else {
+            Vec::new()
+        },
+        bindings: row
+            .try_get::<sqlx::types::Json<_>, _>("bindings_json")
+            .map_err(|_| unavailable())?
+            .0,
+        revision: revision_from_i64(row.try_get("revision").map_err(|_| unavailable())?)?,
+    })
+}
+
+async fn check_revision(
+    tx: &mut Transaction<'_, Postgres>,
+    expected: Revision,
+) -> AdminStoreResult<()> {
+    let revision: i64 =
+        sqlx::query_scalar("select config_revision from runtime_settings where id=1 for update")
+            .fetch_one(&mut **tx)
+            .await
+            .map_err(|_| unavailable())?;
+    if revision_from_i64(revision)? != expected {
+        return Err(conflict());
+    }
+    Ok(())
+}
+
+async fn validate_artifact_acceptance(
+    tx: &mut Transaction<'_, Postgres>,
+    instance: &PluginInstance,
+) -> AdminStoreResult<()> {
+    let row = sqlx::query(
+        "select metadata_json, accepted_at from plugin_artifacts where sha256=$1 for key share",
+    )
+    .bind(&instance.artifact_sha256)
+    .fetch_optional(&mut **tx)
+    .await
+    .map_err(|_| unavailable())?
+    .ok_or_else(not_found)?;
+    let metadata = super::artifacts::decode_metadata(&row)?;
+    let accepted = row
+        .try_get::<Option<chrono::DateTime<chrono::Utc>>, _>("accepted_at")
+        .map_err(|_| unavailable())?
+        .is_some();
+    let expected_grants = metadata
+        .requested_permissions
+        .into_iter()
+        .map(|permission| PluginPermissionGrant { permission })
+        .collect::<Vec<_>>();
+    if instance.trusted_process != accepted
+        || instance.grants != expected_grants
+        || (instance.enabled && !accepted)
+    {
+        return Err(AdminStoreError::new(
+            AdminStoreErrorKind::Invalid,
+            "plugin",
+            "plugin instance acceptance facts do not match its artifact",
+        ));
+    }
+    Ok(())
+}
+
+async fn validate_binding_references(
+    tx: &mut Transaction<'_, Postgres>,
+    instance: &PluginInstance,
+) -> AdminStoreResult<()> {
+    let client_key_ids: Vec<String> = instance
+        .bindings
+        .iter()
+        .flat_map(|binding| {
+            binding.client_key_ids.iter().chain(
+                binding
+                    .identity_bindings
+                    .iter()
+                    .map(|identity| &identity.client_key_id),
+            )
+        })
+        .collect::<BTreeSet<_>>()
+        .into_iter()
+        .cloned()
+        .collect();
+    let account_group_ids: Vec<String> = instance
+        .bindings
+        .iter()
+        .flat_map(|binding| &binding.account_group_ids)
+        .collect::<BTreeSet<_>>()
+        .into_iter()
+        .cloned()
+        .collect();
+    let valid: bool = sqlx::query_scalar(
+        "select not exists (
+           select 1 from unnest($1::text[]) as scope(id)
+           left join client_api_keys existing_key on existing_key.id = scope.id
+           where existing_key.id is null
+         ) and not exists (
+           select 1 from unnest($2::text[]) as scope(id)
+           left join account_groups existing_group on existing_group.id = scope.id
+           where existing_group.id is null
+         )",
+    )
+    .bind(client_key_ids)
+    .bind(account_group_ids)
+    .fetch_one(&mut **tx)
+    .await
+    .map_err(|_| unavailable())?;
+    if !valid {
+        return Err(AdminStoreError::new(
+            AdminStoreErrorKind::Invalid,
+            "plugin",
+            "plugin binding references do not exist",
+        ));
+    }
+    Ok(())
+}
+
+pub(super) async fn save(
+    pool: &PgPool,
+    instance: PluginInstance,
+    expected: Revision,
+    context: &MutationContext,
+) -> AdminStoreResult<PluginInstanceMutation> {
+    save_inner(pool, instance, expected, None, &[], context).await
+}
+
+pub(super) async fn save_with_state(
+    pool: &PgPool,
+    instance: PluginInstance,
+    expected: Revision,
+    state: &PluginStateCommit,
+    replacements: &[PluginInstanceReplacement],
+    context: &MutationContext,
+) -> AdminStoreResult<PluginInstanceMutation> {
+    save_inner(pool, instance, expected, Some(state), replacements, context).await
+}
+
+async fn save_inner(
+    pool: &PgPool,
+    mut instance: PluginInstance,
+    expected: Revision,
+    state: Option<&PluginStateCommit>,
+    replacements: &[PluginInstanceReplacement],
+    context: &MutationContext,
+) -> AdminStoreResult<PluginInstanceMutation> {
+    let id = uuid::Uuid::parse_str(&instance.id).map_err(|_| conflict())?;
+    let mut tx = pool.begin().await.map_err(|_| unavailable())?;
+    check_revision(&mut tx, expected).await?;
+    validate_artifact_acceptance(&mut tx, &instance).await?;
+    // 停用是损坏配置的恢复路径，必须原样保留绑定；再次启用时才要求引用仍存在。
+    if instance.enabled {
+        validate_binding_references(&mut tx, &instance).await?;
+    }
+    let revision = bump_config_revision_in_transaction(&mut tx)
+        .await
+        .map_err(|e| admin_store_error("plugin", e))?;
+    sqlx::query("insert into plugin_instances (id,artifact_sha256,name,enabled,configuration_json,bindings_json,revision) values ($1,$2,$3,$4,$5,$6,$7) on conflict (id) do update set artifact_sha256=excluded.artifact_sha256,name=excluded.name,enabled=excluded.enabled,configuration_json=excluded.configuration_json,bindings_json=excluded.bindings_json,revision=excluded.revision")
+        .bind(id).bind(&instance.artifact_sha256).bind(&instance.name).bind(instance.enabled).bind(&instance.configuration)
+        .bind(sqlx::types::Json(&instance.bindings)).bind(i64::try_from(revision.get()).map_err(|_| unavailable())?)
+        .execute(&mut *tx).await.map_err(|error| if error.as_database_error().is_some_and(|e| e.is_foreign_key_violation()) { conflict() } else {unavailable()})?;
+    let secrets: BTreeMap<_, _> = instance
+        .secrets
+        .iter()
+        .map(|(key, value)| (key.as_str(), value.expose_secret()))
+        .collect();
+    sqlx::query("insert into plugin_instance_secrets(instance_id,secrets_json) values ($1,$2) on conflict (instance_id) do update set secrets_json=excluded.secrets_json")
+        .bind(id).bind(sqlx::types::Json(secrets)).execute(&mut *tx).await.map_err(|_| unavailable())?;
+    // 与当前配置及状态一同提交，准备失败或事务冲突不能污染恢复点。
+    // 停用草稿可能缺少必填参数，不能覆盖此版本最近的启用配置。
+    if instance.enabled {
+        sqlx::query("insert into plugin_version_configurations (instance_id,artifact_sha256,configuration_json,secrets_json,bindings_json) select i.id,i.artifact_sha256,i.configuration_json,s.secrets_json,i.bindings_json from plugin_instances i join plugin_instance_secrets s on s.instance_id=i.id where i.id=$1 on conflict (instance_id,artifact_sha256) do update set configuration_json=excluded.configuration_json,secrets_json=excluded.secrets_json,bindings_json=excluded.bindings_json")
+            .bind(id).execute(&mut *tx).await.map_err(|_| unavailable())?;
+    }
+    let committed_revision = admin_revision(revision)?;
+    // 旧配置与新配置共享事务，任一版本检查或状态提交失败都不留下半次切换。
+    for replacement in replacements {
+        let previous_id = uuid::Uuid::parse_str(&replacement.id).map_err(|_| conflict())?;
+        if previous_id == id || !instance.enabled {
+            return Err(conflict());
+        }
+        let artifact_sha256: String = sqlx::query_scalar(
+            "update plugin_instances set enabled=false,revision=$3 \
+             where id=$1 and revision=$2 and enabled=true \
+             and artifact_sha256 in (select sha256 from plugin_artifacts where \
+                 metadata_json->>'pluginId'=(select metadata_json->>'pluginId' from plugin_artifacts where sha256=$4)) \
+             returning artifact_sha256",
+        )
+        .bind(previous_id)
+        .bind(i64::try_from(replacement.expected_revision).map_err(|_| conflict())?)
+        .bind(i64::try_from(revision.get()).map_err(|_| unavailable())?)
+        .bind(&instance.artifact_sha256)
+        .fetch_optional(&mut *tx).await.map_err(|_| unavailable())?
+        .ok_or_else(conflict)?;
+        super::state::rebind_existing_configuration(
+            &mut tx,
+            &replacement.id,
+            &artifact_sha256,
+            committed_revision,
+        )
+        .await?;
+        append_admin_audit_event_in_transaction(
+            &mut tx,
+            mutation_audit(
+                context,
+                "configure",
+                "plugin_instance",
+                &replacement.id,
+                vec!["enabled".into()],
+            ),
+            revision,
+        )
+        .await
+        .map_err(|e| admin_store_error("plugin", e))?;
+    }
+    if let Some(state) = state {
+        super::state::commit_configuration(&mut tx, &instance, committed_revision, state).await?;
+    } else {
+        super::state::rebind_existing_configuration(
+            &mut tx,
+            &instance.id,
+            &instance.artifact_sha256,
+            committed_revision,
+        )
+        .await?;
+    }
+    append_admin_audit_event_in_transaction(
+        &mut tx,
+        mutation_audit(
+            context,
+            "configure",
+            "plugin_instance",
+            &instance.id,
+            vec![
+                "artifact".into(),
+                "configuration".into(),
+                "bindings".into(),
+                "enabled".into(),
+            ],
+        ),
+        revision,
+    )
+    .await
+    .map_err(|e| admin_store_error("plugin", e))?;
+    tx.commit().await.map_err(|_| unavailable())?;
+    instance.revision = committed_revision;
+    Ok(PluginInstanceMutation {
+        config_revision: instance.revision,
+        instance,
+    })
+}
+
+pub(super) async fn delete(
+    pool: &PgPool,
+    id: &str,
+    expected: Revision,
+    context: &MutationContext,
+) -> AdminStoreResult<Revision> {
+    let key = uuid::Uuid::parse_str(id).map_err(|_| not_found())?;
+    let mut tx = pool.begin().await.map_err(|_| unavailable())?;
+    check_revision(&mut tx, expected).await?;
+    let revision = bump_config_revision_in_transaction(&mut tx)
+        .await
+        .map_err(|e| admin_store_error("plugin", e))?;
+    let enabled: bool = sqlx::query_scalar("select enabled from plugin_instances where id=$1")
+        .bind(key)
+        .fetch_optional(&mut *tx)
+        .await
+        .map_err(|_| unavailable())?
+        .ok_or_else(not_found)?;
+    if enabled {
+        return Err(conflict());
+    }
+    sqlx::query("delete from plugin_instances where id=$1")
+        .bind(key)
+        .execute(&mut *tx)
+        .await
+        .map_err(|_| conflict())?;
+    append_admin_audit_event_in_transaction(
+        &mut tx,
+        mutation_audit(
+            context,
+            "delete",
+            "plugin_instance",
+            id,
+            vec!["instance".into()],
+        ),
+        revision,
+    )
+    .await
+    .map_err(|e| admin_store_error("plugin", e))?;
+    tx.commit().await.map_err(|_| unavailable())?;
+    admin_revision(revision)
+}
+
+fn revision_from_i64(value: i64) -> AdminStoreResult<Revision> {
+    Revision::new(u64::try_from(value).map_err(|_| unavailable())?).map_err(|_| unavailable())
+}
diff --git a/backend/crates/gateway-store/src/postgres/plugins/mod.rs b/backend/crates/gateway-store/src/postgres/plugins/mod.rs
new file mode 100644
index 000000000..f186c747e
--- /dev/null
+++ b/backend/crates/gateway-store/src/postgres/plugins/mod.rs
@@ -0,0 +1,7 @@
+mod artifacts;
+mod credentials;
+mod instances;
+mod sources;
+mod state;
+
+pub use artifacts::PgPluginStore;
diff --git a/backend/crates/gateway-store/src/postgres/plugins/sources.rs b/backend/crates/gateway-store/src/postgres/plugins/sources.rs
new file mode 100644
index 000000000..62e9eb803
--- /dev/null
+++ b/backend/crates/gateway-store/src/postgres/plugins/sources.rs
@@ -0,0 +1,166 @@
+use gateway_admin::{
+    model::{
+        MutationContext, Revision,
+        plugins::{
+            PluginSourceEgress,
+            distribution::{PluginSourceBinding, PluginUpdatePolicy, PluginUpdateSource},
+        },
+    },
+    ports::store::AdminStoreResult,
+};
+use sqlx::{PgPool, Postgres, Transaction};
+
+use super::super::{append_admin_audit_event_in_transaction, bump_config_revision_in_transaction};
+use super::artifacts::{conflict, not_found, unavailable};
+use crate::{admin_revision, admin_store_error, mutation_audit};
+
+#[derive(sqlx::FromRow)]
+struct PluginSourceRow {
+    plugin_id: String,
+    source_json: sqlx::types::Json<PluginUpdateSource>,
+    policy_json: sqlx::types::Json<PluginUpdatePolicy>,
+    outbound_proxy_id: Option<String>,
+}
+
+pub(super) async fn list(pool: &PgPool) -> AdminStoreResult<Vec<PluginSourceBinding>> {
+    let rows: Vec<PluginSourceRow> = sqlx::query_as(
+        "select plugin_id,source_json,policy_json,outbound_proxy_id from plugin_update_sources order by plugin_id",
+    )
+    .fetch_all(pool)
+    .await
+    .map_err(|_| unavailable())?;
+    Ok(rows
+        .into_iter()
+        .map(|row| PluginSourceBinding {
+            plugin_id: row.plugin_id,
+            source: row.source_json.0,
+            policy: row.policy_json.0,
+            outbound_proxy_id: row.outbound_proxy_id,
+        })
+        .collect())
+}
+
+pub(super) async fn change(
+    pool: &PgPool,
+    binding: PluginSourceBinding,
+    context: &MutationContext,
+) -> AdminStoreResult<Revision> {
+    let mut tx = pool.begin().await.map_err(|_| unavailable())?;
+    let revision = bump_config_revision_in_transaction(&mut tx)
+        .await
+        .map_err(|e| admin_store_error("plugin", e))?;
+    if let Some(id) = binding.outbound_proxy_id.as_deref() {
+        lock_proxy(&mut tx, id, None).await?;
+    }
+    let result = sqlx::query(
+        "update plugin_update_sources set source_json=$2,policy_json=$3,outbound_proxy_id=$4 where plugin_id=$1",
+    )
+    .bind(&binding.plugin_id)
+    .bind(sqlx::types::Json(binding.source))
+    .bind(sqlx::types::Json(binding.policy))
+    .bind(binding.outbound_proxy_id)
+    .execute(&mut *tx)
+    .await
+    .map_err(|_| unavailable())?;
+    if result.rows_affected() == 0 {
+        return Err(not_found());
+    }
+    append_admin_audit_event_in_transaction(
+        &mut tx,
+        mutation_audit(
+            context,
+            "change_source",
+            "plugin_source",
+            &binding.plugin_id,
+            vec!["source".into(), "policy".into(), "outbound_proxy".into()],
+        ),
+        revision,
+    )
+    .await
+    .map_err(|e| admin_store_error("plugin", e))?;
+    tx.commit().await.map_err(|_| unavailable())?;
+    admin_revision(revision)
+}
+
+/// 调用方先锁全局 revision，来源确认与制品写入共用同一个事务。
+pub(super) async fn bind(
+    tx: &mut Transaction<'_, Postgres>,
+    plugin_id: &str,
+    source: PluginUpdateSource,
+    outbound_proxy: Option<&PluginSourceEgress>,
+) -> AdminStoreResult<()> {
+    if let Some(proxy) = outbound_proxy {
+        lock_proxy(tx, &proxy.id, Some(proxy.revision)).await?;
+    }
+    let outbound_proxy_id = outbound_proxy.map(|proxy| proxy.id.as_str());
+    sqlx::query("insert into plugin_update_sources(plugin_id,source_json,outbound_proxy_id) values ($1,$2,$3) on conflict do nothing")
+        .bind(plugin_id).bind(sqlx::types::Json(&source)).bind(outbound_proxy_id).execute(&mut **tx).await.map_err(|_| unavailable())?;
+    let stored: (sqlx::types::Json<PluginUpdateSource>, Option<String>) = sqlx::query_as(
+        "select source_json,outbound_proxy_id from plugin_update_sources where plugin_id=$1",
+    )
+    .bind(plugin_id)
+    .fetch_one(&mut **tx)
+    .await
+    .map_err(|_| unavailable())?;
+    if stored.0.0 != source || stored.1.as_deref() != outbound_proxy_id {
+        return Err(conflict());
+    }
+    Ok(())
+}
+
+/// 与制品删除共用全局 revision 锁，最后一个版本删除后不保留重装限制。
+pub(super) async fn delete_if_unused(
+    tx: &mut Transaction<'_, Postgres>,
+    plugin_id: &str,
+    context: &MutationContext,
+    revision: crate::Revision,
+) -> AdminStoreResult<()> {
+    let removed = sqlx::query(
+        "delete from plugin_update_sources where plugin_id=$1
+         and not exists (select 1 from plugin_artifacts where plugin_id=$1)",
+    )
+    .bind(plugin_id)
+    .execute(&mut **tx)
+    .await
+    .map_err(|_| unavailable())?;
+    if removed.rows_affected() > 0 {
+        append_admin_audit_event_in_transaction(
+            tx,
+            mutation_audit(
+                context,
+                "delete",
+                "plugin_source",
+                plugin_id,
+                vec!["source".into(), "policy".into(), "outbound_proxy".into()],
+            ),
+            revision,
+        )
+        .await
+        .map_err(|error| admin_store_error("plugin", error))?;
+    }
+    Ok(())
+}
+
+async fn lock_proxy(
+    tx: &mut Transaction<'_, Postgres>,
+    id: &str,
+    expected_revision: Option<u64>,
+) -> AdminStoreResult<()> {
+    let revision: Option<i64> =
+        sqlx::query_scalar("select revision from outbound_proxies where id=$1 for share")
+            .bind(id)
+            .fetch_optional(&mut **tx)
+            .await
+            .map_err(|_| unavailable())?;
+    let Some(revision) = revision else {
+        return Err(if expected_revision.is_some() {
+            conflict()
+        } else {
+            not_found()
+        });
+    };
+    if expected_revision.is_some_and(|expected| u64::try_from(revision).ok() != Some(expected)) {
+        return Err(conflict());
+    }
+    Ok(())
+}
diff --git a/backend/crates/gateway-store/src/postgres/plugins/state.rs b/backend/crates/gateway-store/src/postgres/plugins/state.rs
new file mode 100644
index 000000000..8e74021ec
--- /dev/null
+++ b/backend/crates/gateway-store/src/postgres/plugins/state.rs
@@ -0,0 +1,1149 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use async_trait::async_trait;
+use gateway_admin::{
+    model::{
+        Revision,
+        plugins::{
+            instances::PluginInstance,
+            state::{
+                ApplyPluginStateMigration, DeletePluginState, PluginStateCommit,
+                PluginStateConfiguration, PluginStateMigrationAction, PluginStateMigrationBatch,
+                PluginStateMigrationNamespace, PluginStateNamespaceOwner, PluginStateOwner,
+                PluginStateOwnerRequest, PluginStateRecord, PluginStateSchema,
+                PluginStateTransition, PluginStateWrite, PutPluginState,
+            },
+        },
+    },
+    ports::{
+        plugins::{
+            PluginStateStore, PluginStateStoreError, PluginStateStoreErrorKind,
+            PluginStateStoreResult,
+        },
+        store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult},
+    },
+};
+use sqlx::{Postgres, Row as _, Transaction};
+
+use super::artifacts::PgPluginStore;
+
+const MIGRATION_BATCH_MAXIMUM: u32 = 100;
+
+struct ActiveGeneration {
+    id: uuid::Uuid,
+    namespace: String,
+    schema_version: u32,
+    schema_sha256: String,
+    record_count: u64,
+    total_bytes: u64,
+    maximum_record_bytes: u64,
+}
+
+struct WritableGeneration {
+    id: uuid::Uuid,
+    maximum_records: u64,
+    maximum_bytes: u64,
+    maximum_value_bytes: u64,
+    next_record_version: u64,
+    record_count: u64,
+    total_bytes: u64,
+}
+
+fn state_error(kind: PluginStateStoreErrorKind) -> PluginStateStoreError {
+    PluginStateStoreError::new(kind)
+}
+
+fn invalid() -> PluginStateStoreError {
+    state_error(PluginStateStoreErrorKind::Invalid)
+}
+
+fn not_found() -> PluginStateStoreError {
+    state_error(PluginStateStoreErrorKind::NotFound)
+}
+
+fn conflict() -> PluginStateStoreError {
+    state_error(PluginStateStoreErrorKind::Conflict)
+}
+
+fn quota() -> PluginStateStoreError {
+    state_error(PluginStateStoreErrorKind::Quota)
+}
+
+fn denied() -> PluginStateStoreError {
+    state_error(PluginStateStoreErrorKind::PermissionDenied)
+}
+
+fn unavailable() -> PluginStateStoreError {
+    state_error(PluginStateStoreErrorKind::Unavailable)
+}
+
+fn admin_conflict() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Conflict,
+        "plugin state",
+        "plugin state configuration conflicts with the active generation",
+    )
+}
+
+fn admin_invalid() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Invalid,
+        "plugin state",
+        "plugin state configuration is invalid",
+    )
+}
+
+fn admin_unavailable() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Unavailable,
+        "plugin state",
+        "plugin state store is unavailable",
+    )
+}
+
+fn valid_key(key: &str) -> bool {
+    !key.is_empty()
+        && key.chars().count() <= 256
+        && key.len() <= 512
+        && !key.chars().any(char::is_control)
+}
+
+fn validate_configuration(configuration: &PluginStateConfiguration) -> PluginStateStoreResult<()> {
+    if configuration.namespaces.len() > 16 {
+        return Err(invalid());
+    }
+    let mut namespaces = BTreeSet::new();
+    for schema in &configuration.namespaces {
+        let schema_bytes = serde_json::to_vec(&schema.schema).map_err(|_| invalid())?;
+        let migrations = schema
+            .migrates_from
+            .iter()
+            .copied()
+            .collect::<BTreeSet<_>>();
+        if !valid_namespace(&schema.namespace)
+            || !namespaces.insert(&schema.namespace)
+            || schema.schema_version == 0
+            || schema.schema_sha256.len() != 64
+            || !schema
+                .schema_sha256
+                .bytes()
+                .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+            || !schema.schema.is_object()
+            || schema_bytes.len() > 32 * 1024
+            || schema.maximum_records == 0
+            || schema.maximum_records > 10_000
+            || schema.maximum_bytes == 0
+            || schema.maximum_bytes > 16 * 1024 * 1024
+            || schema.maximum_value_bytes == 0
+            || schema.maximum_value_bytes > 256 * 1024
+            || u64::from(schema.maximum_value_bytes) > schema.maximum_bytes
+            || migrations.len() != schema.migrates_from.len()
+            || migrations.contains(&0)
+            || migrations.contains(&schema.schema_version)
+        {
+            return Err(invalid());
+        }
+    }
+    Ok(())
+}
+
+fn valid_namespace(namespace: &str) -> bool {
+    !namespace.is_empty()
+        && namespace.len() <= 64
+        && namespace.as_bytes()[0].is_ascii_lowercase()
+        && namespace.bytes().all(|byte| {
+            byte.is_ascii_lowercase() || byte.is_ascii_digit() || b"-_.".contains(&byte)
+        })
+}
+
+fn target_map(configuration: &PluginStateConfiguration) -> BTreeMap<&str, &PluginStateSchema> {
+    configuration
+        .namespaces
+        .iter()
+        .map(|schema| (schema.namespace.as_str(), schema))
+        .collect()
+}
+
+fn revision_i64(revision: Revision) -> Result<i64, PluginStateStoreError> {
+    i64::try_from(revision.get()).map_err(|_| invalid())
+}
+
+fn u64_from_i64(value: i64) -> PluginStateStoreResult<u64> {
+    u64::try_from(value).map_err(|_| unavailable())
+}
+
+fn u32_from_i64(value: i64) -> PluginStateStoreResult<u32> {
+    u32::try_from(value).map_err(|_| unavailable())
+}
+
+async fn active_generations(
+    transaction: &mut Transaction<'_, Postgres>,
+    instance_id: uuid::Uuid,
+    lock: bool,
+) -> PluginStateStoreResult<Vec<ActiveGeneration>> {
+    let query = if lock {
+        "select g.id, g.namespace, g.schema_version, g.schema_sha256, g.record_count, \
+                g.total_bytes, coalesce((select max(r.value_bytes) \
+                  from plugin_state_records r where r.generation_id=g.id), 0) \
+                  as maximum_record_bytes \
+         from plugin_state_generations g where g.instance_id=$1 and g.status='active' \
+         order by g.namespace for update of g"
+    } else {
+        "select g.id, g.namespace, g.schema_version, g.schema_sha256, g.record_count, \
+                g.total_bytes, coalesce((select max(r.value_bytes) \
+                  from plugin_state_records r where r.generation_id=g.id), 0) \
+                  as maximum_record_bytes \
+         from plugin_state_generations g where g.instance_id=$1 and g.status='active' \
+         order by g.namespace"
+    };
+    sqlx::query(query)
+        .bind(instance_id)
+        .fetch_all(&mut **transaction)
+        .await
+        .map_err(|_| unavailable())?
+        .into_iter()
+        .map(|row| {
+            Ok(ActiveGeneration {
+                id: row.try_get("id").map_err(|_| unavailable())?,
+                namespace: row.try_get("namespace").map_err(|_| unavailable())?,
+                schema_version: u32_from_i64(
+                    row.try_get("schema_version").map_err(|_| unavailable())?,
+                )?,
+                schema_sha256: row.try_get("schema_sha256").map_err(|_| unavailable())?,
+                record_count: u64_from_i64(
+                    row.try_get("record_count").map_err(|_| unavailable())?,
+                )?,
+                total_bytes: u64_from_i64(row.try_get("total_bytes").map_err(|_| unavailable())?)?,
+                maximum_record_bytes: u64_from_i64(
+                    row.try_get("maximum_record_bytes")
+                        .map_err(|_| unavailable())?,
+                )?,
+            })
+        })
+        .collect()
+}
+
+#[async_trait]
+impl PluginStateStore for PgPluginStore {
+    async fn load_owner(
+        &self,
+        request: PluginStateOwnerRequest,
+    ) -> PluginStateStoreResult<Option<PluginStateOwner>> {
+        validate_configuration(&request.configuration)?;
+        let instance_id = uuid::Uuid::parse_str(&request.instance_id).map_err(|_| invalid())?;
+        let revision = revision_i64(request.instance_revision)?;
+        let current =
+            sqlx::query("select artifact_sha256, revision from plugin_instances where id=$1")
+                .bind(instance_id)
+                .fetch_optional(&self.pool)
+                .await
+                .map_err(|_| unavailable())?;
+        let Some(current) = current else {
+            return Ok(None);
+        };
+        if current
+            .try_get::<String, _>("artifact_sha256")
+            .map_err(|_| unavailable())?
+            != request.artifact_sha256
+            || current
+                .try_get::<i64, _>("revision")
+                .map_err(|_| unavailable())?
+                != revision
+        {
+            return Ok(None);
+        }
+        let rows = sqlx::query(
+            "select id, namespace, artifact_sha256, schema_version, schema_sha256, \
+                    instance_revision, fence, maximum_records, maximum_bytes, maximum_value_bytes \
+             from plugin_state_generations \
+             where instance_id=$1 and status='active' order by namespace",
+        )
+        .bind(instance_id)
+        .fetch_all(&self.pool)
+        .await
+        .map_err(|_| unavailable())?;
+        let target = target_map(&request.configuration);
+        if rows.len() != target.len() {
+            return Ok(None);
+        }
+        let mut namespaces = BTreeMap::new();
+        for row in rows {
+            let namespace: String = row.try_get("namespace").map_err(|_| unavailable())?;
+            let Some(schema) = target.get(namespace.as_str()) else {
+                return Ok(None);
+            };
+            if row
+                .try_get::<String, _>("artifact_sha256")
+                .map_err(|_| unavailable())?
+                != request.artifact_sha256
+                || row
+                    .try_get::<i64, _>("instance_revision")
+                    .map_err(|_| unavailable())?
+                    != revision
+                || u32_from_i64(row.try_get("schema_version").map_err(|_| unavailable())?)?
+                    != schema.schema_version
+                || row
+                    .try_get::<String, _>("schema_sha256")
+                    .map_err(|_| unavailable())?
+                    != schema.schema_sha256
+                || u64_from_i64(row.try_get("maximum_records").map_err(|_| unavailable())?)?
+                    != u64::from(schema.maximum_records)
+                || u64_from_i64(row.try_get("maximum_bytes").map_err(|_| unavailable())?)?
+                    != schema.maximum_bytes
+                || u64_from_i64(
+                    row.try_get("maximum_value_bytes")
+                        .map_err(|_| unavailable())?,
+                )? != u64::from(schema.maximum_value_bytes)
+            {
+                return Ok(None);
+            }
+            let generation: uuid::Uuid = row.try_get("id").map_err(|_| unavailable())?;
+            let fence: uuid::Uuid = row.try_get("fence").map_err(|_| unavailable())?;
+            namespaces.insert(
+                namespace,
+                PluginStateNamespaceOwner::from_store(
+                    generation.to_string(),
+                    fence.to_string(),
+                    schema.schema_version,
+                ),
+            );
+        }
+        Ok(Some(PluginStateOwner::from_store(
+            request.instance_id,
+            request.artifact_sha256,
+            request.instance_revision,
+            namespaces,
+        )))
+    }
+
+    async fn get(
+        &self,
+        owner: &PluginStateOwner,
+        namespace: &str,
+        key: &str,
+    ) -> PluginStateStoreResult<Option<PluginStateRecord>> {
+        if !valid_key(key) {
+            return Err(invalid());
+        }
+        let namespace_owner = owner.namespace(namespace).ok_or_else(denied)?;
+        let generation =
+            uuid::Uuid::parse_str(namespace_owner.generation_id()).map_err(|_| denied())?;
+        let fence = uuid::Uuid::parse_str(namespace_owner.fence()).map_err(|_| denied())?;
+        let instance_id = uuid::Uuid::parse_str(owner.instance_id()).map_err(|_| denied())?;
+        let row = sqlx::query(
+            "select g.schema_version, r.state_key, r.value_json, r.record_version \
+             from plugin_state_generations g \
+             join plugin_instances i on i.id=g.instance_id \
+             left join plugin_state_records r on r.generation_id=g.id and r.state_key=$7 \
+             where g.id=$1 and g.fence=$2 and g.instance_id=$3 and g.namespace=$4 \
+               and g.artifact_sha256=$5 and g.instance_revision=$6 and g.status='active' \
+               and i.artifact_sha256=g.artifact_sha256 and i.revision=g.instance_revision",
+        )
+        .bind(generation)
+        .bind(fence)
+        .bind(instance_id)
+        .bind(namespace)
+        .bind(owner.artifact_sha256())
+        .bind(revision_i64(owner.instance_revision())?)
+        .bind(key)
+        .fetch_optional(&self.pool)
+        .await
+        .map_err(|_| unavailable())?
+        .ok_or_else(denied)?;
+        let Some(state_key) = row
+            .try_get::<Option<String>, _>("state_key")
+            .map_err(|_| unavailable())?
+        else {
+            return Ok(None);
+        };
+        Ok(Some(PluginStateRecord {
+            key: state_key,
+            value: row.try_get("value_json").map_err(|_| unavailable())?,
+            version: u64_from_i64(row.try_get("record_version").map_err(|_| unavailable())?)?,
+            schema_version: u32_from_i64(
+                row.try_get("schema_version").map_err(|_| unavailable())?,
+            )?,
+        }))
+    }
+
+    async fn put(
+        &self,
+        owner: &PluginStateOwner,
+        command: PutPluginState,
+    ) -> PluginStateStoreResult<PluginStateWrite> {
+        if !valid_key(&command.key) {
+            return Err(invalid());
+        }
+        let value_bytes = serde_json::to_vec(&command.value)
+            .map_err(|_| invalid())?
+            .len();
+        let value_bytes = u64::try_from(value_bytes).map_err(|_| quota())?;
+        let mut transaction = self.pool.begin().await.map_err(|_| unavailable())?;
+        let generation = writable_generation(&mut transaction, owner, &command.namespace).await?;
+        if value_bytes == 0 || value_bytes > generation.maximum_value_bytes {
+            return Err(quota());
+        }
+        let existing = sqlx::query(
+            "select record_version, value_bytes from plugin_state_records \
+             where generation_id=$1 and state_key=$2",
+        )
+        .bind(generation.id)
+        .bind(&command.key)
+        .fetch_optional(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?;
+        let previous_bytes = match (command.expected_version, existing) {
+            (None, None) => 0,
+            (None, Some(_)) | (Some(_), None) => return Err(conflict()),
+            (Some(expected), Some(row)) => {
+                if u64_from_i64(row.try_get("record_version").map_err(|_| unavailable())?)?
+                    != expected
+                {
+                    return Err(conflict());
+                }
+                u64_from_i64(row.try_get("value_bytes").map_err(|_| unavailable())?)?
+            }
+        };
+        let record_count = generation
+            .record_count
+            .checked_add(u64::from(previous_bytes == 0))
+            .ok_or_else(quota)?;
+        let total_bytes = generation
+            .total_bytes
+            .checked_sub(previous_bytes)
+            .and_then(|bytes| bytes.checked_add(value_bytes))
+            .ok_or_else(quota)?;
+        if record_count > generation.maximum_records || total_bytes > generation.maximum_bytes {
+            return Err(quota());
+        }
+        let version = generation.next_record_version;
+        let next_version = version.checked_add(1).ok_or_else(quota)?;
+        sqlx::query(
+            "insert into plugin_state_records( \
+                 generation_id,state_key,value_json,value_bytes,record_version \
+             ) values ($1,$2,$3,$4,$5) \
+             on conflict(generation_id,state_key) do update set \
+                 value_json=excluded.value_json, value_bytes=excluded.value_bytes, \
+                 record_version=excluded.record_version",
+        )
+        .bind(generation.id)
+        .bind(&command.key)
+        .bind(&command.value)
+        .bind(i64::try_from(value_bytes).map_err(|_| quota())?)
+        .bind(i64::try_from(version).map_err(|_| quota())?)
+        .execute(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?;
+        sqlx::query(
+            "update plugin_state_generations set next_record_version=$2, record_count=$3, \
+                 total_bytes=$4 where id=$1",
+        )
+        .bind(generation.id)
+        .bind(i64::try_from(next_version).map_err(|_| quota())?)
+        .bind(i64::try_from(record_count).map_err(|_| quota())?)
+        .bind(i64::try_from(total_bytes).map_err(|_| quota())?)
+        .execute(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?;
+        transaction.commit().await.map_err(|_| unavailable())?;
+        Ok(PluginStateWrite { version })
+    }
+
+    async fn delete(
+        &self,
+        owner: &PluginStateOwner,
+        command: DeletePluginState,
+    ) -> PluginStateStoreResult<bool> {
+        if !valid_key(&command.key) || command.expected_version == 0 {
+            return Err(invalid());
+        }
+        let mut transaction = self.pool.begin().await.map_err(|_| unavailable())?;
+        let generation = writable_generation(&mut transaction, owner, &command.namespace).await?;
+        let row = sqlx::query(
+            "select record_version, value_bytes from plugin_state_records \
+             where generation_id=$1 and state_key=$2",
+        )
+        .bind(generation.id)
+        .bind(&command.key)
+        .fetch_optional(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?;
+        let Some(row) = row else {
+            transaction.commit().await.map_err(|_| unavailable())?;
+            return Ok(false);
+        };
+        if u64_from_i64(row.try_get("record_version").map_err(|_| unavailable())?)?
+            != command.expected_version
+        {
+            return Err(conflict());
+        }
+        let value_bytes = u64_from_i64(row.try_get("value_bytes").map_err(|_| unavailable())?)?;
+        sqlx::query("delete from plugin_state_records where generation_id=$1 and state_key=$2")
+            .bind(generation.id)
+            .bind(&command.key)
+            .execute(&mut *transaction)
+            .await
+            .map_err(|_| unavailable())?;
+        sqlx::query(
+            "update plugin_state_generations set record_count=$2,total_bytes=$3 where id=$1",
+        )
+        .bind(generation.id)
+        .bind(i64::try_from(generation.record_count.saturating_sub(1)).map_err(|_| unavailable())?)
+        .bind(
+            i64::try_from(generation.total_bytes.saturating_sub(value_bytes))
+                .map_err(|_| unavailable())?,
+        )
+        .execute(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?;
+        transaction.commit().await.map_err(|_| unavailable())?;
+        Ok(true)
+    }
+
+    async fn transition_required(
+        &self,
+        instance_id: &str,
+        target: &PluginStateConfiguration,
+    ) -> PluginStateStoreResult<bool> {
+        validate_configuration(target)?;
+        let instance_id = uuid::Uuid::parse_str(instance_id).map_err(|_| invalid())?;
+        let mut transaction = self.pool.begin().await.map_err(|_| unavailable())?;
+        let active = active_generations(&mut transaction, instance_id, false).await?;
+        transaction.commit().await.map_err(|_| unavailable())?;
+        let target = target_map(target);
+        let mut required = false;
+        for generation in active {
+            let Some(schema) = target.get(generation.namespace.as_str()) else {
+                if generation.record_count != 0 {
+                    return Err(conflict());
+                }
+                continue;
+            };
+            if schema.schema_version == generation.schema_version
+                && schema.schema_sha256 == generation.schema_sha256
+            {
+                if generation.record_count > u64::from(schema.maximum_records)
+                    || generation.total_bytes > schema.maximum_bytes
+                    || generation.maximum_record_bytes > u64::from(schema.maximum_value_bytes)
+                {
+                    return Err(conflict());
+                }
+                continue;
+            }
+            if !schema.migrates_from.contains(&generation.schema_version) {
+                return Err(conflict());
+            }
+            required = true;
+        }
+        Ok(required)
+    }
+
+    async fn begin_transition(
+        &self,
+        instance_id: &str,
+        expected_instance_revision: Revision,
+        artifact_sha256: &str,
+        target: PluginStateConfiguration,
+    ) -> PluginStateStoreResult<PluginStateTransition> {
+        validate_configuration(&target)?;
+        let instance_uuid = uuid::Uuid::parse_str(instance_id).map_err(|_| invalid())?;
+        let mut transaction = self.pool.begin().await.map_err(|_| unavailable())?;
+        let current =
+            sqlx::query("select enabled, revision from plugin_instances where id=$1 for update")
+                .bind(instance_uuid)
+                .fetch_optional(&mut *transaction)
+                .await
+                .map_err(|_| unavailable())?
+                .ok_or_else(not_found)?;
+        if current
+            .try_get::<bool, _>("enabled")
+            .map_err(|_| unavailable())?
+            || current
+                .try_get::<i64, _>("revision")
+                .map_err(|_| unavailable())?
+                != revision_i64(expected_instance_revision)?
+        {
+            return Err(conflict());
+        }
+        let staging_exists: bool = sqlx::query_scalar(
+            "select exists(select 1 from plugin_state_generations \
+             where instance_id=$1 and status='staging')",
+        )
+        .bind(instance_uuid)
+        .fetch_one(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?;
+        if staging_exists {
+            return Err(conflict());
+        }
+        let active = active_generations(&mut transaction, instance_uuid, true).await?;
+        let targets = target_map(&target);
+        let transition_id = uuid::Uuid::new_v4();
+        let mut namespaces = Vec::new();
+        for generation in &active {
+            let Some(schema) = targets.get(generation.namespace.as_str()) else {
+                if generation.record_count != 0 {
+                    return Err(conflict());
+                }
+                continue;
+            };
+            if schema.schema_version == generation.schema_version
+                && schema.schema_sha256 == generation.schema_sha256
+            {
+                if generation.record_count > u64::from(schema.maximum_records)
+                    || generation.total_bytes > schema.maximum_bytes
+                    || generation.maximum_record_bytes > u64::from(schema.maximum_value_bytes)
+                {
+                    return Err(conflict());
+                }
+                continue;
+            }
+            if !schema.migrates_from.contains(&generation.schema_version) {
+                return Err(conflict());
+            }
+            let generation_id = uuid::Uuid::new_v4();
+            sqlx::query(
+                "insert into plugin_state_generations( \
+                   id,transition_id,instance_id,namespace,artifact_sha256,schema_version, \
+                   schema_sha256,maximum_records,maximum_bytes,maximum_value_bytes, \
+                   instance_revision,fence,status,source_generation_id \
+                 ) values ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,'staging',$13)",
+            )
+            .bind(generation_id)
+            .bind(transition_id)
+            .bind(instance_uuid)
+            .bind(&schema.namespace)
+            .bind(artifact_sha256)
+            .bind(i64::from(schema.schema_version))
+            .bind(&schema.schema_sha256)
+            .bind(i64::from(schema.maximum_records))
+            .bind(i64::try_from(schema.maximum_bytes).map_err(|_| invalid())?)
+            .bind(i64::from(schema.maximum_value_bytes))
+            .bind(revision_i64(expected_instance_revision)?)
+            .bind(uuid::Uuid::new_v4())
+            .bind(generation.id)
+            .execute(&mut *transaction)
+            .await
+            .map_err(|_| unavailable())?;
+            namespaces.push(PluginStateMigrationNamespace {
+                namespace: schema.namespace.clone(),
+                from_schema_version: generation.schema_version,
+                to_schema_version: schema.schema_version,
+            });
+        }
+        if namespaces.is_empty() {
+            return Err(conflict());
+        }
+        transaction.commit().await.map_err(|_| unavailable())?;
+        Ok(PluginStateTransition {
+            id: transition_id.to_string(),
+            instance_id: instance_id.to_owned(),
+            artifact_sha256: artifact_sha256.to_owned(),
+            namespaces,
+        })
+    }
+
+    async fn migration_batch(
+        &self,
+        transition_id: &str,
+        namespace: &str,
+        maximum_records: u32,
+    ) -> PluginStateStoreResult<PluginStateMigrationBatch> {
+        if maximum_records == 0 || maximum_records > MIGRATION_BATCH_MAXIMUM {
+            return Err(invalid());
+        }
+        let transition_id = uuid::Uuid::parse_str(transition_id).map_err(|_| invalid())?;
+        let staging = sqlx::query(
+            "select source_generation_id,migration_cursor,migration_complete \
+             from plugin_state_generations \
+             where transition_id=$1 and namespace=$2 and status='staging'",
+        )
+        .bind(transition_id)
+        .bind(namespace)
+        .fetch_optional(&self.pool)
+        .await
+        .map_err(|_| unavailable())?
+        .ok_or_else(not_found)?;
+        if staging
+            .try_get::<bool, _>("migration_complete")
+            .map_err(|_| unavailable())?
+        {
+            return Err(conflict());
+        }
+        let source: uuid::Uuid = staging
+            .try_get("source_generation_id")
+            .map_err(|_| unavailable())?;
+        let cursor: Option<String> = staging
+            .try_get("migration_cursor")
+            .map_err(|_| unavailable())?;
+        let rows = sqlx::query(
+            "select r.state_key,r.value_json,r.record_version,g.schema_version \
+             from plugin_state_records r \
+             join plugin_state_generations g on g.id=r.generation_id \
+             where r.generation_id=$1 and ($2::text is null or r.state_key>$2) \
+             order by r.state_key limit $3",
+        )
+        .bind(source)
+        .bind(cursor.as_deref())
+        .bind(i64::from(maximum_records))
+        .fetch_all(&self.pool)
+        .await
+        .map_err(|_| unavailable())?;
+        let records = rows
+            .into_iter()
+            .map(|row| {
+                Ok(PluginStateRecord {
+                    key: row.try_get("state_key").map_err(|_| unavailable())?,
+                    value: row.try_get("value_json").map_err(|_| unavailable())?,
+                    version: u64_from_i64(
+                        row.try_get("record_version").map_err(|_| unavailable())?,
+                    )?,
+                    schema_version: u32_from_i64(
+                        row.try_get("schema_version").map_err(|_| unavailable())?,
+                    )?,
+                })
+            })
+            .collect::<PluginStateStoreResult<_>>()?;
+        Ok(PluginStateMigrationBatch { cursor, records })
+    }
+
+    async fn apply_migration_batch(
+        &self,
+        command: ApplyPluginStateMigration,
+    ) -> PluginStateStoreResult<()> {
+        if command.expected_keys.len() > usize::try_from(MIGRATION_BATCH_MAXIMUM).unwrap()
+            || command.changes.len() != command.expected_keys.len()
+            || command.expected_keys.iter().any(|key| !valid_key(key))
+            || command
+                .expected_keys
+                .windows(2)
+                .any(|pair| pair[0] >= pair[1])
+            || command
+                .changes
+                .iter()
+                .zip(&command.expected_keys)
+                .any(|(change, expected)| change.key != *expected)
+        {
+            return Err(invalid());
+        }
+        let transition_id = uuid::Uuid::parse_str(&command.transition_id).map_err(|_| invalid())?;
+        let mut transaction = self.pool.begin().await.map_err(|_| unavailable())?;
+        let row = sqlx::query(
+            "select id,source_generation_id,migration_cursor,migration_complete, \
+                    maximum_records,maximum_bytes,maximum_value_bytes,next_record_version, \
+                    record_count,total_bytes \
+             from plugin_state_generations \
+             where transition_id=$1 and namespace=$2 and status='staging' for update",
+        )
+        .bind(transition_id)
+        .bind(&command.namespace)
+        .fetch_optional(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?
+        .ok_or_else(not_found)?;
+        let cursor: Option<String> = row.try_get("migration_cursor").map_err(|_| unavailable())?;
+        if cursor != command.cursor
+            || row
+                .try_get::<bool, _>("migration_complete")
+                .map_err(|_| unavailable())?
+        {
+            return Err(conflict());
+        }
+        let generation = WritableGeneration {
+            id: row.try_get("id").map_err(|_| unavailable())?,
+            maximum_records: u64_from_i64(
+                row.try_get("maximum_records").map_err(|_| unavailable())?,
+            )?,
+            maximum_bytes: u64_from_i64(row.try_get("maximum_bytes").map_err(|_| unavailable())?)?,
+            maximum_value_bytes: u64_from_i64(
+                row.try_get("maximum_value_bytes")
+                    .map_err(|_| unavailable())?,
+            )?,
+            next_record_version: u64_from_i64(
+                row.try_get("next_record_version")
+                    .map_err(|_| unavailable())?,
+            )?,
+            record_count: u64_from_i64(row.try_get("record_count").map_err(|_| unavailable())?)?,
+            total_bytes: u64_from_i64(row.try_get("total_bytes").map_err(|_| unavailable())?)?,
+        };
+        let source: uuid::Uuid = row
+            .try_get("source_generation_id")
+            .map_err(|_| unavailable())?;
+        let limit =
+            i64::try_from(command.expected_keys.len().saturating_add(1)).map_err(|_| invalid())?;
+        let source_rows = sqlx::query(
+            "select state_key,value_json from plugin_state_records \
+             where generation_id=$1 and ($2::text is null or state_key>$2) \
+             order by state_key limit $3",
+        )
+        .bind(source)
+        .bind(command.cursor.as_deref())
+        .bind(limit)
+        .fetch_all(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?;
+        if source_rows.len() < command.expected_keys.len()
+            || source_rows
+                .iter()
+                .take(command.expected_keys.len())
+                .zip(&command.expected_keys)
+                .any(|(row, expected)| {
+                    row.try_get::<String, _>("state_key").ok().as_ref() != Some(expected)
+                })
+            || (command.expected_keys.is_empty() && !source_rows.is_empty())
+        {
+            return Err(conflict());
+        }
+        let mut next_version = generation.next_record_version;
+        let mut record_count = generation.record_count;
+        let mut total_bytes = generation.total_bytes;
+        for ((change, source), expected_key) in command
+            .changes
+            .iter()
+            .zip(source_rows.iter())
+            .zip(&command.expected_keys)
+        {
+            let value = match &change.action {
+                PluginStateMigrationAction::Keep => {
+                    Some(source.try_get("value_json").map_err(|_| unavailable())?)
+                }
+                PluginStateMigrationAction::Replace(value) => Some(value.clone()),
+                PluginStateMigrationAction::Delete => None,
+            };
+            let Some(value) = value else {
+                continue;
+            };
+            let bytes = u64::try_from(serde_json::to_vec(&value).map_err(|_| invalid())?.len())
+                .map_err(|_| quota())?;
+            if bytes == 0 || bytes > generation.maximum_value_bytes {
+                return Err(quota());
+            }
+            record_count = record_count.checked_add(1).ok_or_else(quota)?;
+            total_bytes = total_bytes.checked_add(bytes).ok_or_else(quota)?;
+            if record_count > generation.maximum_records || total_bytes > generation.maximum_bytes {
+                return Err(quota());
+            }
+            let version = next_version;
+            next_version = next_version.checked_add(1).ok_or_else(quota)?;
+            sqlx::query(
+                "insert into plugin_state_records( \
+                   generation_id,state_key,value_json,value_bytes,record_version \
+                 ) values ($1,$2,$3,$4,$5)",
+            )
+            .bind(generation.id)
+            .bind(expected_key)
+            .bind(value)
+            .bind(i64::try_from(bytes).map_err(|_| quota())?)
+            .bind(i64::try_from(version).map_err(|_| quota())?)
+            .execute(&mut *transaction)
+            .await
+            .map_err(|error| {
+                if error
+                    .as_database_error()
+                    .is_some_and(|database| database.is_unique_violation())
+                {
+                    conflict()
+                } else {
+                    unavailable()
+                }
+            })?;
+        }
+        let complete = command.expected_keys.is_empty();
+        let next_cursor = command.expected_keys.last().or(command.cursor.as_ref());
+        sqlx::query(
+            "update plugin_state_generations set migration_cursor=$2,migration_complete=$3, \
+                 next_record_version=$4,record_count=$5,total_bytes=$6 where id=$1",
+        )
+        .bind(generation.id)
+        .bind(next_cursor)
+        .bind(complete)
+        .bind(i64::try_from(next_version).map_err(|_| quota())?)
+        .bind(i64::try_from(record_count).map_err(|_| quota())?)
+        .bind(i64::try_from(total_bytes).map_err(|_| quota())?)
+        .execute(&mut *transaction)
+        .await
+        .map_err(|_| unavailable())?;
+        transaction.commit().await.map_err(|_| unavailable())?;
+        Ok(())
+    }
+
+    async fn abort_transition(&self, transition_id: &str) -> PluginStateStoreResult<()> {
+        let transition_id = uuid::Uuid::parse_str(transition_id).map_err(|_| invalid())?;
+        sqlx::query(
+            "delete from plugin_state_generations where transition_id=$1 and status='staging'",
+        )
+        .bind(transition_id)
+        .execute(&self.pool)
+        .await
+        .map_err(|_| unavailable())?;
+        Ok(())
+    }
+}
+
+async fn writable_generation(
+    transaction: &mut Transaction<'_, Postgres>,
+    owner: &PluginStateOwner,
+    namespace: &str,
+) -> PluginStateStoreResult<WritableGeneration> {
+    let namespace_owner = owner.namespace(namespace).ok_or_else(denied)?;
+    let generation =
+        uuid::Uuid::parse_str(namespace_owner.generation_id()).map_err(|_| denied())?;
+    let fence = uuid::Uuid::parse_str(namespace_owner.fence()).map_err(|_| denied())?;
+    let instance = uuid::Uuid::parse_str(owner.instance_id()).map_err(|_| denied())?;
+    let row = sqlx::query(
+        "select g.id,g.maximum_records,g.maximum_bytes,g.maximum_value_bytes, \
+                g.next_record_version,g.record_count,g.total_bytes \
+         from plugin_state_generations g join plugin_instances i on i.id=g.instance_id \
+         where g.id=$1 and g.fence=$2 and g.instance_id=$3 and g.namespace=$4 \
+           and g.artifact_sha256=$5 and g.instance_revision=$6 and g.status='active' \
+           and i.artifact_sha256=g.artifact_sha256 and i.revision=g.instance_revision \
+         for update of g",
+    )
+    .bind(generation)
+    .bind(fence)
+    .bind(instance)
+    .bind(namespace)
+    .bind(owner.artifact_sha256())
+    .bind(revision_i64(owner.instance_revision())?)
+    .fetch_optional(&mut **transaction)
+    .await
+    .map_err(|_| unavailable())?
+    .ok_or_else(denied)?;
+    Ok(WritableGeneration {
+        id: row.try_get("id").map_err(|_| unavailable())?,
+        maximum_records: u64_from_i64(row.try_get("maximum_records").map_err(|_| unavailable())?)?,
+        maximum_bytes: u64_from_i64(row.try_get("maximum_bytes").map_err(|_| unavailable())?)?,
+        maximum_value_bytes: u64_from_i64(
+            row.try_get("maximum_value_bytes")
+                .map_err(|_| unavailable())?,
+        )?,
+        next_record_version: u64_from_i64(
+            row.try_get("next_record_version")
+                .map_err(|_| unavailable())?,
+        )?,
+        record_count: u64_from_i64(row.try_get("record_count").map_err(|_| unavailable())?)?,
+        total_bytes: u64_from_i64(row.try_get("total_bytes").map_err(|_| unavailable())?)?,
+    })
+}
+
+/// 实例与状态代次在同一事务绑定；只有这里会晋升 staging generation。
+pub(super) async fn commit_configuration(
+    transaction: &mut Transaction<'_, Postgres>,
+    instance: &PluginInstance,
+    revision: Revision,
+    commit: &PluginStateCommit,
+) -> AdminStoreResult<()> {
+    validate_configuration(&commit.configuration).map_err(|_| admin_invalid())?;
+    let instance_id = uuid::Uuid::parse_str(&instance.id).map_err(|_| admin_invalid())?;
+    let active = active_generations(transaction, instance_id, true)
+        .await
+        .map_err(|_| admin_unavailable())?;
+    let targets = target_map(&commit.configuration);
+    let transition = commit
+        .transition_id
+        .as_deref()
+        .map(uuid::Uuid::parse_str)
+        .transpose()
+        .map_err(|_| admin_invalid())?;
+    let revision = i64::try_from(revision.get()).map_err(|_| admin_invalid())?;
+    let mut handled = BTreeSet::new();
+    for generation in active {
+        let Some(schema) = targets.get(generation.namespace.as_str()) else {
+            if generation.record_count != 0 {
+                return Err(admin_conflict());
+            }
+            sqlx::query("delete from plugin_state_generations where id=$1")
+                .bind(generation.id)
+                .execute(&mut **transaction)
+                .await
+                .map_err(|_| admin_unavailable())?;
+            continue;
+        };
+        handled.insert(generation.namespace.clone());
+        if schema.schema_version == generation.schema_version
+            && schema.schema_sha256 == generation.schema_sha256
+        {
+            if generation.record_count > u64::from(schema.maximum_records)
+                || generation.total_bytes > schema.maximum_bytes
+                || generation.maximum_record_bytes > u64::from(schema.maximum_value_bytes)
+            {
+                return Err(admin_conflict());
+            }
+            sqlx::query(
+                "update plugin_state_generations set artifact_sha256=$2, \
+                   maximum_records=$3,maximum_bytes=$4,maximum_value_bytes=$5, \
+                   instance_revision=$6,fence=$7 where id=$1",
+            )
+            .bind(generation.id)
+            .bind(&instance.artifact_sha256)
+            .bind(i64::from(schema.maximum_records))
+            .bind(i64::try_from(schema.maximum_bytes).map_err(|_| admin_invalid())?)
+            .bind(i64::from(schema.maximum_value_bytes))
+            .bind(revision)
+            .bind(uuid::Uuid::new_v4())
+            .execute(&mut **transaction)
+            .await
+            .map_err(|_| admin_unavailable())?;
+            continue;
+        }
+        let transition = transition.ok_or_else(admin_conflict)?;
+        let staging = sqlx::query(
+            "select id,record_count,total_bytes,migration_complete,source_generation_id, \
+                    schema_version,schema_sha256,artifact_sha256 \
+             from plugin_state_generations \
+             where transition_id=$1 and instance_id=$2 and namespace=$3 and status='staging' \
+             for update",
+        )
+        .bind(transition)
+        .bind(instance_id)
+        .bind(&generation.namespace)
+        .fetch_optional(&mut **transaction)
+        .await
+        .map_err(|_| admin_unavailable())?
+        .ok_or_else(admin_conflict)?;
+        if !staging
+            .try_get::<bool, _>("migration_complete")
+            .map_err(|_| admin_unavailable())?
+            || staging
+                .try_get::<uuid::Uuid, _>("source_generation_id")
+                .map_err(|_| admin_unavailable())?
+                != generation.id
+            || u32::try_from(
+                staging
+                    .try_get::<i64, _>("schema_version")
+                    .map_err(|_| admin_unavailable())?,
+            )
+            .map_err(|_| admin_unavailable())?
+                != schema.schema_version
+            || staging
+                .try_get::<String, _>("schema_sha256")
+                .map_err(|_| admin_unavailable())?
+                != schema.schema_sha256
+            || staging
+                .try_get::<String, _>("artifact_sha256")
+                .map_err(|_| admin_unavailable())?
+                != instance.artifact_sha256
+            || u64::try_from(
+                staging
+                    .try_get::<i64, _>("record_count")
+                    .map_err(|_| admin_unavailable())?,
+            )
+            .map_err(|_| admin_unavailable())?
+                > u64::from(schema.maximum_records)
+            || u64::try_from(
+                staging
+                    .try_get::<i64, _>("total_bytes")
+                    .map_err(|_| admin_unavailable())?,
+            )
+            .map_err(|_| admin_unavailable())?
+                > schema.maximum_bytes
+        {
+            return Err(admin_conflict());
+        }
+        let staging_id: uuid::Uuid = staging.try_get("id").map_err(|_| admin_unavailable())?;
+        // 先解除迁移来源，再替换活动代次；任一步失败都会连同配置和旧记录一起回滚。
+        sqlx::query("update plugin_state_generations set source_generation_id=null where id=$1")
+            .bind(staging_id)
+            .execute(&mut **transaction)
+            .await
+            .map_err(|_| admin_unavailable())?;
+        sqlx::query("delete from plugin_state_generations where id=$1")
+            .bind(generation.id)
+            .execute(&mut **transaction)
+            .await
+            .map_err(|_| admin_unavailable())?;
+        sqlx::query(
+            "update plugin_state_generations set status='active',instance_revision=$2, \
+             fence=$3,promoted_at=now(),transition_id=null,migration_cursor=null where id=$1",
+        )
+        .bind(staging_id)
+        .bind(revision)
+        .bind(uuid::Uuid::new_v4())
+        .execute(&mut **transaction)
+        .await
+        .map_err(|_| admin_unavailable())?;
+    }
+    for schema in &commit.configuration.namespaces {
+        if handled.contains(&schema.namespace) {
+            continue;
+        }
+        let id = uuid::Uuid::new_v4();
+        sqlx::query(
+            "insert into plugin_state_generations( \
+               id,instance_id,namespace,artifact_sha256,schema_version, \
+               schema_sha256,maximum_records,maximum_bytes,maximum_value_bytes, \
+               instance_revision,fence,status,migration_complete,promoted_at \
+             ) values ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,'active',true,now())",
+        )
+        .bind(id)
+        .bind(instance_id)
+        .bind(&schema.namespace)
+        .bind(&instance.artifact_sha256)
+        .bind(i64::from(schema.schema_version))
+        .bind(&schema.schema_sha256)
+        .bind(i64::from(schema.maximum_records))
+        .bind(i64::try_from(schema.maximum_bytes).map_err(|_| admin_invalid())?)
+        .bind(i64::from(schema.maximum_value_bytes))
+        .bind(revision)
+        .bind(uuid::Uuid::new_v4())
+        .execute(&mut **transaction)
+        .await
+        .map_err(|error| {
+            if error
+                .as_database_error()
+                .is_some_and(|database| database.is_unique_violation())
+            {
+                admin_conflict()
+            } else {
+                admin_unavailable()
+            }
+        })?;
+    }
+    if let Some(transition) = transition {
+        let incomplete: bool = sqlx::query_scalar(
+            "select exists(select 1 from plugin_state_generations \
+             where transition_id=$1 and status='staging')",
+        )
+        .bind(transition)
+        .fetch_one(&mut **transaction)
+        .await
+        .map_err(|_| admin_unavailable())?;
+        if incomplete {
+            return Err(admin_conflict());
+        }
+    }
+    Ok(())
+}
+
+/// 紧急停用不依赖损坏包的 schema 解析；只允许原制品续绑并立即轮换 fence。
+pub(super) async fn rebind_existing_configuration(
+    transaction: &mut Transaction<'_, Postgres>,
+    instance_id: &str,
+    artifact_sha256: &str,
+    revision: Revision,
+) -> AdminStoreResult<()> {
+    let instance_id = uuid::Uuid::parse_str(instance_id).map_err(|_| admin_invalid())?;
+    let mismatched: bool = sqlx::query_scalar(
+        "select exists(select 1 from plugin_state_generations \
+         where instance_id=$1 and status='active' and artifact_sha256<>$2)",
+    )
+    .bind(instance_id)
+    .bind(artifact_sha256)
+    .fetch_one(&mut **transaction)
+    .await
+    .map_err(|_| admin_unavailable())?;
+    if mismatched {
+        return Err(admin_conflict());
+    }
+    sqlx::query(
+        "update plugin_state_generations set instance_revision=$2,fence=$3 \
+         where instance_id=$1 and status='active'",
+    )
+    .bind(instance_id)
+    .bind(i64::try_from(revision.get()).map_err(|_| admin_invalid())?)
+    .bind(uuid::Uuid::new_v4())
+    .execute(&mut **transaction)
+    .await
+    .map_err(|_| admin_unavailable())?;
+    Ok(())
+}
diff --git a/backend/crates/gateway-store/src/postgres/pricing.rs b/backend/crates/gateway-store/src/postgres/pricing.rs
index 4e4635693..3432e2a86 100644
--- a/backend/crates/gateway-store/src/postgres/pricing.rs
+++ b/backend/crates/gateway-store/src/postgres/pricing.rs
@@ -1,7 +1,10 @@
 //! 价格覆盖与请求费用明细的持久化。
 
 use gateway_admin::model::pricing::{PricingChange, PricingSyncChanges, UpdatePricing};
-use gateway_core::metering::{ModelPriceOverride, PricingOverrides};
+use gateway_core::{
+    metering::{ModelPriceOverride, PricingOverrides},
+    routing::ProviderKind,
+};
 use sqlx::types::Json;
 
 use super::{
@@ -110,7 +113,7 @@ pub(crate) fn validate_pricing(pricing: &PricingOverrides) -> StoreResult<()> {
         return Err(invalid_pricing());
     }
     for (provider, models) in pricing {
-        if !matches!(provider.as_str(), "openai" | "xai") {
+        if ProviderKind::new(provider.clone()).is_err() {
             return Err(invalid_pricing());
         }
         for (model, pricing) in models {
diff --git a/backend/crates/gateway-store/src/postgres/provider_accounts/admin_adapter.rs b/backend/crates/gateway-store/src/postgres/provider_accounts/admin_adapter.rs
index 461d7bc24..327bf7ece 100644
--- a/backend/crates/gateway-store/src/postgres/provider_accounts/admin_adapter.rs
+++ b/backend/crates/gateway-store/src/postgres/provider_accounts/admin_adapter.rs
@@ -3,6 +3,9 @@
 use std::collections::BTreeMap;
 use std::sync::Arc;
 
+use gateway_admin::model::provider_credentials::{
+    AuthorizedAccount, CredentialBatchMutationResult,
+};
 use gateway_core::provider_ports::ProviderCooldownPort;
 
 use super::*;
@@ -13,7 +16,7 @@ use crate::postgres::ObservabilityQueryBudget;
 /// 三个 PostgreSQL adapter 都保持私有，调用方只能取得 [`AccountStore`] 暴露的领域能力。
 #[derive(Clone)]
 pub struct PgAdminAccountStore {
-    pool: PgPool,
+    pub(super) pool: PgPool,
     accounts: PgProviderAccountRepository,
     observability: PgObservabilityRepository,
     control_plane: PgControlPlaneRepository,
@@ -217,65 +220,14 @@ impl PgAdminAccountStore {
         context: &MutationContext,
         action: &str,
         outbound_proxy: Option<gateway_admin::model::proxies::ImportProxyBinding>,
-    ) -> AdminStoreResult<CredentialImportResult> {
-        let provider_kind = prepared.provider_kind.as_str().to_owned();
-        let accounts = prepared
-            .credentials
-            .into_iter()
-            .map(prepared_account)
-            .collect::<StoreResult<Vec<_>>>()
-            .map_err(|error| admin_store_error(ENTITY, error))?;
-        let mut changed_fields = vec!["credentials".to_owned()];
-        if settings
-            .as_ref()
-            .is_some_and(|settings| settings.model_access.is_some())
-            || accounts
-                .iter()
-                .any(|account| account.model_access.is_some())
-        {
-            changed_fields.push("model_access".to_owned());
-        }
-        if let Some(settings) = &settings {
-            changed_fields
-                .extend(["enabled", "concurrency_limit", "weight", "group_ids"].map(str::to_owned));
-            if settings.notes.is_some() {
-                changed_fields.push("notes".to_owned());
-            }
-        }
+    ) -> AdminStoreResult<CredentialBatchMutationResult> {
+        let command = prepare_import(prepared, settings, context, action, outbound_proxy)?;
         let imported = self
             .accounts
-            .import_provider_accounts(ImportProviderAccounts {
-                settings,
-                outbound_proxy,
-                scope: ProviderAccountAdminScope {
-                    provider_kind: provider_kind.clone(),
-                },
-                accounts,
-                audit: mutation_audit(
-                    context,
-                    action,
-                    "provider_account",
-                    &provider_kind,
-                    changed_fields,
-                ),
-            })
+            .import_provider_accounts(command)
             .await
             .map_err(|error| admin_store_error(ENTITY, error))?;
-        Ok(CredentialImportResult {
-            config_revision: admin_revision(imported.config_revision)?,
-            credential_ids: imported
-                .account_ids
-                .into_iter()
-                .map(CoreProviderAccountId::new)
-                .collect::<Result<Vec<_>, _>>()
-                .map_err(|_| {
-                    AdminStoreError::new(
-                        AdminStoreErrorKind::Unavailable,
-                        ENTITY,
-                        "provider account import returned an invalid account ID",
-                    )
-                })?,
-        })
+        import_result(imported)
     }
 
     async fn commit_prepared_rotation(
@@ -286,60 +238,13 @@ impl PgAdminAccountStore {
         action: &str,
     ) -> AdminStoreResult<CredentialMutationResult> {
         let account_id = prepared.account_id.clone();
-        let scope = ProviderAccountAdminScope {
-            provider_kind: prepared.provider_kind.as_str().to_owned(),
-        };
-        let mut changed_fields = vec!["credentials".to_owned()];
-        if let Some(settings) = &settings {
-            changed_fields
-                .extend(["enabled", "concurrency_limit", "weight", "groups"].map(str::to_owned));
-            if settings.model_access.is_some() {
-                changed_fields.push("model_access".to_owned());
-            }
-            if settings.outbound_proxy.is_some() {
-                changed_fields.push("outbound_proxy".to_owned());
-            }
-            if settings.notes.is_some() {
-                changed_fields.push("notes".to_owned());
-            }
-        }
+        let command = prepare_rotation(prepared, settings, context, action)?;
         let rotation = self
             .accounts
-            .rotate_provider_account(RotateProviderAccount {
-                settings,
-                scope,
-                profile: UpdateProviderAccount {
-                    id: account_id.as_str().to_owned(),
-                    name: prepared.name,
-                    email: prepared.email,
-                    plan_type: prepared.plan_type,
-                },
-                replacement_identity: prepared.replacement_identity,
-                credential: ProviderCredentialUpdate {
-                    account_id: account_id.as_str().to_owned(),
-                    expected_revision: store_revision(prepared.expected_credential_revision)?,
-                    provider_credentials_json: provider_document_json(prepared.provider_material)
-                        .map_err(|error| admin_store_error(ENTITY, error))?,
-                    has_refresh_token: prepared.has_refresh_token,
-                    access_token_expires_at: prepared.access_token_expires_at,
-                    next_refresh_at: prepared.next_refresh_at,
-                    preserve_profile: prepared.preserve_profile,
-                },
-                audit: mutation_audit(
-                    context,
-                    action,
-                    "provider_account",
-                    account_id.as_str(),
-                    changed_fields,
-                ),
-            })
+            .rotate_provider_account(command)
             .await
             .map_err(|error| admin_store_error(ENTITY, error))?;
-        Ok(CredentialMutationResult {
-            config_revision: admin_revision(rotation.config_revision)?,
-            account_id,
-            credential_revision: Some(admin_revision(rotation.credential_revision)?),
-        })
+        rotation_result(rotation, account_id)
     }
 
     async fn account_groups_by_account(
@@ -394,6 +299,45 @@ impl PgAdminAccountStore {
 
 #[async_trait]
 impl AccountStore for PgAdminAccountStore {
+    async fn list_plugin_accounts(
+        &self,
+        query: PluginAccountListQuery,
+    ) -> AdminStoreResult<PluginAccountPage> {
+        let limit = i64::from(query.limit.get());
+        let mut accounts = self
+            .accounts
+            .list_plugin_accounts(
+                query.provider_kind.as_ref().map(ProviderKind::as_str),
+                query.cursor.as_ref().map(CoreProviderAccountId::as_str),
+                limit + 1,
+            )
+            .await
+            .map_err(|error| admin_store_error(ENTITY, error))?;
+        let has_more = accounts.len() > usize::from(query.limit.get());
+        if has_more {
+            accounts.pop();
+        }
+        let next_cursor = has_more
+            .then(|| accounts.last().map(|account| account.id.clone()))
+            .flatten()
+            .map(CoreProviderAccountId::new)
+            .transpose()
+            .map_err(|_| {
+                AdminStoreError::new(
+                    AdminStoreErrorKind::Invalid,
+                    ENTITY,
+                    "plugin account cursor is invalid",
+                )
+            })?;
+        Ok(PluginAccountPage {
+            accounts: accounts
+                .into_iter()
+                .map(admin_account_record)
+                .collect::<AdminStoreResult<_>>()?,
+            next_cursor,
+        })
+    }
+
     async fn list_accounts(
         &self,
         query: AdminAccountListQuery,
@@ -445,6 +389,7 @@ impl AccountStore for PgAdminAccountStore {
             items,
             total: page.total,
             summary: page.summary,
+            providers: page.providers,
         })
     }
 
@@ -525,6 +470,25 @@ impl AccountStore for PgAdminAccountStore {
             .transpose()
     }
 
+    async fn credential_details_by_id(
+        &self,
+        account_id: &CoreProviderAccountId,
+    ) -> AdminStoreResult<Option<CredentialDetails>> {
+        let (control_plane, account) = futures::try_join!(
+            self.control_plane.load_control_plane(),
+            self.accounts.load_provider_account(account_id.as_str()),
+        )
+        .map_err(|error| admin_store_error(ENTITY, error))?;
+        account
+            .map(|record| {
+                Ok(CredentialDetails {
+                    config_revision: admin_revision(control_plane.settings.config_revision)?,
+                    credential: admin_account_record(record.summary)?,
+                })
+            })
+            .transpose()
+    }
+
     async fn load_credentials_for_export(
         &self,
         provider_kind: &ProviderKind,
@@ -566,90 +530,63 @@ impl AccountStore for PgAdminAccountStore {
         Ok(credentials)
     }
 
+    async fn load_credential_for_plugin(
+        &self,
+        account_id: &CoreProviderAccountId,
+    ) -> AdminStoreResult<Option<ProviderExportCredentialInput>> {
+        self.accounts
+            .load_provider_account(account_id.as_str())
+            .await
+            .map_err(|error| admin_store_error(ENTITY, error))?
+            .map(|record| {
+                Ok(ProviderExportCredentialInput {
+                    account: admin_account_record(record.summary)?,
+                    provider_material: ProviderDocument::new(OpaqueProviderData::new(
+                        record.provider_credentials_json.fields().clone(),
+                    )),
+                })
+            })
+            .transpose()
+    }
+
     async fn commit_credential_import(
         &self,
         command: CredentialImportCommit,
         context: &MutationContext,
     ) -> AdminStoreResult<CredentialImportResult> {
-        self.commit_prepared_import(
-            command.prepared,
-            command.settings,
-            context,
-            "import_document",
-            command.outbound_proxy,
-        )
-        .await
+        let result = self
+            .commit_prepared_import(
+                command.prepared,
+                command.settings,
+                context,
+                "import_document",
+                command.outbound_proxy,
+            )
+            .await?;
+        Ok(CredentialImportResult {
+            config_revision: result.config_revision,
+            credential_ids: result
+                .accounts
+                .into_iter()
+                .map(|account| account.account_id)
+                .collect(),
+        })
     }
 
     async fn commit_authorization(
         &self,
         command: AuthorizationCommit,
         context: &MutationContext,
-    ) -> AdminStoreResult<CredentialMutationResult> {
-        match command.credential {
-            AuthorizationCredentialCommit::Create(credential) => {
-                let CredentialImportResult {
-                    config_revision,
-                    credential_ids,
-                } = self
-                    .commit_prepared_import(
-                        PreparedCredentialImport {
-                            provider_kind: credential.provider_kind.clone(),
-                            credentials: vec![credential],
-                        },
-                        command.settings,
-                        context,
-                        "authorize",
-                        command
-                            .pending
-                            .outbound_proxy_id()
-                            .zip(command.pending.outbound_proxy())
-                            .map(
-                                |(id, proxy)| gateway_admin::model::proxies::ImportProxyBinding {
-                                    id: id.to_owned(),
-                                    proxy: proxy.clone(),
-                                },
-                            ),
-                    )
-                    .await?;
-                let [account_id]: [CoreProviderAccountId; 1] =
-                    credential_ids.try_into().map_err(|_| {
-                        AdminStoreError::new(
-                            AdminStoreErrorKind::Unavailable,
-                            ENTITY,
-                            "authorization import returned an unexpected account count",
-                        )
-                    })?;
-                let details = self
-                    .accounts
-                    .load_provider_account(account_id.as_str())
-                    .await
-                    .map_err(|error| admin_store_error(ENTITY, error))?
-                    .ok_or_else(|| {
-                        AdminStoreError::new(
-                            AdminStoreErrorKind::Unavailable,
-                            ENTITY,
-                            "authorized credential was not visible after commit",
-                        )
-                    })?;
-                Ok(CredentialMutationResult {
-                    config_revision,
-                    account_id,
-                    credential_revision: Some(admin_revision(details.summary.credential_revision)?),
-                })
-            }
-            AuthorizationCredentialCommit::Reauthorize(prepared) => {
-                if command.settings.is_some() {
-                    return Err(AdminStoreError::new(
-                        AdminStoreErrorKind::Invalid,
-                        ENTITY,
-                        "reauthorization cannot change account settings",
-                    ));
-                }
-                self.commit_prepared_rotation(prepared, None, context, "reauthorize")
-                    .await
-            }
-        }
+    ) -> AdminStoreResult<gateway_admin::model::provider_credentials::AuthorizationCommitResult>
+    {
+        self.commit_authorization_once(command, context).await
+    }
+
+    async fn authorization_receipt(
+        &self,
+        key: &gateway_admin::model::provider_credentials::AuthorizationReceiptKey,
+    ) -> AdminStoreResult<Option<CredentialBatchMutationResult>> {
+        self.load_authorization_receipt(key).await
     }
 
     async fn commit_credential_rotation(
@@ -999,3 +936,148 @@ impl AccountStore for PgAdminAccountStore {
             .map_err(|error| admin_store_error(ENTITY, error))
     }
 }
+
+pub(super) fn prepare_import(
+    prepared: PreparedCredentialImport,
+    settings: Option<AccountImportSettings>,
+    context: &MutationContext,
+    action: &str,
+    outbound_proxy: Option<gateway_admin::model::proxies::ImportProxyBinding>,
+) -> AdminStoreResult<ImportProviderAccounts> {
+    let provider_kind = prepared.provider_kind.as_str().to_owned();
+    let accounts = prepared
+        .credentials
+        .into_iter()
+        .map(prepared_account)
+        .collect::<StoreResult<Vec<_>>>()
+        .map_err(|error| admin_store_error(ENTITY, error))?;
+    let mut changed_fields = vec!["credentials".to_owned()];
+    if settings
+        .as_ref()
+        .is_some_and(|settings| settings.model_access.is_some())
+        || accounts
+            .iter()
+            .any(|account| account.model_access.is_some())
+    {
+        changed_fields.push("model_access".to_owned());
+    }
+    if let Some(settings) = &settings {
+        changed_fields
+            .extend(["enabled", "concurrency_limit", "weight", "group_ids"].map(str::to_owned));
+        if settings.notes.is_some() {
+            changed_fields.push("notes".to_owned());
+        }
+    }
+    Ok(ImportProviderAccounts {
+        settings,
+        outbound_proxy,
+        scope: ProviderAccountAdminScope {
+            provider_kind: provider_kind.clone(),
+        },
+        accounts,
+        audit: mutation_audit(
+            context,
+            action,
+            "provider_account",
+            &provider_kind,
+            changed_fields,
+        ),
+    })
+}
+
+pub(super) fn import_result(
+    imported: ProviderAccountAdminImport,
+) -> AdminStoreResult<CredentialBatchMutationResult> {
+    Ok(CredentialBatchMutationResult {
+        config_revision: admin_revision(imported.config_revision)?,
+        accounts: imported
+            .account_ids
+            .into_iter()
+            .map(|id| {
+                let revision = imported.credential_revisions.get(&id).ok_or_else(|| {
+                    AdminStoreError::new(
+                        AdminStoreErrorKind::Unavailable,
+                        ENTITY,
+                        "account import revision is missing",
+                    )
+                })?;
+                let account_id = CoreProviderAccountId::new(id).map_err(|_| {
+                    AdminStoreError::new(
+                        AdminStoreErrorKind::Unavailable,
+                        ENTITY,
+                        "provider account import returned an invalid account ID",
+                    )
+                })?;
+                Ok(AuthorizedAccount {
+                    account_id,
+                    credential_revision: Some(admin_revision(*revision)?),
+                })
+            })
+            .collect::<AdminStoreResult<_>>()?,
+    })
+}
+
+pub(super) fn prepare_rotation(
+    prepared: PreparedCredentialRotationFacts,
+    settings: Option<UpdateAccount>,
+    context: &MutationContext,
+    action: &str,
+) -> AdminStoreResult<RotateProviderAccount> {
+    let account_id = prepared.account_id.clone();
+    let scope = ProviderAccountAdminScope {
+        provider_kind: prepared.provider_kind.as_str().to_owned(),
+    };
+    let mut changed_fields = vec!["credentials".to_owned()];
+    if let Some(settings) = &settings {
+        changed_fields
+            .extend(["enabled", "concurrency_limit", "weight", "groups"].map(str::to_owned));
+        if settings.model_access.is_some() {
+            changed_fields.push("model_access".to_owned());
+        }
+        if settings.outbound_proxy.is_some() {
+            changed_fields.push("outbound_proxy".to_owned());
+        }
+        if settings.notes.is_some() {
+            changed_fields.push("notes".to_owned());
+        }
+    }
+    Ok(RotateProviderAccount {
+        settings,
+        scope,
+        profile: UpdateProviderAccount {
+            id: account_id.as_str().to_owned(),
+            name: prepared.name,
+            email: prepared.email,
+            plan_type: prepared.plan_type,
+        },
+        replacement_identity: prepared.replacement_identity,
+        credential: ProviderCredentialUpdate {
+            account_id: account_id.as_str().to_owned(),
+            expected_revision: store_revision(prepared.expected_credential_revision)?,
+            provider_credentials_json: provider_document_json(prepared.provider_material)
+                .map_err(|error| admin_store_error(ENTITY, error))?,
+            has_refresh_token: prepared.has_refresh_token,
+            access_token_expires_at: prepared.access_token_expires_at,
+            next_refresh_at: prepared.next_refresh_at,
+            preserve_profile: prepared.preserve_profile,
+        },
+        audit: mutation_audit(
+            context,
+            action,
+            "provider_account",
+            account_id.as_str(),
+            changed_fields,
+        ),
+    })
+}
+
+pub(super) fn rotation_result(
+    rotation: ProviderAccountAdminRotation,
+    account_id: CoreProviderAccountId,
+) -> AdminStoreResult<CredentialMutationResult> {
+    Ok(CredentialMutationResult {
+        config_revision: admin_revision(rotation.config_revision)?,
+        account_id,
+        credential_revision: Some(admin_revision(rotation.credential_revision)?),
+    })
+}
diff --git a/backend/crates/gateway-store/src/postgres/provider_accounts/admin_queries.rs b/backend/crates/gateway-store/src/postgres/provider_accounts/admin_queries.rs
index 97e9cf88c..7a39aa442 100644
--- a/backend/crates/gateway-store/src/postgres/provider_accounts/admin_queries.rs
+++ b/backend/crates/gateway-store/src/postgres/provider_accounts/admin_queries.rs
@@ -7,6 +7,7 @@ pub(crate) struct AdminAccountPageRows {
     pub(crate) accounts: Vec<ProviderAccountSummary>,
     pub(crate) total: u64,
     pub(crate) summary: AccountSummary,
+    pub(crate) providers: Vec<String>,
 }
 
 pub(crate) async fn load_admin_account_page(
@@ -60,7 +61,7 @@ pub(crate) async fn load_admin_account_page(
 
     let statement = format!(
         "with account_statuses as (
-           select a.id,
+           select a.id, a.provider_kind,
                   case
                     when not a.enabled then 'disabled'
                     when a.credential_state <> 'ready'
@@ -80,7 +81,8 @@ pub(crate) async fn load_admin_account_page(
                     as summary_rate_limited,
                   count(*) filter (where admin_status = 'disabled')::bigint
                     as summary_disabled,
-                  count(*) filter (where admin_status = 'error')::bigint as summary_error
+                  count(*) filter (where admin_status = 'error')::bigint as summary_error,
+                  coalesce(array_agg(distinct provider_kind order by provider_kind), '{{}}'::text[]) as providers
              from account_statuses
          ),
          filtered as materialized (
@@ -127,6 +129,7 @@ pub(crate) async fn load_admin_account_page(
                 global_summary.summary_total, global_summary.summary_normal,
                 global_summary.summary_quota_exhausted, global_summary.summary_rate_limited,
                 global_summary.summary_disabled, global_summary.summary_error,
+                global_summary.providers,
                 settings.config_revision
            from filtered_total
            cross join global_summary
@@ -169,6 +172,13 @@ pub(crate) async fn load_admin_account_page(
     })?;
     let config_revision = revision_from_row(metadata)?;
     let total = unsigned_metadata(metadata, "filtered_total")?;
+    let providers = metadata.try_get("providers").map_err(|_| {
+        AdminStoreError::new(
+            AdminStoreErrorKind::Invalid,
+            ENTITY,
+            "persisted account providers are invalid",
+        )
+    })?;
     let summary = AccountSummary {
         total: unsigned_metadata(metadata, "summary_total")?,
         normal: unsigned_metadata(metadata, "summary_normal")?,
@@ -193,6 +203,7 @@ pub(crate) async fn load_admin_account_page(
         accounts,
         total,
         summary,
+        providers,
     })
 }
 
diff --git a/backend/crates/gateway-store/src/postgres/provider_accounts/authorization.rs b/backend/crates/gateway-store/src/postgres/provider_accounts/authorization.rs
new file mode 100644
index 000000000..84ebfdc1d
--- /dev/null
+++ b/backend/crates/gateway-store/src/postgres/provider_accounts/authorization.rs
@@ -0,0 +1,212 @@
+//! 完成回执与账号、审计共享提交边界；Redis claim 只负责上游准备阶段的互斥。
+
+use gateway_admin::model::provider_credentials::{
+    AuthorizationCommitResult, AuthorizationMutationTarget, AuthorizationReceiptKey,
+    AuthorizedAccount, CredentialBatchMutationResult,
+};
+use serde::{Deserialize, Serialize};
+
+use super::{admin_adapter, repository, *};
+
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct StoredAccount {
+    account_id: String,
+    credential_revision: Option<u64>,
+}
+
+impl PgAdminAccountStore {
+    pub(super) async fn load_authorization_receipt(
+        &self,
+        key: &AuthorizationReceiptKey,
+    ) -> AdminStoreResult<Option<CredentialBatchMutationResult>> {
+        load_receipt(&self.pool, key).await
+    }
+
+    pub(super) async fn commit_authorization_once(
+        &self,
+        command: AuthorizationCommit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AuthorizationCommitResult> {
+        if command.key.provider_kind() != command.pending.provider_kind()
+            || !command.key.matches_context(context)
+            || !command.pending.owner_binding().matches_context(context)
+        {
+            return Err(invalid_receipt());
+        }
+        let mut transaction = self.pool.begin().await.map_err(|_| unavailable_receipt())?;
+        let outcome = commit_authorization_in_transaction(&mut transaction, command, context).await;
+        match outcome {
+            Ok(outcome) => {
+                transaction
+                    .commit()
+                    .await
+                    .map_err(|_| unavailable_receipt())?;
+                Ok(outcome)
+            }
+            Err(error) => {
+                transaction
+                    .rollback()
+                    .await
+                    .map_err(|_| unavailable_receipt())?;
+                Err(error)
+            }
+        }
+    }
+}
+
+async fn commit_authorization_in_transaction(
+    transaction: &mut Transaction<'_, Postgres>,
+    command: AuthorizationCommit,
+    context: &MutationContext,
+) -> AdminStoreResult<AuthorizationCommitResult> {
+    let key = &command.key;
+    // 同一 flow 的竞争者先等待事务结果；Redis 租约过期不能造成第二次账号提交。
+    let lock = format!(
+        "authorization:{}:{}",
+        key.provider_kind(),
+        key.flow_digest()
+    );
+    sqlx::query("select pg_advisory_xact_lock(hashtextextended($1, 814037))")
+        .bind(lock)
+        .execute(&mut **transaction)
+        .await
+        .map_err(|_| unavailable_receipt())?;
+    if let Some(result) = load_receipt(&mut **transaction, key).await? {
+        return Ok(AuthorizationCommitResult {
+            result,
+            newly_committed: false,
+        });
+    }
+    let result = match (command.pending.target(), command.credential) {
+        (
+            AuthorizationMutationTarget::Create { .. },
+            AuthorizationCredentialCommit::Create(credentials),
+        ) => {
+            if credentials.is_empty()
+                || credentials.len() > 200
+                || credentials
+                    .iter()
+                    .any(|credential| &credential.provider_kind != key.provider_kind())
+            {
+                return Err(invalid_receipt());
+            }
+            let prepared = admin_adapter::prepare_import(
+                PreparedCredentialImport {
+                    provider_kind: key.provider_kind().clone(),
+                    credentials,
+                },
+                command.settings,
+                context,
+                "authorize",
+                command
+                    .pending
+                    .outbound_proxy_id()
+                    .zip(command.pending.outbound_proxy())
+                    .map(
+                        |(id, proxy)| gateway_admin::model::proxies::ImportProxyBinding {
+                            id: id.into(),
+                            proxy: proxy.clone(),
+                        },
+                    ),
+            )?;
+            let result = repository::import_provider_accounts_in_transaction(transaction, prepared)
+                .await
+                .map_err(|error| admin_store_error(ENTITY, error))?;
+            admin_adapter::import_result(result)?
+        }
+        (
+            AuthorizationMutationTarget::Reauthorize { account_id },
+            AuthorizationCredentialCommit::Reauthorize(prepared),
+        ) => {
+            if command.settings.is_some()
+                || &prepared.account_id != account_id
+                || &prepared.provider_kind != key.provider_kind()
+            {
+                return Err(invalid_receipt());
+            }
+            let prepared =
+                admin_adapter::prepare_rotation(*prepared, None, context, "reauthorize")?;
+            let result =
+                repository::rotate_provider_account_admin_in_transaction(transaction, prepared)
+                    .await
+                    .map_err(|error| admin_store_error(ENTITY, error))?;
+            admin_adapter::rotation_result(result, account_id.clone())?.into()
+        }
+        _ => return Err(invalid_receipt()),
+    };
+    let accounts = result
+        .accounts
+        .iter()
+        .map(|account| StoredAccount {
+            account_id: account.account_id.to_string(),
+            credential_revision: account.credential_revision.map(|revision| revision.get()),
+        })
+        .collect::<Vec<_>>();
+    sqlx::query("insert into authorization_receipts(provider_kind, flow_digest, owner_digest, config_revision, accounts_json) values ($1,$2,$3,$4,$5)")
+            .bind(key.provider_kind().as_str()).bind(key.flow_digest()).bind(key.owner_digest())
+            .bind(i64::try_from(result.config_revision.get()).map_err(|_| invalid_receipt())?)
+            .bind(serde_json::to_value(accounts).map_err(|_| invalid_receipt())?)
+            .execute(&mut **transaction).await.map_err(|_| unavailable_receipt())?;
+    // 保留期长于 OAuth pending 上限；每次提交有界回收，避免引入第二套维护任务。
+    sqlx::query("delete from authorization_receipts where ctid in (select ctid from authorization_receipts where expires_at <= now() order by expires_at limit 128 for update skip locked)")
+            .execute(&mut **transaction).await.map_err(|_| unavailable_receipt())?;
+    Ok(AuthorizationCommitResult {
+        result,
+        newly_committed: true,
+    })
+}
+
+async fn load_receipt<'a>(
+    executor: impl sqlx::PgExecutor<'a>,
+    key: &AuthorizationReceiptKey,
+) -> AdminStoreResult<Option<CredentialBatchMutationResult>> {
+    let row: Option<(String, i64, serde_json::Value)> = sqlx::query_as("select owner_digest, config_revision, accounts_json from authorization_receipts where provider_kind=$1 and flow_digest=$2 and expires_at>now()")
+        .bind(key.provider_kind().as_str()).bind(key.flow_digest()).fetch_optional(executor).await.map_err(|_| unavailable_receipt())?;
+    let Some((owner, revision, accounts)) = row else {
+        return Ok(None);
+    };
+    if owner != key.owner_digest() {
+        return Err(invalid_receipt());
+    }
+    let accounts: Vec<StoredAccount> =
+        serde_json::from_value(accounts).map_err(|_| unavailable_receipt())?;
+    let accounts = accounts
+        .into_iter()
+        .map(|account| {
+            Ok(AuthorizedAccount {
+                account_id: CoreProviderAccountId::new(account.account_id)
+                    .map_err(|_| unavailable_receipt())?,
+                credential_revision: account
+                    .credential_revision
+                    .map(|revision| AdminRevision::new(revision).map_err(|_| unavailable_receipt()))
+                    .transpose()?,
+            })
+        })
+        .collect::<AdminStoreResult<Vec<_>>>()?;
+    if accounts.is_empty() || accounts.len() > 200 {
+        return Err(unavailable_receipt());
+    }
+    Ok(Some(CredentialBatchMutationResult {
+        config_revision: AdminRevision::new(
+            u64::try_from(revision).map_err(|_| unavailable_receipt())?,
+        )
+        .map_err(|_| unavailable_receipt())?,
+        accounts,
+    }))
+}
+
+fn invalid_receipt() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Invalid,
+        ENTITY,
+        "invalid authorization receipt binding",
+    )
+}
+fn unavailable_receipt() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Unavailable,
+        ENTITY,
+        "authorization receipt unavailable",
+    )
+}
diff --git a/backend/crates/gateway-store/src/postgres/provider_accounts/mod.rs b/backend/crates/gateway-store/src/postgres/provider_accounts/mod.rs
index 9c8b40bd7..b29d2d077 100644
--- a/backend/crates/gateway-store/src/postgres/provider_accounts/mod.rs
+++ b/backend/crates/gateway-store/src/postgres/provider_accounts/mod.rs
@@ -23,8 +23,9 @@ use gateway_admin::{
         provider_credentials::{
             AuthorizationCommit, AuthorizationCredentialCommit, CredentialDetails,
             CredentialImportCommit, CredentialImportResult, CredentialMutationResult,
-            CredentialRotationCommit, PreparedCredentialCreate, PreparedCredentialImport,
-            PreparedCredentialRotationFacts, ProviderDocument, ProviderExportCredentialInput,
+            CredentialRotationCommit, PluginAccountListQuery, PluginAccountPage,
+            PreparedCredentialCreate, PreparedCredentialImport, PreparedCredentialRotationFacts,
+            ProviderDocument, ProviderExportCredentialInput,
         },
     },
     ports::store::{AccountStore, AdminStoreError, AdminStoreErrorKind, AdminStoreResult},
@@ -59,6 +60,7 @@ use super::{
 
 mod admin_adapter;
 mod admin_queries;
+mod authorization;
 mod core_adapter;
 mod mapping;
 mod quota_forecast;
diff --git a/backend/crates/gateway-store/src/postgres/provider_accounts/repository.rs b/backend/crates/gateway-store/src/postgres/provider_accounts/repository.rs
index d264a9696..65355cb63 100644
--- a/backend/crates/gateway-store/src/postgres/provider_accounts/repository.rs
+++ b/backend/crates/gateway-store/src/postgres/provider_accounts/repository.rs
@@ -5,6 +5,12 @@ use super::*;
 #[async_trait]
 pub trait ProviderAccountRepository: Send + Sync {
     async fn load_provider_account(&self, id: &str) -> StoreResult<Option<ProviderAccountRecord>>;
+    async fn list_plugin_accounts(
+        &self,
+        provider_kind: Option<&str>,
+        cursor: Option<&str>,
+        limit: i64,
+    ) -> StoreResult<Vec<ProviderAccountSummary>>;
     async fn list_provider_accounts(
         &self,
         provider_kind: Option<&str>,
@@ -103,6 +109,42 @@ impl ProviderAccountRepository for PgProviderAccountRepository {
         row.map(account_record_from_row).transpose()
     }
 
+    async fn list_plugin_accounts(
+        &self,
+        provider_kind: Option<&str>,
+        cursor: Option<&str>,
+        limit: i64,
+    ) -> StoreResult<Vec<ProviderAccountSummary>> {
+        if provider_kind.is_some_and(str::is_empty) {
+            return Err(invalid("plugin account provider kind must not be empty"));
+        }
+        if limit <= 0 {
+            return Err(invalid("plugin account page limit must be positive"));
+        }
+        let rows = sqlx::query(
+            "select location_country, location_region, location_city, location_timezone, outbound_proxy_url, id, provider_kind, name, notes, email, upstream_user_id,
+                    upstream_account_id, plan_type, authentication_kind, credential_revision, has_refresh_token,
+                    access_token_expires_at, next_refresh_at, enabled, concurrency_limit, weight, model_access_json, credential_state,
+                    credential_observed_at, quota_access_state, quota_evidence,
+                    quota_access_observed_at, quota_reset_at,
+                    quota_observed_at, last_error_reason, last_error_message, created_at, updated_at
+               from provider_accounts
+               left join (select id as location_proxy_id, location_country, location_region, location_city, location_timezone from outbound_proxies) proxy_location
+                 on outbound_proxy_id = location_proxy_id
+              where ($1::text is null or provider_kind = $1)
+                and ($2::text is null or id > $2)
+              order by id
+              limit $3",
+        )
+        .bind(provider_kind)
+        .bind(cursor)
+        .bind(limit)
+        .fetch_all(&self.pool)
+        .await
+        .map_err(|_| postgres_unavailable("list plugin accounts"))?;
+        rows.into_iter().map(account_summary_from_row).collect()
+    }
+
     async fn list_provider_accounts(
         &self,
         provider_kind: Option<&str>,
@@ -456,75 +498,12 @@ impl ProviderAccountAdminRepository for PgProviderAccountRepository {
         &self,
         command: ImportProviderAccounts,
     ) -> StoreResult<ProviderAccountAdminImport> {
-        command.validate()?;
         let mut transaction = self
             .pool
             .begin()
             .await
             .map_err(|_| postgres_unavailable("begin provider account admin import"))?;
-        let result = async {
-            let revision = bump_config_revision_in_transaction(&mut transaction).await?;
-            if let Some(binding) = &command.outbound_proxy {
-                let (_, current) = super::super::proxies::resolve_proxy_selection(
-                    &mut transaction,
-                    &gateway_admin::model::proxies::AccountProxySelection::Saved(
-                        binding.id.clone(),
-                    ),
-                )
-                .await?;
-                if current.as_ref() != Some(&binding.proxy) {
-                    return Err(StoreError::Conflict {
-                        entity: "outbound proxy",
-                        id: binding.id.clone(),
-                        kind: ConflictKind::StaleRevision,
-                    });
-                }
-            }
-            let mut account_ids = Vec::with_capacity(command.accounts.len());
-            for account in &command.accounts {
-                account_ids
-                    .push(upsert_provider_account_in_transaction(&mut transaction, account).await?);
-            }
-            if let Some(settings) = &command.settings {
-                let unique_ids = account_ids
-                    .iter()
-                    .cloned()
-                    .collect::<BTreeSet<_>>()
-                    .into_iter()
-                    .collect::<Vec<_>>();
-                update_provider_accounts_scheduling_in_transaction(
-                    &mut transaction,
-                    &unique_ids,
-                    Some(settings.enabled),
-                    Some(settings.concurrency_limit),
-                    Some(settings.weight),
-                    settings.model_access.as_ref(),
-                    None,
-                )
-                .await?;
-                replace_account_group_assignments_in_transaction(
-                    &mut transaction,
-                    &unique_ids,
-                    &settings.group_ids,
-                )
-                .await?;
-                if let Some(notes) = settings.notes.as_deref() {
-                    update_provider_account_notes_in_transaction(
-                        &mut transaction,
-                        &unique_ids,
-                        notes,
-                    )
-                    .await?;
-                }
-            }
-            append_admin_audit_event_in_transaction(&mut transaction, command.audit, revision)
-                .await?;
-            Ok(ProviderAccountAdminImport {
-                config_revision: revision,
-                account_ids,
-            })
-        }
-        .await;
+        let result = import_provider_accounts_in_transaction(&mut transaction, command).await;
         finish_admin_transaction(transaction, result, "provider account admin import").await
     }
 
@@ -532,78 +511,12 @@ impl ProviderAccountAdminRepository for PgProviderAccountRepository {
         &self,
         command: RotateProviderAccount,
     ) -> StoreResult<ProviderAccountAdminRotation> {
-        command.scope.validate()?;
-        require_nonempty(ENTITY, "account_id", &command.profile.id)?;
-        require_nonempty(ENTITY, "name", &command.profile.name)?;
-        if let Some(identity) = &command.replacement_identity {
-            require_nonempty(ENTITY, "upstream_user_id", identity.upstream_user_id())?;
-            if let Some(account_id) = identity.upstream_account_id() {
-                require_nonempty(ENTITY, "upstream_account_id", account_id)?;
-            }
-        }
-        if command.profile.id != command.credential.account_id {
-            return Err(invalid("rotated profile and credential account IDs differ"));
-        }
-        validate_credential_update(&command.credential)?;
-        if let Some(settings) = &command.settings {
-            if settings.account_id != command.profile.id {
-                return Err(invalid(
-                    "rotated credential and account settings IDs differ",
-                ));
-            }
-            validate_batch_update_group_ids(&settings.group_ids)?;
-        }
         let mut transaction = self
             .pool
             .begin()
             .await
             .map_err(|_| postgres_unavailable("begin provider account admin rotation"))?;
-        let result = async {
-            let config_revision = bump_config_revision_in_transaction(&mut transaction).await?;
-            let credential_revision = rotate_provider_account_in_transaction(
-                &mut transaction,
-                &command.scope,
-                &command.profile,
-                command.replacement_identity.as_ref(),
-                &command.credential,
-            )
-            .await?;
-            // 凭据 CAS、普通设置和审计共享事务，任何设置失败都回滚凭据更新。
-            if let Some(settings) = &command.settings {
-                let ids = std::slice::from_ref(&settings.account_id);
-                update_provider_accounts_scheduling_in_transaction(
-                    &mut transaction,
-                    ids,
-                    Some(settings.enabled),
-                    Some(settings.concurrency_limit),
-                    Some(settings.weight),
-                    settings.model_access.as_ref(),
-                    settings.outbound_proxy.as_ref(),
-                )
-                .await?;
-                replace_account_group_assignments_in_transaction(
-                    &mut transaction,
-                    ids,
-                    &settings.group_ids,
-                )
-                .await?;
-                if let Some(notes) = settings.notes.as_deref() {
-                    update_provider_account_notes_in_transaction(&mut transaction, ids, notes)
-                        .await?;
-                }
-            }
-            append_admin_audit_event_in_transaction(
-                &mut transaction,
-                command.audit,
-                config_revision,
-            )
-            .await?;
-            Ok(ProviderAccountAdminRotation {
-                config_revision,
-                credential_revision,
-            })
-        }
-        .await;
+        let result = rotate_provider_account_admin_in_transaction(&mut transaction, command).await;
         finish_admin_transaction(transaction, result, "provider account admin rotation").await
     }
 
@@ -799,7 +712,7 @@ async fn replace_account_group_assignments_in_transaction(
 pub(crate) async fn upsert_provider_account_in_transaction(
     transaction: &mut Transaction<'_, Postgres>,
     account: &NewProviderAccount,
-) -> StoreResult<String> {
+) -> StoreResult<(String, Revision)> {
     account.validate()?;
     let credential_state = account.credential_state;
     let proxy_id = match account.outbound_proxy.as_ref() {
@@ -810,7 +723,7 @@ pub(crate) async fn upsert_provider_account_in_transaction(
         ),
         None => None,
     };
-    let imported_id = sqlx::query_scalar::<_, String>(
+    let imported = sqlx::query_as::<_, (String, i64)>(
         "insert into provider_accounts (
            outbound_proxy_url, outbound_proxy_id, id, provider_kind, name, email, upstream_user_id,
            upstream_account_id, plan_type, authentication_kind, provider_credentials_json, credential_revision,
@@ -850,7 +763,7 @@ pub(crate) async fn upsert_provider_account_in_transaction(
            last_error_reason = null,
            last_error_message = null,
            updated_at = greatest(now(), provider_accounts.updated_at, excluded.credential_observed_at)
-         returning id",
+         returning id, credential_revision",
     )
     .bind(&account.id)
     .bind(&account.provider_kind)
@@ -893,7 +806,7 @@ pub(crate) async fn upsert_provider_account_in_transaction(
         id: account.id.clone(),
         kind: ConflictKind::InvalidTransition,
     })?;
-    Ok(imported_id)
+    Ok((imported.0, Revision::new(to_u64(imported.1)?)?))
 }
 
 pub(crate) async fn rotate_provider_account_in_transaction(
@@ -1132,3 +1045,126 @@ pub(crate) async fn finish_admin_transaction<T>(
         }
     }
 }
+
+// 授权回执与账号写入需要共享事务；常规导入、刷新和轮换复用同一写入合同。
+pub(super) async fn import_provider_accounts_in_transaction(
+    transaction: &mut Transaction<'_, Postgres>,
+    command: ImportProviderAccounts,
+) -> StoreResult<ProviderAccountAdminImport> {
+    command.validate()?;
+    let revision = bump_config_revision_in_transaction(transaction).await?;
+    if let Some(binding) = &command.outbound_proxy {
+        let (_, current) = super::super::proxies::resolve_proxy_selection(
+            transaction,
+            &gateway_admin::model::proxies::AccountProxySelection::Saved(binding.id.clone()),
+        )
+        .await?;
+        if current.as_ref() != Some(&binding.proxy) {
+            return Err(StoreError::Conflict {
+                entity: "outbound proxy",
+                id: binding.id.clone(),
+                kind: ConflictKind::StaleRevision,
+            });
+        }
+    }
+    let mut account_ids = Vec::with_capacity(command.accounts.len());
+    let mut credential_revisions = std::collections::BTreeMap::new();
+    for account in &command.accounts {
+        let (id, revision) = upsert_provider_account_in_transaction(transaction, account).await?;
+        credential_revisions.insert(id.clone(), revision);
+        account_ids.push(id);
+    }
+    if let Some(settings) = &command.settings {
+        let unique_ids = account_ids
+            .iter()
+            .cloned()
+            .collect::<BTreeSet<_>>()
+            .into_iter()
+            .collect::<Vec<_>>();
+        update_provider_accounts_scheduling_in_transaction(
+            transaction,
+            &unique_ids,
+            Some(settings.enabled),
+            Some(settings.concurrency_limit),
+            Some(settings.weight),
+            settings.model_access.as_ref(),
+            None,
+        )
+        .await?;
+        replace_account_group_assignments_in_transaction(
+            transaction,
+            &unique_ids,
+            &settings.group_ids,
+        )
+        .await?;
+        if let Some(notes) = settings.notes.as_deref() {
+            update_provider_account_notes_in_transaction(transaction, &unique_ids, notes).await?;
+        }
+    }
+    append_admin_audit_event_in_transaction(transaction, command.audit, revision).await?;
+    Ok(ProviderAccountAdminImport {
+        config_revision: revision,
+        account_ids,
+        credential_revisions,
+    })
+}
+
+pub(super) async fn rotate_provider_account_admin_in_transaction(
+    transaction: &mut Transaction<'_, Postgres>,
+    command: RotateProviderAccount,
+) -> StoreResult<ProviderAccountAdminRotation> {
+    command.scope.validate()?;
+    require_nonempty(ENTITY, "account_id", &command.profile.id)?;
+    require_nonempty(ENTITY, "name", &command.profile.name)?;
+    if let Some(identity) = &command.replacement_identity {
+        require_nonempty(ENTITY, "upstream_user_id", identity.upstream_user_id())?;
+        if let Some(account_id) = identity.upstream_account_id() {
+            require_nonempty(ENTITY, "upstream_account_id", account_id)?;
+        }
+    }
+    if command.profile.id != command.credential.account_id {
+        return Err(invalid("rotated profile and credential account IDs differ"));
+    }
+    validate_credential_update(&command.credential)?;
+    if let Some(settings) = &command.settings {
+        if settings.account_id != command.profile.id {
+            return Err(invalid(
+                "rotated credential and account settings IDs differ",
+            ));
+        }
+        validate_batch_update_group_ids(&settings.group_ids)?;
+    }
+    let config_revision = bump_config_revision_in_transaction(transaction).await?;
+    let credential_revision = rotate_provider_account_in_transaction(
+        transaction,
+        &command.scope,
+        &command.profile,
+        command.replacement_identity.as_ref(),
+        &command.credential,
+    )
+    .await?;
+    // 凭据 CAS、普通设置和审计共享事务，任何设置失败都回滚凭据更新。
+    if let Some(settings) = &command.settings {
+        let ids = std::slice::from_ref(&settings.account_id);
+        update_provider_accounts_scheduling_in_transaction(
+            transaction,
+            ids,
+            Some(settings.enabled),
+            Some(settings.concurrency_limit),
+            Some(settings.weight),
+            settings.model_access.as_ref(),
+            settings.outbound_proxy.as_ref(),
+        )
+        .await?;
+        replace_account_group_assignments_in_transaction(transaction, ids, &settings.group_ids)
+            .await?;
+        if let Some(notes) = settings.notes.as_deref() {
+            update_provider_account_notes_in_transaction(transaction, ids, notes).await?;
+        }
+    }
+    append_admin_audit_event_in_transaction(transaction, command.audit, config_revision).await?;
+    Ok(ProviderAccountAdminRotation {
+        config_revision,
+        credential_revision,
+    })
+}
diff --git a/backend/crates/gateway-store/src/postgres/provider_accounts/rows.rs b/backend/crates/gateway-store/src/postgres/provider_accounts/rows.rs
index 645b2dad0..5d4b2d183 100644
--- a/backend/crates/gateway-store/src/postgres/provider_accounts/rows.rs
+++ b/backend/crates/gateway-store/src/postgres/provider_accounts/rows.rs
@@ -247,6 +247,8 @@ pub struct ImportProviderAccounts {
 pub struct ProviderAccountAdminImport {
     pub config_revision: Revision,
     pub account_ids: Vec<String>,
+    /// 与导入同一事务返回的最终凭据版本，避免提交后再查到另一轮写入。
+    pub credential_revisions: std::collections::BTreeMap<String, Revision>,
 }
 
 impl fmt::Debug for ImportProviderAccounts {
diff --git a/backend/crates/gateway-store/src/postgres/runtime_settings.rs b/backend/crates/gateway-store/src/postgres/runtime_settings.rs
index 8bc3f18f0..5eab65c65 100644
--- a/backend/crates/gateway-store/src/postgres/runtime_settings.rs
+++ b/backend/crates/gateway-store/src/postgres/runtime_settings.rs
@@ -19,8 +19,8 @@ use crate::{Revision, StoreError, StoreResult, postgres_unavailable};
 
 #[derive(Clone, PartialEq, Eq)]
 pub struct RuntimeSettings {
-    pub openai_client_profile: Option<gateway_core::account::OpaqueProviderData>,
-    pub xai_client_profile: Option<gateway_core::account::OpaqueProviderData>,
+    pub request_profiles:
+        BTreeMap<gateway_core::routing::ProviderKind, gateway_core::account::OpaqueProviderData>,
     pub config_revision: Revision,
     pub admin_api_key: Option<String>,
     pub refresh_margin_seconds: u64,
@@ -54,6 +54,7 @@ impl fmt::Debug for RuntimeSettings {
     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
         formatter
             .debug_struct("RuntimeSettings")
+            .field("request_profile_count", &self.request_profiles.len())
             .field("config_revision", &self.config_revision)
             .field(
                 "admin_api_key",
@@ -110,8 +111,10 @@ impl fmt::Debug for RuntimeSettings {
 
 #[derive(Clone)]
 pub struct RuntimeSettingsUpdate {
-    pub openai_client_profile: Option<gateway_core::account::OpaqueProviderData>,
-    pub xai_client_profile: Option<gateway_core::account::OpaqueProviderData>,
+    pub request_profile_updates: BTreeMap<
+        gateway_core::routing::ProviderKind,
+        Option<gateway_core::account::OpaqueProviderData>,
+    >,
     pub admin_api_key: Option<String>,
     pub refresh_margin_seconds: u64,
     pub refresh_concurrency: u32,
@@ -176,6 +179,15 @@ impl RuntimeSettingsUpdate {
             || !valid_client_version(self.min_codex_cli_version.as_deref())
             || !valid_probe_model(self.account_auto_freeze_probe_model.as_deref())
             || RotationStrategy::parse(&self.rotation_strategy).is_none()
+            || self.request_profile_updates.len() > 256
+            || self
+                .request_profile_updates
+                .values()
+                .flatten()
+                .any(|profile| {
+                    serde_json::to_vec(profile.expose_to_provider())
+                        .map_or(true, |encoded| encoded.len() > 64 * 1024)
+                })
         {
             return Err(StoreError::InvalidData {
                 entity: "runtime settings",
@@ -278,6 +290,56 @@ impl ProviderRuntimePolicyPort for PgRuntimeSettingsRepository {
         })
     }
 
+    fn load_request_profile_configurations<'a>(
+        &'a self,
+        revision: gateway_core::routing::ConfigRevision,
+        provider: &'a gateway_core::routing::ProviderKind,
+    ) -> futures::future::BoxFuture<
+        'a,
+        Result<Vec<gateway_core::account::OpaqueProviderData>, ProviderStoreError>,
+    > {
+        Box::pin(async move {
+            // 单条语句共享一个 MVCC 快照：先核对候选 revision，再只投影配置对象；
+            // Client Key 明文与其它策略字段不会进入插件准备边界。
+            let rows = sqlx::query_as::<_, (i64, Option<sqlx::types::Json<serde_json::Value>>)>(
+                "select settings.config_revision, profiles.profile
+                 from runtime_settings settings
+                 cross join lateral (
+                   select settings.provider_request_profiles_json -> $1 as profile
+                   union
+                   select keys.provider_request_profiles_json -> $1
+                   from client_api_keys keys
+                   where keys.provider_request_profiles_json ? $1
+                 ) profiles
+                 where settings.id = 1",
+            )
+            .bind(provider.as_str())
+            .fetch_all(&self.pool)
+            .await
+            .map_err(|_| provider_unavailable("load Provider request profile configurations"))?;
+            let expected_revision = i64::try_from(revision.get())
+                .map_err(|_| provider_invalid("validate Provider request profile revision"))?;
+            if rows.is_empty()
+                || rows
+                    .iter()
+                    .any(|(actual_revision, _)| *actual_revision != expected_revision)
+            {
+                return Err(provider_conflict(
+                    "validate Provider request profile revision",
+                ));
+            }
+            rows.into_iter()
+                .filter_map(|(_, profile)| profile)
+                .map(|profile| {
+                    let serde_json::Value::Object(profile) = profile.0 else {
+                        return Err(provider_invalid("decode Provider request profile"));
+                    };
+                    Ok(gateway_core::account::OpaqueProviderData::new(profile))
+                })
+                .collect()
+        })
+    }
+
     fn load_refresh_policy(
         &self,
     ) -> futures::future::BoxFuture<'_, Result<ProviderRefreshPolicy, ProviderStoreError>> {
@@ -346,6 +408,24 @@ pub(crate) async fn update_runtime_settings_in_transaction(
     update.validate()?;
     let refresh_margin_seconds =
         i64::try_from(update.refresh_margin_seconds).map_err(|_| invalid_numeric())?;
+    let request_profile_updates = update
+        .request_profile_updates
+        .iter()
+        .filter_map(|(provider, profile)| {
+            profile.as_ref().map(|profile| {
+                (
+                    provider.as_str().to_owned(),
+                    serde_json::Value::Object(profile.expose_to_provider().clone()),
+                )
+            })
+        })
+        .collect::<serde_json::Map<_, _>>();
+    let request_profile_deletions = update
+        .request_profile_updates
+        .iter()
+        .filter(|(_, profile)| profile.is_none())
+        .map(|(provider, _)| provider.as_str().to_owned())
+        .collect::<Vec<_>>();
     let next = sqlx::query_scalar::<_, i64>(
         "update runtime_settings
              set config_revision = config_revision + 1,
@@ -374,9 +454,7 @@ pub(crate) async fn update_runtime_settings_in_transaction(
                      request_location_json = $23,
                      request_location_enabled = $24,
                      responses_max_decompressed_body_bytes = $25,
-                     provider_request_profiles_json = provider_request_profiles_json
-                         || case when $26::jsonb is null then '{}'::jsonb else jsonb_build_object('openai', $26::jsonb) end
-                         || case when $27::jsonb is null then '{}'::jsonb else jsonb_build_object('xai', $27::jsonb) end,
+	                 provider_request_profiles_json = (provider_request_profiles_json - $26::text[]) || $27::jsonb,
 	                 updated_at = now()
 	             where id = 1
 	             returning config_revision",
@@ -418,8 +496,8 @@ pub(crate) async fn update_runtime_settings_in_transaction(
         i64::try_from(update.responses_max_decompressed_body_bytes)
             .map_err(|_| invalid_numeric())?,
     )
-    .bind(update.openai_client_profile.as_ref().map(|profile| sqlx::types::Json(profile.expose_to_provider())))
-    .bind(update.xai_client_profile.as_ref().map(|profile| sqlx::types::Json(profile.expose_to_provider())))
+    .bind(request_profile_deletions)
+    .bind(sqlx::types::Json(request_profile_updates))
     .fetch_optional(&mut **transaction)
     .await
     .map_err(|_| postgres_unavailable("update runtime settings in transaction"))?
@@ -501,18 +579,22 @@ struct RuntimeSettingsRow {
     account_auto_freeze_adaptive_concurrency: bool,
 }
 
-fn runtime_settings_from_row(mut row: RuntimeSettingsRow) -> StoreResult<RuntimeSettings> {
+fn runtime_settings_from_row(row: RuntimeSettingsRow) -> StoreResult<RuntimeSettings> {
+    let request_profiles = row
+        .provider_request_profiles_json
+        .0
+        .into_iter()
+        .map(|(provider, profile)| {
+            let provider = gateway_core::routing::ProviderKind::new(provider)
+                .map_err(|_| invalid_request_profile())?;
+            Ok((
+                provider,
+                gateway_core::account::OpaqueProviderData::new(profile),
+            ))
+        })
+        .collect::<StoreResult<BTreeMap<_, _>>>()?;
     Ok(RuntimeSettings {
-        openai_client_profile: row
-            .provider_request_profiles_json
-            .0
-            .remove("openai")
-            .map(gateway_core::account::OpaqueProviderData::new),
-        xai_client_profile: row
-            .provider_request_profiles_json
-            .0
-            .remove("xai")
-            .map(gateway_core::account::OpaqueProviderData::new),
+        request_profiles,
         config_revision: Revision::new(to_u64(row.config_revision)?)?,
         admin_api_key: row.admin_api_key,
         refresh_margin_seconds: to_u64(row.refresh_margin_seconds)?,
@@ -562,6 +644,13 @@ fn invalid_location() -> StoreError {
     }
 }
 
+fn invalid_request_profile() -> StoreError {
+    StoreError::InvalidData {
+        entity: "runtime settings",
+        message: "Provider request profile key is invalid".to_owned(),
+    }
+}
+
 fn invalid_numeric() -> StoreError {
     StoreError::InvalidData {
         entity: "runtime settings",
@@ -577,6 +666,10 @@ fn provider_invalid(operation: &'static str) -> ProviderStoreError {
     ProviderStoreError::new(ProviderStoreErrorKind::InvalidData, operation)
 }
 
+fn provider_conflict(operation: &'static str) -> ProviderStoreError {
+    ProviderStoreError::new(ProviderStoreErrorKind::Conflict, operation)
+}
+
 fn valid_model_mappings(mappings: &BTreeMap<String, String>) -> bool {
     mappings.len() <= 512
         && mappings.iter().all(|(requested, upstream)| {
diff --git a/backend/crates/gateway-store/src/redis/coordination_buffer.rs b/backend/crates/gateway-store/src/redis/coordination_buffer.rs
index 02521a2f3..ab0334969 100644
--- a/backend/crates/gateway-store/src/redis/coordination_buffer.rs
+++ b/backend/crates/gateway-store/src/redis/coordination_buffer.rs
@@ -3,8 +3,11 @@
 //! Continuation affinity 决定下一轮 Provider 与账号，必须在响应 ID 可复用前
 //! 获得 Redis 确认，因此不属于本模块的可丢失副作用。
 
-use std::num::NonZeroUsize;
 use std::sync::Arc;
+use std::{
+    num::NonZeroUsize,
+    time::{Duration, Instant},
+};
 
 use futures::future::{BoxFuture, ready};
 use gateway_core::engine::ModelRequestId;
@@ -22,6 +25,7 @@ use gateway_core::task::{DaemonTask, WorkerTaskError};
 use tokio::sync::{Mutex, mpsc};
 
 const DEFAULT_QUEUE_CAPACITY: usize = 4_096;
+const SHUTDOWN_DRAIN_TIMEOUT: Duration = Duration::from_secs(2);
 
 /// 准入读取保持强一致；终态释放只做有界入队，Redis 失败由 worker 吸收。
 #[derive(Clone)]
@@ -127,7 +131,10 @@ impl DaemonTask for ClientAdmissionReleaseWriter {
             let mut receiver = self.receiver.lock().await;
             loop {
                 let release = tokio::select! {
-                    () = cancellation.cancelled() => return Ok(()),
+                    () = cancellation.cancelled() => {
+                        drain_admission_releases(&mut receiver, self.inner.as_ref()).await;
+                        return Ok(());
+                    },
                     release = receiver.recv() => release,
                 };
                 let Some(release) = release else {
@@ -237,7 +244,10 @@ impl DaemonTask for ProviderCircuitFeedbackWriter {
             let mut receiver = self.receiver.lock().await;
             loop {
                 let feedback = tokio::select! {
-                    () = cancellation.cancelled() => return Ok(()),
+                    () = cancellation.cancelled() => {
+                        drain_circuit_feedback(&mut receiver, self.inner.as_ref()).await;
+                        return Ok(());
+                    },
                     feedback = receiver.recv() => feedback,
                 };
                 let Some(feedback) = feedback else {
@@ -260,3 +270,52 @@ impl DaemonTask for ProviderCircuitFeedbackWriter {
         })
     }
 }
+
+async fn drain_admission_releases(
+    receiver: &mut mpsc::Receiver<AdmissionRelease>,
+    port: &dyn ClientAdmissionPort,
+) {
+    receiver.close();
+    let started_at = Instant::now();
+    while let Some(release) = receiver.recv().await {
+        let remaining = SHUTDOWN_DRAIN_TIMEOUT.saturating_sub(started_at.elapsed());
+        if remaining.is_zero()
+            || tokio::time::timeout(
+                remaining,
+                port.release(&release.client_api_key_id, &release.model_request_id),
+            )
+            .await
+            .is_err()
+        {
+            tracing::warn!("Client admission 关闭排空超时，剩余租约依赖 TTL 收敛");
+            break;
+        }
+    }
+}
+
+async fn drain_circuit_feedback(
+    receiver: &mut mpsc::Receiver<CircuitFeedback>,
+    port: &dyn ProviderCircuitPort,
+) {
+    receiver.close();
+    let started_at = Instant::now();
+    while let Some(feedback) = receiver.recv().await {
+        let remaining = SHUTDOWN_DRAIN_TIMEOUT.saturating_sub(started_at.elapsed());
+        if remaining.is_zero() {
+            tracing::warn!("Provider circuit 关闭排空超时，剩余反馈已丢弃");
+            break;
+        }
+        let result = match feedback {
+            CircuitFeedback::Failure(provider) => {
+                tokio::time::timeout(remaining, port.observe_failure(&provider)).await
+            }
+            CircuitFeedback::Success(provider) => {
+                tokio::time::timeout(remaining, port.observe_success(&provider)).await
+            }
+        };
+        if result.is_err() {
+            tracing::warn!("Provider circuit 关闭排空超时，剩余反馈已丢弃");
+            break;
+        }
+    }
+}
diff --git a/backend/crates/gateway-store/src/workers.rs b/backend/crates/gateway-store/src/workers.rs
index 1bcf4d8be..29dce232b 100644
--- a/backend/crates/gateway-store/src/workers.rs
+++ b/backend/crates/gateway-store/src/workers.rs
@@ -1,6 +1,101 @@
 //! Worker 贡献、调度定义与健康探针。
 
 use super::*;
+use gateway_core::task::DaemonTask;
+
+const COMMAND_DRAIN_TIMEOUT: Duration = Duration::from_secs(4);
+
+pub(crate) struct CommandStoreWriters {
+    pub(crate) execution: postgres::ExecutionObservationWriter<postgres::PgExecutionStore>,
+    pub(crate) client_key_usage: postgres::PgClientApiKeyUsageWriter,
+    pub(crate) admission_release: redis::ClientAdmissionReleaseWriter,
+    pub(crate) circuit_feedback: redis::ProviderCircuitFeedbackWriter,
+}
+
+/// 短生命周期 CLI 只运行数据面必需的四个写泵，不注册恢复、保留或维护 Worker。
+pub struct CommandStoreDrain {
+    cancellation: gateway_core::lifecycle::CancellationToken,
+    tasks: Vec<tokio::task::JoinHandle<Result<(), WorkerTaskError>>>,
+    execution_idle: postgres::ExecutionBufferIdle,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+#[error("command store writes could not be drained")]
+pub struct CommandStoreDrainError;
+
+impl CommandStoreWriters {
+    pub(crate) fn start(self) -> CommandStoreDrain {
+        let cancellation = gateway_core::lifecycle::CancellationToken::new();
+        let Self {
+            execution,
+            client_key_usage,
+            admission_release,
+            circuit_feedback,
+        } = self;
+        let execution_idle = execution.idle();
+        let tasks = vec![
+            spawn_command_writer(execution, cancellation.child_token()),
+            spawn_command_writer(client_key_usage, cancellation.child_token()),
+            spawn_command_writer(admission_release, cancellation.child_token()),
+            spawn_command_writer(circuit_feedback, cancellation.child_token()),
+        ];
+        CommandStoreDrain {
+            cancellation,
+            tasks,
+            execution_idle,
+        }
+    }
+}
+
+fn spawn_command_writer<T>(
+    writer: T,
+    cancellation: gateway_core::lifecycle::CancellationToken,
+) -> tokio::task::JoinHandle<Result<(), WorkerTaskError>>
+where
+    T: DaemonTask + Send + 'static,
+{
+    tokio::spawn(async move { writer.run(cancellation).await })
+}
+
+impl CommandStoreDrain {
+    pub(crate) async fn shutdown(mut self) -> Result<(), CommandStoreDrainError> {
+        let deadline = std::time::Instant::now() + COMMAND_DRAIN_TIMEOUT;
+        // CLI 调用方已结束数据面会话；先让已接收的 execution 写入在正常 writer
+        // 路径完成，避免立即取消后落入更短的常驻进程关闭丢弃窗口。
+        let mut failed = !self.execution_idle.wait_until(deadline).await;
+        self.cancellation.cancel();
+        for mut task in self.tasks.drain(..) {
+            let remaining = deadline.saturating_duration_since(std::time::Instant::now());
+            if remaining.is_zero() {
+                task.abort();
+                failed = true;
+                continue;
+            }
+            match tokio::time::timeout(remaining, &mut task).await {
+                Ok(Ok(Ok(()))) => {}
+                Ok(Ok(Err(_))) | Ok(Err(_)) => failed = true,
+                Err(_) => {
+                    task.abort();
+                    failed = true;
+                }
+            }
+        }
+        if failed {
+            Err(CommandStoreDrainError)
+        } else {
+            Ok(())
+        }
+    }
+}
+
+impl Drop for CommandStoreDrain {
+    fn drop(&mut self) {
+        self.cancellation.cancel();
+        for task in &self.tasks {
+            task.abort();
+        }
+    }
+}
 
 pub(crate) fn store_worker_contributions(
     execution: Arc<postgres::PgExecutionStore>,
diff --git a/backend/crates/gateway-store/tests/bundle.rs b/backend/crates/gateway-store/tests/bundle.rs
new file mode 100644
index 000000000..f7b37ae68
--- /dev/null
+++ b/backend/crates/gateway-store/tests/bundle.rs
@@ -0,0 +1,109 @@
+use gateway_core::{
+    account::{
+        CredentialRevision, NewProviderAccount, PlaintextCredential, ProviderAccount,
+        ProviderAccountId,
+    },
+    routing::ProviderKind,
+};
+use gateway_store::StoreConfig;
+use serde_json::json;
+use sqlx::postgres::PgPoolOptions;
+
+#[tokio::test]
+async fn inspection_bundle_does_not_migrate_and_rejects_business_writes() {
+    let (Some(database), Some(redis)) = (
+        crate::support::test_env("CPR_TEST_DATABASE_URL"),
+        crate::support::test_env("CPR_TEST_REDIS_URL"),
+    ) else {
+        return;
+    };
+    let schema = format!("cpr_inspection_{}", uuid::Uuid::new_v4().simple());
+    let admin = PgPoolOptions::new()
+        .max_connections(1)
+        .connect(&database)
+        .await
+        .unwrap();
+    sqlx::raw_sql(sqlx::AssertSqlSafe(format!("create schema {schema}")))
+        .execute(&admin)
+        .await
+        .unwrap();
+    let mut database = url::Url::parse(&database).unwrap();
+    database
+        .query_pairs_mut()
+        .append_pair("options", &format!("-csearch_path={schema}"));
+    let config_connection = |mut url: url::Url| {
+        let password = url.password().unwrap().to_owned();
+        url.set_password(None).unwrap();
+        json!({"url":url.as_str(),"password":password})
+    };
+    let mut config: StoreConfig = serde_json::from_value(json!({
+        "database":config_connection(database), "redis":config_connection(url::Url::parse(&redis).unwrap()),
+    })).unwrap();
+    let directory = tempfile::tempdir().unwrap();
+    config.resolve_and_validate(directory.path()).unwrap();
+    let inspection = gateway_store::initialize_read_only(config.clone())
+        .await
+        .unwrap();
+    assert!(
+        inspection
+            .admin_ports()
+            .plugins()
+            .load_instances()
+            .await
+            .is_err()
+    );
+    let tables: i64 =
+        sqlx::query_scalar("select count(*) from information_schema.tables where table_schema=$1")
+            .bind(&schema)
+            .fetch_one(&admin)
+            .await
+            .unwrap();
+    assert_eq!(tables, 0, "只读帮助不能在空库创建迁移表或业务表");
+    drop(inspection);
+    let writable = gateway_store::initialize(config.clone()).await.unwrap();
+    let inspection = gateway_store::initialize_read_only(config).await.unwrap();
+    let create = |id: &str| NewProviderAccount {
+        account: ProviderAccount::new(
+            ProviderAccountId::new(id.to_owned()).unwrap(),
+            ProviderKind::new("example").unwrap(),
+            "inspection test".into(),
+            None,
+            "api_key".into(),
+            CredentialRevision::new(1).unwrap(),
+            None,
+        ),
+        credential: PlaintextCredential::new(
+            json!({"key":"test-only"}).as_object().unwrap().clone(),
+        ),
+        model_access: None,
+    };
+    writable
+        .provider_ports()
+        .accounts()
+        .create_account(create("acct_writable"))
+        .await
+        .unwrap();
+    assert!(
+        inspection
+            .provider_ports()
+            .accounts()
+            .create_account(create("acct_readonly"))
+            .await
+            .is_err()
+    );
+    let accounts = inspection
+        .provider_ports()
+        .accounts()
+        .list_accounts()
+        .await
+        .unwrap();
+    assert_eq!(accounts.len(), 1);
+    assert_eq!(accounts[0].id().as_str(), "acct_writable");
+    drop(inspection);
+    drop(writable);
+    sqlx::raw_sql(sqlx::AssertSqlSafe(format!("drop schema {schema} cascade")))
+        .execute(&admin)
+        .await
+        .unwrap();
+    admin.close().await;
+}
diff --git a/backend/crates/gateway-store/tests/main.rs b/backend/crates/gateway-store/tests/main.rs
index f1acfc4ba..10559529c 100644
--- a/backend/crates/gateway-store/tests/main.rs
+++ b/backend/crates/gateway-store/tests/main.rs
@@ -1,4 +1,5 @@
 mod backup;
+mod bundle;
 mod config;
 mod postgres;
 mod redis;
diff --git a/backend/crates/gateway-store/tests/postgres/account_groups.rs b/backend/crates/gateway-store/tests/postgres/account_groups.rs
index 87cfaceba..d5daa06f6 100644
--- a/backend/crates/gateway-store/tests/postgres/account_groups.rs
+++ b/backend/crates/gateway-store/tests/postgres/account_groups.rs
@@ -173,8 +173,7 @@ async fn groups_aggregate_cross_provider_members_and_key_bindings_without_multip
     let (scope_revision, widened) = keys
         .update_client_key(
             UpdateClientKey {
-                openai_client_profile_override: None,
-                xai_client_profile_override: None,
+                request_profile_override_updates: Default::default(),
                 daily_limit_usd: None,
                 weekly_limit_usd: None,
                 id: client_key_id("key_group_one"),
@@ -200,8 +199,7 @@ async fn groups_aggregate_cross_provider_members_and_key_bindings_without_multip
     let (restricted_revision, restricted) = keys
         .update_client_key(
             UpdateClientKey {
-                openai_client_profile_override: None,
-                xai_client_profile_override: None,
+                request_profile_override_updates: Default::default(),
                 daily_limit_usd: None,
                 weekly_limit_usd: None,
                 id: client_key_id("key_group_one"),
@@ -325,8 +323,7 @@ async fn group_costs_should_include_statusless_websocket_but_reject_statusless_h
 fn new_key(id: &str, group_ids: Vec<AccountGroupId>) -> NewClientKey {
     let marker = char::from(id.as_bytes().last().copied().unwrap_or(b'k'));
     NewClientKey {
-        openai_client_profile_override: None,
-        xai_client_profile_override: None,
+        request_profile_overrides: Default::default(),
         budget: Default::default(),
         id: client_key_id(id),
         name: id.to_owned(),
diff --git a/backend/crates/gateway-store/tests/postgres/client_budgets.rs b/backend/crates/gateway-store/tests/postgres/client_budgets.rs
index adbcb3151..af91b63ea 100644
--- a/backend/crates/gateway-store/tests/postgres/client_budgets.rs
+++ b/backend/crates/gateway-store/tests/postgres/client_budgets.rs
@@ -471,8 +471,7 @@ async fn budget_updates_preserve_omitted_limits_and_do_not_clear_usage() {
         .await
         .unwrap();
     let update = UpdateClientKey {
-        openai_client_profile_override: None,
-        xai_client_profile_override: None,
+        request_profile_override_updates: Default::default(),
         id: ClientApiKeyId::new("key").unwrap(),
         name: "key".to_owned(),
         label: None,
@@ -491,8 +490,7 @@ async fn budget_updates_preserve_omitted_limits_and_do_not_clear_usage() {
     admin
         .update_client_key(
             UpdateClientKey {
-                openai_client_profile_override: None,
-                xai_client_profile_override: None,
+                request_profile_override_updates: Default::default(),
                 daily_limit_usd: None,
                 weekly_limit_usd: None,
                 ..update.clone()
@@ -516,8 +514,7 @@ async fn budget_updates_preserve_omitted_limits_and_do_not_clear_usage() {
     admin
         .update_client_key(
             UpdateClientKey {
-                openai_client_profile_override: None,
-                xai_client_profile_override: None,
+                request_profile_override_updates: Default::default(),
                 daily_limit_usd: Some("0".parse().unwrap()),
                 weekly_limit_usd: None,
                 ..update
diff --git a/backend/crates/gateway-store/tests/postgres/client_keys.rs b/backend/crates/gateway-store/tests/postgres/client_keys.rs
index 7ccfa4b85..693a3c4ac 100644
--- a/backend/crates/gateway-store/tests/postgres/client_keys.rs
+++ b/backend/crates/gateway-store/tests/postgres/client_keys.rs
@@ -49,8 +49,7 @@ async fn migrated_keys_persist_exactly_and_keep_short_keys_masked() {
         let (_, record) = store
             .create_client_key(
                 NewClientKey {
-                    openai_client_profile_override: None,
-                    xai_client_profile_override: None,
+                    request_profile_overrides: Default::default(),
                     id: id.clone(),
                     name: format!("Migrated {index}"),
                     label: None,
@@ -105,8 +104,7 @@ async fn duplicate_migrated_keys_conflict_atomically_without_extra_audits() {
     };
     let key = "legacy-key-case-sensitive!";
     let command = |id: &str| NewClientKey {
-        openai_client_profile_override: None,
-        xai_client_profile_override: None,
+        request_profile_overrides: Default::default(),
         id: ClientApiKeyId::new(id).unwrap(),
         name: id.to_owned(),
         label: None,
@@ -142,8 +140,7 @@ async fn duplicate_migrated_keys_conflict_atomically_without_extra_audits() {
 #[test]
 fn generated_client_key_format_remains_valid() {
     let key = NewClientApiKey {
-        openai_client_profile_override: None,
-        xai_client_profile_override: None,
+        request_profile_overrides: Default::default(),
         budget: Default::default(),
         id: "key-1".to_owned(),
         name: "default".to_owned(),
@@ -176,8 +173,7 @@ async fn client_key_names_are_checked_atomically_on_create_and_rename() {
         request_id: "duplicate-name-test".to_owned(),
     };
     let create = |id: &str, name: &str| NewClientKey {
-        openai_client_profile_override: None,
-        xai_client_profile_override: None,
+        request_profile_overrides: Default::default(),
         id: ClientApiKeyId::new(id).unwrap(),
         name: name.to_owned(),
         label: None,
@@ -187,8 +183,7 @@ async fn client_key_names_are_checked_atomically_on_create_and_rename() {
         plaintext: format!("synthetic-credential-{id}"),
     };
     let update = |id: ClientApiKeyId, name: &str| UpdateClientKey {
-        openai_client_profile_override: None,
-        xai_client_profile_override: None,
+        request_profile_override_updates: Default::default(),
         id,
         name: name.to_owned(),
         label: None,
@@ -643,8 +638,7 @@ async fn dedicated_reveal_returns_plaintext_without_debug_exposure() {
 fn client_key_debug_redacts_plaintext() {
     let secret = format!("sk_{}", "s".repeat(43));
     let key = NewClientApiKey {
-        openai_client_profile_override: None,
-        xai_client_profile_override: None,
+        request_profile_overrides: Default::default(),
         budget: Default::default(),
         id: "key-1".to_owned(),
         name: "default".to_owned(),
@@ -712,6 +706,8 @@ async fn key_profile_override_roundtrips_and_explicit_clear_restores_inheritance
             .clone(),
     );
     let id = ClientApiKeyId::new("key_profile").unwrap();
+    let openai = gateway_core::routing::ProviderKind::new("openai").unwrap();
+    let dynamic = gateway_core::routing::ProviderKind::new("provider.example").unwrap();
     let (_, record) = store
         .create_client_key(
             NewClientKey {
@@ -722,16 +718,24 @@ async fn key_profile_override_roundtrips_and_explicit_clear_restores_inheritance
                 limits: RateLimits::unlimited(),
                 budget: Default::default(),
                 plaintext: "synthetic-profile-test-key".to_owned(),
-                openai_client_profile_override: Some(profile.clone()),
-                xai_client_profile_override: Some(profile.clone()),
+                request_profile_overrides: BTreeMap::from([
+                    (openai.clone(), profile.clone()),
+                    (dynamic.clone(), profile.clone()),
+                ]),
             },
             &context,
         )
         .await
         .unwrap();
-    assert_eq!(record.openai_client_profile_override, Some(profile.clone()));
-    assert_eq!(record.xai_client_profile_override, Some(profile.clone()));
-    let update = |override_value| UpdateClientKey {
+    assert_eq!(
+        record.request_profile_overrides.get(&openai),
+        Some(&profile)
+    );
+    assert_eq!(
+        record.request_profile_overrides.get(&dynamic),
+        Some(&profile)
+    );
+    let update = |override_value: Option<Option<OpaqueProviderData>>| UpdateClientKey {
         id: id.clone(),
         name: "profile".to_owned(),
         label: None,
@@ -739,18 +743,22 @@ async fn key_profile_override_roundtrips_and_explicit_clear_restores_inheritance
         limits: RateLimits::unlimited(),
         daily_limit_usd: None,
         weekly_limit_usd: None,
-        openai_client_profile_override: override_value,
-        xai_client_profile_override: None,
+        request_profile_override_updates: override_value
+            .map(|profile| BTreeMap::from([(openai.clone(), profile)]))
+            .unwrap_or_default(),
     };
     let (_, unchanged) = store
         .update_client_key(update(None), &context)
         .await
         .unwrap();
     assert_eq!(
-        unchanged.openai_client_profile_override,
-        Some(profile.clone())
+        unchanged.request_profile_overrides.get(&openai),
+        Some(&profile)
+    );
+    assert_eq!(
+        unchanged.request_profile_overrides.get(&dynamic),
+        Some(&profile)
     );
-    assert_eq!(unchanged.xai_client_profile_override, Some(profile.clone()));
     let snapshot = PgRuntimeSnapshotRepository::new(database.pool.clone())
         .load_runtime_snapshot()
         .await
@@ -760,24 +768,31 @@ async fn key_profile_override_roundtrips_and_explicit_clear_restores_inheritance
         Some(&profile)
     );
     assert_eq!(
-        snapshot.client_api_keys[0]
-            .request_profiles
-            .get(&gateway_core::routing::ProviderKind::new("xai").unwrap()),
+        snapshot.client_api_keys[0].request_profiles.get(&dynamic),
         Some(&profile)
     );
-    let mut clear_xai = update(None);
-    clear_xai.xai_client_profile_override = Some(None);
-    let (_, cleared_xai) = store.update_client_key(clear_xai, &context).await.unwrap();
-    assert_eq!(cleared_xai.xai_client_profile_override, None);
+    let mut clear_dynamic = update(None);
+    clear_dynamic
+        .request_profile_override_updates
+        .insert(dynamic.clone(), None);
+    let (_, cleared_dynamic) = store
+        .update_client_key(clear_dynamic, &context)
+        .await
+        .unwrap();
+    assert!(
+        !cleared_dynamic
+            .request_profile_overrides
+            .contains_key(&dynamic)
+    );
     assert_eq!(
-        cleared_xai.openai_client_profile_override,
-        Some(profile.clone())
+        cleared_dynamic.request_profile_overrides.get(&openai),
+        Some(&profile)
     );
     let (_, cleared) = store
         .update_client_key(update(Some(None)), &context)
         .await
         .unwrap();
-    assert_eq!(cleared.openai_client_profile_override, None);
+    assert!(!cleared.request_profile_overrides.contains_key(&openai));
     let snapshot = PgRuntimeSnapshotRepository::new(database.pool.clone())
         .load_runtime_snapshot()
         .await
diff --git a/backend/crates/gateway-store/tests/postgres/execution.rs b/backend/crates/gateway-store/tests/postgres/execution.rs
index 1dfa7b40d..1cc352b5f 100644
--- a/backend/crates/gateway-store/tests/postgres/execution.rs
+++ b/backend/crates/gateway-store/tests/postgres/execution.rs
@@ -441,6 +441,14 @@ async fn billing_snapshot_survives_later_price_changes_and_usage_detail_reads()
     seed_running_request(&database.pool, "req_billing_snapshot")
         .await
         .unwrap();
+    sqlx::query(
+        "update model_requests
+         set provider_kind = 'example-plugin', upstream_model_id = 'plugin-model'
+         where id = 'req_billing_snapshot'",
+    )
+    .execute(&database.pool)
+    .await
+    .unwrap();
     let money = |ticks| {
         Money::new(
             Decimal::from_scaled(ticks).unwrap(),
@@ -489,7 +497,7 @@ async fn billing_snapshot_survives_later_price_changes_and_usage_detail_reads()
     assert_eq!(saved.custom_multiplier_bps, 12500);
     assert_eq!(saved.total_amount.amount, "0.00075".parse().unwrap());
     sqlx::query("update runtime_settings set pricing_overrides_json = $1 where id = 1")
-        .bind(json!({"openai":{"gpt-5.4":{"multiplierBps":90000,"bands":{}}}}))
+        .bind(json!({"example-plugin":{"plugin-model":{"multiplierBps":90000,"bands":{}}}}))
         .execute(&database.pool)
         .await
         .unwrap();
diff --git a/backend/crates/gateway-store/tests/postgres/execution_buffer.rs b/backend/crates/gateway-store/tests/postgres/execution_buffer.rs
index 5c014b290..76cdf0c84 100644
--- a/backend/crates/gateway-store/tests/postgres/execution_buffer.rs
+++ b/backend/crates/gateway-store/tests/postgres/execution_buffer.rs
@@ -1,6 +1,7 @@
 use std::num::NonZeroUsize;
+use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::{Arc, Mutex};
-use std::time::{Duration, SystemTime};
+use std::time::{Duration, Instant, SystemTime};
 
 use async_trait::async_trait;
 use gateway_core::account::ProviderAccountId;
@@ -18,6 +19,7 @@ use gateway_core::upstream::UpstreamSendState;
 use gateway_store::postgres::{
     BufferedExecutionStore, ObservabilityRepository as _, PgExecutionStore,
 };
+use tokio::sync::{Notify, Semaphore};
 
 use super::{
     TestDatabase,
@@ -102,6 +104,139 @@ impl ExecutionStore for RecordingStore {
     }
 }
 
+struct BlockingStore {
+    active: AtomicUsize,
+    maximum_active: AtomicUsize,
+    started: AtomicUsize,
+    started_changed: Notify,
+    releases: Semaphore,
+    operations: Mutex<Vec<(String, &'static str)>>,
+}
+
+impl Default for BlockingStore {
+    fn default() -> Self {
+        Self {
+            active: AtomicUsize::new(0),
+            maximum_active: AtomicUsize::new(0),
+            started: AtomicUsize::new(0),
+            started_changed: Notify::new(),
+            releases: Semaphore::new(0),
+            operations: Mutex::new(Vec::new()),
+        }
+    }
+}
+
+struct ActiveWrite<'a>(&'a AtomicUsize);
+
+impl Drop for ActiveWrite<'_> {
+    fn drop(&mut self) {
+        self.0.fetch_sub(1, Ordering::AcqRel);
+    }
+}
+
+impl BlockingStore {
+    async fn record(&self, request_id: &str, operation: &'static str) -> Result<(), StoreError> {
+        self.operations
+            .lock()
+            .expect("operations lock")
+            .push((request_id.to_owned(), operation));
+        let active = self.active.fetch_add(1, Ordering::AcqRel) + 1;
+        self.maximum_active.fetch_max(active, Ordering::AcqRel);
+        let _active = ActiveWrite(&self.active);
+        self.started.fetch_add(1, Ordering::AcqRel);
+        self.started_changed.notify_waiters();
+        self.releases
+            .acquire()
+            .await
+            .expect("release semaphore")
+            .forget();
+        Ok(())
+    }
+
+    async fn wait_for_started(&self, expected: usize) {
+        tokio::time::timeout(Duration::from_secs(1), async {
+            loop {
+                let changed = self.started_changed.notified();
+                if self.started.load(Ordering::Acquire) >= expected {
+                    break;
+                }
+                changed.await;
+            }
+        })
+        .await
+        .expect("expected writes should start");
+    }
+
+    fn operations_for(&self, request_id: &str) -> Vec<&'static str> {
+        self.operations
+            .lock()
+            .expect("operations lock")
+            .iter()
+            .filter_map(|(candidate, operation)| (candidate == request_id).then_some(*operation))
+            .collect()
+    }
+}
+
+#[async_trait]
+impl ExecutionStore for BlockingStore {
+    async fn create_model_request(&self, request: NewModelRequest) -> Result<(), StoreError> {
+        self.record(request.id.as_str(), "create").await
+    }
+
+    async fn record_attempt(&self, attempt: AttemptRecord) -> Result<(), StoreError> {
+        self.record(attempt.request_id.as_str(), "attempt").await
+    }
+
+    async fn mark_send_state(
+        &self,
+        request_id: &ModelRequestId,
+        _: UpstreamSendState,
+    ) -> Result<(), StoreError> {
+        self.record(request_id.as_str(), "send").await
+    }
+
+    async fn mark_downstream_committed(
+        &self,
+        request_id: &ModelRequestId,
+        _: SystemTime,
+        _: Option<u16>,
+    ) -> Result<(), StoreError> {
+        self.record(request_id.as_str(), "commit").await
+    }
+
+    async fn record_client_status(
+        &self,
+        request_id: &ModelRequestId,
+        _: u16,
+    ) -> Result<(), StoreError> {
+        self.record(request_id.as_str(), "status").await
+    }
+
+    async fn record_intermediate_failure(
+        &self,
+        failure: IntermediateFailure,
+    ) -> Result<(), StoreError> {
+        self.record(failure.request_id.as_str(), "intermediate_failure")
+            .await
+    }
+
+    async fn record_probe_failure(&self, _: ProbeFailure) -> Result<(), StoreError> {
+        self.record("probe", "probe_failure").await
+    }
+
+    async fn finalize_model_request(
+        &self,
+        finalization: ModelRequestFinalization,
+    ) -> Result<(), StoreError> {
+        self.record(finalization.request_id.as_str(), "finalize")
+            .await
+    }
+
+    async fn recover_expired(&self, _: SystemTime) -> Result<RecoveryReport, StoreError> {
+        Ok(RecoveryReport::default())
+    }
+}
+
 #[tokio::test]
 async fn full_observation_queue_never_waits_for_the_database() {
     let inner = Arc::new(RecordingStore::default());
@@ -178,6 +313,185 @@ async fn observation_writer_persists_commands_in_enqueue_order() {
     assert_eq!(store.stats().queued_items, 0);
 }
 
+#[tokio::test]
+async fn request_affine_lanes_run_independently_and_preserve_each_request_order() {
+    let inner = Arc::new(BlockingStore::default());
+    let (store, writer) = BufferedExecutionStore::with_capacity(
+        Arc::clone(&inner),
+        NonZeroUsize::new(4).expect("capacity"),
+    );
+    let first = ModelRequestId::new("req_lane_0").expect("first request id");
+    let second = ModelRequestId::new("req_lane_1").expect("second request id");
+    for request_id in [&first, &second] {
+        store
+            .mark_send_state(request_id, UpstreamSendState::Sent)
+            .await
+            .expect("enqueue send state");
+        store
+            .record_client_status(request_id, 200)
+            .await
+            .expect("enqueue status");
+    }
+
+    let cancellation = CancellationToken::new();
+    let writer = Arc::new(writer);
+    let task = tokio::spawn({
+        let writer = Arc::clone(&writer);
+        let cancellation = cancellation.clone();
+        async move { writer.run(cancellation).await }
+    });
+    inner.wait_for_started(2).await;
+    assert_eq!(inner.maximum_active.load(Ordering::Acquire), 2);
+    assert_eq!(inner.operations_for(first.as_str()), ["send"]);
+    assert_eq!(inner.operations_for(second.as_str()), ["send"]);
+
+    inner.releases.add_permits(2);
+    inner.wait_for_started(4).await;
+    inner.releases.add_permits(2);
+    tokio::time::timeout(Duration::from_secs(1), async {
+        while store.stats().persisted_total != 4 {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .expect("all writes should persist");
+    cancellation.cancel();
+    task.await
+        .expect("writer task")
+        .expect("writer cancellation");
+
+    assert_eq!(inner.operations_for(first.as_str()), ["send", "status"]);
+    assert_eq!(inner.operations_for(second.as_str()), ["send", "status"]);
+    assert_eq!(store.stats().dropped_total, 0);
+    assert_eq!(store.stats().queued_items, 0);
+}
+
+#[tokio::test]
+async fn idle_wait_includes_a_dequeued_write_until_persistence_finishes() {
+    let inner = Arc::new(BlockingStore::default());
+    let (store, writer) = BufferedExecutionStore::with_capacity(
+        Arc::clone(&inner),
+        NonZeroUsize::new(1).expect("capacity"),
+    );
+    let request_id = ModelRequestId::new("req_idle_inflight").expect("request id");
+    store
+        .mark_send_state(&request_id, UpstreamSendState::Sent)
+        .await
+        .expect("enqueue write");
+    let cancellation = CancellationToken::new();
+    let writer = Arc::new(writer);
+    let task = tokio::spawn({
+        let writer = Arc::clone(&writer);
+        let cancellation = cancellation.clone();
+        async move { writer.run(cancellation).await }
+    });
+    inner.wait_for_started(1).await;
+
+    let idle = writer.wait_until_idle(Instant::now() + Duration::from_secs(1));
+    tokio::pin!(idle);
+    assert!(
+        tokio::time::timeout(Duration::from_millis(20), &mut idle)
+            .await
+            .is_err(),
+        "从队列取出的写入仍应计入 drain"
+    );
+    inner.releases.add_permits(1);
+    assert!(idle.await);
+
+    cancellation.cancel();
+    task.await
+        .expect("writer task")
+        .expect("writer cancellation");
+    assert_eq!(store.stats().persisted_total, 1);
+    assert_eq!(store.stats().queued_items, 0);
+}
+
+#[tokio::test]
+async fn global_item_budget_includes_writes_running_in_every_lane() {
+    let inner = Arc::new(BlockingStore::default());
+    let (store, writer) = BufferedExecutionStore::with_capacity(
+        Arc::clone(&inner),
+        NonZeroUsize::new(2).expect("capacity"),
+    );
+    let first = ModelRequestId::new("req_lane_0").expect("first request id");
+    let second = ModelRequestId::new("req_lane_1").expect("second request id");
+    let rejected = ModelRequestId::new("req_lane_2").expect("rejected request id");
+    store
+        .mark_send_state(&first, UpstreamSendState::Sent)
+        .await
+        .expect("enqueue first lane");
+    store
+        .mark_send_state(&second, UpstreamSendState::Sent)
+        .await
+        .expect("enqueue second lane");
+
+    let cancellation = CancellationToken::new();
+    let writer = Arc::new(writer);
+    let task = tokio::spawn({
+        let writer = Arc::clone(&writer);
+        let cancellation = cancellation.clone();
+        async move { writer.run(cancellation).await }
+    });
+    inner.wait_for_started(2).await;
+    assert_eq!(store.stats().queued_items, 2);
+    store
+        .mark_send_state(&rejected, UpstreamSendState::Sent)
+        .await
+        .expect("full global budget remains fail open");
+    assert_eq!(store.stats().dropped_total, 1);
+    assert_eq!(store.stats().queued_items, 2);
+
+    inner.releases.add_permits(2);
+    tokio::time::timeout(Duration::from_secs(1), async {
+        while store.stats().persisted_total != 2 {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .expect("accepted writes should persist");
+    cancellation.cancel();
+    task.await
+        .expect("writer task")
+        .expect("writer cancellation");
+    assert_eq!(store.stats().queued_items, 0);
+}
+
+#[tokio::test]
+async fn all_lanes_share_one_shutdown_deadline_for_inflight_writes() {
+    let inner = Arc::new(BlockingStore::default());
+    let (store, writer) = BufferedExecutionStore::with_capacity(
+        Arc::clone(&inner),
+        NonZeroUsize::new(4).expect("capacity"),
+    );
+    for index in 0..4 {
+        let request_id = ModelRequestId::new(format!("req_lane_{index}"))
+            .expect("request id assigned to a distinct lane");
+        store
+            .mark_send_state(&request_id, UpstreamSendState::Sent)
+            .await
+            .expect("enqueue lane write");
+    }
+
+    let cancellation = CancellationToken::new();
+    let writer = Arc::new(writer);
+    let task = tokio::spawn({
+        let writer = Arc::clone(&writer);
+        let cancellation = cancellation.clone();
+        async move { writer.run(cancellation).await }
+    });
+    inner.wait_for_started(4).await;
+    cancellation.cancel();
+    tokio::time::timeout(Duration::from_secs(3), task)
+        .await
+        .expect("four blocked lanes must share the two-second shutdown deadline")
+        .expect("writer task")
+        .expect("writer cancellation");
+
+    assert_eq!(store.stats().persisted_total, 0);
+    assert_eq!(store.stats().dropped_total, 4);
+    assert_eq!(store.stats().queued_items, 0);
+}
+
 #[tokio::test]
 async fn observation_writer_continues_after_a_database_write_failure() {
     let inner = Arc::new(RecordingStore::failing_once("send"));
@@ -331,6 +645,66 @@ async fn zero_attempt_create_and_finalize_drain_in_order_with_trace() {
     database.close().await;
 }
 
+#[tokio::test]
+async fn request_affine_lanes_persist_a_postgres_lifecycle_burst_without_orphans() {
+    const REQUESTS: usize = 256;
+    const WRITES: u64 = (REQUESTS * 2) as u64;
+
+    let Some(database) = TestDatabase::create("execution_lane_burst").await else {
+        return;
+    };
+    let (store, writer) =
+        BufferedExecutionStore::new(Arc::new(PgExecutionStore::new(database.pool.clone())));
+    for index in 0..REQUESTS {
+        let request = accepted_request(&format!("req_execution_lane_burst_{index}"));
+        store
+            .create_model_request(request.clone())
+            .await
+            .expect("enqueue create");
+        store
+            .finalize_model_request(early_failure(&request))
+            .await
+            .expect("enqueue finalization");
+    }
+    assert_eq!(store.stats().enqueued_total, WRITES);
+    assert_eq!(store.stats().dropped_total, 0);
+
+    let cancellation = CancellationToken::new();
+    let writer = Arc::new(writer);
+    let task = tokio::spawn({
+        let writer = Arc::clone(&writer);
+        let cancellation = cancellation.clone();
+        async move { writer.run(cancellation).await }
+    });
+    tokio::time::timeout(Duration::from_secs(15), async {
+        while store.stats().persisted_total != WRITES {
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .expect("PostgreSQL burst should drain");
+    cancellation.cancel();
+    task.await
+        .expect("writer task")
+        .expect("writer cancellation");
+
+    let (total, failed): (i64, i64) = sqlx::query_as(
+        "select count(*), count(*) filter (where outcome = 'failed')
+         from model_requests where id like 'req_execution_lane_burst_%'",
+    )
+    .fetch_one(&database.pool)
+    .await
+    .expect("load burst rows");
+    assert_eq!((total, failed), (REQUESTS as i64, REQUESTS as i64));
+    let stats = store.stats();
+    assert_eq!(stats.persisted_total, WRITES);
+    assert_eq!(stats.write_failure_total, 0);
+    assert_eq!(stats.dropped_total, 0);
+    assert_eq!(stats.queued_items, 0);
+    assert_eq!(stats.queued_bytes, 0);
+    database.close().await;
+}
+
 #[tokio::test]
 async fn zero_attempt_dropped_finalize_is_fail_open_and_recoverable_at_deadline() {
     let Some(database) = TestDatabase::create("zero_attempt_queue_full").await else {
diff --git a/backend/crates/gateway-store/tests/postgres/mod.rs b/backend/crates/gateway-store/tests/postgres/mod.rs
index f9fca9e88..e49a9e2d5 100644
--- a/backend/crates/gateway-store/tests/postgres/mod.rs
+++ b/backend/crates/gateway-store/tests/postgres/mod.rs
@@ -21,6 +21,7 @@ mod execution_buffer;
 mod health;
 mod observability;
 mod ops_events;
+mod plugins;
 mod pricing;
 mod provider_accounts;
 mod proxies;
@@ -58,6 +59,10 @@ pub(super) fn admin_account_store(pool: &PgPool) -> PgAdminAccountStore {
 
 impl TestDatabase {
     pub(super) async fn create(label: &str) -> Option<Self> {
+        Self::create_through(label, i64::MAX).await
+    }
+
+    pub(super) async fn create_through(label: &str, migration_version: i64) -> Option<Self> {
         let database_url = crate::support::test_env("CPR_TEST_DATABASE_URL")?;
         let schema = format!("cpr_store_{label}_{}", Uuid::new_v4().simple());
         let admin = PgPoolOptions::new()
@@ -86,7 +91,7 @@ impl TestDatabase {
             .await
             .expect("connect isolated test schema");
         TEST_MIGRATOR
-            .run(&pool)
+            .run_to(migration_version, &pool)
             .await
             .expect("apply test migrations");
         Some(Self {
@@ -229,6 +234,7 @@ async fn connect_and_migrate_should_apply_all_migrations_once_and_reopen_cleanly
             "account_groups",
             "admin_audit_events",
             "admin_users",
+            "authorization_receipts",
             "backup_records",
             "backup_settings",
             "client_api_key_groups",
@@ -238,6 +244,15 @@ async fn connect_and_migrate_should_apply_all_migrations_once_and_reopen_cleanly
             "model_requests",
             "ops_events",
             "outbound_proxies",
+            "plugin_artifact_credentials",
+            "plugin_artifact_platforms",
+            "plugin_artifacts",
+            "plugin_instance_secrets",
+            "plugin_instances",
+            "plugin_source_credentials",
+            "plugin_state_generations",
+            "plugin_state_records",
+            "plugin_update_sources",
             "provider_accounts",
             "runtime_settings",
         ]
diff --git a/backend/crates/gateway-store/tests/postgres/observability/mod.rs b/backend/crates/gateway-store/tests/postgres/observability/mod.rs
index 8e4acc71e..b2c1a5c3e 100644
--- a/backend/crates/gateway-store/tests/postgres/observability/mod.rs
+++ b/backend/crates/gateway-store/tests/postgres/observability/mod.rs
@@ -35,6 +35,54 @@ fn observability_range_rejects_empty_window() {
     assert!(ObservabilityRange::new(now, now).is_err());
 }
 
+#[tokio::test]
+async fn usage_provider_filters_preserve_deleted_accounts_and_late_errors_within_range() {
+    let Some(database) = TestDatabase::create("usage_provider_filters").await else {
+        return;
+    };
+    let now = Utc::now();
+    seed_observability_facts(&database.pool, now).await.unwrap();
+    sqlx::query("update model_requests set provider_kind = 'outside-range', started_at = $1 - interval '3 hours', completed_at = $1 - interval '2 hours'")
+        .bind(now).execute(&database.pool).await.unwrap();
+    sqlx::query("update model_requests set provider_kind = 'retired-plugin', started_at = $1 - interval '5 minutes', completed_at = $1 - interval '4 minutes' where id = 'req_observe_success'")
+        .bind(now).execute(&database.pool).await.unwrap();
+    sqlx::query("update model_requests set provider_kind = 'late-error', completed_at = $1 - interval '3 minutes' where id = 'req_observe_failed'")
+        .bind(now).execute(&database.pool).await.unwrap();
+    sqlx::query("update model_requests set provider_kind = 'end-boundary', started_at = $1, completed_at = $1 where id = 'req_observe_uncommitted'")
+        .bind(now).execute(&database.pool).await.unwrap();
+    sqlx::query(
+        "update ops_events set provider_kind = 'ops-only', created_at = $1 - interval '2 minutes'",
+    )
+    .bind(now)
+    .execute(&database.pool)
+    .await
+    .unwrap();
+    sqlx::query("delete from provider_accounts")
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    let store = admin_observability_store(&database.pool);
+    let providers = store
+        .usage_provider_kinds(
+            admin_observability::TimeRange::new(now - TimeDelta::hours(1), now).unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(providers, ["late-error", "ops-only", "retired-plugin"]);
+    let empty = store
+        .usage_provider_kinds(
+            admin_observability::TimeRange::new(
+                now + TimeDelta::hours(1),
+                now + TimeDelta::hours(2),
+            )
+            .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert!(empty.is_empty());
+    database.close().await;
+}
+
 #[test]
 fn observability_range_accepts_full_configured_retention_window() {
     let now = Utc::now();
diff --git a/backend/crates/gateway-store/tests/postgres/plugins/artifacts.rs b/backend/crates/gateway-store/tests/postgres/plugins/artifacts.rs
new file mode 100644
index 000000000..c585b2422
--- /dev/null
+++ b/backend/crates/gateway-store/tests/postgres/plugins/artifacts.rs
@@ -0,0 +1,456 @@
+use std::collections::BTreeMap;
+
+use gateway_admin::{
+    model::{
+        MutationActor, MutationContext,
+        plugins::{
+            InspectedPluginArtifact, PluginArtifactMetadata, PluginContribution, PluginSource,
+            distribution::{PluginSourceBinding, PluginUpdateSource},
+        },
+    },
+    ports::{plugins::PluginStore, store::AdminStoreErrorKind},
+};
+use gateway_store::postgres::PgPluginStore;
+
+use super::super::TestDatabase;
+
+pub(super) fn artifact(digest: char, platforms: &[&str]) -> InspectedPluginArtifact {
+    InspectedPluginArtifact {
+        metadata: PluginArtifactMetadata {
+            plugin_id: "test.example".into(),
+            version: "1.0.0".into(),
+            name: "example".into(),
+            display_name: "Example".into(),
+            publisher: "test".into(),
+            author: Some("Tests".into()),
+            description: "测试包".into(),
+            license: "MIT".into(),
+            sha256: digest.to_string().repeat(64),
+            platforms: platforms.iter().map(|value| (*value).into()).collect(),
+            icon: None,
+            contributes: BTreeMap::from([(
+                "middleware".into(),
+                PluginContribution {
+                    id: "test.example.middleware".into(),
+                    version: 1,
+                    stages: vec!["attempt".into()],
+                    input_formats: vec!["openai".into()],
+                    output_formats: vec!["openai".into()],
+                },
+            )]),
+            requested_permissions: vec![],
+            configuration_schema: serde_json::json!({}),
+            secret_fields: vec![],
+            state_namespaces: vec![],
+        },
+        archive: b"verified package fixture".as_slice().into(),
+    }
+}
+
+pub(super) fn context() -> MutationContext {
+    MutationContext {
+        actor: MutationActor::System,
+        request_id: "plugin-test".into(),
+    }
+}
+
+pub(super) async fn initialize_revision(database: &TestDatabase) {
+    sqlx::query(
+        "insert into runtime_settings(id, config_revision, updated_at) values (1,1,now()) on conflict do nothing",
+    )
+    .execute(&database.pool)
+    .await
+    .unwrap();
+}
+
+#[tokio::test]
+async fn presentation_text_is_not_persisted_and_legacy_text_does_not_change_artifact_identity() {
+    let Some(database) = TestDatabase::create("plugin_artifact_presentation").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let fixture = artifact('a', &["linux-x86_64"]);
+    let installed = store
+        .install_artifact(fixture.clone(), PluginSource::Upload, &context())
+        .await
+        .unwrap();
+    let stored: serde_json::Value =
+        sqlx::query_scalar("select metadata_json from plugin_artifacts where sha256=$1")
+            .bind(&fixture.metadata.sha256)
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert!(stored.get("permissionDescriptions").is_none());
+    sqlx::query("update plugin_artifacts set metadata_json=metadata_json || $2 where sha256=$1")
+        .bind(&fixture.metadata.sha256)
+        .bind(serde_json::json!({"permissionDescriptions": [{"permission": "models", "label": "旧文案", "description": "旧说明"}]}))
+        .execute(&database.pool).await.unwrap();
+    let repeated = store
+        .install_artifact(fixture.clone(), PluginSource::Upload, &context())
+        .await
+        .unwrap();
+    assert_eq!(repeated.config_revision, installed.config_revision);
+    assert_eq!(repeated.artifact.metadata, fixture.metadata);
+    assert_eq!(
+        store
+            .load_artifact(&fixture.metadata.sha256)
+            .await
+            .unwrap()
+            .metadata,
+        fixture.metadata
+    );
+    let mut changed = fixture;
+    changed.metadata.requested_permissions.push("models".into());
+    assert_eq!(
+        store
+            .install_artifact(changed, PluginSource::Upload, &context())
+            .await
+            .err()
+            .unwrap()
+            .kind(),
+        AdminStoreErrorKind::Conflict
+    );
+    database.close().await;
+}
+
+#[tokio::test]
+async fn artifact_acceptance_is_exact_and_idempotent() {
+    let Some(database) = TestDatabase::create("plugin_artifact_acceptance").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let installed = store
+        .install_artifact(
+            artifact('a', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    assert!(installed.artifact.accepted_at.is_none());
+
+    let accepted = store
+        .accept_artifact(&installed.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    let repeated = store
+        .accept_artifact(&installed.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    assert!(accepted.artifact.accepted_at.is_some());
+    assert_eq!(repeated.artifact, accepted.artifact);
+    assert_eq!(repeated.config_revision, accepted.config_revision);
+    let accept_audits: i64 = sqlx::query_scalar(
+        "select count(*) from admin_audit_events where entity_kind='plugin_artifact' and action='accept'",
+    )
+    .fetch_one(&database.pool)
+    .await
+    .unwrap();
+    assert_eq!(accept_audits, 1);
+    database.close().await;
+}
+
+#[tokio::test]
+async fn plugin_migration_preserves_main_settings_and_accepts_new_installations() {
+    let Some(database) = TestDatabase::create_through("plugin_upgrade_from_main", 17).await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    sqlx::query("update runtime_settings set max_concurrent_per_account=0 where id=1")
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    let before: serde_json::Value =
+        sqlx::query_scalar("select to_jsonb(s) from runtime_settings s where id=1")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    super::super::TEST_MIGRATOR
+        .run(&database.pool)
+        .await
+        .unwrap();
+    let after: serde_json::Value =
+        sqlx::query_scalar("select to_jsonb(s) from runtime_settings s where id=1")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert_eq!(after, before);
+    let store = PgPluginStore::new(database.pool.clone());
+    store
+        .install_artifact(
+            artifact('a', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    database.close().await;
+}
+
+#[tokio::test]
+async fn source_identity_requires_publisher_and_name() {
+    let Some(database) = TestDatabase::create("plugin_source_identity").await else {
+        return;
+    };
+    for plugin_id in [
+        "legacy-plugin",
+        "Publisher.name",
+        "publisher.-name",
+        "publisher.name.extra",
+    ] {
+        let error = sqlx::query(
+            "insert into plugin_update_sources(plugin_id,source_json) values ($1,'{}')",
+        )
+        .bind(plugin_id)
+        .execute(&database.pool)
+        .await
+        .expect_err("invalid identity must be rejected by the owning table");
+        assert_eq!(
+            error.as_database_error().unwrap().code().as_deref(),
+            Some("23514")
+        );
+    }
+    database.close().await;
+}
+
+#[tokio::test]
+async fn artifact_bytes_and_audit_survive_repository_recreation() {
+    let Some(database) = TestDatabase::create("plugin_recovery").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let expected = artifact('a', &["linux-x86_64"]);
+    let saved = store
+        .install_artifact(expected.clone(), PluginSource::Upload, &context())
+        .await
+        .unwrap();
+    assert_eq!(saved.config_revision.get(), 2);
+    drop(store);
+    let reopened = PgPluginStore::new(database.pool.clone());
+    let recovered = reopened
+        .load_artifact(&expected.metadata.sha256)
+        .await
+        .unwrap();
+    assert_eq!(recovered.archive, expected.archive);
+    assert_eq!(recovered.metadata, expected.metadata);
+    let audit: (String, i64, Vec<String>) = sqlx::query_as("select action, config_revision, changed_fields from admin_audit_events where entity_kind='plugin_artifact'").fetch_one(&database.pool).await.unwrap();
+    assert_eq!(
+        audit,
+        (
+            "install".into(),
+            2,
+            vec!["artifact".into(), "source".into()]
+        )
+    );
+    database.close().await;
+}
+
+#[tokio::test]
+async fn overlapping_platform_content_cannot_replace_a_published_version() {
+    let Some(database) = TestDatabase::create("plugin_immutable").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    store
+        .install_artifact(
+            artifact('a', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    let result = store
+        .install_artifact(
+            artifact('b', &["linux-x86_64", "windows-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await;
+    assert!(result.is_err_and(|error| error.kind() == AdminStoreErrorKind::Conflict));
+    assert_eq!(store.list_artifacts().await.unwrap().len(), 1);
+    let revision: i64 =
+        sqlx::query_scalar("select config_revision from runtime_settings where id=1")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert_eq!(revision, 2, "冲突必须回滚全局 revision");
+    database.close().await;
+}
+
+#[tokio::test]
+async fn unchanged_official_package_survives_host_upgrade_and_rollback() {
+    let Some(database) = TestDatabase::create("plugin_builtin_reimport").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let package = artifact('a', &["linux-x86_64"]);
+    let saved = store
+        .install_artifact(
+            package.clone(),
+            PluginSource::Builtin {
+                release: "3.12.0".into(),
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    for release in ["3.13.0", "3.12.0", "3.11.0"] {
+        let imported = store
+            .install_artifact(
+                package.clone(),
+                PluginSource::Builtin {
+                    release: release.into(),
+                },
+                &context(),
+            )
+            .await
+            .expect("同一个官方包可随不同宿主发行重复导入");
+        assert_eq!(imported.config_revision, saved.config_revision);
+        assert_eq!(imported.artifact, saved.artifact, "保留首次安装来源与时间");
+    }
+    let audit_count: i64 = sqlx::query_scalar(
+        "select count(*) from admin_audit_events where entity_kind='plugin_artifact'",
+    )
+    .fetch_one(&database.pool)
+    .await
+    .unwrap();
+    assert_eq!(audit_count, 1, "幂等导入不制造配置变更与重复安装审计");
+    database.close().await;
+}
+
+#[tokio::test]
+async fn official_reimport_still_rejects_changed_metadata_and_custom_source() {
+    let Some(database) = TestDatabase::create("plugin_builtin_identity").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let source = PluginSource::Builtin {
+        release: "3.12.0".into(),
+    };
+    let package = artifact('a', &["linux-x86_64"]);
+    let saved = store
+        .install_artifact(package.clone(), source.clone(), &context())
+        .await
+        .unwrap();
+    let mut changed = package.clone();
+    changed.metadata.display_name = "Changed metadata".into();
+    for (candidate, source) in [(changed, source), (package, PluginSource::Upload)] {
+        assert!(
+            store
+                .install_artifact(candidate, source, &context())
+                .await
+                .is_err_and(|error| error.kind() == AdminStoreErrorKind::Conflict)
+        );
+    }
+    assert_eq!(store.list_artifacts().await.unwrap(), vec![saved.artifact]);
+    let revision: i64 =
+        sqlx::query_scalar("select config_revision from runtime_settings where id=1")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert_eq!(revision, 2);
+    database.close().await;
+}
+
+#[tokio::test]
+async fn changing_update_binding_does_not_relabel_custom_package_as_official() {
+    let Some(database) = TestDatabase::create("plugin_builtin_provenance").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let package = artifact('a', &["linux-x86_64"]);
+    let saved = store
+        .install_artifact(package.clone(), PluginSource::Upload, &context())
+        .await
+        .unwrap();
+    let changed_revision = store
+        .change_update_source(
+            PluginSourceBinding {
+                plugin_id: package.metadata.plugin_id.clone(),
+                source: PluginUpdateSource::Builtin,
+                policy: Default::default(),
+                outbound_proxy_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    assert!(
+        store
+            .install_artifact(
+                package,
+                PluginSource::Builtin {
+                    release: "3.13.0".into(),
+                },
+                &context(),
+            )
+            .await
+            .is_err_and(|error| error.kind() == AdminStoreErrorKind::Conflict)
+    );
+    assert_eq!(store.list_artifacts().await.unwrap(), vec![saved.artifact]);
+    let revision: i64 =
+        sqlx::query_scalar("select config_revision from runtime_settings where id=1")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert_eq!(u64::try_from(revision).unwrap(), changed_revision.get());
+    database.close().await;
+}
+
+#[tokio::test]
+async fn authorized_source_change_reuses_identical_package_without_rewriting_provenance() {
+    let Some(database) = TestDatabase::create("plugin_reinstall_source").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let package = artifact('a', &["linux-x86_64"]);
+    let saved = store
+        .install_artifact(package.clone(), PluginSource::Upload, &context())
+        .await
+        .unwrap();
+    let source = PluginSource::Url {
+        url: "https://example.com/plugin.tar.gz".into(),
+        credential_ids: vec![],
+        outbound_proxy: None,
+    };
+    assert!(
+        store
+            .install_artifact(package.clone(), source.clone(), &context())
+            .await
+            .is_err_and(|error| error.kind() == AdminStoreErrorKind::Conflict),
+        "未经管理员确认的来源仍需拒绝"
+    );
+    let revision = store
+        .change_update_source(
+            PluginSourceBinding {
+                plugin_id: package.metadata.plugin_id.clone(),
+                source: PluginUpdateSource::Url {
+                    url: "https://example.com/plugin.tar.gz".into(),
+                },
+                policy: Default::default(),
+                outbound_proxy_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    let repeated = store
+        .install_artifact(package, source, &context())
+        .await
+        .unwrap();
+    assert_eq!(repeated.artifact, saved.artifact, "保留首次安装来源和时间");
+    assert_eq!(
+        repeated.config_revision, revision,
+        "相同包不产生额外版本变更"
+    );
+    assert_eq!(store.list_artifacts().await.unwrap().len(), 1);
+    database.close().await;
+}
diff --git a/backend/crates/gateway-store/tests/postgres/plugins/credentials.rs b/backend/crates/gateway-store/tests/postgres/plugins/credentials.rs
new file mode 100644
index 000000000..b97129ba2
--- /dev/null
+++ b/backend/crates/gateway-store/tests/postgres/plugins/credentials.rs
@@ -0,0 +1,256 @@
+use gateway_admin::{
+    model::plugins::{
+        PluginSource,
+        distribution::{
+            DownloadPurpose, SourceAuthentication, SourceCredential, SourceCredentialInfo,
+        },
+    },
+    ports::{plugins::PluginStore, store::AdminStoreErrorKind},
+};
+use gateway_store::postgres::PgPluginStore;
+use secrecy::ExposeSecret as _;
+
+use super::{
+    super::TestDatabase,
+    artifacts::{artifact, context, initialize_revision},
+};
+
+#[tokio::test]
+async fn download_secrets_survive_recovery_without_entering_lists_or_audit_and_references_block_deletion()
+ {
+    let Some(database) = TestDatabase::create("plugin_credentials").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let id = uuid::Uuid::now_v7().to_string();
+    let info = SourceCredentialInfo {
+        id: id.clone(),
+        name: "Test GitHub".into(),
+        origin: "https://api.github.com".into(),
+        path_prefix: "/repos/example/plugin".into(),
+        purposes: vec![DownloadPurpose::Metadata, DownloadPurpose::Artifact],
+    };
+    store
+        .save_source_credential(
+            SourceCredential {
+                info: info.clone(),
+                authentication: SourceAuthentication::Github {
+                    token: "fixture-sensitive-value".into(),
+                },
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    let listed = store.list_source_credentials().await.unwrap();
+    assert_eq!(listed, vec![info]);
+    assert!(
+        !serde_json::to_string(&listed)
+            .unwrap()
+            .contains("fixture-sensitive-value")
+    );
+    drop(store);
+    let store = PgPluginStore::new(database.pool.clone());
+    let recovered = store.load_source_credential(&id).await.unwrap();
+    let SourceAuthentication::Github { token } = recovered.authentication else {
+        panic!("wrong authentication type")
+    };
+    assert_eq!(token.expose_secret(), "fixture-sensitive-value");
+    let saved = store
+        .install_artifact(
+            artifact('c', &["linux-x86_64"]),
+            PluginSource::Github {
+                repository: "example/plugin".into(),
+                tag: "v1.0.0".into(),
+                asset: "plugin.tar.gz".into(),
+                credential_ids: vec![id.clone()],
+                outbound_proxy: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        store
+            .delete_source_credential(&id, &context())
+            .await
+            .unwrap_err()
+            .kind(),
+        AdminStoreErrorKind::Conflict
+    );
+    let audit: Vec<String> =
+        sqlx::query_scalar("select row_to_json(events)::text from admin_audit_events events")
+            .fetch_all(&database.pool)
+            .await
+            .unwrap();
+    assert!(
+        audit
+            .iter()
+            .all(|event| !event.contains("fixture-sensitive-value"))
+    );
+    store
+        .delete_artifact(&saved.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    assert!(store.list_source_credentials().await.unwrap().is_empty());
+    assert!(store.list_update_sources().await.unwrap().is_empty());
+    assert!(matches!(
+        store.load_source_credential(&id).await,
+        Err(error) if error.kind() == AdminStoreErrorKind::NotFound
+    ));
+    database.close().await;
+}
+
+fn credential(id: &str) -> SourceCredential {
+    SourceCredential {
+        info: SourceCredentialInfo {
+            id: id.into(),
+            name: "Cleanup fixture".into(),
+            origin: "https://downloads.example.com".into(),
+            path_prefix: "/".into(),
+            purposes: vec![DownloadPurpose::Artifact],
+        },
+        authentication: SourceAuthentication::Bearer {
+            token: "cleanup-fixture-secret".into(),
+        },
+    }
+}
+
+fn source(ids: &[&str]) -> PluginSource {
+    PluginSource::Url {
+        url: "https://downloads.example.com/plugin.tar.gz".into(),
+        credential_ids: ids.iter().map(|id| (*id).into()).collect(),
+        outbound_proxy: None,
+    }
+}
+
+#[tokio::test]
+async fn deletion_cleans_exclusive_credentials_but_preserves_shared_and_unrelated_ones() {
+    let Some(database) = TestDatabase::create("plugin_credential_cleanup").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let exclusive = uuid::Uuid::now_v7().to_string();
+    let shared = uuid::Uuid::now_v7().to_string();
+    let unrelated = uuid::Uuid::now_v7().to_string();
+    for id in [&exclusive, &shared, &unrelated] {
+        store
+            .save_source_credential(credential(id), &context())
+            .await
+            .unwrap();
+    }
+    let first = artifact('a', &["linux-x86_64"]);
+    store
+        .install_artifact(first.clone(), source(&[&exclusive, &shared]), &context())
+        .await
+        .unwrap();
+    let mut second = artifact('b', &["linux-x86_64"]);
+    second.metadata.plugin_id = "test.other".into();
+    second.metadata.name = "other".into();
+    store
+        .install_artifact(second.clone(), source(&[&shared]), &context())
+        .await
+        .unwrap();
+
+    let revision = store
+        .delete_artifact(&first.metadata.sha256, &context())
+        .await
+        .unwrap();
+    let remaining = store.list_source_credentials().await.unwrap();
+    assert_eq!(
+        remaining
+            .iter()
+            .map(|info| info.id.as_str())
+            .collect::<Vec<_>>(),
+        [&shared, &unrelated]
+    );
+    assert_eq!(
+        store.list_update_sources().await.unwrap()[0].plugin_id,
+        "test.other"
+    );
+    let audits: Vec<(String, i64)> = sqlx::query_as(
+        "select entity_kind,config_revision from admin_audit_events where action='delete' order by entity_kind",
+    ).fetch_all(&database.pool).await.unwrap();
+    let revision = i64::try_from(revision.get()).unwrap();
+    assert_eq!(
+        audits,
+        vec![
+            ("plugin_artifact".into(), revision),
+            ("plugin_source".into(), revision),
+            ("plugin_source_credential".into(), revision),
+        ]
+    );
+
+    store
+        .delete_artifact(&second.metadata.sha256, &context())
+        .await
+        .unwrap();
+    assert_eq!(
+        store.list_source_credentials().await.unwrap(),
+        vec![credential(&unrelated).info]
+    );
+    assert!(store.list_update_sources().await.unwrap().is_empty());
+    database.close().await;
+}
+
+#[tokio::test]
+async fn cleanup_failure_rolls_back_artifact_source_credentials_revision_and_audit() {
+    let Some(database) = TestDatabase::create("plugin_cleanup_atomic").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let id = uuid::Uuid::now_v7().to_string();
+    store
+        .save_source_credential(credential(&id), &context())
+        .await
+        .unwrap();
+    let installed = store
+        .install_artifact(artifact('c', &["linux-x86_64"]), source(&[&id]), &context())
+        .await
+        .unwrap();
+    let before_sources = store.list_update_sources().await.unwrap();
+    sqlx::raw_sql(
+        "create function reject_credential_cleanup() returns trigger language plpgsql as $$
+         begin raise exception 'cleanup failure fixture'; end $$;
+         create trigger reject_credential_cleanup before delete on plugin_source_credentials
+         for each row execute function reject_credential_cleanup();",
+    )
+    .execute(&database.pool)
+    .await
+    .unwrap();
+
+    assert!(
+        store
+            .delete_artifact(&installed.artifact.metadata.sha256, &context())
+            .await
+            .is_err()
+    );
+    assert_eq!(
+        store.list_artifacts().await.unwrap(),
+        vec![installed.artifact]
+    );
+    assert_eq!(store.list_update_sources().await.unwrap(), before_sources);
+    assert_eq!(
+        store.list_source_credentials().await.unwrap(),
+        vec![credential(&id).info]
+    );
+    let revision: i64 =
+        sqlx::query_scalar("select config_revision from runtime_settings where id=1")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert_eq!(
+        u64::try_from(revision).unwrap(),
+        installed.config_revision.get()
+    );
+    let audits: i64 =
+        sqlx::query_scalar("select count(*) from admin_audit_events where action='delete'")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert_eq!(audits, 0);
+    database.close().await;
+}
diff --git a/backend/crates/gateway-store/tests/postgres/plugins/instances.rs b/backend/crates/gateway-store/tests/postgres/plugins/instances.rs
new file mode 100644
index 000000000..02d2394aa
--- /dev/null
+++ b/backend/crates/gateway-store/tests/postgres/plugins/instances.rs
@@ -0,0 +1,835 @@
+use std::collections::BTreeMap;
+
+use gateway_admin::{
+    model::{
+        Revision,
+        client_keys::DeleteClientKey,
+        plugins::{
+            PluginSource,
+            instances::{
+                PluginCapabilityBinding, PluginFailurePolicy, PluginFrontendIdentityBinding,
+                PluginInstance, PluginInstanceReplacement,
+            },
+            state::{PluginStateCommit, PluginStateConfiguration},
+        },
+    },
+    ports::{
+        plugins::PluginStore,
+        store::{AdminStoreErrorKind, ClientKeyStore},
+    },
+};
+use gateway_core::policy::ClientApiKeyId;
+use gateway_store::postgres::{PgAdminClientKeyStore, PgPluginStore};
+use secrecy::ExposeSecret as _;
+
+use super::{
+    super::TestDatabase,
+    artifacts::{artifact, context, initialize_revision},
+};
+
+fn instance(digest: String) -> PluginInstance {
+    PluginInstance {
+        id: uuid::Uuid::now_v7().to_string(),
+        name: "Example".into(),
+        artifact_sha256: digest,
+        enabled: false,
+        trusted_process: true,
+        configuration: serde_json::json!({"baseUrl":"https://example.com"}),
+        secrets: BTreeMap::from([("token".into(), "sensitive-fixture".into())]),
+        grants: vec![],
+        bindings: vec![],
+        revision: Revision::new(1).unwrap(),
+    }
+}
+
+#[tokio::test]
+async fn management_authorization_checks_exact_target_without_loading_secrets() {
+    use gateway_admin::model::plugins::management::PluginManagementTarget;
+    let Some(database) = TestDatabase::create("plugin_target_authorization").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let installed = store
+        .install_artifact(
+            artifact('a', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    let accepted = store
+        .accept_artifact(&installed.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    let mut candidate = instance(installed.artifact.metadata.sha256);
+    candidate.enabled = true;
+    let saved = store
+        .save_instance(candidate, accepted.config_revision, &context())
+        .await
+        .unwrap();
+    let target = PluginManagementTarget {
+        instance_id: saved.instance.id.clone(),
+        artifact_sha256: saved.instance.artifact_sha256.clone(),
+        revision: saved.instance.revision.get(),
+    };
+    // 故意留下不能解码为密钥映射的测试数据，授权查询不得读取或解释它。
+    sqlx::query("update plugin_instance_secrets set secrets_json=$2 where instance_id=$1")
+        .bind(uuid::Uuid::parse_str(&target.instance_id).unwrap())
+        .bind(serde_json::json!({"token": false}))
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    assert!(store.management_target_is_current(&target).await.unwrap());
+    for changed in [
+        PluginManagementTarget {
+            revision: target.revision + 1,
+            ..target.clone()
+        },
+        PluginManagementTarget {
+            revision: u64::MAX,
+            ..target.clone()
+        },
+        PluginManagementTarget {
+            artifact_sha256: "b".repeat(64),
+            ..target.clone()
+        },
+        PluginManagementTarget {
+            instance_id: uuid::Uuid::now_v7().to_string(),
+            ..target.clone()
+        },
+        PluginManagementTarget {
+            instance_id: "invalid".into(),
+            ..target.clone()
+        },
+    ] {
+        assert!(!store.management_target_is_current(&changed).await.unwrap());
+    }
+    sqlx::query("update plugin_instances set enabled=false where id=$1")
+        .bind(uuid::Uuid::parse_str(&target.instance_id).unwrap())
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    assert!(!store.management_target_is_current(&target).await.unwrap());
+    sqlx::query("update plugin_instances set enabled=true where id=$1")
+        .bind(uuid::Uuid::parse_str(&target.instance_id).unwrap())
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    sqlx::query("update plugin_artifacts set accepted_at=null where sha256=$1")
+        .bind(&target.artifact_sha256)
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    assert!(!store.management_target_is_current(&target).await.unwrap());
+    store
+        .delete_instance(&target.instance_id, saved.config_revision, &context())
+        .await
+        .expect_err("启用中的实例不能删除");
+    sqlx::query("update plugin_instances set enabled=false where id=$1")
+        .bind(uuid::Uuid::parse_str(&target.instance_id).unwrap())
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    store
+        .delete_instance(&target.instance_id, saved.config_revision, &context())
+        .await
+        .unwrap();
+    assert!(!store.management_target_is_current(&target).await.unwrap());
+    database.close().await;
+}
+
+fn usage_binding(client_key_id: &str, account_group_id: &str) -> PluginCapabilityBinding {
+    PluginCapabilityBinding {
+        contribution: "test.example.usage".into(),
+        stage: "observation".into(),
+        order: 0,
+        failure_policy: PluginFailurePolicy::Observe,
+        client_key_ids: vec![client_key_id.into()],
+        account_group_ids: vec![account_group_id.into()],
+        provider_ids: vec![],
+        models: vec![],
+        identity_bindings: vec![],
+    }
+}
+
+fn frontend_authentication_binding(
+    principal: &str,
+    client_key_id: &str,
+) -> PluginCapabilityBinding {
+    PluginCapabilityBinding {
+        contribution: "test.example.frontendAuthentication".into(),
+        stage: "authentication".into(),
+        order: 0,
+        failure_policy: PluginFailurePolicy::Reject,
+        client_key_ids: vec![],
+        account_group_ids: vec![],
+        provider_ids: vec![],
+        models: vec![],
+        identity_bindings: vec![PluginFrontendIdentityBinding {
+            principal: principal.into(),
+            client_key_id: client_key_id.into(),
+        }],
+    }
+}
+
+#[tokio::test]
+async fn replacement_commits_enablement_together_and_preserves_old_configuration_and_secrets() {
+    let Some(database) = TestDatabase::create("plugin_replace").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let installed = store
+        .install_artifact(
+            artifact('e', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    let accepted = store
+        .accept_artifact(&installed.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    let mut old = instance(installed.artifact.metadata.sha256.clone());
+    old.enabled = true;
+    let saved = store
+        .save_instance(old.clone(), accepted.config_revision, &context())
+        .await
+        .unwrap();
+    let mut current = instance(installed.artifact.metadata.sha256);
+    current.enabled = true;
+    let switched = store
+        .save_instance_replacing(
+            current.clone(),
+            saved.config_revision,
+            PluginStateCommit {
+                configuration: PluginStateConfiguration { namespaces: vec![] },
+                transition_id: None,
+            },
+            &[PluginInstanceReplacement {
+                id: old.id.clone(),
+                expected_revision: saved.instance.revision.get(),
+            }],
+            &context(),
+        )
+        .await
+        .unwrap();
+    let snapshot = store.load_instances().await.unwrap();
+    assert_eq!(snapshot.config_revision, switched.config_revision);
+    let previous = snapshot
+        .instances
+        .iter()
+        .find(|item| item.id == old.id)
+        .unwrap();
+    let target = snapshot
+        .instances
+        .iter()
+        .find(|item| item.id == current.id)
+        .unwrap();
+    assert!(!previous.enabled);
+    assert!(target.enabled);
+    assert_eq!(previous.revision, target.revision);
+    assert_eq!(previous.configuration, old.configuration);
+    assert_eq!(
+        previous.secrets["token"].expose_secret(),
+        old.secrets["token"].expose_secret()
+    );
+    let audits: i64 =
+        sqlx::query_scalar("select count(*) from admin_audit_events where config_revision=$1")
+            .bind(i64::try_from(switched.config_revision.get()).unwrap())
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert_eq!(audits, 2);
+    database.close().await;
+}
+
+#[tokio::test]
+async fn replacement_rolls_back_all_writes_when_a_confirmed_configuration_has_changed() {
+    let Some(database) = TestDatabase::create("plugin_replace_stale").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let installed = store
+        .install_artifact(
+            artifact('f', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    let accepted = store
+        .accept_artifact(&installed.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    let mut first = instance(installed.artifact.metadata.sha256.clone());
+    first.enabled = true;
+    let first = store
+        .save_instance(first, accepted.config_revision, &context())
+        .await
+        .unwrap();
+    let mut second = instance(installed.artifact.metadata.sha256.clone());
+    second.enabled = true;
+    let second = store
+        .save_instance(second, first.config_revision, &context())
+        .await
+        .unwrap();
+    let mut target = instance(installed.artifact.metadata.sha256);
+    target.enabled = true;
+    let result = store
+        .save_instance_replacing(
+            target,
+            second.config_revision,
+            PluginStateCommit {
+                configuration: PluginStateConfiguration { namespaces: vec![] },
+                transition_id: None,
+            },
+            &[
+                PluginInstanceReplacement {
+                    id: first.instance.id.clone(),
+                    expected_revision: first.instance.revision.get(),
+                },
+                PluginInstanceReplacement {
+                    id: second.instance.id.clone(),
+                    expected_revision: second.instance.revision.get() - 1,
+                },
+            ],
+            &context(),
+        )
+        .await;
+    assert_eq!(result.err().unwrap().kind(), AdminStoreErrorKind::Conflict);
+    let snapshot = store.load_instances().await.unwrap();
+    assert_eq!(snapshot.config_revision, second.config_revision);
+    assert_eq!(snapshot.instances.len(), 2);
+    assert!(snapshot.instances.iter().all(|item| item.enabled));
+    database.close().await;
+}
+
+#[tokio::test]
+async fn instance_save_rejects_unaccepted_enablement_and_forged_acceptance_facts() {
+    let Some(database) = TestDatabase::create("plugin_instance_acceptance_facts").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let mut package = artifact('d', &["linux-x86_64"]);
+    package.metadata.requested_permissions = vec!["network".into()];
+    let installed = store
+        .install_artifact(package, PluginSource::Upload, &context())
+        .await
+        .unwrap();
+
+    let mut enabled = instance(installed.artifact.metadata.sha256.clone());
+    enabled.enabled = true;
+    enabled.trusted_process = false;
+    assert_eq!(
+        store
+            .save_instance(enabled, installed.config_revision, &context())
+            .await
+            .err()
+            .expect("unaccepted artifact cannot be enabled")
+            .kind(),
+        AdminStoreErrorKind::Invalid
+    );
+    let mut forged = instance(installed.artifact.metadata.sha256.clone());
+    forged.trusted_process = true;
+    assert_eq!(
+        store
+            .save_instance(forged, installed.config_revision, &context())
+            .await
+            .err()
+            .expect("unaccepted artifact cannot forge trust")
+            .kind(),
+        AdminStoreErrorKind::Invalid
+    );
+
+    let accepted = store
+        .accept_artifact(&installed.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    let missing_grant = instance(installed.artifact.metadata.sha256);
+    assert_eq!(
+        store
+            .save_instance(missing_grant, accepted.config_revision, &context())
+            .await
+            .err()
+            .expect("accepted artifact grants cannot be forged")
+            .kind(),
+        AdminStoreErrorKind::Invalid
+    );
+    database.close().await;
+}
+
+#[tokio::test]
+async fn instance_and_secret_restore_together_and_artifact_deletion_respects_references() {
+    let Some(database) = TestDatabase::create("plugin_instances").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let artifact = store
+        .install_artifact(
+            artifact('e', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    let artifact = store
+        .accept_artifact(&artifact.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    let input = instance(artifact.artifact.metadata.sha256.clone());
+    let saved = store
+        .save_instance(input.clone(), artifact.config_revision, &context())
+        .await
+        .unwrap();
+    drop(store);
+    let store = PgPluginStore::new(database.pool.clone());
+    let loaded = store.load_instances().await.unwrap();
+    assert_eq!(loaded.config_revision, saved.config_revision);
+    assert_eq!(loaded.instances[0].configuration, input.configuration);
+    assert_eq!(
+        loaded.instances[0].secrets["token"].expose_secret(),
+        "sensitive-fixture"
+    );
+    let configuration: String =
+        sqlx::query_scalar("select configuration_json::text from plugin_instances")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert!(!configuration.contains("sensitive-fixture"));
+    assert_eq!(
+        store
+            .delete_artifact(&input.artifact_sha256, &context())
+            .await
+            .unwrap_err()
+            .kind(),
+        AdminStoreErrorKind::Conflict
+    );
+    store
+        .delete_instance(&input.id, loaded.config_revision, &context())
+        .await
+        .unwrap();
+    store
+        .delete_artifact(&input.artifact_sha256, &context())
+        .await
+        .unwrap();
+    let count: i64 = sqlx::query_scalar("select count(*) from plugin_instance_secrets")
+        .fetch_one(&database.pool)
+        .await
+        .unwrap();
+    assert_eq!(count, 0);
+    database.close().await;
+}
+
+#[tokio::test]
+async fn a_prepared_instance_cannot_commit_over_a_later_configuration_change() {
+    let Some(database) = TestDatabase::create("plugin_instance_race").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let artifact = store
+        .install_artifact(
+            artifact('f', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    let artifact = store
+        .accept_artifact(&artifact.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    let first = instance(artifact.artifact.metadata.sha256);
+    let mut stale = first.clone();
+    stale.name = "stale".into();
+    let saved = store
+        .save_instance(first.clone(), artifact.config_revision, &context())
+        .await
+        .unwrap();
+    let error = store
+        .save_instance(stale, artifact.config_revision, &context())
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminStoreErrorKind::Conflict);
+    let loaded = store.load_instances().await.unwrap();
+    assert_eq!(loaded.instances[0].name, first.name);
+    assert_eq!(loaded.config_revision, saved.config_revision);
+    database.close().await;
+}
+
+#[tokio::test]
+async fn missing_binding_references_reject_without_bumping_revision() {
+    let Some(database) = TestDatabase::create("plugin_instance_missing_scope").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let artifact = store
+        .install_artifact(
+            artifact('a', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    let artifact = store
+        .accept_artifact(&artifact.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    let mut input = instance(artifact.artifact.metadata.sha256);
+    input.enabled = true;
+    input.bindings = vec![usage_binding(
+        "missing-client-key",
+        "grp_11111111111111111111111111111111",
+    )];
+    let error = match store
+        .save_instance(input, artifact.config_revision, &context())
+        .await
+    {
+        Ok(_) => panic!("missing binding references must be rejected"),
+        Err(error) => error,
+    };
+    assert_eq!(error.kind(), AdminStoreErrorKind::Invalid);
+    let revision: i64 =
+        sqlx::query_scalar("select config_revision from runtime_settings where id=1")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert_eq!(
+        revision,
+        i64::try_from(artifact.config_revision.get()).unwrap()
+    );
+    let count: i64 = sqlx::query_scalar("select count(*) from plugin_instances")
+        .fetch_one(&database.pool)
+        .await
+        .unwrap();
+    assert_eq!(count, 0);
+    database.close().await;
+}
+
+#[tokio::test]
+async fn existing_binding_references_roundtrip_in_the_instance_snapshot() {
+    let Some(database) = TestDatabase::create("plugin_instance_existing_scope").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let artifact = store
+        .install_artifact(
+            artifact('b', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    let artifact = store
+        .accept_artifact(&artifact.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    let client_key_id = "client-key-observer";
+    let account_group_id = "grp_22222222222222222222222222222222";
+    let plaintext_key = format!("sk_{}", "a".repeat(43));
+    sqlx::query(
+        "insert into client_api_keys(
+           id, name, key, enabled, max_concurrency, requests_per_minute, created_at, updated_at
+         ) values ($1, 'Observer Key', $2, true, 0, 0, now(), now())",
+    )
+    .bind(client_key_id)
+    .bind(plaintext_key)
+    .execute(&database.pool)
+    .await
+    .unwrap();
+    sqlx::query(
+        "insert into account_groups(
+           id, name, description, enabled, created_at, updated_at, color
+         ) values ($1, 'Observer Group', null, false, now(), now(), '#112233FF')",
+    )
+    .bind(account_group_id)
+    .execute(&database.pool)
+    .await
+    .unwrap();
+
+    let mut input = instance(artifact.artifact.metadata.sha256);
+    input.enabled = true;
+    input.bindings = vec![usage_binding(client_key_id, account_group_id)];
+    let saved = store
+        .save_instance(input, artifact.config_revision, &context())
+        .await
+        .unwrap();
+    let loaded = store.load_instances().await.unwrap();
+    assert_eq!(loaded.instances.len(), 1);
+    assert_eq!(
+        loaded.instances[0].bindings[0].client_key_ids,
+        [client_key_id]
+    );
+    assert_eq!(
+        loaded.instances[0].bindings[0].account_group_ids,
+        [account_group_id]
+    );
+
+    sqlx::query("delete from client_api_keys where id = $1")
+        .bind(client_key_id)
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    sqlx::query("delete from account_groups where id = $1")
+        .bind(account_group_id)
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    let mut disabled = loaded.instances[0].clone();
+    disabled.enabled = false;
+    store
+        .save_instance(disabled, saved.config_revision, &context())
+        .await
+        .expect("disabling must preserve stale bindings as a recovery path");
+    let disabled = store.load_instances().await.unwrap().instances.remove(0);
+    assert!(!disabled.enabled);
+    assert_eq!(disabled.bindings[0].client_key_ids, [client_key_id]);
+    assert_eq!(disabled.bindings[0].account_group_ids, [account_group_id]);
+    database.close().await;
+}
+
+#[tokio::test]
+async fn client_key_deletion_revision_prevents_a_stale_authentication_mapping_commit() {
+    let Some(database) = TestDatabase::create("plugin_instance_auth_key_race").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let artifact = store
+        .install_artifact(
+            artifact('c', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    let artifact = store
+        .accept_artifact(&artifact.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    let client_key_id = "client-key-authentication";
+    sqlx::query(
+        "insert into client_api_keys(
+           id, name, key, enabled, max_concurrency, requests_per_minute, created_at, updated_at
+         ) values ($1, 'Authentication Key', $2, true, 0, 0, now(), now())",
+    )
+    .bind(client_key_id)
+    .bind(format!("sk_{}", "b".repeat(43)))
+    .execute(&database.pool)
+    .await
+    .unwrap();
+
+    let mut input = instance(artifact.artifact.metadata.sha256);
+    input.enabled = true;
+    input.bindings = vec![frontend_authentication_binding(
+        "controlled-principal",
+        client_key_id,
+    )];
+    let saved = store
+        .save_instance(input.clone(), artifact.config_revision, &context())
+        .await
+        .expect("existing mapped key is accepted");
+    let loaded = store.load_instances().await.unwrap();
+    assert_eq!(
+        loaded.instances[0].bindings[0].identity_bindings[0].client_key_id,
+        client_key_id
+    );
+
+    let keys = PgAdminClientKeyStore::new(database.pool.clone());
+    let deleted_revision = keys
+        .delete_client_key(
+            DeleteClientKey {
+                id: ClientApiKeyId::new(client_key_id).unwrap(),
+            },
+            &context(),
+        )
+        .await
+        .expect("deletion is an explicit revocation");
+    assert!(deleted_revision.get() > saved.config_revision.get());
+
+    let stale_error = match store
+        .save_instance(input.clone(), saved.config_revision, &context())
+        .await
+    {
+        Ok(_) => panic!("stale candidate cannot commit over key deletion"),
+        Err(error) => error,
+    };
+    assert_eq!(stale_error.kind(), AdminStoreErrorKind::Conflict);
+    let missing_error = match store
+        .save_instance(input.clone(), deleted_revision, &context())
+        .await
+    {
+        Ok(_) => panic!("an enabled binding cannot reference the deleted key"),
+        Err(error) => error,
+    };
+    assert_eq!(missing_error.kind(), AdminStoreErrorKind::Invalid);
+
+    input.enabled = false;
+    store
+        .save_instance(input, deleted_revision, &context())
+        .await
+        .expect("disabling preserves the stale mapping as a recovery path");
+    database.close().await;
+}
+
+#[tokio::test]
+async fn version_settings_survive_upgrade_and_disabled_edits_and_share_the_transaction() {
+    let Some(database) = TestDatabase::create("plugin_version_settings").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let mut revision = Revision::new(1).unwrap();
+    for digest in ['a', 'b'] {
+        let mut package = artifact(digest, &["linux-x86_64"]);
+        package.metadata.version = if digest == 'a' { "1.0.0" } else { "2.0.0" }.into();
+        store
+            .install_artifact(package, PluginSource::Upload, &context())
+            .await
+            .unwrap();
+        revision = store
+            .accept_artifact(&digest.to_string().repeat(64), &context())
+            .await
+            .unwrap()
+            .config_revision;
+    }
+    let mut old = instance("a".repeat(64));
+    old.enabled = true;
+    old.configuration = serde_json::json!({"v1":"original"});
+    let saved = store
+        .save_instance(old, revision, &context())
+        .await
+        .unwrap();
+    let id = saved.instance.id.clone();
+    let mut next = saved.instance;
+    next.artifact_sha256 = "b".repeat(64);
+    next.configuration = serde_json::json!({"v2":"changed"});
+    next.secrets.insert("token".into(), "v2-secret".into());
+    let saved = store
+        .save_instance(next, saved.config_revision, &context())
+        .await
+        .unwrap();
+    let old_settings = store
+        .load_version_configuration(&id, &"a".repeat(64))
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(
+        old_settings.configuration,
+        serde_json::json!({"v1":"original"})
+    );
+    assert_eq!(
+        old_settings.secrets["token"].expose_secret(),
+        "sensitive-fixture"
+    );
+    let mut disabled = saved.instance;
+    disabled.enabled = false;
+    disabled.configuration = serde_json::json!({"incomplete":"draft"});
+    disabled.secrets.clear();
+    let saved = store
+        .save_instance(disabled, saved.config_revision, &context())
+        .await
+        .unwrap();
+    let v2_settings = store
+        .load_version_configuration(&id, &"b".repeat(64))
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(
+        v2_settings.configuration,
+        serde_json::json!({"v2":"changed"})
+    );
+    assert_eq!(v2_settings.secrets["token"].expose_secret(), "v2-secret");
+    let mut conflict = saved.instance;
+    conflict.enabled = true;
+    conflict.configuration = serde_json::json!({"mustNotCommit":true});
+    assert!(
+        store
+            .save_instance(conflict, revision, &context())
+            .await
+            .is_err()
+    );
+    assert_eq!(
+        store
+            .load_version_configuration(&id, &"b".repeat(64))
+            .await
+            .unwrap()
+            .unwrap()
+            .configuration,
+        v2_settings.configuration
+    );
+    assert_eq!(store.configuration_versions(&id).await.unwrap().len(), 2);
+    store
+        .delete_artifact(&"a".repeat(64), &context())
+        .await
+        .unwrap();
+    assert!(
+        store
+            .load_version_configuration(&id, &"a".repeat(64))
+            .await
+            .unwrap()
+            .is_none()
+    );
+    let current = store.load_instances().await.unwrap();
+    store
+        .delete_instance(&id, current.config_revision, &context())
+        .await
+        .unwrap();
+    assert!(store.configuration_versions(&id).await.unwrap().is_empty());
+    database.close().await;
+}
+
+#[tokio::test]
+async fn version_configuration_migration_preserves_existing_enabled_settings() {
+    let Some(database) = TestDatabase::create_through("plugin_version_upgrade", 18).await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let id = uuid::Uuid::now_v7();
+    let digest = "a".repeat(64);
+    let store = PgPluginStore::new(database.pool.clone());
+    let package = store
+        .install_artifact(
+            artifact('a', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    store
+        .accept_artifact(&package.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    sqlx::query("insert into plugin_instances (id,artifact_sha256,name,enabled,configuration_json,bindings_json,revision) values ($1,$2,'prior installation',true,$3,'[]'::jsonb,1)")
+        .bind(id).bind(&digest).bind(serde_json::json!({"preserved":true})).execute(&database.pool).await.unwrap();
+    sqlx::query("insert into plugin_instance_secrets (instance_id,secrets_json) values ($1,$2)")
+        .bind(id)
+        .bind(serde_json::json!({"token":"migration-fixture-secret"}))
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    super::super::TEST_MIGRATOR
+        .run(&database.pool)
+        .await
+        .unwrap();
+    let saved = store
+        .load_version_configuration(&id.to_string(), &digest)
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(saved.configuration, serde_json::json!({"preserved":true}));
+    assert_eq!(
+        saved.secrets["token"].expose_secret(),
+        "migration-fixture-secret"
+    );
+    database.close().await;
+}
diff --git a/backend/crates/gateway-store/tests/postgres/plugins/mod.rs b/backend/crates/gateway-store/tests/postgres/plugins/mod.rs
new file mode 100644
index 000000000..d45179844
--- /dev/null
+++ b/backend/crates/gateway-store/tests/postgres/plugins/mod.rs
@@ -0,0 +1,5 @@
+mod artifacts;
+mod credentials;
+mod instances;
+mod sources;
+mod state;
diff --git a/backend/crates/gateway-store/tests/postgres/plugins/sources.rs b/backend/crates/gateway-store/tests/postgres/plugins/sources.rs
new file mode 100644
index 000000000..fab0debb7
--- /dev/null
+++ b/backend/crates/gateway-store/tests/postgres/plugins/sources.rs
@@ -0,0 +1,365 @@
+use gateway_admin::{
+    model::{
+        plugins::{
+            PluginSource, PluginSourceEgress,
+            distribution::{PluginSourceBinding, PluginUpdatePolicy, PluginUpdateSource},
+        },
+        proxies::{NewProxy, UpdateProxy},
+    },
+    ports::{plugins::PluginStore, proxy::ProxyStore, store::AdminStoreErrorKind},
+};
+use gateway_core::account::OutboundProxy;
+use gateway_store::postgres::{PgPluginStore, PgProxyRepository};
+
+use super::{
+    super::TestDatabase,
+    artifacts::{artifact, context, initialize_revision},
+};
+
+#[tokio::test]
+async fn upgrades_keep_old_artifacts_and_require_explicit_source_change() {
+    let Some(database) = TestDatabase::create("plugin_sources").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let old = artifact('a', &["linux-x86_64"]);
+    store
+        .install_artifact(old.clone(), PluginSource::Upload, &context())
+        .await
+        .unwrap();
+    let mut new = artifact('b', &["linux-x86_64"]);
+    new.metadata.version = "2.0.0".into();
+    let remote = PluginSource::Github {
+        repository: "example/plugin".into(),
+        tag: "v2.0.0".into(),
+        asset: "plugin.tar.gz".into(),
+        credential_ids: vec![],
+        outbound_proxy: None,
+    };
+    let failure = store
+        .install_artifact(new.clone(), remote.clone(), &context())
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(failure.kind(), AdminStoreErrorKind::Conflict);
+    assert_eq!(store.list_artifacts().await.unwrap().len(), 1);
+    store
+        .change_update_source(
+            PluginSourceBinding {
+                plugin_id: "test.example".into(),
+                source: PluginUpdateSource::Github {
+                    repository: "example/plugin".into(),
+                },
+                policy: Default::default(),
+                outbound_proxy_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    store
+        .install_artifact(new, remote, &context())
+        .await
+        .unwrap();
+    assert_eq!(store.list_artifacts().await.unwrap().len(), 2);
+    assert_eq!(
+        store
+            .load_artifact(&old.metadata.sha256)
+            .await
+            .unwrap()
+            .archive,
+        old.archive
+    );
+    database.close().await;
+}
+
+#[tokio::test]
+async fn concurrent_identical_installations_are_idempotent_without_duplicate_audit() {
+    let Some(database) = TestDatabase::create("plugin_install_race").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let context = context();
+    let results = futures::future::join_all((0..8).map(|_| {
+        store.install_artifact(
+            artifact('d', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context,
+        )
+    }))
+    .await;
+    assert!(results.iter().all(|result| {
+        result
+            .as_ref()
+            .is_ok_and(|mutation| mutation.config_revision.get() == 2)
+    }));
+    let count: i64 = sqlx::query_scalar(
+        "select count(*) from admin_audit_events where entity_kind='plugin_artifact'",
+    )
+    .fetch_one(&database.pool)
+    .await
+    .unwrap();
+    assert_eq!(count, 1);
+    database.close().await;
+}
+
+#[tokio::test]
+async fn last_version_deletion_clears_source_rules_and_allows_a_fresh_install() {
+    let Some(database) = TestDatabase::create("plugin_source_cleanup").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let first = artifact('a', &["linux-x86_64"]);
+    let mut second = artifact('b', &["linux-x86_64"]);
+    second.metadata.version = "2.0.0".into();
+    for package in [&first, &second] {
+        store
+            .install_artifact(package.clone(), PluginSource::Upload, &context())
+            .await
+            .unwrap();
+    }
+    store
+        .delete_artifact(&first.metadata.sha256, &context())
+        .await
+        .unwrap();
+    assert_eq!(
+        store.list_update_sources().await.unwrap()[0].source,
+        PluginUpdateSource::Upload
+    );
+    let remote = PluginSource::Github {
+        repository: "example/new-source".into(),
+        tag: "v1.0.0".into(),
+        asset: "plugin.tar.gz".into(),
+        credential_ids: vec![],
+        outbound_proxy: None,
+    };
+    assert_eq!(
+        store
+            .install_artifact(first.clone(), remote.clone(), &context())
+            .await
+            .err()
+            .unwrap()
+            .kind(),
+        AdminStoreErrorKind::Conflict
+    );
+
+    store
+        .delete_artifact(&second.metadata.sha256, &context())
+        .await
+        .unwrap();
+    assert!(store.list_update_sources().await.unwrap().is_empty());
+    store
+        .install_artifact(first, remote.clone(), &context())
+        .await
+        .unwrap();
+    assert_eq!(
+        store.list_update_sources().await.unwrap()[0].source,
+        (&remote).into()
+    );
+    database.close().await;
+}
+
+#[tokio::test]
+async fn update_policy_is_persistent_audited_and_unchanged_by_install_or_read() {
+    let Some(database) = TestDatabase::create("plugin_update_policy").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    store
+        .install_artifact(
+            artifact('a', &["linux-x86_64"]),
+            PluginSource::Upload,
+            &context(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        store.list_update_sources().await.unwrap()[0].policy,
+        PluginUpdatePolicy::Manual {}
+    );
+    let binding = PluginSourceBinding {
+        plugin_id: "test.example".into(),
+        source: PluginUpdateSource::Github {
+            repository: "example/plugin".into(),
+        },
+        policy: PluginUpdatePolicy::Pinned {
+            tag: "v2.0.0-rc.1".into(),
+            allow_prerelease: true,
+        },
+        outbound_proxy_id: None,
+    };
+    assert_eq!(
+        store
+            .change_update_source(binding.clone(), &context())
+            .await
+            .unwrap()
+            .get(),
+        3
+    );
+    drop(store);
+    let reopened = PgPluginStore::new(database.pool.clone());
+    for _ in 0..2 {
+        assert_eq!(
+            reopened.list_update_sources().await.unwrap(),
+            vec![binding.clone()]
+        );
+    }
+    let mut next = artifact('b', &["linux-x86_64"]);
+    next.metadata.version = "2.0.0-rc.1".into();
+    reopened
+        .install_artifact(
+            next,
+            PluginSource::Github {
+                repository: "example/plugin".into(),
+                tag: "v2.0.0-rc.1".into(),
+                asset: "plugin.tar.gz".into(),
+                credential_ids: vec![],
+                outbound_proxy: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(reopened.list_update_sources().await.unwrap(), vec![binding]);
+    let audits: Vec<(String, i64, Vec<String>)> = sqlx::query_as("select action,config_revision,changed_fields from admin_audit_events where entity_kind='plugin_source'")
+        .fetch_all(&database.pool).await.unwrap();
+    assert_eq!(
+        audits,
+        vec![(
+            "change_source".into(),
+            3,
+            vec!["source".into(), "policy".into(), "outbound_proxy".into()]
+        )]
+    );
+    let revision: i64 =
+        sqlx::query_scalar("select config_revision from runtime_settings where id=1")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert_eq!(revision, 4, "读取不能推进配置 revision");
+    database.close().await;
+}
+
+#[tokio::test]
+async fn source_proxy_is_revision_fenced_and_referenced_until_the_artifact_is_deleted() {
+    let Some(database) = TestDatabase::create("plugin_source_proxy").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let plugins = PgPluginStore::new(database.pool.clone());
+    let proxies = PgProxyRepository::new(database.pool.clone());
+    let saved = proxies
+        .create(
+            NewProxy {
+                location: None,
+                name: "Plugin source".into(),
+                proxy: OutboundProxy::parse("http://127.0.0.1:18080").unwrap(),
+            },
+            &context(),
+        )
+        .await
+        .unwrap()
+        .record;
+    let source = PluginSource::Github {
+        repository: "example/plugin".into(),
+        tag: "v1.0.0".into(),
+        asset: "plugin.tar.gz".into(),
+        credential_ids: vec![],
+        outbound_proxy: Some(PluginSourceEgress {
+            id: saved.id.clone(),
+            revision: saved.revision.get(),
+        }),
+    };
+    let installed = plugins
+        .install_artifact(artifact('e', &["linux-x86_64"]), source.clone(), &context())
+        .await
+        .unwrap();
+    assert_eq!(
+        plugins.list_update_sources().await.unwrap()[0].outbound_proxy_id,
+        Some(saved.id.clone())
+    );
+    let updated = proxies
+        .update(
+            UpdateProxy {
+                location: None,
+                id: saved.id.clone(),
+                revision: saved.revision,
+                name: saved.name,
+                proxy: Some(OutboundProxy::parse("http://127.0.0.1:18081").unwrap()),
+            },
+            &context(),
+        )
+        .await
+        .unwrap()
+        .record;
+    let mut candidate = artifact('f', &["linux-x86_64"]);
+    candidate.metadata.version = "2.0.0".into();
+    let Err(error) = plugins
+        .install_artifact(candidate, source, &context())
+        .await
+    else {
+        panic!("stale proxy revision must reject the artifact")
+    };
+    assert_eq!(error.kind(), AdminStoreErrorKind::Conflict);
+    assert_eq!(
+        proxies
+            .delete(&updated.id, updated.revision, &context())
+            .await
+            .unwrap_err()
+            .kind(),
+        AdminStoreErrorKind::Conflict
+    );
+    plugins
+        .change_update_source(
+            PluginSourceBinding {
+                plugin_id: "test.example".into(),
+                source: PluginUpdateSource::Upload,
+                policy: PluginUpdatePolicy::Manual {},
+                outbound_proxy_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        proxies
+            .delete(&updated.id, updated.revision, &context())
+            .await
+            .unwrap_err()
+            .kind(),
+        AdminStoreErrorKind::Conflict,
+        "历史制品仍引用该代理时不得删除"
+    );
+    plugins
+        .delete_artifact(&installed.artifact.metadata.sha256, &context())
+        .await
+        .unwrap();
+    proxies
+        .delete(&updated.id, updated.revision, &context())
+        .await
+        .unwrap();
+    let removed_proxy_source = PluginSource::Github {
+        repository: "example/plugin".into(),
+        tag: "v3.0.0".into(),
+        asset: "plugin.tar.gz".into(),
+        credential_ids: vec![],
+        outbound_proxy: Some(PluginSourceEgress {
+            id: updated.id,
+            revision: updated.revision.get(),
+        }),
+    };
+    let mut candidate = artifact('0', &["linux-x86_64"]);
+    candidate.metadata.version = "3.0.0".into();
+    let Err(error) = plugins
+        .install_artifact(candidate, removed_proxy_source, &context())
+        .await
+    else {
+        panic!("deleted frozen proxy identity must reject the artifact")
+    };
+    assert_eq!(error.kind(), AdminStoreErrorKind::Conflict);
+    database.close().await;
+}
diff --git a/backend/crates/gateway-store/tests/postgres/plugins/state.rs b/backend/crates/gateway-store/tests/postgres/plugins/state.rs
new file mode 100644
index 000000000..7177605c2
--- /dev/null
+++ b/backend/crates/gateway-store/tests/postgres/plugins/state.rs
@@ -0,0 +1,855 @@
+use std::collections::BTreeMap;
+
+use gateway_admin::{
+    model::{
+        Revision,
+        plugins::{
+            PluginSource,
+            instances::PluginInstance,
+            state::{
+                ApplyPluginStateMigration, DeletePluginState, PluginStateCommit,
+                PluginStateConfiguration, PluginStateMigrationAction, PluginStateMigrationChange,
+                PluginStateOwnerRequest, PluginStateSchema, PutPluginState,
+            },
+        },
+    },
+    ports::{
+        plugins::{PluginStateStore, PluginStateStoreErrorKind, PluginStore},
+        store::AdminStoreErrorKind,
+    },
+};
+use gateway_store::postgres::PgPluginStore;
+use serde_json::json;
+
+use super::{
+    super::TestDatabase,
+    artifacts::{artifact, context, initialize_revision},
+};
+
+fn schema(version: u32, migrates_from: Vec<u32>, maximum_records: u32) -> PluginStateSchema {
+    PluginStateSchema {
+        namespace: "cache".into(),
+        schema_version: version,
+        schema_sha256: char::from_digit(version, 16)
+            .unwrap()
+            .to_string()
+            .repeat(64),
+        schema: json!({
+            "type": "object",
+            "required": ["value"],
+            "properties": {"value": {"type": "integer"}},
+            "additionalProperties": false,
+        }),
+        maximum_records,
+        maximum_bytes: 1024,
+        maximum_value_bytes: 128,
+        migrates_from,
+    }
+}
+
+fn configuration(schema: PluginStateSchema) -> PluginStateConfiguration {
+    PluginStateConfiguration {
+        namespaces: vec![schema],
+    }
+}
+
+fn instance(artifact_sha256: String) -> PluginInstance {
+    PluginInstance {
+        id: uuid::Uuid::now_v7().to_string(),
+        name: "State fixture".into(),
+        artifact_sha256,
+        enabled: false,
+        trusted_process: true,
+        configuration: json!({}),
+        secrets: BTreeMap::new(),
+        grants: vec![],
+        bindings: vec![],
+        revision: Revision::new(1).unwrap(),
+    }
+}
+
+fn owner_request(
+    instance: &PluginInstance,
+    configuration: PluginStateConfiguration,
+) -> PluginStateOwnerRequest {
+    PluginStateOwnerRequest {
+        instance_id: instance.id.clone(),
+        artifact_sha256: instance.artifact_sha256.clone(),
+        instance_revision: instance.revision,
+        configuration,
+    }
+}
+
+async fn install_version(
+    store: &PgPluginStore,
+    digest: char,
+    version: &str,
+) -> gateway_admin::model::plugins::PluginArtifactMutation {
+    let mut artifact = artifact(digest, &["linux-x86_64"]);
+    artifact.metadata.version = version.into();
+    let installed = store
+        .install_artifact(artifact, PluginSource::Upload, &context())
+        .await
+        .unwrap();
+    store
+        .accept_artifact(&installed.artifact.metadata.sha256, &context())
+        .await
+        .unwrap()
+}
+
+async fn migrate_all(
+    store: &PgPluginStore,
+    transition_id: &str,
+    namespace: &str,
+    batch_size: u32,
+) -> Vec<String> {
+    let mut keys = Vec::new();
+    loop {
+        let batch = store
+            .migration_batch(transition_id, namespace, batch_size)
+            .await
+            .unwrap();
+        let complete = batch.records.is_empty();
+        let expected_keys: Vec<_> = batch
+            .records
+            .iter()
+            .map(|record| record.key.clone())
+            .collect();
+        keys.extend(expected_keys.iter().cloned());
+        store
+            .apply_migration_batch(ApplyPluginStateMigration {
+                transition_id: transition_id.to_owned(),
+                namespace: namespace.to_owned(),
+                cursor: batch.cursor,
+                changes: expected_keys
+                    .iter()
+                    .map(|key| PluginStateMigrationChange {
+                        key: key.clone(),
+                        action: PluginStateMigrationAction::Keep,
+                    })
+                    .collect(),
+                expected_keys,
+            })
+            .await
+            .unwrap();
+        if complete {
+            return keys;
+        }
+    }
+}
+
+#[tokio::test]
+async fn migration_preserves_byte_order_for_mixed_case_and_unicode_keys() {
+    let Some(database) = TestDatabase::create("plugin_state_key_order").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let installed = install_version(&store, 'a', "1.0.0").await;
+    let state = configuration(schema(1, vec![], 10));
+    let saved = store
+        .save_instance_with_state(
+            instance(installed.artifact.metadata.sha256),
+            installed.config_revision,
+            PluginStateCommit {
+                configuration: state.clone(),
+                transition_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    let owner = store
+        .load_owner(owner_request(&saved.instance, state))
+        .await
+        .unwrap()
+        .unwrap();
+    for key in ["a", "B", "é", "Z", "中", "a10", "a2"] {
+        store
+            .put(
+                &owner,
+                PutPluginState {
+                    namespace: "cache".into(),
+                    key: key.into(),
+                    value: json!({"value": 1}),
+                    expected_version: None,
+                },
+            )
+            .await
+            .unwrap();
+    }
+    let target = install_version(&store, 'b', "2.0.0").await;
+    let transition = store
+        .begin_transition(
+            &saved.instance.id,
+            saved.instance.revision,
+            &target.artifact.metadata.sha256,
+            configuration(schema(2, vec![1], 10)),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        migrate_all(&store, &transition.id, "cache", 3).await,
+        ["B", "Z", "a", "a10", "a2", "é", "中"]
+    );
+    database.close().await;
+}
+
+#[tokio::test]
+async fn completed_migration_releases_old_records_and_artifact() {
+    let Some(database) = TestDatabase::create("plugin_state_release").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let installed = install_version(&store, 'a', "1.0.0").await;
+    let old_digest = installed.artifact.metadata.sha256;
+    let state = configuration(schema(1, vec![], 2));
+    let saved = store
+        .save_instance_with_state(
+            instance(old_digest.clone()),
+            installed.config_revision,
+            PluginStateCommit {
+                configuration: state.clone(),
+                transition_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    let owner = store
+        .load_owner(owner_request(&saved.instance, state))
+        .await
+        .unwrap()
+        .unwrap();
+    store
+        .put(
+            &owner,
+            PutPluginState {
+                namespace: "cache".into(),
+                key: "retained".into(),
+                value: json!({"value": 1}),
+                expected_version: None,
+            },
+        )
+        .await
+        .unwrap();
+    let target = install_version(&store, 'b', "2.0.0").await;
+    let state = configuration(schema(2, vec![1], 2));
+    let transition = store
+        .begin_transition(
+            &saved.instance.id,
+            saved.instance.revision,
+            &target.artifact.metadata.sha256,
+            state.clone(),
+        )
+        .await
+        .unwrap();
+    migrate_all(&store, &transition.id, "cache", 100).await;
+    let mut upgraded = saved.instance;
+    upgraded.artifact_sha256 = target.artifact.metadata.sha256;
+    let upgraded = store
+        .save_instance_with_state(
+            upgraded,
+            target.config_revision,
+            PluginStateCommit {
+                configuration: state.clone(),
+                transition_id: Some(transition.id),
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    store
+        .delete_artifact(&old_digest, &context())
+        .await
+        .unwrap();
+    let owner = store
+        .load_owner(owner_request(&upgraded.instance, state))
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(
+        store
+            .get(&owner, "cache", "retained")
+            .await
+            .unwrap()
+            .unwrap()
+            .value,
+        json!({"value": 1})
+    );
+    let counts: (i64, i64) = sqlx::query_as(
+        "select (select count(*) from plugin_state_generations), \
+                (select count(*) from plugin_state_records)",
+    )
+    .fetch_one(&database.pool)
+    .await
+    .unwrap();
+    assert_eq!(counts, (1, 1));
+    database.close().await;
+}
+
+#[tokio::test]
+async fn schema_budget_uses_compact_json_not_database_formatting() {
+    let Some(database) = TestDatabase::create("plugin_state_schema_budget").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let installed = install_version(&store, 'a', "1.0.0").await;
+    let mut namespace = schema(1, vec![], 2);
+    namespace.schema = json!({
+        "type": "string",
+        "enum": (0..4000).map(|index| format!("v{index:04}")).collect::<Vec<_>>(),
+    });
+    assert!(serde_json::to_vec(&namespace.schema).unwrap().len() <= 32 * 1024);
+    let database_bytes: i32 = sqlx::query_scalar("select octet_length($1::jsonb::text)")
+        .bind(&namespace.schema)
+        .fetch_one(&database.pool)
+        .await
+        .unwrap();
+    assert!(database_bytes > 32 * 1024);
+    let state = configuration(namespace);
+    let saved = store
+        .save_instance_with_state(
+            instance(installed.artifact.metadata.sha256),
+            installed.config_revision,
+            PluginStateCommit {
+                configuration: state.clone(),
+                transition_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    assert!(
+        store
+            .load_owner(owner_request(&saved.instance, state))
+            .await
+            .unwrap()
+            .is_some()
+    );
+    database.close().await;
+}
+
+#[tokio::test]
+async fn failed_multi_namespace_promotion_restores_cleaned_source_generations() {
+    let Some(database) = TestDatabase::create("plugin_state_promotion_rollback").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let installed = install_version(&store, 'a', "1.0.0").await;
+    let old_digest = installed.artifact.metadata.sha256;
+    let mut state = configuration(schema(1, vec![], 2));
+    let mut second = state.namespaces[0].clone();
+    second.namespace = "settings".into();
+    state.namespaces.push(second);
+    let saved = store
+        .save_instance_with_state(
+            instance(old_digest.clone()),
+            installed.config_revision,
+            PluginStateCommit {
+                configuration: state.clone(),
+                transition_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    let owner = store
+        .load_owner(owner_request(&saved.instance, state))
+        .await
+        .unwrap()
+        .unwrap();
+    for namespace in ["cache", "settings"] {
+        store
+            .put(
+                &owner,
+                PutPluginState {
+                    namespace: namespace.into(),
+                    key: "retained".into(),
+                    value: json!({"value": 1}),
+                    expected_version: None,
+                },
+            )
+            .await
+            .unwrap();
+    }
+    let target = install_version(&store, 'b', "2.0.0").await;
+    let mut state = configuration(schema(2, vec![1], 2));
+    let mut second = state.namespaces[0].clone();
+    second.namespace = "settings".into();
+    state.namespaces.push(second);
+    let transition = store
+        .begin_transition(
+            &saved.instance.id,
+            saved.instance.revision,
+            &target.artifact.metadata.sha256,
+            state.clone(),
+        )
+        .await
+        .unwrap();
+    migrate_all(&store, &transition.id, "cache", 100).await;
+    let mut upgraded = saved.instance;
+    upgraded.artifact_sha256 = target.artifact.metadata.sha256;
+    let commit = PluginStateCommit {
+        configuration: state.clone(),
+        transition_id: Some(transition.id.clone()),
+    };
+    let error = store
+        .save_instance_with_state(
+            upgraded.clone(),
+            target.config_revision,
+            commit.clone(),
+            &context(),
+        )
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminStoreErrorKind::Conflict);
+    // cache 已走过清理步骤，settings 未完成导致整笔事务回滚，旧身份和两份数据仍有效。
+    for namespace in ["cache", "settings"] {
+        assert_eq!(
+            store
+                .get(&owner, namespace, "retained")
+                .await
+                .unwrap()
+                .unwrap()
+                .value,
+            json!({"value": 1})
+        );
+    }
+    migrate_all(&store, &transition.id, "settings", 100).await;
+    let upgraded = store
+        .save_instance_with_state(upgraded, target.config_revision, commit, &context())
+        .await
+        .unwrap();
+    store
+        .delete_artifact(&old_digest, &context())
+        .await
+        .unwrap();
+    let owner = store
+        .load_owner(owner_request(&upgraded.instance, state))
+        .await
+        .unwrap()
+        .unwrap();
+    for namespace in ["cache", "settings"] {
+        assert_eq!(
+            store
+                .get(&owner, namespace, "retained")
+                .await
+                .unwrap()
+                .unwrap()
+                .value,
+            json!({"value": 1})
+        );
+    }
+    database.close().await;
+}
+
+#[tokio::test]
+async fn removing_empty_namespace_releases_its_artifact_reference() {
+    let Some(database) = TestDatabase::create("plugin_state_remove_namespace").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let installed = install_version(&store, 'a', "1.0.0").await;
+    let old_digest = installed.artifact.metadata.sha256;
+    let saved = store
+        .save_instance_with_state(
+            instance(old_digest.clone()),
+            installed.config_revision,
+            PluginStateCommit {
+                configuration: configuration(schema(1, vec![], 2)),
+                transition_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    let target = install_version(&store, 'b', "2.0.0").await;
+    let mut upgraded = saved.instance;
+    upgraded.artifact_sha256 = target.artifact.metadata.sha256;
+    store
+        .save_instance_with_state(
+            upgraded,
+            target.config_revision,
+            PluginStateCommit {
+                configuration: PluginStateConfiguration { namespaces: vec![] },
+                transition_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    store
+        .delete_artifact(&old_digest, &context())
+        .await
+        .unwrap();
+    let remaining: i64 = sqlx::query_scalar("select count(*) from plugin_state_generations")
+        .fetch_one(&database.pool)
+        .await
+        .unwrap();
+    assert_eq!(remaining, 0);
+    database.close().await;
+}
+
+#[tokio::test]
+async fn state_cas_quota_and_fence_are_independent_from_global_revision() {
+    let Some(database) = TestDatabase::create("plugin_state_cas").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let installed = install_version(&store, 'a', "1.0.0").await;
+    let state = configuration(schema(1, vec![], 2));
+    let saved = store
+        .save_instance_with_state(
+            instance(installed.artifact.metadata.sha256),
+            installed.config_revision,
+            PluginStateCommit {
+                configuration: state.clone(),
+                transition_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    let owner = store
+        .load_owner(owner_request(&saved.instance, state.clone()))
+        .await
+        .unwrap()
+        .unwrap();
+
+    // 无关制品安装会推进全局配置 revision，但不能撤销实例自己的状态 fence。
+    let unrelated = install_version(&store, 'b', "2.0.0").await;
+    let first = store
+        .put(
+            &owner,
+            PutPluginState {
+                namespace: "cache".into(),
+                key: "a".into(),
+                value: json!({"value": 1}),
+                expected_version: None,
+            },
+        )
+        .await
+        .unwrap();
+    let second = store
+        .put(
+            &owner,
+            PutPluginState {
+                namespace: "cache".into(),
+                key: "b".into(),
+                value: json!({"value": 2}),
+                expected_version: None,
+            },
+        )
+        .await
+        .unwrap();
+    assert_eq!((first.version, second.version), (1, 2));
+    assert_eq!(
+        store
+            .put(
+                &owner,
+                PutPluginState {
+                    namespace: "cache".into(),
+                    key: "c".into(),
+                    value: json!({"value": 3}),
+                    expected_version: None,
+                },
+            )
+            .await
+            .unwrap_err()
+            .kind(),
+        PluginStateStoreErrorKind::Quota
+    );
+    let updated = store
+        .put(
+            &owner,
+            PutPluginState {
+                namespace: "cache".into(),
+                key: "a".into(),
+                value: json!({"value": 4}),
+                expected_version: Some(first.version),
+            },
+        )
+        .await
+        .unwrap();
+    assert_eq!(updated.version, 3);
+    assert_eq!(
+        store
+            .delete(
+                &owner,
+                DeletePluginState {
+                    namespace: "cache".into(),
+                    key: "a".into(),
+                    expected_version: first.version,
+                },
+            )
+            .await
+            .unwrap_err()
+            .kind(),
+        PluginStateStoreErrorKind::Conflict
+    );
+    assert!(
+        store
+            .delete(
+                &owner,
+                DeletePluginState {
+                    namespace: "cache".into(),
+                    key: "a".into(),
+                    expected_version: updated.version,
+                },
+            )
+            .await
+            .unwrap()
+    );
+    let recreated = store
+        .put(
+            &owner,
+            PutPluginState {
+                namespace: "cache".into(),
+                key: "a".into(),
+                value: json!({"value": 5}),
+                expected_version: None,
+            },
+        )
+        .await
+        .unwrap();
+    assert_eq!(recreated.version, 4, "删除后不能产生可 ABA 的记录版本");
+    assert_eq!(
+        store.load_instances().await.unwrap().config_revision,
+        unrelated.config_revision,
+        "普通状态写入不能推进全局配置 revision"
+    );
+    let mut undersized = state.clone();
+    undersized.namespaces[0].maximum_value_bytes = 4;
+    assert_eq!(
+        store
+            .transition_required(&saved.instance.id, &undersized)
+            .await
+            .unwrap_err()
+            .kind(),
+        PluginStateStoreErrorKind::Conflict,
+        "配额收紧不能让已有记录超过单值上限"
+    );
+
+    // 同一实例的配置提交会轮换 fence；旧进程即使仍持有 owner 也不能继续写。
+    let rebound = store
+        .save_instance_with_state(
+            saved.instance.clone(),
+            unrelated.config_revision,
+            PluginStateCommit {
+                configuration: state.clone(),
+                transition_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    let error = store.get(&owner, "cache", "a").await.err().unwrap();
+    assert_eq!(error.kind(), PluginStateStoreErrorKind::PermissionDenied);
+    let rebound_owner = store
+        .load_owner(owner_request(&rebound.instance, state))
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(
+        store
+            .get(&rebound_owner, "cache", "a")
+            .await
+            .unwrap()
+            .unwrap()
+            .value,
+        json!({"value": 5})
+    );
+    database.close().await;
+}
+
+#[tokio::test]
+async fn migration_promotes_atomically_and_incomplete_staging_cannot_replace_active_state() {
+    let Some(database) = TestDatabase::create("plugin_state_migration").await else {
+        return;
+    };
+    initialize_revision(&database).await;
+    let store = PgPluginStore::new(database.pool.clone());
+    let first_artifact = install_version(&store, 'c', "1.0.0").await;
+    let second_artifact = install_version(&store, 'd', "2.0.0").await;
+    let third_artifact = install_version(&store, 'e', "3.0.0").await;
+    let first_state = configuration(schema(1, vec![], 4));
+    let saved = store
+        .save_instance_with_state(
+            instance(first_artifact.artifact.metadata.sha256),
+            third_artifact.config_revision,
+            PluginStateCommit {
+                configuration: first_state.clone(),
+                transition_id: None,
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    let first_owner = store
+        .load_owner(owner_request(&saved.instance, first_state))
+        .await
+        .unwrap()
+        .unwrap();
+    for (key, value) in [("a", 1), ("b", 2)] {
+        store
+            .put(
+                &first_owner,
+                PutPluginState {
+                    namespace: "cache".into(),
+                    key: key.into(),
+                    value: json!({"value": value}),
+                    expected_version: None,
+                },
+            )
+            .await
+            .unwrap();
+    }
+
+    let second_state = configuration(schema(2, vec![1], 4));
+    assert!(
+        store
+            .transition_required(&saved.instance.id, &second_state)
+            .await
+            .unwrap()
+    );
+    let transition = store
+        .begin_transition(
+            &saved.instance.id,
+            saved.instance.revision,
+            &second_artifact.artifact.metadata.sha256,
+            second_state.clone(),
+        )
+        .await
+        .unwrap();
+    let batch = store
+        .migration_batch(&transition.id, "cache", 64)
+        .await
+        .unwrap();
+    assert_eq!(
+        batch
+            .records
+            .iter()
+            .map(|record| record.key.as_str())
+            .collect::<Vec<_>>(),
+        ["a", "b"]
+    );
+    store
+        .apply_migration_batch(ApplyPluginStateMigration {
+            transition_id: transition.id.clone(),
+            namespace: "cache".into(),
+            cursor: batch.cursor,
+            expected_keys: vec!["a".into(), "b".into()],
+            changes: vec![
+                PluginStateMigrationChange {
+                    key: "a".into(),
+                    action: PluginStateMigrationAction::Keep,
+                },
+                PluginStateMigrationChange {
+                    key: "b".into(),
+                    action: PluginStateMigrationAction::Replace(json!({"value": 20})),
+                },
+            ],
+        })
+        .await
+        .unwrap();
+    let terminal = store
+        .migration_batch(&transition.id, "cache", 64)
+        .await
+        .unwrap();
+    assert!(terminal.records.is_empty());
+    store
+        .apply_migration_batch(ApplyPluginStateMigration {
+            transition_id: transition.id.clone(),
+            namespace: "cache".into(),
+            cursor: terminal.cursor,
+            expected_keys: vec![],
+            changes: vec![],
+        })
+        .await
+        .unwrap();
+    assert_eq!(
+        store.load_instances().await.unwrap().config_revision,
+        saved.config_revision,
+        "状态迁移批次不能推进全局配置 revision"
+    );
+
+    let mut upgraded = saved.instance.clone();
+    upgraded.artifact_sha256 = second_artifact.artifact.metadata.sha256;
+    let upgraded = store
+        .save_instance_with_state(
+            upgraded,
+            saved.config_revision,
+            PluginStateCommit {
+                configuration: second_state.clone(),
+                transition_id: Some(transition.id),
+            },
+            &context(),
+        )
+        .await
+        .unwrap();
+    let error = store.get(&first_owner, "cache", "a").await.err().unwrap();
+    assert_eq!(error.kind(), PluginStateStoreErrorKind::PermissionDenied);
+    let second_owner = store
+        .load_owner(owner_request(&upgraded.instance, second_state))
+        .await
+        .unwrap()
+        .unwrap();
+    let migrated = store
+        .get(&second_owner, "cache", "b")
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(migrated.schema_version, 2);
+    assert_eq!(migrated.value, json!({"value": 20}));
+
+    let third_state = configuration(schema(3, vec![2], 4));
+    let incomplete = store
+        .begin_transition(
+            &upgraded.instance.id,
+            upgraded.instance.revision,
+            &third_artifact.artifact.metadata.sha256,
+            third_state.clone(),
+        )
+        .await
+        .unwrap();
+    let mut rejected = upgraded.instance.clone();
+    rejected.artifact_sha256 = third_artifact.artifact.metadata.sha256;
+    let error = store
+        .save_instance_with_state(
+            rejected,
+            upgraded.config_revision,
+            PluginStateCommit {
+                configuration: third_state,
+                transition_id: Some(incomplete.id.clone()),
+            },
+            &context(),
+        )
+        .await
+        .err()
+        .unwrap();
+    assert_eq!(error.kind(), AdminStoreErrorKind::Conflict);
+    let current = store.load_instances().await.unwrap();
+    assert_eq!(current.config_revision, upgraded.config_revision);
+    assert_eq!(
+        current.instances[0].artifact_sha256,
+        upgraded.instance.artifact_sha256
+    );
+    store.abort_transition(&incomplete.id).await.unwrap();
+    assert_eq!(
+        store
+            .get(&second_owner, "cache", "b")
+            .await
+            .unwrap()
+            .unwrap()
+            .value,
+        json!({"value": 20})
+    );
+    database.close().await;
+}
diff --git a/backend/crates/gateway-store/tests/postgres/pricing.rs b/backend/crates/gateway-store/tests/postgres/pricing.rs
index 54e91665e..47e9269e5 100644
--- a/backend/crates/gateway-store/tests/postgres/pricing.rs
+++ b/backend/crates/gateway-store/tests/postgres/pricing.rs
@@ -245,7 +245,11 @@ async fn concurrent_pricing_syncs_merge_selected_changes_and_remove_only_selecte
     let (first, second) = tokio::join!(
         settings.sync_pricing(patch(json!({"openai": {"model-a": price}})), &context),
         settings.sync_pricing(
-            patch(json!({"openai": {"model-b": price}, "xai": {"model-a": price}})),
+            patch(json!({
+                "openai": {"model-b": price},
+                "xai": {"model-a": price},
+                "example-plugin": {"model-c": price}
+            })),
             &context
         ),
     );
@@ -254,9 +258,16 @@ async fn concurrent_pricing_syncs_merge_selected_changes_and_remove_only_selecte
     assert_eq!(
         serde_json::to_value(&stored.synced).unwrap(),
         json!({
-            "openai": {"model-a": price, "model-b": price}, "xai": {"model-a": price}
+            "example-plugin": {"model-c": price},
+            "openai": {"model-a": price, "model-b": price},
+            "xai": {"model-a": price}
         })
     );
+    let snapshot = PgRuntimeSnapshotRepository::new(database.pool.clone())
+        .load_runtime_snapshot()
+        .await
+        .unwrap();
+    assert!(snapshot.settings.pricing["example-plugin"].contains_key("model-c"));
     settings
         .sync_pricing(patch(json!({"openai": {"model-a": null}})), &context)
         .await
@@ -265,7 +276,9 @@ async fn concurrent_pricing_syncs_merge_selected_changes_and_remove_only_selecte
     assert_eq!(
         serde_json::to_value(&stored.synced).unwrap(),
         json!({
-            "openai": {"model-b": price}, "xai": {"model-a": price}
+            "example-plugin": {"model-c": price},
+            "openai": {"model-b": price},
+            "xai": {"model-a": price}
         })
     );
     let before = stored;
@@ -273,7 +286,7 @@ async fn concurrent_pricing_syncs_merge_selected_changes_and_remove_only_selecte
         settings
             .sync_pricing(
                 patch(json!({
-                    "openai": {"model-b": null}, "invalid": {"model-c": price}
+                    "openai": {"model-b": null}, "__invalid": {"model-c": price}
                 })),
                 &context
             )
diff --git a/backend/crates/gateway-store/tests/postgres/provider_accounts/admin_adapter.rs b/backend/crates/gateway-store/tests/postgres/provider_accounts/admin_adapter.rs
new file mode 100644
index 000000000..a6fffc909
--- /dev/null
+++ b/backend/crates/gateway-store/tests/postgres/provider_accounts/admin_adapter.rs
@@ -0,0 +1,277 @@
+use super::*;
+
+#[tokio::test]
+async fn provider_filters_include_unregistered_accounts_even_on_an_empty_filtered_page() {
+    let Some(database) = TestDatabase::create("account_provider_filters").await else {
+        return;
+    };
+    let repository = PgProviderAccountRepository::new(database.pool.clone());
+    for (index, provider) in ["openai", "retired-plugin", "retired-plugin", "all"]
+        .into_iter()
+        .enumerate()
+    {
+        let mut record = account(
+            &format!("acct_filter_{index}"),
+            &format!("user-filter-{index}"),
+        );
+        record.provider_kind = provider.into();
+        repository.insert_provider_account(record).await.unwrap();
+    }
+    let query = AccountListQuery {
+        page: 2,
+        page_size: PageSize::new(1).unwrap(),
+        provider_kind: Some(ProviderKind::new("openai").unwrap()),
+        group_filter: None,
+        search: None,
+        status: None,
+        sort: None,
+    };
+    let store = admin_account_store(&database.pool);
+    let page = store
+        .list_accounts(query.clone(), Default::default())
+        .await
+        .unwrap();
+    assert!(page.items.is_empty());
+    assert_eq!(page.providers, ["all", "openai", "retired-plugin"]);
+    let literal = store
+        .list_accounts(
+            AccountListQuery {
+                page: 1,
+                provider_kind: Some(ProviderKind::new("all").unwrap()),
+                ..query.clone()
+            },
+            Default::default(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(literal.items.len(), 1);
+    assert_eq!(literal.total, 1);
+    sqlx::query("delete from provider_accounts")
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    let empty = store
+        .list_accounts(query, Default::default())
+        .await
+        .unwrap();
+    assert!(empty.providers.is_empty());
+    database.close().await;
+}
+
+#[tokio::test]
+async fn plugin_account_provider_filter_is_optional_and_applied_before_cursor_pagination() {
+    let Some(database) = TestDatabase::create("plugin_account_scope").await else {
+        return;
+    };
+    let repository = PgProviderAccountRepository::new(database.pool.clone());
+    for id in ["acct_plugin_a", "acct_plugin_b", "acct_plugin_c"] {
+        repository
+            .insert_provider_account(account(id, &format!("user-{id}")))
+            .await
+            .unwrap();
+    }
+    let mut other_provider = account("acct_plugin_other", "user-other");
+    other_provider.provider_kind = "xai".to_owned();
+    repository
+        .insert_provider_account(other_provider)
+        .await
+        .unwrap();
+    let store = admin_account_store(&database.pool);
+    let first = store
+        .list_plugin_accounts(PluginAccountListQuery {
+            provider_kind: Some(ProviderKind::new("openai").unwrap()),
+            cursor: None,
+            limit: PageSize::new(1).unwrap(),
+        })
+        .await
+        .unwrap();
+    assert_eq!(
+        first
+            .accounts
+            .iter()
+            .map(|account| account.id.as_str())
+            .collect::<Vec<_>>(),
+        ["acct_plugin_a"]
+    );
+    assert_eq!(
+        first.next_cursor.as_ref().map(ProviderAccountId::as_str),
+        Some("acct_plugin_a")
+    );
+
+    let second = store
+        .list_plugin_accounts(PluginAccountListQuery {
+            provider_kind: Some(ProviderKind::new("openai").unwrap()),
+            cursor: first.next_cursor,
+            limit: PageSize::new(1).unwrap(),
+        })
+        .await
+        .unwrap();
+    assert_eq!(
+        second
+            .accounts
+            .iter()
+            .map(|account| account.id.as_str())
+            .collect::<Vec<_>>(),
+        ["acct_plugin_b"]
+    );
+    assert_eq!(
+        second.next_cursor.as_ref().map(ProviderAccountId::as_str),
+        Some("acct_plugin_b")
+    );
+
+    // 未指定 Provider 时按全局账号 ID 跨 Provider 分页，Provider 归属来自持久记录。
+    let all = store
+        .list_plugin_accounts(PluginAccountListQuery {
+            provider_kind: None,
+            cursor: None,
+            limit: PageSize::new(16).unwrap(),
+        })
+        .await
+        .unwrap();
+    assert_eq!(
+        all.accounts
+            .iter()
+            .map(|account| account.id.as_str())
+            .collect::<Vec<_>>(),
+        [
+            "acct_plugin_a",
+            "acct_plugin_b",
+            "acct_plugin_c",
+            "acct_plugin_other"
+        ]
+    );
+    assert!(all.next_cursor.is_none());
+
+    database.close().await;
+}
+
+pub(super) fn credential(id: &str, user: &str) -> PreparedCredentialCreate {
+    PreparedCredentialCreate {
+        account_id: ProviderAccountId::new(id).unwrap(),
+        provider_kind: ProviderKind::new("example").unwrap(),
+        name: "login account".into(),
+        email: None,
+        upstream_user_id: Some(user.into()),
+        upstream_account_id: None,
+        plan_type: None,
+        authentication_kind: "oauth".into(),
+        provider_material: ProviderDocument::new(OpaqueProviderData::new(
+            json!({"access_token":"test-only"})
+                .as_object()
+                .unwrap()
+                .clone(),
+        )),
+        has_refresh_token: false,
+        access_token_expires_at: None,
+        next_refresh_at: None,
+        enabled: true,
+        credential_state: CredentialState::Ready,
+        credential_observed_at: Utc::now(),
+        outbound_proxy: None,
+        model_access: None,
+    }
+}
+
+pub(super) fn command(
+    credentials: Vec<PreparedCredentialCreate>,
+) -> (AuthorizationCommit, MutationContext) {
+    let context = MutationContext {
+        actor: MutationActor::System,
+        request_id: "authorization-batch".into(),
+    };
+    (
+        AuthorizationCommit {
+            key: gateway_admin::model::provider_credentials::AuthorizationReceiptKey::new(
+                ProviderKind::new("example").unwrap(),
+                &uuid::Uuid::new_v4().to_string(),
+                &context,
+            )
+            .unwrap(),
+            settings: None,
+            pending: PendingAuthorizationMutation::new(
+                ProviderKind::new("example").unwrap(),
+                AuthorizationMutationTarget::Create {
+                    name: "login".into(),
+                },
+                AuthorizationOwnerBinding::from_context(&context),
+            ),
+            credential: AuthorizationCredentialCommit::Create(credentials),
+        },
+        context,
+    )
+}
+
+#[tokio::test]
+async fn authorization_batch_returns_actual_ids_and_revisions_from_one_audited_transaction() {
+    let Some(database) = TestDatabase::create("authorization_batch").await else {
+        return;
+    };
+    let store = admin_account_store(&database.pool);
+    let (first, context) = command(vec![credential("acct_existing", "user-one")]);
+    store.commit_authorization(first, &context).await.unwrap();
+    let (batch, context) = command(vec![
+        credential("acct_candidate", "user-one"),
+        credential("acct_second", "user-two"),
+    ]);
+    let result = store
+        .commit_authorization(batch, &context)
+        .await
+        .unwrap()
+        .result;
+    assert_eq!(
+        result
+            .accounts
+            .iter()
+            .map(|account| (
+                account.account_id.as_str(),
+                account.credential_revision.unwrap().get()
+            ))
+            .collect::<Vec<_>>(),
+        [("acct_existing", 2), ("acct_second", 1)]
+    );
+    assert_eq!(
+        result.config_revision.get(),
+        current_revision(&database.pool).await as u64
+    );
+    let accounts: i64 = sqlx::query_scalar("select count(*) from provider_accounts")
+        .fetch_one(&database.pool)
+        .await
+        .unwrap();
+    assert_eq!(accounts, 2);
+    let audit: i64 =
+        sqlx::query_scalar("select count(*) from admin_audit_events where action = 'authorize'")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert_eq!(audit, 2, "每批一次审计，不能对每个账号分别提交");
+    database.close().await;
+}
+
+#[tokio::test]
+async fn authorization_batch_conflict_rolls_back_earlier_accounts_revision_and_audit() {
+    let Some(database) = TestDatabase::create("authorization_batch_rollback").await else {
+        return;
+    };
+    let store = admin_account_store(&database.pool);
+    let (seed, context) = command(vec![credential("acct_existing", "user-one")]);
+    store.commit_authorization(seed, &context).await.unwrap();
+    let before = current_revision(&database.pool).await;
+    let (batch, context) = command(vec![
+        credential("acct_new", "user-new"),
+        credential("acct_existing", "different-user"),
+    ]);
+    assert!(store.commit_authorization(batch, &context).await.is_err());
+    let accounts: Vec<String> = sqlx::query_scalar("select id from provider_accounts order by id")
+        .fetch_all(&database.pool)
+        .await
+        .unwrap();
+    assert_eq!(accounts, ["acct_existing"]);
+    assert_eq!(current_revision(&database.pool).await, before);
+    let audit: i64 =
+        sqlx::query_scalar("select count(*) from admin_audit_events where action = 'authorize'")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert_eq!(audit, 1);
+    database.close().await;
+}
diff --git a/backend/crates/gateway-store/tests/postgres/provider_accounts/authorization.rs b/backend/crates/gateway-store/tests/postgres/provider_accounts/authorization.rs
new file mode 100644
index 000000000..5451427fa
--- /dev/null
+++ b/backend/crates/gateway-store/tests/postgres/provider_accounts/authorization.rs
@@ -0,0 +1,222 @@
+use gateway_admin::model::provider_credentials::{
+    AuthorizationReceiptKey, PreparedCredentialRotationFacts,
+};
+
+use super::{
+    admin_adapter::{command, credential},
+    *,
+};
+
+#[tokio::test]
+async fn concurrent_authorization_retries_share_one_account_write_and_one_receipt() {
+    let Some(database) = TestDatabase::create("authorization_receipt_race").await else {
+        return;
+    };
+    let store = admin_account_store(&database.pool);
+    let (authorization, context) = command(vec![credential("acct_receipt", "receipt-user")]);
+    let key = authorization.key.clone();
+    let (first, second) = tokio::join!(
+        store.commit_authorization(authorization.clone(), &context),
+        store.commit_authorization(authorization, &context)
+    );
+    let (first, second) = (first.unwrap(), second.unwrap());
+    assert_eq!(first.result, second.result);
+    assert_ne!(first.newly_committed, second.newly_committed);
+    assert_eq!(
+        first.result.accounts[0].credential_revision.unwrap().get(),
+        1
+    );
+    let counts: (i64, i64, i64) = sqlx::query_as("select (select count(*) from provider_accounts), (select count(*) from admin_audit_events where action='authorize'), (select count(*) from authorization_receipts)")
+        .fetch_one(&database.pool).await.unwrap();
+    assert_eq!(counts, (1, 1, 1));
+    let restarted = admin_account_store(&database.pool);
+    assert_eq!(
+        restarted.authorization_receipt(&key).await.unwrap(),
+        Some(first.result.clone())
+    );
+    let outsider = MutationContext {
+        actor: MutationActor::AdminApiKey,
+        request_id: "different-owner".into(),
+    };
+    // 相同 flow 的另一身份不能读取账号结果，也不能另行提交同一个授权。
+    let (mut foreign, _) = command(vec![credential("acct_foreign", "foreign-user")]);
+    foreign.key = key.clone();
+    assert!(
+        restarted
+            .commit_authorization(foreign, &outsider)
+            .await
+            .is_err()
+    );
+    let stored: String =
+        sqlx::query_scalar("select to_jsonb(r)::text from authorization_receipts r")
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert!(!stored.contains("access_token") && !stored.contains("test-only"));
+    database.close().await;
+}
+
+#[tokio::test]
+async fn a_receipt_failure_rolls_back_accounts_audit_and_config_revision() {
+    let Some(database) = TestDatabase::create("authorization_receipt_failure").await else {
+        return;
+    };
+    let store = admin_account_store(&database.pool);
+    let before = current_revision(&database.pool).await;
+    sqlx::query("alter table authorization_receipts add constraint fail_receipt check (false)")
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    let (command, context) = command(vec![credential("acct_rollback", "rollback-user")]);
+    assert!(
+        store
+            .commit_authorization(command.clone(), &context)
+            .await
+            .is_err()
+    );
+    assert_eq!(current_revision(&database.pool).await, before);
+    let counts: (i64, i64, i64) = sqlx::query_as("select (select count(*) from provider_accounts), (select count(*) from admin_audit_events), (select count(*) from authorization_receipts)").fetch_one(&database.pool).await.unwrap();
+    assert_eq!(counts, (0, 0, 0));
+    assert!(
+        store
+            .authorization_receipt(&command.key)
+            .await
+            .unwrap()
+            .is_none()
+    );
+    sqlx::query("alter table authorization_receipts drop constraint fail_receipt")
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    assert!(
+        store
+            .commit_authorization(command, &context)
+            .await
+            .unwrap()
+            .newly_committed
+    );
+    database.close().await;
+}
+
+#[tokio::test]
+async fn expired_receipts_are_unreadable_and_reclaimed_without_removing_accounts() {
+    let Some(database) = TestDatabase::create("authorization_receipt_expiry").await else {
+        return;
+    };
+    let store = admin_account_store(&database.pool);
+    let (authorization, context) = command(vec![credential("acct_expired", "expired-user")]);
+    let key = authorization.key.clone();
+    store
+        .commit_authorization(authorization, &context)
+        .await
+        .unwrap();
+    sqlx::query("update authorization_receipts set created_at=now()-interval '25 hours', expires_at=now()-interval '1 hour'")
+        .execute(&database.pool).await.unwrap();
+    assert!(store.authorization_receipt(&key).await.unwrap().is_none());
+    let (next, context) = command(vec![credential("acct_next", "next-user")]);
+    let current = next.key.clone();
+    let committed = store.commit_authorization(next, &context).await.unwrap();
+    assert_eq!(
+        store.authorization_receipt(&current).await.unwrap(),
+        Some(committed.result)
+    );
+    let counts: (i64, i64) = sqlx::query_as("select (select count(*) from provider_accounts), (select count(*) from authorization_receipts)")
+        .fetch_one(&database.pool).await.unwrap();
+    assert_eq!(counts, (2, 1));
+    database.close().await;
+}
+
+#[tokio::test]
+async fn reauthorization_replay_keeps_the_committed_revision_and_later_profile_edits() {
+    let Some(database) = TestDatabase::create("reauthorization_receipt").await else {
+        return;
+    };
+    let store = admin_account_store(&database.pool);
+    let (seed, context) = command(vec![credential("acct_reauthorize", "reauthorize-user")]);
+    let receipt = store.commit_authorization(seed, &context).await.unwrap();
+    let id = receipt.result.accounts[0].account_id.clone();
+    let command = AuthorizationCommit {
+        key: AuthorizationReceiptKey::new(
+            ProviderKind::new("example").unwrap(),
+            "reauthorize-flow",
+            &context,
+        )
+        .unwrap(),
+        pending: PendingAuthorizationMutation::new(
+            ProviderKind::new("example").unwrap(),
+            AuthorizationMutationTarget::Reauthorize {
+                account_id: id.clone(),
+            },
+            AuthorizationOwnerBinding::from_context(&context),
+        ),
+        settings: None,
+        credential: AuthorizationCredentialCommit::Reauthorize(Box::new(
+            PreparedCredentialRotationFacts {
+                account_id: id.clone(),
+                provider_kind: ProviderKind::new("example").unwrap(),
+                expected_credential_revision: gateway_admin::model::Revision::new(1).unwrap(),
+                replacement_identity: None,
+                name: "remote profile".into(),
+                email: None,
+                plan_type: None,
+                preserve_profile: true,
+                provider_material: ProviderDocument::new(OpaqueProviderData::new(
+                    json!({"access_token":"rotated-test-only"})
+                        .as_object()
+                        .unwrap()
+                        .clone(),
+                )),
+                has_refresh_token: false,
+                access_token_expires_at: None,
+                next_refresh_at: None,
+            },
+        )),
+    };
+    let committed = store
+        .commit_authorization(command.clone(), &context)
+        .await
+        .unwrap();
+    sqlx::query("update provider_accounts set name='later profile' where id=$1")
+        .bind(id.as_str())
+        .execute(&database.pool)
+        .await
+        .unwrap();
+    let replayed = store
+        .commit_authorization(command.clone(), &context)
+        .await
+        .unwrap();
+    assert!(!replayed.newly_committed);
+    assert_eq!(replayed.result, committed.result);
+    let account: (String, i64) =
+        sqlx::query_as("select name, credential_revision from provider_accounts where id=$1")
+            .bind(id.as_str())
+            .fetch_one(&database.pool)
+            .await
+            .unwrap();
+    assert_eq!(account, ("later profile".into(), 2));
+    let outsider = MutationContext {
+        actor: MutationActor::AdminApiKey,
+        request_id: "outsider".into(),
+    };
+    let key = AuthorizationReceiptKey::new(
+        ProviderKind::new("example").unwrap(),
+        "reauthorize-flow",
+        &outsider,
+    )
+    .unwrap();
+    assert!(store.authorization_receipt(&key).await.is_err());
+    let another = AuthorizationReceiptKey::new(
+        ProviderKind::new("other").unwrap(),
+        "reauthorize-flow",
+        &context,
+    )
+    .unwrap();
+    assert!(
+        store
+            .authorization_receipt(&another)
+            .await
+            .unwrap()
+            .is_none()
+    );
+    database.close().await;
+}
diff --git a/backend/crates/gateway-store/tests/postgres/provider_accounts/mod.rs b/backend/crates/gateway-store/tests/postgres/provider_accounts/mod.rs
index ea19dba85..78b47ab9e 100644
--- a/backend/crates/gateway-store/tests/postgres/provider_accounts/mod.rs
+++ b/backend/crates/gateway-store/tests/postgres/provider_accounts/mod.rs
@@ -4,6 +4,8 @@ use std::{
     time::{Duration, SystemTime},
 };
 
+mod admin_adapter;
+mod authorization;
 mod quota_forecast;
 mod timestamps;
 
@@ -19,8 +21,8 @@ use gateway_admin::{
         observability::TimeRange,
         provider_credentials::{
             AuthorizationCommit, AuthorizationCredentialCommit, AuthorizationMutationTarget,
-            AuthorizationOwnerBinding, PendingAuthorizationMutation, PreparedCredentialCreate,
-            ProviderDocument,
+            AuthorizationOwnerBinding, PendingAuthorizationMutation, PluginAccountListQuery,
+            PreparedCredentialCreate, ProviderDocument,
         },
     },
     ports::store::AccountStore,
@@ -771,6 +773,7 @@ async fn terminal_admin_list_filters_and_sorts_before_pagination_with_retained_u
         .expect("sort accounts by retained usage");
     assert_eq!(usage_page.config_revision.get(), 1);
     assert_eq!(usage_page.total, 6);
+    assert_eq!(usage_page.providers, ["openai", "xai"]);
     assert_eq!(usage_page.summary.total, 6);
     assert_eq!(usage_page.summary.normal, 1);
     assert_eq!(usage_page.summary.quota_exhausted, 2);
@@ -838,6 +841,7 @@ async fn terminal_admin_list_filters_and_sorts_before_pagination_with_retained_u
         .expect("filter account directory");
     assert_eq!(filtered.total, 1);
     assert_eq!(filtered.summary, usage_page.summary);
+    assert_eq!(filtered.providers, usage_page.providers);
     assert_eq!(filtered.items[0].account.id, "acct_alpha");
     assert_eq!(filtered.items[0].account.provider_kind.as_str(), "openai");
 
@@ -1961,6 +1965,12 @@ async fn authorization_create_returns_existing_account_id_when_identity_is_upser
     let result = admin_account_store(&database.pool)
         .commit_authorization(
             AuthorizationCommit {
+                key: gateway_admin::model::provider_credentials::AuthorizationReceiptKey::new(
+                    provider_kind.clone(),
+                    "authorization-upsert",
+                    &context,
+                )
+                .unwrap(),
                 settings: Some(gateway_admin::model::accounts::AccountImportSettings {
                     notes: Some("  OAuth 新建备注  ".to_owned()),
                     model_access: Default::default(),
@@ -1976,7 +1986,7 @@ async fn authorization_create_returns_existing_account_id_when_identity_is_upser
                     },
                     AuthorizationOwnerBinding::from_context(&context),
                 ),
-                credential: AuthorizationCredentialCommit::Create(PreparedCredentialCreate {
+                credential: AuthorizationCredentialCommit::Create(vec![PreparedCredentialCreate {
                     model_access: Default::default(),
                     outbound_proxy: None,
                     account_id: ProviderAccountId::new("acct_authorization_candidate")
@@ -1997,17 +2007,21 @@ async fn authorization_create_returns_existing_account_id_when_identity_is_upser
                     enabled: true,
                     credential_state: CredentialState::Ready,
                     credential_observed_at: Utc::now(),
-                }),
+                }]),
             },
             &context,
         )
         .await
         .expect("authorize existing identity");
 
+    let result = result.result;
+
     assert_eq!(
         (
-            result.account_id.as_str(),
-            result.credential_revision.map(|revision| revision.get()),
+            result.accounts[0].account_id.as_str(),
+            result.accounts[0]
+                .credential_revision
+                .map(|revision| revision.get()),
         ),
         ("acct_authorization_existing", Some(2)),
     );
diff --git a/backend/crates/gateway-store/tests/postgres/proxies.rs b/backend/crates/gateway-store/tests/postgres/proxies.rs
index fc39be7c5..65e2c88c6 100644
--- a/backend/crates/gateway-store/tests/postgres/proxies.rs
+++ b/backend/crates/gateway-store/tests/postgres/proxies.rs
@@ -857,33 +857,26 @@ async fn legacy_urls_join_one_catalog_entry_and_invalid_batch_rolls_back() {
 
 #[tokio::test]
 async fn migration_backfills_shared_proxies_without_changing_credentials() {
-    let Some(database) = TestDatabase::create("proxy_backfill").await else {
+    let Some(database) = TestDatabase::create_through("proxy_backfill", 4).await else {
         return;
     };
-    let accounts = PgProviderAccountRepository::new(database.pool.clone());
+    // 从真实旧 schema 正向升级，不拆卸最新结构，避免遗漏后续增加的引用约束。
     for id in ["acct_one", "acct_two", "acct_direct"] {
-        accounts
-            .insert_provider_account(account(id, id))
-            .await
-            .unwrap();
+        let proxy_url = (id != "acct_direct").then_some("http://user:secret@127.0.0.1:8080/");
+        sqlx::query(
+            "insert into provider_accounts (
+                id,provider_kind,name,authentication_kind,provider_credentials_json,
+                has_refresh_token,credential_observed_at,created_at,updated_at,outbound_proxy_url
+             ) values ($1,'openai',$1,'oauth','{}',false,now(),now(),now(),$2)",
+        )
+        .bind(id)
+        .bind(proxy_url)
+        .execute(&database.pool)
+        .await
+        .unwrap();
     }
-    // 回退到迁移前的结构，随后完整重放同一份位置迁移。
-    sqlx::raw_sql("alter table runtime_settings drop column request_location_json, drop column request_location_enabled;
-        alter table provider_accounts drop column outbound_proxy_id; drop table outbound_proxies;
-        update provider_accounts set outbound_proxy_url = 'http://user:secret@127.0.0.1:8080/' where id <> 'acct_direct';")
-        .execute(&database.pool).await.unwrap();
-    sqlx::raw_sql(include_str!(
-        "../../../../migrations/0005_managed_outbound_proxies.sql"
-    ))
-    .execute(&database.pool)
-    .await
-    .unwrap();
-    sqlx::raw_sql(include_str!(
-        "../../../../migrations/0011_proxy_request_location.sql"
-    ))
-    .execute(&database.pool)
-    .await
-    .unwrap();
+    super::TEST_MIGRATOR.run(&database.pool).await.unwrap();
+    let accounts = PgProviderAccountRepository::new(database.pool.clone());
     let inherited = gateway_core::account::ProviderAccountStore::list_accounts(&accounts)
         .await
         .unwrap();
diff --git a/backend/crates/gateway-store/tests/postgres/runtime_settings.rs b/backend/crates/gateway-store/tests/postgres/runtime_settings.rs
index e11693bfb..442e7058f 100644
--- a/backend/crates/gateway-store/tests/postgres/runtime_settings.rs
+++ b/backend/crates/gateway-store/tests/postgres/runtime_settings.rs
@@ -9,8 +9,7 @@ use super::TestDatabase;
 
 fn settings_with_margin(refresh_margin_seconds: u64) -> RuntimeSettingsUpdate {
     RuntimeSettingsUpdate {
-        openai_client_profile: None,
-        xai_client_profile: None,
+        request_profile_updates: BTreeMap::new(),
         request_location_enabled: false,
         request_location: Default::default(),
         admin_api_key: None,
@@ -527,11 +526,14 @@ async fn request_profile_initialization_is_idempotent_and_old_updates_preserve_i
             .load_runtime_settings()
             .await
             .unwrap()
-            .openai_client_profile,
-        Some(initial)
+            .request_profiles
+            .get(&provider),
+        Some(&initial)
     );
     let mut update = settings_with_margin(3600);
-    update.openai_client_profile = Some(document("edited"));
+    update
+        .request_profile_updates
+        .insert(provider.clone(), Some(document("edited")));
     repository.update_runtime_settings(update).await.unwrap();
     assert_eq!(
         repository
@@ -543,6 +545,50 @@ async fn request_profile_initialization_is_idempotent_and_old_updates_preserve_i
     database.close().await;
 }
 
+#[tokio::test]
+async fn request_profile_deletion_is_explicit_and_preserves_other_profiles() {
+    use gateway_core::{
+        account::OpaqueProviderData, provider_ports::ProviderRuntimePolicyPort,
+        routing::ProviderKind,
+    };
+    let Some(database) = TestDatabase::create("request_profile_deletion").await else {
+        return;
+    };
+    let repository = PgRuntimeSettingsRepository::new(database.pool.clone());
+    let kept = ProviderKind::new("provider.kept").unwrap();
+    let removed = ProviderKind::new("provider.removed").unwrap();
+    let profile = |marker: &str| {
+        OpaqueProviderData::new(
+            serde_json::json!({"marker":marker})
+                .as_object()
+                .unwrap()
+                .clone(),
+        )
+    };
+    repository
+        .initialize_request_profile(&kept, profile("kept"))
+        .await
+        .unwrap();
+    repository
+        .initialize_request_profile(&removed, profile("removed"))
+        .await
+        .unwrap();
+
+    let mut update = settings_with_margin(3_600);
+    update.request_profile_updates.insert(removed.clone(), None);
+    repository.update_runtime_settings(update).await.unwrap();
+    let settings = repository.load_runtime_settings().await.unwrap();
+
+    assert_eq!(
+        (
+            settings.request_profiles.get(&kept),
+            settings.request_profiles.get(&removed),
+        ),
+        (Some(&profile("kept")), None),
+    );
+    database.close().await;
+}
+
 #[tokio::test]
 async fn xai_profile_initialization_and_updates_preserve_other_providers() {
     use gateway_core::{
@@ -574,15 +620,30 @@ async fn xai_profile_initialization_and_updates_preserve_other_providers() {
         document("initial")
     );
     let mut update = settings_with_margin(3600);
-    update.openai_client_profile = Some(document("openai"));
-    update.xai_client_profile = Some(document("xai"));
+    update.request_profile_updates.insert(
+        ProviderKind::new("openai").unwrap(),
+        Some(document("openai")),
+    );
+    update
+        .request_profile_updates
+        .insert(provider.clone(), Some(document("xai")));
     repository.update_runtime_settings(update).await.unwrap();
     let mut update = settings_with_margin(3600);
-    update.xai_client_profile = Some(document("edited"));
+    update
+        .request_profile_updates
+        .insert(provider.clone(), Some(document("edited")));
     repository.update_runtime_settings(update).await.unwrap();
     let settings = repository.load_runtime_settings().await.unwrap();
-    assert_eq!(settings.openai_client_profile, Some(document("openai")));
-    assert_eq!(settings.xai_client_profile, Some(document("edited")));
+    assert_eq!(
+        settings
+            .request_profiles
+            .get(&ProviderKind::new("openai").unwrap()),
+        Some(&document("openai"))
+    );
+    assert_eq!(
+        settings.request_profiles.get(&provider),
+        Some(&document("edited"))
+    );
     assert_eq!(
         repository
             .initialize_request_profile(&provider, document("old-yaml"))
@@ -592,3 +653,69 @@ async fn xai_profile_initialization_and_updates_preserve_other_providers() {
     );
     database.close().await;
 }
+
+#[tokio::test]
+async fn request_profile_projection_is_revision_consistent_and_includes_key_overrides() {
+    use gateway_core::{
+        account::OpaqueProviderData,
+        provider_ports::{ProviderRuntimePolicyPort, ProviderStoreErrorKind},
+        routing::ProviderKind,
+    };
+    let Some(database) = TestDatabase::create("request_profile_projection").await else {
+        return;
+    };
+    let repository = PgRuntimeSettingsRepository::new(database.pool.clone());
+    let provider = ProviderKind::new("provider.example").unwrap();
+    let document = |marker: &str| {
+        OpaqueProviderData::new(
+            serde_json::json!({"marker":marker})
+                .as_object()
+                .unwrap()
+                .clone(),
+        )
+    };
+    let mut update = settings_with_margin(3600);
+    update
+        .request_profile_updates
+        .insert(provider.clone(), Some(document("global")));
+    repository.update_runtime_settings(update).await.unwrap();
+    sqlx::query(
+        "insert into client_api_keys (
+           id, name, key, enabled, max_concurrency, requests_per_minute,
+           provider_request_profiles_json, created_at, updated_at
+         ) values ($1, $2, $3, true, 0, 0, $4::jsonb, now(), now())",
+    )
+    .bind("key_profile_projection")
+    .bind("profile projection")
+    .bind("synthetic-profile-projection-secret")
+    .bind(sqlx::types::Json(serde_json::json!({
+        "provider.example":{"marker":"key"}
+    })))
+    .execute(&database.pool)
+    .await
+    .unwrap();
+    let revision = repository
+        .load_runtime_settings()
+        .await
+        .unwrap()
+        .config_revision;
+    let revision = gateway_core::routing::ConfigRevision::new(revision.get()).unwrap();
+    let profiles = repository
+        .load_request_profile_configurations(revision, &provider)
+        .await
+        .unwrap();
+    assert_eq!(profiles.len(), 2);
+    assert!(profiles.contains(&document("global")));
+    assert!(profiles.contains(&document("key")));
+
+    repository
+        .update_runtime_settings(settings_with_margin(7200))
+        .await
+        .unwrap();
+    let error = repository
+        .load_request_profile_configurations(revision, &provider)
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), ProviderStoreErrorKind::Conflict);
+    database.close().await;
+}
diff --git a/backend/crates/gateway-store/tests/redis/coordination_buffer.rs b/backend/crates/gateway-store/tests/redis/coordination_buffer.rs
index ff5a15e4f..2a12e308b 100644
--- a/backend/crates/gateway-store/tests/redis/coordination_buffer.rs
+++ b/backend/crates/gateway-store/tests/redis/coordination_buffer.rs
@@ -1,3 +1,4 @@
+use std::collections::BTreeSet;
 use std::num::NonZeroUsize;
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
@@ -6,13 +7,13 @@ use futures::future::BoxFuture;
 use gateway_core::engine::ModelRequestId;
 use gateway_core::engine::admission::{
     ClientAdmissionDecision, ClientAdmissionError, ClientAdmissionPort, ClientAdmissionRecovery,
-    ClientAdmissionRequest, ClientAdmissionRestoreResult,
+    ClientAdmissionRejection, ClientAdmissionRequest, ClientAdmissionRestoreResult,
 };
 use gateway_core::engine::execution::{
     ProviderCircuitDecision, ProviderCircuitError, ProviderCircuitPort,
 };
 use gateway_core::lifecycle::CancellationToken;
-use gateway_core::policy::ClientApiKeyId;
+use gateway_core::policy::{ClientApiKeyId, RateLimits};
 use gateway_core::routing::ProviderKind;
 use gateway_store::redis::{BufferedClientAdmissionPort, BufferedProviderCircuitPort};
 
@@ -101,6 +102,70 @@ impl ProviderCircuitPort for RecordingCoordination {
     }
 }
 
+struct CapacityCoordination {
+    active: Mutex<BTreeSet<String>>,
+    maximum: usize,
+}
+
+impl CapacityCoordination {
+    fn new(maximum: usize) -> Self {
+        Self {
+            active: Mutex::new(BTreeSet::new()),
+            maximum,
+        }
+    }
+
+    fn active(&self) -> usize {
+        self.active.lock().expect("active admission lock").len()
+    }
+}
+
+impl ClientAdmissionPort for CapacityCoordination {
+    fn abandon(&self, _: &ClientApiKeyId, request: &ModelRequestId) {
+        self.active
+            .lock()
+            .expect("active admission lock")
+            .remove(request.as_str());
+    }
+
+    fn admit(
+        &self,
+        request: ClientAdmissionRequest,
+    ) -> BoxFuture<'_, Result<ClientAdmissionDecision, ClientAdmissionError>> {
+        Box::pin(async move {
+            let mut active = self.active.lock().expect("active admission lock");
+            if active.len() >= self.maximum {
+                return Ok(ClientAdmissionDecision::Rejected(
+                    ClientAdmissionRejection::ConcurrencyLimited,
+                ));
+            }
+            active.insert(request.model_request_id.as_str().to_owned());
+            Ok(ClientAdmissionDecision::Granted)
+        })
+    }
+
+    fn release<'a>(
+        &'a self,
+        _: &'a ClientApiKeyId,
+        request: &'a ModelRequestId,
+    ) -> BoxFuture<'a, Result<bool, ClientAdmissionError>> {
+        Box::pin(async move {
+            Ok(self
+                .active
+                .lock()
+                .expect("active admission lock")
+                .remove(request.as_str()))
+        })
+    }
+
+    fn restore(
+        &self,
+        _: ClientAdmissionRecovery,
+    ) -> BoxFuture<'_, Result<ClientAdmissionRestoreResult, ClientAdmissionError>> {
+        Box::pin(async { Ok(ClientAdmissionRestoreResult::default()) })
+    }
+}
+
 #[tokio::test]
 async fn full_recoverable_coordination_queues_should_drop_writes_without_waiting() {
     let inner = Arc::new(RecordingCoordination::default());
@@ -189,6 +254,75 @@ async fn redis_coordination_writers_should_flush_each_side_effect() {
     assert_eq!(operations, ["admission", "circuit_success"]);
 }
 
+#[tokio::test]
+async fn awaited_buffered_release_should_not_publish_capacity_before_writer_runs() {
+    let inner = Arc::new(CapacityCoordination::new(8));
+    let (admissions, admission_writer) = BufferedClientAdmissionPort::with_capacity(
+        inner.clone(),
+        NonZeroUsize::new(8).expect("capacity"),
+    );
+    let client = ClientApiKeyId::new("key_capacity_handoff").expect("client key");
+    let request = |index| ClientAdmissionRequest {
+        model_request_id: ModelRequestId::new(format!("req_capacity_handoff_{index}"))
+            .expect("request ID"),
+        client_api_key_id: client.clone(),
+        lease_ttl: Duration::from_secs(60),
+        allow_concurrency_acquire: true,
+        limits: RateLimits {
+            max_concurrency: 8,
+            requests_per_minute: 0,
+        },
+    };
+
+    let mut granted = Vec::new();
+    for index in 0..8 {
+        let request = request(index);
+        assert_eq!(
+            admissions.admit(request.clone()).await.expect("admit"),
+            ClientAdmissionDecision::Granted
+        );
+        granted.push(request.model_request_id);
+    }
+    assert_eq!(inner.active(), 8);
+
+    assert!(
+        admissions
+            .release(&client, &granted[0])
+            .await
+            .expect("enqueue release")
+    );
+    assert_eq!(inner.active(), 8, "await only confirms queue admission");
+    let replacement = request(8);
+    assert_eq!(
+        admissions
+            .admit(replacement.clone())
+            .await
+            .expect("admit before writer"),
+        ClientAdmissionDecision::Rejected(ClientAdmissionRejection::ConcurrencyLimited)
+    );
+
+    let cancellation = CancellationToken::new();
+    let task = spawn_writer(Arc::new(admission_writer), cancellation.clone());
+    tokio::time::timeout(Duration::from_secs(1), async {
+        while inner.active() == 8 {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .expect("writer should publish released capacity");
+    assert_eq!(
+        admissions
+            .admit(replacement)
+            .await
+            .expect("admit after writer"),
+        ClientAdmissionDecision::Granted
+    );
+    cancellation.cancel();
+    task.await
+        .expect("admission writer task")
+        .expect("admission writer cancellation");
+}
+
 fn spawn_writer<T>(
     writer: Arc<T>,
     cancellation: CancellationToken,
diff --git a/backend/crates/providers/openai/src/admin.rs b/backend/crates/providers/openai/src/admin.rs
index 6142e3677..b7dcd2fd5 100644
--- a/backend/crates/providers/openai/src/admin.rs
+++ b/backend/crates/providers/openai/src/admin.rs
@@ -163,6 +163,23 @@ impl OpenAiAdminProvider {
 
 #[async_trait]
 impl ProviderAdmin for OpenAiAdminProvider {
+    fn account_capabilities(
+        &self,
+        _account_id: &ProviderAccountId,
+        authentication_kind: &str,
+    ) -> gateway_admin::model::provider_capabilities::ProviderAccountCapabilities {
+        let oauth = authentication_kind == crate::credential::CODEX_AUTHENTICATION_KIND_OAUTH;
+        gateway_admin::model::provider_capabilities::ProviderAccountCapabilities {
+            quota: oauth,
+            quota_refresh: oauth,
+            profile: oauth,
+            subscription: oauth,
+            avatar: oauth,
+            reset_credits: oauth,
+            consume_reset_credit: oauth,
+        }
+    }
+
     fn pricing_catalog(&self) -> gateway_admin::model::pricing::ProviderPricingCatalog {
         crate::transport::usage::pricing_catalog()
     }
@@ -184,6 +201,23 @@ impl ProviderAdmin for OpenAiAdminProvider {
             .map_err(map_client_profile_error)
     }
 
+    fn credential_capabilities(
+        &self,
+    ) -> gateway_admin::model::provider_capabilities::ProviderCredentialCapabilities {
+        use gateway_admin::model::provider_capabilities::{
+            AuthorizationCompletion, ProviderCredentialCapabilities, ProviderLoginCapability,
+        };
+        ProviderCredentialCapabilities {
+            import: Some(serde_json::json!({"type":"object"})),
+            login: Some(ProviderLoginCapability {
+                input_schema: serde_json::json!({"type":"object", "additionalProperties":false}),
+                completion: AuthorizationCompletion::Callback,
+            }),
+            refresh: true,
+            export: true,
+        }
+    }
+
     fn provider_kind(&self) -> &ProviderKind {
         &self.provider_kind
     }
@@ -230,7 +264,7 @@ impl ProviderAdmin for OpenAiAdminProvider {
         }
     }
 
-    fn connection_test_operation(
+    async fn connection_test_operation(
         &self,
         upstream_model: &UpstreamModelId,
         input_text: &str,
@@ -429,8 +463,17 @@ impl ProviderAdmin for OpenAiAdminProvider {
 
     async fn start_authorization(
         &self,
-        pending: PendingAuthorizationMutation,
+        command: gateway_admin::model::provider_credentials::PrepareAuthorization,
     ) -> Result<AuthorizationStarted, ProviderAdminError> {
+        if !command
+            .input
+            .expose_to_provider()
+            .expose_to_provider()
+            .is_empty()
+        {
+            return Err(provider_admin_error(ProviderAdminErrorKind::Invalid));
+        }
+        let pending = command.pending;
         if pending.provider_kind() != &self.provider_kind {
             return Err(provider_admin_error(ProviderAdminErrorKind::Invalid));
         }
@@ -474,20 +517,21 @@ impl ProviderAdmin for OpenAiAdminProvider {
             })
             .map_err(map_oauth_error)?;
         let (mutation, completed_credential, authorization_guard) = completed.into_parts();
-        let credential = match (mutation.target(), completed_credential) {
-            (
-                AuthorizationMutationTarget::Create { .. },
-                CompletedCodexOAuthCredential::Create(credential),
-            ) => {
-                prepared_create(credential, Utc::now()).map(PreparedAuthorizationCredential::Create)
-            }
-            (
-                AuthorizationMutationTarget::Reauthorize { .. },
-                CompletedCodexOAuthCredential::Reauthorize(credential),
-            ) => prepared_rotation(credential, mutation.provider_kind().clone())
-                .map(PreparedAuthorizationCredential::Reauthorize),
-            _ => Err(provider_admin_error(ProviderAdminErrorKind::Internal)),
-        };
+        let credential =
+            match (mutation.target(), completed_credential) {
+                (
+                    AuthorizationMutationTarget::Create { .. },
+                    CompletedCodexOAuthCredential::Create(credential),
+                ) => prepared_create(credential, Utc::now())
+                    .map(|credential| PreparedAuthorizationCredential::Create(vec![credential])),
+                (
+                    AuthorizationMutationTarget::Reauthorize { .. },
+                    CompletedCodexOAuthCredential::Reauthorize(credential),
+                ) => prepared_rotation(credential, mutation.provider_kind().clone()).map(
+                    |credential| PreparedAuthorizationCredential::Reauthorize(Box::new(credential)),
+                ),
+                _ => Err(provider_admin_error(ProviderAdminErrorKind::Internal)),
+            };
         let credential = match credential {
             Ok(credential) => credential,
             Err(error) => {
diff --git a/backend/crates/providers/openai/src/credential/selector.rs b/backend/crates/providers/openai/src/credential/selector.rs
index 0b11637dc..7c2f7b01a 100644
--- a/backend/crates/providers/openai/src/credential/selector.rs
+++ b/backend/crates/providers/openai/src/credential/selector.rs
@@ -12,7 +12,7 @@ use gateway_core::account::{
     ProviderAccountId, QuotaEvidence,
 };
 use gateway_core::concurrency::{CapacityWait, ConcurrencyWaitQueue, QueueRejection};
-use gateway_core::engine::{AttemptContext, ContinuationAttempt};
+use gateway_core::engine::{AttemptContext, ContinuationAttempt, policy::AccountPolicyError};
 use gateway_core::provider_ports::{
     ProviderLeaseAcquisition, ProviderLeaseGuard, ProviderLeasePort, ProviderLeaseRequest,
     ProviderSchedulingLeaseRequest, ProviderSessionAffinityKey, ProviderSessionAffinityPort,
@@ -141,6 +141,7 @@ enum AffinityEscapeReason {
     LeaseSaturated,
     HigherPriority,
     PinnedAccount,
+    SchedulingPolicy,
     SelectionInvariant,
 }
 
@@ -153,6 +154,7 @@ impl AffinityEscapeReason {
             Self::LeaseSaturated => "lease_saturated",
             Self::HigherPriority => "higher_priority",
             Self::PinnedAccount => "pinned_account",
+            Self::SchedulingPolicy => "scheduling_policy",
             Self::SelectionInvariant => "selection_invariant",
         }
     }
@@ -206,6 +208,9 @@ impl AffinitySelection {
         }
         match selection {
             PreferredAccountSelection::Hit => {}
+            PreferredAccountSelection::OverriddenByPolicy => {
+                self.escape(AffinityEscapeReason::SchedulingPolicy);
+            }
             PreferredAccountSelection::Blocked(AccountSchedulingBlocker::ConcurrencyLimit) => {
                 self.escape(AffinityEscapeReason::LeaseSaturated);
             }
@@ -321,6 +326,42 @@ impl CodexCredentialSelector {
         .await
     }
 
+    /// 中间件完成请求改写后，用真实 OpenAI 会话事实复验已持有的租约。
+    ///
+    /// 此处只复用既有亲和与 cyber-policy 端口，不再次选号；冲突必须在发送前失败，
+    /// 避免同一 attempt 持有旧租约时重入账号选择。
+    pub(crate) async fn validate_translated_selection(
+        &self,
+        lease: &mut CodexCredentialLease,
+        session_affinity: Option<&CodexSessionAffinity>,
+        cyber_policy_session_key: Option<&ProviderSessionAffinityKey>,
+    ) -> Result<(), CredentialSelectionError> {
+        let selected_account = lease.account.id().clone();
+        if let Some(affinity) = session_affinity {
+            if self
+                .claim_initial_session_affinity(affinity.key(), &selected_account)
+                .await
+                .is_some_and(|effective| effective != selected_account)
+            {
+                return Err(CredentialSelectionError::NoEligibleCredential);
+            }
+            lease.affinity_expected_account_id = selected_account.clone();
+        }
+
+        let cyber_policy_scope = self
+            .prepare_cyber_policy_scope(cyber_policy_session_key)
+            .await;
+        if cyber_policy_scope
+            .as_ref()
+            .and_then(|scope| scope.state.as_ref())
+            .is_some_and(|state| state.excluded_accounts().contains(&selected_account))
+        {
+            return Err(CredentialSelectionError::NoEligibleCredential);
+        }
+        lease.cyber_policy_scope = cyber_policy_scope;
+        Ok(())
+    }
+
     /// 为不属于 Responses 文本模型目录的 Provider 原生端点选择账号。
     ///
     /// 账号范围、健康度、配额、并发租约、cookie 与认证准备仍走同一套选择链路；
@@ -573,7 +614,20 @@ impl CodexCredentialSelector {
                             .insert(candidate.account.id().clone());
                     }
                 }
-                let selection = AccountSelector.select(&candidates, &context);
+                let selection = match request
+                    .attempt
+                    .select_account(&self.provider_kind, upstream_model, &candidates, &context)
+                    .await
+                {
+                    Ok(selection) => selection,
+                    Err(AccountPolicyError::StaleCandidate) => continue 'capacity,
+                    Err(AccountPolicyError::Rejected) => {
+                        return Err(CredentialSelectionError::PolicyRejected);
+                    }
+                    Err(AccountPolicyError::Fault) => {
+                        return Err(CredentialSelectionError::PolicyUnavailable);
+                    }
+                };
                 request.attempt.trace().account_selection(
                     &candidates,
                     &context,
@@ -1527,6 +1581,10 @@ pub enum CredentialSelectionError {
     Coordinator,
     #[error("Codex Cookie policy rejected the value")]
     CookiePolicy,
+    #[error("account scheduling policy rejected the request")]
+    PolicyRejected,
+    #[error("account scheduling policy is unavailable")]
+    PolicyUnavailable,
 }
 
 impl From<CredentialRepositoryError> for CredentialSelectionError {
diff --git a/backend/crates/providers/openai/src/provider/execution.rs b/backend/crates/providers/openai/src/provider/execution.rs
index f3d024205..4310f8c37 100644
--- a/backend/crates/providers/openai/src/provider/execution.rs
+++ b/backend/crates/providers/openai/src/provider/execution.rs
@@ -6,7 +6,7 @@ use super::*;
 
 impl CodexProvider {
     pub(super) async fn execute_image(
-        &self,
+        self: Arc<Self>,
         image: &ImageRequest,
         candidate: &ProviderCandidate,
         context: AttemptContext,
@@ -38,6 +38,7 @@ impl CodexProvider {
         self.execute_raw_json_endpoint(
             context,
             RawJsonEndpointRequest {
+                operation: Operation::GenerateImage(image.clone()),
                 response_origin,
                 endpoint_path,
                 body: image.payload().body().clone(),
@@ -50,7 +51,7 @@ impl CodexProvider {
     }
 
     pub(super) async fn execute_search(
-        &self,
+        self: Arc<Self>,
         search: &StandaloneSearchRequest,
         candidate: &ProviderCandidate,
         context: AttemptContext,
@@ -72,10 +73,12 @@ impl CodexProvider {
             context.client_api_key_ref(),
             "id",
         );
+        let response_origin = self.search_url.clone();
         self.execute_raw_json_endpoint(
             context,
             RawJsonEndpointRequest {
-                response_origin: self.search_url.clone(),
+                operation: Operation::Search(search.clone()),
+                response_origin,
                 endpoint_path: CODEX_ALPHA_SEARCH_PATH,
                 body: search.payload().body().clone(),
                 image_turn_id: None,
@@ -87,7 +90,7 @@ impl CodexProvider {
     }
 
     async fn execute_raw_json_endpoint(
-        &self,
+        self: Arc<Self>,
         context: AttemptContext,
         request: RawJsonEndpointRequest,
     ) -> Result<ProviderStream, ProviderError> {
@@ -104,6 +107,91 @@ impl CodexProvider {
         let account_selection_wait_ms =
             u64::try_from(selection_started_at.elapsed().as_millis()).unwrap_or(u64::MAX);
         let lease = Arc::new(lease);
+        let operation = request.operation.clone();
+        let provider_kind = ProviderKind::new(PROVIDER_NAME)
+            .map_err(|_| provider_error(ProviderErrorKind::Protocol, UpstreamSendState::NotSent))?;
+        let account_id = lease.account_id().clone();
+        let provider = Arc::clone(&self);
+        let terminal_context = context.clone();
+        context
+            .execute_middleware(
+                operation,
+                provider_kind,
+                None,
+                account_id,
+                Box::new(move |operation, middleware_headers| {
+                    Box::pin(async move {
+                        provider
+                            .execute_selected_raw_json_endpoint(
+                                terminal_context,
+                                operation,
+                                middleware_headers,
+                                request,
+                                lease,
+                                account_selection_wait_ms,
+                            )
+                            .await
+                    })
+                }),
+            )
+            .await
+    }
+
+    async fn execute_selected_raw_json_endpoint(
+        self: Arc<Self>,
+        context: AttemptContext,
+        operation: Operation,
+        middleware_headers: Vec<MiddlewareHeader>,
+        mut request: RawJsonEndpointRequest,
+        lease: Arc<CodexCredentialLease>,
+        account_selection_wait_ms: u64,
+    ) -> Result<ProviderStream, ProviderError> {
+        match operation {
+            Operation::GenerateImage(image) => {
+                let Operation::GenerateImage(original) = &request.operation else {
+                    return Err(provider_error(
+                        ProviderErrorKind::InvalidRequest,
+                        UpstreamSendState::NotSent,
+                    ));
+                };
+                if image.kind() != original.kind() || image.payload().protocol() != PROVIDER_NAME {
+                    return Err(provider_error(
+                        ProviderErrorKind::InvalidRequest,
+                        UpstreamSendState::NotSent,
+                    ));
+                }
+                request.body = image.payload().body().clone();
+                request.image_turn_id = image
+                    .payload()
+                    .context()
+                    .get("image_turn_id")
+                    .and_then(Value::as_str)
+                    .map(str::to_owned);
+            }
+            Operation::Search(search) => {
+                if !matches!(&request.operation, Operation::Search(_))
+                    || search.payload().protocol() != PROVIDER_NAME
+                {
+                    return Err(provider_error(
+                        ProviderErrorKind::InvalidRequest,
+                        UpstreamSendState::NotSent,
+                    ));
+                }
+                request.body = search.payload().body().clone();
+                request.turn_metadata = search
+                    .payload()
+                    .context()
+                    .get("turn_metadata")
+                    .and_then(Value::as_str)
+                    .map(str::to_owned);
+            }
+            _ => {
+                return Err(provider_error(
+                    ProviderErrorKind::InvalidRequest,
+                    UpstreamSendState::NotSent,
+                ));
+            }
+        }
         let allows_account_state_mutation = lease.allows_account_state_mutation();
         let provider_kind = ProviderKind::new(PROVIDER_NAME)
             .map_err(|_| provider_error(ProviderErrorKind::Protocol, UpstreamSendState::NotSent))?;
@@ -130,7 +218,8 @@ impl CodexProvider {
                 .map_err(|_| {
                     provider_error(ProviderErrorKind::Unavailable, UpstreamSendState::NotSent)
                 })?
-                .with_authentication(lease.authentication()),
+                .with_authentication(lease.authentication())
+                .with_middleware_headers(middleware_headers),
             response_origin: request.response_origin,
             endpoint_path: request.endpoint_path,
             body: request.body,
@@ -156,6 +245,7 @@ impl CodexProvider {
 }
 
 struct RawJsonEndpointRequest {
+    operation: Operation,
     response_origin: Url,
     endpoint_path: &'static str,
     body: Bytes,
diff --git a/backend/crates/providers/openai/src/provider/failure.rs b/backend/crates/providers/openai/src/provider/failure.rs
index a6672803e..2bf4a32a6 100644
--- a/backend/crates/providers/openai/src/provider/failure.rs
+++ b/backend/crates/providers/openai/src/provider/failure.rs
@@ -855,6 +855,7 @@ pub(super) fn map_client_error(
         )),
         CodexClientError::InvalidHeaderName(_)
         | CodexClientError::InvalidHeaderValue(_)
+        | CodexClientError::MiddlewareHeaderConflict
         | CodexClientError::WebSocketEncode(_)
         | CodexClientError::RequestBodyEncode(_)
         | CodexClientError::RequestCompression(_)
@@ -1040,6 +1041,11 @@ fn client_diagnostic(error: &CodexClientError) -> Option<ProviderDiagnostic> {
             "invalid_header_value",
             "OpenAI request header value is invalid".to_owned(),
         ),
+        CodexClientError::MiddlewareHeaderConflict => (
+            "prepare",
+            "middleware_header_conflict",
+            "OpenAI middleware header conflicts with a provider-managed header".to_owned(),
+        ),
         CodexClientError::WebSocketEncode(_) | CodexClientError::RequestBodyEncode(_) => (
             "prepare",
             "request_encode_failed",
diff --git a/backend/crates/providers/openai/src/provider/mod.rs b/backend/crates/providers/openai/src/provider/mod.rs
index 77121f2e1..59efd3d2f 100644
--- a/backend/crates/providers/openai/src/provider/mod.rs
+++ b/backend/crates/providers/openai/src/provider/mod.rs
@@ -11,6 +11,7 @@ use bytes::Bytes;
 use futures::{StreamExt, future::BoxFuture};
 use gateway_core::account::{AccountFeedbackStats, ProviderAccount};
 use gateway_core::engine::continuation::{ContinuationBinding, NativeContinuationScope};
+use gateway_core::engine::middleware::MiddlewareHeader;
 use gateway_core::engine::provider::{
     ContinuationRequestObservation, EventStream, Provider, ProviderCallMetadata, ProviderRequest,
     ProviderRequestObservation, ProviderSelectionObservation, ProviderStream,
@@ -28,8 +29,8 @@ use gateway_core::event::{
 };
 use gateway_core::lifecycle::CancellationToken;
 use gateway_core::operation::{
-    GenerateRequest, ImageRequest, ImageRequestKind, Operation, OperationKind,
-    ProviderSessionState, StandaloneSearchRequest,
+    CapabilityRequirements, GenerateRequest, ImageRequest, ImageRequestKind, Operation,
+    OperationKind, ProviderSessionState, StandaloneSearchRequest,
 };
 use gateway_core::provider_ports::ProviderSessionAffinityKey;
 use gateway_core::routing::{
@@ -45,7 +46,7 @@ use gateway_core::upstream::{UpstreamSendState, UpstreamTransport};
 use gateway_protocol::openai::events::{
     ParsedRateLimits, parse_rate_limit_headers, rate_limits_to_header_pairs,
 };
-use reqwest::Client;
+use reqwest::{Client, header::HeaderValue};
 use secrecy::{ExposeSecret, SecretString};
 use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value, json};
@@ -137,6 +138,7 @@ pub enum CodexProviderConfigError {
     InvalidBaseUrl,
 }
 
+#[derive(Clone)]
 pub struct CodexProvider {
     selector: Arc<CodexCredentialSelector>,
     catalog: Arc<CodexCredentialCatalogService>,
@@ -152,7 +154,70 @@ pub struct CodexProvider {
     stream_max_retries: u32,
 }
 
+struct PreparedGenerateRequest {
+    upstream: CodexResponsesRequest,
+    previous_session: Option<OpenAiSessionState>,
+    continuation_requested: bool,
+    session_affinity: Option<CodexSessionAffinity>,
+    cyber_policy_session_key: Option<ProviderSessionAffinityKey>,
+}
+
+struct SelectedGenerate {
+    lease: CodexCredentialLease,
+    session_affinity: Option<CodexSessionAffinity>,
+    cyber_policy_key: Option<ProviderSessionAffinityKey>,
+    account_selection_wait_ms: u64,
+    frozen_requirements: CapabilityRequirements,
+}
+
 impl CodexProvider {
+    fn prepare_generate_request(
+        &self,
+        generate: &GenerateRequest,
+        upstream_model: &UpstreamModelId,
+        context: &AttemptContext,
+    ) -> Result<PreparedGenerateRequest, ProviderError> {
+        let previous_session = decode_openai_session_state(generate);
+        let continuation_requested = generate.native_continuation_requested();
+        let mut upstream = encode_generate_request(generate, upstream_model.as_str(), None)
+            .map_err(map_request_error)?;
+        // 插件加工后仍重新应用宿主强制策略与本地会话身份。
+        upstream.apply_fast_policy(context.disable_fast());
+        if let Some(conversation_id) = previous_session
+            .as_ref()
+            .and_then(|state| state.conversation_id.as_ref())
+        {
+            upstream.local_conversation_id = Some(conversation_id.clone());
+        }
+        if let Some(identity) = &self.session_identity {
+            identity.prepare_local_conversation(&mut upstream);
+        }
+        if let Some(previous_session) = previous_session.as_ref() {
+            upstream.turn_state = if same_client_turn(
+                previous_session.client_turn_id.as_deref(),
+                upstream.client_turn_id.as_deref(),
+            ) {
+                upstream
+                    .turn_state
+                    .take()
+                    .or_else(|| previous_session.turn_state.clone())
+            } else {
+                None
+            };
+        }
+        let session_affinity =
+            derive_codex_session_affinity(&upstream, context.client_api_key_ref());
+        let cyber_policy_session_key =
+            derive_codex_cyber_policy_session_key(&upstream, context.client_api_key_ref());
+        Ok(PreparedGenerateRequest {
+            upstream,
+            previous_session,
+            continuation_requested,
+            session_affinity,
+            cyber_policy_session_key,
+        })
+    }
+
     fn client_for_request(
         &self,
         context: &AttemptContext,
@@ -352,7 +417,7 @@ impl Provider for CodexProvider {
     }
 
     async fn execute(
-        &self,
+        self: Arc<Self>,
         request: ProviderRequest,
         context: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
@@ -393,45 +458,27 @@ impl Provider for CodexProvider {
                 UpstreamSendState::NotSent,
             ));
         };
-        let previous_session = decode_openai_session_state(generate);
-        let continuation_requested = generate.native_continuation_requested();
-        let mut upstream_request = encode_generate_request(generate, upstream_model.as_str(), None)
-            .map_err(map_request_error)?;
-        // 编码已生成独立请求；HTTP、WS 与重试在头部和计量之前共用此策略。
-        upstream_request.apply_fast_policy(context.disable_fast());
-        if let Some(conversation_id) = previous_session
-            .as_ref()
-            .and_then(|state| state.conversation_id.as_ref())
-        {
-            upstream_request.local_conversation_id = Some(conversation_id.clone());
-        }
-        if let Some(identity) = &self.session_identity {
-            identity.prepare_local_conversation(&mut upstream_request);
-        }
-        if let Some(previous_session) = previous_session.as_ref() {
-            upstream_request.turn_state = if same_client_turn(
-                previous_session.client_turn_id.as_deref(),
-                upstream_request.client_turn_id.as_deref(),
-            ) {
-                upstream_request
-                    .turn_state
-                    .take()
-                    .or_else(|| previous_session.turn_state.clone())
-            } else {
-                None
-            };
-        }
-        let session_affinity =
-            derive_codex_session_affinity(&upstream_request, context.client_api_key_ref());
-        let cyber_policy_session_key =
-            derive_codex_cyber_policy_session_key(&upstream_request, context.client_api_key_ref());
-
-        let requires_websocket = transport_requirement(&upstream_request).requires_websocket()
-            || (context.continuation_attempt() == ContinuationAttempt::Native
-                && (previous_session.as_ref().is_some_and(|state| {
-                    state.continuation_scope == OpenAiContinuationScope::ConnectionLocal
-                }) || matches!(context.continuation(), Some(ContinuationBinding::Pinned(binding))
-                        if binding.scope() == NativeContinuationScope::ConnectionLocal)));
+        // 其他协议必须先取得真实账号，再按固定 attempt 阶段调用转换器；选号前不能
+        // 把未知正文当成 OpenAI wire 解释会话、亲和或传输字段。
+        let preselection = (generate.protocol_payload().protocol() == PROVIDER_NAME)
+            .then(|| self.prepare_generate_request(generate, upstream_model, &context))
+            .transpose()?;
+        let (selection_session_affinity, selection_cyber_policy_key, requires_websocket) =
+            preselection.map_or((None, None, false), |prepared| {
+                let requires_websocket =
+                    transport_requirement(&prepared.upstream).requires_websocket()
+                        || (context.continuation_attempt() == ContinuationAttempt::Native
+                            && (prepared.previous_session.as_ref().is_some_and(|state| {
+                                state.continuation_scope
+                                    == OpenAiContinuationScope::ConnectionLocal
+                            }) || matches!(context.continuation(), Some(ContinuationBinding::Pinned(binding))
+                                    if binding.scope() == NativeContinuationScope::ConnectionLocal)));
+                (
+                    prepared.session_affinity,
+                    prepared.cyber_policy_session_key,
+                    requires_websocket,
+                )
+            });
         let selection_started_at = Instant::now();
         let lease = self
             .selector
@@ -440,18 +487,108 @@ impl Provider for CodexProvider {
                     upstream_model: upstream_model.as_str(),
                     request_url: &self.responses_url,
                     attempt: &context,
-                    session_affinity_key: session_affinity.as_ref().map(|affinity| affinity.key()),
+                    session_affinity_key: selection_session_affinity
+                        .as_ref()
+                        .map(|affinity| affinity.key()),
                 },
-                cyber_policy_session_key.as_ref(),
-                session_affinity.as_ref(),
+                selection_cyber_policy_key.as_ref(),
+                selection_session_affinity.as_ref(),
                 requires_websocket,
             )
             .await
             .map_err(map_selection_error)?;
         let account_selection_wait_ms =
             u64::try_from(selection_started_at.elapsed().as_millis()).unwrap_or(u64::MAX);
+        let provider_kind = ProviderKind::new(PROVIDER_NAME)
+            .map_err(|_| provider_error(ProviderErrorKind::Protocol, UpstreamSendState::NotSent))?;
+        let account_id = lease.account_id().clone();
+        let frozen_requirements = Operation::Generate(generate.clone()).capability_requirements();
+        let provider = Arc::clone(&self);
+        let terminal_context = context.clone();
+        let terminal_model = upstream_model.clone();
+        context
+            .execute_middleware(
+                Operation::Generate(generate.clone()),
+                provider_kind,
+                Some(upstream_model.as_str().to_owned()),
+                account_id,
+                Box::new(move |operation, middleware_headers| {
+                    Box::pin(async move {
+                        provider
+                            .execute_selected_generate(
+                                operation,
+                                middleware_headers,
+                                terminal_model,
+                                terminal_context,
+                                SelectedGenerate {
+                                    lease,
+                                    session_affinity: selection_session_affinity,
+                                    cyber_policy_key: selection_cyber_policy_key,
+                                    account_selection_wait_ms,
+                                    frozen_requirements,
+                                },
+                            )
+                            .await
+                    })
+                }),
+            )
+            .await
+    }
+}
+
+impl CodexProvider {
+    async fn execute_selected_generate(
+        self: Arc<Self>,
+        operation: Operation,
+        middleware_headers: Vec<MiddlewareHeader>,
+        upstream_model: UpstreamModelId,
+        context: AttemptContext,
+        selected: SelectedGenerate,
+    ) -> Result<ProviderStream, ProviderError> {
+        let SelectedGenerate {
+            mut lease,
+            session_affinity: selection_session_affinity,
+            cyber_policy_key: selection_cyber_policy_key,
+            account_selection_wait_ms,
+            frozen_requirements,
+        } = selected;
+        let Operation::Generate(generate) = operation else {
+            return Err(provider_error(
+                ProviderErrorKind::Protocol,
+                UpstreamSendState::NotSent,
+            ));
+        };
+        if generate.protocol_payload().protocol() != PROVIDER_NAME
+            || native_request_requirements(&generate) != frozen_requirements
+        {
+            return Err(provider_error(
+                ProviderErrorKind::InvalidRequest,
+                UpstreamSendState::NotSent,
+            ));
+        }
+        validate_openai_reasoning(generate.protocol_payload().body())?;
+        let processed = self.prepare_generate_request(&generate, &upstream_model, &context)?;
+        let mut upstream_request = processed.upstream;
+        let previous_session = processed.previous_session;
+        let continuation_requested = processed.continuation_requested;
+        let session_affinity = processed.session_affinity;
+        let cyber_policy_session_key = processed.cyber_policy_session_key;
+        if selection_session_affinity
+            .as_ref()
+            .map(|affinity| affinity.key())
+            != session_affinity.as_ref().map(|affinity| affinity.key())
+            || selection_cyber_policy_key.as_ref() != cyber_policy_session_key.as_ref()
+        {
+            self.selector
+                .validate_translated_selection(
+                    &mut lease,
+                    session_affinity.as_ref(),
+                    cyber_policy_session_key.as_ref(),
+                )
+                .await
+                .map_err(map_selection_error)?;
+        }
         let lease = Arc::new(lease);
-        // 首字计时的起点：账号选择完成之后、上游建立之前。
         if previous_session.as_ref().is_some_and(|state| {
             state
                 .credential_revision
@@ -555,7 +692,6 @@ impl Provider for CodexProvider {
         ) {
             normalize_non_codex_request_body(upstream_request.body_mut());
         }
-        // 每次执行从原始请求编码，选定出口后再覆盖，避免换号时携带上次位置。
         if let Some(location) = lease
             .account()
             .request_location()
@@ -592,6 +728,19 @@ impl Provider for CodexProvider {
         } else {
             requested_transport
         };
+        if transport == CodexProviderTransport::PreferWebSocket
+            && middleware_headers.iter().any(|header| {
+                match HeaderValue::from_bytes(header.value()) {
+                    Ok(value) => value.to_str().is_err(),
+                    Err(_) => true,
+                }
+            })
+        {
+            return Err(provider_error(
+                ProviderErrorKind::Protocol,
+                UpstreamSendState::NotSent,
+            ));
+        }
         apply_transport(&mut upstream_request, transport);
         let metadata = ProviderCallMetadata::new(
             provider_kind,
@@ -636,10 +785,11 @@ impl Provider for CodexProvider {
                 .map_err(|_| {
                     provider_error(ProviderErrorKind::Unavailable, UpstreamSendState::NotSent)
                 })?
-                .with_authentication(lease.authentication()),
+                .with_authentication(lease.authentication())
+                .with_middleware_headers(middleware_headers),
             response_origin: self.responses_url.clone(),
             request: upstream_request,
-            upstream_model: upstream_model.clone(),
+            upstream_model,
             transport_policy: transport,
             context,
             selector: Arc::clone(&self.selector),
@@ -665,3 +815,34 @@ impl Provider for CodexProvider {
         })
     }
 }
+
+fn native_request_requirements(request: &GenerateRequest) -> CapabilityRequirements {
+    // 此处只解释已知 OpenAI wire；不在 Core 的通用转换路径推断任意目标协议。
+    Operation::Generate(GenerateRequest::from_protocol_payload(
+        request.protocol_payload().clone(),
+    ))
+    .capability_requirements()
+}
+
+fn validate_openai_reasoning(body: &Map<String, Value>) -> Result<(), ProviderError> {
+    let Some(effort) = body
+        .get("reasoning")
+        .and_then(Value::as_object)
+        .and_then(|reasoning| reasoning.get("effort"))
+    else {
+        return Ok(());
+    };
+    let Some(effort) = effort.as_str() else {
+        return Err(provider_error(
+            ProviderErrorKind::InvalidRequest,
+            UpstreamSendState::NotSent,
+        ));
+    };
+    if effort.is_empty() || effort.len() > 64 || effort.chars().any(char::is_control) {
+        return Err(provider_error(
+            ProviderErrorKind::InvalidRequest,
+            UpstreamSendState::NotSent,
+        ));
+    }
+    Ok(())
+}
diff --git a/backend/crates/providers/openai/src/provider/observation.rs b/backend/crates/providers/openai/src/provider/observation.rs
index 7040ab50c..8f7235611 100644
--- a/backend/crates/providers/openai/src/provider/observation.rs
+++ b/backend/crates/providers/openai/src/provider/observation.rs
@@ -812,5 +812,13 @@ pub(super) fn map_selection_error(error: CredentialSelectionError) -> ProviderEr
             ProviderErrorKind::ProviderInfrastructureUnavailable,
             UpstreamSendState::NotSent,
         ),
+        CredentialSelectionError::PolicyRejected => provider_error(
+            ProviderErrorKind::RequestPolicyDenied,
+            UpstreamSendState::NotSent,
+        ),
+        CredentialSelectionError::PolicyUnavailable => provider_error(
+            ProviderErrorKind::Unavailable,
+            UpstreamSendState::NotSent,
+        ),
     }
 }
diff --git a/backend/crates/providers/openai/src/transport/client.rs b/backend/crates/providers/openai/src/transport/client.rs
index 14d171343..ba646f8e3 100644
--- a/backend/crates/providers/openai/src/transport/client.rs
+++ b/backend/crates/providers/openai/src/transport/client.rs
@@ -12,6 +12,7 @@ use crate::transport::profile::CodexWireProfileState;
 use bytes::Bytes;
 use chrono::{DateTime, NaiveDateTime, Utc};
 use futures::{Stream, StreamExt};
+use gateway_core::engine::middleware::MiddlewareHeader;
 use gateway_protocol::openai::{
     WS_REQUEST_HEADER_RESPONSES_LITE_CLIENT_METADATA_KEY, events::retry_after_seconds_from_body,
     sse::SseError,
@@ -212,6 +213,9 @@ pub enum CodexClientError {
     /// 请求头值无效。
     #[error("invalid request header value: {0}")]
     InvalidHeaderValue(#[from] reqwest::header::InvalidHeaderValue),
+    /// 中间件业务头试图覆盖 Provider 已构造的受管头。
+    #[error("middleware request header conflicts with a provider-managed header")]
+    MiddlewareHeaderConflict,
     /// SSE 响应解析失败。
     #[error("invalid upstream SSE response: {0}")]
     InvalidSse(#[from] SseError),
@@ -281,6 +285,9 @@ impl fmt::Debug for CodexClientError {
             Self::InvalidHeaderValue(_) => {
                 formatter.write_str("CodexClientError::InvalidHeaderValue([REDACTED])")
             }
+            Self::MiddlewareHeaderConflict => {
+                formatter.write_str("CodexClientError::MiddlewareHeaderConflict")
+            }
             Self::InvalidSse(_) => formatter.write_str("CodexClientError::InvalidSse([REDACTED])"),
             Self::ModelCatalog(error) => formatter
                 .debug_tuple("CodexClientError::ModelCatalog")
@@ -334,6 +341,7 @@ impl CodexClientError {
             Self::CustomCa(_)
             | Self::InvalidHeaderName(_)
             | Self::InvalidHeaderValue(_)
+            | Self::MiddlewareHeaderConflict
             | Self::WebSocketEncode(_)
             | Self::RequestBodyEncode(_)
             | Self::RequestCompression(_) => None,
@@ -671,6 +679,7 @@ pub struct CodexBackendClient {
     pub(super) websocket_origin_key: String,
     pub(super) outbound_proxy: Option<gateway_core::account::OutboundProxy>,
     pub(super) egress_key: String,
+    pub(super) middleware_headers: Vec<MiddlewareHeader>,
 }
 
 impl CodexBackendClient {
diff --git a/backend/crates/providers/openai/src/transport/client_json.rs b/backend/crates/providers/openai/src/transport/client_json.rs
index 3b861ab5c..909f49944 100644
--- a/backend/crates/providers/openai/src/transport/client_json.rs
+++ b/backend/crates/providers/openai/src/transport/client_json.rs
@@ -45,6 +45,7 @@ impl CodexBackendClient {
             "x-codex-turn-metadata",
             context.turn_metadata,
         );
+        self.append_middleware_headers(&mut headers)?;
 
         let trace = context
             .trace
diff --git a/backend/crates/providers/openai/src/transport/client_sse.rs b/backend/crates/providers/openai/src/transport/client_sse.rs
index f353549f6..437da2348 100644
--- a/backend/crates/providers/openai/src/transport/client_sse.rs
+++ b/backend/crates/providers/openai/src/transport/client_sse.rs
@@ -69,6 +69,7 @@ impl CodexBackendClient {
             websocket_origin_key: websocket_origin_key(&base_url),
             outbound_proxy: None,
             egress_key: String::new(),
+            middleware_headers: Vec::new(),
             base_url,
             official_base_url: crate::OFFICIAL_CODEX_BASE_URL.to_owned(),
             protocol: OpenAiUpstreamProtocol::Codex,
@@ -84,6 +85,16 @@ impl CodexBackendClient {
         self
     }
 
+    /// 附加当前 attempt 经 Core 复核的业务请求头。
+    #[must_use]
+    pub(crate) fn with_middleware_headers(
+        mut self,
+        middleware_headers: Vec<gateway_core::engine::middleware::MiddlewareHeader>,
+    ) -> Self {
+        self.middleware_headers = middleware_headers;
+        self
+    }
+
     /// 驱逐指定账号的 Responses WebSocket 池连接。
     pub async fn evict_websocket_account(&self, account_id: &str) {
         if let Some(pool) = &self.websocket_pool {
@@ -292,7 +303,7 @@ impl CodexBackendClient {
                 tracing::warn!(error = %error, "Failed to write Codex WebSocket audit artifact");
             }
         }
-        let connection_profile = websocket_connection_profile(&headers);
+        let connection_profile = websocket_connection_profile(&headers, &self.middleware_headers);
         let pool_key =
             self.websocket_pool_key(request, context, pool_account_id, &connection_profile);
         let pool_log_context = pool_key.as_ref().map(WebSocketPoolLogContext::from_key);
@@ -634,15 +645,32 @@ async fn read_model_catalog_body(response: ReqwestResponse) -> CodexClientResult
     Ok(body)
 }
 
-fn websocket_connection_profile(headers: &HeaderMap) -> String {
-    ["originator", "user-agent", X_OPENAI_MEMGEN_REQUEST_HEADER]
+fn websocket_connection_profile(
+    headers: &HeaderMap,
+    middleware_headers: &[gateway_core::engine::middleware::MiddlewareHeader],
+) -> String {
+    let mut profile = ["originator", "user-agent", X_OPENAI_MEMGEN_REQUEST_HEADER]
         .map(|name| {
             headers
                 .get(name)
                 .and_then(|value| value.to_str().ok())
                 .unwrap_or_default()
         })
-        .join("\0")
+        .join("\0");
+    if !middleware_headers.is_empty() {
+        use sha2::{Digest, Sha256};
+
+        let mut digest = Sha256::new();
+        for header in middleware_headers {
+            digest.update(header.name().len().to_le_bytes());
+            digest.update(header.name().as_bytes());
+            digest.update(header.value().len().to_le_bytes());
+            digest.update(header.value());
+        }
+        profile.push('\0');
+        profile.push_str(&hex::encode(digest.finalize()));
+    }
+    profile
 }
 
 fn http_sse_stream(
diff --git a/backend/crates/providers/openai/src/transport/headers.rs b/backend/crates/providers/openai/src/transport/headers.rs
index 23ad8cafe..b8ed31c40 100644
--- a/backend/crates/providers/openai/src/transport/headers.rs
+++ b/backend/crates/providers/openai/src/transport/headers.rs
@@ -206,8 +206,24 @@ impl CodexBackendClient {
         };
         insert_optional_protocol_header(&mut headers, "x-codex-routing-hint", Some(&routing_hint));
         append_passthrough_headers(&mut headers, request);
+        self.append_middleware_headers(&mut headers)?;
         Ok(headers)
     }
+
+    pub(super) fn append_middleware_headers(
+        &self,
+        headers: &mut HeaderMap,
+    ) -> CodexClientResult<()> {
+        let provider_headers = headers.keys().cloned().collect::<Vec<_>>();
+        for header in &self.middleware_headers {
+            let name = HeaderName::from_bytes(header.name().as_bytes())?;
+            if provider_headers.contains(&name) {
+                return Err(super::client::CodexClientError::MiddlewareHeaderConflict);
+            }
+            headers.append(name, HeaderValue::from_bytes(header.value())?);
+        }
+        Ok(())
+    }
 }
 
 fn append_passthrough_headers(headers: &mut HeaderMap, request: &CodexResponsesRequest) {
diff --git a/backend/crates/providers/openai/tests/admin.rs b/backend/crates/providers/openai/tests/admin.rs
index 1b2b7468b..8c384063d 100644
--- a/backend/crates/providers/openai/tests/admin.rs
+++ b/backend/crates/providers/openai/tests/admin.rs
@@ -64,6 +64,29 @@ const COMPLETED_SESSION_SSE: &str = concat!(
     "data: {\"type\":\"response.completed\",\"response\":{\"id\":\"resp_initialized_session\",\"model\":\"gpt-5.4\",\"status\":\"completed\",\"output\":[],\"usage\":{\"input_tokens\":1,\"output_tokens\":1,\"total_tokens\":2}}}\n\n"
 );
 
+#[tokio::test]
+async fn account_capabilities_distinguish_oauth_from_api_key_and_unknown_credentials() {
+    let config = valid_config();
+    let bundle = provider_openai::initialize(config.config.clone(), provider_ports())
+        .await
+        .unwrap();
+    let provider = bundle.admin_provider();
+    let id = ProviderAccountId::new("acct_capabilities").unwrap();
+    let oauth = provider.account_capabilities(&id, "oauth");
+    assert!(
+        oauth.quota
+            && oauth.quota_refresh
+            && oauth.profile
+            && oauth.subscription
+            && oauth.avatar
+            && oauth.reset_credits
+            && oauth.consume_reset_credit
+    );
+    for kind in ["api_key", "unknown"] {
+        assert_eq!(provider.account_capabilities(&id, kind), Default::default());
+    }
+}
+
 #[tokio::test]
 async fn openai_bundle_exposes_one_core_provider_and_drains_worker_contributions_once() {
     let config = valid_config();
@@ -265,7 +288,7 @@ async fn initialized_provider_keeps_thread_spawn_transport_conversations_distinc
         .expect("OpenAI payload")
         .with_context(Map::from_iter([("use_websocket".to_owned(), json!(false))]));
         let operation = Operation::Generate(GenerateRequest::from_protocol_payload(payload));
-        let mut stream = provider
+        let mut stream = Arc::clone(&provider)
             .execute(
                 initialized_provider_request(operation, account_id),
                 initialized_attempt_context(request_id, account_id),
@@ -525,13 +548,20 @@ async fn openai_admin_provider_persists_the_full_pending_envelope_and_binds_owne
     };
     let started = bundle
         .admin_provider()
-        .start_authorization(PendingAuthorizationMutation::new(
-            ProviderKind::new("openai").expect("provider"),
-            AuthorizationMutationTarget::Create {
-                name: "OAuth account".to_owned(),
+        .start_authorization(
+            gateway_admin::model::provider_credentials::PrepareAuthorization {
+                input: gateway_admin::model::provider_credentials::ProviderDocument::new(
+                    gateway_core::account::OpaqueProviderData::new(serde_json::Map::new()),
+                ),
+                pending: PendingAuthorizationMutation::new(
+                    ProviderKind::new("openai").expect("provider"),
+                    AuthorizationMutationTarget::Create {
+                        name: "OAuth account".to_owned(),
+                    },
+                    AuthorizationOwnerBinding::from_context(&start_context),
+                ),
             },
-            AuthorizationOwnerBinding::from_context(&start_context),
-        ))
+        )
         .await
         .expect("start authorization");
     {
@@ -627,11 +657,18 @@ async fn openai_reauthorization_pending_payload_reuses_the_account_installation_
 
     bundle
         .admin_provider()
-        .start_authorization(PendingAuthorizationMutation::new(
-            ProviderKind::new("openai").expect("provider"),
-            AuthorizationMutationTarget::Reauthorize { account_id },
-            AuthorizationOwnerBinding::from_context(&context),
-        ))
+        .start_authorization(
+            gateway_admin::model::provider_credentials::PrepareAuthorization {
+                input: gateway_admin::model::provider_credentials::ProviderDocument::new(
+                    gateway_core::account::OpaqueProviderData::new(serde_json::Map::new()),
+                ),
+                pending: PendingAuthorizationMutation::new(
+                    ProviderKind::new("openai").expect("provider"),
+                    AuthorizationMutationTarget::Reauthorize { account_id },
+                    AuthorizationOwnerBinding::from_context(&context),
+                ),
+            },
+        )
         .await
         .expect("start reauthorization");
 
@@ -715,6 +752,7 @@ async fn openai_admin_provider_projects_cached_quota_models_and_canonical_export
             &UpstreamModelId::new("gpt-5.4").expect("upstream model"),
             "Reply with exactly OK.",
         )
+        .await
         .expect("connection test operation");
     let Operation::Generate(request) = operation else {
         panic!("connection test must be a generate operation");
@@ -2323,3 +2361,48 @@ async fn api_key_admin_exposes_only_configuration_and_preserves_key_when_rotatin
         ProviderAdminErrorKind::Unsupported
     );
 }
+
+#[tokio::test]
+async fn browser_authorization_declares_callback_and_rejects_extra_login_inputs() {
+    use gateway_admin::model::{
+        provider_capabilities::AuthorizationCompletion,
+        provider_credentials::{
+            AuthorizationMutationTarget, AuthorizationOwnerBinding, PendingAuthorizationMutation,
+            PrepareAuthorization,
+        },
+    };
+    let config = valid_config();
+    let bundle = provider_openai::initialize(config.config.clone(), provider_ports())
+        .await
+        .unwrap();
+    let provider = bundle.admin_provider();
+    let login = provider.credential_capabilities().login.unwrap();
+    assert_eq!(login.completion, AuthorizationCompletion::Callback);
+    assert_eq!(
+        login.input_schema,
+        json!({"type":"object", "additionalProperties":false})
+    );
+    let error = provider
+        .start_authorization(PrepareAuthorization {
+            pending: PendingAuthorizationMutation::new(
+                ProviderKind::new("openai").unwrap(),
+                AuthorizationMutationTarget::Create {
+                    name: "form account".into(),
+                },
+                AuthorizationOwnerBinding::from_context(&MutationContext {
+                    actor: MutationActor::System,
+                    request_id: "login-input-test".into(),
+                }),
+            ),
+            input: ProviderDocument::new(OpaqueProviderData::new(
+                json!({"token":"unexpected-fixture-secret"})
+                    .as_object()
+                    .unwrap()
+                    .clone(),
+            )),
+        })
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), ProviderAdminErrorKind::Invalid);
+    assert!(!format!("{error:?}").contains("unexpected-fixture-secret"));
+}
diff --git a/backend/crates/providers/openai/tests/provider/contract.rs b/backend/crates/providers/openai/tests/provider/contract.rs
index aadd84661..e9d997ce2 100644
--- a/backend/crates/providers/openai/tests/provider/contract.rs
+++ b/backend/crates/providers/openai/tests/provider/contract.rs
@@ -7,7 +7,7 @@ use std::time::{Duration, SystemTime};
 use base64::{Engine as _, engine::general_purpose::STANDARD};
 use bytes::Bytes;
 use chrono::Utc;
-use futures::{SinkExt, StreamExt};
+use futures::{SinkExt, StreamExt, future::BoxFuture};
 use gateway_core::account::{
     AccountFeedbackStats, AccountWeight, CredentialState, OpaqueProviderData, ProviderAccountId,
     ProviderAccountStore as _, QuotaAccessChange, QuotaAccessState, QuotaEvidence,
@@ -16,6 +16,11 @@ use gateway_core::account::{
 use gateway_core::engine::continuation::{
     ContinuationBinding, NativeContinuationPin, PreviousResponseId,
 };
+use gateway_core::engine::execution::ClientTransport;
+use gateway_core::engine::middleware::{
+    FrozenMiddlewarePlan, MiddlewareContext, MiddlewareError, MiddlewareHeader, MiddlewareMount,
+    MiddlewareNext, MiddlewarePlan, MiddlewareRequest, MiddlewareResponse,
+};
 use gateway_core::engine::provider::{Provider as _, ProviderRequest};
 use gateway_core::engine::{
     AccountAttemptContext, AttemptContext, AttemptTransport, ContinuationAttempt, ModelRequestId,
@@ -38,6 +43,7 @@ use gateway_core::routing::{
     ProviderKind, ProviderModel, PublicModelId, RoutingContext, RuntimeAccount,
     RuntimeAccountDirectory, RuntimeSnapshot, UpstreamModelId,
 };
+use gateway_core::runtime::extensions::{ExtensionSetId, ExtensionSetLease, ExtensionSetReference};
 use gateway_core::upstream::UpstreamSendState;
 use provider_openai::config::DEFAULT_STREAM_MAX_RETRIES;
 use provider_openai::credential::{
@@ -66,6 +72,432 @@ use crate::support::{
 };
 use crate::transport::accept_codex_test_websocket;
 
+#[tokio::test]
+async fn native_openai_translates_a_non_native_source_before_encoding() {
+    let store = Arc::new(MemoryAccountStore::default());
+    create_account(&store, "acct_provider_contract").await;
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(
+            ResponseTemplate::new(200)
+                .insert_header("content-type", "text/event-stream")
+                .set_body_string(CAPTURE_COMPLETED_SSE),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+    let translations = Arc::new(Mutex::new(0_usize));
+    let source = Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "example-source",
+            Map::from_iter([("opaque".to_owned(), json!("source-only"))]),
+        )
+        .unwrap()
+        .with_context(Map::from_iter([("use_websocket".to_owned(), json!(false))])),
+    ));
+    let mut stream = provider_with_base_url(&store, server.uri())
+        .execute(
+            planned_request("openai", source),
+            context_with_middleware(
+                "req_native_translate",
+                Arc::new(TranslationMiddleware {
+                    translations: Arc::clone(&translations),
+                    target: Map::from_iter([
+                        ("model".to_owned(), json!("ignored-by-forced-model")),
+                        ("input".to_owned(), json!("translated")),
+                        ("stream".to_owned(), json!(true)),
+                    ]),
+                }),
+                false,
+            ),
+        )
+        .await
+        .expect("registered translation should run before native encoding");
+    assert!(server.received_requests().await.unwrap().is_empty());
+    while let Some(event) = stream.next().await {
+        event.expect("translated request response");
+    }
+    assert_eq!(*translations.lock().unwrap(), 1);
+    let requests = server.received_requests().await.unwrap();
+    let sent = captured_request_body(&requests[0]);
+    assert_eq!(sent["input"][0]["content"][0]["text"], "translated");
+    assert_eq!(sent["model"], "gpt-5.4");
+}
+
+#[tokio::test]
+async fn native_openai_rejects_missing_translation_before_send() {
+    let store = Arc::new(MemoryAccountStore::default());
+    create_account(&store, "acct_provider_contract").await;
+    let server = MockServer::start().await;
+    let source = Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "example-source",
+            Map::from_iter([("opaque".to_owned(), json!("source-only"))]),
+        )
+        .unwrap()
+        .with_context(Map::from_iter([("use_websocket".to_owned(), json!(false))])),
+    ));
+    let error = match provider_with_base_url(&store, server.uri())
+        .execute(
+            planned_request("openai", source),
+            context_with_middleware(
+                "req_native_translate_missing",
+                Arc::new(PassThroughMiddleware),
+                false,
+            ),
+        )
+        .await
+    {
+        Ok(_) => panic!("missing translation pair must be explicit"),
+        Err(error) => error,
+    };
+    assert_eq!(error.kind(), ProviderErrorKind::InvalidRequest);
+    assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+    assert!(server.received_requests().await.unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn native_openai_rejects_capability_expanding_translation_before_send() {
+    let store = Arc::new(MemoryAccountStore::default());
+    create_account(&store, "acct_provider_contract").await;
+    let server = MockServer::start().await;
+    let source = Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "example-source",
+            Map::from_iter([("opaque".to_owned(), json!("source-only"))]),
+        )
+        .unwrap()
+        .with_context(Map::from_iter([("use_websocket".to_owned(), json!(false))])),
+    ));
+    let translations = Arc::new(Mutex::new(0));
+    let error = match provider_with_base_url(&store, server.uri())
+        .execute(
+            planned_request("openai", source),
+            context_with_middleware(
+                "req_native_translate_expansion",
+                Arc::new(TranslationMiddleware {
+                    translations: Arc::clone(&translations),
+                    target: json!({
+                        "model":"ignored-by-forced-model",
+                        "input":"translated",
+                        "tools":[{"type":"function", "name":"new_capability"}]
+                    })
+                    .as_object()
+                    .unwrap()
+                    .clone(),
+                }),
+                false,
+            ),
+        )
+        .await
+    {
+        Ok(_) => panic!("translation cannot expand routed capabilities"),
+        Err(error) => error,
+    };
+    assert_eq!(error.kind(), ProviderErrorKind::InvalidRequest);
+    assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+    assert_eq!(*translations.lock().unwrap(), 1);
+    assert!(server.received_requests().await.unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn native_openai_revalidates_translated_transport_without_reselecting() {
+    let store = Arc::new(MemoryAccountStore::default());
+    let upstream = MockServer::start().await;
+    store
+        .seed_api_key(
+            "acct_provider_contract",
+            upstream.uri(),
+            provider_openai::credential::ApiKeyTransport::Http,
+        )
+        .await;
+    let source = Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "example-source",
+            Map::from_iter([("opaque".to_owned(), json!("source-only"))]),
+        )
+        .unwrap()
+        .with_context(Map::from_iter([("use_websocket".to_owned(), json!(true))])),
+    ));
+    let error = match provider(&store)
+        .execute(
+            planned_request("openai", source),
+            context_with_middleware(
+                "req_native_translate_transport",
+                Arc::new(TranslationMiddleware {
+                    translations: Arc::new(Mutex::new(0)),
+                    target: json!({
+                        "model": "ignored-by-forced-model",
+                        "input": [],
+                        "store": false,
+                        "generate": false
+                    })
+                    .as_object()
+                    .unwrap()
+                    .clone(),
+                }),
+                false,
+            ),
+        )
+        .await
+    {
+        Ok(_) => panic!("selected HTTP account cannot satisfy translated WebSocket request"),
+        Err(error) => error,
+    };
+    assert_eq!(error.kind(), ProviderErrorKind::Unsupported);
+    assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+    assert!(upstream.received_requests().await.unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn native_openai_claims_translated_session_affinity_before_send() {
+    let store = Arc::new(MemoryAccountStore::default());
+    create_account(&store, "acct_provider_contract").await;
+    let server = MockServer::start().await;
+    let affinity = Arc::new(MemorySessionAffinity::default());
+    let source = Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "example-source",
+            Map::from_iter([("opaque".to_owned(), json!("source-only"))]),
+        )
+        .unwrap()
+        .with_context(Map::from_iter([
+            ("conversation_id".to_owned(), json!("translated-session")),
+            ("use_websocket".to_owned(), json!(false)),
+        ])),
+    ));
+    let stream = provider_with_affinity_and_base_url(&store, Arc::clone(&affinity), server.uri())
+        .execute(
+            planned_request("openai", source),
+            context_with_middleware(
+                "req_native_translate_affinity",
+                Arc::new(TranslationMiddleware {
+                    translations: Arc::new(Mutex::new(0)),
+                    target: json!({
+                        "model": "ignored-by-forced-model",
+                        "input": "translated",
+                        "stream": true
+                    })
+                    .as_object()
+                    .unwrap()
+                    .clone(),
+                }),
+                false,
+            ),
+        )
+        .await
+        .expect("translated session should keep the selected account");
+    assert_eq!(
+        stream.metadata().provider_account_id().as_str(),
+        "acct_provider_contract"
+    );
+    assert_eq!(affinity.binding_count(), 1);
+    assert!(server.received_requests().await.unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn attempt_middleware_runs_once_before_native_encoding_and_fast_policy() {
+    let store = Arc::new(MemoryAccountStore::default());
+    create_account(&store, "acct_provider_contract").await;
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(
+            ResponseTemplate::new(200)
+                .insert_header("content-type", "text/event-stream")
+                .set_body_string(CAPTURE_COMPLETED_SSE),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+    let observed = Arc::new(Mutex::new(Vec::new()));
+    let operation = Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "openai",
+            json!({"model":"gpt-5.6-sol", "input":"hello", "unknown":{"preserved":true}})
+                .as_object()
+                .unwrap()
+                .clone(),
+        )
+        .unwrap()
+        .with_context(Map::from_iter([("use_websocket".to_owned(), json!(false))])),
+    ));
+    let mut stream = provider_with_base_url(&store, server.uri())
+        .execute(
+            planned_request("openai", operation),
+            context_with_middleware(
+                "req_native_normalize",
+                Arc::new(RecordingMiddleware {
+                    observed: Arc::clone(&observed),
+                    replacement: ("service_tier".to_owned(), json!("priority")),
+                    request_headers: vec![
+                        MiddlewareHeader::new(
+                            "x-business-context",
+                            Bytes::from_static(b"tenant-public"),
+                        ),
+                        MiddlewareHeader::new(
+                            "x-business-context",
+                            Bytes::from_static(b"trace-public"),
+                        ),
+                    ],
+                }),
+                true,
+            ),
+        )
+        .await
+        .unwrap();
+    assert!(server.received_requests().await.unwrap().is_empty());
+    while let Some(event) = stream.next().await {
+        event.unwrap();
+    }
+    {
+        let observed = observed.lock().unwrap();
+        assert_eq!(observed.len(), 1);
+        assert_eq!(observed[0]["input"], "hello");
+    }
+    let requests = server.received_requests().await.unwrap();
+    let sent = captured_request_body(&requests[0]);
+    assert_eq!(sent["service_tier"], "default");
+    assert_eq!(sent["unknown"]["preserved"], true);
+    assert_eq!(
+        captured_header_values(&requests[0], "x-business-context"),
+        vec![b"tenant-public".to_vec(), b"trace-public".to_vec()],
+    );
+
+    let mut conflict = provider_with_base_url(&store, server.uri())
+        .execute(
+            planned_request("openai", http_generate_operation()),
+            context_with_middleware(
+                "req_native_header_conflict",
+                Arc::new(RecordingMiddleware {
+                    observed: Arc::default(),
+                    replacement: ("service_tier".to_owned(), json!("priority")),
+                    request_headers: vec![MiddlewareHeader::new(
+                        "x-codex-routing-hint",
+                        Bytes::from_static(b"plugin-value"),
+                    )],
+                }),
+                false,
+            ),
+        )
+        .await
+        .expect("header validation remains on the cold Provider stream");
+    let Some(Err(error)) = conflict.next().await else {
+        panic!("a Provider-managed header collision must fail before send")
+    };
+    assert_eq!(error.kind(), ProviderErrorKind::Protocol);
+    assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+    assert_eq!(server.received_requests().await.unwrap().len(), 1);
+}
+
+#[tokio::test]
+async fn attempt_middleware_rejects_non_text_websocket_headers_before_opening() {
+    let store = Arc::new(MemoryAccountStore::default());
+    create_account(&store, "acct_provider_contract").await;
+    let server = MockServer::start().await;
+    let operation = Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "openai",
+            json!({"model":"gpt-5.4", "input":"hello"})
+                .as_object()
+                .unwrap()
+                .clone(),
+        )
+        .unwrap()
+        .with_context(Map::from_iter([("use_websocket".to_owned(), json!(true))])),
+    ));
+
+    let error = provider_with_base_url(&store, server.uri())
+        .execute(
+            planned_request("openai", operation),
+            context_with_middleware(
+                "req_native_websocket_obs_text",
+                Arc::new(RecordingMiddleware {
+                    observed: Arc::default(),
+                    replacement: ("service_tier".to_owned(), json!("priority")),
+                    request_headers: vec![MiddlewareHeader::new(
+                        "x-business-context",
+                        Bytes::from_static(&[0x80]),
+                    )],
+                }),
+                false,
+            ),
+        )
+        .await
+        .err()
+        .expect("WebSocket headers must be representable before opening");
+
+    assert_eq!(error.kind(), ProviderErrorKind::Protocol);
+    assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+    assert!(server.received_requests().await.unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn attempt_middleware_can_change_reasoning_before_native_encoding() {
+    let store = Arc::new(MemoryAccountStore::default());
+    create_account(&store, "acct_provider_contract").await;
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/responses"))
+        .respond_with(
+            ResponseTemplate::new(200)
+                .insert_header("content-type", "text/event-stream")
+                .set_body_string(CAPTURE_COMPLETED_SSE),
+        )
+        .expect(1)
+        .mount(&server)
+        .await;
+    let operation = Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "openai",
+            json!({
+                "model":"gpt-5.6-sol",
+                "input":"hello",
+                "reasoning":{"effort":"future-level","summary":"detailed"},
+                "unknown":{"preserved":true}
+            })
+            .as_object()
+            .unwrap()
+            .clone(),
+        )
+        .unwrap()
+        .with_context(Map::from_iter([("use_websocket".to_owned(), json!(false))])),
+    ));
+    let observed = Arc::new(Mutex::new(Vec::new()));
+    let mut stream = provider_with_base_url(&store, server.uri())
+        .execute(
+            planned_request("openai", operation),
+            context_with_middleware(
+                "req_native_reasoning",
+                Arc::new(RecordingMiddleware {
+                    observed: Arc::clone(&observed),
+                    replacement: ("reasoning".to_owned(), json!({"effort":"high"})),
+                    request_headers: Vec::new(),
+                }),
+                false,
+            ),
+        )
+        .await
+        .unwrap();
+    while let Some(event) = stream.next().await {
+        event.unwrap();
+    }
+
+    let requests = server.received_requests().await.unwrap();
+    let body = captured_request_body(&requests[0]);
+    assert_eq!(body["reasoning"], json!({"effort":"high"}));
+    assert_eq!(
+        body.pointer("/input/0/content/0/text"),
+        Some(&json!("hello"))
+    );
+    assert_eq!(body["unknown"]["preserved"], true);
+    assert_eq!(
+        observed.lock().unwrap()[0]["reasoning"]["effort"],
+        "future-level"
+    );
+}
+
 #[tokio::test]
 async fn responses_bill_sent_model_and_observe_unpriced_response_without_rewriting_it() {
     let store = Arc::new(MemoryAccountStore::default());
@@ -251,7 +683,7 @@ async fn selected_proxy_location_overrides_global_and_reloads_without_mutating_c
     ].into_iter().enumerate() {
         let location = location.map(|value| serde_json::from_value::<RequestLocation>(value).unwrap());
         store.set_egress(account_id, Some(OutboundProxy::parse(&proxy.uri()).unwrap()), location);
-        let mut stream = provider.execute(planned_request("openai", operation.clone()), context_with_state_owner_and_location(&format!("req_proxy_location_{index}"), account_id, global_enabled.then(global_request_location))).await.expect("prepare");
+        let mut stream = Arc::clone(&provider).execute(planned_request("openai", operation.clone()), context_with_state_owner_and_location(&format!("req_proxy_location_{index}"), account_id, global_enabled.then(global_request_location))).await.expect("prepare");
         while let Some(event) = stream.next().await { event.expect("proxy response"); }
         let requests = proxy.received_requests().await.unwrap();
         let body = captured_request_body(requests.last().expect("request reached selected proxy"));
@@ -557,18 +989,18 @@ fn wire_profile() -> CodexWireProfileState {
     })
 }
 
-fn provider(store: &Arc<MemoryAccountStore>) -> CodexProvider {
+fn provider(store: &Arc<MemoryAccountStore>) -> Arc<CodexProvider> {
     provider_with_affinity(store, Arc::new(MemorySessionAffinity::default()))
 }
 
 fn provider_with_affinity(
     store: &Arc<MemoryAccountStore>,
     session_affinity: Arc<MemorySessionAffinity>,
-) -> CodexProvider {
+) -> Arc<CodexProvider> {
     provider_with_affinity_and_base_url(store, session_affinity, OFFICIAL_CODEX_BASE_URL.to_owned())
 }
 
-fn provider_with_base_url(store: &Arc<MemoryAccountStore>, base_url: String) -> CodexProvider {
+fn provider_with_base_url(store: &Arc<MemoryAccountStore>, base_url: String) -> Arc<CodexProvider> {
     provider_with_base_url_and_retry_budget(
         store,
         base_url,
@@ -580,7 +1012,7 @@ fn provider_with_base_url_and_retry_budget(
     store: &Arc<MemoryAccountStore>,
     base_url: String,
     stream_max_retries: u32,
-) -> CodexProvider {
+) -> Arc<CodexProvider> {
     provider_and_quota_with_affinity_and_base_url_and_leases(
         store,
         Arc::new(MemorySessionAffinity::default()),
@@ -594,7 +1026,7 @@ fn provider_with_base_url_and_retry_budget(
 fn provider_with_leases(
     store: &Arc<MemoryAccountStore>,
     leases: Arc<TestLeaseCoordinator>,
-) -> CodexProvider {
+) -> Arc<CodexProvider> {
     provider_with_affinity_and_base_url_and_leases(
         store,
         Arc::new(MemorySessionAffinity::default()),
@@ -607,7 +1039,7 @@ fn provider_with_affinity_and_base_url(
     store: &Arc<MemoryAccountStore>,
     session_affinity: Arc<MemorySessionAffinity>,
     base_url: String,
-) -> CodexProvider {
+) -> Arc<CodexProvider> {
     provider_with_affinity_and_base_url_and_leases(
         store,
         session_affinity,
@@ -621,7 +1053,7 @@ fn provider_with_affinity_and_base_url_and_leases(
     session_affinity: Arc<MemorySessionAffinity>,
     base_url: String,
     leases: Arc<TestLeaseCoordinator>,
-) -> CodexProvider {
+) -> Arc<CodexProvider> {
     provider_and_quota_with_affinity_and_base_url_and_leases(
         store,
         session_affinity,
@@ -638,7 +1070,7 @@ fn provider_and_quota_with_affinity_and_base_url_and_leases(
     base_url: String,
     leases: Arc<TestLeaseCoordinator>,
     stream_max_retries: u32,
-) -> (CodexProvider, Arc<CodexCredentialQuotaService>) {
+) -> (Arc<CodexProvider>, Arc<CodexCredentialQuotaService>) {
     let (provider, quota, _) = provider_and_quota_with_runtime_ports(
         store,
         session_affinity,
@@ -660,7 +1092,7 @@ fn provider_and_quota_with_runtime_ports(
     cooldowns: Arc<MemoryCooldownPort>,
     policy: Arc<dyn gateway_core::provider_ports::ProviderRuntimePolicyPort>,
 ) -> (
-    CodexProvider,
+    Arc<CodexProvider>,
     Arc<CodexCredentialQuotaService>,
     Arc<CodexWebSocketPool>,
 ) {
@@ -710,7 +1142,7 @@ fn provider_and_quota_with_runtime_ports(
         stream_max_retries,
     )
     .expect("official OpenAI provider");
-    (provider, quota, websocket_pool)
+    (Arc::new(provider), quota, websocket_pool)
 }
 
 async fn create_account(store: &Arc<MemoryAccountStore>, id: &str) {
@@ -852,6 +1284,7 @@ fn planned_provider_endpoint_request(provider_name: &str, operation: Operation)
     let plan = snapshot
         .plan_provider_endpoint(
             &provider,
+            None,
             &operation,
             account_scope,
             &RoutingContext::default(),
@@ -933,6 +1366,118 @@ fn global_request_location() -> gateway_core::account::RequestLocation {
     }
 }
 
+#[derive(Debug)]
+struct TranslationMiddleware {
+    translations: Arc<Mutex<usize>>,
+    target: Map<String, Value>,
+}
+
+impl MiddlewarePlan for TranslationMiddleware {
+    fn handle(
+        &self,
+        context: MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        assert_eq!(context.mount(), MiddlewareMount::Attempt);
+        assert!(context.account_id().is_some());
+        *self.translations.lock().unwrap() += 1;
+        let (_, headers, _) = request.into_parts();
+        next.run(MiddlewareRequest::new(
+            "openai",
+            headers,
+            Bytes::from(serde_json::to_vec(&self.target).unwrap()),
+        ))
+    }
+}
+
+#[derive(Debug)]
+struct PassThroughMiddleware;
+
+impl MiddlewarePlan for PassThroughMiddleware {
+    fn handle(
+        &self,
+        _: MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        next.run(request)
+    }
+}
+
+#[derive(Debug)]
+struct RecordingMiddleware {
+    observed: Arc<Mutex<Vec<Map<String, Value>>>>,
+    replacement: (String, Value),
+    request_headers: Vec<MiddlewareHeader>,
+}
+
+impl MiddlewarePlan for RecordingMiddleware {
+    fn handle(
+        &self,
+        context: MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        assert_eq!(context.mount(), MiddlewareMount::Attempt);
+        assert_eq!(request.protocol(), "openai");
+        let (protocol, mut headers, bytes) = request.into_parts();
+        let mut body: Map<String, Value> = serde_json::from_slice(&bytes).unwrap();
+        self.observed.lock().unwrap().push(body.clone());
+        body.insert(self.replacement.0.clone(), self.replacement.1.clone());
+        headers.extend(self.request_headers.clone());
+        next.run(MiddlewareRequest::new(
+            protocol,
+            headers,
+            Bytes::from(serde_json::to_vec(&body).unwrap()),
+        ))
+    }
+}
+
+#[derive(Debug)]
+struct TestExtensionLease;
+
+impl ExtensionSetLease for TestExtensionLease {
+    fn is_ready(&self) -> bool {
+        true
+    }
+}
+
+fn context_with_middleware(
+    request_id: &str,
+    plan: Arc<dyn MiddlewarePlan>,
+    disable_fast: bool,
+) -> AttemptContext {
+    let plan = FrozenMiddlewarePlan::new(
+        plan,
+        ExtensionSetReference::new(
+            ExtensionSetId::new(format!("thinking-{request_id}")).unwrap(),
+            Arc::new(TestExtensionLease),
+        ),
+    );
+    AttemptContext::new(
+        RequestAttemptContext::new(
+            ModelRequestId::new(request_id).expect("request id"),
+            ClientApiKeyId::new("key_openai_contract").expect("client key id"),
+        )
+        .with_disable_fast(disable_fast)
+        .with_middleware(
+            Some(plan),
+            Arc::from([]),
+            "/v1/responses".to_owned(),
+            ClientTransport::HttpSse,
+        )
+        .with_request_location(Some(global_request_location())),
+        NonZeroU32::MIN,
+        SystemTime::now() + Duration::from_secs(30),
+        account_policy(),
+        AccountAttemptContext::new(BTreeSet::new(), None, None)
+            .with_account_scope(contract_account_scope()),
+        None,
+        CancellationToken::new(),
+    )
+}
+
 fn context(request_id: &str, cancellation: CancellationToken) -> AttemptContext {
     context_with_fast_policy(request_id, cancellation, false)
 }
@@ -1862,7 +2407,7 @@ async fn exhausted_account_pool_returns_usage_limit_before_http_or_websocket_net
     let server = MockServer::start().await;
     let provider = provider_with_base_url(&store, server.uri());
     for operation in [http_generate_operation(), generate_operation()] {
-        let Err(error) = provider
+        let Err(error) = Arc::clone(&provider)
             .execute(
                 planned_request("openai", operation),
                 context("req_exhausted_pool", CancellationToken::new()),
@@ -2044,7 +2589,7 @@ async fn image_endpoints_bypass_only_the_text_catalog_and_preserve_the_current_c
             )]));
         let operation = Operation::GenerateImage(ImageRequest::from_raw_json(*kind, payload));
         let request = planned_provider_endpoint_request("openai", operation);
-        let mut stream = provider
+        let mut stream = Arc::clone(&provider)
             .execute(
                 request,
                 context(
@@ -2518,7 +3063,7 @@ async fn assert_cross_endpoint_affinity(thread_id: Option<&str>) {
         Arc::clone(&leases),
     );
     let root = Operation::Generate(generate_with_session_context("shared-root", None, None));
-    let root_stream = provider
+    let root_stream = Arc::clone(&provider)
         .execute(
             planned_request("openai", root.clone()),
             context("req_cross_endpoint_root", CancellationToken::new()),
@@ -2532,7 +3077,7 @@ async fn assert_cross_endpoint_affinity(thread_id: Option<&str>) {
         thread_id,
         None,
     ));
-    let first = provider
+    let first = Arc::clone(&provider)
         .execute(
             planned_request("openai", generation.clone()),
             context("req_cross_endpoint_first", CancellationToken::new()),
@@ -2581,7 +3126,7 @@ async fn assert_cross_endpoint_affinity(thread_id: Option<&str>) {
             .continuation
             .affinity_hash
     );
-    let mut same = provider
+    let mut same = Arc::clone(&provider)
         .execute(
             planned_provider_endpoint_request("openai", search.clone()),
             context("req_cross_endpoint_search", CancellationToken::new()),
@@ -2604,7 +3149,7 @@ async fn assert_cross_endpoint_affinity(thread_id: Option<&str>) {
         .lock()
         .expect("busy accounts")
         .insert(first_account.clone());
-    let mut fallback = provider
+    let mut fallback = Arc::clone(&provider)
         .execute(
             planned_provider_endpoint_request("openai", search),
             context("req_cross_endpoint_busy", CancellationToken::new()),
@@ -2629,7 +3174,7 @@ async fn assert_cross_endpoint_affinity(thread_id: Option<&str>) {
     );
     store.set_scheduling(other_account, None, AccountWeight::new(1).expect("weight"));
 
-    let resumed = provider
+    let resumed = Arc::clone(&provider)
         .execute(
             planned_request("openai", generation.clone()),
             context("req_cross_endpoint_resumed", CancellationToken::new()),
@@ -2666,7 +3211,7 @@ async fn assert_cross_endpoint_affinity(thread_id: Option<&str>) {
                 .continuation
                 .affinity_hash
         );
-        let selected_image = provider
+        let selected_image = Arc::clone(&provider)
             .execute(
                 planned_provider_endpoint_request("openai", image),
                 context("req_cross_endpoint_image", CancellationToken::new()),
@@ -2680,7 +3225,7 @@ async fn assert_cross_endpoint_affinity(thread_id: Option<&str>) {
         drop(selected_image);
     }
     if thread_id.is_some() {
-        let root_stream = provider
+        let root_stream = Arc::clone(&provider)
             .execute(
                 planned_request("openai", root),
                 context(
@@ -3029,7 +3574,7 @@ async fn websocket_close_after_delivery_preserves_details_and_reconnects_through
         SESSION_ID,
         "thread-first",
     ));
-    let mut stream = provider
+    let mut stream = Arc::clone(&provider)
         .execute(
             planned_request("openai", first_operation),
             context("req_websocket_close", CancellationToken::new()),
@@ -3184,7 +3729,7 @@ async fn websocket_fast_path_miss_uses_http_and_keeps_background_preconnect() {
         ))
     };
 
-    let mut first = provider
+    let mut first = Arc::clone(&provider)
         .execute(
             planned_request("openai", operation("thread-http-fallback")),
             context("req_fast_path_http", CancellationToken::new()),
@@ -3704,7 +4249,7 @@ async fn ambiguous_websocket_close_reconnects_and_retains_native_continuation()
         SESSION_ID,
         "thread-first",
     ));
-    let mut stream = provider
+    let mut stream = Arc::clone(&provider)
         .execute(
             planned_request("openai", operation),
             context("req_websocket_normal_close", CancellationToken::new()),
@@ -3777,7 +4322,7 @@ async fn ambiguous_websocket_close_reconnects_and_retains_native_continuation()
         SESSION_ID,
         "thread-second",
     ));
-    let mut fresh_stream = provider
+    let mut fresh_stream = Arc::clone(&provider)
         .execute(
             planned_request("openai", second_operation),
             context("req_websocket_fresh_retry", CancellationToken::new()),
@@ -3814,7 +4359,7 @@ async fn ambiguous_websocket_close_reconnects_and_retains_native_continuation()
         )
         .with_provider_session_state(recovered_session),
     );
-    let mut continuation_stream = provider
+    let mut continuation_stream = Arc::clone(&provider)
         .execute(
             planned_request("openai", continuation_operation),
             pinned_continuation_context(
@@ -3842,7 +4387,7 @@ async fn ambiguous_websocket_close_reconnects_and_retains_native_continuation()
         Some("thread-first"),
         None,
     ));
-    let mut other_stream = provider
+    let mut other_stream = Arc::clone(&provider)
         .execute(
             planned_request("openai", other_operation),
             context("req_other_session_websocket", CancellationToken::new()),
@@ -3933,7 +4478,7 @@ async fn repeated_websocket_failures_exhaust_budget_then_use_http_and_report_htt
             "repeated-close",
             "turn",
         ));
-        let mut stream = provider
+        let mut stream = Arc::clone(&provider)
             .execute(
                 planned_request("openai", operation),
                 context(
@@ -3962,7 +4507,7 @@ async fn repeated_websocket_failures_exhaust_budget_then_use_http_and_report_htt
             "repeated-close",
             "turn",
         ));
-        let mut stream = provider
+        let mut stream = Arc::clone(&provider)
             .execute(
                 planned_request("openai", operation),
                 context(
@@ -4046,7 +4591,7 @@ async fn websocket_upgrade_required_immediately_enables_session_http_fallback()
             None,
         ))
     };
-    let mut first = provider
+    let mut first = Arc::clone(&provider)
         .execute(
             planned_request("openai", operation()),
             context("req_upgrade_required", CancellationToken::new()),
@@ -4067,7 +4612,7 @@ async fn websocket_upgrade_required_immediately_enables_session_http_fallback()
     );
     drop(first);
 
-    let mut second = provider
+    let mut second = Arc::clone(&provider)
         .execute(
             planned_request("openai", operation()),
             context("req_upgrade_required_next_turn", CancellationToken::new()),
@@ -4081,7 +4626,7 @@ async fn websocket_upgrade_required_immediately_enables_session_http_fallback()
     tokio::time::pause();
     for index in 0..3 {
         tokio::time::advance(Duration::from_secs(5 * 60 * 60)).await;
-        let stream = provider
+        let stream = Arc::clone(&provider)
             .execute(
                 planned_request("openai", operation()),
                 context(
@@ -4093,7 +4638,7 @@ async fn websocket_upgrade_required_immediately_enables_session_http_fallback()
             .expect("prepare active session");
         assert_eq!(stream.metadata().transport().as_str(), "http_sse");
     }
-    let unrelated = provider
+    let unrelated = Arc::clone(&provider)
         .execute(
             planned_request(
                 "openai",
@@ -4194,7 +4739,7 @@ async fn downstream_websocket_new_chain_should_override_session_and_attempt_http
         }
     });
     let provider = provider_with_base_url(&store, base_url);
-    let mut seed = provider
+    let mut seed = Arc::clone(&provider)
         .execute(
             planned_request(
                 "openai",
@@ -4246,7 +4791,7 @@ async fn downstream_websocket_new_chain_should_override_session_and_attempt_http
             )
             .unwrap(),
         );
-        let mut stream = provider
+        let mut stream = Arc::clone(&provider)
             .execute(
                 planned_request("openai", Operation::Generate(request)),
                 attempt,
@@ -5431,7 +5976,7 @@ async fn account_selection_log_should_include_affinity_observation_fields() {
             )]));
         }
         let generation = GenerateRequest::from_protocol_payload(payload);
-        let stream = provider
+        let stream = Arc::clone(&provider)
             .execute(
                 planned_request("openai", Operation::Generate(generation)),
                 context(request_id, CancellationToken::new()),
@@ -5547,7 +6092,7 @@ async fn subagent_requests_should_share_the_root_session_account_affinity_key()
                 .expect("OpenAI payload")
                 .with_context(Map::from_iter([("use_websocket".to_owned(), json!(false))])),
         );
-        let mut stream = provider
+        let mut stream = Arc::clone(&provider)
             .execute(
                 planned_request("openai", Operation::Generate(generation)),
                 context(request_id, CancellationToken::new()),
@@ -5611,7 +6156,7 @@ async fn explicit_session_id_should_override_turn_specific_prompt_cache_keys_for
             )])),
         );
 
-        let stream = provider
+        let stream = Arc::clone(&provider)
             .execute(
                 planned_request("openai", Operation::Generate(generation)),
                 context(request_id, CancellationToken::new()),
@@ -5662,7 +6207,7 @@ async fn affinity_quota_switch_should_clear_old_turn_state_without_a_provider_st
     )
     .expect("OpenAI payload")
     .with_context(Map::from_iter([("use_websocket".to_owned(), json!(false))]));
-    let first = provider
+    let first = Arc::clone(&provider)
         .execute(
             planned_request(
                 "openai",
@@ -5801,7 +6346,7 @@ async fn thread_spawn_children_should_inherit_the_root_with_independent_scoped_b
                 .affinity_hash
                 .expect("affinity hash"),
         );
-        let stream = provider
+        let stream = Arc::clone(&provider)
             .execute(
                 planned_request("openai", operation),
                 context(request_id, CancellationToken::new()),
@@ -5928,7 +6473,7 @@ async fn child_busy_failover_should_leave_the_running_parent_and_siblings_on_the
         server.uri(),
         Arc::clone(&leases),
     );
-    let child = provider
+    let child = Arc::clone(&provider)
         .execute(
             planned_request("openai", operation("child-one")),
             context("req_child_inherit", CancellationToken::new()),
@@ -5949,7 +6494,7 @@ async fn child_busy_failover_should_leave_the_running_parent_and_siblings_on_the
         .expect("busy accounts")
         .insert(root_account.clone());
     for thread in ["child-one", "cold-child"] {
-        let mut child = provider
+        let mut child = Arc::clone(&provider)
             .execute(
                 planned_request("openai", operation(thread)),
                 context("req_child_busy", CancellationToken::new()),
@@ -5990,7 +6535,7 @@ async fn child_busy_failover_should_leave_the_running_parent_and_siblings_on_the
         ("cold-child", "acct_subagent_b"),
         ("new-sibling", "acct_subagent_a"),
     ] {
-        let stream = provider
+        let stream = Arc::clone(&provider)
             .execute(
                 planned_request("openai", operation(thread)),
                 context("req_after_parent_completion", CancellationToken::new()),
@@ -6046,7 +6591,7 @@ async fn failed_child_failover_should_preserve_both_existing_bindings() {
         Arc::clone(&leases),
     );
     for thread in [None, Some("child")] {
-        let stream = provider
+        let stream = Arc::clone(&provider)
             .execute(
                 planned_request(
                     "openai",
@@ -6075,7 +6620,7 @@ async fn failed_child_failover_should_preserve_both_existing_bindings() {
         )
         .expect("search payload"),
     ));
-    let mut child = provider
+    let mut child = Arc::clone(&provider)
         .execute(
             planned_provider_endpoint_request("openai", search),
             context("req_failed_child", CancellationToken::new()),
@@ -6097,7 +6642,7 @@ async fn failed_child_failover_should_preserve_both_existing_bindings() {
     drop(child);
     leases.busy_accounts.lock().expect("busy accounts").clear();
     for thread in [None, Some("child")] {
-        let stream = provider
+        let stream = Arc::clone(&provider)
             .execute(
                 planned_request(
                     "openai",
@@ -6813,7 +7358,7 @@ fn provider_with_capacity_tracking(
     store: &Arc<MemoryAccountStore>,
     base_url: String,
     cooldowns: Arc<MemoryCooldownPort>,
-) -> (CodexProvider, Arc<CodexWebSocketPool>) {
+) -> (Arc<CodexProvider>, Arc<CodexWebSocketPool>) {
     let (provider, _, pool) = provider_and_quota_with_runtime_ports(
         store,
         Arc::new(MemorySessionAffinity::default()),
@@ -6888,7 +7433,7 @@ async fn capacity_feedback_only_counts_overload_rejections_and_excludes_diagnost
                     } else {
                         http_generate_operation()
                     };
-                    let mut stream = provider
+                    let mut stream = Arc::clone(&provider)
                         .execute(planned_request("openai", operation), attempt)
                         .await
                         .expect("prepare upstream attempt");
@@ -7670,7 +8215,7 @@ async fn exact_websocket_busy_then_replay_scope_relaxation_is_rejected_before_se
     )
     .expect("initial provider session state");
 
-    let mut seed = provider
+    let mut seed = Arc::clone(&provider)
         .execute(
             planned_request("openai", operation(None, initial_session_state)),
             context("req_ws_busy_seed", CancellationToken::new()),
@@ -7694,7 +8239,7 @@ async fn exact_websocket_busy_then_replay_scope_relaxation_is_rejected_before_se
     );
 
     let continuation = operation(Some(CLIENT_PREVIOUS_RESPONSE_ID), session_state);
-    let mut busy = provider
+    let mut busy = Arc::clone(&provider)
         .execute(
             planned_request("openai", continuation.clone()),
             pinned_continuation_context(
@@ -7719,7 +8264,7 @@ async fn exact_websocket_busy_then_replay_scope_relaxation_is_rejected_before_se
         }
     }
 
-    let mut exact = provider
+    let mut exact = Arc::clone(&provider)
         .execute(
             planned_request("openai", continuation.clone()),
             pinned_continuation_context(
@@ -7761,7 +8306,7 @@ async fn exact_websocket_busy_then_replay_scope_relaxation_is_rejected_before_se
         ),
         ("req_ws_busy_replay_any", 3, ContinuationAttempt::ReplayAny),
     ] {
-        let result = provider
+        let result = Arc::clone(&provider)
             .execute(
                 planned_request("openai", continuation.clone()),
                 pinned_continuation_context(
@@ -8556,7 +9101,7 @@ async fn completed_websocket_response_resets_consecutive_failure_budget() {
             "budget-reset",
             "turn",
         ));
-        let mut stream = provider
+        let mut stream = Arc::clone(&provider)
             .execute(
                 planned_request("openai", operation),
                 context(
@@ -8624,7 +9169,7 @@ async fn connection_limit_rejection_requests_one_provider_retry_and_reconnects_i
             "turn",
         ))
     };
-    let mut stream = provider
+    let mut stream = Arc::clone(&provider)
         .execute(
             planned_request("openai", operation()),
             context("req_rejected", CancellationToken::new()),
@@ -8890,7 +9435,7 @@ async fn assert_websocket_failure_headers(headers: Value, request_id: Option<&st
         ))
     };
     if reuse {
-        let mut first = provider
+        let mut first = Arc::clone(&provider)
             .execute(
                 planned_request("openai", operation()),
                 context("req_ws_initial", CancellationToken::new()),
@@ -9101,7 +9646,7 @@ async fn api_key_native_endpoints_preserve_bodies_headers_and_own_base_url() {
                 )),
                 _ => Operation::Search(StandaloneSearchRequest::from_raw_json(payload)),
             };
-            let mut stream = provider
+            let mut stream = Arc::clone(&provider)
                 .execute(
                     planned_provider_endpoint_request("openai", operation),
                     context(
@@ -9424,7 +9969,7 @@ async fn disabled_api_key_diagnostic_preserves_authentication_and_transport_cons
         .mount(&upstream)
         .await;
     let provider = provider_with_base_url(&store, oauth.uri());
-    let mut stream = provider
+    let mut stream = Arc::clone(&provider)
         .execute(
             planned_request("openai", generate_operation()),
             diagnostic_context("req_disabled_api_http", account_id),
@@ -9458,7 +10003,7 @@ async fn disabled_api_key_diagnostic_preserves_authentication_and_transport_cons
         )
         .expect("search payload"),
     ));
-    let result = provider
+    let result = Arc::clone(&provider)
         .execute(
             planned_request("openai", warmup),
             diagnostic_context("req_disabled_api_restricted", account_id),
@@ -9514,7 +10059,7 @@ async fn api_key_http_account_is_rejected_before_websocket_warmup_or_old_revisio
         .unwrap(),
     ));
     assert!(
-        provider
+        Arc::clone(&provider)
             .execute(
                 planned_request("openai", warmup),
                 diagnostic_context("req_api_warmup", "acct_provider_contract")
@@ -9968,7 +10513,7 @@ async fn quota_continuation_full_client_replay_selects_another_account() {
         "quota-replay",
         "turn",
     ));
-    let mut stream = provider
+    let mut stream = Arc::clone(&provider)
         .execute(
             planned_request("openai", first),
             context("req_quota_first", CancellationToken::new()),
@@ -9983,7 +10528,7 @@ async fn quota_continuation_full_client_replay_selects_another_account() {
         event.unwrap();
     }
     drop(stream);
-    let mut stream = provider
+    let mut stream = Arc::clone(&provider)
         .execute(
             planned_request("openai", quota_continuation_operation(true)),
             context("req_quota_delta", CancellationToken::new())
@@ -10165,7 +10710,7 @@ async fn fast_policy_changes_preserve_the_websocket_continuation_and_meter_each_
         } else {
             ContinuationAttempt::None
         });
-        let mut stream = provider
+        let mut stream = Arc::clone(&provider)
             .execute(planned_request("openai", operation), context)
             .await
             .unwrap();
diff --git a/backend/crates/providers/xai/src/admin.rs b/backend/crates/providers/xai/src/admin.rs
index eb4fa6d91..268a29b4d 100644
--- a/backend/crates/providers/xai/src/admin.rs
+++ b/backend/crates/providers/xai/src/admin.rs
@@ -321,6 +321,19 @@ impl XaiAdminProvider {
 
 #[async_trait]
 impl ProviderAdmin for XaiAdminProvider {
+    fn account_capabilities(
+        &self,
+        _account_id: &ProviderAccountId,
+        authentication_kind: &str,
+    ) -> gateway_admin::model::provider_capabilities::ProviderAccountCapabilities {
+        let oauth = authentication_kind == crate::credential::XAI_AUTHENTICATION_KIND_OAUTH;
+        gateway_admin::model::provider_capabilities::ProviderAccountCapabilities {
+            quota: oauth,
+            quota_refresh: oauth,
+            ..Default::default()
+        }
+    }
+
     fn client_profile_options(
         &self,
     ) -> Result<gateway_core::account::OpaqueProviderData, ProviderAdminError> {
@@ -378,6 +391,23 @@ impl ProviderAdmin for XaiAdminProvider {
     fn pricing_catalog(&self) -> gateway_admin::model::pricing::ProviderPricingCatalog {
         crate::transport::canonical::pricing_catalog()
     }
+    fn credential_capabilities(
+        &self,
+    ) -> gateway_admin::model::provider_capabilities::ProviderCredentialCapabilities {
+        use gateway_admin::model::provider_capabilities::{
+            AuthorizationCompletion, ProviderCredentialCapabilities, ProviderLoginCapability,
+        };
+        ProviderCredentialCapabilities {
+            import: Some(serde_json::json!({"type":"object"})),
+            login: Some(ProviderLoginCapability {
+                input_schema: serde_json::json!({"type":"object", "additionalProperties":false}),
+                completion: AuthorizationCompletion::Callback,
+            }),
+            refresh: true,
+            export: true,
+        }
+    }
+
     fn provider_kind(&self) -> &ProviderKind {
         &self.provider_kind
     }
@@ -391,7 +421,7 @@ impl ProviderAdmin for XaiAdminProvider {
         self.quota.invalidate_scheduling(account_ids);
     }
 
-    fn connection_test_operation(
+    async fn connection_test_operation(
         &self,
         upstream_model: &UpstreamModelId,
         input_text: &str,
@@ -586,8 +616,17 @@ impl ProviderAdmin for XaiAdminProvider {
 
     async fn start_authorization(
         &self,
-        pending: PendingAuthorizationMutation,
+        command: gateway_admin::model::provider_credentials::PrepareAuthorization,
     ) -> Result<AuthorizationStarted, ProviderAdminError> {
+        if !command
+            .input
+            .expose_to_provider()
+            .expose_to_provider()
+            .is_empty()
+        {
+            return Err(provider_error(ProviderAdminErrorKind::Invalid));
+        }
+        let pending = command.pending;
         if pending.provider_kind() != &self.provider_kind {
             return Err(provider_error(ProviderAdminErrorKind::Invalid));
         }
@@ -901,16 +940,19 @@ impl XaiAdminProvider {
                         .with_outbound_proxy(stored.mutation.outbound_proxy().cloned()),
                     credential: prepared.credential,
                 };
-                PreparedAuthorizationCredential::Create(prepared_create(prepared, Utc::now())?)
+                PreparedAuthorizationCredential::Create(vec![prepared_create(
+                    prepared,
+                    Utc::now(),
+                )?])
             }
             AuthorizationMutationTarget::Reauthorize { .. } => {
                 let current =
                     current.ok_or_else(|| provider_error(ProviderAdminErrorKind::Internal))?;
                 let prepared = verified_rotation(current, tokens)?;
-                PreparedAuthorizationCredential::Reauthorize(prepared_rotation(
+                PreparedAuthorizationCredential::Reauthorize(Box::new(prepared_rotation(
                     prepared,
                     self.provider_kind.clone(),
-                )?)
+                )?))
             }
         };
         Ok(PreparedAuthorizationCommit::new(
diff --git a/backend/crates/providers/xai/src/credential/selector.rs b/backend/crates/providers/xai/src/credential/selector.rs
index bd6cd65af..7f8f7689f 100644
--- a/backend/crates/providers/xai/src/credential/selector.rs
+++ b/backend/crates/providers/xai/src/credential/selector.rs
@@ -11,6 +11,7 @@ use gateway_core::account::{
     QuotaAccessState, QuotaEvidence, QuotaState,
 };
 use gateway_core::concurrency::{CapacityWait, ConcurrencyWaitQueue};
+use gateway_core::engine::policy::AccountPolicyError;
 use gateway_core::provider_ports::{
     ProviderCooldown, ProviderCooldownPort, ProviderCooldownScope, ProviderLeaseAcquisition,
     ProviderLeasePort, ProviderLeaseRequest, ProviderSchedulingLeaseRequest,
@@ -98,7 +99,7 @@ impl GrokAccountSessionSelector {
             request.deadline(),
             request.concurrency_wait_budget(),
         );
-        loop {
+        'refresh: loop {
             let diagnostic = request.eligibility() == AccountEligibilityPolicy::BypassForDiagnostic;
             // store 侧常规调度列表不包含停用账号；管理端诊断要对固定账号执行真实上游
             // 验证，这里把不在列表里的 required 账号显式补回候选。
@@ -243,7 +244,30 @@ impl GrokAccountSessionSelector {
             let mut retry_after = None;
             loop {
                 let capacity = AccountSelector.capacity_snapshot(&candidates, &capacity_context);
-                let Some(selection) = AccountSelector.select(&candidates, &context) else {
+                let selection = match request.request_policy() {
+                    Some(policy) => {
+                        policy
+                            .select_account(
+                                request.attempt_index(),
+                                &self.provider_kind,
+                                Some(request.upstream_model().as_str()),
+                                &candidates,
+                                &context,
+                            )
+                            .await
+                    }
+                    None => Ok(AccountSelector.select(&candidates, &context)),
+                };
+                let Some(selection) = (match selection {
+                    Ok(selection) => selection,
+                    Err(AccountPolicyError::StaleCandidate) => continue 'refresh,
+                    Err(AccountPolicyError::Rejected) => {
+                        return Err(GrokSessionSelectorError::PolicyRejected);
+                    }
+                    Err(AccountPolicyError::Fault) => {
+                        return Err(GrokSessionSelectorError::PolicyUnavailable);
+                    }
+                }) else {
                     break;
                 };
                 let selected = selection.candidate();
diff --git a/backend/crates/providers/xai/src/provider/failure.rs b/backend/crates/providers/xai/src/provider/failure.rs
index 04ddb823c..86434adc5 100644
--- a/backend/crates/providers/xai/src/provider/failure.rs
+++ b/backend/crates/providers/xai/src/provider/failure.rs
@@ -415,6 +415,15 @@ pub(super) fn map_selection_error(error: GrokSessionSelectorError) -> ProviderEr
             "account scheduling state is temporarily unreadable".to_owned(),
             "account_selector_unavailable",
         ),
+        GrokSessionSelectorError::PolicyRejected => {
+            return provider_error(
+                ProviderErrorKind::RequestPolicyDenied,
+                UpstreamSendState::NotSent,
+            );
+        }
+        GrokSessionSelectorError::PolicyUnavailable => {
+            return provider_error(ProviderErrorKind::Unavailable, UpstreamSendState::NotSent);
+        }
         GrokSessionSelectorError::InvalidSession => {
             return provider_error(ProviderErrorKind::Protocol, UpstreamSendState::NotSent);
         }
diff --git a/backend/crates/providers/xai/src/provider/mod.rs b/backend/crates/providers/xai/src/provider/mod.rs
index 147152c51..09b4200d2 100644
--- a/backend/crates/providers/xai/src/provider/mod.rs
+++ b/backend/crates/providers/xai/src/provider/mod.rs
@@ -11,6 +11,7 @@ use gateway_core::account::{
     ProviderAccountStore,
 };
 use gateway_core::engine::continuation::ContinuationBinding;
+use gateway_core::engine::middleware::MiddlewareHeader;
 use gateway_core::engine::provider::{
     EventStream, Provider, ProviderCallMetadata, ProviderRequest, ProviderRequestObservation,
     ProviderSelectionObservation, ProviderStream,
@@ -25,7 +26,8 @@ use gateway_core::event::{
     ProviderResponseTimings, ResponseMeta,
 };
 use gateway_core::operation::{
-    Feature, GenerateRequest, Operation, OperationKind, ProviderSessionState,
+    CapabilityRequirements, Feature, GenerateRequest, Operation, OperationKind,
+    ProviderSessionState,
 };
 use gateway_core::routing::{
     ModelCapabilities, ModelPresentation, ProviderCandidate, ProviderCatalogGeneration,
@@ -52,7 +54,7 @@ use crate::reasoning_replay::{
     GrokReasoningReplay, GrokReasoningReplayCapture, GrokReasoningReplayKey,
     valid_reasoning_ciphertext,
 };
-use crate::transport::canonical::GrokCanonicalDecoder;
+use crate::transport::canonical::{GrokCanonicalDecoder, GrokNativeResponseTranslator};
 use crate::transport::config::XAI_PROVIDER_NAME;
 use crate::transport::headers::{GrokClientIdentity, build_grok_headers};
 use crate::transport::profile::{GROK_CLI_RELEASE_POLL_INTERVAL, GrokCliReleaseService};
@@ -89,6 +91,7 @@ const RESPONSE_NOT_FOUND_CODE: &str = "not_found";
 /// 每次调用只选择一个 OAuth 会话。仅当 xAI 明确拒绝历史 reasoning 密文时，
 /// 允许在同账号、同凭据、同会话绑定上剥离密文后有界重试一次。凭据轮换、
 /// endpoint fallback 以及公开 xAI API key 推理都不在该 adapter 内。
+#[derive(Clone)]
 pub struct GrokBuildProvider {
     selector: Arc<dyn GrokSessionSelector>,
     transport: Arc<dyn GrokInferenceTransport>,
@@ -101,6 +104,24 @@ pub struct GrokBuildProvider {
     responses_url: Url,
 }
 
+struct PreparedGrokAttempt {
+    generate: GenerateRequest,
+    middleware_headers: Vec<MiddlewareHeader>,
+    previous_session: Option<XaiSessionState>,
+    upstream_model: UpstreamModelId,
+    selected: SelectedGrokSession,
+    account_selection_wait_ms: u64,
+    context: AttemptContext,
+}
+
+struct SelectedGrokAttempt {
+    upstream_model: UpstreamModelId,
+    selected: SelectedGrokSession,
+    account_selection_wait_ms: u64,
+    context: AttemptContext,
+    frozen_requirements: CapabilityRequirements,
+}
+
 impl GrokBuildProvider {
     /// 在显式的会话与 transport 边界上创建 Provider。
     pub fn new(
@@ -194,7 +215,7 @@ impl Provider for GrokBuildProvider {
     }
 
     async fn execute(
-        &self,
+        self: Arc<Self>,
         request: ProviderRequest,
         context: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
@@ -240,19 +261,181 @@ impl GrokBuildProvider {
     }
 
     async fn execute_generate(
-        &self,
+        self: Arc<Self>,
         generate: &GenerateRequest,
         candidate: &ProviderCandidate,
         context: AttemptContext,
     ) -> Result<ProviderStream, ProviderError> {
-        if crate::transport::compaction::has_terminal_compaction_trigger(generate) {
-            return self.execute_compaction(generate, candidate, context).await;
-        }
+        let selected = self
+            .select_grok_attempt(generate, candidate, context)
+            .await?;
+        let provider_kind =
+            ProviderKind::new(XAI_PROVIDER_NAME).map_err(|_| protocol_not_sent())?;
+        let account_id = selected.selected.account_id().clone();
+        let model = selected.upstream_model.as_str().to_owned();
+        let middleware_context = selected.context.clone();
+        let provider = Arc::clone(&self);
+        middleware_context
+            .execute_middleware(
+                Operation::Generate(generate.clone()),
+                provider_kind,
+                Some(model),
+                account_id,
+                Box::new(move |operation, middleware_headers| {
+                    Box::pin(async move {
+                        provider
+                            .execute_selected_grok(operation, middleware_headers, selected)
+                            .await
+                    })
+                }),
+            )
+            .await
+    }
+
+    async fn select_grok_attempt(
+        &self,
+        generate: &GenerateRequest,
+        candidate: &ProviderCandidate,
+        context: AttemptContext,
+    ) -> Result<SelectedGrokAttempt, ProviderError> {
         let upstream_model = candidate_upstream_model(candidate)?;
         let previous_session = decode_xai_session_state(generate)?;
-        let continuation_account = continuation_account(&context, previous_session.as_ref())?;
-        let mut upstream_request = GrokResponsesRequest::encode(
+        let native_source = generate.protocol_payload().protocol() == "openai";
+        let native_compaction = native_source
+            && crate::transport::compaction::has_terminal_compaction_trigger(generate);
+        let (selection_model, operation_account, affinity) = if native_compaction {
+            validate_compaction_context(&context)?;
+            let operation_account = previous_session_account(previous_session.as_ref())?;
+            let request = GrokCompactionRequest::encode(
+                generate,
+                upstream_model.as_str(),
+                context.client_api_key_ref(),
+            )
+            .map_err(map_request_error)?;
+            let selection_model = request
+                .upstream_model()
+                .ok_or_else(protocol_not_sent)?
+                .to_owned();
+            (
+                selection_model,
+                merge_frozen_account_owner(&context, operation_account)?,
+                request.affinity().cloned(),
+            )
+        } else if native_source {
+            let operation_account = continuation_account(&context, previous_session.as_ref())?;
+            let request = GrokResponsesRequest::encode(
+                generate,
+                upstream_model.as_str(),
+                context.client_api_key_ref(),
+            )
+            .map_err(map_request_error)?;
+            let selection_model = request
+                .upstream_model()
+                .ok_or_else(protocol_not_sent)?
+                .to_owned();
+            (
+                selection_model,
+                merge_frozen_account_owner(&context, operation_account)?,
+                request.affinity().cloned(),
+            )
+        } else {
+            // 源协议由转换插件拥有；这里只使用冻结的候选模型与 Core 账号 owner，
+            // 不把未知 JSON 中的同名字段解释为 xAI 会话或亲和事实。
+            let operation_account = continuation_account(&context, previous_session.as_ref())?;
+            (
+                upstream_model.as_str().to_owned(),
+                merge_frozen_account_owner(&context, operation_account)?,
+                None,
+            )
+        };
+        let selection_model =
+            UpstreamModelId::new(selection_model).map_err(|_| protocol_not_sent())?;
+        let selection_started_at = Instant::now();
+        let selected = select_grok_session(
+            self.selector.as_ref(),
+            candidate,
+            &selection_model,
+            &context,
+            operation_account,
+            affinity,
+        )
+        .await?;
+        let account_selection_wait_ms =
+            u64::try_from(selection_started_at.elapsed().as_millis()).unwrap_or(u64::MAX);
+        Ok(SelectedGrokAttempt {
+            upstream_model: upstream_model.clone(),
+            selected,
+            account_selection_wait_ms,
+            context,
+            frozen_requirements: Operation::Generate(generate.clone()).capability_requirements(),
+        })
+    }
+
+    async fn execute_selected_grok(
+        &self,
+        operation: Operation,
+        middleware_headers: Vec<MiddlewareHeader>,
+        selected: SelectedGrokAttempt,
+    ) -> Result<ProviderStream, ProviderError> {
+        let SelectedGrokAttempt {
+            upstream_model,
+            selected,
+            account_selection_wait_ms,
+            context,
+            frozen_requirements,
+        } = selected;
+        let Operation::Generate(generate) = operation else {
+            return Err(protocol_not_sent());
+        };
+        if generate.protocol_payload().protocol() != "openai"
+            || native_request_requirements(&generate) != frozen_requirements
+        {
+            return Err(provider_error(
+                ProviderErrorKind::InvalidRequest,
+                UpstreamSendState::NotSent,
+            ));
+        }
+        let previous_session = decode_xai_session_state(&generate)?;
+        let operation_account =
+            if crate::transport::compaction::has_terminal_compaction_trigger(&generate) {
+                validate_compaction_context(&context)?;
+                previous_session_account(previous_session.as_ref())?
+            } else {
+                continuation_account(&context, previous_session.as_ref())?
+            };
+        let operation_account = merge_frozen_account_owner(&context, operation_account)?;
+        validate_selected_grok_account(&selected, &context, operation_account.as_ref())?;
+        let prepared = PreparedGrokAttempt {
             generate,
+            middleware_headers,
+            previous_session,
+            upstream_model,
+            selected,
+            account_selection_wait_ms,
+            context,
+        };
+        if crate::transport::compaction::has_terminal_compaction_trigger(&prepared.generate) {
+            self.execute_prepared_compaction(prepared).await
+        } else {
+            self.execute_prepared_generate(prepared).await
+        }
+    }
+
+    async fn execute_prepared_generate(
+        &self,
+        prepared: PreparedGrokAttempt,
+    ) -> Result<ProviderStream, ProviderError> {
+        let PreparedGrokAttempt {
+            generate,
+            middleware_headers,
+            previous_session,
+            upstream_model,
+            selected,
+            account_selection_wait_ms,
+            context,
+        } = prepared;
+        let mut upstream_request = GrokResponsesRequest::encode(
+            &generate,
             upstream_model.as_str(),
             context.client_api_key_ref(),
         )
@@ -269,18 +452,6 @@ impl GrokBuildProvider {
         if let Some(previous) = previous_session.as_ref() {
             upstream_request.inherit_session(previous.session_id.as_deref());
         }
-        let selection_started_at = Instant::now();
-        let selected = select_grok_session(
-            self.selector.as_ref(),
-            candidate,
-            &wire_upstream_model,
-            &context,
-            continuation_account,
-            upstream_request.affinity().cloned(),
-        )
-        .await?;
-        let account_selection_wait_ms =
-            u64::try_from(selection_started_at.elapsed().as_millis()).unwrap_or(u64::MAX);
         // 首字计时的起点：账号选择完成之后、上游建立之前。
         let output_started_at = Instant::now();
         apply_continuation(
@@ -320,6 +491,8 @@ impl GrokBuildProvider {
                 .set_replay_input(input)
                 .map_err(map_request_error)?;
         }
+        let native_response_translator =
+            GrokNativeResponseTranslator::for_request(&upstream_request);
         let reasoning_replay_capture =
             reasoning_replay_key.map(|key| self.reasoning_replay.capture(key));
         let session_capture = (!matches!(
@@ -341,7 +514,8 @@ impl GrokBuildProvider {
         });
         let selected = Arc::new(selected);
         let allows_account_state_mutation = selected.allows_account_state_mutation();
-        let metadata = provider_call_metadata(candidate, &selected, account_selection_wait_ms)?;
+        let metadata =
+            provider_call_metadata(&upstream_model, &selected, account_selection_wait_ms)?;
         let events = cold_http_sse_stream(
             Arc::clone(&self.selector),
             Arc::clone(&self.transport),
@@ -351,48 +525,44 @@ impl GrokBuildProvider {
                 credential_recovery: Arc::clone(&self.credential_recovery),
                 responses_url: self.responses_url.clone(),
                 request: upstream_request,
+                middleware_headers,
                 upstream_model: wire_upstream_model,
                 context,
                 session: Arc::clone(&selected),
                 output_started_at,
+                native_response_boundary: true,
                 session_capture,
                 reasoning_replay_capture,
             },
         );
         let stream = ProviderStream::new(metadata, events, selected);
-        Ok(if allows_account_state_mutation {
+        let stream = if allows_account_state_mutation {
             stream.with_account_feedback(Arc::clone(&self.account_feedback))
         } else {
             stream
-        })
+        };
+        Ok(stream.with_native_response_translator(native_response_translator))
     }
 
-    async fn execute_compaction(
+    async fn execute_prepared_compaction(
         &self,
-        generate: &GenerateRequest,
-        candidate: &ProviderCandidate,
-        context: AttemptContext,
+        prepared: PreparedGrokAttempt,
     ) -> Result<ProviderStream, ProviderError> {
-        if context.continuation().is_some()
-            || context.continuation_attempt() != ContinuationAttempt::None
-        {
-            return Err(provider_error(
-                ProviderErrorKind::InvalidRequest,
-                UpstreamSendState::NotSent,
-            ));
-        }
-        let previous_session = decode_xai_session_state(generate)?;
-        let operation_account = previous_session
-            .as_ref()
-            .map(|previous| ProviderAccountId::new(previous.account_id.clone()))
-            .transpose()
-            .map_err(|_| protocol_not_sent())?;
+        let PreparedGrokAttempt {
+            generate,
+            middleware_headers,
+            previous_session,
+            upstream_model,
+            selected,
+            account_selection_wait_ms,
+            context,
+        } = prepared;
+        validate_compaction_context(&context)?;
         let inherited_session_id = previous_session
             .as_ref()
             .and_then(|previous| previous.session_id.clone());
-        let upstream_model = candidate_upstream_model(candidate)?;
         let upstream_request = GrokCompactionRequest::encode(
-            generate,
+            &generate,
             upstream_model.as_str(),
             context.client_api_key_ref(),
         )
@@ -410,20 +580,7 @@ impl GrokBuildProvider {
         let upstream_session_id = inherited_session_id
             .clone()
             .or_else(|| explicit_replay_session_id.clone());
-        let selection_started_at = Instant::now();
-        let selected = Arc::new(
-            select_grok_session(
-                self.selector.as_ref(),
-                candidate,
-                &wire_upstream_model,
-                &context,
-                operation_account,
-                upstream_request.affinity().cloned(),
-            )
-            .await?,
-        );
-        let account_selection_wait_ms =
-            u64::try_from(selection_started_at.elapsed().as_millis()).unwrap_or(u64::MAX);
+        let selected = Arc::new(selected);
         let reasoning_replay_key = explicit_replay_session_id
             .as_deref()
             .or(inherited_session_id.as_deref())
@@ -435,7 +592,8 @@ impl GrokBuildProvider {
                 )
             });
         let allows_account_state_mutation = selected.allows_account_state_mutation();
-        let metadata = provider_call_metadata(candidate, &selected, account_selection_wait_ms)?;
+        let metadata =
+            provider_call_metadata(&upstream_model, &selected, account_selection_wait_ms)?;
         let events = cold_compaction_http_sse_stream(
             Arc::clone(&self.selector),
             Arc::clone(&self.transport),
@@ -445,6 +603,7 @@ impl GrokBuildProvider {
                 credential_recovery: Arc::clone(&self.credential_recovery),
                 responses_url: self.responses_url.clone(),
                 request: upstream_request,
+                middleware_headers,
                 upstream_model: wire_upstream_model,
                 upstream_session_id,
                 context,
@@ -462,6 +621,14 @@ impl GrokBuildProvider {
     }
 }
 
+fn native_request_requirements(request: &GenerateRequest) -> CapabilityRequirements {
+    // 这里只读取本 Provider 已知的 Responses 字段；工具别名等原生保护字段另行校验。
+    Operation::Generate(GenerateRequest::from_protocol_payload(
+        request.protocol_payload().clone(),
+    ))
+    .capability_requirements()
+}
+
 async fn select_grok_session(
     selector: &dyn GrokSessionSelector,
     candidate: &ProviderCandidate,
@@ -481,6 +648,10 @@ async fn select_grok_session(
         context.client_api_key_ref().clone(),
     )
     .with_concurrency_wait_budget(context.concurrency_wait_budget().clone())
+    .with_request_policy(
+        context.request_policy_context().cloned(),
+        context.attempt_index(),
+    )
     .with_eligibility_policy(if context.is_diagnostic_required_account() {
         AccountEligibilityPolicy::BypassForDiagnostic
     } else {
@@ -516,13 +687,13 @@ async fn select_grok_session(
 }
 
 fn provider_call_metadata(
-    candidate: &ProviderCandidate,
+    upstream_model: &UpstreamModelId,
     selected: &SelectedGrokSession,
     account_selection_wait_ms: u64,
 ) -> Result<ProviderCallMetadata, ProviderError> {
     Ok(ProviderCallMetadata::new(
         ProviderKind::new(XAI_PROVIDER_NAME).map_err(|_| protocol_not_sent())?,
-        candidate_upstream_model(candidate)?.clone(),
+        upstream_model.clone(),
         selected.account_id().clone(),
         UpstreamTransport::new(HTTP_SSE_TRANSPORT).map_err(|_| protocol_not_sent())?,
     )
@@ -532,6 +703,66 @@ fn provider_call_metadata(
     )))
 }
 
+fn validate_compaction_context(context: &AttemptContext) -> Result<(), ProviderError> {
+    if context.continuation().is_some()
+        || context.continuation_attempt() != ContinuationAttempt::None
+    {
+        return Err(provider_error(
+            ProviderErrorKind::InvalidRequest,
+            UpstreamSendState::NotSent,
+        ));
+    }
+    Ok(())
+}
+
+fn previous_session_account(
+    previous_session: Option<&XaiSessionState>,
+) -> Result<Option<ProviderAccountId>, ProviderError> {
+    previous_session
+        .map(|previous| ProviderAccountId::new(previous.account_id.clone()))
+        .transpose()
+        .map_err(|_| protocol_not_sent())
+}
+
+fn merge_frozen_account_owner(
+    context: &AttemptContext,
+    operation_account: Option<ProviderAccountId>,
+) -> Result<Option<ProviderAccountId>, ProviderError> {
+    if context.continuation_attempt() == ContinuationAttempt::ReplayAny {
+        return Ok(operation_account);
+    }
+    let provider = ProviderKind::new(XAI_PROVIDER_NAME).map_err(|_| protocol_not_sent())?;
+    let Some(owner) = context
+        .account_state_owner()
+        .filter(|owner| owner.provider() == &provider)
+    else {
+        return Ok(operation_account);
+    };
+    if operation_account
+        .as_ref()
+        .is_some_and(|account| account != owner.account())
+    {
+        return Err(invalid_continuation());
+    }
+    Ok(Some(owner.account().clone()))
+}
+
+fn validate_selected_grok_account(
+    selected: &SelectedGrokSession,
+    context: &AttemptContext,
+    operation_account: Option<&ProviderAccountId>,
+) -> Result<(), ProviderError> {
+    if context.excluded_accounts().contains(selected.account_id())
+        || context
+            .required_account()
+            .is_some_and(|required| required != selected.account_id())
+        || operation_account.is_some_and(|required| required != selected.account_id())
+    {
+        return Err(protocol_not_sent());
+    }
+    Ok(())
+}
+
 fn candidate_upstream_model(
     candidate: &ProviderCandidate,
 ) -> Result<&UpstreamModelId, ProviderError> {
diff --git a/backend/crates/providers/xai/src/provider/stream.rs b/backend/crates/providers/xai/src/provider/stream.rs
index 5c4ea544f..a4062ed97 100644
--- a/backend/crates/providers/xai/src/provider/stream.rs
+++ b/backend/crates/providers/xai/src/provider/stream.rs
@@ -8,10 +8,12 @@ pub(super) struct GrokStreamAttempt {
     pub(super) credential_recovery: Arc<dyn GrokCredentialRecovery>,
     pub(super) responses_url: Url,
     pub(super) request: GrokResponsesRequest,
+    pub(super) middleware_headers: Vec<MiddlewareHeader>,
     pub(super) upstream_model: UpstreamModelId,
     pub(super) context: AttemptContext,
     pub(super) session: Arc<SelectedGrokSession>,
     pub(super) output_started_at: Instant,
+    pub(super) native_response_boundary: bool,
     pub(super) session_capture: Option<GrokSessionCapture>,
     pub(super) reasoning_replay_capture: Option<GrokReasoningReplayCapture>,
 }
@@ -22,6 +24,7 @@ pub(super) struct GrokCompactionStreamAttempt {
     pub(super) credential_recovery: Arc<dyn GrokCredentialRecovery>,
     pub(super) responses_url: Url,
     pub(super) request: GrokCompactionRequest,
+    pub(super) middleware_headers: Vec<MiddlewareHeader>,
     pub(super) upstream_model: UpstreamModelId,
     pub(super) upstream_session_id: Option<String>,
     pub(super) context: AttemptContext,
@@ -30,6 +33,31 @@ pub(super) struct GrokCompactionStreamAttempt {
     pub(super) reasoning_replay_key: Option<GrokReasoningReplayKey>,
 }
 
+fn append_middleware_grok_headers(
+    target: &mut Vec<crate::transport::GrokHeader>,
+    headers: &[MiddlewareHeader],
+) -> Result<(), ProviderError> {
+    let provider_header_count = target.len();
+    for header in headers {
+        if target[..provider_header_count]
+            .iter()
+            .any(|existing| existing.name().eq_ignore_ascii_case(header.name()))
+        {
+            return Err(provider_error(
+                ProviderErrorKind::Protocol,
+                UpstreamSendState::NotSent,
+            ));
+        }
+        let value = std::str::from_utf8(header.value())
+            .map_err(|_| provider_error(ProviderErrorKind::Protocol, UpstreamSendState::NotSent))?;
+        target.push(crate::transport::GrokHeader::public(
+            header.name().to_owned(),
+            value.to_owned(),
+        ));
+    }
+    Ok(())
+}
+
 pub(super) struct AcceptedGrokInference {
     response: GrokInferenceResponse,
     observation: ProviderResponseObservation,
@@ -83,6 +111,7 @@ pub(super) fn cold_compaction_http_sse_stream(
         credential_recovery,
         responses_url,
         mut request,
+        middleware_headers,
         upstream_model,
         upstream_session_id,
         context,
@@ -91,7 +120,7 @@ pub(super) fn cold_compaction_http_sse_stream(
         reasoning_replay_key,
     } = attempt;
     Box::pin(async_stream::try_stream! {
-        let headers = build_grok_headers(
+        let mut headers = build_grok_headers(
             &wire_profile,
             &session,
             &client_identity,
@@ -100,6 +129,7 @@ pub(super) fn cold_compaction_http_sse_stream(
             None,
             &upstream_model,
         );
+        append_middleware_grok_headers(&mut headers, &middleware_headers)?;
         let mut invalid_encrypted_content_retried = false;
         let accepted = loop {
             if context.cancellation().is_cancelled() {
@@ -381,10 +411,12 @@ pub(super) fn cold_http_sse_stream(
         credential_recovery,
         responses_url,
         mut request,
+        middleware_headers,
         upstream_model,
         context,
         session,
         output_started_at,
+        native_response_boundary,
         mut session_capture,
         mut reasoning_replay_capture,
     } = attempt;
@@ -395,7 +427,7 @@ pub(super) fn cold_http_sse_stream(
                 UpstreamSendState::NotSent,
             ))?;
         }
-        let headers = build_grok_headers(
+        let mut headers = build_grok_headers(
             &wire_profile,
             &session,
             &client_identity,
@@ -404,6 +436,7 @@ pub(super) fn cold_http_sse_stream(
             None,
             &upstream_model,
         );
+        append_middleware_grok_headers(&mut headers, &middleware_headers)?;
         let cancellation = context.cancellation().clone();
         let mut invalid_encrypted_content_retried = false;
         let response = loop {
@@ -510,7 +543,13 @@ pub(super) fn cold_http_sse_stream(
             let Some(chunk) = next else {
                 break;
             };
-            let mut events = match decoder.push(&chunk) {
+            let (mut events, mut projected_events) = match if native_response_boundary {
+                decoder
+                    .push_before_translation(&chunk)
+                    .map(|batch| (batch.source_events, Some(batch.projected_events)))
+            } else {
+                decoder.push(&chunk).map(|events| (events, None))
+            } {
                 Ok(events) => events,
                 Err(error) => {
                     let error = map_continuation_failure(&context, error);
@@ -560,10 +599,12 @@ pub(super) fn cold_http_sse_stream(
                 .iter()
                 .flat_map(ProviderEvent::canonical_facts)
                 .any(|event| matches!(event, GatewayEvent::Completed(_)));
-            attach_xai_session_update(&mut events, &mut session_capture)?;
-            if let Some(capture) = reasoning_replay_capture.as_mut() {
-                capture.observe(&events);
-            }
+            attach_grok_response_state(
+                &mut events,
+                projected_events.as_deref_mut(),
+                &mut session_capture,
+                &mut reasoning_replay_capture,
+            )?;
             if completed && session.allows_account_state_mutation() {
                 selector.record_success(&session).await;
             }
@@ -575,7 +616,13 @@ pub(super) fn cold_http_sse_stream(
                 return;
             }
         }
-        let mut final_events = match decoder.finish() {
+        let (mut final_events, mut projected_events) = match if native_response_boundary {
+            decoder
+                .finish_before_translation()
+                .map(|batch| (batch.source_events, Some(batch.projected_events)))
+        } else {
+            decoder.finish().map(|events| (events, None))
+        } {
             Ok(events) => events,
             Err(error) => {
                 let error = map_continuation_failure(&context, error);
@@ -624,10 +671,12 @@ pub(super) fn cold_http_sse_stream(
                 ProviderResponseTimings { first_token_ms, ..base_timings },
             ));
         }
-        attach_xai_session_update(&mut final_events, &mut session_capture)?;
-        if let Some(capture) = reasoning_replay_capture.as_mut() {
-            capture.observe(&final_events);
-        }
+        attach_grok_response_state(
+            &mut final_events,
+            projected_events.as_deref_mut(),
+            &mut session_capture,
+            &mut reasoning_replay_capture,
+        )?;
         if completed && session.allows_account_state_mutation() {
             selector.record_success(&session).await;
         }
@@ -637,3 +686,40 @@ pub(super) fn cold_http_sse_stream(
         }
     })
 }
+
+fn attach_grok_response_state(
+    delivery_events: &mut [ProviderEvent],
+    projected_events: Option<&mut [ProviderEvent]>,
+    session_capture: &mut Option<GrokSessionCapture>,
+    reasoning_replay_capture: &mut Option<GrokReasoningReplayCapture>,
+) -> Result<(), ProviderError> {
+    let Some(projected_events) = projected_events else {
+        attach_xai_session_update(delivery_events, session_capture)?;
+        if let Some(capture) = reasoning_replay_capture.as_mut() {
+            capture.observe(delivery_events);
+        }
+        return Ok(());
+    };
+
+    attach_xai_session_update(projected_events, session_capture)?;
+    if let Some(capture) = reasoning_replay_capture.as_mut() {
+        capture.observe(projected_events);
+    }
+    let Some(state) = projected_events
+        .iter_mut()
+        .find_map(ProviderEvent::take_session_update)
+    else {
+        return Ok(());
+    };
+    let terminal = delivery_events
+        .iter_mut()
+        .find(|event| {
+            event
+                .canonical_facts()
+                .iter()
+                .any(|fact| matches!(fact, GatewayEvent::Completed(_)))
+        })
+        .ok_or_else(protocol_sent)?;
+    terminal.attach_session_update(state);
+    Ok(())
+}
diff --git a/backend/crates/providers/xai/src/transport/canonical.rs b/backend/crates/providers/xai/src/transport/canonical.rs
index cbbb69cea..8d10c74a7 100644
--- a/backend/crates/providers/xai/src/transport/canonical.rs
+++ b/backend/crates/providers/xai/src/transport/canonical.rs
@@ -2,6 +2,7 @@
 
 use std::collections::{BTreeMap, BTreeSet};
 
+use gateway_core::engine::provider::NativeResponseTranslator;
 use gateway_core::error::{
     ClientVisibleUpstreamError, OpaqueUpstreamValue, ProviderError, ProviderErrorKind,
 };
@@ -26,6 +27,23 @@ use super::{classify_grok_quota_failure, scrub_account_fingerprints};
 const CONTENTS_PER_OUTPUT: u32 = 1_024;
 const LONG_CONTEXT_THRESHOLD: u64 = 200_000;
 const GROK_PING_SSE_COMMENT: &[u8] = b": ping\n\n";
+const XAI_RESPONSE_PROTOCOL: &str = "xai";
+const OPENAI_RESPONSE_PROTOCOL: &str = "openai";
+
+pub(crate) struct GrokDecodedResponseBatch {
+    pub(crate) source_events: Vec<ProviderEvent>,
+    pub(crate) projected_events: Vec<ProviderEvent>,
+}
+
+struct ProjectedWireEvent {
+    event_type: String,
+    wire: ProtocolWireEvent,
+}
+
+/// 单次 xAI stream 独占的原生响应交付转换状态。
+pub(crate) struct GrokNativeResponseTranslator {
+    response_transform: GrokResponseTransform,
+}
 
 #[derive(Clone, Copy)]
 struct TokenRates {
@@ -278,6 +296,64 @@ pub struct GrokCanonicalDecoder {
     requires_provider_cost: bool,
 }
 
+impl GrokNativeResponseTranslator {
+    #[must_use]
+    pub(crate) fn for_request(request: &GrokResponsesRequest) -> Self {
+        Self {
+            response_transform: request.response_transform(),
+        }
+    }
+}
+
+impl NativeResponseTranslator for GrokNativeResponseTranslator {
+    fn source_protocol(&self) -> &str {
+        XAI_RESPONSE_PROTOCOL
+    }
+
+    fn target_protocol(&self) -> &str {
+        OPENAI_RESPONSE_PROTOCOL
+    }
+
+    fn translate(
+        &mut self,
+        event: &ProtocolWireEvent,
+    ) -> Result<Vec<ProtocolWireEvent>, ProviderError> {
+        if event.protocol() != XAI_RESPONSE_PROTOCOL {
+            return Err(protocol_error_marker());
+        }
+        if event.has_json_data() {
+            let value = event.data().clone();
+            let event_type = value
+                .get("type")
+                .and_then(Value::as_str)
+                .or_else(|| event.event_type())
+                .unwrap_or_default()
+                .to_owned();
+            return project_response_event(
+                &mut self.response_transform,
+                &event_type,
+                value,
+                event.event_type(),
+                event.sse_id(),
+                event.sse_retry(),
+            )
+            .map(|events| events.into_iter().map(|event| event.wire).collect());
+        }
+        if event
+            .raw_sse_frame()
+            .is_some_and(|frame| frame.as_ref() == GROK_PING_SSE_COMMENT)
+        {
+            return ProtocolWireEvent::raw_sse(
+                OPENAI_RESPONSE_PROTOCOL,
+                bytes::Bytes::from_static(GROK_PING_SSE_COMMENT),
+            )
+            .map(|wire| vec![wire])
+            .map_err(protocol_error);
+        }
+        Err(protocol_error_marker())
+    }
+}
+
 impl GrokCanonicalDecoder {
     /// 使用路由后最终发往上游的请求模型计价，并在响应缺少模型时用于 canonical 兜底。
     pub fn new(upstream_model: impl Into<String>) -> Self {
@@ -345,11 +421,31 @@ impl GrokCanonicalDecoder {
     }
 
     pub fn push(&mut self, chunk: &[u8]) -> Result<Vec<ProviderEvent>, ProviderError> {
+        let events = self.decoder.push(chunk).map_err(protocol_error)?;
+        self.decode(events).map(|batch| batch.projected_events)
+    }
+
+    /// 解码同一批上游事件，同时返回转换前 xAI wire 与独立生成的 OpenAI 投影。
+    pub(crate) fn push_before_translation(
+        &mut self,
+        chunk: &[u8],
+    ) -> Result<GrokDecodedResponseBatch, ProviderError> {
         let events = self.decoder.push(chunk).map_err(protocol_error)?;
         self.decode(events)
     }
 
     pub fn finish(&mut self) -> Result<Vec<ProviderEvent>, ProviderError> {
+        let events = self.decoder.finish().map_err(protocol_error)?;
+        let output = self.decode(events)?.projected_events;
+        if !self.completed {
+            return Err(protocol_error_marker());
+        }
+        Ok(output)
+    }
+
+    pub(crate) fn finish_before_translation(
+        &mut self,
+    ) -> Result<GrokDecodedResponseBatch, ProviderError> {
         let events = self.decoder.finish().map_err(protocol_error)?;
         let output = self.decode(events)?;
         if !self.completed {
@@ -360,7 +456,7 @@ impl GrokCanonicalDecoder {
 
     pub(crate) fn finish_without_terminal(&mut self) -> Result<Vec<ProviderEvent>, ProviderError> {
         let events = self.decoder.finish().map_err(protocol_error)?;
-        self.decode(events)
+        self.decode(events).map(|batch| batch.projected_events)
     }
 
     /// 取走本批解码帧里是否已出现首个非前导输出事件（结构帧也算），用于首字计时。
@@ -368,8 +464,9 @@ impl GrokCanonicalDecoder {
         std::mem::take(&mut self.output_start_seen)
     }
 
-    fn decode(&mut self, events: Vec<SseEvent>) -> Result<Vec<ProviderEvent>, ProviderError> {
-        let mut output = Vec::new();
+    fn decode(&mut self, events: Vec<SseEvent>) -> Result<GrokDecodedResponseBatch, ProviderError> {
+        let mut source_events = Vec::new();
+        let mut projected_events = Vec::new();
         for event in events {
             if event
                 .event
@@ -395,12 +492,18 @@ impl GrokCanonicalDecoder {
                     .and_then(|value| value.get("type").and_then(Value::as_str))
                     .is_none_or(|event_type| event_type == "ping")
             {
-                let wire = ProtocolWireEvent::raw_sse(
-                    "openai",
+                let source_wire = ProtocolWireEvent::raw_sse(
+                    XAI_RESPONSE_PROTOCOL,
                     bytes::Bytes::from_static(GROK_PING_SSE_COMMENT),
                 )
                 .map_err(|_| protocol_error_marker())?;
-                output.push(ProviderEvent::wire(wire));
+                let projected_wire = ProtocolWireEvent::raw_sse(
+                    OPENAI_RESPONSE_PROTOCOL,
+                    bytes::Bytes::from_static(GROK_PING_SSE_COMMENT),
+                )
+                .map_err(|_| protocol_error_marker())?;
+                source_events.push(ProviderEvent::wire(source_wire));
+                projected_events.push(ProviderEvent::wire(projected_wire));
                 continue;
             }
             let Ok(value) = parsed else {
@@ -410,28 +513,21 @@ impl GrokCanonicalDecoder {
             if body_type == Some("response.doom_loop_check") {
                 continue;
             }
-            let Some(event_type) = body_type.or(event.event.as_deref()) else {
-                let transformed = self
-                    .response_transform
-                    .rewrite_stream_event("", value)
-                    .map_err(|_| protocol_error_marker())?;
-                for (index, transformed) in transformed.into_iter().enumerate() {
-                    let mut value = transformed.into_value();
-                    self.response_transform.resequence_stream_value(&mut value);
-                    let wire = ProtocolWireEvent::json_with_sse_metadata(
-                        "openai",
-                        None,
-                        value,
-                        (index == 0).then(|| event.id.clone()).flatten(),
-                        (index == 0).then_some(event.retry).flatten(),
-                    )
-                    .map_err(|_| protocol_error_marker())?;
-                    output.push(ProviderEvent::wire(wire));
-                }
-                continue;
-            };
-            let event_type = event_type.to_owned();
-            self.response_model.observe(Some(&event_type), &value);
+            let event_type = body_type
+                .or(event.event.as_deref())
+                .unwrap_or_default()
+                .to_owned();
+            let source_wire = ProtocolWireEvent::json_with_sse_metadata(
+                XAI_RESPONSE_PROTOCOL,
+                event.event.clone(),
+                value.clone(),
+                event.id.clone(),
+                event.retry,
+            )
+            .map_err(|_| protocol_error_marker())?;
+            if !event_type.is_empty() {
+                self.response_model.observe(Some(&event_type), &value);
+            }
             // 工具转换可能隐藏注入的调用，计费事实必须从转换前的上游事件读取。
             if let Some(response) = value.get("response") {
                 if let Some(tier) = response.get("service_tier").and_then(Value::as_str) {
@@ -443,22 +539,23 @@ impl GrokCanonicalDecoder {
                 self.requires_provider_cost |= !token_only_output(item);
             }
             // 转换失败必须终止，不能丢弃工具参数后仍向客户端报告成功。
-            let transformed = self
-                .response_transform
-                .rewrite_stream_event(&event_type, value)
-                .map_err(|_| protocol_error_marker())?;
-            for (index, transformed) in transformed.into_iter().enumerate() {
-                let transformed_type = transformed.event_type().to_owned();
-                if !client_visible_event(&transformed_type) {
-                    continue;
-                }
+            let projected = project_response_event(
+                &mut self.response_transform,
+                &event_type,
+                value,
+                event.event.as_deref(),
+                event.id.as_deref(),
+                event.retry,
+            )?;
+            let mut source_canonical = Vec::new();
+            for projected in projected {
+                let transformed_type = projected.event_type;
                 // 首个非前导、非失败事件（结构帧也算）开启首字计时。
                 self.output_start_seen |= !matches!(
                     transformed_type.as_str(),
                     "response.created" | "response.in_progress" | "response.failed" | "error"
                 );
-                let mut value = transformed.into_value();
-                self.response_transform.resequence_stream_value(&mut value);
+                let value = projected.wire.data();
                 let mut canonical = Vec::new();
                 // 终态事件（completed/incomplete）fail-closed：用量/计费校验失败即断流。
                 // 其余内容事件容忍字段校验失败——正常上游变体（空 delta、重复 index、
@@ -468,7 +565,7 @@ impl GrokCanonicalDecoder {
                     transformed_type.as_str(),
                     "response.completed" | "response.incomplete"
                 );
-                match self.decode_event(&transformed_type, &value, &mut canonical) {
+                match self.decode_event(&transformed_type, value, &mut canonical) {
                     Ok(()) => {}
                     Err(error)
                         if !terminal_event && error.kind() == ProviderErrorKind::Protocol =>
@@ -477,27 +574,23 @@ impl GrokCanonicalDecoder {
                     }
                     Err(error) => return Err(error),
                 }
-                let wire_event = if transformed_type == event_type {
-                    event.event.clone()
+                source_canonical.extend(canonical.iter().cloned());
+                projected_events.push(if canonical.is_empty() {
+                    ProviderEvent::wire(projected.wire)
                 } else {
-                    Some(transformed_type)
-                };
-                let wire = ProtocolWireEvent::json_with_sse_metadata(
-                    "openai",
-                    wire_event,
-                    value,
-                    (index == 0).then(|| event.id.clone()).flatten(),
-                    (index == 0).then_some(event.retry).flatten(),
-                )
-                .map_err(|_| protocol_error_marker())?;
-                output.push(if canonical.is_empty() {
-                    ProviderEvent::wire(wire)
-                } else {
-                    ProviderEvent::canonical_with_wire(canonical, wire)
+                    ProviderEvent::canonical_with_wire(canonical, projected.wire)
                 });
             }
+            source_events.push(if source_canonical.is_empty() {
+                ProviderEvent::wire(source_wire)
+            } else {
+                ProviderEvent::canonical_with_wire(source_canonical, source_wire)
+            });
         }
-        Ok(output)
+        Ok(GrokDecodedResponseBatch {
+            source_events,
+            projected_events,
+        })
     }
 
     fn decode_event(
@@ -840,6 +933,46 @@ impl GrokCanonicalDecoder {
     }
 }
 
+fn project_response_event(
+    response_transform: &mut GrokResponseTransform,
+    event_type: &str,
+    value: Value,
+    source_event_type: Option<&str>,
+    sse_id: Option<&str>,
+    sse_retry: Option<u64>,
+) -> Result<Vec<ProjectedWireEvent>, ProviderError> {
+    let transformed = response_transform
+        .rewrite_stream_event(event_type, value)
+        .map_err(protocol_error)?;
+    let mut projected = Vec::with_capacity(transformed.len());
+    for (index, transformed) in transformed.into_iter().enumerate() {
+        let transformed_type = transformed.event_type().to_owned();
+        if !event_type.is_empty() && !client_visible_event(&transformed_type) {
+            continue;
+        }
+        let mut value = transformed.into_value();
+        response_transform.resequence_stream_value(&mut value);
+        let wire_event = if transformed_type == event_type {
+            source_event_type.map(str::to_owned)
+        } else {
+            Some(transformed_type.clone())
+        };
+        let wire = ProtocolWireEvent::json_with_sse_metadata(
+            OPENAI_RESPONSE_PROTOCOL,
+            wire_event,
+            value,
+            (index == 0).then(|| sse_id.map(str::to_owned)).flatten(),
+            (index == 0).then_some(sse_retry).flatten(),
+        )
+        .map_err(protocol_error)?;
+        projected.push(ProjectedWireEvent {
+            event_type: transformed_type,
+            wire,
+        });
+    }
+    Ok(projected)
+}
+
 fn client_visible_event(event_type: &str) -> bool {
     event_type == "error"
         || (event_type.starts_with("response.") && event_type != "response.doom_loop_check")
diff --git a/backend/crates/providers/xai/src/transport/headers.rs b/backend/crates/providers/xai/src/transport/headers.rs
index fbb06286b..360a0aae3 100644
--- a/backend/crates/providers/xai/src/transport/headers.rs
+++ b/backend/crates/providers/xai/src/transport/headers.rs
@@ -67,15 +67,15 @@ impl fmt::Debug for GrokHeaderValue {
 /// 一个官方 Grok CLI 代理请求头。
 #[derive(Debug, Clone)]
 pub struct GrokHeader {
-    name: &'static str,
+    name: String,
     value: GrokHeaderValue,
 }
 
 impl GrokHeader {
-    /// 返回静态 header 名。
+    /// 返回 header 名。
     #[must_use]
-    pub const fn name(&self) -> &'static str {
-        self.name
+    pub fn name(&self) -> &str {
+        &self.name
     }
 
     /// 返回类型化的 header 值。
@@ -84,16 +84,16 @@ impl GrokHeader {
         &self.value
     }
 
-    pub(crate) fn public(name: &'static str, value: impl Into<String>) -> Self {
+    pub(crate) fn public(name: impl Into<String>, value: impl Into<String>) -> Self {
         Self {
-            name,
+            name: name.into(),
             value: GrokHeaderValue::Public(value.into()),
         }
     }
 
-    pub(crate) fn sensitive(name: &'static str, value: SecretValue) -> Self {
+    pub(crate) fn sensitive(name: impl Into<String>, value: SecretValue) -> Self {
         Self {
-            name,
+            name: name.into(),
             value: GrokHeaderValue::Sensitive(value),
         }
     }
diff --git a/backend/crates/providers/xai/src/transport/session.rs b/backend/crates/providers/xai/src/transport/session.rs
index 0ccc8b852..d11334145 100644
--- a/backend/crates/providers/xai/src/transport/session.rs
+++ b/backend/crates/providers/xai/src/transport/session.rs
@@ -9,6 +9,7 @@ use gateway_core::account::{
     AccountCapacitySnapshot, AccountEligibilityPolicy, AccountSelectionPolicy, CredentialRevision,
     ProviderAccountId,
 };
+use gateway_core::engine::policy::RequestPolicyContext;
 use gateway_core::policy::ClientApiKeyId;
 use gateway_core::routing::{FrozenAccountScope, UpstreamModelId};
 use sha2::{Digest as _, Sha256};
@@ -238,6 +239,8 @@ pub struct GrokSessionSelection {
     account_scope: Arc<FrozenAccountScope>,
     client_api_key_id: ClientApiKeyId,
     concurrency_wait_budget: gateway_core::concurrency::ConcurrencyWaitBudget,
+    request_policy: Option<RequestPolicyContext>,
+    attempt_index: std::num::NonZeroU32,
 }
 
 impl GrokSessionSelection {
@@ -263,9 +266,23 @@ impl GrokSessionSelection {
             account_scope,
             client_api_key_id,
             concurrency_wait_budget: gateway_core::concurrency::ConcurrencyWaitBudget::default(),
+            request_policy: None,
+            attempt_index: std::num::NonZeroU32::MIN,
         }
     }
 
+    /// 附着普通数据面请求冻结的插件策略；管理诊断保持空值。
+    #[must_use]
+    pub(crate) fn with_request_policy(
+        mut self,
+        policy: Option<RequestPolicyContext>,
+        attempt_index: std::num::NonZeroU32,
+    ) -> Self {
+        self.request_policy = policy;
+        self.attempt_index = attempt_index;
+        self
+    }
+
     /// 附着仅由显式客户端会话派生的账号亲和键。
     #[must_use]
     pub fn with_affinity(mut self, affinity: Option<GrokSessionAffinityKey>) -> Self {
@@ -349,6 +366,16 @@ impl GrokSessionSelection {
     pub const fn client_api_key_id(&self) -> &ClientApiKeyId {
         &self.client_api_key_id
     }
+
+    #[must_use]
+    pub(crate) const fn request_policy(&self) -> Option<&RequestPolicyContext> {
+        self.request_policy.as_ref()
+    }
+
+    #[must_use]
+    pub(crate) const fn attempt_index(&self) -> std::num::NonZeroU32 {
+        self.attempt_index
+    }
 }
 
 /// Grok session selector 返回的 future。
@@ -456,6 +483,12 @@ pub enum GrokSessionSelectorError {
     /// 选择器依赖的后端服务不可用。
     #[error("Grok Build session selector is unavailable")]
     Unavailable,
+    /// 插件调度策略明确拒绝本次请求。
+    #[error("account scheduling policy rejected the request")]
+    PolicyRejected,
+    /// 插件调度策略调用失败且配置为拒绝。
+    #[error("account scheduling policy is unavailable")]
+    PolicyUnavailable,
 }
 
 /// 构造选中会话时的失败。
diff --git a/backend/crates/providers/xai/tests/admin.rs b/backend/crates/providers/xai/tests/admin.rs
index 343a95cf9..237cc0343 100644
--- a/backend/crates/providers/xai/tests/admin.rs
+++ b/backend/crates/providers/xai/tests/admin.rs
@@ -51,6 +51,25 @@ use crate::support::{
     TestSessionExclusions, account_id, create_input, seed_input,
 };
 
+#[tokio::test]
+async fn account_capabilities_advertise_only_xai_oauth_quota_operations() {
+    let bundle = provider_xai::initialize(provider_ports()).await.unwrap();
+    let provider = bundle.admin_provider();
+    let id = ProviderAccountId::new("acct_capabilities").unwrap();
+    let oauth = provider.account_capabilities(&id, "oauth");
+    assert_eq!(
+        oauth,
+        gateway_admin::model::provider_capabilities::ProviderAccountCapabilities {
+            quota: true,
+            quota_refresh: true,
+            ..Default::default()
+        }
+    );
+    for kind in ["api_key", "unknown"] {
+        assert_eq!(provider.account_capabilities(&id, kind), Default::default());
+    }
+}
+
 #[tokio::test]
 async fn account_unavailable_clears_real_selector_cooldowns_only_for_deleted_account() {
     let store = MemoryProviderAccountStore::shared();
@@ -424,6 +443,7 @@ async fn xai_admin_provider_projects_cached_quota_models_and_canonical_export()
             &UpstreamModelId::new("grok-4.5").expect("upstream model"),
             "Reply with exactly OK.",
         )
+        .await
         .expect("connection test operation");
     let Operation::Generate(request) = operation else {
         panic!("connection test must be a generate operation");
@@ -1263,3 +1283,45 @@ async fn client_profile_preview_and_dashboard_use_saved_configuration() {
     assert!(dashboard.release.is_none());
     assert!(dashboard.verified_at.is_none());
 }
+
+#[tokio::test]
+async fn browser_authorization_declares_callback_and_rejects_extra_login_inputs() {
+    use gateway_admin::model::{
+        provider_capabilities::AuthorizationCompletion,
+        provider_credentials::{
+            AuthorizationMutationTarget, AuthorizationOwnerBinding, PendingAuthorizationMutation,
+            PrepareAuthorization,
+        },
+    };
+    let bundle = provider_xai::initialize(provider_ports()).await.unwrap();
+    let provider = bundle.admin_provider();
+    let login = provider.credential_capabilities().login.unwrap();
+    assert_eq!(login.completion, AuthorizationCompletion::Callback);
+    assert_eq!(
+        login.input_schema,
+        json!({"type":"object", "additionalProperties":false})
+    );
+    let error = provider
+        .start_authorization(PrepareAuthorization {
+            pending: PendingAuthorizationMutation::new(
+                ProviderKind::new("xai").unwrap(),
+                AuthorizationMutationTarget::Create {
+                    name: "form account".into(),
+                },
+                AuthorizationOwnerBinding::from_context(&MutationContext {
+                    actor: MutationActor::System,
+                    request_id: "login-input-test".into(),
+                }),
+            ),
+            input: ProviderDocument::new(OpaqueProviderData::new(
+                json!({"token":"unexpected-fixture-secret"})
+                    .as_object()
+                    .unwrap()
+                    .clone(),
+            )),
+        })
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), ProviderAdminErrorKind::Invalid);
+    assert!(!format!("{error:?}").contains("unexpected-fixture-secret"));
+}
diff --git a/backend/crates/providers/xai/tests/provider/contract.rs b/backend/crates/providers/xai/tests/provider/contract.rs
index a62553caf..62a5c54a2 100644
--- a/backend/crates/providers/xai/tests/provider/contract.rs
+++ b/backend/crates/providers/xai/tests/provider/contract.rs
@@ -4,7 +4,8 @@ use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::{Arc, Mutex};
 use std::time::{Duration, SystemTime};
 
-use futures::{StreamExt, stream};
+use bytes::Bytes;
+use futures::{StreamExt, future::BoxFuture, stream};
 use gateway_core::account::{
     AccountFeedbackStats, AccountRuntimeSignals, AccountSelectionPolicy, CredentialRevision,
     CredentialState, ProviderAccountStore, RotationStrategy,
@@ -12,6 +13,11 @@ use gateway_core::account::{
 use gateway_core::engine::continuation::{
     ContinuationBinding, NativeContinuationPin, PreviousResponseId,
 };
+use gateway_core::engine::execution::ClientTransport;
+use gateway_core::engine::middleware::{
+    FrozenMiddlewarePlan, MiddlewareContext, MiddlewareError, MiddlewareHeader, MiddlewareMount,
+    MiddlewareNext, MiddlewarePlan, MiddlewareRequest, MiddlewareResponse,
+};
 use gateway_core::engine::provider::{Provider, ProviderRequest};
 use gateway_core::engine::{
     AccountAttemptContext, AttemptContext, ContinuationAttempt, ModelRequestId,
@@ -35,6 +41,7 @@ use gateway_core::routing::{
     ProviderModel, PublicModelId, RoutingContext, RuntimeAccount, RuntimeAccountDirectory,
     RuntimeSnapshot, SupportLevel, UpstreamModelId,
 };
+use gateway_core::runtime::extensions::{ExtensionSetId, ExtensionSetLease, ExtensionSetReference};
 use gateway_core::upstream::UpstreamSendState;
 use provider_xai::{
     GrokAccountSessionSelector, GrokBillingRequest, GrokBillingTransport,
@@ -61,6 +68,501 @@ const MODEL: &str = "grok-4.5";
 const CATALOG_FIXTURE: &[u8] =
     include_bytes!("../transport/catalog/fixtures/official_grok_models_snapshot.json");
 
+#[tokio::test]
+async fn native_xai_translates_a_non_native_source_before_encoding() {
+    let transport = StubInferenceTransport::success();
+    let selector = StubSelector::success();
+    let provider = provider(Arc::clone(&selector), transport.clone()).await;
+    let translations = Arc::new(Mutex::new(0_usize));
+    let source = Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "example-source",
+            Map::from_iter([
+                ("opaque".to_owned(), json!("source-only")),
+                ("input".to_owned(), json!([{"type":"compaction_trigger"}])),
+                ("prompt_cache_key".to_owned(), json!("must-not-be-read")),
+            ]),
+        )
+        .unwrap(),
+    ));
+    let mut stream = provider
+        .execute(
+            provider_request_with_operation("xai", source),
+            context_with_middleware(Arc::new(TranslationMiddleware {
+                translations: Arc::clone(&translations),
+                target: Map::from_iter([
+                    ("model".to_owned(), json!("ignored-by-forced-model")),
+                    ("input".to_owned(), json!("translated")),
+                    ("stream".to_owned(), json!(true)),
+                ]),
+            })),
+        )
+        .await
+        .expect("registered translation should run before native encoding");
+    assert_eq!(selector.calls.load(Ordering::SeqCst), 1);
+    assert_eq!(transport.calls.load(Ordering::SeqCst), 0);
+    while let Some(event) = stream.next().await {
+        event.expect("translated request response");
+    }
+    assert_eq!(*translations.lock().unwrap(), 1);
+    let requests = transport.requests.lock().unwrap();
+    let sent: Value = serde_json::from_slice(requests[0].body()).unwrap();
+    assert_eq!(sent["input"], "translated");
+    assert_eq!(sent["model"], MODEL);
+}
+
+#[tokio::test]
+async fn native_xai_translated_compaction_uses_one_selection_and_one_translation() {
+    let selector = StubSelector::success();
+    let transport = StubInferenceTransport::sequence([InferenceMode::SuccessBody(compaction_sse(
+        &valid_compaction_summary("translated compaction"),
+        None,
+    ))]);
+    let provider = provider(Arc::clone(&selector), transport.clone()).await;
+    let translations = Arc::new(Mutex::new(0_usize));
+    let source = Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "example-source",
+            Map::from_iter([("opaque".to_owned(), json!("source-only"))]),
+        )
+        .unwrap(),
+    ));
+    let target = match compaction_operation() {
+        Operation::Generate(request) => request.protocol_payload().body().clone(),
+        _ => unreachable!("compaction fixture is a generation request"),
+    };
+    let mut stream = provider
+        .execute(
+            provider_request_with_operation("xai", source),
+            context_with_middleware(Arc::new(TranslationMiddleware {
+                translations: Arc::clone(&translations),
+                target,
+            })),
+        )
+        .await
+        .expect("translated compaction should prepare one cold stream");
+    assert_eq!(selector.calls.load(Ordering::SeqCst), 1);
+    assert_eq!(transport.calls.load(Ordering::SeqCst), 0);
+    while let Some(event) = stream.next().await {
+        event.expect("translated compaction response");
+    }
+    assert_eq!(*translations.lock().unwrap(), 1);
+    assert_eq!(selector.calls.load(Ordering::SeqCst), 1);
+    assert_eq!(transport.calls.load(Ordering::SeqCst), 1);
+    let requests = transport.requests.lock().unwrap();
+    let sent: Value = serde_json::from_slice(requests[0].body()).unwrap();
+    assert_eq!(sent["store"], false);
+    assert!(
+        sent["input"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .all(|item| { item.get("type").and_then(Value::as_str) != Some("compaction_trigger") })
+    );
+}
+
+#[tokio::test]
+async fn native_xai_rejects_missing_or_capability_expanding_translation_before_send() {
+    let source = || {
+        Operation::Generate(GenerateRequest::from_protocol_payload(
+            ProtocolPayload::json_object(
+                "example-source",
+                Map::from_iter([("opaque".to_owned(), json!("source-only"))]),
+            )
+            .unwrap(),
+        ))
+    };
+
+    let selector = StubSelector::success();
+    let transport = StubInferenceTransport::success();
+    let missing_provider = provider(Arc::clone(&selector), transport.clone()).await;
+    let missing = match missing_provider
+        .execute(
+            provider_request_with_operation("xai", source()),
+            context_with_middleware(Arc::new(PassThroughMiddleware)),
+        )
+        .await
+    {
+        Ok(_) => panic!("missing translation pair must be explicit"),
+        Err(error) => error,
+    };
+    assert_eq!(missing.kind(), ProviderErrorKind::InvalidRequest);
+    assert_eq!(missing.send_state(), UpstreamSendState::NotSent);
+    assert_eq!(selector.calls.load(Ordering::SeqCst), 1);
+    assert_eq!(transport.calls.load(Ordering::SeqCst), 0);
+
+    let selector = StubSelector::success();
+    let transport = StubInferenceTransport::success();
+    let expanded_provider = provider(Arc::clone(&selector), transport.clone()).await;
+    let expanded = match expanded_provider
+        .execute(
+            provider_request_with_operation("xai", source()),
+            context_with_middleware(Arc::new(TranslationMiddleware {
+                translations: Arc::new(Mutex::new(0)),
+                target: object(json!({
+                    "model": "ignored-by-forced-model",
+                    "input": "translated",
+                    "tools": [{"type":"function", "name":"new_capability"}]
+                })),
+            })),
+        )
+        .await
+    {
+        Ok(_) => panic!("translation cannot expand routed capabilities"),
+        Err(error) => error,
+    };
+    assert_eq!(expanded.kind(), ProviderErrorKind::InvalidRequest);
+    assert_eq!(expanded.send_state(), UpstreamSendState::NotSent);
+    assert_eq!(selector.calls.load(Ordering::SeqCst), 1);
+    assert_eq!(transport.calls.load(Ordering::SeqCst), 0);
+}
+
+#[tokio::test]
+async fn native_response_translation_keeps_raw_xai_and_delivery_state_independent() {
+    let arguments =
+        serde_json::to_string(&json!({"operation":{"type":"delete_file","path":"note.txt"}}))
+            .unwrap();
+    let arguments_json = serde_json::to_string(&arguments).unwrap();
+    let body = format!(
+        concat!(
+            "event: response.created\n",
+            "data: {{\"type\":\"response.created\",\"response\":{{\"id\":\"resp_native_boundary\",\"model\":\"grok-4.5\"}}}}\n\n",
+            "event: response.output_item.added\n",
+            "data: {{\"type\":\"response.output_item.added\",\"output_index\":0,\"item\":{{\"id\":\"item_patch\",\"type\":\"function_call\",\"call_id\":\"call_patch\",\"name\":\"xai_proxy_apply_patch\"}}}}\n\n",
+            "event: response.output_item.done\n",
+            "data: {{\"type\":\"response.output_item.done\",\"output_index\":0,\"item\":{{\"id\":\"item_patch\",\"type\":\"function_call\",\"call_id\":\"call_patch\",\"name\":\"xai_proxy_apply_patch\",\"arguments\":{arguments_json}}}}}\n\n",
+            "event: response.completed\n",
+            "data: {{\"type\":\"response.completed\",\"response\":{{\"id\":\"resp_native_boundary\",\"model\":\"grok-4.5\",\"status\":\"completed\"}}}}\n\n",
+        ),
+        arguments_json = arguments_json,
+    );
+    let transport =
+        StubInferenceTransport::sequence([InferenceMode::SuccessBody(body.into_bytes())]);
+    let provider = provider(StubSelector::success(), transport).await;
+    let operation = Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object(
+            "openai",
+            Map::from_iter([
+                ("model".to_owned(), json!("client-model")),
+                ("input".to_owned(), json!("edit")),
+                ("tools".to_owned(), json!([{"type":"apply_patch"}])),
+            ]),
+        )
+        .unwrap(),
+    ));
+    let mut stream = provider
+        .execute(
+            provider_request_with_operation("xai", operation),
+            context(CancellationToken::new(), None),
+        )
+        .await
+        .expect("native response stream");
+    assert!(stream.has_native_response_translator());
+
+    let mut added_was_deferred = false;
+    let mut done_expanded = false;
+    let mut terminal_state_preserved = false;
+    while let Some(event) = stream.next().await {
+        let event = event.expect("source event");
+        if !event.has_client_event() {
+            continue;
+        }
+        let source_type = event
+            .wire_event()
+            .and_then(|wire| {
+                assert_eq!(wire.protocol(), "xai");
+                wire.data()
+                    .get("type")
+                    .and_then(Value::as_str)
+                    .map(str::to_owned)
+            })
+            .expect("xAI source event type");
+        let terminal = event
+            .canonical_facts()
+            .iter()
+            .any(|fact| matches!(fact, GatewayEvent::Completed(_)));
+        let had_session_update = event.session_update().is_some();
+        let translated = stream
+            .translate_native_response(event, terminal)
+            .expect("native response translation");
+        if source_type == "response.output_item.added" {
+            assert!(translated.is_empty());
+            added_was_deferred = true;
+            continue;
+        }
+        assert!(translated.iter().all(|event| {
+            event
+                .wire_event()
+                .is_some_and(|wire| wire.protocol() == "openai")
+        }));
+        if source_type == "response.output_item.done" {
+            assert_eq!(translated.len(), 2);
+            assert_eq!(
+                translated[0]
+                    .wire_event()
+                    .and_then(|wire| wire.event_type()),
+                Some("response.output_item.added")
+            );
+            assert!(translated.iter().all(|event| {
+                event.wire_event().is_some_and(|wire| {
+                    wire.data().pointer("/item/type") == Some(&json!("apply_patch_call"))
+                })
+            }));
+            done_expanded = true;
+        }
+        if terminal {
+            assert!(had_session_update);
+            terminal_state_preserved = translated
+                .first()
+                .is_some_and(|event| event.session_update().is_some());
+        }
+    }
+    assert!(added_was_deferred);
+    assert!(done_expanded);
+    assert!(terminal_state_preserved);
+}
+
+#[tokio::test]
+async fn pass_through_middleware_projects_native_response_once() {
+    let provider = provider(StubSelector::success(), StubInferenceTransport::success()).await;
+    let mut stream = provider
+        .execute(
+            provider_request("xai"),
+            context_with_middleware(Arc::new(PassThroughMiddleware)),
+        )
+        .await
+        .expect("native response stream");
+    assert!(!stream.has_native_response_translator());
+
+    let mut client_events = 0;
+    while let Some(event) = stream.next().await {
+        let event = event.expect("projected response event");
+        if let Some(wire) = event.wire_event() {
+            client_events += 1;
+            assert_eq!(wire.protocol(), "openai");
+        }
+    }
+    assert!(client_events > 0);
+}
+
+#[tokio::test]
+async fn attempt_middleware_runs_once_before_native_encoding() {
+    let transport = StubInferenceTransport::success();
+    let native_provider = provider(StubSelector::success(), transport.clone()).await;
+    let observed = Arc::new(Mutex::new(Vec::new()));
+    let body = json!({
+        "model": "client-model",
+        "input": "hello",
+        "service_tier": "priority",
+    });
+    let operation = Operation::Generate(GenerateRequest::from_protocol_payload(
+        ProtocolPayload::json_object("openai", body.as_object().unwrap().clone()).unwrap(),
+    ));
+    let mut stream = native_provider
+        .execute(
+            provider_request_with_operation("xai", operation),
+            context_with_middleware(Arc::new(RecordingMiddleware {
+                observed: Arc::clone(&observed),
+                replacement: None,
+                request_headers: vec![
+                    MiddlewareHeader::new(
+                        "x-business-context",
+                        Bytes::from_static(b"tenant-public"),
+                    ),
+                    MiddlewareHeader::new(
+                        "x-business-context",
+                        Bytes::from_static(b"trace-public"),
+                    ),
+                ],
+            })),
+        )
+        .await
+        .expect("native conversion should prepare the request");
+    assert_eq!(transport.calls.load(Ordering::SeqCst), 0);
+    while let Some(event) = stream.next().await {
+        event.expect("successful native response");
+    }
+    {
+        let observed = observed.lock().unwrap();
+        assert_eq!(observed.len(), 1);
+        assert_eq!(observed[0].0, "openai");
+        assert_eq!(observed[0].1["service_tier"], "priority");
+        let requests = transport.requests.lock().unwrap();
+        let sent: Map<String, Value> = serde_json::from_slice(requests[0].body()).unwrap();
+        assert!(!sent.contains_key("service_tier"));
+        assert_eq!(
+            requests[0]
+                .headers()
+                .iter()
+                .filter(|header| header.name() == "x-business-context")
+                .map(|header| header.value().expose())
+                .collect::<Vec<_>>(),
+            vec!["tenant-public", "trace-public"],
+        );
+    }
+
+    let conflict_transport = StubInferenceTransport::success();
+    let conflict_provider = provider(StubSelector::success(), conflict_transport.clone()).await;
+    let mut conflict = conflict_provider
+        .execute(
+            provider_request("xai"),
+            context_with_middleware(Arc::new(RecordingMiddleware {
+                observed: Arc::default(),
+                replacement: None,
+                request_headers: vec![MiddlewareHeader::new(
+                    "x-grok-client-version",
+                    Bytes::from_static(b"plugin-value"),
+                )],
+            })),
+        )
+        .await
+        .expect("header validation remains on the cold Provider stream");
+    let error = next_provider_error(&mut conflict).await;
+    assert_eq!(error.kind(), ProviderErrorKind::Protocol);
+    assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+    assert_eq!(conflict_transport.calls.load(Ordering::SeqCst), 0);
+    assert!(conflict_transport.requests.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn attempt_middleware_preserves_native_cache_tools() {
+    let transport = StubInferenceTransport::success();
+    let provider = provider(StubSelector::success(), transport.clone()).await;
+    let observed = Arc::new(Mutex::new(Vec::new()));
+    let mut stream = provider
+        .execute(
+            provider_request_with_operation(
+                "xai",
+                reasoning_replay_operation(
+                    "cache-policy-session",
+                    json!([{"type":"message","role":"user","content":"hello"}]),
+                ),
+            ),
+            context_with_middleware(Arc::new(RecordingMiddleware {
+                observed: Arc::clone(&observed),
+                replacement: None,
+                request_headers: Vec::new(),
+            })),
+        )
+        .await
+        .expect("native cache tools must not look like policy capability expansion");
+    while let Some(event) = stream.next().await {
+        event.expect("successful native response");
+    }
+
+    let observed = observed.lock().unwrap();
+    assert_eq!(observed.len(), 1);
+    assert!(observed[0].1.get("tools").is_none());
+    drop(observed);
+
+    let requests = transport.requests.lock().unwrap();
+    let sent: Value = serde_json::from_slice(requests[0].body()).unwrap();
+    assert_eq!(
+        sent.get("tools"),
+        Some(&json!([{"type":"web_search"}, {"type":"x_search"}]))
+    );
+    assert_eq!(sent.get("tool_choice"), Some(&json!("none")));
+}
+
+#[tokio::test]
+async fn attempt_middleware_updates_generation_and_compaction_input() {
+    for compact in [false, true] {
+        let (operation, transport) = if compact {
+            (
+                compaction_operation(),
+                StubInferenceTransport::sequence([InferenceMode::SuccessBody(compaction_sse(
+                    &valid_compaction_summary("normalized compaction"),
+                    None,
+                ))]),
+            )
+        } else {
+            (operation(), StubInferenceTransport::success())
+        };
+        let provider = provider(StubSelector::success(), transport.clone()).await;
+        let observed = Arc::new(Mutex::new(Vec::new()));
+        let mut stream = provider
+            .execute(
+                provider_request_with_operation("xai", operation),
+                context_with_middleware(Arc::new(RecordingMiddleware {
+                    observed: Arc::clone(&observed),
+                    replacement: Some(("instructions".to_owned(), json!("normalized instruction"))),
+                    request_headers: Vec::new(),
+                })),
+            )
+            .await
+            .expect("processed native request");
+        assert_eq!(transport.calls.load(Ordering::SeqCst), 0);
+        while let Some(event) = stream.next().await {
+            event.expect("normalization preserves a successful native response");
+        }
+        let observed = observed.lock().unwrap();
+        assert_eq!(observed.len(), 1);
+        assert_eq!(observed[0].0, "openai");
+        let requests = transport.requests.lock().unwrap();
+        assert_eq!(requests.len(), 1);
+        let sent: Value = serde_json::from_slice(requests[0].body()).unwrap();
+        assert_eq!(sent["instructions"], "normalized instruction");
+        assert_eq!(sent["model"], MODEL);
+    }
+}
+
+#[tokio::test]
+async fn attempt_middleware_can_change_reasoning_before_native_validation() {
+    let transport = StubInferenceTransport::success();
+    let provider = provider(StubSelector::success(), transport.clone()).await;
+    let observed = Arc::new(Mutex::new(Vec::new()));
+    let mut stream = provider
+        .execute(
+            provider_request_with_reasoning_operation(
+                "xai",
+                operation_with_reasoning_effort("minimal"),
+            ),
+            context_with_middleware(Arc::new(RecordingMiddleware {
+                observed: Arc::clone(&observed),
+                replacement: Some(("reasoning".to_owned(), json!({"effort":"xhigh"}))),
+                request_headers: Vec::new(),
+            })),
+        )
+        .await
+        .expect("thinking policy should prepare the xAI stream");
+    while let Some(event) = stream.next().await {
+        event.expect("successful xAI response");
+    }
+
+    let requests = transport.requests.lock().unwrap();
+    let body: Value = serde_json::from_slice(requests[0].body()).unwrap();
+    assert_eq!(body["reasoning"]["effort"], "high");
+    assert_eq!(body["model"], MODEL);
+    assert_eq!(
+        observed.lock().unwrap()[0].1["reasoning"]["effort"],
+        "minimal"
+    );
+}
+
+#[tokio::test]
+async fn middleware_output_still_passes_native_validation_before_send() {
+    let transport = StubInferenceTransport::success();
+    let provider = provider(StubSelector::success(), transport.clone()).await;
+    let error = provider
+        .execute(
+            provider_request_with_reasoning_operation(
+                "xai",
+                operation_with_reasoning_effort("medium"),
+            ),
+            context_with_middleware(Arc::new(RecordingMiddleware {
+                observed: Arc::default(),
+                replacement: Some(("input".to_owned(), json!(42))),
+                request_headers: Vec::new(),
+            })),
+        )
+        .await
+        .err()
+        .expect("unsupported reasoning remains invalid after middleware");
+    assert_eq!(error.kind(), ProviderErrorKind::InvalidRequest);
+    assert_eq!(error.send_state(), UpstreamSendState::NotSent);
+    assert_eq!(transport.calls.load(Ordering::SeqCst), 0);
+}
+
 fn observed_transport_metrics() -> GrokInferenceTransportMetrics {
     GrokInferenceTransportMetrics::default()
         .with_headers_ms(42)
@@ -620,7 +1122,7 @@ impl GrokCredentialRecovery for StubRecovery {
 async fn provider(
     selector: Arc<StubSelector>,
     transport: Arc<StubInferenceTransport>,
-) -> GrokBuildProvider {
+) -> Arc<GrokBuildProvider> {
     provider_with_recovery(
         selector,
         transport,
@@ -633,7 +1135,7 @@ async fn provider_with_recovery(
     selector: Arc<StubSelector>,
     transport: Arc<StubInferenceTransport>,
     recovery: Arc<StubRecovery>,
-) -> GrokBuildProvider {
+) -> Arc<GrokBuildProvider> {
     provider_with_catalog_transport(
         selector,
         transport,
@@ -648,7 +1150,7 @@ async fn provider_with_catalog_transport(
     transport: Arc<StubInferenceTransport>,
     recovery: Arc<StubRecovery>,
     catalog_transport: Arc<dyn GrokModelCatalogTransport>,
-) -> GrokBuildProvider {
+) -> Arc<GrokBuildProvider> {
     let store = MemoryProviderAccountStore::shared();
     let account_store: Arc<dyn ProviderAccountStore> = store.clone();
     let repository = GrokCredentialRepository::new(account_store);
@@ -664,15 +1166,17 @@ async fn provider_with_catalog_transport(
         catalog_transport,
         cache,
     ));
-    GrokBuildProvider::new(
-        selector,
-        transport,
-        catalog,
-        recovery,
-        Arc::new(AccountFeedbackStats::default()),
-        crate::support::xai_wire_profile(),
+    Arc::new(
+        GrokBuildProvider::new(
+            selector,
+            transport,
+            catalog,
+            recovery,
+            Arc::new(AccountFeedbackStats::default()),
+            crate::support::xai_wire_profile(),
+        )
+        .expect("official xAI provider configuration"),
     )
-    .expect("official xAI provider configuration")
 }
 
 async fn mapped_transport_error(
@@ -933,21 +1437,42 @@ fn provider_request(provider_kind: &str) -> ProviderRequest {
 }
 
 fn provider_request_with_operation(provider_kind: &str, operation: Operation) -> ProviderRequest {
-    provider_request_with_upstream_model(provider_kind, MODEL, operation)
+    provider_request_with_model_capabilities(provider_kind, MODEL, operation, false)
+}
+
+fn provider_request_with_reasoning_operation(
+    provider_kind: &str,
+    operation: Operation,
+) -> ProviderRequest {
+    provider_request_with_model_capabilities(provider_kind, MODEL, operation, true)
 }
 
 fn provider_request_with_upstream_model(
     provider_kind: &str,
     upstream_model: &str,
     operation: Operation,
+) -> ProviderRequest {
+    provider_request_with_model_capabilities(provider_kind, upstream_model, operation, false)
+}
+
+fn provider_request_with_model_capabilities(
+    provider_kind: &str,
+    upstream_model: &str,
+    operation: Operation,
+    supports_reasoning: bool,
 ) -> ProviderRequest {
     let provider = ProviderKind::new(provider_kind).expect("provider");
+    let mut capabilities =
+        ModelCapabilities::new(BTreeSet::from([OperationKind::Generate]), Some(131_072))
+            .with_feature(Feature::Tools, SupportLevel::Native)
+            .with_feature(Feature::NativeContinuation, SupportLevel::Native);
+    if supports_reasoning {
+        capabilities = capabilities.with_feature(Feature::Reasoning, SupportLevel::Native);
+    }
     let provider_model = ProviderModel::new(
         provider.clone(),
         UpstreamModelId::new(upstream_model).expect("model"),
-        ModelCapabilities::new(BTreeSet::from([OperationKind::Generate]), Some(131_072))
-            .with_feature(Feature::Tools, SupportLevel::Native)
-            .with_feature(Feature::NativeContinuation, SupportLevel::Native),
+        capabilities,
     );
     let account_scope = Arc::new(FrozenAccountScope::new(
         Arc::new(RuntimeAccountDirectory::new(BTreeMap::from([(
@@ -983,6 +1508,124 @@ fn selection_policy() -> AccountSelectionPolicy {
     )
 }
 
+#[derive(Debug)]
+struct TranslationMiddleware {
+    translations: Arc<Mutex<usize>>,
+    target: Map<String, Value>,
+}
+
+impl MiddlewarePlan for TranslationMiddleware {
+    fn handle(
+        &self,
+        context: MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        assert_eq!(context.mount(), MiddlewareMount::Attempt);
+        assert!(context.account_id().is_some());
+        *self.translations.lock().unwrap() += 1;
+        let (_, headers, _) = request.into_parts();
+        next.run(MiddlewareRequest::new(
+            "openai",
+            headers,
+            Bytes::from(serde_json::to_vec(&self.target).unwrap()),
+        ))
+    }
+}
+
+#[derive(Debug)]
+struct PassThroughMiddleware;
+
+impl MiddlewarePlan for PassThroughMiddleware {
+    fn handle(
+        &self,
+        _: MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        next.run(request)
+    }
+}
+
+type ObservedRequest = (String, Map<String, Value>);
+
+#[derive(Debug)]
+struct RecordingMiddleware {
+    observed: Arc<Mutex<Vec<ObservedRequest>>>,
+    replacement: Option<(String, Value)>,
+    request_headers: Vec<MiddlewareHeader>,
+}
+
+impl MiddlewarePlan for RecordingMiddleware {
+    fn handle(
+        &self,
+        context: MiddlewareContext,
+        request: MiddlewareRequest,
+        next: Box<dyn MiddlewareNext>,
+    ) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
+        assert_eq!(context.mount(), MiddlewareMount::Attempt);
+        let (protocol, mut headers, bytes) = request.into_parts();
+        let mut body: Map<String, Value> = serde_json::from_slice(&bytes).unwrap();
+        self.observed
+            .lock()
+            .unwrap()
+            .push((protocol.clone(), body.clone()));
+        if let Some((field, value)) = &self.replacement {
+            body.insert(field.clone(), value.clone());
+        }
+        headers.extend(self.request_headers.clone());
+        next.run(MiddlewareRequest::new(
+            protocol,
+            headers,
+            Bytes::from(serde_json::to_vec(&body).unwrap()),
+        ))
+    }
+}
+
+#[derive(Debug)]
+struct TestExtensionLease;
+
+impl ExtensionSetLease for TestExtensionLease {
+    fn is_ready(&self) -> bool {
+        true
+    }
+}
+
+fn context_with_middleware(plan: Arc<dyn MiddlewarePlan>) -> AttemptContext {
+    context_with_middleware_and_cancellation(plan, CancellationToken::new())
+}
+
+fn context_with_middleware_and_cancellation(
+    plan: Arc<dyn MiddlewarePlan>,
+    cancellation: CancellationToken,
+) -> AttemptContext {
+    let plan = FrozenMiddlewarePlan::new(
+        plan,
+        ExtensionSetReference::new(
+            ExtensionSetId::new("native-xai-middleware".to_owned()).unwrap(),
+            Arc::new(TestExtensionLease),
+        ),
+    );
+    AttemptContext::new(
+        gateway_core::engine::RequestAttemptContext::new(
+            ModelRequestId::new("req_xai_middleware").unwrap(),
+            ClientApiKeyId::new("key_xai_contract").unwrap(),
+        )
+        .with_middleware(
+            Some(plan),
+            Arc::from([]),
+            "/v1/responses".to_owned(),
+            ClientTransport::HttpSse,
+        ),
+        NonZeroU32::MIN,
+        SystemTime::now() + Duration::from_secs(30),
+        selection_policy(),
+        AccountAttemptContext::new(BTreeSet::new(), None, None),
+        None,
+        cancellation,
+    )
+}
+
 fn context(
     cancellation: CancellationToken,
     continuation: Option<ContinuationBinding>,
@@ -1030,8 +1673,8 @@ fn context_with_continuation_attempt(
     context(CancellationToken::new(), Some(continuation)).with_continuation_attempt(attempt)
 }
 
-async fn execute_successfully(provider: &GrokBuildProvider, operation: Operation) {
-    let mut stream = provider
+async fn execute_successfully(provider: &Arc<GrokBuildProvider>, operation: Operation) {
+    let mut stream = Arc::clone(provider)
         .execute(
             provider_request_with_operation("xai", operation),
             context(CancellationToken::new(), None),
@@ -1139,19 +1782,21 @@ async fn disabled_account_diagnostic_selects_the_pinned_account_without_state_wr
         Arc::new(MemoryCooldownPort::default()),
         Arc::new(AccountFeedbackStats::default()),
     );
-    let provider = GrokBuildProvider::new(
-        Arc::new(selector),
-        StubInferenceTransport::success(),
-        Arc::new(crate::support::grok_catalog_service(
-            repository,
-            Arc::new(StaticCatalogTransport),
-            MemoryGrokCatalogCache::shared(),
-        )),
-        StubRecovery::new(GrokCredentialRecoveryOutcome::Unavailable),
-        Arc::new(AccountFeedbackStats::default()),
-        crate::support::xai_wire_profile(),
-    )
-    .expect("official xAI provider configuration");
+    let provider = Arc::new(
+        GrokBuildProvider::new(
+            Arc::new(selector),
+            StubInferenceTransport::success(),
+            Arc::new(crate::support::grok_catalog_service(
+                repository,
+                Arc::new(StaticCatalogTransport),
+                MemoryGrokCatalogCache::shared(),
+            )),
+            StubRecovery::new(GrokCredentialRecoveryOutcome::Unavailable),
+            Arc::new(AccountFeedbackStats::default()),
+            crate::support::xai_wire_profile(),
+        )
+        .expect("official xAI provider configuration"),
+    );
 
     let mut stream = provider
         .execute(
@@ -1884,7 +2529,7 @@ async fn compaction_protocol_stream_failure_should_allow_pre_delivery_recovery()
 async fn inference_request_uses_oauth_headers_and_no_api_key() {
     let transport = StubInferenceTransport::success();
     let provider = provider(StubSelector::success(), transport.clone()).await;
-    let mut stream = provider
+    let mut stream = Arc::clone(&provider)
         .execute(
             provider_request("xai"),
             context(CancellationToken::new(), None),
@@ -2606,7 +3251,7 @@ async fn continuation_should_inherit_unchanged_instructions_and_replay_changed_i
             ProtocolPayload::json_object("openai", first_body.as_object().expect("body").clone())
                 .expect("payload"),
         ));
-        let mut first = provider
+        let mut first = Arc::clone(&provider)
             .execute(
                 provider_request_with_operation("xai", operation),
                 context(CancellationToken::new(), None),
@@ -2999,7 +3644,7 @@ async fn connection_state_inherits_session_and_recovers_reasoning_on_pinned_acco
         )
         .expect("OpenAI payload"),
     ));
-    let mut first = provider
+    let mut first = Arc::clone(&provider)
         .execute(
             provider_request_with_operation("xai", first_operation),
             context(CancellationToken::new(), None),
@@ -3025,7 +3670,7 @@ async fn connection_state_inherits_session_and_recovers_reasoning_on_pinned_acco
         }),
         state.clone(),
     );
-    let mut continued = provider
+    let mut continued = Arc::clone(&provider)
         .execute(
             provider_request_with_operation("xai", continued_operation),
             context(
@@ -3125,7 +3770,7 @@ async fn replay_owner_should_reencode_custom_apply_patch_call_for_grok() {
         )
         .expect("OpenAI payload"),
     ));
-    let mut first = provider
+    let mut first = Arc::clone(&provider)
         .execute(
             provider_request_with_operation("xai", first_operation),
             context(CancellationToken::new(), None),
@@ -3253,9 +3898,16 @@ async fn cancellation_before_poll_never_calls_transport() {
     let provider = provider(StubSelector::success(), transport.clone()).await;
     let cancellation = CancellationToken::new();
     let mut stream = provider
-        .execute(provider_request("xai"), context(cancellation.clone(), None))
+        .execute(
+            provider_request("xai"),
+            context_with_middleware_and_cancellation(
+                Arc::new(PassThroughMiddleware),
+                cancellation.clone(),
+            ),
+        )
         .await
         .expect("prepared stream");
+    assert!(!stream.has_native_response_translator());
     cancellation.cancel();
     let error = stream
         .next()
diff --git a/backend/migrations/.frozen-sha256 b/backend/migrations/.frozen-sha256
index 8d360df6e..1e8e3f5c9 100644
--- a/backend/migrations/.frozen-sha256
+++ b/backend/migrations/.frozen-sha256
@@ -15,3 +15,5 @@ b20e425c0b062b72d35fdebe294e023eb17ceb44ac93083ff3d48400715bf430  0012_upstream_
 9bd37bd314b6864816c43cb4fd1869fb415920d4f10f766976e344334a1f60fc  0015_proxy_dual_stack_exit.sql
 a1e23b8535ed41de27861833cd2d5ee7498a9bb0e523156ba3f011f9c6b3966b  0016_client_profiles_and_model_pricing.sql
 fcfae912ddefd54551ebf8e7e733442519d2862d2977134d548ebc1e75c1dc34  0017_unlimited_default_account_concurrency.sql
+deb4ef30b3a8a1c7a76055dbd09e5d232d9bb85b712205f5fb9c38c28417900d  0018_plugins.sql
+667fa2969ab9fc714a74e1a53470f738298d78ed6a248e07172c828bd702452c  0019_plugin_version_configurations.sql
diff --git a/backend/migrations/0018_plugins.sql b/backend/migrations/0018_plugins.sql
new file mode 100644
index 000000000..b58403231
--- /dev/null
+++ b/backend/migrations/0018_plugins.sql
@@ -0,0 +1,145 @@
+-- 更新规则可变；制品保存安装时的来源事实，包体随 PostgreSQL 备份恢复。
+create table plugin_update_sources (
+    plugin_id text primary key check (
+        octet_length(plugin_id) <= 64
+        and plugin_id ~ '^[a-z0-9]([a-z0-9-]*[a-z0-9])?[.][a-z0-9]([a-z0-9-]*[a-z0-9])?$'
+    ),
+    source_json jsonb not null check (jsonb_typeof(source_json) = 'object'),
+    policy_json jsonb not null default '{"kind":"manual"}'::jsonb
+        check (jsonb_typeof(policy_json) = 'object'),
+    outbound_proxy_id text references outbound_proxies(id) on delete restrict
+);
+
+create index plugin_update_sources_outbound_proxy_id_idx on plugin_update_sources(outbound_proxy_id);
+
+create table plugin_artifacts (
+    sha256 text primary key check (sha256 ~ '^[0-9a-f]{64}$'),
+    plugin_id text not null references plugin_update_sources(plugin_id),
+    version text not null check (length(version) between 1 and 128),
+    metadata_json jsonb not null check (jsonb_typeof(metadata_json) = 'object'),
+    source_json jsonb not null check (jsonb_typeof(source_json) = 'object'),
+    -- 历史下载引用阻止代理被误删；地址与认证仍只存在受管代理记录中。
+    outbound_proxy_id text references outbound_proxies(id) on delete restrict,
+    archive bytea not null check (octet_length(archive) between 1 and 33554432),
+    installed_at timestamptz not null default now(),
+    -- 接受事实绑定不可变包；实例运行权限从包声明派生。
+    accepted_at timestamptz
+);
+
+create index plugin_artifacts_plugin_id_idx on plugin_artifacts(plugin_id);
+create index plugin_artifacts_outbound_proxy_id_idx on plugin_artifacts(outbound_proxy_id);
+
+-- 平台逐项约束，避免通过增加另一平台条目绕过同版本不可变规则。
+create table plugin_artifact_platforms (
+    plugin_id text not null,
+    version text not null,
+    platform text not null,
+    artifact_sha256 text not null references plugin_artifacts(sha256) on delete cascade,
+    primary key (plugin_id, version, platform)
+);
+
+create index plugin_artifact_platforms_artifact_sha256_idx on plugin_artifact_platforms(artifact_sha256);
+
+-- 下载鉴权单独持久化；普通列表和审计只返回 info_json，不读取 secret_json。
+create table plugin_source_credentials (
+    id uuid primary key,
+    info_json jsonb not null check (jsonb_typeof(info_json) = 'object'),
+    secret_json jsonb not null check (jsonb_typeof(secret_json) = 'object')
+);
+
+create table plugin_artifact_credentials (
+    artifact_sha256 text not null references plugin_artifacts(sha256) on delete cascade,
+    credential_id uuid not null references plugin_source_credentials(id),
+    primary key (artifact_sha256, credential_id)
+);
+
+create index plugin_artifact_credentials_credential_id_idx on plugin_artifact_credentials(credential_id);
+
+create table plugin_instances (
+    id uuid primary key,
+    artifact_sha256 text not null references plugin_artifacts(sha256),
+    name text not null check (length(name) between 1 and 128),
+    enabled boolean not null,
+    configuration_json jsonb not null check (jsonb_typeof(configuration_json) = 'object' and octet_length(configuration_json::text) <= 65536),
+    bindings_json jsonb not null check (jsonb_typeof(bindings_json) = 'array'),
+    revision bigint not null check (revision > 0)
+);
+
+create index plugin_instances_artifact_sha256_idx on plugin_instances(artifact_sha256);
+
+create table plugin_instance_secrets (
+    instance_id uuid primary key references plugin_instances(id) on delete cascade,
+    secrets_json jsonb not null check (jsonb_typeof(secrets_json) = 'object' and octet_length(secrets_json::text) <= 65536)
+);
+
+-- 私有状态与配置 revision 分离；普通状态写入不得推进全局 revision。
+create table plugin_state_generations (
+    id uuid primary key,
+    transition_id uuid,
+    instance_id uuid not null references plugin_instances(id) on delete cascade,
+    namespace text not null check (namespace ~ '^[a-z][a-z0-9_.-]{0,63}$'),
+    artifact_sha256 text not null references plugin_artifacts(sha256),
+    schema_version bigint not null check (schema_version between 1 and 4294967295),
+    schema_sha256 text not null check (schema_sha256 ~ '^[0-9a-f]{64}$'),
+    maximum_records bigint not null check (maximum_records between 1 and 10000),
+    maximum_bytes bigint not null check (maximum_bytes between 1 and 16777216),
+    maximum_value_bytes bigint not null check (
+        maximum_value_bytes between 1 and 262144
+        and maximum_value_bytes <= maximum_bytes
+    ),
+    instance_revision bigint not null check (instance_revision > 0),
+    fence uuid not null,
+    status text not null check (status in ('staging', 'active')),
+    source_generation_id uuid references plugin_state_generations(id),
+    next_record_version bigint not null default 1 check (next_record_version > 0),
+    record_count bigint not null default 0 check (record_count between 0 and maximum_records),
+    total_bytes bigint not null default 0 check (total_bytes between 0 and maximum_bytes),
+    migration_cursor text,
+    migration_complete boolean not null default false,
+    created_at timestamptz not null default now(),
+    promoted_at timestamptz,
+    unique (instance_id, namespace, status),
+    unique (transition_id, namespace),
+    check (source_generation_id is null or source_generation_id <> id),
+    check (
+        (status = 'staging' and transition_id is not null)
+        or (status = 'active' and transition_id is null and source_generation_id is null
+            and migration_cursor is null and migration_complete and promoted_at is not null)
+    )
+);
+
+create index plugin_state_generations_artifact_sha256_idx on plugin_state_generations(artifact_sha256);
+create index plugin_state_generations_source_generation_id_idx on plugin_state_generations(source_generation_id);
+
+create table plugin_state_records (
+    generation_id uuid not null references plugin_state_generations(id) on delete cascade,
+    -- 游标分页与 Rust 字符串比较都按 UTF-8 字节序，不受数据库 locale 影响。
+    state_key text collate "C" not null check (
+        length(state_key) between 1 and 256
+        and octet_length(state_key) <= 512
+        and state_key !~ '[[:cntrl:]]'
+    ),
+    value_json jsonb not null,
+    value_bytes bigint not null check (value_bytes between 1 and 262144),
+    record_version bigint not null check (record_version > 0),
+    primary key (generation_id, state_key)
+);
+
+-- 授权回执与账号写入同事务提交；不保存 flow、回调地址或凭据文档。
+create table authorization_receipts (
+    provider_kind text not null,
+    flow_digest text not null check (flow_digest ~ '^[0-9a-f]{64}$'),
+    owner_digest text not null check (owner_digest ~ '^[0-9a-f]{64}$'),
+    config_revision bigint not null check (config_revision > 0),
+    accounts_json jsonb not null check (
+        jsonb_typeof(accounts_json) = 'array'
+        and jsonb_array_length(accounts_json) between 1 and 200
+        and octet_length(accounts_json::text) <= 65536
+    ),
+    created_at timestamptz not null default now(),
+    expires_at timestamptz not null default (now() + interval '24 hours'),
+    primary key (provider_kind, flow_digest),
+    check (expires_at > created_at)
+);
+
+create index authorization_receipts_expiry_idx on authorization_receipts (expires_at);
diff --git a/backend/migrations/0019_plugin_version_configurations.sql b/backend/migrations/0019_plugin_version_configurations.sql
new file mode 100644
index 000000000..c260cc5dc
--- /dev/null
+++ b/backend/migrations/0019_plugin_version_configurations.sql
@@ -0,0 +1,18 @@
+-- 配置恢复与插件私有状态迁移分离，删除实例或制品时同步清理对应快照。
+create table plugin_version_configurations (
+    instance_id uuid not null references plugin_instances(id) on delete cascade,
+    artifact_sha256 text not null references plugin_artifacts(sha256) on delete cascade,
+    configuration_json jsonb not null check (jsonb_typeof(configuration_json) = 'object'),
+    secrets_json jsonb not null check (jsonb_typeof(secrets_json) = 'object'),
+    bindings_json jsonb not null check (jsonb_typeof(bindings_json) = 'array'),
+    primary key (instance_id, artifact_sha256)
+);
+
+-- 只为已有启用配置建立恢复点，未启用草稿不能冒充可用版本。
+insert into plugin_version_configurations
+    (instance_id, artifact_sha256, configuration_json, secrets_json, bindings_json)
+select i.id, i.artifact_sha256, i.configuration_json,
+       coalesce(s.secrets_json, '{}'::jsonb), i.bindings_json
+from plugin_instances i
+left join plugin_instance_secrets s on s.instance_id = i.id
+where i.enabled;
diff --git a/backend/migrations/README.md b/backend/migrations/README.md
index e71510665..bf2005e18 100644
--- a/backend/migrations/README.md
+++ b/backend/migrations/README.md
@@ -3,7 +3,7 @@
 sqlx 在服务启动、监听请求之前按编号执行迁移，并把文件 checksum 记入 `_sqlx_migrations`。
 已应用迁移的字节与记录不一致时，服务会拒绝启动。
 
-`0001_initial.sql` 定义数据库初始化基线，后续 schema 变更按编号新增迁移。
+初始化基线与后续 schema 变更按递增编号组织。
 完整清单以本目录 SQL 文件和 `.frozen-sha256` 为准。
 
 ## 冻结规则
@@ -12,7 +12,7 @@ sqlx 在服务启动、监听请求之前按编号执行迁移，并把文件 ch
   空白。任何改动都会让该大版本的已部署实例在下次重启时因 checksum 失配而无法启动，
   且没有自动恢复路径。
 - 同一大版本内的 schema 变更一律新增编号迁移，永远不回改
-  旧文件。切换大版本时允许把已完成升级的 schema 折叠成新的 `0001` 基线，因为跨大版本
+  旧文件。切换大版本时允许把已完成升级的 schema 折叠成新的初始化基线，因为跨大版本
   不支持在线升级，目标版本必须使用全新数据目录部署。
 - 支持连续升级的预发行线从首次发布起同样冻结迁移。alpha、beta、rc 到对应正式版必须保留
   已发布迁移的编号与字节；同一轮 exp 的后续发行也只能追加迁移。发布前以该发行线已发布版本
diff --git a/deploy/Dockerfile b/deploy/Dockerfile
index 867ce105b..56d49a9c6 100644
--- a/deploy/Dockerfile
+++ b/deploy/Dockerfile
@@ -8,7 +8,7 @@ FROM node:26-bookworm-slim@sha256:2d49d876e96237d76de412761cf05dbfe5aee325cc4406
 
 WORKDIR /app/frontend
 COPY frontend/package.json frontend/pnpm-lock.yaml frontend/pnpm-workspace.yaml ./
-RUN npm install --global pnpm@11.7.0 \
+RUN npm install --global "$(node -p 'require("./package.json").packageManager')" \
     && pnpm install --frozen-lockfile
 COPY frontend ./
 RUN pnpm build
@@ -88,5 +88,9 @@ ARG CPR_PREBUILT_DIR=dist/docker
 
 COPY --chown=cpr:cpr ${CPR_PREBUILT_DIR}/linux-${TARGETARCH}/codex-proxy-rs /app/bin/codex-proxy-rs
 COPY --chown=cpr:cpr ${CPR_PREBUILT_DIR}/web/dist ./web/dist
-RUN chmod +x /app/bin/codex-proxy-rs
+COPY --chown=cpr:cpr ${CPR_PREBUILT_DIR}/linux-${TARGETARCH}/plugins/official /app/bin/plugins/official
+RUN chmod +x /app/bin/codex-proxy-rs \
+    && find /app/bin/plugins/official -type f -exec chmod 0444 '{}' + \
+    && chmod 0555 /app/bin/plugins/official \
+    && chmod 0755 /app/bin/plugins
 USER cpr
diff --git a/deploy/Dockerfile.dockerignore b/deploy/Dockerfile.dockerignore
index a130a34a4..8fa95e8d4 100644
--- a/deploy/Dockerfile.dockerignore
+++ b/deploy/Dockerfile.dockerignore
@@ -1,6 +1,8 @@
 # Build outputs and dependency caches.
 **/target/
-frontend/node_modules/
+**/node_modules/
+**/.pnpm-store/
+**/.pnpm-cache/
 frontend/dist/
 frontend/.vite/
 dist/*
@@ -19,6 +21,7 @@ deploy/logs/
 local.yaml
 local.yml
 .env
+.env.*
 config.yaml
 deploy/config.yaml
 deploy/.env
diff --git a/deploy/README.md b/deploy/README.md
index 53a90885e..e4560b9d2 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -4,16 +4,33 @@
 本文补充客户端配置、权限、备份和升级；部署命令从安装目录 `codex-proxy-rs/` 执行，
 其中 `deploy/` 存放 Compose 文件和配置，`.runtime/` 存放持久化数据。
 
-需要维护的配置文件：
+配置按职责保存，不都在 YAML 中：
 
-- `config.yaml`：应用行为与真实凭据，由 `config.example.yaml` 复制得到并被 Git 忽略。
-- `compose.yaml`：镜像、容器网络、端口、目录映射、健康检查和资源限制。
+| 位置 | 内容 | 修改方式 |
+| --- | --- | --- |
+| `deploy/config.yaml` | 监听、数据库/Redis 连接、部署凭据与日志等启动配置 | 从模板创建，已有部署合并修改，不覆盖原文件 |
+| `deploy/compose.yaml` | 镜像、容器网络、端口、挂载与资源限制 | 调整 Compose 并重建受影响容器 |
+| PostgreSQL | 账号、Key、运行设置、上游身份、插件配置等业务数据 | 管理端或管理 API |
+| 浏览器本地 | 主题和界面偏好 | 当前浏览器的主题设置 |
 
-项目不使用 `.env` 配置文件。Compose 环境变量用于容器地址、镜像选择和构建发布；
-应用设置与凭据保存在 `config.yaml` 中。已有部署不要重新复制模板覆盖配置。
+项目不使用 `.env` 配置文件。Compose 环境变量用于容器地址、镜像选择和构建发布。
 配置加载会忽略未知或已移除的字段，并在启动控制台提示字段名；不输出对应值。缺少必填字段时会指出缺项并停止启动，
 已知字段的类型和取值仍需合法；可选字段省略时使用默认值。
 
+## 部署结构
+
+```mermaid
+flowchart LR
+  Client[客户端 / 管理浏览器] -->|HTTPS| Proxy[反向代理]
+  Proxy -->|HTTP / SSE / WebSocket| App[网关：单副本]
+  App --> PG[(PostgreSQL)]
+  App --> Redis[(Redis)]
+  App --> Upstream[上游服务]
+  App -. 数据库备份 .-> Backup[S3 / R2]
+```
+
+网关端口默认只绑定本机；数据库和 Redis 不对公网开放。插件以网关同一系统身份运行，不能作为不可信代码沙箱。
+
 ## 手动安装
 
 本节适用于 Linux amd64/arm64，需准备 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL，
@@ -64,24 +81,6 @@ Linux 上应用容器以 `10001:10001` 运行。上述命令将应用数据和
 配置设为 `0640`，均由当前用户持有、容器组 `10001` 访问。
 `config.yaml` 通过 Compose `configs` 只读挂载，普通 Compose 保留宿主机文件的 UID/GID 和 mode。
 
-OpenAI 与 xAI 上游身份在管理端「系统设置 → 上游配置 → 客户端身份」配置，Key 可按 Provider 选择独立身份覆盖通用值。
-OpenAI 首次默认 macOS Desktop 自动最新，支持范围与字段见 [客户端身份合同](../docs/api.md#openai-上游客户端身份)。
-客户端身份只保存于数据库；首次使用内置默认值，重启不会覆盖已有选择。
-`openai.residency` 为独立的数据驻留部署约束，省略或 `null` 时不指定；后台账号与 Desktop 专属请求使用内置官方画像。
-OpenAI 上游地址、WebSocket 池、额度刷新和 OAuth 使用 Provider 默认值。
-xAI 无需 YAML 配置，首次默认 Grok CLI 的 Linux x86_64 身份并采用自动更新。
-管理端支持固定版本与自动更新；字段及生效范围见 [xAI 客户端身份](../docs/api.md#xai-上游客户端身份)。
-xAI 的后台 OAuth、目录和额度查询使用内置官方画像。
-后台发布检查只更新可重建的版本资料，不回写用户选择或 `config.yaml`；失败继续使用同组合的有效版本。
-
-全局请求位置在管理端「系统设置 → 上游配置 → 请求位置覆盖」配置，默认关闭，保留客户端原有位置和时区。
-开启后使用自定义位置，关闭时保留已保存的自定义值。「代理管理」设置的自定义位置优先于全局设置，
-全局关闭时代理自定义仍生效。保存后新请求生效，无需重启；关闭代理自定义后恢复全局继承。
-该设置统一 OpenAI Responses 的 Web Search 位置与带来源标记的环境日期、时区，不修改 epoch 时间戳、
-真实出口 IP 或服务系统时区。字段约束见 [运行设置](../docs/api.md#8-运行设置)。
-
-请求位置由管理端设置，数据库初始化不从 `config.yaml` 导入位置值。
-
 ## 启动
 
 ```bash
@@ -102,6 +101,45 @@ curl -i http://127.0.0.1:8080/healthz
 不要把未脱敏的 `docker compose config` 或 `docker inspect` 输出上传到工单；它们会包含
 PostgreSQL/Redis 启动密码。日常校验使用 `config --quiet`。
 
+### 启动后的运行设置
+
+在管理端修改以下设置，保存后对新请求生效，重启不会覆盖已保存的选择：
+
+| 设置 | 入口与边界 |
+| --- | --- |
+| 上游客户端身份 | “系统设置 → 上游配置 → 客户端身份”；Key 可按 Provider 覆盖，支持自动或固定版本 |
+| 全局请求位置 | “系统设置 → 上游配置 → 请求位置覆盖”；默认关闭，不从 YAML 导入 |
+| 代理位置 | “代理管理”；优先于全局位置，全局关闭时仍可独立生效 |
+
+位置覆盖只影响 OpenAI 请求中受支持的位置、日期与时区信息，不改变真实出口 IP、epoch 时间戳或系统时区。
+`openai.residency` 是独立的部署约束。身份与位置字段见 [运行设置 API](../docs/api.md#8-运行设置)。
+后台账号操作使用 Provider 自己的官方画像；发布资料刷新不改写用户选择或 `config.yaml`。
+
+### 插件命令行
+
+使用与网关相同的工作目录和 `deploy/config.yaml`，读取制品已接受且当前已启用的插件实例：
+
+```bash
+codex-proxy-rs plugin --help
+codex-proxy-rs plugin <实例ID> <命令> --help
+codex-proxy-rs plugin <实例ID> <命令> --参数 值
+```
+
+不带子命令或使用 `serve` 时启动网关；插件命令不监听 HTTP、不启动后台任务，也不恢复或清理正在运行的
+网关准入状态。顶层 `--help/--version` 不读取配置。插件帮助只读数据库，不执行迁移、登录或账号保存，
+因此需要先由正常部署完成数据库初始化。宿主诊断保留在配置的文件日志中，stdout/stderr 专用于命令结果。
+
+参数支持 `--名称=值` 或 `--名称 值`；布尔参数可直接写 `--名称`，关闭时写 `--名称=false`。
+duration 使用 `500ms`、`1m30s` 等带单位形式。参数可能进入 shell 历史和系统进程列表，不能因为插件声明
+了敏感参数就认为命令行是安全的密钥输入通道；真实凭据优先使用对应插件提供的受控登录或导入入口。
+
+成功命令原样返回插件退出码与输出。命令受总期限约束，`Ctrl-C` 或终止信号会取消调用并回收插件进程。
+若命令产生账号，只有成功结果才按顺序通过 Admin 保存；调用受制品访问域、`command_line` 阶段和当前资源事实约束，
+模型执行 Key 由具体调用选择，不在实例中预绑定。
+部分保存后失败或取消不会自动重放，先核对账号和审计记录，再决定是否重新执行。
+
+独立仓库 `codex-proxy-plugins` 的 `examples/request-workbench` 提供不访问真实上游的综合示例。
+
 ## 公网访问
 
 Compose 默认只绑定 `127.0.0.1`。从其他设备访问时，在应用前配置反向代理，
@@ -259,6 +297,12 @@ cargo run -p codex-proxy-rs
 `CPR_TEST_DATABASE_URL` / `CPR_TEST_REDIS_URL` 约定见
 [迁移文档](../backend/migrations/README.md)。
 
+管理端的依赖准备与 UI 源码联调见 [贡献与验证](../CONTRIBUTING.md#验证)。另开终端从仓库根目录启动前端：
+
+```bash
+pnpm --dir frontend dev
+```
+
 ## 持久化与备份
 
 Compose 使用以下绑定目录：
@@ -343,6 +387,24 @@ OpenAI 主动额度重置卡及其消费结果由上游持有，不写入 Postgr
 请求问题反馈使用 [接口问题反馈表单](../.github/ISSUE_TEMPLATE/api-bug-report.yml)；错误诊断与查询合同见
 [API 文档](../docs/api.md#10-dashboard用量与错误)。
 
+### 插件取文与 Fake-IP DNS
+
+插件受管 HTTP 会检查域名解析出的全部地址，再使用通过校验的地址连接，默认拒绝内网、回环、
+链路本地和保留地址。配置了代理也不会跳过目标地址校验，宿主不自动改用公共 DNS。
+
+若取文提示“目标地址被安全策略拦截”，先在**实际运行网关的主机或容器内**检查域名解析。
+Clash / Mihomo 的 Fake-IP 模式可能把公网域名解析为 `198.18.0.0/15` 中的地址，此时应调整代理 DNS，
+让需要访问的域名返回真实公网地址，不要关闭宿主检查或放行整个保留地址段。
+
+例如 Mihomo 使用 `fake-ip-filter-mode: blacklist` 时，将 `github.com` 追加到现有
+`dns.fake-ip-filter` 列表，保留原条目及其他 DNS、代理规则。Clash Verge Rev 开启 DNS 覆写时，
+应在 DNS 设置中修改持久配置，而不是只编辑会被重新生成的运行配置。规则模式和白名单模式含义不同，
+按所用版本的 [Mihomo DNS 文档](https://wiki.metacubex.one/config/dns/)配置。
+重新加载后确认解析结果已改变，再验证实际取文；浏览器或普通 `curl` 可访问不能代替宿主校验。
+
+宿主日志中的“插件受管 HTTP 请求失败”只记录固定原因、错误类别和发送状态，不包含请求网址、
+请求头、正文或凭据。域名解析失败、网络超时、连接失败和地址拒绝应分别处理，不需要开启请求转储。
+
 ## 密码语义
 
 - `admin.default_password` 只在首次创建管理员时使用。
@@ -379,7 +441,7 @@ docker compose -f deploy/compose.yaml pull codex-proxy-rs
 docker compose -f deploy/compose.yaml up -d --no-build --wait codex-proxy-rs
 ```
 
-源码构建需要克隆源码仓库并准备配置与数据目录，以下命令从仓库根目录执行：
+源码构建需要克隆源码仓库并准备配置与数据目录。UI 组件库从锁定的 GitHub 提交下载，并在前端依赖安装阶段自动构建，无需准备同级源码仓库或额外 build context。以下命令从仓库根目录执行：
 
 ```bash
 docker compose -f deploy/compose.yaml build codex-proxy-rs
@@ -451,10 +513,34 @@ Release 必须提供当前 OS/架构的 `codex-proxy-rs_<version>_<os>_<arch>.ta
 .runtime/data/update-tmp/
 ```
 
+### 插件兼容与发行目录
+
+教学示例在 `codex-proxy-plugins` 独立构建和发布，通过[插件管理](../docs/plugins.md)安装。
+宿主发行物当前不内置插件，但仍包含用于兼容检查的封口清单。
+
+| 文件或目录 | 用途 |
+| --- | --- |
+| `plugin-release-manifest.json` | 固定宿主版本、提交、平台与支持的插件合同；插件列表当前为空 |
+| 可执行文件同目录的 `plugins/official` | 随受信宿主发行物部署的只读目录，与二进制、Web 资源成套更新或恢复 |
+
+- 更新或回滚前，逐一检查启用实例的精确包与目标宿主是否兼容。制品缺失、不兼容或并发配置变更会阻止切换；失败或取消时恢复整组文件，不自动停用插件或接受其他制品
+- 非空官方清单中的包经身份、平台和摘要校验后幂等导入；导入不接受访问域、不创建配置、不启用，也不删除旧包。管理员确认访问域后才执行默认配置流程；重复摘要保留首次安装出处
+- `sealed` 是构建封口标记，不是密码学签名。普通上传、URL 或 GitHub 安装不能获得 `builtin` 身份，独立教学示例也不例外
+
+首次从不支持官方目录的旧更新器升级时，须完整解压平台发行包或更新正式容器镜像；旧更新器不会复制新增目录。
+后续在线更新会成套处理该目录。macOS arm64 提供构建产物；部署前仍需验证目标平台的插件运行与上游调用，不能只以打包成功判断可用。
+
 ## 备份与恢复
 
 ### 备份内容与限制
 
+- 插件包体、固定来源、下载凭据、制品接受事实、实例配置、版本配置快照、敏感配置、能力/Provider 绑定和私有状态都保存在
+  PostgreSQL，随数据库一起备份；插件 Provider 账号仍使用同库的通用账号表，不另建第二份账号权威。
+  来源使用的出站代理及其认证也须随库恢复，不能只备份 `plugin_*` 表；来源代理与账号代理独立选择，
+  不依赖进程代理环境，故障时不会自动回退直连。
+  包体单个上限为 32 MiB，需要计入数据库及备份容量；解压运行目录和 Redis 协调状态是可重建数据，
+  不作为插件安装或访问域事实。恢复时保留制品接受状态、实例配置、账号引用和状态代次的一致性；插件降级仍须
+  通过状态兼容校验，不通过手工替换缓存目录回滚。
 - 官方运行镜像内置与 Compose 数据库服务版本一致的 `pg_dump` / `pg_restore`，无需额外安装。
   自行替换 PostgreSQL 版本时，应同步核对备份工具版本。
 - 备份暂存目录为 `host.runtime_data_dir/backup-staging`；Compose 默认对应
@@ -491,7 +577,10 @@ pg_restore --no-owner --no-privileges --password \
 1. 先备份现有数据库，并停止应用；在独立的空数据库中恢复归档，检查数据和迁移版本。
 2. 应用保持停止，离线核对备份设置与记录。禁用快照中的旧计划，处理非终态记录
    （`queued/dumping/uploading/deleting`）、旧调度游标和到期清理条件，再决定哪些记录保留。
-3. 确认不会误执行旧任务或删除恢复前的远端对象后，再启动应用；重新测试 S3 连接并设置计划。
+3. 使用空 Redis 和空插件解包缓存做一次冷启动；逐一核对已启用实例的包摘要/平台、制品接受状态、配置与绑定、账号引用、
+   私有状态 schema/代次，并执行实际插件操作。缺少或损坏必需包体、引用不完整或状态不兼容时，恢复不能
+   记为成功，也不能用相同插件 ID 的其他包替代。
+4. 确认不会误执行旧任务或删除恢复前的远端对象后，再接入业务流量；重新测试 S3 连接并设置计划。
 
 只关闭计划备份不会停止 Worker 的任务恢复和到期删除。无法确认这些记录的影响时，
 不要把恢复后的数据库直接接入运行中的应用。具体处理应根据目标库数据制定，不提供清空生产记录的通用命令。
diff --git a/docs/api.md b/docs/api.md
index 50293a7c0..1a082b124 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -4,11 +4,19 @@
 `backend/crates/gateway-api/src` 中的 router 为准。配置 Codex 请先看 [客户端配置](../deploy/README.md#客户端配置)；
 运行实例是否包含这些功能，应结合其版本和 revision 确认。
 
+| 查找内容 | 入口 |
+| --- | --- |
+| 鉴权与响应 | [公共约定](#1-鉴权与公共约定) · [浏览器会话与 Key 自助页](#4-浏览器认证) |
+| 客户端协议 | [Responses、Images、模型与 Provider 操作](#3-openai-数据面与模型目录) · [额度查询](#api-key-额度查询) |
+| 账号与授权范围 | [账号](#5-账号) · [代理](#独立代理管理--managed-proxies) · [分组](#6-账号分组) · [Client Key](#7-client-key) |
+| 系统与运维 | [健康检查](#2-健康检查) · [运行设置](#8-运行设置) · [备份](#9-备份) · [统计与诊断](#10-dashboard用量与错误) · [版本与更新](#11-版本更新与重启) |
+| 插件 | [安装包与来源](#安装包与来源) · [运行实例](#121-运行实例) · [管理扩展](#122-管理扩展页面与原始-api) |
+
 ## 1. 鉴权与公共约定
 
 ### OpenAI 数据面客户端接口
 
-所有 `/v1/*` 请求都使用管理端创建的 Client Key：
+默认情况下，`/v1/*` 使用管理端创建的 Client Key：
 
 ```http
 Authorization: Bearer sk_...
@@ -17,6 +25,10 @@ Authorization: Bearer sk_...
 自动生成的 Key 保持 `sk_` 格式；迁入的自定义 Key 使用保存时的原值，不限制前缀或固定长度。
 无论格式如何，只有已保存且启用的 Client Key 能通过鉴权。
 
+启用[入口认证插件](../backend/crates/gateway-plugin/sdk/docs/capabilities.md#数据面入口认证)时，
+`Authorization` 可按插件协议校验，并由宿主将外部身份映射到明确绑定的 Client Key。
+账号范围、模型权限、并发和预算仍由该 Key 决定；插件认证不接管管理员或 Key 自助页登录。
+
 Codex 原生生图配置还会携带 `X-OpenAI-Actor-Authorization: proxy-managed`。
 它仅用于客户端识别服务端托管认证，不能代替 Client Key。网关和 OpenAI Provider 都会过滤该请求头，
 上游账号身份只由服务端选中的账号提供；不要把真实账号 token 放进该标记。
@@ -68,7 +80,7 @@ HTTPS 来源以及缺失、`null` 或非法来源保留 `Secure`。`HttpOnly`、
 
 请求无需自带 `x-request-id`；缺失时服务端自动生成 UUID 并在响应头回传同一 request ID。
 `api.request_id_header` 可改变注入与回传的 header 名，管理端鉴权不依赖该名字。
-管理端响应统一带 `Cache-Control: no-store`。
+管理端 JSON 与动态响应统一带 `Cache-Control: no-store`；插件静态资源按下述资源接口的私有缓存策略返回。
 
 配置了 CORS 白名单 origin 时，跨域请求以凭据模式放行，仅允许 `GET`/`POST` 方法和
 `authorization`、`content-type`、`x-api-key` 与 request ID 四个请求头，不使用通配符。
@@ -106,6 +118,7 @@ HTTPS 来源以及缺失、`null` 或非法来源保留 `Secure`。`HttpOnly`、
 | 404 | `40401` | 资源或管理接口不存在 |
 | 409 | `40901` | 资源状态冲突 |
 | 429 | `42901` | 登录尝试过多 |
+| 429 | `42902` | 管理操作请求过于频繁；安全文案可说明具体受限操作 |
 | 500 | `50001` | 服务内部错误 |
 | 502 | `50201` | 上游服务请求失败 |
 | 502 | `50202` | 不可逆上游操作的执行结果未知；刷新状态后再决定是否重试 |
@@ -135,6 +148,7 @@ Codex PAT 验证服务不可用和身份响应无效分别返回 `50301`、`5020
 管理写入不要求客户端提供全局配置版本。会改变路由快照或安全配置的写入由后端在事务内推进
 内部 `config_revision`，并用于快照发布与审计。账号更新和分组查询/写入的部分响应会返回
 `configRevision` 作为已提交事实，但它不是客户端 mutation 的前置条件。
+个别资源另有自己的并发检查，如代理的 `revision` 和插件实例的 `expectedRevision`；按对应接口提交，不与全局版本混用。
 
 ## 2. 健康检查
 
@@ -156,11 +170,35 @@ WebSocket message 和 frame 不设置网关私有长度上限；协议可接受
 | `POST` | `/v1/images/edits` | 通过 OpenAI Provider 发起图像编辑；JSON 请求与响应正文原样转发 |
 | `GET` | `/v1/models` | 返回当前 Client Key 账号范围内各 Provider 的可用公开模型并集；有两种响应形态，见下 |
 | `GET` | `/v1/models/{model_id}` | 返回 OpenAI 兼容的单模型详情 |
+| `POST` | `/v1/providers/{provider}/models/{model}/count_tokens` | 调用指定 Provider/model 声明的精确 Token 计数；请求和响应均为 JSON |
+| `GET` / `POST` | `/v1/providers/{provider}/http/{endpoint}` | 调用指定 Provider 预先声明的固定 HTTP 操作；不是任意 URL 代理 |
 | `GET` | `/v1/usage` | 查询当前 Client Key 的日与周额度，仅使用网关已结算的 USD 账本 |
 
+### Provider 自有操作
+
+这两类 `/v1/providers/*` 路由使用同一 Client Key 鉴权、账号组范围、Provider 账号资格、租约、
+并发/频率准入、请求记录和发送事实。`provider`、`model` 与 `endpoint` 都是已发布目录中的稳定 ID；
+宿主不会接受客户端提供的上游 URL，也不会把下游 Authorization、Cookie、API Key、Host、转发头或
+`Connection` 声明的逐跳头交给插件。上游账号认证只来自宿主选中的账号。
+
+`POST /v1/providers/{provider}/models/{model}/count_tokens` 接受最多 8 MiB 的合法 JSON，且只路由到
+为该模型明确声明 `count_tokens` 的 Provider。Core 不解释或重写请求/响应 JSON，响应必须是插件按其
+声明的本地精确 tokenizer 或上游精确计数合同返回的原始 JSON；没有准确实现时返回不支持，不从 usage
+或字符数推算。响应固定使用 `application/json` 并重算 `Content-Length`。
+
+`GET|POST /v1/providers/{provider}/http/{endpoint}` 只允许 Provider descriptor 中该 endpoint 声明的
+方法；`HEAD`、其他方法、未声明 endpoint 和未声明的方法在出站前拒绝。GET 不能携带正文，POST 正文
+最多 8 MiB；query 作为不透明值交给目标 Provider 再按其固定合同校验，不能改变上游 origin 或路径。
+成功响应由最多 64 KiB 的有序原始片段组成，聚合后最多 8 MiB，字节不经 JSON 转码。宿主保留允许的
+`Content-Type` 和安全业务响应头，移除认证、`Set-Cookie`、`Location`、逐跳、压缩及 framing 头，
+并按最终正文重算 `Content-Length`；缺少媒体类型时使用 `application/octet-stream`。Provider 的结构化
+失败仍沿用数据面错误映射和已确认的上游状态/可见正文边界，不把非 2xx 成功封套当作成功。
+
 Codex 的 review 等子代理请求仍使用 `/v1/responses`，并通过 `x-openai-subagent` 请求头携带子代理类型；
 网关不提供独立的子代理请求路径。
 
+### Responses 请求与传输
+
 `POST /v1/responses` 在鉴权后按 `Content-Encoding` 解压，再解析 JSON；支持单一 `gzip`、
 `deflate`（zlib 封装）和 `zstd`，缺省、空值或 `identity` 直接使用原始正文。gzip 多成员与 zstd
 多帧连续解码，整体展开结果受运行设置 `responsesMaxDecompressedBodyBytes` 约束（默认 64 MiB），
@@ -230,6 +268,8 @@ HTML 或截断正文当作 message。
 提供网关关联 ID，并用 `x-gateway-request-id` 独立标识网关请求。除下述客户端错误兼容与原生续写额度恢复外，
 已经取得的原始上游错误帧不重写。
 
+### 模型目录
+
 `GET /v1/models` 默认返回 OpenAI 兼容列表 `{"object": "list", "data": [...]}`；请求携带非空
 `client_version` query 参数（Codex 客户端）时改为返回 Codex 专用目录合同 `{"models": [...]}`。
 
@@ -263,6 +303,8 @@ Codex 专用目录中的 `context_window` 与 `max_context_window` 分别表示
 覆盖这些值。Codex 客户端配置 `model_context_window` 后，按该值与非空 `max_context_window` 的较小值
 使用窗口；上限为空时保留客户端本地值。xAI 目录只声明一个窗口，其 Provider 继续以该值作为客户端覆盖上限。
 
+### 透传与错误恢复
+
 OpenAI 路径保留客户端 Responses wire 语义：请求 body 的未知字段和字段顺序保持不变（受控模型
 映射除外），HTTP SSE 与 WebSocket 的上游业务事件除下述客户端错误兼容外按原始字节转发，
 response ID 按 opaque 值处理而不假设 UUID 或固定长度；除客户端错误兼容与原生续写额度恢复外，
@@ -308,9 +350,10 @@ OpenAI 选号阶段确认本次可选账号全部额度耗尽时，HTTP 返回 `
 
 ### API Key 额度查询
 
-`GET /v1/usage` 使用 `Authorization: Bearer <Client Key>`，不接受会话 Cookie、管理 API Key 或查询参数。
-只返回该 Key 的日与周额度，不包含明文 Key、账号资料或其他 Key 的数据。查询不会调用上游、扣费、占用推理并发/RPM，
-也不会更新最近使用时间或开启预算窗口；额度耗尽后仍可查询。
+`GET /v1/usage` 使用同一数据面入口认证，默认传入 `Authorization: Bearer <Client Key>`；
+启用入口认证插件时可查询其映射 Key 的额度。不接受会话 Cookie、管理 API Key 或查询参数。
+只返回当前 Key 的日与周额度，不包含明文 Key、账号资料或其他 Key 的数据。查询本身不执行模型推理、扣费或占用推理并发/RPM，
+不更新最近使用时间或开启预算窗口；额度耗尽后仍可查询。已配置的入口认证和 request 中间件仍按授权执行。
 
 成功响应直接返回以下 JSON，不使用管理接口信封，所有响应带 `Cache-Control: no-store`：
 
@@ -412,12 +455,13 @@ config 返回 `{ name, plaintextKey }`，仅读取服务端会话绑定的当前
 
 ## 5. 账号
 
-账号 API 使用统一路由，不存在 Provider Instance 或 Provider 专属账号路由。需要 Provider 的请求只接受
-`provider: "openai" | "xai"`。
+账号 API 使用统一路由，不存在 Provider Instance 或 Provider 专属账号路由。`provider` 使用 Provider ID，
+包括内置 `openai`、`xai` 和插件平台；需要调用 Provider 的操作须由当前已发布的能力支持。
 
 | 方法 | 路由 | 主要 query/body | 说明 |
 | --- | --- | --- | --- |
 | `GET` | `/api/admin/accounts` | `page`、`pageSize`、`provider`、`groupId`、`search`、`status`、排序字段 | 分页查询账号与汇总 |
+| `GET` | `/api/admin/accounts/providers` | 无 | 查询已发布 Provider 的凭据能力、输入 schema 与登录完成方式 |
 | `GET` | `/api/admin/accounts/detail` | `accountId` | 查询账号详情、额度和本地用量 |
 | `GET` | `/api/admin/accounts/export` | `accountIds`、`confirm=export_sensitive_accounts` | 显式导出最多 200 个账号的敏感 Provider 文档 |
 | `POST` | `/api/admin/accounts/import` | `{ provider, data, settings?, outboundProxyId? }` | 导入或按上游身份更新账号，可同时应用调度、分组设置与默认代理 |
@@ -427,30 +471,35 @@ config 返回 `{ name, plaintextKey }`，仅读取服务端会话绑定的当前
 | `POST` | `/api/admin/accounts/import-tasks/stop` | `{ taskId }` | 跳过未开始的条目，已开始的条目继续完成 |
 | `POST` | `/api/admin/accounts/refresh` | `{ accountId }` | 手工刷新 OAuth credential（`idToken` / `accessToken` / `refreshToken`），不刷新额度 |
 | `POST` | `/api/admin/accounts/recover` | `{ accountId }` | 停用账号只启用调度；已启用账号强制清除本地错误/额度/cooldown 事实，不访问上游 |
-| `POST` | `/api/admin/accounts/rotate` | OpenAI rotation 字段 | 更新指定 OpenAI 账号的 OAuth token 或 API Key 上游设置 |
-| `POST` | `/api/admin/accounts/update` | `{ accountId, enabled, concurrencyLimit, weight, groupIds, notes?, modelAccess?, outboundProxyId?, outboundProxyUrl? }` | 一次更新账号备注、调度状态、并发上限（`null` 表示继承运行参数）、权重（1–100）、所属分组与出站代理 |
+| `POST` | `/api/admin/accounts/update` | `{ accountId, enabled, concurrencyLimit, weight, groupIds, notes?, modelAccess?, outboundProxyId?, outboundProxyUrl?, connection? }` | 一次更新账号设置；`connection` 仅用于编辑 OpenAI API Key 账号的连接地址、传输方式和密钥，见下文 |
 | `POST` | `/api/admin/accounts/batch-update` | `{ accountIds, enabled?, concurrencyLimit?, weight?, groupIds?, modelAccess?, outboundProxyId?, outboundProxyUrl? }` | 一次事务更新所选账号；仅修改提供的字段，至少提供一项修改 |
 | `POST` | `/api/admin/accounts/delete` | `{ provider, accountIds }` | 批量删除 1–200 个账号 |
-| `GET` | `/api/admin/accounts/quota` | `accountId` | 读取当前额度，不强制访问上游 |
+| `GET` | `/api/admin/accounts/quota` | `accountId` | 读取当前额度，不强制访问上游；Provider 未提供额度能力时返回空额度投影 |
 | `GET` | `/api/admin/accounts/quota-forecast` | `accountId` | 按需读取周/月容量预测、源窗口剩余估算与采样依据，不刷新上游额度 |
 | `POST` | `/api/admin/accounts/quota/refresh` | `{ accountId }` | 访问 Provider 并刷新额度，同时同步额度所属状态 |
-| `GET` | `/api/admin/accounts/personal-info` | `accountId` | 按需汇聚 OpenAI/Codex 官方个人资料、累计活动与订阅信息，不更新额度或 credential |
-| `GET` | `/api/admin/accounts/reset-credits` | `accountId` | 查询 OpenAI 上游主动额度重置卡，不读取本地库存 |
-| `POST` | `/api/admin/accounts/reset-credits` | `{ accountId, creditId?, redeemRequestId }` | 使用 UUIDv4 幂等键消费一张 OpenAI 上游重置卡 |
+| `GET` | `/api/admin/accounts/personal-info` | `accountId` | 按需汇聚 Provider 上游个人资料、累计活动与订阅信息，不更新额度或 credential |
+| `GET` | `/api/admin/accounts/profile-avatar` | `accountId`、可选 `version` | 返回支持头像能力的 Provider 字节流，需要管理员会话；`version` 仅区分浏览器缓存 |
+| `GET` | `/api/admin/accounts/reset-credits` | `accountId` | 查询支持该能力的 Provider 重置卡，不读取本地库存 |
+| `POST` | `/api/admin/accounts/reset-credits` | `{ accountId, creditId?, redeemRequestId }` | 使用 UUIDv4 幂等键消费一张 Provider 重置卡 |
 | `GET` | `/api/admin/accounts/models` | `accountId` | 优先读取该 Provider + 套餐的模型 cache，缺失时有限实时拉取 |
 | `POST` | `/api/admin/accounts/models/refresh` | `{ accountId }` | 强制拉取最新模型并覆盖 cache |
 | `GET` | `/api/admin/accounts/connection-test` | `accountId`、`modelId` | 通过 SSE 返回实时连接测试事件，不作为业务 Responses 用量记录 |
-| `POST` | `/api/admin/accounts/oauth/start` | `{ provider, name, accountId?, outboundProxyId?, outboundProxyUrl? }` | 创建 OpenAI 或 xAI OAuth flow；`accountId` 表示重新授权 |
+| `POST` | `/api/admin/accounts/oauth/start` | `{ provider, name, input?, accountId?, outboundProxyId?, outboundProxyUrl? }` | 为支持登录的 Provider 创建 flow；`accountId` 表示重新授权 |
 | `POST` | `/api/admin/accounts/oauth/complete` | `{ provider, flowId, callbackUrl, settings? }` | 消费 OAuth callback；首次授权可附带账号设置，重新授权保留原设置 |
+| `POST` | `/api/admin/accounts/oauth/poll` | `{ provider, flowId, callbackUrl?, settings? }` | 轮询支持该能力的 Provider 登录，返回待确认或批量完成 |
 
 账号列表支持以下稳定值：
 
-- `provider`: `all`、`openai`、`xai`；
+- `provider`: Provider ID（如 `openai`、`xai` 或插件平台 ID），省略或空值表示不过滤；
 - `groupId`: 分组 ID、`ungrouped`，或省略以不过滤；
 - `status`: `normal`、`quota_exhausted`、`rate_limited`、`disabled`、`error`；
 - `sortBy`: `email`、`status`、`planType`、`usage`、`lastUsedAt`、`expiresAt`；
 - `sortDirection`: `asc`、`desc`。
 
+账号列表的 `data.providers` 为全部已保存账号的 Provider ID 去重排序列表，不受当前筛选、分页或插件启停影响。
+没有账号时返回空数组；创建账号时可用的平台及操作另由 `/api/admin/accounts/providers` 的能力描述确定。
+显式 `provider` 按 ID 匹配，包括名为 `all` 的平台。既有调用方若使用 `provider=all` 表示全部平台，须改为省略该参数。
+
 账号限流详情在 `quota` 中返回：`rateLimitReason` 为 `upstream_rate_limit`（上游临时限流）、
 `capacity_freeze`（容量错误触发自动冻结）或 `null`。`recoveryProbeRequired` 表示解除冻结是否需要成功探测；
 此时 `rateLimitedUntil` 是最早探测时间，到期后仍保持 `rate_limited`，直到探测成功或手动恢复。
@@ -600,7 +649,23 @@ JSON 文件按 Provider 文档分项，不拆解内部代理引用或改变 Prov
 终态结果保留 1 小时后自动清理。服务重启会丢失任务与未执行输入，已提交的账号不受影响；
 任务记录仍在保留期内时，可通过列表接口查询当前管理员的任务及进度。
 
-### 账号导入与 OAuth
+### 账号能力、导入与 OAuth
+
+`GET /api/admin/accounts/providers` 返回 `{ provider, credentials }` 数组，读取同一已发布代次，
+需要管理员身份。`credentials.import` 为输入对象的 JSON Schema，`null`
+表示不支持；`refresh`、`export` 为支持标记。`login` 为 `null` 或
+`{ inputSchema, completion: "callback" | "poll" }`，分别使用授权完成或轮询入口。
+描述只表示 Provider 实现了哪些操作；账号类型、账号范围和权限仍由实际操作校验。停用的插件从该目录
+撤下，但既有账号与分组关系保留。响应不包含实例配置、凭据或登录输入。
+
+敏感账号导出要求所选全部 Provider 当前已注册且声明 `credentials.export`。混合选择中只要有一个
+不支持导出的 Provider，整个请求都会在读取或解密任何凭据前拒绝，不返回部分导出结果。
+
+账号列表及额度详情中的 `capabilities` 则针对当前账号，包含布尔字段 `quota`、`quotaRefresh`、`profile`、
+`subscription`、`avatar`、`resetCredits` 和 `consumeResetCredit`，分别表示额度读取、额度刷新、资料、订阅、
+头像、重置卡查询及消费能力。服务端结合 Provider 声明、账号认证类型和插件账号授权生成，客户端据此显示
+操作；只读与写入能力分别判断，不按 Provider 名称推测。插件撤下后保留账号，但这些能力为 `false`。
+能力是查询时的投影，不能代替实际操作的权限校验，也不保证上游可用。
 
 导入的 `data` 必须是 JSON object，Admin API 请求上限为 64 MiB；Provider 可以收紧限制，
 当前 xAI 导入上限为 16 MiB。内部 schema 由目标 Provider 独占解释：
@@ -638,7 +703,8 @@ API Key 账号使用以下独立凭据形态：
 `transport` 可省略（默认 `http`）或设为 `prefer_websocket`。API Key 使用 Bearer 认证与普通 JSON，
 不携带 OAuth Cookie 或 ChatGPT 身份。上游模型列表使用标准 `/models` 格式，按账号和凭据版本隔离；
 目录用于模型发现，不作为能力白名单，未列出的模型仍交由上游判断。
-API Key 每次导入创建独立账号；更新已有账号使用 `rotate`。导出会显式包含密钥，沿用敏感导出的确认合同。
+API Key 每次导入创建独立账号；更新已有账号使用 `/api/admin/accounts/update` 的 `connection` 字段。
+导出会显式包含密钥，沿用敏感导出的确认合同。
 
 sub2api 的 `platform=openai`、`type=apikey` 使用 `credentials.base_url` / `credentials.api_key`；
 导入时按其端点规则将服务根、版本前缀或完整 `/responses` 地址转换为 API 前缀，缺省地址为官方 `/v1`。
@@ -672,7 +738,7 @@ RT-only 使用同一形状，只提交 `refreshToken`。不得把真实 token 
 `weight` 为 1–100，`groupIds` 为完整分组集合。设置应用于本次导入的全部账号，包括匹配到的已有账号，
 与凭据在同一事务内提交；分组不存在时整次回滚。省略 `settings` 时新账号使用默认设置并保持未分组，
 已有账号保留原有分组、权重与并发设置。可选 `notes` 与编辑备注使用相同的校验和清空语义，省略或 `null` 保留已有备注；
-管理端新建表单留空时省略 `notes`。重新授权不接受 `settings`，credential refresh 和未携带 `settings` 的 rotation 保留账号设置。
+管理端新建表单留空时省略 `notes`。重新授权不接受 `settings`，凭据刷新保留账号设置。
 
 账号列表的每个 item 返回轻量 `groups: [{ id, name, enabled }]`。
 
@@ -681,23 +747,31 @@ OpenAI 的 CPR 导出保持 OAuth 账号的既有 token 与过期时间字段。
 旧文档不带此字段时，新账号默认 `all`，已有账号保留原值；凭据刷新、重新授权和目录刷新均保留政策。
 sub2api 的 `credentials.model_mapping` 不转换为本项目的账号模型限制。
 
-OpenAI rotation 请求字段为：
+编辑 OpenAI API Key 账号时，在 `POST /api/admin/accounts/update` 的账号设置中附带 `connection`：
 
 ```json
 {
-  "provider": "openai",
   "accountId": "acct_...",
-  "idToken": "...",
-  "accessToken": "...",
-  "refreshToken": "..."
+  "enabled": true,
+  "concurrencyLimit": null,
+  "weight": 1,
+  "groupIds": [],
+  "connection": {
+    "baseUrl": "https://api.example.com/v1",
+    "transport": "http",
+    "apiKey": "..."
+  }
 }
 ```
 
-API Key rotation 使用 `{ provider: "openai", accountId, baseUrl, transport, apiKey?, settings? }`。
-省略 `apiKey` 保留当前密钥，空字符串无效；账号 ID 和认证类型不能通过轮换转换。
-rotation 可选携带 `settings`，字段与 `POST /api/admin/accounts/update` 相同，其中 `accountId` 必须与外层一致。
-凭据与设置在同一事务中保存，任一校验或持久化失败均不落库；省略 `settings` 保留现有分组、调度等设置。
-`GET /api/admin/accounts/detail` 对 API Key 账号额外返回 `credentialConfiguration: { base_url, transport }`，不回显密钥。
+`connection.transport` 支持 `http`、`prefer_websocket`。省略 `connection` 时只更新账号设置；
+省略 `connection.apiKey` 保留当前密钥，空字符串无效。连接设置只适用于现有 OpenAI API Key 账号，
+不能修改账号 ID、Provider 或认证类型，也不接受 OAuth token 或通用凭据文档。
+凭据与设置在同一事务中保存，任一校验或持久化失败均不落库。
+`GET /api/admin/accounts/detail` 对 API Key 账号额外返回 `credentialConfiguration: { base_url, transport }`；
+声明连接设置能力的插件 Provider 可返回其 rotate schema 中明确公开的标量字段。字段投影
+不超过 64 KiB，不接受引用、组合或条件 schema，不回显密钥、`writeOnly` 字段、
+原始插件配置或 secret。不适用的账号省略该字段。
 更新会推进凭据 revision 并失效目录与连接；旧版本会话不可静默续接到新上游。
 
 OAuth start 使用：
@@ -710,10 +784,26 @@ OAuth start 使用：
 }
 ```
 
+可选 `input` 为登录表单对象，省略时使用 `{}`，编码后最多 64 KiB。插件按其声明的登录 schema
+校验，失败时不会发起插件登录调用，也不返回包含输入值的校验错误。OpenAI/xAI 的浏览器授权流程不接收
+额外输入。该对象只传给当前登录准备调用；宿主持久化的授权目标不保存它，插件需要跨步骤保留的状态由
+插件显式返回，再进入既有加密临时存储。
+
 重新授权已有账号时，start 请求仍携带 `provider` 和展示用 `name`，只额外提供目标 `accountId`；
 客户端不得提交 `credentialRevision`、旧 token 身份或其他并发控制字段。complete 请求也不重复提交
 `accountId`，后端通过 `flowId` 中保存的目标绑定完成授权。
 
+声明登录轮询能力的插件使用 `POST /api/admin/accounts/oauth/poll` 接续 start 返回的 `flowId`。
+待确认时返回 `{ status: "pending", retryAfterMs }`，完成时返回 `{ status: "complete", accountIds }`，
+两种结果均为 HTTP 200；一次登录可以创建多个账号，全部账号在同一事务提交。`callbackUrl` 可省略，
+需要浏览器回调的插件由该字段接收返回值；`settings` 只允许用于首次创建。
+流程只允许发起它的管理员身份继续。尚未完成的流程过期后需重新发起；插件配置、制品或权限发生变化后，
+也需重新发起登录，宿主重启但上述内容不变时可继续。插件私有登录状态不返回客户端。
+
+账号提交成功后，`complete` 和 `poll` 保留 24 小时的完成结果。同一管理员使用相同 `provider`、`flowId`
+重试时返回原账号结果，不再执行授权或更新凭据；新提交的 `callbackUrl` 和 `settings` 不会再次应用。
+恢复完成结果不要求插件仍处于启用状态。`complete` 只返回单账号结果，多账号授权必须使用 `poll`。
+
 ### OpenAI 身份、额度与状态
 
 - OAuth 文件导入接受 camelCase 与 snake_case 的三个 token 字段，内部统一保存为
@@ -820,11 +910,12 @@ OAuth 账号的额度、个人资料、订阅与重置卡请求先使用 `openai
 回退后的响应或错误作为最终结果，不以原来的 404 覆盖。重置卡消费回退复用原始请求体和幂等键，
 传输失败仍按消费结果不明确处理。API Key 账号不会因此获得 OAuth 账号能力，也不会改变推理请求的目标地址。
 
-### OpenAI 个人信息
+### 账号个人信息
 
-`GET /api/admin/accounts/personal-info?accountId=...` 需要管理员会话，当前由 OpenAI/Codex OAuth
-账号提供。后端并发读取资料统计与订阅，一次返回；每次请求均重新查询，除上述 404 路由回退外不自动重试，
-不刷新 credential，不读取本地 usage/billing 记录，也不缓存或估算统计结果。
+`GET /api/admin/accounts/personal-info?accountId=...` 需要管理员会话，由支持对应能力的 Provider
+提供，包括 OpenAI/Codex OAuth 账号与声明资料/订阅操作的插件 Provider。后端并发读取资料统计与订阅，
+一次返回；每次请求均重新查询，不刷新 credential，不读取本地 usage/billing 记录，也不缓存或估算统计结果。
+OpenAI 的查询沿用上述 404 路由回退；插件查询需要 `profile` 用途的账号与出站授权。
 
 响应 `data` 包含：
 
@@ -852,7 +943,7 @@ OAuth 账号的额度、个人资料、订阅与重置卡请求先使用 `openai
 
 #### 订阅信息
 
-后端使用当前凭据、绑定的上游账号 ID 和账号出站代理访问 `/backend-api/subscriptions?account_id=...`，
+OpenAI 使用当前凭据、绑定的上游账号 ID 和账号出站代理访问 `/backend-api/subscriptions?account_id=...`，
 不枚举其他账号，不返回上游订阅 ID 或原始响应。
 
 `subscription` 为 `null`（未获得可用订阅周期），或包含以下字段：
@@ -866,14 +957,15 @@ OAuth 账号的额度、个人资料、订阅与重置卡请求先使用 `openai
 | `billingCurrency` | string 或 null | 上游计费币种 |
 | `observedAt` | RFC 3339 字符串 | 本次查询时间 |
 
-订阅不写入额度快照或数据库，不参与账号状态或调度；查询含 404 回退共用最多 5 秒预算，响应最多 64 KiB。
+订阅不写入额度快照或数据库，不参与账号状态或调度；OpenAI 查询含 404 回退共用最多 5 秒预算，响应最多 64 KiB。
 上游失败或未提供有效周期时返回未知，不据此标记免费、过期或禁用；请求期间账号身份或 credential
 revision 变化时丢弃结果。
 
-### OpenAI 主动额度重置卡
+### 主动额度重置卡
 
-`GET /api/admin/accounts/reset-credits?accountId=...` 每次都查询 OpenAI 上游；后端不把卡片列表写入
-PostgreSQL 或 Redis。
+`GET /api/admin/accounts/reset-credits?accountId=...` 每次都查询对应 Provider；后端不把卡片列表写入
+PostgreSQL 或 Redis。OpenAI OAuth 与声明该能力的插件可使用，账号视图分别以 `resetCredits` 和
+`consumeResetCredit` 表示查询和消费能力。
 
 查询响应：
 
@@ -907,7 +999,11 @@ PostgreSQL 或 Redis。
 ```
 
 消费响应只返回上游结果 `code` 和可选 `credit`。消费端确认成功后应重新 GET 卡片列表，并显式调用
-`POST /api/admin/accounts/quota/refresh` 回读官方额度；不得直接改写本地 `resetAt`。xAI 不支持该能力。
+`POST /api/admin/accounts/quota/refresh` 回读上游额度；未提供 `quotaRefresh` 能力时不发起该查询。
+不得因为消费成功直接改写本地 `resetAt` 或解除冻结。xAI 不支持该能力。
+
+插件的已确认拒绝与凭据需刷新是完整业务结果；消费调用超时、进程退出、协议损坏或结果无法通过校验时，
+按结果未知处理。消费期间账号身份或凭据版本变化也返回结果未知，不将旧结果套用到新绑定账号。
 
 ## 6. 账号分组
 
@@ -951,16 +1047,19 @@ HTTP 请求头及新建 WS 的握手提示按当时的最终出站档位构造
 | `POST` | `/api/admin/client-keys/delete` | `{ id }` | 删除 |
 
 创建字段为 `name`、可选 `label`、`groupIds`、`maxConcurrency`、`requestsPerMinute`、可选
-`dailyLimitUsd`、`weeklyLimitUsd`、`customKey`、`openaiClientProfileOverride` 和 `xaiClientProfileOverride`。更新请求携带 `id`，不接受 `customKey`。
+`dailyLimitUsd`、`weeklyLimitUsd`、`customKey` 和 `providerRequestProfileOverrides`。更新请求携带 `id`，不接受 `customKey`。
 `groupIds` 必须显式提交：空数组派生 `routingScope: "all"`，非空数组派生
 `routingScope: "groups"`。响应同时返回分组引用 `groups`，以及从当前有效账号池派生、仅供展示的
 `providerKinds`。创建和 reveal 响应会返回完整明文 Key，调用方
 必须立即安全保存。
 
-`openaiClientProfileOverride` 为完整的 [OpenAI 客户端身份](#openai-上游客户端身份)对象或 `null`，列表也返回该字段。
-`xaiClientProfileOverride` 对应完整的 [xAI 客户端身份](#xai-上游客户端身份)，两者分别覆盖所属 Provider，列表同时返回。
-创建时省略或 `null` 表示跟随通用设置；更新时省略保留现值，显式 `null` 才清除覆盖。
-独立配置整体覆盖通用设置，不逐字段继承；切换全局配置不会影响独立 Key。
+`providerRequestProfileOverrides` 按 Provider ID 保存身份选择，列表返回同名对象。创建时各项为完整配置对象，
+未提供的 Provider 跟随通用设置；更新时省略某项保留原值，设为 `null` 清除该项覆盖。最多 256 项，每项最多 64 KiB。
+独立配置整体覆盖通用设置，不逐字段继承；切换全局配置不会影响独立 Key。目录与选择规则见 [Provider 客户端身份](#provider-客户端身份)。
+
+兼容字段 `openaiClientProfileOverride` 和 `xaiClientProfileOverride` 分别对应上述映射中的 `openai`、`xai`。
+创建时省略或 `null` 表示无覆盖；更新时省略保留、`null` 清除。与通用字段同时提交时必须一致，否则拒绝整个请求；
+响应中的兼容字段从同一映射派生，不是第二份配置。
 
 密钥列表的 `search` 仅匹配名称和标签，不匹配密钥值或可见前缀；搜索不区分大小写，使用字面量前缀匹配。
 创建和更新时去除名称首尾空白，并按忽略大小写、首尾空格的名称查重，重复返回 `409`。
@@ -1025,12 +1124,11 @@ HTTP 返回 `429`，`error.code` 为 `key_daily_budget_exceeded` 或 `key_weekly
 | 方法 | 路由 | 说明 |
 | --- | --- | --- |
 | `GET` | `/api/admin/settings` | 读取运行设置 |
-| `POST` | `/api/admin/settings/update` | 原子替换全部运行设置 |
+| `POST` | `/api/admin/settings/update` | 原子保存运行设置；身份配置按显式提供的 Provider 项更新 |
 | `GET` | `/api/admin/settings/client-downloads/codex-desktop/windows` | 提取 Codex Desktop Windows 离线安装直链；`refresh=true` 强制刷新进程内短缓存 |
-| `GET` | `/api/admin/settings/client-profiles/openai` | 读取六个预设、自动更新可用状态和 `globalConfiguration` |
-| `POST` | `/api/admin/settings/client-profiles/openai/preview` | body 为 `{ configuration }`，值为完整身份对象或 `null`（解析当前通用设置）；只预览，不保存 |
-| `GET` | `/api/admin/settings/client-profiles/xai` | 读取 Grok CLI 默认字段 `defaults` 和 `globalConfiguration` |
-| `POST` | `/api/admin/settings/client-profiles/xai/preview` | body 为 `{ configuration }`，值为完整 xAI 身份对象或 `null`（解析当前通用设置）；只预览，不保存 |
+| `GET` | `/api/admin/settings/client-profiles` | 返回 `{ providers: [Provider ID] }`，列出当前支持客户端身份配置的 Provider |
+| `GET` | `/api/admin/settings/client-profiles/{provider}` | 读取该 Provider 的可选配置和 `globalConfiguration` |
+| `POST` | `/api/admin/settings/client-profiles/{provider}/preview` | `{ configuration }`，完整配置对象或 `null`（解析当前通用设置）；只预览，不保存 |
 | `GET` | `/api/admin/settings/admin-api-key` | 只返回管理 API Key 是否存在 |
 | `POST` | `/api/admin/settings/admin-api-key/delete` | 删除管理 API Key |
 | `POST` | `/api/admin/settings/admin-api-key/regenerate` | 重新生成并一次性返回完整管理 API Key |
@@ -1038,7 +1136,9 @@ HTTP 返回 `429`，`error.code` 为 `key_daily_budget_exceeded` 或 `key_weekly
 设置更新字段包括：
 
 ```text
+providerRequestProfiles
 openaiClientProfile
+xaiClientProfile
 requestLocationEnabled
 requestLocation
 modelMappings
@@ -1117,8 +1217,9 @@ OpenAI 长上下文为输入超过 272000 Token，xAI 为输入达到 200000 Tok
 `multiplierBps` 为 0～1000000 的整数，10000 表示 1 倍、0 表示本地估算为零，最大 100 倍。
 它作用于本地费用及对应明细，独立于服务档位；缺少计价依据的请求即使倍率为零仍然是费用未知。
 
-`provider` 为 `openai` 或 `xai`；`models` 为 1～500 个模型 ID，每个 ID 为 1～128 字节且不含空白、
-控制字符。`change` 为以下形式之一：
+`provider` 必须是 `GET` 返回的 `defaults` 中当前已注册的 Provider；除内置 `openai`、`xai` 外，
+当前注册的插件 Provider 也会出现在该目录中。`models` 为 1～500 个模型 ID，每个 ID 为
+1～128 字节且不含空白、控制字符。`change` 为以下形式之一：
 
 - `{ "action": "replace", "pricing": { "multiplierBps": 12500, "bands": { ... } } }`：替换选中模型的人工
   配置，未提供档位重新继承来源；内置和同步均未登记的模型必须包含 `standard`。
@@ -1136,10 +1237,26 @@ models.dev 同步只导入可表示为当前文本 Token 计价的 OpenAI/xAI 
 及所有人工单价与倍率保持不变。选中的已同步模型若不再出现在来源价目中，则移除其来源层，恢复内置价格；
 没有内置价目的模型变为未配置。
 
+### Provider 客户端身份
+
+`providerRequestProfiles` 是按 Provider ID 索引的通用配置对象，最多 256 项、每项最多 64 KiB。
+更新时省略某项保留原值，对象替换该项，`null` 删除显式选择并使用 Provider 默认值；不清除其他 Provider 的配置。
+配置内容由对应 Provider 校验，不包含账号凭据。Key 可通过 `providerRequestProfileOverrides` 整体覆盖所属 Provider 的选择。
+
+`openaiClientProfile` 与 `xaiClientProfile` 是同一映射的兼容字段：省略保留，不能显式提交 `null`；
+与通用字段同时提供时必须一致，否则整次更新拒绝。读取响应从映射派生这两个字段，不维护平行状态。
+
+先查询 Provider 目录，再读取选项与预览。OpenAI 选项返回六个 `presets`，xAI 返回 `defaults`；
+插件 Provider 返回 `presets: [{ id, label, description, configuration }]` 和 `defaultConfiguration`，
+宿主均补充 `globalConfiguration`。插件配置只能选用声明的完整 `configuration`，不能自行拼接未知字段。
+插件预览包含 `configuration`、`source`、`product`、`version`、`build`、`target`、`userAgent`、`attributes`、
+`verifiedAt` 和 `release`；未知资料保持缺失，不代表身份已经核验。插件开发合同见
+[请求画像目录](../backend/crates/gateway-plugin/sdk/docs/capabilities.md#请求画像目录)。
+
 ### OpenAI 上游客户端身份
 
 `openaiClientProfile` 保存通用选择，首次默认 `MacOS · Desktop · 自动最新`。
-设置更新省略该字段保留现值，不能提交 `null`。初始化不读取 YAML 身份字段；内置默认只用于初始化，不形成第三层运行时回退。
+兼容字段的更新语义见上节。初始化不读取 YAML 身份字段。
 该配置作用于 Client Key 的 OpenAI 模型请求与原生模型目录，适用于 HTTP/SSE、WebSocket、Images 和 Search。
 不改变 xAI、入站客户端版本门禁、账号认证或后台 Desktop 专属操作。
 
@@ -1212,6 +1329,8 @@ User-Agent 使用 `grok-shell/<版本> (<系统>; <架构>)`，其中 `arm64` 
 观测在途峰值的 80%（下限 2，只降不升）。这会持久修改账号并发设置；跟随全局默认的账号也会设为独立上限，
 解冻后不自动恢复，管理员可手动改回。
 
+### Windows 客户端下载
+
 Windows 离线包接口固定解析 Microsoft Store Product ID `9PLM9XGG6VKS` 的 Retail 包，不接受调用方提供
 产品 ID、上游地址、ring 或文件名。后端只返回通过包名、架构、Microsoft CDN host/path、scheme 和失效
 时间校验的 `x64` / `arm64` MSIX 直链，不代理安装包字节。Store 内容通道返回 HTTP/80 临时地址时保留
@@ -1324,6 +1443,7 @@ errorCode, errorMessage, startedAt, completedAt, expiresAt, createdAt, updatedAt
 | --- | --- | --- |
 | `GET` | `/api/admin/dashboard/summary` | Dashboard 汇总；支持 `kind`、`startTime`、`endTime` |
 | `GET` | `/api/admin/dashboard/trend` | Dashboard 趋势；`kind=usage|latency|errors` |
+| `GET` | `/api/admin/usage/providers` | 时间范围内请求及错误记录的 Provider ID 去重排序列表 |
 | `GET` | `/api/admin/usage/records` | 请求记录分页列表 |
 | `GET` | `/api/admin/usage/records/detail` | 按 `id` 查询请求详情 |
 | `GET` | `/api/admin/usage/records/summary` | 当前筛选条件的请求汇总 |
@@ -1339,6 +1459,11 @@ Dashboard 的 `capacityInfo.maxConcurrentPerAccount` 为默认账号并发上限
 request/response/upstream ID、outcome 与搜索文本。诊断 `dimension` 可取 `model`、`account`、
 `apiKey`、`provider`、`transport`、`failureClass`、`status`。
 
+`/api/admin/usage/providers` 仅接受可选的 `startTime`、`endTime`，返回 `data: string[]`，没有记录时为空数组。
+时间使用 RFC 3339 格式，包含起点、不包含终点；默认终点为当前时间、起点为终点前 7 天，范围须为正且不超过 366 天。
+平台集合包含按开始时间命中的请求、按完成时间命中的请求错误，以及按发生时间命中的运维错误，忽略尚未确定的平台。
+该集合来自历史记录，不受当前平台选择、分页、账号删除或插件停用影响，不表示平台当前可执行或可创建账号。
+
 管理端请求列表及 Dashboard 最近请求中的 `accountNotes` 为账号当前备注，按内部账号 ID 关联。
 备注不写入请求历史快照；无备注或账号已删除时返回 `null`，修改备注不改变历史请求的账号归属。
 
@@ -1446,9 +1571,343 @@ Key 已删除或未关联时为 `null`，不影响记录返回，不包含密钥
 执行，结果通过 `/update/status` 的 `operation` 查询：`status` 为 `idle`、`running`、`succeeded` 或 `failed`，
 终态包含 `finishedAt`，失败原因在 `error` 中。SSE 的 `operationId` 用于关联进度；终态事件发出前状态已落盘。
 连接中断不取消已受理任务；响应丢失时先查询状态，不自动重复提交。打开更新页面时也会恢复最近一次任务。
+下载并解包后，Admin 会以目标发行清单声明的宿主插件合同检查每个启用实例的精确制品；回滚则对备份发行清单
+执行同一检查。两条路径都会在文件交换前后复核同一全局插件配置版本。任一实例不兼容、制品缺失、请求取消或
+配置并发变化都会失败；已交换的二进制、Web 资源和官方插件目录会成组恢复。预检不会自动停用实例、切换插件
+版本或增加权限。
 
 状态响应的 `currentVersion` 表示已安装文件的版本，运行中的版本仍以 `/version` 为准。
 `needRestart=true` 表示成功安装的版本尚未在当前进程生效，此时应调用重启接口，不能重复发起更新。
 Host 关闭或任务取消会记录失败终态；状态查询会收敛无执行锁的遗留 `running`。
 异常退出留下的锁仍遵循 30 分钟过期规则，未过期前不会抢占其他进程的操作。
 实例升级和仓库发版见 [部署文档](../deploy/README.md#镜像升级与源码构建)。
+
+## 12. 插件管理
+
+除明确标注的公开入口外，以下接口需要管理身份。图标读取及 12.2 中标注的原始响应接口直接返回资源、插件响应
+或模型响应，其余接口使用统一管理响应信封。制品按摘要接受其不可变访问域；首次安装某个插件时会尝试创建默认配置，
+配置完整则启用，缺少必填项则保留为待配置。操作流程见 [插件使用](plugins.md)，开发合同见
+[SDK](../backend/crates/gateway-plugin/sdk/README.md)。不提供官方商店或第三方市场订阅接口。
+
+### 安装包与来源
+
+| 方法 | 路径 | 行为 |
+| --- | --- | --- |
+| GET | `/api/admin/plugins/artifacts` | 列出制品的 `metadata`、固定 `source`、`installedAt` 与可为 `null` 的 `acceptedAt` |
+| GET | `/api/admin/plugins/artifacts/{sha256}/icon?theme=light\|dark` | 管理身份；按不可变制品摘要读取已校验图标；无图标返回 404 |
+| POST | `/api/admin/plugins/artifacts/upload` | 上传原始 tar.gz 包体，最多 32 MiB；查询参数 `sha256` 必须固定已解析的包；接受访问域并完成安装 |
+| POST | `/api/admin/plugins/artifacts/upload/verify` | 同样接收原始包体，只读解析并校验，返回 `metadata` 与 `source`，不安装 |
+| POST | `/api/admin/plugins/artifacts/install` | 从 URL 或固定 GitHub Release 下载、校验，接受访问域并完成安装 |
+| POST | `/api/admin/plugins/artifacts/verify` | 按远程来源只读解析并校验完整包，返回 `metadata` 与固定 `source`，不持久化或启动插件 |
+| POST | `/api/admin/plugins/artifacts/accept` | 严格请求 `{ "sha256": "<小写 SHA-256>" }`，接受已导入制品的访问域并完成安装 |
+| POST | `/api/admin/plugins/artifacts/delete` | 请求 `{ "sha256": "<小写 SHA-256>" }`，删除未被引用的制品 |
+| POST | `/api/admin/plugins/releases/query` | 查询指定 GitHub 仓库的最新稳定版或明确 tag |
+| POST | `/api/admin/plugins/updates/check` | 按插件已保存的来源和策略查询 Release，只读，不下载或切换实例 |
+| GET / POST | `/api/admin/plugins/source-credentials` | 列出公开授权范围，或创建独立下载凭据 |
+| POST | `/api/admin/plugins/source-credentials/delete` | 请求 `{ "id": "<凭据 ID>" }`，删除未被来源引用的下载凭据 |
+| GET / POST | `/api/admin/plugins/update-sources` | 查询或显式改变插件后续安装的允许来源及更新检查策略 |
+
+删除制品时，同一事务会清理该制品使用过且已无任何制品引用的下载凭据；删除插件的最后一个版本时，
+同时清理其来源规则、更新检查策略及出站代理引用。其他版本共享的凭据、代理本身和审计记录保留，
+独立创建但未被该制品使用的下载凭据不会被顺带删除。完整卸载后重新安装不受旧来源规则限制。
+
+#### 包信息
+
+安装包使用的版本与字段规则见 [SDK 清单](../backend/crates/gateway-plugin/sdk/docs/manifest.md)。
+插件 ID 由 `publisher + "." + name` 派生；`displayName` 和可选 `author` 仅用于展示。
+
+制品 `metadata` 返回 `pluginId`、`name`、`displayName`、`publisher`、可为 `null` 的 `author`、`version`、
+`description`、`license`、`sha256`、`platforms`、可为 `null` 的 `icon`、`contributes`、`requestedPermissions`、
+`permissionDescriptions`、`configurationSchema`、`secretFields` 和 `stateNamespaces`。`permissionDescriptions` 的每项为
+`{ permission, label, description }`，供安装确认直接展示。`contributes` 是以稳定 snake_case capability 为 key 的对象；每个值包含
+`id`、`version`、`stages`、`inputFormats` 和 `outputFormats`。`id` 是实例绑定引用的完整贡献项 ID，客户端必须通过
+当前制品的 `contributes` 映射确定其 capability，不能解析 ID 文本推测能力。
+
+#### 图标读取
+
+`metadata.icon` 为清单中的包内路径或 `{ "light": "...", "dark": "..." }` 对象；未声明时为 `null`。
+配置示例、支持格式与文件限制见 [SDK 插件图标](../backend/crates/gateway-plugin/sdk/docs/manifest.md#插件图标)。
+
+读取浅色主题图标使用 `GET /api/admin/plugins/artifacts/{sha256}/icon?theme=light`：
+
+- `sha256` 为制品的 64 位小写十六进制摘要；`theme` 必填，值为 `light` 或 `dark`。单路径图标在两种主题下返回相同内容
+- 成功返回图片原始字节，`Content-Type` 为清单声明的 MIME，不使用 JSON 信封、不转换图片格式。制品不存在或未提供图标时返回 `404`
+- 响应包含 `X-Content-Type-Options: nosniff` 和 `Cache-Control: private, max-age=31536000, immutable`；缓存按制品摘要与主题区分
+- SVG 使用 sandbox CSP 隔离，允许内联样式和 data 图片，禁止脚本执行与外部资源请求
+
+客户端应将接口地址用于 `<img src="…">`，不内联 SVG，也不把清单路径拼成文件系统路径或公开 URL。
+没有图标时由客户端显示通用图标。
+
+#### 解析与确认安装
+
+本地包先调用 `artifacts/upload/verify`，远程包先调用 `artifacts/verify`。校验只返回包信息与来源，
+不保存、不接受访问域、不启动插件，也不代表实例配置或私有状态已经兼容。
+修改文件、地址、Release、摘要、凭据或代理选择后必须重新校验；确认安装时固定校验返回的身份、版本与摘要。
+
+远程解析请求包含 `location`、可选 `credentialIds` 和 `outboundProxyId`，不需要预先提供 ID 或版本。
+更新已有插件时可传 `expectedPluginId` 锁定预期身份；首次安装从包内清单读取身份，并按该身份复核已保存的来源绑定。
+URL 与 GitHub 的 `location.sha256` 在解析时均可省略，由服务端计算实际包摘要；提供摘要时必须通过匹配检查。
+
+确认安装时，将解析返回的 `metadata.pluginId`、`metadata.version` 和 `metadata.sha256` 分别填入
+`pluginId`、`version`、`location.sha256`，与原来的来源、凭据和代理选择一起提交 `artifacts/install`。
+这三个字段在远程安装时必填，确保实际安装内容与确认的包相同。清单 ID、版本、宿主兼容范围与平台
+必须通过校验；来源类型、地址或代理选择变化返回冲突，需要先显式修改更新来源。相同包及来源重复安装为幂等操作；
+同一插件版本的平台产物不允许替换成不同内容。安装新版本保留已安装旧版本。
+
+```json
+{
+  "pluginId": "acme.example",
+  "version": "1.0.0",
+  "credentialIds": [],
+  "outboundProxyId": null,
+  "location": {
+    "kind": "url",
+    "url": "https://downloads.example.org/plugin.tar.gz",
+    "sha256": "<64 位小写十六进制摘要>"
+  }
+}
+```
+
+上传、远程安装和 `artifacts/accept` 成功响应均为平铺对象：
+
+```json
+{
+  "artifact": {
+    "metadata": {},
+    "source": { "kind": "upload" },
+    "installedAt": "2026-09-22T00:00:00Z",
+    "acceptedAt": "2026-09-22T00:00:01Z"
+  },
+  "configRevision": 2,
+  "defaultInstanceId": "<实例 UUID 或 null>",
+  "configurationRequired": false
+}
+```
+
+接受制品时，若该插件没有任何实例，服务端使用稳定的 creation ID 创建一份默认实例：普通配置取 schema 默认值，
+敏感字段不复制默认值；除 `management`、`command_line` 和 `frontend_authentication` 外，为声明的贡献项及阶段建立
+空范围默认 binding。仅缺少必填项时 `configurationRequired=true` 且实例保持停用；配置完整时实例直接启用。
+非法 schema、类型错误或把敏感字段放入普通配置会拒绝安装。已有该插件实例时不额外创建或切换实例，
+`defaultInstanceId=null`。相同摘要的接受和默认实例创建可重试，不产生副本。
+
+宿主发行目录导入的制品只写入不可变包和来源，`acceptedAt=null`；在严格复核
+`permissionDescriptions` 后调用 `artifacts/accept`。未接受制品不能用于创建、更新或启用实例。
+
+GitHub 的 `location` 使用 `kind: "github"`、`repository: "owner/repo"`、`tag`、`asset`、
+`allow_prerelease` 和 `sha256`。解析时优先使用显式摘要或 GitHub 的 SHA-256，缺失时读取同一 Release 的
+`checksums.txt`；都未提供时计算下载内容的摘要供确认安装使用。显式摘要与 GitHub 摘要冲突时拒绝下载。
+摘要用于内容一致性检查，不证明发布者身份，只应安装可信来源的插件。
+
+#### GitHub Release 查询
+
+查询请求为 `{ "query": { "repository": "owner/repo", "tag": null, "allowPrerelease": false }, "credentialIds": [], "outboundProxyId": null }`。
+`tag: null` 查询最新稳定版；预发行版须指定 tag 并允许预发行。响应包含固定 tag、产物列表、`queriedAt`
+和 `expiresAt`。成功缓存 1 小时，失败缓存 30 秒，同一查询合并并发；限流返回错误，不转换成空列表。
+
+#### 下载认证与代理
+
+下载凭据创建字段为 `name`、`origin`、`pathPrefix`、`purposes`、`authentication`。
+`purposes` 可选 `metadata`、`artifact`；`authentication.kind` 可选 `github`、`bearer`、`basic`、`header`，
+分别携带 `token`、`token`、`username/password`、`name/value`。列表与创建响应只返回 ID 和授权范围。
+每次重定向都按 origin、路径段边界和用途重新匹配凭据，重叠授权拒绝执行。
+来源 URL 使用 HTTPS，不包含用户信息、查询参数或片段；回环地址允许 HTTP，供本机来源使用。
+
+查询、校验和远程安装的 `outboundProxyId` 指向已保存的出站代理，与下载凭据独立，公开来源也可选择代理。
+省略或 `null` 表示直连，不继承进程环境代理；代理失败不会回退直连。查询与下载期间代理配置变化时返回 `409`，需重新操作。
+查询缓存与限流按凭据及代理身份隔离。制品历史 `source.outbound_proxy` 只保存下载时的 `{ id, revision }`，不返回代理地址或认证信息。
+仍被更新来源或制品引用的代理不能删除；修改后续来源不会清除已安装制品的历史引用。
+
+#### 更新来源与检查
+
+修改更新来源请求为 `{ "pluginId": "acme.example", "source": { "kind": "github", "repository": "owner/repo" }, "policy": { "kind": "stable" }, "outboundProxyId": null }`；
+其他可选来源为 `upload` 或带 `url` 的 `url`。`policy` 省略时为 `manual`；GitHub 还支持 `stable`（最新稳定版）和
+`{ "kind": "pinned", "tag": "v2.0.0-rc.1", "allow_prerelease": true }`。其他来源只支持 `manual`。
+来源、策略和代理选择一同持久化与审计；代理字段省略或 `null` 明确保存为直连。`upload` 和 `builtin` 不接受代理。
+变更不改变已安装包的历史来源，不自动下载、接受制品或切换实例版本。
+
+检查更新请求为 `{ "pluginId": "acme.example", "credentialIds": [] }`，返回 `binding` 和 `release`。
+服务端使用已保存的来源、策略和代理，不接受临时替换仓库或代理；查询期间来源变更返回 `409`，不可访问或限流仍返回错误。
+`release` 仅是来源元数据，不表示插件包已通过身份、版本、平台、兼容范围或摘要校验；选择产物后仍须显式调用安装接口，
+安装成功也不会自动修改现有实例的固定制品。手动策略和不支持 Release 查询的来源返回明确错误，不伪装为没有更新。
+
+### 12.1 运行实例
+
+| 方法 | 路径 | 行为 |
+| --- | --- | --- |
+| GET | `/api/admin/plugins/instances` | 列出实例配置、功能绑定、配置完整性及发布状态，不返回 secret 值 |
+| POST | `/api/admin/plugins/instances` | 创建实例，返回 `id` 和 `configRevision` |
+| POST | `/api/admin/plugins/instances/update` | 请求 `{ "id": "<实例 ID>", "instance": { ...配置字段 } }`，整体更新实例 |
+| GET | `/api/admin/plugins/instances/version-plan?id=<实例 ID>&artifactSha256=<目标摘要>` | 只读生成版本设置草稿，不启动插件、不返回密钥值 |
+| POST | `/api/admin/plugins/instances/switch-version` | 请求 `{ "id": "<实例 ID>", "target": { "artifactSha256": "<已安装目标摘要>", "expectedRevision": 1 } }`，准备后切换版本 |
+| GET | `/api/admin/plugins/instances/rollback-plan?id=<实例 ID>` | 只读列出当前版本、实例 revision 与按语义版本降序排列的已安装、已接受且有配置快照的旧版候选，不启动插件 |
+| POST | `/api/admin/plugins/instances/rollback` | 请求 `{ "id": "<实例 ID>", "target": { "artifactSha256": "<已安装且已接受旧版摘要>", "expectedRevision": 1 } }`，校验后回滚 |
+| POST | `/api/admin/plugins/instances/disable` | 请求 `{ "id": "<实例 ID>" }`，停用实例并发布新集合 |
+| POST | `/api/admin/plugins/instances/delete` | 请求 `{ "id": "<实例 ID>" }`，删除已停用实例 |
+
+#### 创建与更新
+
+创建与更新的配置字段为 `name`、`artifactSha256`、`enabled`、`configuration` 和必填的 `bindings`，
+`secrets` 可选。输入严格拒绝未知字段；`trustedProcess` 和 `grants` 不是输入字段。`artifactSha256` 必须指向
+已接受的制品，其访问域由制品声明精确派生，实例不能增加或删减。`configuration` 是匹配插件 schema 的 JSON 对象；敏感字段必须
+放入 `secrets`，空对象清除全部值。省略时同版本编辑保留当前值；跨版本编辑优先保留目标版本快照的密钥，没有快照则保留当前值。
+
+创建可传 `creationId`（标准小写 UUID），同一草稿重试复用该 ID，已保存且内容不同则返回 409，不创建副本或覆盖旧配置。
+相同内容的重试仍会重新准备并发布，不保证配置 revision 不变。更新可传 `expectedRevision`，与实例列表的 `revision`
+不一致时返回 409，管理员应重新加载后确认。创建不能传 `expectedRevision`，更新不能传 `creationId`。
+删除实例会一并删除其 secret、私有状态与版本配置快照，停用则保留这些数据。
+
+保存启用配置时，可传 `replaceInstances: [{ "id": "<旧配置 ID>", "expectedRevision": 1 }]`，
+明确确认同时停用的同插件配置（最多 256 项，不得包含当前配置或重复 ID）。同一插件最多启用一个实例，省略且已有其他启用配置时返回 409。
+不能将已有实例切换成另一个插件。
+目标配置准备通过后，停用旧配置与保存目标在同一事务提交，旧配置及其密钥、私有状态保留。
+待停用配置必须仍启用且 revision 与确认时一致，否则返回 409，重新读取并确认后再提交。
+
+列表项包含 `id`、`name`、`artifactSha256`、`enabled`、`configurationRequired`、`configuration`、
+`secretFields`、`bindings`、`revision`、`running`、`publishedRevision` 和 `runtime`。`configurationRequired`
+由当前制品 schema 与已保存的普通/敏感配置实时派生，不写入数据库；它只表示仍缺少必填值。停用实例也不能保存
+类型错误、非法 schema 或把敏感字段混入普通配置。
+
+#### 版本切换与私有状态
+
+私有状态通过 [SDK 回调](../backend/crates/gateway-plugin/sdk/docs/capabilities.md#私有状态)访问，不提供任意读写的管理 HTTP 接口。
+升级若需要迁移，实例可能暂时停用；迁移失败且发生并发配置变更时保持停用，不覆盖管理员的新配置。
+版本切换只接受同一插件已安装且已接受的制品，`expectedRevision` 必须等于实例列表中的 `revision`，过期请求返回 409。
+`version-plan` 返回 `instanceRevision`、`artifactSha256`、`configuration`、`secretFields`、`bindings` 和 `restored`，
+最后一项表示使用了目标版本的配置快照。没有快照时只补充缺失的 schema 默认值，保留当前显式值；功能范围按能力与阶段映射到目标声明，
+新能力使用默认绑定，已关闭的既有能力继续关闭，客户端认证仍须显式身份映射。草稿不代表已通过校验。
+
+`switch-version` 重新生成草稿并执行准备与提交，名称和启停状态保持不变，权限从目标制品派生。不兼容设置返回 400，当前设置不变；
+可读取草稿并通过 `instances/update` 携带原 `expectedRevision` 提交修正。不会推断字段改名或丢弃未知参数与密钥。
+
+每个实例、制品摘要保存一份最近启用时提交的配置快照，包含普通配置、secret 与 binding，停用草稿不覆盖快照。
+`rollback` 只接受有快照的较早语义版本，恢复该版本设置并重新检查平台、配置与私有状态，保留当前名称与启停状态。
+快照与实例修改共享事务，不从审计日志重建，也不恢复私有业务数据；删除实例或制品时删除对应快照。
+
+#### 访问域与受管资源
+
+清单的 `requestedPermissions` 只接受五个稳定访问域，确认结果以制品摘要为边界；实例输入没有单独授权字段。
+
+| 标识 | 含义 |
+| --- | --- |
+| `network` | 访问网络 |
+| `models` | 查询模型和 Client Key 基本信息并调用模型，可能产生消耗 |
+| `accounts` | 读取和修改账号，包括访问原始凭据 |
+| `requests` | 查看和处理请求、响应、路由及账号选择 |
+| `public_endpoints` | 提供无需登录即可访问的资源与回调入口 |
+
+访问域不是 operation、Provider、账号、origin 或命名空间白名单。Runtime 仍按当前贡献项、调用阶段、父调用和宿主业务
+端口限制可用方法，不能把一个域借给无关调用。账号资源以每次请求的 `accountId` 查找权威 Provider，不接受插件提供的
+Provider 事实；Client Key 列表只投影 `id`、`name`、`enabled`，不返回前缀、明文、账号绑定或额度策略。模型调用须显式
+选择 Key ID，并继续经过该 Key 的当前准入、范围、预算、用量与计费合同。私有状态只能访问清单声明的命名空间。
+
+受管 HTTP 还会执行宿主网络策略。目标默认只允许常规公网地址；每次请求重新校验全部解析地址，连接使用通过校验的
+固定地址并保留原始 Host 与 TLS 域名校验。托管回调由宿主解析目标域名，HTTP/HTTPS/SOCKS 代理接收固定 IP；
+无法由宿主安全解析的目标会被拒绝。代理沿用所选账号配置，不自动回退直连；重定向不会自动跟随，后续地址必须重新校验。
+
+#### 能力绑定与范围
+
+`bindings` 通过 `contribution` 指定清单已声明的贡献项，并包含该贡献项声明支持的 `stage`、顺序和失败策略；
+尚未声明、尚未注册或阶段不匹配的贡献项不能启用。
+首次安装生成的默认实例会为适用贡献项的每个声明阶段创建 binding，`order=0`，观察阶段使用 `observe`，
+其他阶段使用 `reject`，所有范围数组为空。`management`、`command_line` 按清单声明注册，不接受 binding；
+`frontend_authentication` 必须由管理员显式配置身份映射，也不自动创建。
+
+请求终态观察的绑定格式如下；同一实例同时订阅 `request_lifecycle` 和 `usage` 时使用相同 `order`，
+宿主合并为一次调用，仅附带命中订阅的事实。
+
+```json
+{
+  "contribution": "acme.usage-observer.usage",
+  "stage": "observation",
+  "order": 10,
+  "failurePolicy": "observe",
+  "clientKeyIds": [],
+  "accountGroupIds": [],
+  "providerIds": [],
+  "models": []
+}
+```
+
+范围数组缺省或为空表示不限制该维度；同一数组中的条件取并集，不同维度取交集，全部为空表示全局。
+`clientKeyIds` 和 `accountGroupIds` 引用已有资源 ID，保存启用实例时校验存在性；引用被删除后仍可停用实例，
+保留原绑定供管理员修订，重新启用前必须修正引用。账号组范围使用请求开始时
+Client Key 已冻结的绑定组（含绑定但禁用的组），不按最终选中账号重新解释；全账号 Key 没有绑定组。
+Provider 范围匹配最终实际尝试的 Provider；未进入 Provider 的拒绝不会命中有限 Provider 范围。
+模型范围匹配客户端请求的公开模型 ID。配置发布不改变在途请求的匹配范围，同一实例不会因命中多个组而重复调用。
+
+`frontend_authentication` binding 只能使用 `authentication` 阶段、`reject` 或 `delegate` 失败策略，并通过
+`identityBindings: [{ "principal": "...", "clientKeyId": "..." }]` 明确映射外部身份；其他范围数组必须为空。
+普通 binding 不能携带 `identityBindings`。已停用、删除或不再授权的 Key 不会因映射恢复访问。
+
+实例不为管理页面或命令行预绑定模型执行 Key。管理页面经 12.2 的模型桥在每次调用时显式提交 `clientKeyId`；
+CLI 插件也须在具体调用中选择当前 Key。管理员身份本身不提升为推理身份，Key 明文不会发送给插件。
+
+观察失败只记录诊断，不改变响应、路由、标准 Usage 或账单。当前仅派发一次终态，过载直接丢弃，
+不承诺进程崩溃后的持久投递；这不是请求前拦截、流逐帧观察或账单重算接口。
+尚未通过重新鉴权、未建立冻结请求上下文的失败不触发当前终态观察。
+
+#### 发布状态
+
+启用或修改时先准备候选进程及目录，再提交和发布；失败不替换正在运行的集合。
+切换后在途请求保留原版本，其引用排空后回收旧进程。
+
+| 字段 | 含义 |
+| --- | --- |
+| `enabled` | 期望启用状态 |
+| `publishedRevision` | 当前已发布的全局配置版本 |
+| `running` | 实例已启用且发布版本与持久化配置一致；不代表进程存活或外部服务健康 |
+
+### 12.2 管理扩展页面与原始 API
+
+`GET /api/admin/plugins/extensions` 需要管理身份，返回统一信封，`data` 为当前已发布的扩展数组。
+每项包含 `target: { instanceId, artifactSha256, revision }`、`name`、`configurationSchema`、
+`pages`、`routes`、`resources` 和 `callbacks`。schema 不是实例配置，不包含 secret 值。
+页面目录的 `pages[].title` 与 `pages[].description` 分别用于宿主页面标题、副标题；未声明副标题时为 `null`。
+目录来自冻结的插件注册结果，并与当前持久化实例复验；停用、换包或修改实例后旧目录项立即不再可用。
+
+以下用 `{target}` 表示 `{instanceId}/{artifactSha256}/{revision}`，`{path}` 表示包内已声明的相对路径：
+
+| 方法 | 路径 | 身份与响应 |
+| --- | --- | --- |
+| 已注册方法 | `/api/admin/plugins/extensions/{target}/api/{path}` | 管理身份；插件原始响应，不套管理信封 |
+| GET | `/api/admin/plugins/extensions/{target}/resources/{path}` | 管理身份；已校验的静态字节 |
+| POST | `/api/admin/plugins/extensions/{target}/models/responses?clientKeyId=<ID>` | 管理身份；原生 Responses JSON 或 SSE，不套管理信封 |
+| POST | `/api/admin/plugins/extensions/{target}/callback-tickets` | 管理身份；统一信封中的一次性回调票据 |
+| GET | `/plugins/resources/{target}/{path}` | 无须登录，但资源须声明公开且制品已接受 `public_endpoints` 访问域 |
+| GET | `/plugins/callbacks/{target}/{path}` | 无须登录，但必须携带有效且未消费的 `state` 票据 |
+
+实例目标失效返回 409，调用方应刷新扩展目录，不重放原操作。尚无可用发布视图时返回 503。
+所有入口都要求当前实例仍启用、制品已接受且版本匹配；公开资源与回调还要求制品声明 `public_endpoints`。
+公开入口不是读取任意包文件的路径。
+单项静态资源最多 1 MiB，总量最多 8 MiB；资源必须同时出现在制品清单和注册结果中。
+
+管理 API 只转交方法、相对路径、查询字符串、Content-Type、宿主请求关联与原始正文，不转交管理 Cookie
+或任意认证头。仅接受注册的方法、路径和内容类型；查询最多 8 KiB，正文最多 1 MiB 且受运行帧预算约束，
+GET/HEAD 不接受正文。响应状态码为 200–599，内容类型须在注册列表内，204/304 不允许正文；插件不能
+自选 Set-Cookie、Location 或其他响应头。失败可能发生在副作用之后，不提供自动重试。
+
+动态 API 与登录回调设置 `Cache-Control: no-store`。静态资源成功响应设置 `private, no-cache` 与内容 ETag，
+浏览器可保存正文，但每次复用前必须重新校验管理员身份（公开资源除外）、实例版本和资源授权；
+`If-None-Match` 匹配时返回无正文的 `304`。停用、版本或授权变更后，旧目标仍被拒绝，不返回缓存命中。
+两类响应均设置 nosniff、no-referrer 与限制性 CSP。管理端页面使用隔离 iframe，
+仅允许脚本，不具有父页面同源权限；联网、弹窗、表单、嵌套页面和顶层导航均不开放。
+页面访问已声明管理路由须经过固定目标的宿主桥，不能指定其他实例或版本。插件页面作者合同见
+[SDK 管理 API 与页面](../backend/crates/gateway-plugin/sdk/docs/capabilities.md#管理-api-与页面)。
+
+模型桥只接受严格的 `clientKeyId` 查询参数和 Responses JSON 正文；传输正文与解压后的正文均最多 8 MiB。
+服务端先复核固定目标与 `models` 访问域，再按 ID 查询当前 Client Key，并使用普通 Responses HTTP/SSE 执行链；
+因此仍执行当前 Key 的准入、账号范围、预算、用量、计费与请求插件链，包括发起页面所属插件自己的适用 hook。
+这不是嵌套的宿主模型回调，管理身份本身也不提供推理身份，Key 明文不会离开宿主。
+
+等待首帧、非流式生成和流式正文交付期间约每秒复核一次固定目标与 `models` 访问域。实例停用、制品或 revision
+变化以及访问资格失效会取消底层执行并停止响应。成功或协议错误沿用 Responses 内容类型，并返回可检索的
+`x-request-id` 与 `x-gateway-request-id`；响应移除 Cookie 和认证头并设置 nosniff、no-referrer 与限制性 CSP。
+内置页面桥最多并发 4 个模型请求，每次拉取最多 64 KiB，总期限 10 分钟；页面在已收到响应后 30 秒不继续拉取会取消，
+等待首个响应本身不受该空闲计时误杀。
+
+票据请求为 `{ "path": "oauth", "ttlSeconds": 60 }`，有效期只允许 1–600 秒；响应数据为
+`{ "state": "<一次性不透明票据>", "expiresAtMs": 0 }`。state 绑定签发管理身份、实例、制品、版本与路径，
+不得记录或截图。公开回调只接受无正文的 GET，查询参数必须恰好包含一个 `state`；过期、错路径、跨实例、
+并发重复或已消费票据均拒绝。宿主在执行前原子消费票据，因此超时或插件失败后不能重放。
+公开调用使用无宿主回调权限的独立阶段，不能读取或保存账号、读写状态、发送受管 HTTP 或日志。
+票据用于受控接收第三方返回结果，不代替敏感管理操作的身份校验。
diff --git a/docs/architecture.md b/docs/architecture.md
index 628468fdb..2fb9eb939 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -4,14 +4,21 @@
 具体 HTTP 字段见 [接口文档](api.md)，部署参数见 [部署文档](../deploy/README.md)；上游 URL、超时、
 重试间隔和 UI 布局属于源码或配置，不在架构文档重复维护。
 
+| 阅读目标 | 章节 |
+| --- | --- |
+| 了解模块与插件边界 | [运行拓扑](#2-运行拓扑)、[Workspace](#3-workspace-边界)、[插件扩展](#31-插件扩展) |
+| 跟踪一次请求 | [请求生命周期](#4-数据面请求生命周期)、[协议边界](#5-provider-与协议边界)、[路由与结算](#6-路由账号范围与-continuation) |
+| 修改配置与持久化 | [控制面](#7-控制面与-revision)、[状态所有权](#8-状态所有权) |
+| 维护运行行为 | [凭据与额度](#9-credential额度与主动重置)、[观测与任务](#10-观测与后台任务)、[生命周期](#11-生命周期安全与恢复) |
+
 ## 1. 系统定位
 
 Codex Proxy RS 是单进程、单副本运行的多 Provider AI 网关，同时提供：
 
 - 面向客户端的 OpenAI Responses、Images、standalone Search 和模型目录协议；
 - 面向管理员的 `/api/admin/*` 控制面和 Vue 管理端；
-- 面向 Key 持有者的 `/api/key-usage/*` 用量与客户端配置接口、独立 `/key-usage` 页面，以及 Bearer 鉴权的 `/v1/usage` 额度查询；
-- OpenAI 与 xAI 两个编译期 Provider；
+- 面向 Key 持有者的 `/api/key-usage/*` 用量与客户端配置接口、独立 `/key-usage` 页面，以及复用数据面认证的 `/v1/usage` 额度查询；
+- OpenAI 与 xAI 两个编译期 Provider，以及插件提供的 Provider、认证、中间件和管理扩展；
 - PostgreSQL 持久化、Redis 协调状态以及 S3/R2 数据库备份。
 
 系统不提供 `/v1/chat/completions`，不存在 Provider Instance 层，也不支持通过复制应用容器进行多副本
@@ -21,34 +28,27 @@ Codex Proxy RS 是单进程、单副本运行的多 Provider AI 网关，同时
 ## 2. 运行拓扑
 
 ```mermaid
-flowchart LR
-  Client[API Client] --> API[gateway-api]
-  Browser[Vue Admin] --> API
-
-  API --> Core[gateway-core]
-  API --> Admin[gateway-admin]
-
+flowchart TB
+  Client[API 客户端 / 管理端] --> API[gateway-api]
+  Host[gateway-host] -. 生命周期与后台任务 .-> API
+  API --> Core[gateway-core<br/>请求执行]
+  API --> Admin[gateway-admin<br/>管理用例]
   Core --> Registry[Provider Registry]
   Admin --> Registry
-  Registry --> OpenAI[provider-openai]
-  Registry --> XAI[provider-xai]
-  OpenAI --> OpenAIUpstream[OpenAI upstream]
-  XAI --> XAIUpstream[xAI upstream]
-
+  Registry --> Builtin[OpenAI / xAI]
+  Registry --> Plugins[Plugin Runtime / 插件进程]
+  Builtin --> Upstream[上游服务]
+  Plugins --> Upstream
   Core --> Store[gateway-store]
   Admin --> Store
-  OpenAI --> Store
-  XAI --> Store
+  Builtin --> Store
   Store --> PG[(PostgreSQL)]
   Store --> Redis[(Redis)]
   Store --> Object[(S3 / R2)]
-
-  Host[gateway-host] -. lifecycle / workers / update .-> API
-  Host -. lazy client distribution resolver .-> Admin
-  Host --> StoreLinks[RG-Adguard / Microsoft CDN]
 ```
 
-`backend/apps/gateway` 是唯一组合根，按 Host → Store → Provider → Core → Admin → API → Worker 的顺序
+图中表示运行时协作，不是 crate 的直接依赖。`backend/apps/gateway` 是网关的唯一组合根，
+按 Host → Store → Provider → Core → Admin → API → Worker 的顺序
 初始化具体实现。其余 crate 只暴露自己的配置、端口和 Bundle，不自行定位别的实现。
 
 ## 3. Workspace 边界
@@ -56,15 +56,20 @@ flowchart LR
 | 路径 | 责任 |
 | --- | --- |
 | `backend/apps/gateway` | 读取顶层配置、连接 Bundle、注册 Provider 与 Worker |
+| `backend/apps/plugin-cli`（包名 `codex-proxy-plugin-cli`） | `cpr-plugin package` 校验作者清单并生成平台元数据、资源摘要与归档；内部仅依赖 SDK，不参与网关运行时加载 |
 | `gateway-protocol` | 跨层共享的 OpenAI wire contract、SSE 编解码与无业务 owner 的解析事实，不依赖其他 workspace crate |
 | `gateway-core` | operation、canonical event、请求快照、路由、admission、attempt 协调、交付边界和计量 |
 | `gateway-admin` | 管理领域、Key 用量查询、Provider/Store 端口、审计语义和备份策略 |
 | `gateway-api` | HTTP/WS/SSE 解码与交付、Admin 与 Key 用量 wire、静态 Web UI；不直接访问 Store 或具体 Provider |
 | `gateway-store` | PostgreSQL、Redis、S3/R2、`pg_dump` 适配器；不拥有业务策略 |
 | `gateway-host` | 配置加载、日志、HTTP 生命周期、Worker 监督、系统更新及外部价格源适配 |
+| `gateway-plugin/sdk`（包名 `gateway-plugin-sdk`） | 公开插件清单与线协议，独立于网关领域；异步收发通过可选 `io` feature 提供 |
+| `gateway-plugin/runtime`（包名 `gateway-plugin-runtime`） | 插件包校验、能力适配、双向 RPC 与发布集合；通过 Host 管理子进程和受管 HTTP |
 | `providers/openai` | OpenAI OAuth、账号选择、目录、额度、Responses/Images/Search transport |
 | `providers/xai` | xAI OAuth session、账号选择、目录、额度和 Grok/Responses 转换 |
 | `frontend` | Vue 管理端与 Key 用量页，仅通过各自身份允许的控制面 API 访问状态 |
+| 独立仓库 `codex-proxy-ui` | 管理端与插件页面共用的 Vue 基础组件、纯主题算法和样式，不依赖宿主业务状态、路由或 API |
+| 独立仓库 `codex-proxy-plugins` | 官方维护综合示例，依赖公开 SDK，Rust 处理器和已构建页面合成一个可安装包，不随宿主构建发版 |
 
 依赖方向遵守四条规则：
 
@@ -73,10 +78,87 @@ flowchart LR
 3. API 只调用 Core/Admin 抽象；Store 只实现端口。
 4. 具体实现只在组合根相遇。
 
+`frontend/` 是独立的 Node 项目，自行管理依赖、pnpm 配置、锁文件和 ESLint；仓库根目录不建立前端 workspace。
+管理端与独立示例仓库分别依赖 `@codex-proxy/ui` 的固定 GitHub 标签，通过锁文件固定实际提交并校验源码归档完整性，不要求同级源码目录。安装与构建许可见 [贡献与审查](../CONTRIBUTING.md#验证)。
+UI 包只公开组件、主题与样式入口；Pinia 持久化、登录、路由和管理请求仍由各自应用持有。
+插件页面把所需 UI、Vue 和 Tailwind CSS 4 样式编译进包内静态资源，通过隔离页面与受限消息桥使用自己的管理接口，
+不在运行时借用宿主 Vue 实例或内部模块。组件与主题扩展方式见 [管理端主题](theme.md)。
+
+### 3.1 插件扩展
+
+`gateway-plugin/` 只是目录分组，包含独立 SDK 和宿主 Runtime，不存在聚合 crate。
+SDK 定义双方通信合同；Runtime 把插件能力接入既有 Core / Admin 端口，不另建请求引擎或持久化体系。
+当前合同为 SDK `0.4.0`、清单 `manifestVersion: 3`、进程协议 `4`；宿主只准备通过当前合同与兼容范围校验的制品。
+
+下图表示运行时协作，不表示 crate 直接依赖；具体实现由组合根注入：
+
+```mermaid
+flowchart LR
+  API["管理端 / API"] --> Admin["Admin<br/>制品接受、配置、绑定"]
+  Admin -->|持久化| Store["Store<br/>包体、接受事实、配置与私有状态"]
+  Admin -->|校验与准备| Runtime["Plugin Runtime<br/>包校验、能力适配、RPC"]
+  Core["Core<br/>请求执行与发布快照"] -->|调用扩展| Runtime
+  Runtime <-->|SDK 协议| Plugin["插件进程"]
+  Runtime -->|受管资源| Host["Host<br/>进程、网络、Worker"]
+  Runtime -->|账号事务端口| Admin
+  Runtime -->|模型执行端口| Core
+```
+
+#### 职责与源码入口
+
+| 模块 | 负责什么 | 不负责什么 |
+| --- | --- | --- |
+| [SDK](../backend/crates/gateway-plugin/sdk/README.md) | 清单、调用数据、消息与帧；可选 `io` 会话辅助 | 不依赖其他 workspace crate，不启动宿主 |
+| [Runtime](../backend/crates/gateway-plugin/runtime/src/lib.rs) | 校验包与声明、准备能力集合、RPC、访问域执行与资源回收 | 不持久化安装选择，不重新决定账号资格或费用 |
+| Core | 发布不可变扩展快照；准入、路由、租约、请求交付与计费 | 不解释插件私有协议与存储格式 |
+| Admin / Store | 制品接受与配置用例 / 事务、版本校验、加密存储与审计 | 缓存目录和进程内状态不能替代数据库事实 |
+| Host | 下载、受管 HTTP、子进程容量与生命周期、维护任务监督 | 不解释插件业务协议 |
+| [Plugin CLI](../backend/apps/plugin-cli/README.md) | 校验作者清单，生成平台包与摘要 | workspace 内仅依赖 SDK，不构建源码、不安装或启用插件 |
+
+#### 发布与执行边界
+
+- **制品接受固定访问域。** 只读校验不持久化；上传、URL 和 GitHub 的确认安装接受精确摘要声明的五个访问域，
+  官方发行导入仍须管理员确认。若插件尚无实例，Admin 以稳定 ID 合并 schema 默认值与适用贡献项 binding：
+  配置完整则启用，缺少必填项则停用待补；已有实例时不复制配置或切换版本。实例不能增删制品访问域。
+- **一份发布快照。** 数据面、管理页面和维护任务使用同一不可变扩展集合；CLI 复用准备与调用合同，按次读取持久化配置。
+  新配置准备成功后才提交发布，在途请求持有旧集合直到结束；管理目标和回调另按当前身份与版本复验。
+- **插件故障按实例隔离。** 恢复时将启动失败的实例及其错误保留在发布集合中，正常实例和原生能力继续发布；
+  用户正在修改的实例仍须准备成功才能提交。集合区分进程就绪、可继续服务与需要后台重建，单个进程退出不撤销全部请求快照。
+  故障绑定保留原有作用范围和拒绝／委托策略，入口认证故障不降级为其他认证方式；宿主配置存储与 revision 无法确认时仍停止新请求。
+- **宿主持有业务事实。** 插件返回能力结果，Core 继续决定账号资格、发送状态、标准用量与费用；账号变更由 Admin / Store
+  执行版本校验、事务和审计。撤下 Provider 不删除账号或历史记录，失败的观察回调不改变响应和账单。
+- **数据加工走中间件。** `request` 包裹逻辑请求，`attempt` 包裹每次已选号的执行；请求顺序进入、响应逆序返回。
+  正文按需读取，透传无需额外读取权限；转换和改写不能绕过 Core 的交付、取消与结算边界。
+  数据面插件通过受管 HTTP 已发送或无法证明未发送时，Runtime 把该事实并入 Core 的请求副作用水位，后续不能按
+  Provider 的 `not_sent` 结果透明重放。
+- **访问域不跨调用。** `network`、`models`、`accounts`、`requests`、`public_endpoints` 只开放对应资源域；
+  账号、HTTP、模型、私有状态和日志回调仍绑定有效父调用与阶段。管理页和 CLI 不预绑定 Client Key，模型调用按次
+  选择当前 Key；页面 Responses 桥还复核精确实例目标和 `models` 域，并在等待与交付期间持续撤销检查。
+  `frontend_authentication` 必须显式配置 principal 到 Key 的映射；公开登录回调使用一次性票据且不继承宿主回调权限。
+- **版本切换保持数据一致。** 同一插件最多启用一个实例；每个实例与制品摘要保存最近启用时提交的配置、密钥和绑定，
+  快照与实例修改共享事务，停用草稿不覆盖恢复点。版本切换优先恢复目标快照，否则合并缺失默认值并保留显式设置。
+  私有状态按实例、schema 与配置版本隔离，写入使用精确记录版本。
+  不兼容升级须停用、排空并完成迁移，再原子提交配置与状态；失败不能覆盖并发修改。回滚也须通过兼容检查，
+  续写状态不能静默丢弃或改用其他账号。
+
+#### 信任与资源边界
+
+插件以与宿主相同的 OS 身份运行；接受制品访问域是管理员确认，不是操作系统沙箱。
+进程、RPC、下载、缓存与回调均有容量和期限限制；Host 提供受管资源，Runtime 负责协议、访问域与调用上下文校验。
+下载来源、凭据与代理按目标匹配，网络操作不占用数据库事务，提交前重新校验来源与代理版本。
+
+管理页面使用无同源权限的 sandbox iframe，通过固定目标的宿主桥访问已声明路由；
+UI、Vue 与样式随插件打包，不读取宿主内部模块。
+官方插件身份仅来自受信宿主发行物内的封口清单，普通安装不能指定 `builtin`；封口标记不是密码学签名。
+宿主更新与回滚必须通过已启用插件的兼容检查，不能自动接受制品或停用实例来绕过检查。
+
+安装到使用见 [插件使用](plugins.md)，清单与能力合同见 [SDK](../backend/crates/gateway-plugin/sdk/README.md)，
+HTTP 字段见 [插件 API](api.md#12-插件管理)，更新与数据恢复见 [部署说明](../deploy/README.md#插件兼容与发行目录)。
+
 组合根的 workspace architecture tests 冻结成员清单、依赖 DAG、公开模块面、源码纪律以及生产/测试模块
 镜像关系；具体行为边界由各 crate 的集成测试维护。
 
-### 3.1 Rust 模块组织约定
+### 3.2 Rust 模块组织约定
 
 后端采用目录模块的 `mod.rs` 风格；以下规则由组合根的 workspace architecture tests 扫描全部生产源码与
 测试模块树：
@@ -91,14 +173,14 @@ flowchart LR
    不能依靠同一 crate 内可见性掩盖循环边界。
 5. 每个 crate 的 `src/` 与 `tests/` 平级，生产源码不承载测试。`tests/` 镜像 `src/` 的模块目录形态：例如
    `src/foo/mod.rs` 对应 `tests/foo/mod.rs`，`src/foo/bar.rs` 对应 `tests/foo/bar.rs`。一个生产模块可以没有
-   测试；额外场景测试必须放在最近的生产 owner 目录下。根级 `support` 和冻结的 crate/workspace 架构场景
+   测试；额外场景测试必须放在最近的生产 owner 目录下。根级 `support` 及其辅助模块和冻结的 crate/workspace 架构场景
    是明确例外。
 
 较大的模块门面只负责组合和 re-export：账号 Admin HTTP 边界按 `wire`、`credentials`、`handlers`、
 `presenter` 划分；Provider 执行按 continuation、stream、failure、observation 和 worker 等职责拆分；xAI
 请求转换按 response、tools 与 history 拆分。各子模块之间只使用 owner 内最小可见性。
 
-### 3.2 `gateway-core` 内部 owner
+### 3.3 `gateway-core` 内部 owner
 
 `gateway-core` 内共享事实按语义 owner 划分：
 
@@ -149,24 +231,23 @@ Client Key 费用账本独立累计各次 attempt 的实际费用，不能因请
 
 ```mermaid
 sequenceDiagram
-  participant C as Client
-  participant A as API Adapter
-  participant E as Core Engine
+  participant C as 客户端
+  participant A as API
+  participant E as Core
   participant P as Provider
-  participant S as Store / Ops queue
+  participant S as Store
 
-  C->>A: authenticated request
-  A->>E: Operation + client context
-  E->>E: freeze snapshot and compile routing plan
-  E->>S: enqueue request / attempt observations
-  E->>S: check Key budget against recorded usage
-  E->>P: one candidate, one credential, one attempt
-  P-->>E: cold canonical stream + raw wire
-  E->>E: enforce send and downstream commit barriers
-  E-->>A: committed response stream
+  C->>A: 请求与认证
+  A->>E: Operation 与客户端上下文
+  E->>E: 冻结策略，生成路由计划
+  E->>S: 检查 Key 预算
+  E->>P: 一个凭据的一次尝试
+  P-->>E: 冷流与原始协议数据
+  E->>E: 检查发送与交付边界
+  E-->>A: 提交响应流
   A-->>C: JSON / SSE / WebSocket
-  E->>S: settle charge idempotently
-  E->>S: enqueue terminal observation and metering
+  E->>S: 幂等费用结算
+  E->>S: 异步投递观测与计量
 ```
 
 请求开始时冻结 `RuntimeSnapshot`、Client Key 的账号范围及账号模型政策、模型映射、Codex 客户端最低版本、Provider
@@ -214,6 +295,9 @@ OpenAI 模型目录用于发现，不因目录缺项拒绝请求；管理员配
 - OpenAI 是透明边界。Responses 请求保留未知字段和字段顺序；SSE、WebSocket、Images 与 standalone
   Search 的业务正文按原始字节转发，原生续写额度恢复遵循下述 continuation 例外。
   canonical facts 从同一数据旁路提取，用于路由、恢复判断、观测和计费。
+  非流式 Responses 由 API 聚合 wire：终态省略或清空 `output` 时，使用同一响应的 `output_item.done`
+  按 `output_index` 还原完整输出；已有非空终态输出不改写。完成项缺失或冲突时在下游提交前拒绝，
+  不凭 canonical 增量补造内容，也不让 SSE/WS 转发额外保存整份输出。
 - Responses 的业务扩展头保留原始多值字节。API 负责剥离鉴权、账号身份和 HTTP 传输字段，
   并提取会话语义；`gateway-protocol` 共享 HTTP 传输与网关链路字段分类。客户端兼容规则集中在
   `providers/openai/src/transport/downstream/`：`headers.rs` 管理下游环境头和已提取语义的头部别名，
@@ -324,12 +408,13 @@ Vue 普通管理请求的错误提示由 `api/request.ts` 响应拦截器统一
 规范化异常保留 `status`、`code`、`requestId` 与 `kind`。页面和 `useAsyncAction` 不重复弹出接口错误；
 查询可以保留失败状态与重试入口，本地校验、文件操作、SSE 诊断和成功响应中的业务结果仍归各自 owner。
 
-API 模块按 `url`、`method`、`data`（POST）或 `params: data`（GET）排列请求配置；
-仅在实际调用方需要时提供 `RequestOptions`（`signal`、`timeout`、`silent`），并放在请求配置末尾。取消或已被新查询取代的请求
-不弹提示；后台轮询、重启探测等显式使用 `silent`，它只关闭提示，不吞异常，也不跳过会话失效处理。
+取消或已被新查询取代的请求不弹提示；后台轮询、重启探测等显式使用 `silent`，它只关闭提示，
+不吞异常，也不跳过会话失效处理。
 批量操作的部分成功汇总、不可逆操作的结果未知等必要业务处理先将对应请求静默，再由业务 owner 提供
 一次有上下文的反馈；不得为普通失败重新维护一套消息或业务码映射。
 
+### 登录与查询身份
+
 管理员和密钥登录共用 `/api/auth/*`、AuthService、Redis 会话结构和 `cpr_session` Cookie。
 登录类型只选择凭据校验方式，权限来自服务端保存的身份。管理入口只接受管理员身份或部署级管理 API Key；
 AuthService 每次恢复 Key 会话时重新检查 Key 是否存在且启用；Key 会话不能访问管理员页面和管理接口。
@@ -338,8 +423,8 @@ AuthService 每次恢复 Key 会话时重新检查 Key 是否存在且启用；K
 管理员会话保存由已加盐密码哈希派生的指纹，每次恢复时与 PostgreSQL 当前密码核对；普通设置变更不影响该绑定。
 改密在 AuthService 验证当前密码和新密码策略，Store 以旧哈希条件更新密码并在同一 PostgreSQL 事务记录审计。
 事务提交后旧管理员会话的指纹失配，不依赖 Redis 批量删除完成撤销；原始密码及密码哈希不进入 Redis。
-KeyUsageService 从 AuthService 的服务端身份或 Core 的 ClientKeyVerifier 只读校验确定唯一查询范围，复用 ClientKeyStore 的额度账本投影和
-ObservabilityStore 的范围查询；Bearer 查询仅提供当前额度，不执行推理准入或开启窗口。
+KeyUsageService 从 AuthService 的服务端身份或 Core 的入口认证结果确定唯一查询范围，复用 ClientKeyStore 的额度账本投影和
+ObservabilityStore 的范围查询；数据面额度查询不执行推理准入或开启窗口，入口认证和适用的请求中间件仍会执行。
 API 只输出各入口所需的字段白名单，不复用管理员的宽响应。
 客户端配置通过 ClientKeyStore 显式读取当前会话绑定 Key 的明文，不进入用量响应。
 前端 `/key-usage` 独立于管理布局，不挂载管理员菜单或请求管理接口；配置弹窗和 Codex / CCSwitch
@@ -450,8 +535,9 @@ HTTP validation
 ```
 
 会改变路由快照或安全配置的 mutation 在同一 PostgreSQL 事务中提交业务事实、推进内部
-`config_revision` 并写入脱敏审计。Admin mutation 不要求客户端提交 revision；少数账号/分组响应
-返回已提交的 `configRevision`，不将它当作乐观并发前置条件。
+`config_revision` 并写入脱敏审计。`configRevision` 不作为客户端写入的乐观并发前置条件；
+少数账号/分组响应返回它用于标识已提交的配置。插件配置等资源另有 `revision` / `expectedRevision` 检查，
+不能与全局配置版本混用。
 
 额度、cooldown、目录 generation、请求统计和自动 credential refresh 属于运行时观测，不推进全局
 revision；credential 轮换只推进账号自己的 `credential_revision`。Redis 通知用于缩短收敛延迟，
@@ -467,10 +553,11 @@ PostgreSQL 周期对账才是正确性基础。
 | --- | --- | --- |
 | 账号、credential、分组、Client Key、设置、审计、请求与备份记录 | PostgreSQL | 业务持久化事实 |
 | Client Key 金额窗口与费用事件 | PostgreSQL | 准入与幂等结算的权威账本，独立于请求观测与日志保留策略 |
+| 插件包体、安装来源、制品接受事实、实例配置与私有状态 | PostgreSQL | 制品访问域由已接受摘要派生；进程内发布集合由持久化事实构建 |
 | admission、lease、cooldown、circuit、会话亲和、continuation、OAuth pending、目录 cache | Redis | 可重建、可过期的协调状态 |
 | 控制面统一登录会话与登录限流桶 | Redis | AuthService 唯一拥有；保存 Admin / Key 身份、绑定 ID、绝对有效期和计数，不保存原始凭据 |
 | 日志、OAuth 恢复记录、在线更新状态、备份暂存 | `.runtime/` | 部署节点本地运行文件 |
-| 重置卡库存与消费结果 | OpenAI upstream | 后端不建立本地卡库存；前端按账号在浏览器会话期间保留最近查询、未决消费幂等键与发送锁 |
+| 重置卡库存与消费结果 | 对应 Provider 的上游 | 后端不建立本地卡库存；前端按账号在浏览器会话期间保留最近查询、未决消费幂等键与发送锁 |
 | Provider 公开模型与官方发布资料 | Provider/runtime cache | 由官方目录或发布源刷新，与 PostgreSQL 中的用户身份选择分别管理 |
 | Windows 安装包临时直链 | Host 进程内短缓存 | 按需解析、严格校验、到期前丢弃；不写 PostgreSQL/Redis，也不代理包字节 |
 
@@ -490,9 +577,9 @@ PostgreSQL schema 由迁移目录按编号管理。已应用迁移按字节冻
 credential 与 quota 是两组独立事实：credential refresh 不等于 quota refresh，额度接口的 401/403
 也不能单独证明 refresh token 永久失效。
 
-- OpenAI 支持 OAuth、AT/RT 与 OAuth JSON，导入识别 camelCase 和官方 `auth.json` 的 snake_case token 字段；
-  RT-only 导入先换取 AT，AT-only 导入没有
-  自动续期能力。OAuth 身份只从官方 JWT claims 投影，不信任导入文档顶层身份字段。
+- OpenAI 支持 OAuth、AT/RT、PAT 和上游 API Key。OAuth 身份来自官方 JWT claims，PAT 经官方身份接口验证，
+  不信任导入文档顶层身份字段。RT-only 导入先换取 AT；AT-only、PAT 与 API Key 不参加 OAuth 自动续期。
+  输入形态和适用操作见 [账号能力与导入](api.md#账号能力导入与-oauth)。
 - xAI 使用 OAuth session；API Key 不是受支持的账号 credential。刷新额度时同步查询官方实时订阅，
   只把套餐事实写入现有 quota JSON。明确无付费订阅的个人账号显示 Free；查询失败、缺失字段或
   团队身份不推断为 Free，订阅查询失败不影响额度观测。
@@ -517,8 +604,10 @@ OpenAI 订阅周期属于按需个人信息，不是额度事实。Admin 账号
 ## 10. 观测与后台任务
 
 账号容量预测属于 Admin 的只读派生规则，不参与 quota 权威状态、调度或金额结算。Store 通过专用采样端口
-在同一 SQL 快照内返回截至观测时间的累计数值及有界历史 Provider 文档；文档仅由具体 Provider 复用协议
-解析器解释，Admin 按中立的额度事实选择近期进度段预测剩余量，再加本周期已记录用量形成周期总量。
+在同一 SQL 快照内返回截至观测时间的累计数值及有界历史 Provider 文档；原生 Provider 复用协议解析器解释
+文档，插件由 Runtime 本地解释 SDK 声明的版本化额度观测，不在历史查询中调用插件进程。观测通过 Core 原有
+请求结算持久化，账号关联由实际执行上下文确定，窗口身份与归属必须匹配当前额度窗口。Admin 按中立的额度
+事实选择近期进度段预测剩余量，再加本周期已记录用量形成周期总量。
 周期以额度重置为边界，重置后累计与样本重新开始。该采样不改变全站完整交付用量口径，不创建第二份
 持久化额度状态。部分 Token/美元费用缺失仅提示精度限制，继续按已记录数值估算；对应数值完全不可用时
 才不返回该项预测，不按请求数量补齐未知消耗。历史请求完成时间只是额度时间的近似，不承诺严格扣额归因
@@ -579,10 +668,8 @@ worker 复用连接测试探针执行真实上游调用，并按冻结代次处
 
 启动只有在配置、PostgreSQL、Redis、Provider、Core、Admin、API 和 Worker 全部初始化成功后才进入服务。
 健康检查综合 Core、Store 与 Worker 状态，但不会把单个 Provider 的业务降级等同于整个进程失活。
-组合根在启动时只把 Host 的 `ClientDistributionResolver` 能力注入 Admin；此时不访问 RG-Adguard，下载
-HTTP Client 构造失败也不会阻断网关启动。外部解析在已认证管理员首次打开客户端下载弹窗时惰性执行，
-失败时按架构使用 OpenAI 官方稳定地址。Microsoft Store 内容通道返回的 HTTP/80 临时链接保留原始 scheme，
-不会被错误改写到该 host 不保证支持的 HTTPS 虚拟主机。
+客户端下载解析由 Host 的 `ClientDistributionResolver` 实现，组合根注入 Admin；只在管理员请求时访问外部来源，
+不阻塞启动。失败时使用官方稳定地址，临时直链不持久化或代理下载，字段与来源规则见 [客户端下载 API](api.md#windows-客户端下载)。
 
 关闭分为两段：先停止接收新连接并 drain HTTP/WS，再取消并等待 Worker；两段各有独立预算，Compose 的
 `stop_grace_period` 必须覆盖二者之和。超时后只丢弃仍未落盘的可恢复观测，不执行隐式业务重放。
@@ -606,7 +693,9 @@ HTTP Client 构造失败也不会阻断网关启动。外部解析在已认证
 - 真实 secret 不进入普通日志、Debug、fixture 或 audit details；明文只能通过账号导出、Key reveal、
   备份设置等明确的敏感 Admin 合同返回。
 - OAuth pending flow 使用有期限、带 owner 的一次性 claim；事务成功后才消费，失败释放 claim。
-- 在线更新校验 Release host、大小、SHA-256 和归档路径，并只允许同一大版本内更新。
+- 在线更新校验 Release host、大小、SHA-256 和归档路径，并只允许同一大版本内更新；更新与回滚的目标发行清单
+  还要通过全部启用插件的静态兼容检查，文件交换前后复核同一插件配置版本，失败或取消时恢复二进制、Web 与
+  官方插件目录。
   Host 在受理时持久化任务并转交后台执行，任务持有操作锁与终态写入责任，不依赖 HTTP 请求的生命周期。
   状态文件是更新结果的权威来源，SSE 终态在状态落盘后发送；Host 关闭与任务析构都必须收敛状态。
 
@@ -632,5 +721,14 @@ RUST_MIN_STACK=16777216 cargo +1.97.0 test --manifest-path backend/Cargo.toml --
 [迁移文档](../backend/migrations/README.md#本地测试库) 配置专用测试库；未设置环境变量时，本地相关测试会跳过。
 其他检查与界面验证按 [贡献与审查](../CONTRIBUTING.md#验证) 执行。
 
+插件 Runtime 的真实子进程与持久化测试使用 `CPR_PLUGIN_TEST_DATABASE_URL` 和
+`CPR_PLUGIN_TEST_REDIS_URL` 指向专用实例，密码及隔离要求与上述 Store 测试一致。
+设置 `CPR_PLUGIN_TEST_LIVE_HTTP=1` 会额外请求 GitHub 公共 HTTPS API，验证受管出站链路；这不代表模型推理验收。
+若测试环境使用 Fake-IP 或私网 DNS，需通过 `CPR_PLUGIN_TEST_LIVE_NETWORK_RANGES` 显式提供逗号分隔的
+CIDR 授权。该选项只用于真实网络测试，默认为空，不改变生产网络策略或其他测试的授权。
+
+独立插件包的构建、安装与功能验证说明位于 `codex-proxy-plugins` 仓库的 `examples/request-workbench/README.md`。
+功能测试与性能、隔离和平台实测分别记录，不相互替代。
+
 改动使现有说明失真或缺少必要信息时，修订所属文档：用户入口写入根 README，HTTP 合同写入 `docs/api.md`，
 部署操作写入 `deploy/README.md`，架构不变量保留在本文。
diff --git a/docs/plugins.md b/docs/plugins.md
new file mode 100644
index 000000000..27824b343
--- /dev/null
+++ b/docs/plugins.md
@@ -0,0 +1,121 @@
+# 插件使用
+
+插件“制品”是按 SHA-256 固定的代码、版本和访问域；“配置”是运行实例，保存普通设置、敏感设置和功能范围。
+日常使用只维护一个当前配置，同一插件最多启用一个实例。访问域随制品接受，不能在设置中另行增删。
+
+```mermaid
+flowchart LR
+  A[选择来源] --> B[校验包并查看访问域]
+  B --> C[确认安装并接受制品]
+  C --> D[生成默认配置]
+  D -->|配置完整| E[启用并发布]
+  D -->|缺少必填项| F[补充配置后启用]
+```
+
+宿主支持 SDK `0.4.0`、`manifestVersion: 3` 和进程协议 `4`。包必须同时满足当前平台和宿主兼容范围。
+
+## 安装
+
+在“插件管理”点击安装图标，选择来源：
+
+- **上传包**：选择发布者提供的 `tar.gz` 或 `tgz` 包
+- **URL**：填写固定下载地址；支持 HTTPS，本机回环地址可使用 HTTP
+- **GitHub**：填写仓库地址或 `owner/repo`；标签留空查询最新稳定版，预发行版须指定标签
+
+公开来源无需认证。私有来源可选择或创建独立下载认证；认证按来源和用途限制，不会交给插件进程。
+下载代理独立选择，默认直连，代理失败不会回退直连。SHA-256 用于固定内容，不证明发布者身份。
+
+“下一步”只解析和校验包，不保存制品。检查名称、发布者、版本、平台、摘要和访问域后确认安装；上传、URL
+和 GitHub 安装会接受该摘要声明的访问域。随宿主发行物导入的官方制品会显示为“待接受”，也必须先查看访问域并确认，
+未接受的制品不能创建或编辑配置。相同摘要的确认可安全重试。
+
+确认安装后，若该插件还没有任何配置，宿主会：
+
+1. 从 schema 填入普通配置默认值，不把敏感字段的默认值写入普通配置
+2. 为需要实例范围的贡献项生成默认绑定；管理页面和命令行按声明注册，入口认证不自动绑定
+3. 配置完整时直接启用并发布；仅缺少必填项时保存为停用并打开配置页
+
+类型错误、非法 schema 或把敏感值混入普通配置会直接拒绝，不会伪装成“待配置”。更新已有插件时不会创建另一套配置，
+管理端在包安装完成后提示确认切换，检查通过后应用目标版本，不兼容时保留原版本并打开待调整的设置。
+
+### 五个访问域
+
+安装确认只使用以下稳定访问域；具体调用仍受贡献项、当前调用上下文和宿主策略限制。
+
+| 标识 | 安装摘要中的含义 |
+| --- | --- |
+| `network` | 访问网络 |
+| `models` | 查询模型和 Client Key 基本信息并调用模型，可能产生消耗 |
+| `accounts` | 读取和修改账号，包括访问原始凭据 |
+| `requests` | 查看和处理请求、响应、路由及账号选择 |
+| `public_endpoints` | 提供无需登录即可访问的资源与回调入口 |
+
+访问域不是操作列表或资源白名单。实例配置不能扩大、缩小或伪造制品声明；切换版本后使用目标制品已经接受的精确声明。
+插件进程与网关使用相同的系统身份，接受访问域不是操作系统沙箱，因此只安装可信来源的包。
+
+## 配置与启用
+
+在插件详情中直接启用或停用，设置会保留，无需重新填写。插件没有可设置的参数或认证映射时不显示设置入口。
+
+“设置”按当前包的 schema 显示参数，敏感字段单独保存且不回显。首次补齐必填项后“保存并启用”；其他设置修改保持
+原有启停状态。请求处理能力随包自动注册，无需在安装时逐项勾选；有特殊需求时，可在“高级设置”中调整请求作用范围。
+客户端 Key、账号分组、Provider 和模型等范围同时满足才生效，同一范围内任一值匹配即可。
+
+范围数组为空表示不限制该维度。自动创建的默认绑定不预先绑定 Client Key；普通网关请求仍以实际请求的 Key 和冻结策略
+执行。管理页面和命令行不保存功能 binding，页面调用模型时由页面每次明确选择一个 Client Key ID，宿主按当前 Key 状态、
+范围、预算、账本和普通请求链执行，插件看不到 Key 明文。
+
+`frontend_authentication` 不会随安装自动接管入口。启用它时必须明确配置外部 principal 到既有 Client Key 的映射；
+已停用或删除的 Key 不会因此恢复访问。已有多套配置保留在“历史配置”中，选择使用时确认替换当前配置；不再提供新增配置入口，
+也不会自动删除历史配置、密钥或私有数据。升级前已经启用多套的插件会提示整理，宿主不会擅自选择停用对象，后续启用或更新
+必须收敛到一套配置。
+
+“已启用”表示配置已经发布，不是外部服务的健康证明。“等待生效”表示候选仍在准备；“需要处理”会显示发布或运行失败原因。
+并发编辑冲突时应重新加载当前 revision 后确认，不能覆盖另一窗口的修改。
+
+## 使用
+
+| 功能 | 使用方式 |
+| --- | --- |
+| 管理页面 | 从插件详情或左侧插件导航打开；页面在隔离 iframe 中运行 |
+| 页面模型请求 | 每次选择 Client Key，经固定实例版本的 Responses 桥执行，返回原生 JSON 或 SSE |
+| 请求中间件、模型路由、账号调度、请求观察 | 匹配功能范围的正常网关请求自动使用 |
+| Provider 扩展 | 在账号管理中按插件支持的方式添加或授权账号 |
+| 入口认证 | 客户端按插件协议访问，宿主把明确的 principal 映射到 Client Key |
+| 维护任务 | 宿主按已声明能力和当前访问域调度，不提供没有后端支持的手动入口 |
+| 命令行 | 在宿主环境运行 `codex-proxy-rs plugin <配置 ID> --help` |
+
+页面模型桥要求管理会话、当前实例/制品/revision 和 `models` 访问域同时有效。停用实例、切换版本或 revision、
+撤销相应访问资格后，宿主会在等待首帧和交付响应期间持续复核并取消请求；它不会把管理 Cookie、Key 明文或认证头交给插件。
+
+## 更新、回退与卸载
+
+- **检查更新**：GitHub 按保存的策略查询发布，URL 下载并解析当前地址的包；本地上传不支持查询。检查本身不会安装，GitHub 标签也不等于包内版本。
+- **更新插件**：选择新包并确认安装，再确认切换到目标版本。保留已填写的值，补充新版本缺失的默认值；字段改名、类型改变或删除等不兼容情况由用户调整，不猜测或静默清空参数与密钥。
+- **切换版本**：在版本列表中选择已安装版本，确认当前版本与目标版本后执行。若该版本已有恢复设置，使用它上次启用时提交的参数、密钥与功能范围；否则从当前设置生成草稿。切换保持启停状态，目标访问域以已接受的包为准。停用的历史配置引用旧版本时显示“历史配置”，不表示该版本正在运行。
+- **回退版本**：只列出同一插件已安装、已接受且保留恢复设置的较早版本，恢复对应设置后重新执行兼容检查。
+
+每个精确插件包保留最近一次启用时提交的配置快照，停用期间未完成的草稿不会覆盖恢复点。升级宿主时会为已有启用配置建立
+恢复点，无法补回此前已经丢失的旧版本设置。修改下载来源会先单独保存，取消后续安装也会保留已保存来源。当前浏览器标签页
+记住未提交的安装参数和凭据引用，不保存认证明文或上传文件。
+
+设置恢复不等于私有数据恢复。私有数据迁移仍由插件声明的迁移能力处理，不兼容且无迁移路径时不能切换；迁移失败会尝试
+恢复原版本，若恢复会覆盖并发修改则保持停用并提示处理。配置检查或候选准备失败不会覆盖当前设置。
+
+宿主重启时逐个恢复已启用插件。不兼容、启动失败的实例显示异常并保留设置，管理员可重新启动、停用或切换版本；
+其他插件、原生转发和管理端继续运行。运行中的插件进程退出时，也不会撤销整个宿主的运行配置。
+命中故障插件绑定的请求仍遵循既有拒绝或委托策略；入口认证插件失败不会绕过认证，插件 Provider 不可用时不能选择它执行请求。
+
+| 操作 | 删除什么 | 保留什么 |
+| --- | --- | --- |
+| 停用 | 不删除；新请求不再使用 | 配置、密钥、私有数据和版本 |
+| 删除配置 | 该配置及其密钥、私有数据、版本配置快照；无法撤销 | 已安装版本 |
+| 删除版本 | 所选制品、对应配置快照及其已无引用的下载认证；最后一个版本还会清理来源规则；被配置或在途调用引用时不能删除 | 其他版本与配置、共享下载认证 |
+| 卸载插件 | 确认范围内的配置、数据、版本、来源规则及已无引用的下载认证 | 其他插件仍使用的下载认证、审计记录 |
+
+卸载不是跨多个请求的事务；失败时会显示已完成结果，可重试剩余步骤，不会扩大到确认后新增的配置。只想暂时停用时不要卸载。
+完整卸载后重新安装可选择新的来源，不再沿用旧来源限制。独立创建但未被删除版本使用的下载认证不会被顺带删除。
+需要保留数据时，删除前按[部署、备份与恢复](../deploy/README.md)保存备份。
+
+开发插件见 [SDK](../backend/crates/gateway-plugin/sdk/README.md) 与 [插件 CLI](../backend/apps/plugin-cli/README.md)；
+完整示例在独立的 `codex-proxy-plugins` 仓库维护。HTTP 字段与限制见 [API 参考](api.md#12-插件管理)。
diff --git a/docs/theme.md b/docs/theme.md
index 371b43529..0febe0ab8 100644
--- a/docs/theme.md
+++ b/docs/theme.md
@@ -54,8 +54,8 @@
 
 | 场景 | 参考入口 | 关注点 |
 | --- | --- | --- |
-| 页面头部 | [BasePageHeader](../frontend/src/components/base/BasePageHeader.vue)、[系统概览](../frontend/src/views/dashboard/components/DashboardContent.vue) | 简短标题、必要的统计范围或状态、就近操作 |
-| 内容与指标 | [BaseCard](../frontend/src/components/base/BaseCard.vue)、[用量概览卡片](../frontend/src/views/usage/components/UsageSummaryCards.vue) | 可选说明、紧凑摘要、数值与辅助信息的主次 |
+| 页面头部 | `@codex-proxy/ui` 的 `BasePageHeader`、[系统概览](../frontend/src/views/dashboard/components/DashboardContent.vue) | 简短标题、必要的统计范围或状态、就近操作 |
+| 内容与指标 | `@codex-proxy/ui` 的 `BaseCard`、[用量概览卡片](../frontend/src/views/usage/components/UsageSummaryCards.vue) | 可选说明、紧凑摘要、数值与辅助信息的主次 |
 | 表单帮助 | [API Key 账号字段](../frontend/src/views/accounts/components/AccountApiKeyFields.vue) | 直接命名字段，在对应位置提供短提示和示例 |
 
 ## 架构概览
@@ -77,24 +77,18 @@ flowchart LR
 
 核心职责保持分离：
 
-| 层 | 文件 | 职责 |
+| 层 | 入口 | 职责 |
 | --- | --- | --- |
-| 公开入口 | [`theme/index.ts`](../frontend/src/theme/index.ts) | 只汇总稳定的外部 API，不承载实现 |
-| 领域类型 | [`theme/types.ts`](../frontend/src/theme/types.ts) | 唯一类型文件，包含持久化模型、解析结果与内部 Map 契约 |
-| 设计输入 | [`theme/core/constants.ts`](../frontend/src/theme/core/constants.ts) | 默认 Seed、预置主题元数据、尺寸与可编辑白名单 |
-| 颜色算法 | [`theme/core/color.ts`](../frontend/src/theme/core/color.ts) | Ant Design 色板角色、色调混合、透明度与对比度 |
-| Map 派生 | [`theme/derive/colors.ts`](../frontend/src/theme/derive/colors.ts) | Surface、Primary、Semantic、Preset 与数据色 Map |
-| Component 派生 | [`theme/derive/components.ts`](../frontend/src/theme/derive/components.ts) | 尺寸、阴影和 Component Token Map |
-| 输入边界 | [`theme/core/normalize.ts`](../frontend/src/theme/core/normalize.ts) | 持久化配置与直接覆盖值的规范化 |
-| 解析编排 | [`theme/core/resolve.ts`](../frontend/src/theme/core/resolve.ts) | 串联 Seed → Map → Alias → Component |
-| Token 编译 | [`theme/core/tokens.ts`](../frontend/src/theme/core/tokens.ts) | 从类型化 Map 和短角色表生成 CSS Variables |
-| 浏览器适配 | [`theme/runtime/browser.ts`](../frontend/src/theme/runtime/browser.ts) | 将解析结果提交为根作用域运行时样式表 |
+| 基础组件 | `@codex-proxy/ui` | 稳定组件与通用函数，不承载业务状态 |
+| 主题算法 | `@codex-proxy/ui/theme` | 规范化配置，派生 Seed → Map → Alias → Component，生成并提交 CSS Variables |
+| 样式 | `@codex-proxy/ui/styles.css` | 基线、组件样式与完整工具类样式 |
+| Tailwind 合同 | `@codex-proxy/ui/tailwind.css` | 公开 Token 名称，供应用自己的 Tailwind 构建使用 |
 | 状态 | [`stores/modules/theme.ts`](../frontend/src/stores/modules/theme.ts) | 持久化配置、系统明暗偏好、切换动作与动画 |
 | 编辑器状态 | [`useThemeEditor.ts`](../frontend/src/views/theme/composables/useThemeEditor.ts) | 草稿、修改计数、恢复与保存 |
-| 样式桥接 | [`styles/index.css`](../frontend/src/styles/index.css) | 将 CSS Token 暴露为 Tailwind CSS 4 utilities |
-| 样式基线 | [`styles/base.css`](../frontend/src/styles/base.css) | 通过 `@layer base` 提供浏览器基线，通过 `@utility` 提供通用原生滚动条 |
-| 静态基元 | [`styles/tokens.css`](../frontend/src/styles/tokens.css) | 只保留白色、透明色和作用域 `color-scheme` |
 
+独立仓库 `codex-proxy-ui` 是管理端和官方插件页面的共享组件源码；组件不得反向依赖管理端 Store、路由或 API。管理端通过 `@codex-proxy/ui` 公开入口消费组件，插件页面把组件和样式编译进自身静态资源，不在运行时借用宿主模块。
+插件页面的标题与副标题由宿主呈现，内容区只渲染业务；主题变化通过宿主桥同步，接入方式见
+[SDK 页面与宿主桥](../backend/crates/gateway-plugin/sdk/docs/capabilities.md#页面与宿主桥)。
 `theme/` 根目录只保留公开入口 `index.ts` 和唯一类型文件 `types.ts`；内部实现按 `core/`、`derive/`、`runtime/` 分层，不增加嵌套 barrel。
 纯派生模块不访问 DOM，`theme/runtime/browser.ts` 不包含派生规则，Theme Store 不复制算法。
 普通 Map 字段按 camelCase → kebab-case 统一生成 `--cp-*`；Semantic 与 Preset Color 仅维护各自的短角色表。
@@ -154,8 +148,7 @@ interface ThemeCustomization {
 Container 保证 3:1。功能色 Hover/Active 相对中性 Container 保证 3:1，Base 不做该校正。`text` 依据页面、
 容器、浮层和交互填充等中性 Surface 校正；`on-container` 单独依据语义 Container 的默认、Hover、Active 三态
 校正到至少 4.5:1，避免为了彩色底对比度而削弱中性表面上的颜色辨识度。
-`ensureContrast` 以每步 1% 的黑/白混合寻找满足所有配对的颜色；不能满足全部约束时返回最弱配对表现最好的候选，
-因此不承诺任意互相矛盾的自定义前景/背景组合都能达标。
+对比度校正由 UI 库的主题算法统一执行；互相矛盾的自定义前景/背景组合不保证全部达标。
 
 分类、图表与数据强调继续使用 Ant Design Preset Color 的角色结构。Blue、Green、Orange、Red 分别复用
 `colorInfo`、`colorSuccess`、`colorWarning`、`colorError`，保证通用彩色与可编辑语义 Seed 同源；没有语义对应的
@@ -178,7 +171,7 @@ Preset 的实心色使用 P6，普通 Container、Strong Container 与边界按
 Input、阴影与其他 Component Token 从 Fill、Surface、Primary 和 Semantic 派生，不在常量文件维护整套颜色表。
 
 正常文字同时检查 Layout、Container、Elevated、文字交互背景、三级 Fill，以及控件透明填充在各宿主上的合成色
-和选中 / 选中 Hover 背景（新增配对用于浅色，暗色保持既有中性表面校正）。正文、标题和 Secondary 至少 7:1，
+和浅色的选中 / 选中 Hover 背景。正文、标题和 Secondary 至少 7:1，
 Tertiary 至少 5.5:1，Quaternary 至少 4.5:1；这些是相对全部上述表面的最低目标，对 Container 的实测比值通常更高。
 Disabled 保留独立的弱化颜色，不承担正常信息。控件填充由文字 Seed 和透明度派生，placeholder 继续消费
 Quaternary；主按钮白字与功能色文字遵循各自的容器配对规则。
@@ -220,48 +213,32 @@ Token 直接覆盖时不会自动重算同组件的其他状态；需要保持
 | Scrollbar | `--cp-scrollbar-thumb-bg / hover-bg` |
 | BrandMark | `--cp-brand-mark-bg` |
 
-主按钮的颜色在 Component 派生入口统一生成：文字保留 `colorTextLightSolid`，默认背景从 Primary Seed 校正到
-4.5:1，Hover/Active 在该背景上分别混入 8% / 16% 黑色，使白字对比度逐级增强；明暗模式共用此规则。
-这组组件状态与全局 `colorPrimaryHover/Active` 分工明确，调整按钮不会反向改写主色 Seed。
-Input、Select、Textarea 与 NumberInput 共用 Input Component Token，普通按钮和图标按钮分别使用 Button Secondary 与
-Icon Button Secondary Token。组件合同统一，明暗配方分别派生：浅色需要改善宿主背景上的辨识度，暗色保留已有的
-Surface 混色与填充层次，不把浅色配方直接套入暗色。暗色输入的聚焦态直接复用原有 Hover 背景与外圈，
-浅色两态都使用 Container 背景与半透明主色外圈，保证点击前后不切换形态。
+组件状态由 UI 库的 Component 派生层统一生成，页面不维护混色系数：
 
-浅色填充与 Surface 共用外观距离，色源和透明度同步平滑过渡。中性基线的色源保留 `colorTextBase` 的色相与
-饱和度，明度向白色提升一半；控件常态、按钮 Hover / Active 的透明度为 7.5% / 10.5% / 14%，避免直接叠白后发灰。
-带色温主题直接使用文字 Seed，常态取 Secondary Fill 强度的 78%，按钮 Hover / Active 为 9% / 12%，
-保留与 Surface 一致的深浅层级。透明填充随页面、卡片和浮层的宿主背景自然合成。
-输入控件常态保持无边，Hover 与 Focus 均使用 Container 背景（默认浅色为白色）和同色、同宽的 3px 半透明主色
-外圈；两种状态的外圈都不受装饰性阴影强度影响。暗色同样将 Hover 与 Focus 的背景、外圈和装饰阴影统一派生。
+| 角色 | 状态与可读性约束 |
+| --- | --- |
+| 主按钮 | 白字背景至少达到 4.5:1；Hover / Active 加深，不反向改写 Primary Seed |
+| 输入控件 | Input、Select、Textarea、NumberInput 共用 Token；常态无边，Hover 与 Focus 保持相同背景和外圈 |
+| 次级操作 | 普通按钮与图标按钮各用自己的 Secondary Token；透明填充与宿主表面合成，`ghost` 无常态底色 |
+| 表格 | 表头、斑马纹、Hover 独立派生；固定列使用不透明合成背景，选中行保留 Primary 语义 |
+| 错误与焦点 | Hover / Focus 不覆盖错误反馈；焦点外圈不受装饰性阴影强度影响 |
+| 浮层头部 | 浅色取 Secondary Fill，深色取 Tertiary Fill；箭头与头部使用同一 Token，不借用表格背景 |
 
-浅色表头、斑马纹、行 Hover 使用独立的内容填充，中性基线透明度为 9.5% / 4.5% / 9%；带色温主题分别复用
-Tertiary / Quaternary / Tertiary 的混色强度（6% / 3.5% / 6%），让斑马纹可辨、Hover 再深一档。
-这些值先与 Container 合成为不透明背景，避免固定列透出滚动内容。暗色表头、斑马纹和行 Hover 继续分别消费
-Tertiary Fill、Quaternary Fill 和 Text Hover，保持已有颜色。
-表格数据单元格的背景统一使用 150ms 淡入淡出，覆盖普通行、斑马纹和选中行，固定列同步过渡；系统偏好减少动态效果时关闭。
-
-选中行使用 Primary Container；浅色选中行 Hover 使用 Primary Container Hover，暗色仅混入 4% 正文色以轻微提亮，
-保留选中语义。错误状态使用 Error Container 与独立外圈，Hover 或 Focus 不覆盖错误反馈；`ghost` 延续无常态底色的
-轻操作角色。输入焦点外圈不乘以 `shadowStrength`，关闭装饰性阴影不会移除焦点反馈。
-
-结构化浮层头部统一使用 `--cp-popover-header-bg`：浅色从 Secondary Fill 派生，
-深色从 Tertiary Fill 派生。健康时间线朝向头部的箭头也使用该值；
-不要把浮层头部重新绑定到表格斑马纹或普通悬停背景。该 Token 可在主题编辑器中单独调整。
+明暗模式分别派生，但共用组件合同。表格背景过渡覆盖普通行、选中行和固定列，尊重减少动态效果偏好。
 
 Theme Editor 只开放真正由对应组件消费的 Component Token。全局 Alias 不放进组件目录，避免一次覆盖同时改变
 多个无关组件。
 
 应用内品牌图标使用 [`AppBrandMark.vue`](../frontend/src/components/AppBrandMark.vue)：浅色模式取
 `colorBgSpotlight`，深色模式取 `colorBgElevated`，保持中性暗面与白色图形；浏览器 favicon 继续使用固定黑白
-图标，不随主题改变。
+图标，不随主题改变，由 `frontend/public/favicon.svg` 提供，页面通过 `/favicon.svg` 引用。
 
 ### 通用颜色消费
 
 主题层禁止声明账号套餐、推理类型或具体页面名称。业务组件只能选择通用 Preset Color 角色，例如 Cyan Container、
 Purple Strong Container 或 Purple Solid；同一组颜色仍由运行时色板统一派生。`styles/tokens.css` 只保留白色、透明色与
 作用域 `color-scheme`，不保存可换肤值或业务标识色。账户活动热力图以 Success Container 为起点、Success Solid
-为终点，按 22% / 46% / 70% 生成中间密度；浅色与暗色使用同一规则，因此不会在浅色背景退化成近白方块。
+为终点生成中间密度；浅色与暗色使用同一规则。
 图表数据系列也只引用通用 Preset Color Token。
 
 ## 预置主题
@@ -386,12 +363,12 @@ Input、Button Secondary 与 Icon Button Secondary 的三个背景 Token 支持
 仅当值需要在 CSS 函数、SVG 或局部派生中参与计算时，直接读取 `var(--cp-*)`。不在页面组件中重新实现色阶、
 对比度或明暗算法。
 
-`@theme inline` 只注册 Tailwind 名称，不保存主题值。注册表按基础、排版、颜色、圆角、阴影、间距与尺寸排序；
+共享包的 `styles/tailwind.css` 是唯一 `@theme inline` 注册表，只注册 Tailwind 名称，不保存主题值。注册表按基础、排版、颜色、圆角、阴影、间距与尺寸排序；
 颜色再按基元、表面、主色与链接、语义、预设、数据、组件分组。
 Preset 家族按字母排序，每个家族固定使用 `container → container-strong → border → solid → text → on-container`。主题值由
 `initializeTheme()` 在 Vue 挂载前动态生成并提交，不增加 `theme:generate`、`theme:check` 或构建期快照。
 
-全局元素基线统一放进 `styles/base.css` 的 `@layer base`，确保组件 utility 可以按 Tailwind 层级正常覆盖；可复用的
+全局元素基线统一放进共享包 `styles/base.css` 的 `@layer base`，确保组件 utility 可以按 Tailwind 层级正常覆盖；可复用的
 原生滚动条声明使用 Tailwind CSS 4 `@utility`。组件内能等价表达的简单 SVG、渐变、原生外观与伪元素优先使用
 utility / arbitrary variant；Vue Transition、跨浏览器 Range、动态富文本 `:deep()`、复杂纹理与关键帧继续保留局部
 `<style scoped>`，不为追求原子化牺牲可读性。
@@ -419,7 +396,7 @@ utility / arbitrary variant；Vue Transition、跨浏览器 Range、动态富文
 1. 在唯一的 `theme/types.ts` 中声明 Seed、Map 或 Alias 字段。
 2. 在 `theme/core/normalize.ts` 定义合法输入边界。
 3. 在对应派生模块集中生成字段；普通 Map 字段会自动进入 `ThemeTokens` 完整输出。
-4. 如需 Tailwind utility，在 `styles/index.css` 的 `@theme inline` 中映射。
+4. 如需 Tailwind utility，在 `codex-proxy-ui/src/styles/tailwind.css` 的 `@theme inline` 中映射。
 5. 只在确实需要用户控制时加入 Theme Editor；派生细节默认只读。
 
 ### 增加 Component Token
diff --git a/frontend/eslint.config.ts b/frontend/eslint.config.ts
index 6074a0fc0..81677acfc 100644
--- a/frontend/eslint.config.ts
+++ b/frontend/eslint.config.ts
@@ -1,3 +1,4 @@
+// @env node
 import type { ESLint, Rule } from 'eslint'
 import antfu from '@antfu/eslint-config'
 
@@ -64,7 +65,7 @@ const templateStylePlugin = {
 export default antfu(
   {
     type: 'app',
-    ignores: ['dist', 'coverage', 'pnpm-workspace.yaml'],
+    ignores: ['**/dist/**', '**/coverage/**', '**/pnpm-workspace.yaml'],
     formatters: {
       css: true,
       html: true,
diff --git a/frontend/index.html b/frontend/index.html
index 1591d5f5f..e52563499 100644
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -6,7 +6,7 @@
       name="viewport"
       content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover"
     />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg?v=20260801" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>Codex Proxy RS</title>
   </head>
   <body>
diff --git a/frontend/package.json b/frontend/package.json
index 20183be92..98dcd44e2 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -2,7 +2,7 @@
   "name": "codex-proxy-rs-web",
   "type": "module",
   "private": true,
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@12.6.0",
   "scripts": {
     "dev": "vite --host 0.0.0.0",
     "typecheck": "vue-tsc -b --pretty false",
@@ -14,32 +14,28 @@
     "format:check": "pnpm run lint"
   },
   "dependencies": {
-    "@ant-design/colors": "^8.0.1",
-    "@ant-design/fast-color": "^3.0.1",
     "@boxicons/vue": "1.0.1",
+    "@codex-proxy/ui": "github:zyycn/codex-proxy-ui#v0.1.0",
     "@fontsource-variable/inter": "^5.3.0",
     "@fontsource-variable/jetbrains-mono": "^5.3.0",
     "@lucide/vue": "^1.47.0",
     "@vueuse/core": "^15.0.0",
-    "@vueuse/integrations": "^15.0.0",
     "axios": "^1.20.0",
+    "css-tree": "^3.2.1",
     "dayjs": "^1.11.23",
-    "dompurify": "^3.4.15",
     "echarts": "^6.1.0",
     "es-toolkit": "^1.52.0",
     "gsap": "^3.15.0",
-    "marked": "^18.0.13",
     "pinia": "^4.0.3",
     "pinia-plugin-persistedstate": "^4.7.1",
-    "sortablejs": "^1.15.7",
     "vue": "^3.5.43",
     "vue-router": "^5.3.1"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^9.5.1",
     "@tailwindcss/vite": "^4.3.3",
+    "@types/css-tree": "^3.2.0",
     "@types/node": "^26.6.2",
-    "@types/sortablejs": "^1.15.9",
     "@vitejs/plugin-vue": "^6.0.9",
     "@vue/tsconfig": "^0.9.1",
     "eslint": "^10.11.0",
diff --git a/frontend/pnpm-lock.yaml b/frontend/pnpm-lock.yaml
index 418bbf863..329072c72 100644
--- a/frontend/pnpm-lock.yaml
+++ b/frontend/pnpm-lock.yaml
@@ -1,3 +1,161 @@
+---
+lockfileVersion: '9.0'
+
+importers:
+
+  .:
+    configDependencies: {}
+    packageManagerDependencies:
+      pnpm:
+        specifier: 12.6.0
+        version: 12.6.0
+
+packages:
+
+  '@pnpm/exe.android-arm64@12.6.0':
+    resolution: {integrity: sha512-kviIHft9h02q+7N2In7tSL9T/HRUSGwYmU74YPtsWU5ee7vgqPyC0JT6RRX6miW+NxX1CvHgQxg69qq1qTLJYQ==}
+    cpu: [arm64]
+    os: [android]
+
+  '@pnpm/exe.android-x64@12.6.0':
+    resolution: {integrity: sha512-CT8aJKLq2mtZFE71pr4E5Z2xHL8uGnRGr+NclDqsXlVF4SVcQ2QAs14mWi0C8gjT4hbmi+Q0lJRRIkMAWfjjng==}
+    cpu: [x64]
+    os: [android]
+
+  '@pnpm/exe.darwin-arm64@12.6.0':
+    resolution: {integrity: sha512-rafpVkjzugKBMxSvGQd5wK1x5eOTkD/+lcJIFHeQhvd+BJ8kDisOOvwhQDrpGd4vd2Fx+hhW0P2Ptt638OlhFg==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@pnpm/exe.darwin-x64@12.6.0':
+    resolution: {integrity: sha512-72Jpuv1m24gI8zUNcaylYpBWEhBzz1VPhnDIU2GYM2eRP+KsOqVLwV78i+JrihI39zY2NNXmaN4eAKX1inpaDQ==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@pnpm/exe.freebsd-x64@12.6.0':
+    resolution: {integrity: sha512-LON4QgNy1w/XF4uySZIyC/5hEB0oGdelXsY9tSKqstER+2j2X2oHz67skD11RRd/HWFRtMr64shQZ4I9ZoZ0zg==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@pnpm/exe.linux-arm64-musl@12.6.0':
+    resolution: {integrity: sha512-BdDpX+DeaMUc5x6WNcE6FkmFy36NwrBbBvwsZU737Zt3u1fTY+iKFPchjEQNCM4rT6q6xvF2oN3ZwExGsJCkxQ==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@pnpm/exe.linux-arm64@12.6.0':
+    resolution: {integrity: sha512-8h2sNoIhHDpHDYqZZCh9PXr6krqW10btb0GHVGuw710muDHlFAHMtUG2ogmaHge6zJG1xgY4Y7mwX5g/LWvrYg==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.linux-ppc64@12.6.0':
+    resolution: {integrity: sha512-ld6xgcEhFCFrsVsJhbmdmR714PnsEspO/Ij8w0/D7OSiz2hYGu3fZd5tKRxOI5m6H6Gl0/RRFAPncTHbsgXVjQ==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.linux-riscv64@12.6.0':
+    resolution: {integrity: sha512-HIbImydoC3J8NFt+8MXfhTCf5rO6NjCMyinSAHac0VmV8uCHw+kbQkyAzxV84rzz9ZOzmBOnj0b1N461UIYGsw==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.linux-s390x@12.6.0':
+    resolution: {integrity: sha512-DjSqT7+BZ/lWcDHwNMuzsRVfyxUimh+D54Xw4tSWbdVVQhtWtNMUyI93LVnwCmsoEpar2gC3SFeAgywx37svKQ==}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.linux-x64-musl@12.6.0':
+    resolution: {integrity: sha512-31lKeGPmRE6xfV6I3VjaEGVFRei14pl/zgoFDK4w+UkbJqOuNl2Ht3O1GuqNIg3Gl14qTEb4kZRAYFHXifDx9A==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@pnpm/exe.linux-x64@12.6.0':
+    resolution: {integrity: sha512-qFWBneHJAJ73W4whtbaFOL1M/7DBC6ILHXuxc7ZPtEhfPuT1zeZiGrmKHoMAfJA+mcm6xhOFljqVTUS+00Jabw==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.win32-arm64@12.6.0':
+    resolution: {integrity: sha512-OhfefXEEykZlslSUhR8PPRe6MVPV3Oink/dVfIecE5velpc7j80cZYsHlaDrtRDcm3TPwQHkaRW1SJ1efX9oFg==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@pnpm/exe.win32-x64@12.6.0':
+    resolution: {integrity: sha512-L2tuyrD2+Imgxs3VK/ST/2L3xD6vDP0ktJQxM0TaGw7TbAQEMq+RMc8iK6Ew7Id579uzjJe8jSfJID2ZGsOHCA==}
+    cpu: [x64]
+    os: [win32]
+
+  pnpm@12.6.0:
+    resolution: {integrity: sha512-PvaPlRyxEawgS0paFvCy3fDaVqluBBPoHYVdnwtV75JnFHCQKOHNAMQFwsX7e56OxNxGd3yAXQNzwvL/AP0g7A==}
+    engines: {node: '>=18.*'}
+    hasBin: true
+
+snapshots:
+
+  '@pnpm/exe.android-arm64@12.6.0':
+    optional: true
+
+  '@pnpm/exe.android-x64@12.6.0':
+    optional: true
+
+  '@pnpm/exe.darwin-arm64@12.6.0':
+    optional: true
+
+  '@pnpm/exe.darwin-x64@12.6.0':
+    optional: true
+
+  '@pnpm/exe.freebsd-x64@12.6.0':
+    optional: true
+
+  '@pnpm/exe.linux-arm64-musl@12.6.0':
+    optional: true
+
+  '@pnpm/exe.linux-arm64@12.6.0':
+    optional: true
+
+  '@pnpm/exe.linux-ppc64@12.6.0':
+    optional: true
+
+  '@pnpm/exe.linux-riscv64@12.6.0':
+    optional: true
+
+  '@pnpm/exe.linux-s390x@12.6.0':
+    optional: true
+
+  '@pnpm/exe.linux-x64-musl@12.6.0':
+    optional: true
+
+  '@pnpm/exe.linux-x64@12.6.0':
+    optional: true
+
+  '@pnpm/exe.win32-arm64@12.6.0':
+    optional: true
+
+  '@pnpm/exe.win32-x64@12.6.0':
+    optional: true
+
+  pnpm@12.6.0:
+    optionalDependencies:
+      '@pnpm/exe.android-arm64': 12.6.0
+      '@pnpm/exe.android-x64': 12.6.0
+      '@pnpm/exe.darwin-arm64': 12.6.0
+      '@pnpm/exe.darwin-x64': 12.6.0
+      '@pnpm/exe.freebsd-x64': 12.6.0
+      '@pnpm/exe.linux-arm64': 12.6.0
+      '@pnpm/exe.linux-arm64-musl': 12.6.0
+      '@pnpm/exe.linux-ppc64': 12.6.0
+      '@pnpm/exe.linux-riscv64': 12.6.0
+      '@pnpm/exe.linux-s390x': 12.6.0
+      '@pnpm/exe.linux-x64': 12.6.0
+      '@pnpm/exe.linux-x64-musl': 12.6.0
+      '@pnpm/exe.win32-arm64': 12.6.0
+      '@pnpm/exe.win32-x64': 12.6.0
+
+---
 lockfileVersion: '9.0'
 
 settings:
@@ -8,15 +166,12 @@ importers:
 
   .:
     dependencies:
-      '@ant-design/colors':
-        specifier: ^8.0.1
-        version: 8.0.1
-      '@ant-design/fast-color':
-        specifier: ^3.0.1
-        version: 3.0.1
       '@boxicons/vue':
         specifier: 1.0.1
         version: 1.0.1(vue@3.5.43(typescript@6.0.3))
+      '@codex-proxy/ui':
+        specifier: github:zyycn/codex-proxy-ui#v0.1.0
+        version: https://codeload.github.com/zyycn/codex-proxy-ui/tar.gz/8cee8e7698347a58a23f73ad7a3a171ba54ba512(axios@1.20.0)(change-case@5.4.4)(vue@3.5.43(typescript@6.0.3))
       '@fontsource-variable/inter':
         specifier: ^5.3.0
         version: 5.3.0
@@ -29,18 +184,15 @@ importers:
       '@vueuse/core':
         specifier: ^15.0.0
         version: 15.0.0(vue@3.5.43(typescript@6.0.3))
-      '@vueuse/integrations':
-        specifier: ^15.0.0
-        version: 15.0.0(axios@1.20.0)(change-case@5.4.4)(sortablejs@1.15.7)(vue@3.5.43(typescript@6.0.3))
       axios:
         specifier: ^1.20.0
         version: 1.20.0
+      css-tree:
+        specifier: ^3.2.1
+        version: 3.2.1
       dayjs:
         specifier: ^1.11.23
         version: 1.11.23
-      dompurify:
-        specifier: ^3.4.15
-        version: 3.4.15
       echarts:
         specifier: ^6.1.0
         version: 6.1.0
@@ -50,18 +202,12 @@ importers:
       gsap:
         specifier: ^3.15.0
         version: 3.15.0
-      marked:
-        specifier: ^18.0.13
-        version: 18.0.13
       pinia:
         specifier: ^4.0.3
         version: 4.0.3(@vue/devtools-api@8.2.1)(typescript@6.0.3)(vue@3.5.43(typescript@6.0.3))
       pinia-plugin-persistedstate:
         specifier: ^4.7.1
         version: 4.7.1(pinia@4.0.3(@vue/devtools-api@8.2.1)(typescript@6.0.3)(vue@3.5.43(typescript@6.0.3)))
-      sortablejs:
-        specifier: ^1.15.7
-        version: 1.15.7
       vue:
         specifier: ^3.5.43
         version: 3.5.43(typescript@6.0.3)
@@ -75,12 +221,12 @@ importers:
       '@tailwindcss/vite':
         specifier: ^4.3.3
         version: 4.3.3(vite@8.3.0(@types/node@26.6.2)(jiti@2.7.0)(yaml@2.9.0))
+      '@types/css-tree':
+        specifier: ^3.2.0
+        version: 3.2.0
       '@types/node':
         specifier: ^26.6.2
         version: 26.6.2
-      '@types/sortablejs':
-        specifier: ^1.15.9
-        version: 1.15.9
       '@vitejs/plugin-vue':
         specifier: ^6.0.9
         version: 6.0.9(vite@8.3.0(@types/node@26.6.2)(jiti@2.7.0)(yaml@2.9.0))(vue@3.5.43(typescript@6.0.3))
@@ -232,6 +378,13 @@ packages:
     resolution: {integrity: sha512-y7/yvZ2TPAnR9+jnc00klvNNLkJiXFFrQA/hlLCcxA9a2A4zQIOimyFQ9XfwYKiGD1fb5GY8vbKIIgO8d5Tb2A==}
     engines: {node: '>= 20.12.0'}
 
+  '@codex-proxy/ui@https://codeload.github.com/zyycn/codex-proxy-ui/tar.gz/8cee8e7698347a58a23f73ad7a3a171ba54ba512':
+    resolution: {gitHosted: true, integrity: sha512-bTHv1d338Lli+euMXImrjnqDVpBdNVKdu1PrGCPB9Zanz8Hr2ReHugK1sLiSuOtv9tYNofdeWhaQXKLmnddy4Q==, tarball: https://codeload.github.com/zyycn/codex-proxy-ui/tar.gz/8cee8e7698347a58a23f73ad7a3a171ba54ba512}
+    version: 0.1.0
+    engines: {node: '>=24'}
+    peerDependencies:
+      vue: ^3.5.0
+
   '@dprint/formatter@0.5.1':
     resolution: {integrity: sha512-cdZUrm0iv/FnnY3CKE2dEcVhNEzrC551aE2h2mTFwQCRBrqyARLDnb7D+3PlXTUVp3s34ftlnGOVCmhLT9DeKA==}
 
@@ -713,6 +866,9 @@ packages:
     peerDependencies:
       vite: ^5.2.0 || ^6 || ^7 || ^8
 
+  '@types/css-tree@3.2.0':
+    resolution: {integrity: sha512-J5KXmk6BFIepOT7280FdFyNs4c5fh0Uee0otjKEvzchrRs38Ii9qminqc4ds0L19X8Zd/rT+brR9jkBthygjWw==}
+
   '@types/debug@4.1.13':
     resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
 
@@ -740,9 +896,6 @@ packages:
   '@types/node@26.6.2':
     resolution: {integrity: sha512-X1P21scMv4zGKLYqjdGjaKa7COa0RKVYYZZN/NfvLQ1JegxFhdhpZG/Lyn8AXx6CDUavKAd11v6BvfpkDByK8g==}
 
-  '@types/sortablejs@1.15.9':
-    resolution: {integrity: sha512-7HP+rZGE2p886PKV9c9OJzLBI6BBJu1O7lJGYnPyG3fS4/duUCcngkNCjsLwIMV+WMqANe3tt4irrXHSIe68OQ==}
-
   '@types/trusted-types@2.0.7':
     resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==}
 
@@ -1103,6 +1256,10 @@ packages:
     resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
     engines: {node: '>= 8'}
 
+  css-tree@3.2.1:
+    resolution: {integrity: sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA==}
+    engines: {node: ^10 || ^12.20.0 || ^14.13.0 || >=15.0.0}
+
   cssesc@3.0.0:
     resolution: {integrity: sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==}
     engines: {node: '>=4'}
@@ -1172,10 +1329,6 @@ packages:
     resolution: {integrity: sha512-YGRs8knHhKHVShLkFET/rWAU8kmHbOV5LwN938RHI0pljAJ1Gf6SzXsSmRaEzcXTtOOmVqJ5+WtQPL5uigY50Q==}
     engines: {node: '>=14'}
 
-  enhanced-resolve@5.24.3:
-    resolution: {integrity: sha512-PwKooW9JUzh5chmYfHM3IQl5OkK2u2Nm011MgeZrss3JmFraUx/fqrf78kk8GUMYoibx/14MdwTl/1WKkG7TpQ==}
-    engines: {node: '>=10.13.0'}
-
   enhanced-resolve@5.24.5:
     resolution: {integrity: sha512-L1l8TNvomm6UVW5B253AGxQagSQr+vGwhMlrrfRS2qmhx46AMpMVJKQYLvWYbysTMY8VoicOvzHzoHMbyzB+4A==}
     engines: {node: '>=10.13.0'}
@@ -1843,8 +1996,8 @@ packages:
   markdown-table@3.0.4:
     resolution: {integrity: sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==}
 
-  marked@18.0.13:
-    resolution: {integrity: sha512-xTxVzZsBFwunP6HDmtBkabUQEYArnP7/rMDGmPj9SlrKlQ4i8MdYVow+nJL0eOqwpUqhzBoTBRADGN6uYwPyOw==}
+  marked@18.0.14:
+    resolution: {integrity: sha512-mBHK6FBHuBAlhgRe88w9F0O1AbwwXJUcQibUbC/QcdTbVGAD7aWza+xt3N6oT/jCZx3/OMeS+8rnuiHZcQ9s7A==}
     engines: {node: '>= 20'}
     hasBin: true
 
@@ -1891,6 +2044,9 @@ packages:
   mdast-util-to-string@4.0.0:
     resolution: {integrity: sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==}
 
+  mdn-data@2.27.1:
+    resolution: {integrity: sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ==}
+
   mdn-data@2.34.0:
     resolution: {integrity: sha512-OgIlLv0NxJKVW4GTSAoEgpRGd4F2XCqGinK0MsMlBCCS/Zcm2/LsbercNWNA7PeMMcjl75NnI97eqyo7zkdxWA==}
 
@@ -2614,6 +2770,32 @@ snapshots:
       fast-wrap-ansi: 0.2.2
       sisteransi: 1.0.5
 
+  '@codex-proxy/ui@https://codeload.github.com/zyycn/codex-proxy-ui/tar.gz/8cee8e7698347a58a23f73ad7a3a171ba54ba512(axios@1.20.0)(change-case@5.4.4)(vue@3.5.43(typescript@6.0.3))':
+    dependencies:
+      '@ant-design/colors': 8.0.1
+      '@ant-design/fast-color': 3.0.1
+      '@lucide/vue': 1.47.0(vue@3.5.43(typescript@6.0.3))
+      '@vueuse/core': 15.0.0(vue@3.5.43(typescript@6.0.3))
+      '@vueuse/integrations': 15.0.0(axios@1.20.0)(change-case@5.4.4)(sortablejs@1.15.7)(vue@3.5.43(typescript@6.0.3))
+      dompurify: 3.4.15
+      es-toolkit: 1.52.0
+      gsap: 3.15.0
+      marked: 18.0.14
+      sortablejs: 1.15.7
+      vue: 3.5.43(typescript@6.0.3)
+    transitivePeerDependencies:
+      - async-validator
+      - axios
+      - change-case
+      - drauu
+      - focus-trap
+      - fuse.js
+      - idb-keyval
+      - jwt-decode
+      - nprogress
+      - qrcode
+      - universal-cookie
+
   '@dprint/formatter@0.5.1': {}
 
   '@dprint/markdown@0.21.1': {}
@@ -2889,7 +3071,7 @@ snapshots:
   '@tailwindcss/node@4.3.3':
     dependencies:
       '@jridgewell/remapping': 2.3.5
-      enhanced-resolve: 5.24.3
+      enhanced-resolve: 5.24.5
       jiti: 2.7.0
       lightningcss: 1.32.0
       magic-string: 0.30.21
@@ -2954,6 +3136,8 @@ snapshots:
       tailwindcss: 4.3.3
       vite: 8.3.0(@types/node@26.6.2)(jiti@2.7.0)(yaml@2.9.0)
 
+  '@types/css-tree@3.2.0': {}
+
   '@types/debug@4.1.13':
     dependencies:
       '@types/ms': 2.1.0
@@ -2980,8 +3164,6 @@ snapshots:
     dependencies:
       undici-types: 8.9.0
 
-  '@types/sortablejs@1.15.9': {}
-
   '@types/trusted-types@2.0.7':
     optional: true
 
@@ -3353,6 +3535,11 @@ snapshots:
       shebang-command: 2.0.0
       which: 2.0.2
 
+  css-tree@3.2.1:
+    dependencies:
+      mdn-data: 2.27.1
+      source-map-js: 1.2.1
+
   cssesc@3.0.0: {}
 
   csstype@3.2.3: {}
@@ -3404,11 +3591,6 @@ snapshots:
 
   empathic@2.0.1: {}
 
-  enhanced-resolve@5.24.3:
-    dependencies:
-      graceful-fs: 4.2.11
-      tapable: 2.3.3
-
   enhanced-resolve@5.24.5:
     dependencies:
       graceful-fs: 4.2.11
@@ -4077,7 +4259,7 @@ snapshots:
 
   markdown-table@3.0.4: {}
 
-  marked@18.0.13: {}
+  marked@18.0.14: {}
 
   math-intrinsics@1.1.0: {}
 
@@ -4206,6 +4388,8 @@ snapshots:
     dependencies:
       '@types/mdast': 4.0.4
 
+  mdn-data@2.27.1: {}
+
   mdn-data@2.34.0: {}
 
   micromark-core-commonmark@2.0.3:
diff --git a/frontend/pnpm-workspace.yaml b/frontend/pnpm-workspace.yaml
index 0dde9bd9d..4f2737b20 100644
--- a/frontend/pnpm-workspace.yaml
+++ b/frontend/pnpm-workspace.yaml
@@ -1,4 +1,5 @@
 autoInstallPeers: false
 
-minimumReleaseAgeExclude:
-  - vite@8.1.3
+# Git 依赖通过 prepack 生成产物；信任自有 UI 仓库，实际提交仍由锁文件固定。
+allowBuilds:
+  '@codex-proxy/ui@git+https://github.com/zyycn/codex-proxy-ui.git': true
diff --git a/frontend/src/App.vue b/frontend/src/App.vue
index 1dfbad621..8d0c05d35 100644
--- a/frontend/src/App.vue
+++ b/frontend/src/App.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
-import { RouterView } from 'vue-router'
+import { BaseToast } from '@codex-proxy/ui'
 
-import { BaseToast } from '@/components/base/BaseToast'
+import { RouterView } from 'vue-router'
 </script>
 
 <template>
diff --git a/frontend/src/api/index.ts b/frontend/src/api/index.ts
index e8f1d3a45..65dcfe7e9 100644
--- a/frontend/src/api/index.ts
+++ b/frontend/src/api/index.ts
@@ -16,6 +16,10 @@ export * from './modules/backups'
 // Dashboard 聚合
 export * from './modules/dashboard'
 
+// 插件管理
+export * from './modules/plugin-extensions'
+export * from './modules/plugins'
+
 // 模型定价
 export * from './modules/pricing'
 
diff --git a/frontend/src/api/modules/accounts.ts b/frontend/src/api/modules/accounts.ts
index 7dafccf77..05d177d7f 100644
--- a/frontend/src/api/modules/accounts.ts
+++ b/frontend/src/api/modules/accounts.ts
@@ -119,6 +119,7 @@ export interface AccountModelAccess {
 }
 
 export interface Account {
+  capabilities: AccountCapabilities
   outboundProxyEndpoint: string | null
   id: string
   name: string
@@ -153,6 +154,16 @@ export interface Account {
   groups: AccountGroupRef[]
 }
 
+export interface AccountCapabilities {
+  quota: boolean
+  quotaRefresh: boolean
+  profile: boolean
+  subscription: boolean
+  avatar: boolean
+  resetCredits: boolean
+  consumeResetCredit: boolean
+}
+
 export interface AccountQuotaForecast {
   period: 'weekly' | 'monthly'
   targetDays: number
@@ -207,6 +218,7 @@ export interface AccountListResponse {
   items: Account[]
   page: AccountPageMeta
   summary: AccountSummary
+  providers: string[]
 }
 
 export interface AccountRefreshResponse {
@@ -351,6 +363,20 @@ export interface AccountOAuthStartResponse {
   expiresAt: string
 }
 
+export interface AccountProvider {
+  provider: string
+  credentials: {
+    import: Record<string, unknown> | null
+    login: { inputSchema: Record<string, unknown>, completion: 'callback' | 'poll' } | null
+    refresh: boolean
+    export: boolean
+  }
+}
+
+export type AccountAuthorizationPollResponse
+  = { status: 'pending', retryAfterMs: number }
+    | { status: 'complete', accountIds: string[] }
+
 // 请求参数类型：仅定义 API 边界的形状，调用方不依赖显式声明。
 interface AccountListParams {
   page: number
@@ -373,6 +399,7 @@ interface AccountResetCreditConsumeParam extends AccountIdParam {
 }
 
 interface AccountUpdateParam {
+  connection?: { baseUrl: string, transport: ApiKeyConfiguration['transport'], apiKey?: string }
   outboundProxyUrl?: string
   outboundProxyId?: string
   accountId: string
@@ -400,7 +427,7 @@ interface AccountDeleteParams {
   accountIds: string[]
 }
 
-interface AccountImportSettings {
+export interface AccountImportSettings {
   notes?: string
   enabled: boolean
   concurrencyLimit: number | null
@@ -431,6 +458,7 @@ interface AccountOAuthStartParam {
   provider: string
   name: string
   accountId?: string
+  input?: Record<string, unknown>
 }
 
 interface AccountOAuthCompleteParam {
@@ -560,7 +588,7 @@ export function importAccounts(data: AccountImportParam, options: RequestOptions
   return request<AccountImportResponse>({
     url: '/api/admin/accounts/import',
     method: 'POST',
-    data,
+    ...providerInputBody(data),
     ...options,
   })
 }
@@ -569,7 +597,7 @@ export function createAccountImportTask(data: CreateAccountImportTaskParam) {
   return request<AccountImportTask>({
     url: '/api/admin/accounts/import-tasks',
     method: 'POST',
-    data,
+    ...providerInputBody(data),
   })
 }
 
@@ -623,19 +651,46 @@ export function deleteAccounts(data: AccountDeleteParams, options: RequestOption
   })
 }
 
-export function startAccountOAuth(data: AccountOAuthStartParam) {
-  return request<AccountOAuthStartResponse>({
-    url: '/api/admin/accounts/oauth/start',
-    method: 'POST',
-    data,
+export function getAccountProviders(options: RequestOptions = {}) {
+  return request<AccountProvider[]>({
+    url: '/api/admin/accounts/providers',
+    method: 'GET',
+    ...options,
   })
 }
 
-export function completeAccountOAuth(data: AccountOAuthCompleteParam) {
+export function startAccountOAuth(data: AccountOAuthStartParam, options: RequestOptions = {}) {
+  return request<AccountOAuthStartResponse>({
+    url: '/api/admin/accounts/oauth/start',
+    method: 'POST',
+    ...providerInputBody(data),
+    ...options,
+  })
+}
+
+function providerInputBody(data: object) {
+  // Provider 文档是不透明 JSON，先编码，避免 HTTP 客户端合并配置时过滤特殊字段名。
+  return { headers: { 'Content-Type': 'application/json' }, data: JSON.stringify(data) }
+}
+
+export function completeAccountOAuth(data: AccountOAuthCompleteParam, options: RequestOptions = {}) {
   return request<AccountOAuthCompleteResponse>({
     url: '/api/admin/accounts/oauth/complete',
     method: 'POST',
     data,
+    ...options,
+  })
+}
+
+export function pollAccountAuthorization(
+  data: Omit<AccountOAuthCompleteParam, 'callbackUrl'> & { callbackUrl?: string },
+  options: RequestOptions = {},
+) {
+  return request<AccountAuthorizationPollResponse>({
+    url: '/api/admin/accounts/oauth/poll',
+    method: 'POST',
+    data,
+    ...options,
   })
 }
 
@@ -645,18 +700,10 @@ export interface ApiKeyConfiguration {
 }
 
 export function getAccountDetail(data: AccountIdParam, options: RequestOptions = {}) {
-  return request<{ account: Account, credentialConfiguration?: ApiKeyConfiguration }>({
+  return request<{ account: Account, credentialConfiguration?: Record<string, unknown> }>({
     url: '/api/admin/accounts/detail',
     method: 'GET',
     params: data,
     ...options,
   })
 }
-
-export function updateAccountApiKey(data: { accountId: string, baseUrl: string, transport: ApiKeyConfiguration['transport'], apiKey?: string, settings?: AccountUpdateParam }) {
-  return request<{ accountId: string }>({
-    url: '/api/admin/accounts/rotate',
-    method: 'POST',
-    data: { provider: 'openai', ...data },
-  })
-}
diff --git a/frontend/src/api/modules/api-keys.ts b/frontend/src/api/modules/api-keys.ts
index 8f2707bb3..deae50fc6 100644
--- a/frontend/src/api/modules/api-keys.ts
+++ b/frontend/src/api/modules/api-keys.ts
@@ -1,12 +1,13 @@
 import type { RequestOptions } from '../request'
 import type { AccountGroupRef } from './account-groups'
-import type { ClientProfileSelection, XaiClientProfileSelection } from './client-profiles'
+import type { ClientProfileSelection, ProviderRequestProfile, ProviderRequestProfiles, XaiClientProfileSelection } from './client-profiles'
 import request from '../request'
 
 export type ApiKeyRoutingScope = 'all' | 'groups'
 export type ApiKeyBudgetPeriod = 'daily' | 'weekly' | 'all'
 
 export interface ApiKey {
+  providerRequestProfileOverrides: ProviderRequestProfiles
   openaiClientProfileOverride: ClientProfileSelection | null
   xaiClientProfileOverride: XaiClientProfileSelection | null
 
@@ -62,9 +63,6 @@ interface ApiKeyListParams {
 }
 
 export interface ApiKeyWriteParam {
-  openaiClientProfileOverride: ClientProfileSelection | null
-  xaiClientProfileOverride: XaiClientProfileSelection | null
-
   name: string
   label: string | null
   groupIds: string[]
@@ -76,9 +74,11 @@ export interface ApiKeyWriteParam {
 
 interface ApiKeyUpdateParam extends ApiKeyWriteParam {
   id: string
+  providerRequestProfileOverrides: Record<string, ProviderRequestProfile | null>
 }
 
 interface ApiKeyCreateParam extends ApiKeyWriteParam {
+  providerRequestProfileOverrides: ProviderRequestProfiles
   customKey?: string
 }
 
diff --git a/frontend/src/api/modules/client-profiles.ts b/frontend/src/api/modules/client-profiles.ts
index c8b55a9ad..49038bf34 100644
--- a/frontend/src/api/modules/client-profiles.ts
+++ b/frontend/src/api/modules/client-profiles.ts
@@ -1,5 +1,86 @@
 import request from '../request'
 
+export type ProviderRequestProfile = Record<string, unknown>
+export type ProviderRequestProfiles = Record<string, ProviderRequestProfile>
+export type ProviderRequestProfileUpdates = Record<string, ProviderRequestProfile | null>
+
+export interface ProviderRequestProfilePreset {
+  id: string
+  label: string
+  description?: string | null
+  configuration: ProviderRequestProfile
+}
+
+export interface ProviderRequestProfileOptions {
+  presets: ProviderRequestProfilePreset[]
+  defaultConfiguration: ProviderRequestProfile
+  globalConfiguration: ProviderRequestProfile
+}
+
+export interface ProviderRequestProfileTarget {
+  osType: string
+  osVersion: string
+  arch: string
+  terminal: string
+}
+
+export interface ProviderRequestProfileAttribute {
+  label: string
+  value: string
+}
+
+export interface ProviderRequestProfileRelease {
+  status: 'unchecked' | 'current' | 'update_available' | 'failed'
+  checkedAt?: string | null
+  latestVersion?: string | null
+  latestBuild?: string | null
+  publishedAt?: string | null
+  minimumSystemVersion?: string | null
+  hardwareRequirements?: string | null
+  downloadUrl?: string | null
+  downloadSize?: number | null
+  signaturePresent?: boolean | null
+  error?: string | null
+}
+
+export interface ProviderRequestProfilePreview {
+  configuration: ProviderRequestProfile
+  source: 'global' | 'override'
+  product: string
+  version: string
+  build?: string | null
+  target: ProviderRequestProfileTarget
+  userAgent: string
+  attributes: ProviderRequestProfileAttribute[]
+  verifiedAt?: string | null
+  release?: ProviderRequestProfileRelease | null
+}
+
+export function getClientProfileProviders() {
+  return request<{ providers: string[] }>({
+    url: '/api/admin/settings/client-profiles',
+    method: 'GET',
+    silent: true,
+  })
+}
+
+export function getProviderClientProfileOptions(provider: string) {
+  return request<ProviderRequestProfileOptions>({
+    url: `/api/admin/settings/client-profiles/${encodeURIComponent(provider)}`,
+    method: 'GET',
+    silent: true,
+  })
+}
+
+export function previewProviderClientProfile(provider: string, configuration: ProviderRequestProfile | null) {
+  return request<ProviderRequestProfilePreview>({
+    url: `/api/admin/settings/client-profiles/${encodeURIComponent(provider)}/preview`,
+    method: 'POST',
+    data: { configuration },
+    silent: true,
+  })
+}
+
 export interface ClientProfileSelection {
   client: 'desktop' | 'cli'
   platform: 'macos' | 'linux' | 'windows'
diff --git a/frontend/src/api/modules/plugin-extensions.ts b/frontend/src/api/modules/plugin-extensions.ts
new file mode 100644
index 000000000..ad4aa873a
--- /dev/null
+++ b/frontend/src/api/modules/plugin-extensions.ts
@@ -0,0 +1,157 @@
+import type { RequestConfig, RequestOptions } from '../request'
+import { API_BASE_URL } from '../constants'
+import request, { requestRaw } from '../request'
+
+const MAXIMUM_MANAGEMENT_BODY_BYTES = 1024 * 1024
+
+export interface PluginManagementTarget {
+  instanceId: string
+  artifactSha256: string
+  revision: number
+}
+
+export interface PluginManagementPage {
+  id: string
+  title: string
+  description: string | null
+  entry: string
+  icon: string | null
+}
+
+export interface PluginManagementRoute {
+  method: string
+  path: string
+  requestContentTypes: string[]
+  responseContentTypes: string[]
+}
+
+export interface PluginManagementResource {
+  path: string
+  contentType: string
+  public: boolean
+}
+
+export interface PluginManagementCallback {
+  path: string
+  responseContentTypes: string[]
+}
+
+export interface PluginManagementView {
+  target: PluginManagementTarget
+  name: string
+  configurationSchema: Record<string, unknown>
+  pages: PluginManagementPage[]
+  routes: PluginManagementRoute[]
+  resources: PluginManagementResource[]
+  callbacks: PluginManagementCallback[]
+}
+
+export interface PluginManagementRawRequest {
+  method: string
+  path: string
+  query?: string
+  contentType?: string
+  body?: ArrayBuffer
+}
+
+export interface PluginManagementCallbackTicket {
+  state: string
+  expiresAtMs: number
+}
+
+export function getPluginManagementViews(options: RequestOptions = {}) {
+  return request<PluginManagementView[]>({
+    url: '/api/admin/plugins/extensions',
+    method: 'GET',
+    ...options,
+  })
+}
+
+export function getPluginManagementResource(
+  target: PluginManagementTarget,
+  path: string,
+  options: RequestOptions = {},
+) {
+  return requestPluginManagementRaw({
+    url: `${pluginManagementTargetPath(target)}/resources/${encodePluginPath(path)}`,
+    method: 'GET',
+    ...options,
+  })
+}
+
+export function callPluginManagementRoute(
+  target: PluginManagementTarget,
+  call: PluginManagementRawRequest,
+  options: RequestOptions = {},
+) {
+  const query = call.query ? `?${call.query}` : ''
+  return requestPluginManagementRaw({
+    url: `${pluginManagementTargetPath(target)}/api/${encodePluginPath(call.path)}${query}`,
+    method: call.method,
+    data: call.body?.byteLength ? call.body : undefined,
+    headers: call.contentType ? { 'Content-Type': call.contentType } : undefined,
+    ...options,
+  })
+}
+
+export function callPluginModelResponses(
+  target: PluginManagementTarget,
+  clientKeyId: string,
+  body: string,
+  signal: AbortSignal,
+) {
+  const query = new URLSearchParams({ clientKeyId })
+  return fetch(`${API_BASE_URL}${pluginManagementTargetPath(target)}/models/responses?${query}`, {
+    method: 'POST',
+    body,
+    cache: 'no-store',
+    credentials: 'same-origin',
+    headers: {
+      'accept': 'application/json, text/event-stream',
+      'Content-Type': 'application/json',
+    },
+    redirect: 'error',
+    referrerPolicy: 'no-referrer',
+    signal,
+  })
+}
+
+export function createPluginManagementCallbackTicket(
+  target: PluginManagementTarget,
+  data: { path: string, ttlSeconds: number },
+  options: RequestOptions = {},
+) {
+  return request<PluginManagementCallbackTicket>({
+    url: `${pluginManagementTargetPath(target)}/callback-tickets`,
+    method: 'POST',
+    data,
+    ...options,
+  })
+}
+
+export function pluginManagementCallbackPath(
+  target: PluginManagementTarget,
+  path: string,
+  state: string,
+) {
+  return `/plugins/callbacks/${encodeURIComponent(target.instanceId)}/${encodeURIComponent(target.artifactSha256)}/${target.revision}/${encodePluginPath(path)}?state=${encodeURIComponent(state)}`
+}
+
+function pluginManagementTargetPath(target: PluginManagementTarget) {
+  return `/api/admin/plugins/extensions/${encodeURIComponent(target.instanceId)}/${encodeURIComponent(target.artifactSha256)}/${target.revision}`
+}
+
+function encodePluginPath(path: string) {
+  return path.split('/').map(segment => encodeURIComponent(segment)).join('/')
+}
+
+function requestPluginManagementRaw(config: RequestConfig) {
+  return requestRaw(config, {
+    maximumBytes: MAXIMUM_MANAGEMENT_BODY_BYTES,
+    accept: ({ header }) => {
+      const policy = header('content-security-policy')
+      return policy?.split(';').some(directive => directive.trim() === 'sandbox allow-scripts') === true
+        && header('x-content-type-options')?.toLowerCase() === 'nosniff'
+    },
+  })
+}
diff --git a/frontend/src/api/modules/plugins.ts b/frontend/src/api/modules/plugins.ts
new file mode 100644
index 000000000..048ff94de
--- /dev/null
+++ b/frontend/src/api/modules/plugins.ts
@@ -0,0 +1,493 @@
+import type { RequestOptions } from '../request'
+
+import { API_BASE_URL } from '../constants'
+import request from '../request'
+
+export interface PluginSourceEgress {
+  id: string
+  revision: number
+}
+
+export type PluginSource
+  = | { kind: 'builtin', release: string }
+    | { kind: 'upload' }
+    | { kind: 'url', url: string, credential_ids: string[], outbound_proxy?: PluginSourceEgress }
+    | { kind: 'github', repository: string, tag: string, asset: string, credential_ids: string[], outbound_proxy?: PluginSourceEgress }
+
+export interface PluginContribution {
+  id: string
+  version: number
+  stages: string[]
+  inputFormats: string[]
+  outputFormats: string[]
+}
+
+export type PluginIconAsset = string | { light: string, dark: string }
+
+export interface PluginPermissionDescription {
+  permission: string
+  label: string
+  description: string
+}
+
+export interface PluginArtifactMetadata {
+  pluginId: string
+  version: string
+  name: string
+  displayName: string
+  publisher: string
+  author: string | null
+  description: string
+  license: string
+  icon: PluginIconAsset | null
+  sha256: string
+  platforms: string[]
+  contributes: Record<string, PluginContribution>
+  requestedPermissions: string[]
+  permissionDescriptions: PluginPermissionDescription[]
+  configurationSchema: Record<string, unknown>
+  secretFields: string[]
+  stateNamespaces: {
+    namespace: string
+    schemaVersion: number
+    schemaSha256: string
+    schema: Record<string, unknown>
+    maximumRecords: number
+    maximumBytes: number
+    maximumValueBytes: number
+    migratesFrom: number[]
+  }[]
+}
+
+export interface PluginArtifact {
+  metadata: PluginArtifactMetadata
+  source: PluginSource
+  installedAt: string
+  acceptedAt: string | null
+}
+
+export type PluginUpdateSource
+  = | { kind: 'builtin' }
+    | { kind: 'upload' }
+    | { kind: 'url', url: string }
+    | { kind: 'github', repository: string }
+
+export interface PluginUpdateSourceBinding {
+  pluginId: string
+  source: PluginUpdateSource
+  policy: PluginUpdatePolicy
+  outboundProxyId?: string | null
+}
+
+export type PluginUpdatePolicy
+  = | { kind: 'manual' }
+    | { kind: 'stable' }
+    | { kind: 'pinned', tag: string, allow_prerelease: boolean }
+
+export interface PluginUpdateCheck {
+  binding: PluginUpdateSourceBinding
+  release: PluginRelease
+}
+
+export type DownloadPurpose = 'metadata' | 'artifact'
+
+export interface PluginSourceCredential {
+  id: string
+  name: string
+  origin: string
+  pathPrefix: string
+  purposes: DownloadPurpose[]
+}
+
+export type PluginSourceAuthentication
+  = | { kind: 'github', token: string }
+    | { kind: 'bearer', token: string }
+    | { kind: 'basic', username: string, password: string }
+    | { kind: 'header', name: string, value: string }
+
+export interface CreatePluginSourceCredentialRequest {
+  name: string
+  origin: string
+  pathPrefix: string
+  purposes: DownloadPurpose[]
+  authentication: PluginSourceAuthentication
+}
+
+export interface GithubReleaseQuery {
+  repository: string
+  tag: string | null
+  allowPrerelease: boolean
+}
+
+export interface PluginReleaseAsset {
+  name: string
+  size: number
+  sha256: string | null
+}
+
+export interface PluginRelease {
+  repository: string
+  tag: string
+  name: string
+  prerelease: boolean
+  assets: PluginReleaseAsset[]
+  queriedAt: string
+  expiresAt: string
+}
+
+export interface QueryPluginReleaseRequest {
+  query: GithubReleaseQuery
+  credentialIds: string[]
+  outboundProxyId?: string | null
+}
+
+export type RemotePluginLocation
+  = | { kind: 'url', url: string, sha256: string | null }
+    | {
+      kind: 'github'
+      repository: string
+      tag: string
+      asset: string
+      allow_prerelease: boolean
+      sha256: string | null
+    }
+
+interface RemotePluginRequest {
+  credentialIds: string[]
+  outboundProxyId?: string | null
+  location: RemotePluginLocation
+}
+
+export interface InstallRemotePluginRequest extends RemotePluginRequest {
+  pluginId: string
+  version: string
+  location: RemotePluginLocation & { sha256: string }
+}
+
+export interface VerifyRemotePluginRequest extends RemotePluginRequest {
+  expectedPluginId?: string | null
+}
+
+export interface VerifiedPluginArtifact {
+  metadata: PluginArtifactMetadata
+  source: PluginSource
+}
+
+export type PluginFailurePolicy = 'reject' | 'delegate' | 'observe'
+
+export interface PluginFrontendIdentityBinding {
+  principal: string
+  clientKeyId: string
+}
+
+export interface PluginCapabilityBinding {
+  contribution: string
+  stage: string
+  order: number
+  failurePolicy: PluginFailurePolicy
+  providerIds: string[]
+  models: string[]
+  clientKeyIds: string[]
+  accountGroupIds: string[]
+  identityBindings: PluginFrontendIdentityBinding[]
+}
+
+export type PluginInstanceRuntimeStatus
+  = | 'disabled'
+    | 'awaiting_publication'
+    | 'preparing'
+    | 'running'
+    | 'blocked'
+    | 'preparation_failed'
+    | 'faulted'
+    | 'draining'
+
+export interface PluginInstanceRuntimeFailure {
+  code: string
+  message: string
+}
+
+export interface PluginInstanceRuntime {
+  status: PluginInstanceRuntimeStatus
+  actualRevision: number | null
+  actualArtifactSha256: string | null
+  failure: PluginInstanceRuntimeFailure | null
+  drainingRevisions: number[]
+  retainedContinuations: number
+}
+
+export interface PluginInstance {
+  id: string
+  name: string
+  artifactSha256: string
+  enabled: boolean
+  configurationRequired: boolean
+  configuration: Record<string, unknown>
+  secretFields: string[]
+  bindings: PluginCapabilityBinding[]
+  revision: number
+  running: boolean
+  publishedRevision: number | null
+  runtime: PluginInstanceRuntime
+}
+
+export interface ConfigurePluginInstanceRequest {
+  creationId?: string
+  expectedRevision?: number
+  replaceInstances?: { id: string, expectedRevision: number }[]
+  name: string
+  artifactSha256: string
+  enabled: boolean
+  configuration: Record<string, unknown>
+  secrets?: Record<string, string>
+  bindings: PluginCapabilityBinding[]
+}
+
+export interface PluginMutationResponse {
+  configRevision: number
+}
+
+export interface PluginArtifactMutationResponse extends PluginMutationResponse {
+  artifact: PluginArtifact
+  defaultInstanceId: string | null
+  configurationRequired: boolean
+}
+
+interface PluginInstanceMutationResponse extends PluginMutationResponse {
+  id: string
+}
+
+export interface PluginRollbackPlan {
+  instanceRevision: number
+  currentVersion: string
+  targets: { artifactSha256: string, version: string, platforms: string[] }[]
+}
+
+export function getPluginArtifacts(options: RequestOptions = {}) {
+  return request<PluginArtifact[]>({
+    url: '/api/admin/plugins/artifacts',
+    method: 'GET',
+    ...options,
+  })
+}
+
+export function pluginArtifactIconPath(sha256: string, theme: 'light' | 'dark') {
+  return `${API_BASE_URL}/api/admin/plugins/artifacts/${encodeURIComponent(sha256)}/icon?theme=${theme}`
+}
+
+export function uploadPluginArtifact(file: File, sha256: string, options: RequestOptions = {}) {
+  return request<PluginArtifactMutationResponse>({
+    url: '/api/admin/plugins/artifacts/upload',
+    method: 'POST',
+    params: { sha256 },
+    data: file,
+    headers: {
+      'Content-Type': 'application/octet-stream',
+    },
+    timeout: 120000,
+    ...options,
+  })
+}
+
+export function verifyUploadedPlugin(file: File, options: RequestOptions = {}) {
+  return request<VerifiedPluginArtifact>({
+    url: '/api/admin/plugins/artifacts/upload/verify',
+    method: 'POST',
+    data: file,
+    headers: {
+      'Content-Type': 'application/octet-stream',
+    },
+    timeout: 120000,
+    ...options,
+  })
+}
+
+export function installRemotePlugin(data: InstallRemotePluginRequest, options: RequestOptions = {}) {
+  return request<PluginArtifactMutationResponse>({
+    url: '/api/admin/plugins/artifacts/install',
+    method: 'POST',
+    data,
+    timeout: 120000,
+    ...options,
+  })
+}
+
+export function acceptPluginArtifact(data: { sha256: string }, options: RequestOptions = {}) {
+  return request<PluginArtifactMutationResponse>({
+    url: '/api/admin/plugins/artifacts/accept',
+    method: 'POST',
+    data,
+    ...options,
+  })
+}
+
+export function verifyRemotePlugin(data: VerifyRemotePluginRequest, options: RequestOptions = {}) {
+  return request<VerifiedPluginArtifact>({
+    url: '/api/admin/plugins/artifacts/verify',
+    method: 'POST',
+    data,
+    timeout: 120000,
+    ...options,
+  })
+}
+
+export function deletePluginArtifact(data: { sha256: string }, options: RequestOptions = {}) {
+  return request<void>({
+    url: '/api/admin/plugins/artifacts/delete',
+    method: 'POST',
+    data,
+    ...options,
+  })
+}
+
+export function queryPluginRelease(data: QueryPluginReleaseRequest, options: RequestOptions = {}) {
+  return request<PluginRelease>({
+    url: '/api/admin/plugins/releases/query',
+    method: 'POST',
+    data,
+    timeout: 30000,
+    ...options,
+  })
+}
+
+export function getPluginSourceCredentials(options: RequestOptions = {}) {
+  return request<PluginSourceCredential[]>({
+    url: '/api/admin/plugins/source-credentials',
+    method: 'GET',
+    ...options,
+  })
+}
+
+export function createPluginSourceCredential(data: CreatePluginSourceCredentialRequest, options: RequestOptions = {}) {
+  return request<PluginSourceCredential>({
+    url: '/api/admin/plugins/source-credentials',
+    method: 'POST',
+    data,
+    ...options,
+  })
+}
+
+export function deletePluginSourceCredential(data: { id: string }, options: RequestOptions = {}) {
+  return request<PluginMutationResponse>({
+    url: '/api/admin/plugins/source-credentials/delete',
+    method: 'POST',
+    data,
+    ...options,
+  })
+}
+
+export function getPluginUpdateSources(options: RequestOptions = {}) {
+  return request<PluginUpdateSourceBinding[]>({
+    url: '/api/admin/plugins/update-sources',
+    method: 'GET',
+    ...options,
+  })
+}
+
+export function updatePluginSource(data: PluginUpdateSourceBinding, options: RequestOptions = {}) {
+  return request<PluginMutationResponse>({
+    url: '/api/admin/plugins/update-sources',
+    method: 'POST',
+    data,
+    ...options,
+  })
+}
+
+export function checkPluginUpdate(data: { pluginId: string, credentialIds: string[] }, options: RequestOptions = {}) {
+  return request<PluginUpdateCheck>({
+    url: '/api/admin/plugins/updates/check',
+    method: 'POST',
+    data,
+    ...options,
+  })
+}
+
+export function getPluginInstances(options: RequestOptions = {}) {
+  return request<PluginInstance[]>({
+    url: '/api/admin/plugins/instances',
+    method: 'GET',
+    ...options,
+  })
+}
+
+export function createPluginInstance(data: ConfigurePluginInstanceRequest, options: RequestOptions = {}) {
+  return request<PluginInstanceMutationResponse>({
+    url: '/api/admin/plugins/instances',
+    method: 'POST',
+    data,
+    ...options,
+  })
+}
+
+export function updatePluginInstance(data: { id: string, instance: ConfigurePluginInstanceRequest }, options: RequestOptions = {}) {
+  return request<PluginInstanceMutationResponse>({
+    url: '/api/admin/plugins/instances/update',
+    method: 'POST',
+    data,
+    ...options,
+  })
+}
+
+export function getPluginRollbackPlan(id: string, options: RequestOptions = {}) {
+  return request<PluginRollbackPlan>({
+    url: '/api/admin/plugins/instances/rollback-plan',
+    method: 'GET',
+    params: { id },
+    ...options,
+  })
+}
+
+export function rollbackPluginInstance(data: { id: string, target: { artifactSha256: string, expectedRevision: number } }, options: RequestOptions = {}) {
+  return request<PluginInstanceMutationResponse>({
+    url: '/api/admin/plugins/instances/rollback',
+    method: 'POST',
+    data,
+    ...options,
+  })
+}
+
+export function disablePluginInstance(data: { id: string }, options: RequestOptions = {}) {
+  return request<PluginMutationResponse>({
+    url: '/api/admin/plugins/instances/disable',
+    method: 'POST',
+    data,
+    ...options,
+  })
+}
+
+export function deletePluginInstance(data: { id: string }, options: RequestOptions = {}) {
+  return request<PluginMutationResponse>({
+    url: '/api/admin/plugins/instances/delete',
+    method: 'POST',
+    data,
+    ...options,
+  })
+}
+
+export interface PluginVersionPlan {
+  instanceRevision: number
+  artifactSha256: string
+  configuration: Record<string, unknown>
+  secretFields: string[]
+  bindings: PluginCapabilityBinding[]
+  restored: boolean
+}
+
+export function getPluginVersionPlan(id: string, artifactSha256: string, options: RequestOptions = {}) {
+  return request<PluginVersionPlan>({
+    url: '/api/admin/plugins/instances/version-plan',
+    method: 'GET',
+    params: { id, artifactSha256 },
+    ...options,
+  })
+}
+
+export function switchPluginVersion(data: { id: string, target: { artifactSha256: string, expectedRevision: number } }, options: RequestOptions = {}) {
+  return request<PluginInstanceMutationResponse>({
+    url: '/api/admin/plugins/instances/switch-version',
+    method: 'POST',
+    data,
+    timeout: 120000,
+    ...options,
+  })
+}
diff --git a/frontend/src/api/modules/settings.ts b/frontend/src/api/modules/settings.ts
index 5c4ecb790..8f8c4c6bb 100644
--- a/frontend/src/api/modules/settings.ts
+++ b/frontend/src/api/modules/settings.ts
@@ -1,13 +1,14 @@
 import type { RequestOptions } from '../request'
 import type { RequestLocation } from '../types/request-location'
-import type { ClientProfileSelection, XaiClientProfileSelection } from './client-profiles'
+import type { ClientProfileSelection, ProviderRequestProfiles, ProviderRequestProfileUpdates, XaiClientProfileSelection } from './client-profiles'
 import request from '../request'
 
 export type RotationStrategy = 'smart' | 'quota_reset_priority' | 'round_robin' | 'sticky'
 
 export interface RuntimeSettings {
-  openaiClientProfile: ClientProfileSelection
-  xaiClientProfile: XaiClientProfileSelection
+  providerRequestProfiles: ProviderRequestProfiles
+  openaiClientProfile: ClientProfileSelection | null
+  xaiClientProfile: XaiClientProfileSelection | null
 
   requestLocationEnabled: boolean
   requestLocation: RequestLocation
@@ -76,7 +77,9 @@ export function getSettings(options: RequestOptions = {}) {
   })
 }
 
-type UpdateSettingsParam = Omit<RuntimeSettings, 'updatedAt'>
+type UpdateSettingsParam = Omit<RuntimeSettings, 'updatedAt' | 'openaiClientProfile' | 'xaiClientProfile' | 'providerRequestProfiles'> & {
+  providerRequestProfiles: ProviderRequestProfileUpdates
+}
 
 export function updateSettings(data: UpdateSettingsParam) {
   return request<RuntimeSettings>({
diff --git a/frontend/src/api/modules/usage.ts b/frontend/src/api/modules/usage.ts
index 2de801872..214a66dde 100644
--- a/frontend/src/api/modules/usage.ts
+++ b/frontend/src/api/modules/usage.ts
@@ -529,6 +529,15 @@ export function getUsageRecordInsightsOverview(data: UsageRangeQuery, options: R
   })
 }
 
+export function getUsageProviders(data: { startTime?: string, endTime?: string }, options: RequestOptions = {}) {
+  return request<string[]>({
+    url: '/api/admin/usage/providers',
+    method: 'GET',
+    params: data,
+    ...options,
+  })
+}
+
 export function getUsageRecordInsightsDiagnostics(data: UsageDiagnosticsQuery, options: RequestOptions = {}) {
   return request<UsageDiagnosticsResponse>({
     url: '/api/admin/usage/insights/diagnostics',
diff --git a/frontend/src/api/request.ts b/frontend/src/api/request.ts
index cb89426ed..ad49fba49 100644
--- a/frontend/src/api/request.ts
+++ b/frontend/src/api/request.ts
@@ -3,8 +3,8 @@ import type {
   AxiosRequestConfig,
 } from 'axios'
 
+import { toast } from '@codex-proxy/ui'
 import axios from 'axios'
-import { toast } from '@/components/base/BaseToast'
 import { API_BASE_URL, API_TIMEOUT_MS } from './constants'
 import { ApiError, normalizeApiError, normalizeApiResponseError } from './error'
 
@@ -17,7 +17,23 @@ export interface RequestOptions {
   timeout?: number
 }
 
-type RequestConfig = AxiosRequestConfig & RequestOptions
+export type RequestConfig = AxiosRequestConfig & RequestOptions
+
+export interface RawResponseMeta {
+  status: number
+  header: (name: string) => string | undefined
+}
+
+export interface RawResponse {
+  status: number
+  contentType: string
+  body: ArrayBuffer
+}
+
+export interface RawResponseOptions {
+  maximumBytes: number
+  accept: (response: RawResponseMeta) => boolean
+}
 
 const http: AxiosInstance = axios.create({
   baseURL: API_BASE_URL,
@@ -95,3 +111,73 @@ export default async function request<T = unknown>(config: RequestConfig): Promi
     throw error
   }
 }
+
+/**
+ * 使用同一管理会话请求原始字节。只有调用方识别的隔离响应才会作为业务正文返回；
+ * 其余响应继续按 Admin 错误信封处理，不绕过会话失效与统一错误提示。
+ */
+export async function requestRaw(
+  config: RequestConfig,
+  options: RawResponseOptions,
+): Promise<RawResponse> {
+  const generation = sessionGeneration
+  try {
+    const response = await http.request<ArrayBuffer>({
+      ...config,
+      responseType: 'arraybuffer',
+      validateStatus: () => true,
+    })
+    const body = response.data
+    const meta: RawResponseMeta = {
+      status: response.status,
+      header: name => rawHeader(response.headers, name),
+    }
+    if (options.accept(meta)) {
+      if (body.byteLength > options.maximumBytes)
+        throw new ApiError('响应内容超过大小限制', 502, undefined, rawHeader(response.headers, 'x-request-id'), 'http')
+      return {
+        status: response.status,
+        contentType: rawHeader(response.headers, 'content-type') ?? 'application/octet-stream',
+        body,
+      }
+    }
+
+    const decoded = decodeRawEnvelope(body)
+    const normalized = normalizeApiResponseError({ ...response, data: decoded })
+    if (normalized)
+      throw normalized
+    throw new ApiError(
+      response.status >= 400 ? `请求失败（HTTP ${response.status}）` : '服务返回了不受支持的响应',
+      response.status,
+      undefined,
+      rawHeader(response.headers, 'x-request-id'),
+      'http',
+    )
+  }
+  catch (error) {
+    if (error instanceof ApiError)
+      return rejectRequest(error, config, generation)
+    if (axios.isAxiosError(error))
+      return rejectRequest(normalizeApiError(error), config, generation)
+    throw error
+  }
+}
+
+function rawHeader(headers: unknown, name: string) {
+  if (!headers || typeof headers !== 'object')
+    return undefined
+  const source = headers as { get?: (key: string) => unknown, [key: string]: unknown }
+  const value = typeof source.get === 'function' ? source.get(name) : source[name]
+  return typeof value === 'string' && value ? value : undefined
+}
+
+function decodeRawEnvelope(body: ArrayBuffer): unknown {
+  if (body.byteLength === 0)
+    return undefined
+  try {
+    return JSON.parse(new TextDecoder().decode(new Uint8Array(body))) as unknown
+  }
+  catch {
+    return undefined
+  }
+}
diff --git a/frontend/src/components/AccountGroupCheckboxGrid.vue b/frontend/src/components/AccountGroupCheckboxGrid.vue
index 6c6750f05..57a9dff02 100644
--- a/frontend/src/components/AccountGroupCheckboxGrid.vue
+++ b/frontend/src/components/AccountGroupCheckboxGrid.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import type { AccountGroup } from '@/api'
 
-import BaseCheckbox from '@/components/base/BaseCheckbox.vue'
+import { BaseCheckbox } from '@codex-proxy/ui'
 
 withDefaults(
   defineProps<{
diff --git a/frontend/src/components/ApiKeyConfigModal.vue b/frontend/src/components/ApiKeyConfigModal.vue
index 3629acb60..a72e1d49e 100644
--- a/frontend/src/components/ApiKeyConfigModal.vue
+++ b/frontend/src/components/ApiKeyConfigModal.vue
@@ -1,13 +1,8 @@
 <script setup lang="ts">
+import { BaseButton, BaseIconButton, BaseModal, BaseScrollbar, BaseSegmented, BaseSwitch } from '@codex-proxy/ui'
+
 import { Apple, Copy, Monitor, Upload } from '@lucide/vue'
 import { computed, shallowRef } from 'vue'
-
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import BaseSwitch from '@/components/base/BaseSwitch.vue'
 import { buildCodexCcSwitchImportDeeplink } from '@/utils/ccswitchImport'
 import {
   buildCodexConfigFiles,
diff --git a/frontend/src/components/AppAboutModal.vue b/frontend/src/components/AppAboutModal.vue
index 64b139223..2786203d1 100644
--- a/frontend/src/components/AppAboutModal.vue
+++ b/frontend/src/components/AppAboutModal.vue
@@ -1,9 +1,9 @@
 <script setup lang="ts">
 import { Github } from '@boxicons/vue'
+import { BaseModal } from '@codex-proxy/ui'
 import { ExternalLink } from '@lucide/vue'
-import { computed } from 'vue'
 
-import BaseModal from '@/components/base/BaseModal/index.vue'
+import { computed } from 'vue'
 
 const props = defineProps<{
   version: { version: string, gitSha: string } | null
diff --git a/frontend/src/components/ProviderFilter.vue b/frontend/src/components/ProviderFilter.vue
new file mode 100644
index 000000000..0fb06ac90
--- /dev/null
+++ b/frontend/src/components/ProviderFilter.vue
@@ -0,0 +1,39 @@
+<script setup lang="ts">
+import { BaseIconButton, BaseSegmented } from '@codex-proxy/ui'
+import { LayoutGrid, RefreshCw } from '@lucide/vue'
+import { computed } from 'vue'
+import { formatProviderLabel, providerIcon } from '@/utils/providers'
+
+const props = withDefaults(defineProps<{
+  providers: string[]
+  disabled?: boolean
+  loading?: boolean
+  error?: string
+}>(), { disabled: false, loading: false, error: '' })
+const emit = defineEmits<{ retry: [] }>()
+const provider = defineModel<string>({ required: true })
+const options = computed(() => [
+  { label: '全部平台', value: '', icon: LayoutGrid },
+  // 数据清理或切换时间范围后，保留已选条件，由用户决定何时清除。
+  ...[...new Set([...props.providers, provider.value])].filter(Boolean).map(value => ({ label: formatProviderLabel(value), value, icon: providerIcon(value) })),
+])
+</script>
+
+<template>
+  <div class="flex min-w-0 max-w-full items-center gap-1">
+    <div class="min-w-0 overflow-x-auto">
+      <BaseSegmented
+        v-model="provider"
+        label="按平台筛选"
+        display="icon"
+        :style="{ width: `${options.length * 40 + 4}px` }"
+        :options="options"
+        :disabled="disabled || loading"
+        :aria-busy="loading"
+      />
+    </div>
+    <BaseIconButton v-if="error" variant="ghost" label="重新加载平台筛选" :title="error" :disabled="disabled || loading" @click="emit('retry')">
+      <RefreshCw class="size-4 text-cp-error" />
+    </BaseIconButton>
+  </div>
+</template>
diff --git a/frontend/src/components/ProviderFilterSegmented.vue b/frontend/src/components/ProviderFilterSegmented.vue
deleted file mode 100644
index 101ae1d1d..000000000
--- a/frontend/src/components/ProviderFilterSegmented.vue
+++ /dev/null
@@ -1,34 +0,0 @@
-<script setup lang="ts">
-import { Openai, Xai } from '@boxicons/vue'
-import { LayoutGrid } from '@lucide/vue'
-
-import { PROVIDER_DISPLAY_NAMES } from '@/utils/providers'
-import BaseSegmented from './base/BaseSegmented.vue'
-
-withDefaults(
-  defineProps<{
-    disabled?: boolean
-  }>(),
-  {
-    disabled: false,
-  },
-)
-
-const provider = defineModel<string>({ required: true })
-
-const providerOptions = [
-  { label: '全部平台', value: '', icon: LayoutGrid },
-  { label: PROVIDER_DISPLAY_NAMES.openai, value: 'openai', icon: Openai },
-  { label: PROVIDER_DISPLAY_NAMES.xai, value: 'xai', icon: Xai },
-]
-</script>
-
-<template>
-  <BaseSegmented
-    v-model="provider"
-    label="按平台筛选"
-    :options="providerOptions"
-    :disabled="disabled"
-    display="icon"
-  />
-</template>
diff --git a/frontend/src/components/ProviderIconGroup.vue b/frontend/src/components/ProviderIconGroup.vue
index 9d84bc0bd..496f41135 100644
--- a/frontend/src/components/ProviderIconGroup.vue
+++ b/frontend/src/components/ProviderIconGroup.vue
@@ -1,7 +1,6 @@
 <script setup lang="ts">
-import { Key, LinkAlt, Openai, Xai } from '@boxicons/vue'
 import { computed } from 'vue'
-import { formatProviderLabel } from '@/utils/providers'
+import { authenticationIcon, formatAuthenticationLabel, formatProviderLabel, providerIcon } from '@/utils/providers'
 
 const props = withDefaults(
   defineProps<{
@@ -15,7 +14,8 @@ const props = withDefaults(
 )
 
 const normalizedProvider = computed(() => (props.provider ?? '').trim().toLowerCase())
-const normalizedAuthenticationKind = computed(() => (props.authenticationKind ?? '').trim().toLowerCase())
+const providerIconComponent = computed(() => normalizedProvider.value ? providerIcon(normalizedProvider.value) : undefined)
+const authenticationIconComponent = computed(() => authenticationIcon(props.authenticationKind))
 const showAuthenticationKind = computed(() => props.authenticationKind !== undefined)
 const groupGapClass = computed(() => {
   if (props.size === 'xs')
@@ -35,13 +35,7 @@ const iconClass = computed(() => {
 
 const providerLabel = computed(() => formatProviderLabel(props.provider, '未知平台'))
 
-const authenticationLabel = computed(() => {
-  if (normalizedAuthenticationKind.value === 'oauth')
-    return 'OAuth'
-  if (normalizedAuthenticationKind.value === 'api_key')
-    return 'API Key'
-  return props.authenticationKind?.trim() || '未知认证类型'
-})
+const authenticationLabel = computed(() => formatAuthenticationLabel(props.authenticationKind))
 </script>
 
 <template>
@@ -51,8 +45,7 @@ const authenticationLabel = computed(() => {
       :class="iconContainerClass"
       :title="providerLabel"
     >
-      <Openai v-if="normalizedProvider === 'openai'" :class="iconClass" />
-      <Xai v-else-if="normalizedProvider === 'xai'" :class="iconClass" />
+      <component :is="providerIconComponent" v-if="providerIconComponent" :class="iconClass" />
       <span v-else class="text-[10px] font-heavy text-cp-text-quaternary">?</span>
     </span>
 
@@ -62,8 +55,7 @@ const authenticationLabel = computed(() => {
       :class="iconContainerClass"
       :title="authenticationLabel"
     >
-      <LinkAlt v-if="normalizedAuthenticationKind === 'oauth'" :class="iconClass" />
-      <Key v-else-if="normalizedAuthenticationKind === 'api_key'" :class="iconClass" />
+      <component :is="authenticationIconComponent" v-if="authenticationIconComponent" :class="iconClass" />
       <span v-else class="text-[10px] font-heavy text-cp-text-quaternary">?</span>
     </span>
 
diff --git a/frontend/src/components/RequestLocationFields.vue b/frontend/src/components/RequestLocationFields.vue
index 9f9707f60..c6c1f4b70 100644
--- a/frontend/src/components/RequestLocationFields.vue
+++ b/frontend/src/components/RequestLocationFields.vue
@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import type { RequestLocation } from '@/api'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
+import { BaseFormItem, BaseInput } from '@codex-proxy/ui'
 
 defineProps<{ disabled?: boolean }>()
 const location = defineModel<RequestLocation>({ required: true })
diff --git a/frontend/src/components/SchemaForm/index.vue b/frontend/src/components/SchemaForm/index.vue
new file mode 100644
index 000000000..864525145
--- /dev/null
+++ b/frontend/src/components/SchemaForm/index.vue
@@ -0,0 +1,153 @@
+<script setup lang="ts">
+import type { InputField } from './schema'
+import { BaseForm, BaseFormItem, BaseIconButton, BaseInput, BasePopover, BaseSelect, BaseTextarea } from '@codex-proxy/ui'
+import { Braces, Info, List } from '@lucide/vue'
+import { computed, nextTick, shallowRef, useTemplateRef } from 'vue'
+import { jsonObjectError, parseJsonObject } from '@/utils/jsonObject'
+import { inputFields } from './schema'
+
+const props = defineProps<{
+  schema: Record<string, unknown>
+  disabled: boolean
+  maximumBytes?: number
+  fieldErrors?: Record<string, string>
+}>()
+const text = defineModel<string>({ required: true })
+const jsonMode = shallowRef(false)
+const root = useTemplateRef<HTMLElement>('root')
+const error = computed(() => jsonObjectError(text.value, props.maximumBytes))
+const value = computed(() => error.value ? null : parseJsonObject(text.value, props.maximumBytes))
+const fields = computed(() => inputFields(props.schema))
+const hasExtra = computed(() => Object.keys(value.value ?? {}).some(key => !fields.value?.some(field => field.key === key)))
+const incompatibleValue = computed(() => fields.value?.some((field) => {
+  const item = inputValue(field.key)
+  if (item === undefined)
+    return false
+  if (field.values)
+    return !field.values.some(option => option === item)
+  if (field.type === 'number' || field.type === 'integer')
+    return typeof item !== 'number' && typeof item !== 'string'
+  return field.type === 'boolean' ? typeof item !== 'boolean' : typeof item !== 'string'
+}) ?? false)
+const showJson = computed(() => jsonMode.value || fields.value === null || hasExtra.value || incompatibleValue.value || Boolean(error.value))
+const empty = computed(() => fields.value?.length === 0 && props.schema.additionalProperties === false && !showJson.value)
+
+function fieldValue(field: InputField) {
+  const item = inputValue(field.key)
+  if (item === undefined)
+    return ''
+  if (field.values)
+    return String(field.values.findIndex(entry => entry === item))
+  return String(item)
+}
+
+function inputValue(key: string) {
+  return value.value && Object.hasOwn(value.value, key) ? value.value[key] : undefined
+}
+
+function fieldOptions(field: InputField) {
+  const options = field.values
+    ? field.values.map((item, index) => ({ value: String(index), label: String(item) }))
+    : [{ value: 'true', label: '是' }, { value: 'false', label: '否' }]
+  return [{ value: '', label: '未填写' }, ...options]
+}
+
+function update(field: InputField, input: string) {
+  let next: unknown
+  if (input === '' && (field.values || field.type !== 'string')) {
+    next = undefined
+  }
+  else if (field.values) {
+    next = field.values[Number(input)]
+  }
+  else if (field.type === 'boolean') {
+    next = input === 'true'
+  }
+  else if (field.type === 'number' || field.type === 'integer') {
+    // 不把尚未输入完整的数字静默替换成 0，保留原值供服务端校验。
+    next = Number.isFinite(Number(input)) ? Number(input) : input
+  }
+  else {
+    next = input
+  }
+  // 计算属性保留合法的特殊字段名，不触发普通对象的原型 setter。
+  text.value = JSON.stringify({ ...value.value, [field.key]: next }, null, 2)
+}
+
+async function focusField(key?: string) {
+  const editableField = key && fields.value?.some(field => field.key === key)
+  if (editableField && jsonMode.value && !error.value && !hasExtra.value && !incompatibleValue.value)
+    jsonMode.value = false
+  await nextTick()
+
+  const control = editableField && !showJson.value
+    ? [...(root.value?.querySelectorAll<HTMLElement>('[data-schema-control]') ?? [])]
+        .find(element => element.dataset.schemaControl === key)
+    : root.value?.querySelector<HTMLElement>('[data-schema-json-control], textarea')
+  control?.focus()
+  return Boolean(control)
+}
+
+defineExpose({ focusField })
+</script>
+
+<template>
+  <div v-if="!empty" ref="root" class="grid gap-3">
+    <BaseForm v-if="showJson">
+      <BaseFormItem label="输入内容" :error="error">
+        <template #extra>
+          <BaseIconButton v-if="fields !== null" label="使用表单" size="sm" variant="secondary" :disabled="disabled || Boolean(error) || hasExtra || incompatibleValue" @click="jsonMode = false">
+            <List class="size-4" />
+          </BaseIconButton>
+        </template>
+        <BaseTextarea v-model="text" :rows="8" :disabled="disabled" spellcheck="false" autocomplete="off" data-schema-json-control />
+      </BaseFormItem>
+    </BaseForm>
+    <BaseForm v-else>
+      <BaseFormItem
+        v-for="(field, index) in fields"
+        :key="field.key"
+        :label="field.label"
+        :required="field.required"
+        :error="fieldErrors?.[field.key]"
+      >
+        <template v-if="field.description" #label-extra>
+          <BasePopover trigger="hover-click" placement="top-start">
+            <template #trigger>
+              <BaseIconButton :label="`${field.label}说明`" class="size-3.5!" :title="undefined">
+                <Info class="size-3.5" />
+              </BaseIconButton>
+            </template>
+            <p class="m-0 max-w-72 p-3 text-cp-xs leading-relaxed text-cp-text-secondary">
+              {{ field.description }}
+            </p>
+          </BasePopover>
+        </template>
+        <template v-if="index === 0" #extra>
+          <BaseIconButton label="编辑 JSON" size="sm" variant="secondary" :disabled="disabled" @click="jsonMode = true">
+            <Braces class="size-4" />
+          </BaseIconButton>
+        </template>
+        <BaseSelect
+          v-if="field.values || field.type === 'boolean'"
+          :model-value="fieldValue(field)"
+          :options="fieldOptions(field)"
+          :disabled="disabled"
+          :data-schema-control="field.key"
+          class="w-full"
+          @update:model-value="update(field, $event)"
+        />
+        <BaseInput
+          v-else
+          :model-value="fieldValue(field)"
+          :type="field.secret ? 'password' : 'text'"
+          :inputmode="field.type === 'integer' ? 'numeric' : field.type === 'number' ? 'decimal' : 'text'"
+          :disabled="disabled"
+          :data-schema-control="field.key"
+          autocomplete="off"
+          @update:model-value="update(field, $event)"
+        />
+      </BaseFormItem>
+    </BaseForm>
+  </div>
+</template>
diff --git a/frontend/src/components/SchemaForm/schema.ts b/frontend/src/components/SchemaForm/schema.ts
new file mode 100644
index 000000000..1b4f8c6a4
--- /dev/null
+++ b/frontend/src/components/SchemaForm/schema.ts
@@ -0,0 +1,40 @@
+import { isRecord } from '@/utils/object'
+
+export interface InputField {
+  key: string
+  label: string
+  description?: string
+  required: boolean
+  type: 'string' | 'number' | 'integer' | 'boolean'
+  secret: boolean
+  values?: Array<string | number | boolean | null>
+}
+
+// 仅将能无损编辑的平面字段映射为控件，复杂 schema 保留 JSON 编辑，完整校验由服务端负责。
+export function inputFields(schema: Record<string, unknown>): InputField[] | null {
+  if (['$ref', 'allOf', 'anyOf', 'oneOf', 'if', 'dependentSchemas'].some(key => key in schema))
+    return null
+  if (!isRecord(schema.properties))
+    return schema.additionalProperties === false ? [] : null
+  const required = Array.isArray(schema.required) ? schema.required : []
+  const fields: InputField[] = []
+  for (const [key, value] of Object.entries(schema.properties)) {
+    if (!isRecord(value) || !['string', 'number', 'integer', 'boolean'].includes(String(value.type)))
+      return null
+    if (['$ref', 'allOf', 'anyOf', 'oneOf', 'const', 'readOnly'].some(key => key in value))
+      return null
+    const values = value.enum
+    if (values !== undefined && (!Array.isArray(values) || !values.every(item => item === null || ['string', 'number', 'boolean'].includes(typeof item))))
+      return null
+    fields.push({
+      key,
+      label: typeof value.title === 'string' ? value.title : key,
+      description: typeof value.description === 'string' ? value.description : undefined,
+      type: value.type as InputField['type'],
+      required: required.includes(key),
+      secret: value.writeOnly === true || value.format === 'password',
+      values: values as InputField['values'],
+    })
+  }
+  return fields.length || schema.additionalProperties === false ? fields : null
+}
diff --git a/frontend/src/components/base/BaseButton.vue b/frontend/src/components/base/BaseButton.vue
deleted file mode 100644
index 3049287a7..000000000
--- a/frontend/src/components/base/BaseButton.vue
+++ /dev/null
@@ -1,78 +0,0 @@
-<script setup lang="ts">
-import { LoaderCircle } from '@lucide/vue'
-import { computed } from 'vue'
-
-type ButtonVariant = 'primary' | 'secondary' | 'soft' | 'ghost' | 'destructive'
-type ButtonSize = 'sm' | 'md' | 'lg'
-
-const props = withDefaults(
-  defineProps<{
-    variant?: ButtonVariant
-    size?: ButtonSize
-    loading?: boolean
-    disabled?: boolean
-    type?: 'button' | 'submit' | 'reset'
-  }>(),
-  {
-    variant: 'secondary',
-    size: 'md',
-    loading: false,
-    disabled: false,
-    type: 'button',
-  },
-)
-
-defineSlots<{
-  icon?: () => unknown
-  loading?: () => unknown
-  default: () => unknown
-}>()
-
-const variantClasses: Record<ButtonVariant, string> = {
-  primary:
-    'bg-(--cp-button-primary-bg) text-(--cp-button-primary-color) shadow-cp-tertiary hover:bg-(--cp-button-primary-hover-bg) active:bg-(--cp-button-primary-active-bg)',
-  secondary:
-    'bg-cp-button-secondary-bg text-cp-text shadow-cp-tertiary hover:bg-cp-button-secondary-hover-bg active:bg-cp-button-secondary-active-bg',
-  soft:
-    'bg-cp-primary-container text-cp-primary-on-container shadow-none hover:bg-cp-primary-container-hover active:bg-cp-primary-container-hover',
-  ghost:
-    'bg-transparent text-cp-text-secondary shadow-none hover:bg-cp-fill-quaternary hover:text-cp-text active:bg-cp-fill-tertiary',
-  destructive: 'bg-cp-error-container text-cp-error-on-container shadow-none hover:bg-cp-error-container-hover active:bg-cp-error-container-active',
-}
-
-const sizeClasses: Record<ButtonSize, string> = {
-  sm: 'h-cp-control-sm gap-1.5 px-3 text-xs',
-  md: 'h-cp-control gap-2 px-4 text-cp',
-  lg: 'h-cp-control-lg gap-2.5 px-5 text-cp-lg',
-}
-
-const spinnerSizes: Record<ButtonSize, number> = {
-  sm: 14,
-  md: 15,
-  lg: 17,
-}
-
-const classes = computed(() => [
-  'inline-flex shrink-0 touch-manipulation items-center justify-center rounded-cp-sm border-0 font-bold leading-none outline-none transition-[background-color,box-shadow,color,opacity,transform] duration-150 motion-safe:active:translate-y-px motion-safe:active:scale-[0.985] motion-reduce:transition-none',
-  'focus-visible:ring-2 focus-visible:ring-cp-control-outline focus-visible:ring-offset-2 focus-visible:ring-offset-cp-bg-container',
-  'disabled:cursor-not-allowed disabled:transform-none disabled:bg-cp-bg-container-disabled disabled:text-cp-text-disabled disabled:shadow-none',
-  sizeClasses[props.size],
-  variantClasses[props.variant],
-])
-</script>
-
-<template>
-  <button :type="type" :class="classes" :disabled="disabled || loading" :aria-busy="loading || undefined">
-    <span v-if="loading" class="inline-grid shrink-0 place-items-center leading-none">
-      <slot name="loading">
-        <LoaderCircle class="animate-spin motion-reduce:animate-none" :size="spinnerSizes[size]" />
-      </slot>
-    </span>
-    <span v-else-if="$slots.icon" class="inline-grid shrink-0 place-items-center">
-      <slot name="icon" />
-    </span>
-    <span class="inline-flex min-w-0 items-center justify-center gap-2">
-      <slot />
-    </span>
-  </button>
-</template>
diff --git a/frontend/src/components/base/BaseCard.vue b/frontend/src/components/base/BaseCard.vue
deleted file mode 100644
index 797c7becd..000000000
--- a/frontend/src/components/base/BaseCard.vue
+++ /dev/null
@@ -1,89 +0,0 @@
-<script setup lang="ts">
-import { computed } from 'vue'
-
-type CardPadding = 'none' | 'compact' | 'default'
-const props = withDefaults(
-  defineProps<{
-    as?: keyof HTMLElementTagNameMap
-    padding?: CardPadding
-    title?: string
-    description?: string
-  }>(),
-  {
-    as: 'section',
-    padding: 'default',
-    title: undefined,
-    description: undefined,
-  },
-)
-
-const slots = defineSlots<{
-  header?: () => unknown
-  title?: () => unknown
-  description?: () => unknown
-  actions?: () => unknown
-  body?: () => unknown
-  default?: () => unknown
-}>()
-
-const paddingClasses: Record<CardPadding, string | undefined> = {
-  none: undefined,
-  compact: 'p-4',
-  default: 'p-5.5',
-}
-
-const hasManagedHeader = computed(
-  () => Boolean(props.title || props.description || slots.actions || slots.title || slots.description),
-)
-const hasHeader = computed(() => Boolean(slots.header || hasManagedHeader.value))
-const contentClasses = computed(() => [
-  hasHeader.value ? 'mt-4' : undefined,
-  'flex min-h-0 min-w-0 flex-1 flex-col',
-])
-</script>
-
-<template>
-  <component
-    :is="props.as"
-    class="overflow-hidden rounded-cp-card bg-(--cp-card-bg) shadow-cp-card"
-    :class="[paddingClasses[padding], hasHeader ? 'flex min-h-0 flex-col' : undefined]"
-  >
-    <template v-if="$slots.header || hasManagedHeader || $slots.body">
-      <header v-if="$slots.header || hasManagedHeader" class="shrink-0">
-        <slot name="header">
-          <div class="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
-            <div class="min-w-0 pt-0.5">
-              <h2
-                v-if="props.title || $slots.title"
-                class="m-0 text-xl leading-[1.15] font-heavy text-cp-text text-balance"
-              >
-                <slot name="title">
-                  {{ props.title }}
-                </slot>
-              </h2>
-              <p
-                v-if="props.description || $slots.description"
-                class="mt-1.75 mb-0 text-cp leading-[1.3] font-emphasis text-cp-text-secondary text-pretty"
-              >
-                <slot name="description">
-                  {{ props.description }}
-                </slot>
-              </p>
-            </div>
-            <div v-if="$slots.actions" class="shrink-0">
-              <slot name="actions" />
-            </div>
-          </div>
-        </slot>
-      </header>
-
-      <div v-if="$slots.body || $slots.default" :class="contentClasses">
-        <slot name="body">
-          <slot />
-        </slot>
-      </div>
-    </template>
-
-    <slot v-else />
-  </component>
-</template>
diff --git a/frontend/src/components/base/BaseCheckbox.vue b/frontend/src/components/base/BaseCheckbox.vue
deleted file mode 100644
index 7c04b07dd..000000000
--- a/frontend/src/components/base/BaseCheckbox.vue
+++ /dev/null
@@ -1,61 +0,0 @@
-<script setup lang="ts">
-import { Check, Minus } from '@lucide/vue'
-import { computed, useTemplateRef, watchEffect } from 'vue'
-
-const props = withDefaults(
-  defineProps<{
-    label: string
-    indeterminate?: boolean
-    disabled?: boolean
-    showLabel?: boolean
-  }>(),
-  {
-    indeterminate: false,
-    disabled: false,
-    showLabel: false,
-  },
-)
-
-const model = defineModel<boolean>({ default: false })
-const inputRef = useTemplateRef<HTMLInputElement>('input')
-const checked = computed(() => model.value || props.indeterminate)
-
-watchEffect(() => {
-  if (inputRef.value)
-    inputRef.value.indeterminate = props.indeterminate
-})
-
-const boxClasses = computed(() => [
-  'relative inline-flex size-4 shrink-0 items-center justify-center rounded-cp-sm border-0 transition-[background-color,box-shadow,color] duration-150 motion-reduce:transition-none',
-  props.disabled
-    ? 'bg-cp-bg-container-disabled text-cp-text-disabled'
-    : checked.value
-      ? 'bg-cp-primary text-(--cp-button-primary-color)'
-      : 'bg-cp-bg-container text-transparent shadow-[inset_0_0_0_1px_var(--cp-color-border)]',
-])
-</script>
-
-<template>
-  <!-- The native checkbox is nested; the rule does not resolve this Vue template pattern. -->
-  <!-- eslint-disable-next-line vue-a11y/label-has-for -->
-  <label
-    class="group relative inline-flex min-h-4 min-w-4 items-center gap-2.5 text-cp leading-none font-emphasis"
-    :class="disabled ? 'cursor-not-allowed opacity-55' : 'cursor-pointer'"
-  >
-    <input ref="input" v-model="model" type="checkbox" class="peer sr-only" :aria-label="label" :disabled="disabled">
-    <span
-      :class="boxClasses"
-      class="peer-focus-visible:ring-2 peer-focus-visible:ring-cp-control-outline peer-focus-visible:ring-offset-2 peer-focus-visible:ring-offset-cp-bg-container"
-    >
-      <Minus
-        class="absolute size-3 transition-opacity duration-150 motion-reduce:transition-none"
-        :class="indeterminate ? 'opacity-100' : 'opacity-0'"
-      />
-      <Check
-        class="absolute size-3 transition-opacity duration-150 motion-reduce:transition-none"
-        :class="!indeterminate && model ? 'opacity-100' : 'opacity-0'"
-      />
-    </span>
-    <span v-if="showLabel" class="min-w-0 text-cp leading-none font-emphasis"><slot name="label">{{ label }}</slot></span>
-  </label>
-</template>
diff --git a/frontend/src/components/base/BaseColorPicker/color.ts b/frontend/src/components/base/BaseColorPicker/color.ts
deleted file mode 100644
index a1f9eb702..000000000
--- a/frontend/src/components/base/BaseColorPicker/color.ts
+++ /dev/null
@@ -1,130 +0,0 @@
-import { normalizeHexColor, normalizeRgbaHexColor } from '@/utils/color'
-
-const RGBA_COLOR_PATTERN
-  = /^rgba\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(0(?:\.\d+)?|1(?:\.0+)?)\s*\)$/i
-
-export interface HsvaColor {
-  h: number
-  s: number
-  v: number
-  a: number
-}
-
-interface RgbaColor {
-  r: number
-  g: number
-  b: number
-  a: number
-}
-
-export function normalizePickerHexColor(value: string, allowAlpha: boolean) {
-  if (allowAlpha) {
-    const rgba = normalizeRgbaHexColor(value)
-    if (rgba)
-      return rgba
-    const rgb = normalizeHexColor(value)
-    return rgb ? `${rgb}FF` : null
-  }
-
-  const rgb = normalizeHexColor(value)
-  if (rgb)
-    return rgb
-  return normalizeRgbaHexColor(value)?.slice(0, 7) ?? null
-}
-
-export function hexToHsva(value: string): HsvaColor | null {
-  const normalized = normalizePickerHexColor(value, true)
-  if (!normalized)
-    return null
-
-  const red = Number.parseInt(normalized.slice(1, 3), 16) / 255
-  const green = Number.parseInt(normalized.slice(3, 5), 16) / 255
-  const blue = Number.parseInt(normalized.slice(5, 7), 16) / 255
-  const alpha = Number.parseInt(normalized.slice(7, 9), 16) / 255
-  const maximum = Math.max(red, green, blue)
-  const minimum = Math.min(red, green, blue)
-  const delta = maximum - minimum
-  let hue = 0
-
-  if (delta > 0) {
-    if (maximum === red)
-      hue = 60 * (((green - blue) / delta) % 6)
-    else if (maximum === green)
-      hue = 60 * ((blue - red) / delta + 2)
-    else
-      hue = 60 * ((red - green) / delta + 4)
-  }
-
-  return {
-    h: hue < 0 ? hue + 360 : hue,
-    s: maximum === 0 ? 0 : (delta / maximum) * 100,
-    v: maximum * 100,
-    a: alpha,
-  }
-}
-
-export function hsvaToHex(color: HsvaColor, allowAlpha: boolean) {
-  const hue = ((color.h % 360) + 360) % 360
-  const saturation = clamp(color.s, 0, 100) / 100
-  const brightness = clamp(color.v, 0, 100) / 100
-  const chroma = brightness * saturation
-  const section = hue / 60
-  const intermediate = chroma * (1 - Math.abs((section % 2) - 1))
-  const offset = brightness - chroma
-  const [red, green, blue] = section < 1
-    ? [chroma, intermediate, 0]
-    : section < 2
-      ? [intermediate, chroma, 0]
-      : section < 3
-        ? [0, chroma, intermediate]
-        : section < 4
-          ? [0, intermediate, chroma]
-          : section < 5
-            ? [intermediate, 0, chroma]
-            : [chroma, 0, intermediate]
-
-  const rgb = [red, green, blue]
-    .map(channel => Math.round((channel + offset) * 255).toString(16).padStart(2, '0'))
-    .join('')
-  const alpha = allowAlpha
-    ? Math.round(clamp(color.a, 0, 1) * 255).toString(16).padStart(2, '0')
-    : ''
-  return `#${rgb}${alpha}`.toUpperCase()
-}
-
-export function parseRgbaColor(value: string): RgbaColor | null {
-  const match = RGBA_COLOR_PATTERN.exec(value.trim())
-  if (!match)
-    return null
-
-  const red = Number(match[1])
-  const green = Number(match[2])
-  const blue = Number(match[3])
-  const alpha = Number(match[4])
-  if ([red, green, blue].some(channel => channel > 255))
-    return null
-
-  return { r: red, g: green, b: blue, a: alpha }
-}
-
-export function rgbaToHexColor(color: RgbaColor) {
-  return `#${[color.r, color.g, color.b, color.a * 255]
-    .map(channel => Math.round(channel).toString(16).padStart(2, '0'))
-    .join('')}`.toUpperCase()
-}
-
-export function formatRgbaColor(value: string) {
-  const normalized = normalizePickerHexColor(value, true)
-  if (!normalized)
-    return null
-
-  const red = Number.parseInt(normalized.slice(1, 3), 16)
-  const green = Number.parseInt(normalized.slice(3, 5), 16)
-  const blue = Number.parseInt(normalized.slice(5, 7), 16)
-  const alpha = Number((Number.parseInt(normalized.slice(7, 9), 16) / 255).toFixed(3))
-  return `rgba(${red}, ${green}, ${blue}, ${alpha})`
-}
-
-function clamp(value: number, minimum: number, maximum: number) {
-  return Math.min(maximum, Math.max(minimum, value))
-}
diff --git a/frontend/src/components/base/BaseColorPicker/index.vue b/frontend/src/components/base/BaseColorPicker/index.vue
deleted file mode 100644
index 9d6f2bf1c..000000000
--- a/frontend/src/components/base/BaseColorPicker/index.vue
+++ /dev/null
@@ -1,440 +0,0 @@
-<script setup lang="ts">
-import { Check, ChevronDown } from '@lucide/vue'
-import { clamp } from 'es-toolkit'
-import { computed, shallowRef, useTemplateRef, watch } from 'vue'
-
-import { normalizeHexColor } from '@/utils/color'
-import BaseButton from '../BaseButton.vue'
-import BaseInput from '../BaseInput.vue'
-import BasePopover from '../BasePopover.vue'
-import { formatRgbaColor, hexToHsva, hsvaToHex, normalizePickerHexColor, parseRgbaColor, rgbaToHexColor } from './color'
-
-const props = withDefaults(
-  defineProps<{
-    presets?: readonly string[]
-    disabled?: boolean
-    label?: string
-    allowAlpha?: boolean
-  }>(),
-  {
-    presets: () => [],
-    disabled: false,
-    label: '选择颜色',
-    allowAlpha: true,
-  },
-)
-
-const model = defineModel<string>({ required: true })
-const open = shallowRef(false)
-const hue = shallowRef(0)
-const saturation = shallowRef(100)
-const brightness = shallowRef(100)
-const alpha = shallowRef(0.5)
-const customInput = shallowRef('')
-const svPanel = useTemplateRef<HTMLElement>('svPanel')
-const hueSlider = useTemplateRef<HTMLElement>('hueSlider')
-const alphaSlider = useTemplateRef<HTMLElement>('alphaSlider')
-
-const normalizedModel = computed(
-  () => normalizePickerHexColor(model.value, props.allowAlpha) ?? (props.allowAlpha ? '#60A5FA80' : '#2563EB'),
-)
-const triggerSwatchStyle = computed(() =>
-  props.allowAlpha
-    ? {
-        backgroundImage: `linear-gradient(${normalizedModel.value}, ${normalizedModel.value}), conic-gradient(#d8dee8 25%, #fff 0 50%, #d8dee8 0 75%, #fff 0)`,
-        backgroundSize: '100% 100%, 8px 8px',
-      }
-    : { backgroundColor: normalizedModel.value },
-)
-const draftColor = computed(() =>
-  hsvaToHex(
-    {
-      h: hue.value,
-      s: saturation.value,
-      v: brightness.value,
-      a: alpha.value,
-    },
-    props.allowAlpha,
-  ),
-)
-const hueColor = computed(() => `hsl(${hue.value} 100% 50%)`)
-const svCursorStyle = computed(() => ({
-  left: `${saturation.value}%`,
-  top: `${100 - brightness.value}%`,
-}))
-const hueThumbStyle = computed(() => ({ top: `${(hue.value / 360) * 100}%` }))
-const alphaThumbStyle = computed(() => ({ left: `${alpha.value * 100}%` }))
-const alphaTrackStyle = computed(() => {
-  const hex = draftColor.value
-  const red = Number.parseInt(hex.slice(1, 3), 16)
-  const green = Number.parseInt(hex.slice(3, 5), 16)
-  const blue = Number.parseInt(hex.slice(5, 7), 16)
-  return {
-    backgroundImage: `linear-gradient(to right, rgb(${red} ${green} ${blue} / 0), rgb(${red} ${green} ${blue} / 1)), conic-gradient(#d8dee8 25%, #fff 0 50%, #d8dee8 0 75%, #fff 0)`,
-    backgroundSize: '100% 100%, 8px 8px',
-  }
-})
-const inputValid = computed(() =>
-  props.allowAlpha ? Boolean(parseRgbaColor(customInput.value)) : Boolean(normalizeHexColor(customInput.value)),
-)
-const inputError = computed(() =>
-  customInput.value && !inputValid.value
-    ? props.allowAlpha
-      ? '请输入 rgba(r, g, b, a)'
-      : '请输入六位 HEX 颜色，例如 #2563EB'
-    : undefined,
-)
-
-watch(open, (isOpen) => {
-  if (isOpen)
-    resetDraft(normalizedModel.value)
-})
-
-watch(model, (value) => {
-  if (!open.value)
-    resetDraft(value)
-})
-
-function resetDraft(value: string) {
-  const color = hexToHsva(normalizePickerHexColor(value, props.allowAlpha) ?? '') ?? {
-    h: 213,
-    s: 62,
-    v: 98,
-    a: props.allowAlpha ? 0.5 : 1,
-  }
-  hue.value = color.h
-  saturation.value = color.s
-  brightness.value = color.v
-  alpha.value = props.allowAlpha ? color.a : 1
-  syncInput()
-}
-
-function syncInput() {
-  customInput.value = props.allowAlpha
-    ? (formatRgbaColor(draftColor.value) ?? '')
-    : (normalizeHexColor(draftColor.value) ?? '')
-}
-
-function updateSaturationBrightness(event: PointerEvent) {
-  const panel = svPanel.value
-  if (!panel)
-    return
-
-  const bounds = panel.getBoundingClientRect()
-  saturation.value = clamp(((event.clientX - bounds.left) / bounds.width) * 100, 0, 100)
-  brightness.value = clamp(100 - ((event.clientY - bounds.top) / bounds.height) * 100, 0, 100)
-  syncInput()
-}
-
-function startSaturationBrightness(event: PointerEvent) {
-  if (props.disabled)
-    return
-  event.preventDefault()
-  svPanel.value?.setPointerCapture(event.pointerId)
-  updateSaturationBrightness(event)
-}
-
-function updateHue(event: PointerEvent) {
-  const slider = hueSlider.value
-  if (!slider)
-    return
-
-  const bounds = slider.getBoundingClientRect()
-  hue.value = clamp(((event.clientY - bounds.top) / bounds.height) * 360, 0, 360)
-  syncInput()
-}
-
-function startHue(event: PointerEvent) {
-  if (props.disabled)
-    return
-  event.preventDefault()
-  hueSlider.value?.setPointerCapture(event.pointerId)
-  updateHue(event)
-}
-
-function handleSaturationBrightnessKeydown(event: KeyboardEvent) {
-  const step = event.shiftKey ? 5 : 1
-  if (event.key === 'ArrowLeft')
-    saturation.value = clamp(saturation.value - step, 0, 100)
-  else if (event.key === 'ArrowRight')
-    saturation.value = clamp(saturation.value + step, 0, 100)
-  else if (event.key === 'ArrowUp')
-    brightness.value = clamp(brightness.value + step, 0, 100)
-  else if (event.key === 'ArrowDown')
-    brightness.value = clamp(brightness.value - step, 0, 100)
-  else return
-
-  event.preventDefault()
-  syncInput()
-}
-
-function handleHueKeydown(event: KeyboardEvent) {
-  const step = event.shiftKey ? 10 : 1
-  if (event.key === 'ArrowUp' || event.key === 'ArrowLeft')
-    hue.value = clamp(hue.value - step, 0, 360)
-  else if (event.key === 'ArrowDown' || event.key === 'ArrowRight')
-    hue.value = clamp(hue.value + step, 0, 360)
-  else return
-
-  event.preventDefault()
-  syncInput()
-}
-
-function updateAlpha(event: PointerEvent) {
-  const slider = alphaSlider.value
-  if (!slider)
-    return
-
-  const bounds = slider.getBoundingClientRect()
-  alpha.value = clamp((event.clientX - bounds.left) / bounds.width, 0, 1)
-  syncInput()
-}
-
-function startAlpha(event: PointerEvent) {
-  if (props.disabled)
-    return
-  event.preventDefault()
-  alphaSlider.value?.setPointerCapture(event.pointerId)
-  updateAlpha(event)
-}
-
-function handleAlphaKeydown(event: KeyboardEvent) {
-  const step = event.shiftKey ? 0.1 : 0.01
-  if (event.key === 'ArrowLeft' || event.key === 'ArrowDown')
-    alpha.value = clamp(alpha.value - step, 0, 1)
-  else if (event.key === 'ArrowRight' || event.key === 'ArrowUp')
-    alpha.value = clamp(alpha.value + step, 0, 1)
-  else return
-
-  event.preventDefault()
-  syncInput()
-}
-
-function updateFromInput() {
-  const inputColor = normalizedInputColor()
-  const color = inputColor ? hexToHsva(inputColor) : null
-  if (!color)
-    return
-
-  hue.value = color.h
-  saturation.value = color.s
-  brightness.value = color.v
-  alpha.value = props.allowAlpha ? color.a : 1
-  syncInput()
-}
-
-function choosePreset(value: string) {
-  const normalized = normalizePickerHexColor(value, props.allowAlpha)
-  if (normalized)
-    resetDraft(normalized)
-}
-
-function isPresetSelected(value: string) {
-  const normalized = normalizePickerHexColor(value, props.allowAlpha)
-  return normalized?.slice(0, 7) === draftColor.value.slice(0, 7)
-}
-
-function presetCheckClass(value: string) {
-  const normalized = normalizePickerHexColor(value, props.allowAlpha)
-  if (!normalized)
-    return 'text-white'
-
-  const red = Number.parseInt(normalized.slice(1, 3), 16)
-  const green = Number.parseInt(normalized.slice(3, 5), 16)
-  const blue = Number.parseInt(normalized.slice(5, 7), 16)
-  const brightness = red * 0.299 + green * 0.587 + blue * 0.114
-
-  return brightness > 160 ? 'text-[#0f172a]' : 'text-white'
-}
-
-function confirm() {
-  updateFromInput()
-  const normalized = normalizedInputColor()
-  if (!normalized)
-    return
-
-  model.value = normalized
-  open.value = false
-}
-
-function normalizedInputColor() {
-  if (!props.allowAlpha)
-    return normalizeHexColor(customInput.value)
-
-  const rgba = parseRgbaColor(customInput.value)
-  return rgba ? rgbaToHexColor(rgba) : null
-}
-</script>
-
-<template>
-  <BasePopover v-model="open" class="p-0.75" placement="bottom-start" :disabled="props.disabled">
-    <template #trigger>
-      <button
-        type="button"
-        class="group inline-flex size-8 items-center justify-center rounded-sm border-0 bg-transparent p-0 outline-none transition-opacity duration-150 hover:opacity-90 focus-visible:ring-2 focus-visible:ring-cp-control-outline disabled:cursor-not-allowed disabled:opacity-60"
-        :disabled="props.disabled"
-        :aria-label="props.label"
-        aria-haspopup="dialog"
-        :aria-expanded="open"
-      >
-        <span
-          class="relative flex size-full items-center justify-center overflow-hidden rounded-sm"
-          :style="triggerSwatchStyle"
-        >
-          <ChevronDown class="relative size-3.5 text-white drop-shadow-[0_1px_2px_rgb(0_0_0/0.65)]" />
-        </span>
-      </button>
-    </template>
-
-    <div class="grid w-76 gap-3 p-3" role="dialog" :aria-label="props.label">
-      <div class="grid h-43 grid-cols-[1fr_14px] gap-2">
-        <div
-          ref="svPanel"
-          class="base-color-picker__sv relative touch-none overflow-hidden rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-cp-control-outline"
-          :style="{ backgroundColor: hueColor }"
-          role="slider"
-          tabindex="0"
-          aria-label="饱和度和明度"
-          aria-valuemin="0"
-          aria-valuemax="100"
-          :aria-valuenow="Math.round(saturation)"
-          :aria-valuetext="`饱和度 ${Math.round(saturation)}%，明度 ${Math.round(brightness)}%`"
-          @pointerdown="startSaturationBrightness"
-          @pointermove="event => svPanel?.hasPointerCapture(event.pointerId) && updateSaturationBrightness(event)"
-          @keydown="handleSaturationBrightnessKeydown"
-        >
-          <span
-            class="absolute z-1 size-3 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-[0_1px_3px_#00000080]"
-            :style="svCursorStyle"
-          />
-        </div>
-
-        <div
-          ref="hueSlider"
-          class="base-color-picker__hue relative touch-none rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-cp-control-outline"
-          role="slider"
-          tabindex="0"
-          aria-label="色相"
-          aria-orientation="vertical"
-          aria-valuemin="0"
-          aria-valuemax="360"
-          :aria-valuenow="Math.round(hue)"
-          @pointerdown="startHue"
-          @pointermove="event => hueSlider?.hasPointerCapture(event.pointerId) && updateHue(event)"
-          @keydown="handleHueKeydown"
-        >
-          <span
-            class="absolute left-1/2 h-1.5 w-4.5 -translate-x-1/2 -translate-y-1/2 rounded-xs bg-white shadow-[0_0_0_1px_#64748b,0_1px_2px_#0000004d]"
-            :style="hueThumbStyle"
-          />
-        </div>
-      </div>
-
-      <div v-if="props.allowAlpha" class="grid grid-cols-[1fr_36px] items-center gap-2">
-        <div
-          ref="alphaSlider"
-          class="base-color-picker__alpha relative h-3 touch-none rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-cp-control-outline"
-          :style="alphaTrackStyle"
-          role="slider"
-          tabindex="0"
-          aria-label="不透明度"
-          aria-orientation="horizontal"
-          aria-valuemin="0"
-          aria-valuemax="100"
-          :aria-valuenow="Math.round(alpha * 100)"
-          :aria-valuetext="`不透明度 ${Math.round(alpha * 100)}%`"
-          @pointerdown="startAlpha"
-          @pointermove="event => alphaSlider?.hasPointerCapture(event.pointerId) && updateAlpha(event)"
-          @keydown="handleAlphaKeydown"
-        >
-          <span
-            class="absolute top-1/2 size-3.5 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-[0_1px_3px_#00000080]"
-            :style="alphaThumbStyle"
-          />
-        </div>
-        <span class="text-right font-mono text-cp-xs tabular-nums text-cp-text-secondary">
-          {{ Math.round(alpha * 100) }}%
-        </span>
-      </div>
-
-      <div v-if="props.presets.length > 0" class="flex flex-wrap gap-2" role="radiogroup" aria-label="预设颜色">
-        <button
-          v-for="color in props.presets"
-          :key="color"
-          type="button"
-          class="relative flex size-6.5 items-center justify-center rounded-sm border-0 outline-none transition-transform duration-150 hover:scale-105 focus-visible:ring-2 focus-visible:ring-cp-control-outline focus-visible:ring-offset-2 focus-visible:ring-offset-cp-bg-container"
-          :style="{ backgroundColor: color }"
-          role="radio"
-          :aria-label="color"
-          :aria-checked="isPresetSelected(color)"
-          :title="color"
-          @click="choosePreset(color)"
-        >
-          <Check
-            v-if="isPresetSelected(color)"
-            class="size-3.5 drop-shadow-[0_1px_2px_rgb(0_0_0/0.2)]"
-            :class="presetCheckClass(color)"
-          />
-        </button>
-      </div>
-
-      <div class="flex items-start gap-2">
-        <div class="min-w-0 flex-1">
-          <BaseInput
-            v-model="customInput"
-            class="rounded-cp bg-cp-fill-tertiary!"
-            :aria-label="props.allowAlpha ? 'RGBA 颜色' : 'HEX 颜色'"
-            :placeholder="props.allowAlpha ? 'rgba(96, 165, 250, 1)' : '#2563EB'"
-            autocomplete="off"
-            :disabled="props.disabled"
-            :aria-invalid="Boolean(inputError) || undefined"
-            aria-describedby="color-input-error"
-            @change="updateFromInput"
-            @keydown.enter="confirm"
-          />
-          <p
-            v-if="inputError"
-            id="color-input-error"
-            class="mt-1.5 mb-0 text-xs font-emphasis text-cp-error-text"
-            aria-live="polite"
-          >
-            {{ inputError }}
-          </p>
-        </div>
-        <BaseButton size="md" variant="secondary" :disabled="!inputValid" @click="confirm">
-          确定
-        </BaseButton>
-      </div>
-    </div>
-  </BasePopover>
-</template>
-
-<style scoped>
-.base-color-picker__sv::before,
-.base-color-picker__sv::after {
-  position: absolute;
-  inset: 0;
-  content: '';
-}
-
-.base-color-picker__sv::before {
-  background: linear-gradient(to right, #fff, transparent);
-}
-
-.base-color-picker__sv::after {
-  background: linear-gradient(to top, #000, transparent);
-}
-
-.base-color-picker__hue {
-  background: linear-gradient(
-    to bottom,
-    #f00 0%,
-    #ff0 16.67%,
-    #0f0 33.33%,
-    #0ff 50%,
-    #00f 66.67%,
-    #f0f 83.33%,
-    #f00 100%
-  );
-}
-</style>
diff --git a/frontend/src/components/base/BaseConfirmModal.vue b/frontend/src/components/base/BaseConfirmModal.vue
deleted file mode 100644
index 12b8c81dc..000000000
--- a/frontend/src/components/base/BaseConfirmModal.vue
+++ /dev/null
@@ -1,74 +0,0 @@
-<script setup lang="ts">
-import BaseButton from './BaseButton.vue'
-import BaseModal from './BaseModal/index.vue'
-
-const props = withDefaults(
-  defineProps<{
-    title: string
-    description?: string
-    destructive?: boolean
-    confirmText?: string
-    cancelText?: string
-    loading?: boolean
-    confirmDisabled?: boolean
-  }>(),
-  {
-    destructive: false,
-    confirmText: '确认',
-    cancelText: '取消',
-    loading: false,
-    confirmDisabled: false,
-  },
-)
-
-const emit = defineEmits<{
-  confirm: []
-  cancel: []
-}>()
-const open = defineModel<boolean>({ default: false })
-function handleCancel() {
-  if (props.loading)
-    return
-  open.value = false
-  emit('cancel')
-}
-
-function handleConfirm() {
-  if (props.loading || props.confirmDisabled)
-    return
-  emit('confirm')
-}
-</script>
-
-<template>
-  <BaseModal
-    v-model="open"
-    :title="title"
-    :description="description"
-    size="sm"
-    :tone="destructive ? 'danger' : 'warning'"
-    role="alertdialog"
-    :dismissible="!loading"
-  >
-    <div
-      v-if="$slots.default"
-      class="text-cp-lg leading-[1.55] font-emphasis text-cp-text-secondary"
-    >
-      <slot />
-    </div>
-
-    <template #footer>
-      <BaseButton variant="secondary" :disabled="loading" @click="handleCancel">
-        {{ cancelText }}
-      </BaseButton>
-      <BaseButton
-        :variant="destructive ? 'destructive' : 'primary'"
-        :loading="loading"
-        :disabled="confirmDisabled"
-        @click="handleConfirm"
-      >
-        {{ confirmText }}
-      </BaseButton>
-    </template>
-  </BaseModal>
-</template>
diff --git a/frontend/src/components/base/BaseEmpty.vue b/frontend/src/components/base/BaseEmpty.vue
deleted file mode 100644
index 592b4eebf..000000000
--- a/frontend/src/components/base/BaseEmpty.vue
+++ /dev/null
@@ -1,62 +0,0 @@
-<script setup lang="ts">
-import type { Component } from 'vue'
-import { Inbox } from '@lucide/vue'
-import { computed } from 'vue'
-
-type EmptySurface = 'subtle' | 'inset' | 'none'
-
-const props = withDefaults(
-  defineProps<{
-    title?: string
-    description?: string
-    icon?: Component
-    size?: 'sm' | 'md'
-    surface?: EmptySurface
-  }>(),
-  {
-    title: undefined,
-    description: undefined,
-    icon: undefined,
-    size: 'md',
-    surface: 'subtle',
-  },
-)
-
-const resolvedTitle = computed(() => props.title ?? '暂无数据')
-const resolvedIcon = computed(() => props.icon ?? Inbox)
-
-const surfaceClasses: Record<EmptySurface, string> = {
-  subtle: 'rounded-cp-lg bg-cp-fill-alter',
-  inset: 'rounded-cp-lg bg-cp-fill-alter/70',
-  none: 'bg-transparent',
-}
-</script>
-
-<template>
-  <div
-    class="grid justify-items-center text-center"
-    :class="[
-      surfaceClasses[surface],
-      size === 'sm' ? 'gap-2 px-4 py-5' : 'gap-3 px-6 py-8',
-    ]"
-  >
-    <span
-      class="inline-flex items-center justify-center rounded-cp bg-cp-fill-tertiary text-cp-text-quaternary"
-      :class="size === 'sm' ? 'size-8' : 'size-10'"
-    >
-      <component :is="resolvedIcon" :size="size === 'sm' ? 16 : 18" />
-    </span>
-    <p class="m-0 text-cp leading-[1.15] font-heavy text-cp-text">
-      {{ resolvedTitle }}
-    </p>
-    <p
-      v-if="description"
-      class="m-0 max-w-72 text-xs leading-[1.45] font-semibold text-cp-text-secondary"
-    >
-      {{ description }}
-    </p>
-    <div v-if="$slots.action" class="mt-1">
-      <slot name="action" />
-    </div>
-  </div>
-</template>
diff --git a/frontend/src/components/base/BaseForm/FormItem.vue b/frontend/src/components/base/BaseForm/FormItem.vue
deleted file mode 100644
index 655200407..000000000
--- a/frontend/src/components/base/BaseForm/FormItem.vue
+++ /dev/null
@@ -1,72 +0,0 @@
-<script setup lang="ts">
-import { computed, provide, useId } from 'vue'
-import { formFieldKey } from './context'
-
-const props = withDefaults(
-  defineProps<{
-    label?: string
-    description?: string
-    error?: string
-    required?: boolean
-    controlId?: string
-  }>(),
-  {
-    label: undefined,
-    description: undefined,
-    error: undefined,
-    required: false,
-    controlId: undefined,
-  },
-)
-
-const generatedId = useId()
-const resolvedControlId = computed(() => props.controlId ?? `field-${generatedId}`)
-const descriptionId = computed(() => (props.description ? `${resolvedControlId.value}-description` : undefined))
-const errorId = computed(() => (props.error ? `${resolvedControlId.value}-error` : undefined))
-const describedBy = computed(() => [descriptionId.value, errorId.value].filter(Boolean).join(' ') || undefined)
-
-provide(formFieldKey, {
-  controlId: resolvedControlId,
-  describedBy,
-  invalid: computed(() => Boolean(props.error)),
-  required: computed(() => props.required),
-})
-</script>
-
-<template>
-  <div class="min-w-0">
-    <div v-if="label || $slots.label || $slots.extra" class="mb-2 flex min-w-0 items-center justify-between gap-3">
-      <!-- The runtime id comes from the injected field context. -->
-      <!-- eslint-disable-next-line vue-a11y/label-has-for -->
-      <label
-        :for="resolvedControlId"
-        class="flex min-w-0 items-center gap-1.5 text-cp leading-none font-medium text-cp-text-secondary"
-      >
-        <slot name="label">{{ label }}</slot>
-        <span v-if="required" class="font-bold text-cp-error">*</span>
-        <span v-if="required" class="sr-only">必填</span>
-      </label>
-      <div v-if="$slots.extra" class="inline-flex shrink-0 items-center">
-        <slot name="extra" />
-      </div>
-    </div>
-    <p
-      v-if="description"
-      :id="descriptionId"
-      class="mt-0 mb-2 text-xs leading-[1.35] font-emphasis text-cp-text-quaternary"
-    >
-      {{ description }}
-    </p>
-    <div class="min-w-0">
-      <slot />
-    </div>
-    <p
-      v-if="error"
-      :id="errorId"
-      class="mt-2 mb-0 text-xs leading-[1.35] font-emphasis text-cp-error-text"
-      aria-live="polite"
-    >
-      {{ error }}
-    </p>
-  </div>
-</template>
diff --git a/frontend/src/components/base/BaseForm/context.ts b/frontend/src/components/base/BaseForm/context.ts
deleted file mode 100644
index ca102ed87..000000000
--- a/frontend/src/components/base/BaseForm/context.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import type { ComputedRef, InjectionKey } from 'vue'
-
-interface FormFieldContext {
-  controlId: ComputedRef<string>
-  describedBy: ComputedRef<string | undefined>
-  invalid: ComputedRef<boolean>
-  required: ComputedRef<boolean>
-}
-
-export const formFieldKey: InjectionKey<FormFieldContext> = Symbol('form-field')
diff --git a/frontend/src/components/base/BaseForm/index.vue b/frontend/src/components/base/BaseForm/index.vue
deleted file mode 100644
index 5f3ca31ed..000000000
--- a/frontend/src/components/base/BaseForm/index.vue
+++ /dev/null
@@ -1,5 +0,0 @@
-<template>
-  <form class="grid min-w-0 gap-4" @submit.prevent>
-    <slot />
-  </form>
-</template>
diff --git a/frontend/src/components/base/BaseIconButton.vue b/frontend/src/components/base/BaseIconButton.vue
deleted file mode 100644
index 5ca5a6616..000000000
--- a/frontend/src/components/base/BaseIconButton.vue
+++ /dev/null
@@ -1,91 +0,0 @@
-<script setup lang="ts">
-import { LoaderCircle } from '@lucide/vue'
-import { computed } from 'vue'
-
-type IconButtonVariant = 'primary' | 'secondary' | 'filled' | 'success' | 'ghost' | 'destructive'
-type IconButtonSize = 'sm' | 'md' | 'lg'
-
-const props = withDefaults(
-  defineProps<{
-    label: string
-    variant?: IconButtonVariant
-    size?: IconButtonSize
-    loading?: boolean
-    disabled?: boolean
-    pressed?: boolean
-    type?: 'button' | 'submit' | 'reset'
-  }>(),
-  {
-    variant: 'ghost',
-    size: 'md',
-    loading: false,
-    disabled: false,
-    pressed: false,
-    type: 'button',
-  },
-)
-
-defineSlots<{
-  loading?: () => unknown
-  default: () => unknown
-}>()
-
-const variantClasses: Record<IconButtonVariant, string> = {
-  primary:
-    'bg-(--cp-button-primary-bg) text-(--cp-button-primary-color) shadow-cp-tertiary hover:bg-(--cp-button-primary-hover-bg) active:bg-(--cp-button-primary-active-bg)',
-  secondary:
-    'bg-cp-icon-button-secondary-bg text-cp-text-secondary shadow-cp-tertiary hover:bg-cp-icon-button-secondary-hover-bg hover:text-cp-text active:bg-cp-icon-button-secondary-active-bg',
-  filled:
-    'bg-cp-fill-tertiary text-cp-text-secondary shadow-none hover:bg-cp-bg-text-hover hover:text-cp-text active:bg-cp-fill-secondary aria-pressed:bg-cp-bg-text-active',
-  success:
-    'bg-cp-success-container text-cp-success-on-container shadow-none hover:bg-cp-success-container-hover active:bg-cp-success-container-active',
-  ghost:
-    'bg-transparent text-cp-text-secondary shadow-none hover:bg-cp-fill-quaternary hover:text-cp-text active:bg-cp-fill-tertiary',
-  destructive: 'bg-transparent text-cp-error-text shadow-none hover:bg-cp-error-container-hover hover:text-cp-error-on-container active:bg-cp-error-container-active active:text-cp-error-on-container',
-}
-
-const sizeClasses: Record<IconButtonSize, string> = {
-  sm: 'size-cp-control-sm [&>svg]:size-3.5',
-  md: 'size-cp-control [&>svg]:size-4',
-  lg: 'size-cp-control-lg [&>svg]:size-4.5',
-}
-
-const spinnerSizes: Record<IconButtonSize, number> = {
-  sm: 14,
-  md: 16,
-  lg: 18,
-}
-
-const classes = computed(() => [
-  'inline-grid shrink-0 touch-manipulation place-items-center rounded-cp border-0 leading-none outline-none transition-[background-color,box-shadow,color,opacity,transform] duration-150 motion-safe:active:scale-[0.96] motion-reduce:transition-none',
-  'focus-visible:ring-2 focus-visible:ring-cp-control-outline focus-visible:ring-offset-2 focus-visible:ring-offset-cp-bg-container',
-  'disabled:cursor-not-allowed disabled:transform-none disabled:bg-cp-bg-container-disabled disabled:text-cp-text-disabled disabled:shadow-none',
-  sizeClasses[props.size],
-  variantClasses[props.variant],
-  props.pressed ? 'bg-cp-bg-text-active text-cp-text' : undefined,
-])
-</script>
-
-<template>
-  <button
-    :type="type"
-    :class="classes"
-    :disabled="disabled || loading"
-    :aria-label="label"
-    :aria-pressed="pressed || undefined"
-    :aria-busy="loading || undefined"
-    :title="label"
-  >
-    <span
-      v-if="loading"
-      class="inline-grid place-items-center [&>svg]:block [&>svg]:origin-center [&>svg]:transform-view [&>svg]:will-change-transform"
-    >
-      <slot name="loading">
-        <LoaderCircle class="animate-spin motion-reduce:animate-none" :size="spinnerSizes[size]" />
-      </slot>
-    </span>
-    <span v-else class="inline-grid place-items-center">
-      <slot />
-    </span>
-  </button>
-</template>
diff --git a/frontend/src/components/base/BaseInput.vue b/frontend/src/components/base/BaseInput.vue
deleted file mode 100644
index 75faff77a..000000000
--- a/frontend/src/components/base/BaseInput.vue
+++ /dev/null
@@ -1,136 +0,0 @@
-<script setup lang="ts">
-import { computed, inject, useAttrs } from 'vue'
-import { formFieldKey } from './BaseForm/context'
-
-type InputSize = 'sm' | 'md' | 'lg'
-
-defineOptions({ inheritAttrs: false })
-
-const props = withDefaults(
-  defineProps<{
-    placeholder?: string
-    type?: string
-    disabled?: boolean
-    size?: InputSize
-  }>(),
-  {
-    placeholder: '',
-    type: 'text',
-    disabled: false,
-    size: 'md',
-  },
-)
-
-const model = defineModel<string>({ default: '' })
-const attrs = useAttrs()
-const field = inject(formFieldKey, null)
-
-const controlId = computed(() => (typeof attrs.id === 'string' ? attrs.id : field?.controlId.value))
-const invalid = computed(() =>
-  Boolean(field?.invalid.value || attrs['aria-invalid'] === true || attrs['aria-invalid'] === 'true'),
-)
-const describedBy = computed(
-  () =>
-    [typeof attrs['aria-describedby'] === 'string' ? attrs['aria-describedby'] : undefined, field?.describedBy.value]
-      .filter(Boolean)
-      .join(' ') || undefined,
-)
-
-const rootAttrs = computed(() => ({ class: attrs.class, style: attrs.style }))
-const controlAttrs = computed(() =>
-  Object.fromEntries(
-    Object.entries(attrs).filter(
-      ([key]) => !['class', 'style', 'id', 'aria-describedby', 'aria-invalid', 'aria-required'].includes(key),
-    ),
-  ),
-)
-
-const sizeClasses: Record<InputSize, string> = {
-  sm: 'h-cp-control-sm gap-2 px-3 text-xs',
-  md: 'h-cp-control gap-2.5 px-3.5 text-cp',
-  lg: 'h-cp-control-lg gap-3 px-4 text-cp-lg',
-}
-
-const containerClasses = computed(() => [
-  'relative inline-flex w-full min-w-0 items-center overflow-visible rounded-cp border-0 text-cp-text shadow-cp-input transition-[background-color,box-shadow,color] duration-[160ms] motion-reduce:transition-none',
-  sizeClasses[props.size],
-  props.disabled
-    ? 'cursor-not-allowed bg-cp-bg-container-disabled text-cp-text-disabled shadow-none'
-    : invalid.value
-      ? 'bg-(--cp-input-error-active-bg) shadow-cp-input-error-active'
-      : [
-          'bg-[var(--cp-input-bg)]',
-          'hover:not-focus-within:bg-[var(--cp-input-hover-bg)] hover:not-focus-within:shadow-cp-input-hover',
-          'focus-within:bg-(--cp-input-active-bg) focus-within:shadow-cp-input-active',
-        ],
-])
-
-const iconClasses = computed(() => [
-  'inline-flex shrink-0',
-  props.disabled ? 'text-cp-text-disabled' : invalid.value ? 'text-cp-error' : 'text-cp-text-quaternary',
-])
-
-function updateModel(event: Event) {
-  model.value = (event.target as HTMLInputElement).value
-}
-
-function syncAutofill(event: AnimationEvent) {
-  if (event.animationName === 'base-input-autofill-sync')
-    updateModel(event)
-}
-</script>
-
-<template>
-  <div v-bind="rootAttrs" class="min-w-0">
-    <span :class="containerClasses">
-      <span v-if="$slots.prefix" :class="iconClasses">
-        <slot name="prefix" />
-      </span>
-      <input
-        v-bind="controlAttrs"
-        :id="controlId"
-        :value="model"
-        class="base-input__field h-full min-w-0 flex-1 border-0 bg-transparent font-emphasis leading-[1.15] text-cp-text outline-0 placeholder:text-cp-text-quaternary disabled:cursor-not-allowed disabled:text-cp-text-disabled [&[type=number]]:appearance-[textfield] [&[type=number]::-webkit-inner-spin-button]:m-0 [&[type=number]::-webkit-inner-spin-button]:appearance-none [&[type=number]::-webkit-outer-spin-button]:m-0 [&[type=number]::-webkit-outer-spin-button]:appearance-none"
-        :placeholder="placeholder"
-        :type="type"
-        :disabled="disabled"
-        :required="field?.required.value || undefined"
-        :aria-describedby="describedBy"
-        :aria-invalid="invalid || undefined"
-        :aria-required="field?.required.value || undefined"
-        @animationstart="syncAutofill"
-        @change="updateModel"
-        @input="updateModel"
-      >
-      <span v-if="$slots.suffix" :class="iconClasses">
-        <slot name="suffix" />
-      </span>
-    </span>
-  </div>
-</template>
-
-<style scoped>
-.base-input__field:-webkit-autofill,
-.base-input__field:-webkit-autofill:hover,
-.base-input__field:-webkit-autofill:focus,
-.base-input__field:autofill {
-  animation-name: base-input-autofill-sync;
-  animation-duration: 1ms;
-  background-clip: text !important;
-  caret-color: var(--cp-color-text);
-  -webkit-background-clip: text !important;
-  -webkit-text-fill-color: var(--cp-color-text) !important;
-  -webkit-box-shadow: none !important;
-  box-shadow: none !important;
-}
-
-@keyframes base-input-autofill-sync {
-  from {
-    opacity: 1;
-  }
-
-  to {
-    opacity: 1;
-  }
-}
-</style>
diff --git a/frontend/src/components/base/BaseMarkdown/index.vue b/frontend/src/components/base/BaseMarkdown/index.vue
deleted file mode 100644
index af8536ab2..000000000
--- a/frontend/src/components/base/BaseMarkdown/index.vue
+++ /dev/null
@@ -1,33 +0,0 @@
-<script setup lang="ts">
-import { computed, onMounted, shallowRef, useTemplateRef } from 'vue'
-import { renderMarkdown } from './markdown'
-import markdownStyles from './markdown.css?inline'
-
-const props = defineProps<{
-  source?: string | null
-}>()
-
-const host = useTemplateRef<HTMLElement>('host')
-const contentRoot = shallowRef<HTMLElement | null>(null)
-const html = computed(() => renderMarkdown(props.source))
-
-onMounted(() => {
-  if (!host.value)
-    return
-
-  const shadowRoot = host.value.attachShadow({ mode: 'open' })
-  const style = document.createElement('style')
-  const content = document.createElement('div')
-  style.textContent = markdownStyles
-  shadowRoot.append(style, content)
-  contentRoot.value = content
-})
-</script>
-
-<template>
-  <div ref="host" class="min-w-0">
-    <Teleport v-if="contentRoot" :to="contentRoot">
-      <div class="markdown-body" v-html="html" />
-    </Teleport>
-  </div>
-</template>
diff --git a/frontend/src/components/base/BaseMarkdown/markdown.css b/frontend/src/components/base/BaseMarkdown/markdown.css
deleted file mode 100644
index c028f4a31..000000000
--- a/frontend/src/components/base/BaseMarkdown/markdown.css
+++ /dev/null
@@ -1,102 +0,0 @@
-.markdown-body {
-  color: var(--cp-color-text);
-  font-family: var(--font-sans);
-  font-size: var(--cp-font-size-sm);
-  font-weight: var(--font-weight-emphasis);
-  line-height: 1.65;
-  overflow-wrap: anywhere;
-}
-
-.markdown-body * {
-  box-sizing: border-box;
-  max-width: 100%;
-}
-
-.markdown-body > :first-child {
-  margin-top: 0;
-}
-
-.markdown-body > :last-child {
-  margin-bottom: 0;
-}
-
-.markdown-body h1,
-.markdown-body h2,
-.markdown-body h3,
-.markdown-body h4,
-.markdown-body h5,
-.markdown-body h6 {
-  margin: 12px 0 6px;
-  color: var(--cp-color-text);
-  font-size: inherit;
-  font-weight: var(--font-weight-heavy);
-  line-height: 1.4;
-}
-
-.markdown-body p {
-  margin: 0 0 8px;
-}
-
-.markdown-body ul,
-.markdown-body ol {
-  margin: 0 0 8px;
-  padding-left: 1.5em;
-}
-
-.markdown-body ul {
-  list-style-type: disc;
-}
-
-.markdown-body ol {
-  list-style-type: decimal;
-}
-
-.markdown-body li {
-  margin: 3px 0;
-}
-
-.markdown-body a {
-  color: var(--cp-color-link);
-  font-weight: var(--font-weight-heavy);
-  text-decoration: none;
-}
-
-.markdown-body a:hover {
-  color: var(--cp-color-link-hover);
-  text-decoration: underline;
-}
-
-.markdown-body a:focus-visible {
-  border-radius: var(--cp-border-radius-sm);
-  outline: 2px solid var(--cp-control-outline);
-  outline-offset: 2px;
-}
-
-.markdown-body code {
-  border-radius: var(--cp-border-radius-sm);
-  background: var(--cp-color-fill-tertiary);
-  color: var(--cp-color-text);
-  font-family: var(--font-mono);
-  font-size: var(--cp-font-size-xs);
-  padding: 1px 5px;
-}
-
-.markdown-body pre {
-  margin: 8px 0;
-  overflow-x: auto;
-  border-radius: var(--cp-border-radius);
-  background: var(--cp-color-bg-container);
-  padding: 8px 10px;
-}
-
-.markdown-body pre code {
-  background: transparent;
-  padding: 0;
-}
-
-.markdown-body blockquote {
-  margin: 8px 0;
-  border-left: 3px solid var(--cp-color-split);
-  color: var(--cp-color-text-secondary);
-  padding-left: 10px;
-}
diff --git a/frontend/src/components/base/BaseMarkdown/markdown.ts b/frontend/src/components/base/BaseMarkdown/markdown.ts
deleted file mode 100644
index 160179c1d..000000000
--- a/frontend/src/components/base/BaseMarkdown/markdown.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-import DOMPurify from 'dompurify'
-import { Marked } from 'marked'
-
-const marked = new Marked({
-  async: false,
-  breaks: false,
-  gfm: true,
-})
-
-export function renderMarkdown(source?: string | null) {
-  const value = source?.trim()
-  if (!value)
-    return ''
-
-  const html = marked
-    .parse(value, { async: false })
-    .replaceAll('<a ', '<a target="_blank" rel="noreferrer" ')
-
-  return DOMPurify.sanitize(html, {
-    ADD_ATTR: ['target', 'rel'],
-  })
-}
diff --git a/frontend/src/components/base/BaseMenuItem.vue b/frontend/src/components/base/BaseMenuItem.vue
deleted file mode 100644
index 1b7f60e99..000000000
--- a/frontend/src/components/base/BaseMenuItem.vue
+++ /dev/null
@@ -1,46 +0,0 @@
-<script setup lang="ts">
-import { LoaderCircle } from '@lucide/vue'
-import { computed } from 'vue'
-
-const props = withDefaults(
-  defineProps<{
-    tone?: 'neutral' | 'destructive'
-    disabled?: boolean
-    loading?: boolean
-  }>(),
-  {
-    tone: 'neutral',
-    disabled: false,
-    loading: false,
-  },
-)
-
-defineSlots<{
-  icon?: () => unknown
-  loading?: () => unknown
-  default: () => unknown
-}>()
-
-const classes = computed(() => [
-  'flex min-h-9 w-full touch-manipulation items-center gap-2 rounded-cp-sm border-0 bg-transparent px-3 text-left text-cp leading-none font-emphasis outline-none transition-[background-color,color] duration-150 motion-reduce:transition-none',
-  'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-cp-control-outline',
-  'disabled:cursor-not-allowed disabled:text-cp-text-disabled',
-  props.tone === 'destructive'
-    ? 'text-cp-error-text hover:bg-cp-error-container-hover hover:text-cp-error-on-container'
-    : 'text-cp-text hover:bg-cp-bg-text-hover',
-])
-</script>
-
-<template>
-  <button type="button" :class="classes" :disabled="disabled || loading" :aria-busy="loading || undefined">
-    <span v-if="loading" class="inline-grid size-3.5 shrink-0 place-items-center">
-      <slot name="loading">
-        <LoaderCircle class="size-3.5 animate-spin motion-reduce:animate-none" />
-      </slot>
-    </span>
-    <span v-else-if="$slots.icon" class="inline-grid shrink-0 place-items-center">
-      <slot name="icon" />
-    </span>
-    <span class="min-w-0 flex-1 truncate"><slot /></span>
-  </button>
-</template>
diff --git a/frontend/src/components/base/BaseModal/bodyScrollLock.ts b/frontend/src/components/base/BaseModal/bodyScrollLock.ts
deleted file mode 100644
index 4c803100d..000000000
--- a/frontend/src/components/base/BaseModal/bodyScrollLock.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { useScrollLock } from '@vueuse/core'
-
-let bodyScrollLocked: ReturnType<typeof useScrollLock> | undefined
-let lockCount = 0
-
-function getBodyScrollLock() {
-  if (typeof document === 'undefined')
-    return undefined
-
-  bodyScrollLocked ??= useScrollLock(document.body)
-  return bodyScrollLocked
-}
-
-export function lockBodyScroll() {
-  const scrollLock = getBodyScrollLock()
-  if (!scrollLock)
-    return
-
-  lockCount += 1
-  if (lockCount === 1)
-    scrollLock.value = true
-}
-
-export function unlockBodyScroll() {
-  if (!bodyScrollLocked)
-    return
-
-  lockCount = Math.max(0, lockCount - 1)
-  if (lockCount === 0)
-    bodyScrollLocked.value = false
-}
diff --git a/frontend/src/components/base/BaseModal/index.vue b/frontend/src/components/base/BaseModal/index.vue
deleted file mode 100644
index 64a8752fd..000000000
--- a/frontend/src/components/base/BaseModal/index.vue
+++ /dev/null
@@ -1,343 +0,0 @@
-<script setup lang="ts">
-import { AlertCircle, AlertTriangle, CheckCircle2, Info, X } from '@lucide/vue'
-import { useResizeObserver } from '@vueuse/core'
-import { nextTick, onBeforeUnmount, useId, useTemplateRef, watch } from 'vue'
-
-import BaseIconButton from '../BaseIconButton.vue'
-import BaseScrollbar from '../BaseScrollbar.vue'
-import { lockBodyScroll, unlockBodyScroll } from './bodyScrollLock'
-import { useModalDrag } from './useModalDrag'
-
-type ModalSize = 'sm' | 'md' | 'md-wide' | 'lg' | 'xl'
-type ModalTone = 'neutral' | 'info' | 'warning' | 'danger' | 'success'
-
-const props = withDefaults(
-  defineProps<{
-    title: string
-    description?: string
-    size?: ModalSize
-    tone?: ModalTone
-    dismissible?: boolean
-    draggable?: boolean
-    role?: 'dialog' | 'alertdialog'
-  }>(),
-  {
-    description: undefined,
-    size: 'md',
-    tone: 'neutral',
-    dismissible: true,
-    draggable: true,
-    role: 'dialog',
-  },
-)
-
-const open = defineModel<boolean>({ default: false })
-const panel = useTemplateRef<HTMLElement>('panel')
-const titleId = useId()
-const descriptionId = useId()
-const { cancelDrag, constrainPosition, handlePointerDown, isDragging, resetPosition } = useModalDrag(
-  panel,
-  () => props.draggable,
-)
-let previouslyFocused: HTMLElement | null = null
-let ownsScrollLock = false
-
-// 内容分段可能在弹窗打开期间改变面板高度；拖拽偏移必须随尺寸重新约束到视口内。
-useResizeObserver(panel, () => {
-  if (open.value)
-    constrainPosition()
-})
-
-const focusableSelector = [
-  'a[href]',
-  'button:not([disabled])',
-  'input:not([disabled])',
-  'select:not([disabled])',
-  'textarea:not([disabled])',
-  '[tabindex]:not([tabindex="-1"])',
-].join(',')
-
-const sizeClasses: Record<ModalSize, string> = {
-  'sm': 'max-w-md',
-  'md': 'max-w-xl',
-  'md-wide': 'max-w-2xl',
-  'lg': 'max-w-3xl',
-  'xl': 'max-w-5xl',
-}
-
-const iconMap = {
-  neutral: Info,
-  info: Info,
-  warning: AlertTriangle,
-  danger: AlertCircle,
-  success: CheckCircle2,
-}
-
-const toneClasses: Record<ModalTone, { iconBg: string, icon: string }> = {
-  neutral: {
-    iconBg: 'bg-cp-fill-quaternary',
-    icon: 'text-cp-text-secondary',
-  },
-  info: {
-    iconBg: 'bg-cp-info-container',
-    icon: 'text-cp-info',
-  },
-  warning: {
-    iconBg: 'bg-cp-warning-container',
-    icon: 'text-cp-warning',
-  },
-  danger: {
-    iconBg: 'bg-cp-error-container',
-    icon: 'text-cp-error',
-  },
-  success: {
-    iconBg: 'bg-cp-success-container',
-    icon: 'text-cp-success',
-  },
-}
-
-function closeModal() {
-  if (!props.dismissible)
-    return
-  open.value = false
-}
-
-function focusableElements(root: ParentNode | null = panel.value): HTMLElement[] {
-  if (!root)
-    return []
-
-  const elements: HTMLElement[] = []
-  for (const element of root.children) {
-    if (element instanceof HTMLElement && element.matches(focusableSelector) && !element.hidden)
-      elements.push(element)
-    elements.push(...focusableElements(element.shadowRoot ?? element))
-  }
-  return elements
-}
-
-function handleKeydown(event: KeyboardEvent) {
-  if (event.key === 'Escape') {
-    event.preventDefault()
-    closeModal()
-    return
-  }
-  if (event.key !== 'Tab')
-    return
-
-  const focusable = focusableElements()
-  if (focusable.length === 0) {
-    event.preventDefault()
-    panel.value?.focus()
-    return
-  }
-  const first = focusable[0]
-  const last = focusable[focusable.length - 1]
-  let activeElement = document.activeElement
-  while (activeElement?.shadowRoot?.activeElement)
-    activeElement = activeElement.shadowRoot.activeElement
-  if (!panel.value?.contains(document.activeElement)) {
-    event.preventDefault()
-    if (event.shiftKey)
-      last?.focus()
-    else first?.focus()
-  }
-  else if (event.shiftKey && activeElement === first) {
-    event.preventDefault()
-    last?.focus()
-  }
-  else if (!event.shiftKey && activeElement === last) {
-    event.preventDefault()
-    first?.focus()
-  }
-}
-
-function acquireScrollLock() {
-  if (ownsScrollLock)
-    return
-  ownsScrollLock = true
-  lockBodyScroll()
-}
-
-function releaseScrollLock() {
-  if (!ownsScrollLock)
-    return
-  ownsScrollLock = false
-  unlockBodyScroll()
-}
-
-function restorePreviousFocus() {
-  if (previouslyFocused?.isConnected)
-    previouslyFocused.focus()
-  previouslyFocused = null
-}
-
-watch(
-  open,
-  async (isOpen) => {
-    if (isOpen) {
-      previouslyFocused
-        = document.activeElement instanceof HTMLElement ? document.activeElement : null
-      acquireScrollLock()
-      await nextTick()
-      const first = focusableElements()[0]
-      if (first)
-        first.focus()
-      else panel.value?.focus()
-      return
-    }
-
-    cancelDrag()
-    releaseScrollLock()
-    restorePreviousFocus()
-  },
-  { immediate: true },
-)
-
-onBeforeUnmount(() => {
-  releaseScrollLock()
-  restorePreviousFocus()
-})
-</script>
-
-<template>
-  <Teleport to="body">
-    <Transition name="cp-modal" @after-leave="resetPosition">
-      <div
-        v-if="open"
-        class="fixed inset-0 z-50 grid place-items-center overflow-hidden p-3 sm:p-6"
-        role="presentation"
-        @keydown="handleKeydown"
-      >
-        <button
-          type="button"
-          tabindex="-1"
-          aria-label="关闭弹窗"
-          class="absolute inset-0 cursor-default border-0 bg-cp-bg-mask p-0"
-          @click="closeModal"
-        />
-        <section
-          ref="panel"
-          class="cp-modal-panel relative grid max-h-[calc(100dvh-1.5rem)] w-full min-w-0 overflow-hidden rounded-cp-card bg-cp-modal-bg shadow-cp sm:max-h-[calc(100dvh-3rem)]"
-          :class="[
-            sizeClasses[size],
-            $slots.default ? 'grid-rows-[auto_minmax(0,1fr)_auto]' : 'grid-rows-[auto_auto]',
-            isDragging ? 'cp-modal-panel--dragging' : undefined,
-          ]"
-          :role="role"
-          aria-modal="true"
-          :aria-labelledby="titleId"
-          :aria-describedby="description || $slots.description ? descriptionId : undefined"
-          tabindex="-1"
-        >
-          <header
-            class="cp-modal-header grid shrink-0 gap-3 p-4 pb-0 sm:gap-4 sm:p-6 sm:pb-0"
-            :class="[
-              tone === 'neutral'
-                ? 'grid-cols-[minmax(0,1fr)_28px]'
-                : 'grid-cols-[auto_minmax(0,1fr)_28px]',
-              description || $slots.description ? 'items-start' : 'items-center',
-              draggable ? 'cp-modal-header--draggable' : undefined,
-            ]"
-            @pointerdown="handlePointerDown"
-          >
-            <span
-              v-if="tone !== 'neutral'"
-              class="inline-flex size-11 items-center justify-center rounded-cp"
-              :class="$slots.icon ? 'bg-cp-fill-quaternary' : toneClasses[tone].iconBg"
-            >
-              <slot name="icon">
-                <component :is="iconMap[tone]" :size="18" :class="toneClasses[tone].icon" />
-              </slot>
-            </span>
-            <div class="min-w-0">
-              <h2 :id="titleId" class="relative top-px m-0 text-lg leading-[1.15] font-heavy text-cp-text">
-                {{ title }}
-              </h2>
-              <p
-                v-if="description || $slots.description"
-                :id="descriptionId"
-                class="mt-1 mb-0 text-cp leading-[1.45] font-semibold text-cp-text-secondary"
-              >
-                <slot name="description">
-                  {{ description }}
-                </slot>
-              </p>
-            </div>
-            <BaseIconButton
-              label="关闭"
-              size="sm"
-              variant="ghost"
-              :disabled="!dismissible"
-              @click="closeModal"
-            >
-              <X :size="16" />
-            </BaseIconButton>
-          </header>
-          <div v-if="$slots.default" class="min-h-0 overflow-hidden px-3.25 py-3.25 sm:px-5.25 sm:py-5.25">
-            <BaseScrollbar
-              class="h-full -mr-2 pr-2 sm:-mr-3 sm:pr-3"
-            >
-              <div class="p-0.75">
-                <slot />
-              </div>
-            </BaseScrollbar>
-          </div>
-          <footer
-            v-if="$slots.footer"
-            class="flex shrink-0 flex-wrap justify-end gap-2 px-4 pb-4 sm:gap-3 sm:px-6 sm:pb-6"
-          >
-            <slot name="footer" />
-          </footer>
-        </section>
-      </div>
-    </Transition>
-  </Teleport>
-</template>
-
-<style scoped>
-.cp-modal-enter-active,
-.cp-modal-leave-active {
-  transition: opacity 180ms ease;
-}
-
-.cp-modal-enter-active .cp-modal-panel,
-.cp-modal-leave-active .cp-modal-panel {
-  transition:
-    opacity 180ms ease,
-    transform 180ms ease;
-}
-
-.cp-modal-enter-from,
-.cp-modal-leave-to {
-  opacity: 0;
-}
-
-.cp-modal-enter-from .cp-modal-panel {
-  opacity: 0;
-  transform: translate3d(0, 8px, 0) scale(0.985);
-}
-
-.cp-modal-leave-to .cp-modal-panel {
-  opacity: 0;
-  transform: translate3d(0, 4px, 0) scale(0.99);
-}
-
-.cp-modal-header--draggable {
-  cursor: move;
-  touch-action: none;
-  user-select: none;
-}
-
-.cp-modal-panel--dragging .cp-modal-header {
-  cursor: grabbing;
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .cp-modal-enter-active,
-  .cp-modal-leave-active,
-  .cp-modal-enter-active .cp-modal-panel,
-  .cp-modal-leave-active .cp-modal-panel {
-    transition: none;
-  }
-}
-</style>
diff --git a/frontend/src/components/base/BaseModal/useModalDrag.ts b/frontend/src/components/base/BaseModal/useModalDrag.ts
deleted file mode 100644
index 992cf0066..000000000
--- a/frontend/src/components/base/BaseModal/useModalDrag.ts
+++ /dev/null
@@ -1,166 +0,0 @@
-import type { ShallowRef } from 'vue'
-
-import { onBeforeUnmount, onMounted, shallowRef } from 'vue'
-
-const VIEWPORT_GUTTER = 8
-const interactiveSelector = 'button, a, input, select, textarea, [role="button"], [data-modal-drag-ignore]'
-
-interface DragSession {
-  pointerId: number
-  startX: number
-  startY: number
-  originX: number
-  originY: number
-  minX: number
-  maxX: number
-  minY: number
-  maxY: number
-}
-
-function clamp(value: number, min: number, max: number) {
-  return Math.min(max, Math.max(min, value))
-}
-
-export function useModalDrag(
-  target: Readonly<ShallowRef<HTMLElement | null>>,
-  enabled: () => boolean,
-) {
-  const isDragging = shallowRef(false)
-  const offset = { x: 0, y: 0 }
-  let session: DragSession | null = null
-
-  function applyPosition() {
-    if (!target.value)
-      return
-
-    // 使用相对定位保留普通绘制，避免变换合成层在表格单元格之间产生像素缝。
-    target.value.style.left = offset.x === 0 ? '' : `${offset.x}px`
-    target.value.style.top = offset.y === 0 ? '' : `${offset.y}px`
-  }
-
-  function removeDragListeners() {
-    document.removeEventListener('pointermove', handlePointerMove)
-    document.removeEventListener('pointerup', endDrag)
-    document.removeEventListener('pointercancel', endDrag)
-    window.removeEventListener('blur', handleWindowBlur)
-  }
-
-  function endDrag(event?: PointerEvent) {
-    if (event && session && event.pointerId !== session.pointerId)
-      return
-
-    session = null
-    isDragging.value = false
-    removeDragListeners()
-  }
-
-  function handlePointerMove(event: PointerEvent) {
-    if (!session || event.pointerId !== session.pointerId)
-      return
-    if (!enabled()) {
-      endDrag()
-      return
-    }
-
-    event.preventDefault()
-    offset.x = clamp(
-      session.originX + event.clientX - session.startX,
-      session.minX,
-      session.maxX,
-    )
-    offset.y = clamp(
-      session.originY + event.clientY - session.startY,
-      session.minY,
-      session.maxY,
-    )
-    applyPosition()
-  }
-
-  function handlePointerDown(event: PointerEvent) {
-    if (!enabled() || !event.isPrimary || event.button !== 0)
-      return
-
-    const eventTarget = event.target
-    if (eventTarget instanceof Element && eventTarget.closest(interactiveSelector))
-      return
-
-    const element = target.value
-    if (!element)
-      return
-
-    const rect = element.getBoundingClientRect()
-    const viewportWidth = document.documentElement.clientWidth
-    const viewportHeight = document.documentElement.clientHeight
-
-    session = {
-      pointerId: event.pointerId,
-      startX: event.clientX,
-      startY: event.clientY,
-      originX: offset.x,
-      originY: offset.y,
-      minX: offset.x - rect.left + VIEWPORT_GUTTER,
-      maxX: offset.x + viewportWidth - rect.right - VIEWPORT_GUTTER,
-      minY: offset.y - rect.top + VIEWPORT_GUTTER,
-      maxY: offset.y + viewportHeight - rect.bottom - VIEWPORT_GUTTER,
-    }
-    isDragging.value = true
-    event.preventDefault()
-
-    document.addEventListener('pointermove', handlePointerMove, { passive: false })
-    document.addEventListener('pointerup', endDrag)
-    document.addEventListener('pointercancel', endDrag)
-    window.addEventListener('blur', handleWindowBlur)
-  }
-
-  function handleWindowBlur() {
-    endDrag()
-  }
-
-  function updatePosition() {
-    const element = target.value
-    if (!element)
-      return
-
-    const rect = element.getBoundingClientRect()
-    const viewportWidth = document.documentElement.clientWidth
-    const viewportHeight = document.documentElement.clientHeight
-
-    if (rect.left < VIEWPORT_GUTTER)
-      offset.x += VIEWPORT_GUTTER - rect.left
-    else if (rect.right > viewportWidth - VIEWPORT_GUTTER)
-      offset.x -= rect.right - viewportWidth + VIEWPORT_GUTTER
-
-    if (rect.top < VIEWPORT_GUTTER)
-      offset.y += VIEWPORT_GUTTER - rect.top
-    else if (rect.bottom > viewportHeight - VIEWPORT_GUTTER)
-      offset.y -= rect.bottom - viewportHeight + VIEWPORT_GUTTER
-
-    applyPosition()
-  }
-
-  function resetPosition() {
-    endDrag()
-    offset.x = 0
-    offset.y = 0
-    applyPosition()
-  }
-
-  function handleResize() {
-    endDrag()
-    updatePosition()
-  }
-
-  onMounted(() => window.addEventListener('resize', handleResize))
-  onBeforeUnmount(() => {
-    endDrag()
-    window.removeEventListener('resize', handleResize)
-  })
-
-  return {
-    cancelDrag: endDrag,
-    constrainPosition: updatePosition,
-    handlePointerDown,
-    isDragging,
-    resetPosition,
-  }
-}
diff --git a/frontend/src/components/base/BaseMotionIcon.vue b/frontend/src/components/base/BaseMotionIcon.vue
deleted file mode 100644
index 4ee7f1991..000000000
--- a/frontend/src/components/base/BaseMotionIcon.vue
+++ /dev/null
@@ -1,304 +0,0 @@
-<script setup lang="ts">
-import { usePreferredReducedMotion } from '@vueuse/core'
-import { gsap } from 'gsap'
-import { onBeforeUnmount, useTemplateRef, watch } from 'vue'
-
-type MotionIconVariant = 'random' | 'brand'
-type MotionPhase = 'enter' | 'leave'
-type MotionTimeline = ReturnType<typeof gsap.timeline>
-type ReactionBuilder = (root: HTMLElement, glyph: HTMLElement) => MotionTimeline
-
-interface MotionReaction {
-  enter: ReactionBuilder
-  leave: ReactionBuilder
-}
-
-const props = withDefaults(
-  defineProps<{
-    as?: keyof HTMLElementTagNameMap
-    variant?: MotionIconVariant
-  }>(),
-  {
-    as: 'span',
-    variant: 'random',
-  },
-)
-
-const preferredMotion = usePreferredReducedMotion()
-const icon = useTemplateRef<HTMLElement>('icon')
-const glyph = useTemplateRef<HTMLElement>('glyph')
-const randomReactions: MotionReaction[] = [
-  { enter: liftAndBloomEnter, leave: liftAndBloomLeave },
-  { enter: lookAroundEnter, leave: lookAroundLeave },
-  { enter: doubleTapEnter, leave: doubleTapLeave },
-  { enter: counterSwingEnter, leave: counterSwingLeave },
-  { enter: shortOrbitEnter, leave: shortOrbitLeave },
-]
-const brandReaction: MotionReaction = {
-  enter: brandGreetingEnter,
-  leave: brandGreetingLeave,
-}
-let previousReactionIndex = -1
-let activeReaction: MotionReaction | undefined
-let activeTimeline: MotionTimeline | undefined
-let isPointerInside = false
-
-function motionTargets() {
-  return [icon.value, glyph.value].filter((target): target is HTMLElement => Boolean(target))
-}
-
-function clearMotionStyles(element: HTMLElement) {
-  gsap.set(element, { clearProps: 'transform,transformOrigin,willChange' })
-}
-
-function stopActiveTimeline(targets: HTMLElement[]) {
-  activeTimeline?.kill()
-  activeTimeline = undefined
-  gsap.killTweensOf(targets)
-}
-
-function resetMotion() {
-  const targets = motionTargets()
-  stopActiveTimeline(targets)
-  activeReaction = undefined
-  for (const target of targets) clearMotionStyles(target)
-}
-
-function createMotionTimeline(root: HTMLElement, glyphElement: HTMLElement, phase: MotionPhase) {
-  const targets = [root, glyphElement]
-  stopActiveTimeline(targets)
-  gsap.set(targets, { willChange: 'transform' })
-
-  const timeline = gsap.timeline({
-    defaults: { ease: 'power2.out' },
-    onComplete: () => {
-      if (activeTimeline !== timeline)
-        return
-      activeTimeline = undefined
-
-      if (phase === 'leave' && !isPointerInside) {
-        activeReaction = undefined
-        for (const target of targets) clearMotionStyles(target)
-        return
-      }
-
-      gsap.set(targets, { clearProps: 'willChange' })
-    },
-  })
-  activeTimeline = timeline
-  return timeline
-}
-
-function nextRandomReaction() {
-  const index
-    = previousReactionIndex < 0
-      ? Math.floor(Math.random() * randomReactions.length)
-      : (previousReactionIndex + 1 + Math.floor(Math.random() * (randomReactions.length - 1)))
-        % randomReactions.length
-  previousReactionIndex = index
-  return randomReactions[index]!
-}
-
-function liftAndBloomEnter(root: HTMLElement, glyphElement: HTMLElement) {
-  const timeline = createMotionTimeline(root, glyphElement, 'enter')
-  timeline
-    .to(root, { y: -3, scale: 1.055, duration: 0.22 }, 0)
-    .to(
-      glyphElement,
-      { y: -0.5, rotation: -4, scale: 1.13, duration: 0.26, ease: 'back.out(2.1)' },
-      0.02,
-    )
-  return timeline
-}
-
-function liftAndBloomLeave(root: HTMLElement, glyphElement: HTMLElement) {
-  const timeline = createMotionTimeline(root, glyphElement, 'leave')
-  timeline
-    .to(glyphElement, { y: 0, rotation: 0, scale: 1, duration: 0.24, ease: 'back.out(1.6)' }, 0)
-    .to(root, { y: 0, scale: 1, duration: 0.22, ease: 'power3.out' }, 0.02)
-  return timeline
-}
-
-function lookAroundEnter(root: HTMLElement, glyphElement: HTMLElement) {
-  const timeline = createMotionTimeline(root, glyphElement, 'enter')
-  timeline
-    .to(root, { y: -1, scale: 1.025, duration: 0.2 }, 0)
-    .to(glyphElement, { x: -2.5, rotation: -7, duration: 0.13 }, 0)
-    .to(glyphElement, { x: 2.5, rotation: 7, duration: 0.17, ease: 'power2.inOut' }, 0.13)
-    .to(
-      glyphElement,
-      { x: 1, rotation: 3, scale: 1.06, duration: 0.16, ease: 'back.out(1.7)' },
-      0.3,
-    )
-  return timeline
-}
-
-function lookAroundLeave(root: HTMLElement, glyphElement: HTMLElement) {
-  const timeline = createMotionTimeline(root, glyphElement, 'leave')
-  timeline
-    .to(glyphElement, { x: 0, rotation: 0, scale: 1, duration: 0.24, ease: 'back.out(1.7)' }, 0)
-    .to(root, { y: 0, scale: 1, duration: 0.22, ease: 'power3.out' }, 0.02)
-  return timeline
-}
-
-function doubleTapEnter(root: HTMLElement, glyphElement: HTMLElement) {
-  const timeline = createMotionTimeline(root, glyphElement, 'enter')
-  timeline
-    .to(root, { y: 1, scale: 0.965, duration: 0.09, ease: 'power2.in' }, 0)
-    .to(glyphElement, { y: 1.5, scale: 0.92, duration: 0.09, ease: 'power2.in' }, 0)
-    .to(root, { y: -3, scale: 1.055, duration: 0.17, ease: 'back.out(2.2)' }, 0.09)
-    .to(glyphElement, { y: -2, scale: 1.12, duration: 0.19, ease: 'back.out(2.4)' }, 0.09)
-  return timeline
-}
-
-function doubleTapLeave(root: HTMLElement, glyphElement: HTMLElement) {
-  const timeline = createMotionTimeline(root, glyphElement, 'leave')
-  timeline
-    .to(root, { y: 0.5, scale: 0.985, duration: 0.1, ease: 'power2.in' }, 0)
-    .to(glyphElement, { y: 0.75, scale: 0.97, duration: 0.1, ease: 'power2.in' }, 0)
-    .to(root, { y: 0, scale: 1, duration: 0.17, ease: 'back.out(1.8)' }, 0.1)
-    .to(glyphElement, { y: 0, scale: 1, duration: 0.18, ease: 'back.out(1.9)' }, 0.1)
-  return timeline
-}
-
-function counterSwingEnter(root: HTMLElement, glyphElement: HTMLElement) {
-  const timeline = createMotionTimeline(root, glyphElement, 'enter')
-  timeline
-    .to(root, { x: -1.5, y: -1.5, rotation: -4, scale: 1.035, duration: 0.14 }, 0)
-    .to(glyphElement, { x: 2, rotation: 8, duration: 0.14 }, 0)
-    .to(root, { x: 1, y: -1, rotation: 2, duration: 0.15, ease: 'power2.inOut' }, 0.14)
-    .to(glyphElement, { x: -1, rotation: -5, duration: 0.15, ease: 'power2.inOut' }, 0.14)
-  return timeline
-}
-
-function counterSwingLeave(root: HTMLElement, glyphElement: HTMLElement) {
-  const timeline = createMotionTimeline(root, glyphElement, 'leave')
-  timeline
-    .to(root, { x: 0, y: 0, rotation: 0, scale: 1, duration: 0.23, ease: 'back.out(1.6)' }, 0)
-    .to(glyphElement, { x: 0, rotation: 0, duration: 0.21, ease: 'back.out(1.8)' }, 0.02)
-  return timeline
-}
-
-function shortOrbitEnter(root: HTMLElement, glyphElement: HTMLElement) {
-  const timeline = createMotionTimeline(root, glyphElement, 'enter')
-  timeline
-    .to(root, { y: -1.5, scale: 1.025, duration: 0.18 }, 0)
-    .to(glyphElement, { x: 2.5, y: -2, rotation: 5, duration: 0.13 }, 0)
-    .to(glyphElement, { x: -2, y: -0.5, rotation: -5, duration: 0.15 }, 0.13)
-    .to(
-      glyphElement,
-      { x: 0.75, y: -1, rotation: 2, scale: 1.08, duration: 0.18, ease: 'back.out(1.8)' },
-      0.28,
-    )
-  return timeline
-}
-
-function shortOrbitLeave(root: HTMLElement, glyphElement: HTMLElement) {
-  const timeline = createMotionTimeline(root, glyphElement, 'leave')
-  timeline
-    .to(glyphElement, {
-      x: 0,
-      y: 0,
-      rotation: 0,
-      scale: 1,
-      duration: 0.24,
-      ease: 'back.out(1.7)',
-    })
-    .to(root, { y: 0, scale: 1, duration: 0.22, ease: 'power3.out' }, 0.02)
-  return timeline
-}
-
-function brandGreetingEnter(root: HTMLElement, glyphElement: HTMLElement) {
-  const timeline = createMotionTimeline(root, glyphElement, 'enter')
-  timeline
-    .to(root, { scale: 0.965, duration: 0.09, ease: 'power2.in' }, 0)
-    .to(glyphElement, { y: 1, scale: 0.92, duration: 0.09, ease: 'power2.in' }, 0)
-    .to(root, { scale: 1, duration: 0.18, ease: 'back.out(2.4)' }, 0.09)
-    .to(
-      glyphElement,
-      { y: -1.5, rotation: -5, scale: 1.28, duration: 0.22, ease: 'back.out(3)' },
-      0.08,
-    )
-    .to(glyphElement, { x: 1, rotation: 4, scale: 1.2, duration: 0.13, ease: 'power1.inOut' }, 0.3)
-    .to(
-      glyphElement,
-      { x: -0.5, rotation: -2, scale: 1.24, duration: 0.11, ease: 'power1.inOut' },
-      0.43,
-    )
-  return timeline
-}
-
-function brandGreetingLeave(root: HTMLElement, glyphElement: HTMLElement) {
-  const timeline = createMotionTimeline(root, glyphElement, 'leave')
-  timeline
-    .to(glyphElement, {
-      x: 0.35,
-      y: -0.5,
-      rotation: 1,
-      scale: 1.08,
-      duration: 0.14,
-      ease: 'power2.in',
-    })
-    .to(root, { scale: 0.985, duration: 0.14, ease: 'power2.in' }, 0)
-    .to(
-      glyphElement,
-      { x: 0, y: 0, rotation: 0, scale: 1, duration: 0.2, ease: 'back.out(1.8)' },
-      0.12,
-    )
-    .to(root, { scale: 1, duration: 0.2, ease: 'back.out(1.7)' }, 0.12)
-  return timeline
-}
-
-function playEnterReaction() {
-  isPointerInside = true
-  if (preferredMotion.value === 'reduce') {
-    resetMotion()
-    return
-  }
-
-  const root = icon.value
-  const glyphElement = glyph.value
-  if (!root || !glyphElement)
-    return
-
-  activeReaction = props.variant === 'brand' ? brandReaction : nextRandomReaction()
-  activeReaction.enter(root, glyphElement)
-}
-
-function playLeaveReaction() {
-  isPointerInside = false
-  if (preferredMotion.value === 'reduce') {
-    resetMotion()
-    return
-  }
-
-  const root = icon.value
-  const glyphElement = glyph.value
-  if (!root || !glyphElement || !activeReaction) {
-    resetMotion()
-    return
-  }
-
-  activeReaction.leave(root, glyphElement)
-}
-
-watch(preferredMotion, (motion) => {
-  if (motion === 'reduce')
-    resetMotion()
-})
-
-onBeforeUnmount(resetMotion)
-</script>
-
-<template>
-  <component
-    :is="props.as"
-    ref="icon"
-    @pointerenter="playEnterReaction"
-    @pointerleave="playLeaveReaction"
-  >
-    <span ref="glyph" class="inline-flex items-center justify-center">
-      <slot />
-    </span>
-  </component>
-</template>
diff --git a/frontend/src/components/base/BaseNumberInput.vue b/frontend/src/components/base/BaseNumberInput.vue
deleted file mode 100644
index 9dbefe118..000000000
--- a/frontend/src/components/base/BaseNumberInput.vue
+++ /dev/null
@@ -1,113 +0,0 @@
-<script setup lang="ts">
-import { Minus, Plus } from '@lucide/vue'
-import { computed, useAttrs } from 'vue'
-
-import BaseIconButton from './BaseIconButton.vue'
-
-defineOptions({ inheritAttrs: false })
-
-const props = withDefaults(
-  defineProps<{
-    label: string
-    min?: number
-    max?: number
-    step?: number
-    unit?: string
-    disabled?: boolean
-  }>(),
-  {
-    min: undefined,
-    max: undefined,
-    step: 1,
-    unit: undefined,
-    disabled: false,
-  },
-)
-
-const model = defineModel<number>({ required: true })
-const attrs = useAttrs()
-
-const rootAttrs = computed(() => ({ class: attrs.class, style: attrs.style }))
-const controlAttrs = computed(() =>
-  Object.fromEntries(Object.entries(attrs).filter(([key]) => !['class', 'style'].includes(key))),
-)
-const canDecrease = computed(() => !props.disabled && (props.min === undefined || model.value > props.min))
-const canIncrease = computed(() => !props.disabled && (props.max === undefined || model.value < props.max))
-
-function clampValue(value: number) {
-  return Math.min(props.max ?? Number.POSITIVE_INFINITY, Math.max(props.min ?? Number.NEGATIVE_INFINITY, value))
-}
-
-function stepPrecision() {
-  const decimal = String(props.step).split('.')[1]
-  return decimal?.length ?? 0
-}
-
-function updateModel(event: Event) {
-  const value = (event.target as HTMLInputElement).valueAsNumber
-  if (Number.isFinite(value))
-    model.value = clampValue(value)
-}
-
-function restoreValue(event: Event) {
-  const input = event.target as HTMLInputElement
-  input.value = String(model.value)
-}
-
-function stepBy(direction: -1 | 1) {
-  const next = clampValue(model.value + props.step * direction)
-  model.value = Number(next.toFixed(stepPrecision()))
-}
-</script>
-
-<template>
-  <div
-    v-bind="rootAttrs"
-    class="inline-flex h-8 items-center rounded-cp p-0.5 text-cp-text transition-[background-color,box-shadow] duration-150 motion-reduce:transition-none"
-    :class="disabled
-      ? 'cursor-not-allowed bg-cp-bg-container-disabled'
-      : 'bg-[var(--cp-input-bg)] shadow-cp-input hover:not-focus-within:bg-[var(--cp-input-hover-bg)] hover:not-focus-within:shadow-cp-input-hover focus-within:bg-(--cp-input-active-bg) focus-within:shadow-cp-input-active'"
-  >
-    <BaseIconButton
-      :label="`减少${label}`"
-      size="sm"
-      variant="ghost"
-      class="size-7!"
-      :disabled="!canDecrease"
-      @click="stepBy(-1)"
-    >
-      <Minus class="size-3" />
-    </BaseIconButton>
-
-    <span class="inline-flex min-w-0 items-baseline justify-center gap-1 px-1">
-      <input
-        v-bind="controlAttrs"
-        :value="model"
-        type="number"
-        inputmode="decimal"
-        :aria-label="label"
-        :min="min"
-        :max="max"
-        :step="step"
-        :disabled="disabled"
-        class="w-9 min-w-0 appearance-[textfield] border-0 bg-transparent p-0 text-right font-mono text-cp-xs font-bold tabular-nums text-cp-text outline-none disabled:text-cp-text-disabled [&::-webkit-inner-spin-button]:m-0 [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:m-0 [&::-webkit-outer-spin-button]:appearance-none"
-        @input="updateModel"
-        @blur="restoreValue"
-      >
-      <span v-if="unit" class="shrink-0 text-[9px] font-emphasis text-cp-text-quaternary">
-        {{ unit }}
-      </span>
-    </span>
-
-    <BaseIconButton
-      :label="`增加${label}`"
-      size="sm"
-      variant="ghost"
-      class="size-7!"
-      :disabled="!canIncrease"
-      @click="stepBy(1)"
-    >
-      <Plus class="size-3" />
-    </BaseIconButton>
-  </div>
-</template>
diff --git a/frontend/src/components/base/BasePageHeader.vue b/frontend/src/components/base/BasePageHeader.vue
deleted file mode 100644
index 96dae4f0d..000000000
--- a/frontend/src/components/base/BasePageHeader.vue
+++ /dev/null
@@ -1,32 +0,0 @@
-<script setup lang="ts">
-defineProps<{
-  title: string
-  description?: string
-}>()
-</script>
-
-<template>
-  <header
-    class="flex min-h-17 shrink-0 flex-wrap items-start justify-between gap-x-4 gap-y-3"
-  >
-    <div class="min-w-0 flex-1 basis-64">
-      <h1 class="m-0 text-[34px] leading-[1.15] font-extrabold text-cp-text">
-        {{ title }}
-      </h1>
-      <p
-        v-if="description || $slots.description"
-        class="mt-2.5 mb-0 flex items-center gap-2 text-cp-xl leading-[1.15] font-semibold text-cp-text-secondary"
-      >
-        <slot name="description">
-          {{ description }}
-        </slot>
-      </p>
-    </div>
-    <div
-      v-if="$slots.actions"
-      class="mt-0.5 flex shrink-0 items-center justify-end gap-2"
-    >
-      <slot name="actions" />
-    </div>
-  </header>
-</template>
diff --git a/frontend/src/components/base/BasePopover.vue b/frontend/src/components/base/BasePopover.vue
deleted file mode 100644
index b2660d4a0..000000000
--- a/frontend/src/components/base/BasePopover.vue
+++ /dev/null
@@ -1,412 +0,0 @@
-<script setup lang="ts">
-import type { CSSProperties } from 'vue'
-import { onClickOutside, useEventListener, useThrottleFn, whenever } from '@vueuse/core'
-import { clamp } from 'es-toolkit'
-import { computed, nextTick, onBeforeUnmount, ref, shallowRef, useAttrs, watch } from 'vue'
-
-type PopoverPlacement
-  = 'top' | 'top-start' | 'top-end' | 'right' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left'
-type PopoverTrigger = 'click' | 'hover' | 'hover-click'
-type PopoverSide = 'top' | 'right' | 'bottom' | 'left'
-type PopoverArrowSurfaceClass = string | Partial<Record<PopoverSide, string>>
-
-interface PopoverPoint {
-  left: number
-  top: number
-}
-
-interface PopoverPosition {
-  placement: PopoverPlacement
-  point: PopoverPoint
-}
-
-defineOptions({
-  inheritAttrs: false,
-})
-
-const props = withDefaults(
-  defineProps<{
-    placement?: PopoverPlacement
-    trigger?: PopoverTrigger
-    offset?: number
-    disabled?: boolean
-    /** 包含 hover 的触发方式打开弹窗的延迟（毫秒）；click 触发不生效。 */
-    hoverDelay?: number
-    anchorElement?: HTMLElement | null
-    animatePosition?: boolean
-    /** 箭头贴合不同内容边缘时使用的表面类；字符串表示所有边缘共用。 */
-    arrowSurfaceClass?: PopoverArrowSurfaceClass
-  }>(),
-  {
-    placement: 'bottom-end',
-    trigger: 'click',
-    offset: 6,
-    disabled: false,
-    hoverDelay: 400,
-    anchorElement: null,
-    animatePosition: false,
-  },
-)
-
-const open = defineModel<boolean>({ default: false })
-const attrs = useAttrs()
-
-const rootRef = ref<HTMLElement | null>(null)
-const popoverRef = ref<HTMLElement | null>(null)
-const popoverStyle = ref<CSSProperties>({})
-const popoverArrowStyle = ref<CSSProperties>({})
-const popoverPlacement = shallowRef<PopoverPlacement>(props.placement)
-const hoverCloseTimer = shallowRef<number>()
-const hoverOpenTimer = shallowRef<number>()
-const viewportTarget = computed(() => (open.value && typeof window !== 'undefined' ? window : null))
-
-const popoverClasses = computed(() => [
-  'fixed z-50 overflow-visible rounded-cp-lg border-0 bg-cp-bg-elevated text-left text-cp-text shadow-cp',
-  props.animatePosition
-    ? 'transition-[left,top] duration-150 ease-out motion-reduce:transition-none'
-    : undefined,
-])
-const popoverArrowSurfaceClass = computed(() => {
-  if (typeof props.arrowSurfaceClass === 'string')
-    return props.arrowSurfaceClass
-
-  return props.arrowSurfaceClass?.[popoverArrowEdge(popoverPlacement.value)] ?? 'bg-inherit'
-})
-
-function updatePopoverPosition() {
-  const anchorElement = props.anchorElement ?? rootRef.value
-  if (!open.value || !anchorElement)
-    return
-
-  const viewportPadding = 8
-  const triggerRect = anchorElement.getBoundingClientRect()
-  const panelRect = popoverRef.value?.getBoundingClientRect()
-  const panelWidth = panelRect?.width ?? 0
-  const panelHeight = panelRect?.height ?? 0
-  const maxLeft = Math.max(viewportPadding, window.innerWidth - panelWidth - viewportPadding)
-  const maxTop = Math.max(viewportPadding, window.innerHeight - panelHeight - viewportPadding)
-  const position = choosePopoverPosition({
-    placement: props.placement,
-    triggerRect,
-    panelWidth,
-    panelHeight,
-    offset: props.offset,
-    viewportPadding,
-  })
-  popoverPlacement.value = position.placement
-  const left = clamp(position.point.left, viewportPadding, maxLeft)
-  const top = clamp(position.point.top, viewportPadding, maxTop)
-
-  popoverStyle.value = {
-    left: `${left}px`,
-    top: `${top}px`,
-    maxWidth: `calc(100vw - ${viewportPadding * 2}px)`,
-  }
-  popoverArrowStyle.value = popoverArrowPosition({
-    placement: position.placement,
-    triggerRect,
-    panelWidth,
-    panelHeight,
-    left,
-    top,
-  })
-}
-
-function popoverArrowEdge(placement: PopoverPlacement): PopoverSide {
-  const placementSide = placement.split('-')[0] as PopoverSide
-  const oppositeSide: Record<PopoverSide, PopoverSide> = {
-    top: 'bottom',
-    right: 'left',
-    bottom: 'top',
-    left: 'right',
-  }
-
-  return oppositeSide[placementSide]
-}
-
-function choosePopoverPosition(options: {
-  placement: PopoverPlacement
-  triggerRect: DOMRect
-  panelWidth: number
-  panelHeight: number
-  offset: number
-  viewportPadding: number
-}): PopoverPosition {
-  const placements = placementCandidates(options.placement)
-
-  for (const placement of placements) {
-    const point = popoverPoint(placement, options)
-    if (isPointInViewport(point, options)) {
-      return { placement, point }
-    }
-  }
-
-  return {
-    placement: options.placement,
-    point: popoverPoint(options.placement, options),
-  }
-}
-
-function placementCandidates(placement: PopoverPlacement): PopoverPlacement[] {
-  const all: PopoverPlacement[] = [
-    'bottom-end',
-    'bottom-start',
-    'bottom',
-    'top-end',
-    'top-start',
-    'top',
-    'right',
-    'left',
-  ]
-  const opposite: Record<PopoverPlacement, PopoverPlacement> = {
-    'top': 'bottom',
-    'top-start': 'bottom-start',
-    'top-end': 'bottom-end',
-    'right': 'left',
-    'bottom': 'top',
-    'bottom-start': 'top-start',
-    'bottom-end': 'top-end',
-    'left': 'right',
-  }
-
-  return [
-    placement,
-    opposite[placement],
-    ...all.filter(item => item !== placement && item !== opposite[placement]),
-  ]
-}
-
-function popoverPoint(
-  placement: PopoverPlacement,
-  options: {
-    triggerRect: DOMRect
-    panelWidth: number
-    panelHeight: number
-    offset: number
-  },
-): PopoverPoint {
-  const { triggerRect, panelWidth, panelHeight, offset } = options
-  const centerLeft = triggerRect.left + triggerRect.width / 2 - panelWidth / 2
-  const centerTop = triggerRect.top + triggerRect.height / 2 - panelHeight / 2
-
-  const points: Record<PopoverPlacement, PopoverPoint> = {
-    'top': { left: centerLeft, top: triggerRect.top - panelHeight - offset },
-    'top-start': { left: triggerRect.left, top: triggerRect.top - panelHeight - offset },
-    'top-end': {
-      left: triggerRect.right - panelWidth,
-      top: triggerRect.top - panelHeight - offset,
-    },
-    'right': { left: triggerRect.right + offset, top: centerTop },
-    'bottom': { left: centerLeft, top: triggerRect.bottom + offset },
-    'bottom-start': { left: triggerRect.left, top: triggerRect.bottom + offset },
-    'bottom-end': { left: triggerRect.right - panelWidth, top: triggerRect.bottom + offset },
-    'left': { left: triggerRect.left - panelWidth - offset, top: centerTop },
-  }
-
-  return points[placement]
-}
-
-function isPointInViewport(
-  point: PopoverPoint,
-  options: {
-    panelWidth: number
-    panelHeight: number
-    viewportPadding: number
-  },
-) {
-  const { panelWidth, panelHeight, viewportPadding } = options
-
-  return (
-    point.left >= viewportPadding
-    && point.top >= viewportPadding
-    && point.left + panelWidth <= window.innerWidth - viewportPadding
-    && point.top + panelHeight <= window.innerHeight - viewportPadding
-  )
-}
-
-function popoverArrowPosition(options: {
-  placement: PopoverPlacement
-  triggerRect: DOMRect
-  panelWidth: number
-  panelHeight: number
-  left: number
-  top: number
-}): CSSProperties {
-  const arrowSize = 8
-  const arrowHalf = arrowSize / 2
-  const arrowPadding = 12
-  const { placement, triggerRect, panelWidth, panelHeight, left, top } = options
-  const side = placement.split('-')[0]
-  const centerX = triggerRect.left + triggerRect.width / 2 - left
-  const centerY = triggerRect.top + triggerRect.height / 2 - top
-
-  if (side === 'top' || side === 'bottom') {
-    const arrowLeft = clamp(centerX - arrowHalf, arrowPadding, panelWidth - arrowPadding)
-
-    return {
-      left: `${arrowLeft}px`,
-      top: side === 'bottom' ? `${-arrowHalf}px` : `${panelHeight - arrowHalf}px`,
-    }
-  }
-
-  const arrowTop = clamp(centerY - arrowHalf, arrowPadding, panelHeight - arrowPadding)
-
-  return {
-    left: side === 'right' ? `${-arrowHalf}px` : `${panelWidth - arrowHalf}px`,
-    top: `${arrowTop}px`,
-  }
-}
-
-const updatePopoverPositionThrottled = useThrottleFn(updatePopoverPosition, 32, true)
-
-async function openPopover() {
-  if (props.disabled || open.value)
-    return
-
-  clearHoverOpenTimer()
-  clearHoverCloseTimer()
-  open.value = true
-  await nextTick()
-  updatePopoverPosition()
-}
-
-function closePopover() {
-  clearHoverCloseTimer()
-  open.value = false
-}
-
-function togglePopover() {
-  if (!supportsClickTrigger()) {
-    return
-  }
-
-  if (open.value) {
-    closePopover()
-    return
-  }
-
-  void openPopover()
-}
-
-function supportsClickTrigger() {
-  return props.trigger === 'click' || props.trigger === 'hover-click'
-}
-
-function supportsHoverTrigger() {
-  return props.trigger === 'hover' || props.trigger === 'hover-click'
-}
-
-function clearHoverCloseTimer() {
-  if (hoverCloseTimer.value === undefined) {
-    return
-  }
-
-  window.clearTimeout(hoverCloseTimer.value)
-  hoverCloseTimer.value = undefined
-}
-
-function clearHoverOpenTimer() {
-  if (hoverOpenTimer.value === undefined) {
-    return
-  }
-
-  window.clearTimeout(hoverOpenTimer.value)
-  hoverOpenTimer.value = undefined
-}
-
-function handleHoverEnter() {
-  if (!supportsHoverTrigger()) {
-    return
-  }
-
-  clearHoverCloseTimer()
-  // 延迟打开：鼠标稳定悬停一小段时间再展示，避免扫过表格时弹窗频繁闪烁。
-  if (hoverOpenTimer.value === undefined) {
-    hoverOpenTimer.value = window.setTimeout(() => {
-      hoverOpenTimer.value = undefined
-      void openPopover()
-    }, props.hoverDelay)
-  }
-}
-
-function handleHoverLeave() {
-  if (!supportsHoverTrigger()) {
-    return
-  }
-
-  clearHoverOpenTimer()
-  clearHoverCloseTimer()
-  hoverCloseTimer.value = window.setTimeout(closePopover, 90)
-}
-
-whenever(open, async () => {
-  await nextTick()
-  updatePopoverPosition()
-})
-watch(
-  () => props.anchorElement,
-  async () => {
-    if (!open.value)
-      return
-    await nextTick()
-    updatePopoverPosition()
-  },
-)
-
-onClickOutside(rootRef, closePopover, { ignore: [popoverRef] })
-useEventListener(rootRef, 'click', (event) => {
-  event.stopPropagation()
-  togglePopover()
-})
-useEventListener(rootRef, ['mouseenter', 'focusin'], handleHoverEnter)
-useEventListener(rootRef, ['mouseleave', 'focusout'], handleHoverLeave)
-useEventListener(popoverRef, ['mouseenter', 'focusin'], handleHoverEnter)
-useEventListener(popoverRef, ['mouseleave', 'focusout'], handleHoverLeave)
-useEventListener(viewportTarget, 'keydown', (event) => {
-  if (event instanceof KeyboardEvent && event.key === 'Escape') {
-    closePopover()
-  }
-})
-useEventListener(viewportTarget, 'resize', updatePopoverPositionThrottled)
-useEventListener(viewportTarget, 'scroll', updatePopoverPositionThrottled, { capture: true })
-onBeforeUnmount(() => {
-  clearHoverOpenTimer()
-  clearHoverCloseTimer()
-})
-</script>
-
-<template>
-  <div ref="rootRef" class="relative inline-flex overflow-visible" v-bind="attrs">
-    <slot name="trigger" :open="open" :close="closePopover" :toggle="togglePopover" />
-
-    <Teleport to="body">
-      <Transition
-        enter-active-class="transition-[opacity,transform] duration-150 ease-out motion-reduce:transition-none"
-        enter-from-class="-translate-y-1 opacity-0"
-        enter-to-class="translate-y-0 opacity-100"
-        leave-active-class="transition-opacity duration-150 ease-in motion-reduce:transition-none"
-        leave-from-class="opacity-100"
-        leave-to-class="opacity-0"
-      >
-        <div
-          v-if="open"
-          ref="popoverRef"
-          :class="popoverClasses"
-          :style="popoverStyle"
-        >
-          <span
-            class="pointer-events-none absolute size-2 rotate-45"
-            :class="[
-              popoverArrowSurfaceClass,
-              props.animatePosition
-                ? 'transition-[left,top] duration-150 ease-out motion-reduce:transition-none'
-                : undefined,
-            ]"
-            :style="popoverArrowStyle"
-          />
-          <slot :open="open" :close="closePopover" :toggle="togglePopover" />
-        </div>
-      </Transition>
-    </Teleport>
-  </div>
-</template>
diff --git a/frontend/src/components/base/BaseRadio.vue b/frontend/src/components/base/BaseRadio.vue
deleted file mode 100644
index d724ebe20..000000000
--- a/frontend/src/components/base/BaseRadio.vue
+++ /dev/null
@@ -1,63 +0,0 @@
-<script setup lang="ts">
-import { computed } from 'vue'
-
-const props = withDefaults(
-  defineProps<{
-    value: string
-    name: string
-    label: string
-    disabled?: boolean
-    showLabel?: boolean
-  }>(),
-  {
-    disabled: false,
-    showLabel: false,
-  },
-)
-
-defineSlots<{
-  default?: () => unknown
-}>()
-
-const model = defineModel<string>({ required: true })
-const checked = computed(() => model.value === props.value)
-const indicatorClasses = computed(() => [
-  'relative inline-grid size-4 shrink-0 place-items-center rounded-full transition-colors duration-150 motion-reduce:transition-none',
-  props.disabled
-    ? 'bg-cp-bg-container-disabled text-cp-text-disabled'
-    : checked.value
-      ? 'bg-cp-primary text-(--cp-button-primary-color)'
-      : 'bg-cp-fill-secondary text-transparent',
-])
-</script>
-
-<template>
-  <!-- The native radio is nested so the full label remains one accessible click target. -->
-  <!-- eslint-disable-next-line vue-a11y/label-has-for -->
-  <label
-    class="group relative inline-flex min-h-4 min-w-4 items-center gap-2.5"
-    :class="disabled ? 'cursor-not-allowed opacity-55' : 'cursor-pointer'"
-  >
-    <input
-      v-model="model"
-      type="radio"
-      class="peer sr-only"
-      :name="name"
-      :value="value"
-      :aria-label="label"
-      :disabled="disabled"
-    >
-    <span
-      :class="indicatorClasses"
-      class="peer-focus-visible:ring-2 peer-focus-visible:ring-cp-control-outline peer-focus-visible:ring-offset-2 peer-focus-visible:ring-offset-cp-bg-container"
-    >
-      <span class="size-1.5 rounded-full bg-current" />
-    </span>
-    <span v-if="$slots.default" class="min-w-0 flex-1">
-      <slot />
-    </span>
-    <span v-else-if="showLabel" class="text-cp leading-none font-emphasis">
-      {{ label }}
-    </span>
-  </label>
-</template>
diff --git a/frontend/src/components/base/BaseRange.vue b/frontend/src/components/base/BaseRange.vue
deleted file mode 100644
index 3c22da7a9..000000000
--- a/frontend/src/components/base/BaseRange.vue
+++ /dev/null
@@ -1,142 +0,0 @@
-<script setup lang="ts">
-import type { CSSProperties } from 'vue'
-import { computed } from 'vue'
-
-const props = withDefaults(
-  defineProps<{
-    label: string
-    min?: number
-    max?: number
-    step?: number
-    unit?: string
-    disabled?: boolean
-  }>(),
-  {
-    min: 0,
-    max: 100,
-    step: 1,
-    unit: undefined,
-    disabled: false,
-  },
-)
-
-const model = defineModel<number>({ required: true })
-
-const rangeStyle = computed<CSSProperties>(() => {
-  const span = props.max - props.min
-  const progress = span > 0 ? ((model.value - props.min) / span) * 100 : 0
-  return {
-    '--base-range-progress': `${Math.min(100, Math.max(0, progress))}%`,
-  }
-})
-
-const valueText = computed(() => `${model.value}${props.unit ?? ''}`)
-
-function updateModel(event: Event) {
-  const value = (event.target as HTMLInputElement).valueAsNumber
-  if (Number.isFinite(value))
-    model.value = value
-}
-</script>
-
-<template>
-  <input
-    :value="model"
-    type="range"
-    :min="min"
-    :max="max"
-    :step="step"
-    :disabled="disabled"
-    :aria-label="label"
-    :aria-valuetext="valueText"
-    class="base-range h-5 w-full"
-    :style="rangeStyle"
-    @input="updateModel"
-  >
-</template>
-
-<style scoped>
-.base-range {
-  appearance: none;
-  cursor: pointer;
-  background: transparent;
-  outline: none;
-}
-
-.base-range::-webkit-slider-runnable-track {
-  height: 4px;
-  border-radius: 999px;
-  background: linear-gradient(
-    to right,
-    var(--cp-color-primary) 0 var(--base-range-progress),
-    var(--cp-color-fill-secondary) var(--base-range-progress) 100%
-  );
-}
-
-.base-range::-webkit-slider-thumb {
-  width: 14px;
-  height: 14px;
-  margin-top: -5px;
-  appearance: none;
-  border: 2px solid var(--cp-color-bg-container);
-  border-radius: 999px;
-  background: var(--cp-color-primary);
-  transition:
-    box-shadow 150ms ease,
-    transform 150ms ease;
-}
-
-.base-range::-moz-range-track {
-  height: 4px;
-  border-radius: 999px;
-  background: var(--cp-color-fill-secondary);
-}
-
-.base-range::-moz-range-progress {
-  height: 4px;
-  border-radius: 999px;
-  background: var(--cp-color-primary);
-}
-
-.base-range::-moz-range-thumb {
-  width: 10px;
-  height: 10px;
-  border: 2px solid var(--cp-color-bg-container);
-  border-radius: 999px;
-  background: var(--cp-color-primary);
-  transition:
-    box-shadow 150ms ease,
-    transform 150ms ease;
-}
-
-.base-range:hover::-webkit-slider-thumb {
-  transform: scale(1.08);
-}
-
-.base-range:hover::-moz-range-thumb {
-  transform: scale(1.08);
-}
-
-.base-range:focus-visible::-webkit-slider-thumb {
-  box-shadow: 0 0 0 3px var(--cp-color-primary-container-hover);
-}
-
-.base-range:focus-visible::-moz-range-thumb {
-  box-shadow: 0 0 0 3px var(--cp-color-primary-container-hover);
-}
-
-.base-range:disabled {
-  cursor: not-allowed;
-  opacity: 0.5;
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .base-range::-webkit-slider-thumb {
-    transition: none;
-  }
-
-  .base-range::-moz-range-thumb {
-    transition: none;
-  }
-}
-</style>
diff --git a/frontend/src/components/base/BaseScrollbar.vue b/frontend/src/components/base/BaseScrollbar.vue
deleted file mode 100644
index 053e31342..000000000
--- a/frontend/src/components/base/BaseScrollbar.vue
+++ /dev/null
@@ -1,499 +0,0 @@
-<script setup lang="ts">
-import { useEventListener, useResizeObserver, useTimeoutFn } from '@vueuse/core'
-import { clamp } from 'es-toolkit'
-import { computed, nextTick, onBeforeUnmount, onMounted, shallowRef, useTemplateRef } from 'vue'
-
-const props = withDefaults(
-  defineProps<{
-    maxHeight?: string
-    height?: string
-    horizontal?: boolean
-    vertical?: boolean
-    alwaysVisible?: boolean
-  }>(),
-  {
-    maxHeight: undefined,
-    height: undefined,
-    horizontal: false,
-    vertical: true,
-    alwaysVisible: false,
-  },
-)
-
-const emit = defineEmits<{
-  scroll: [payload: { scrollTop: number, scrollLeft: number }]
-}>()
-
-const overflowTolerance = 1
-
-const rootRef = useTemplateRef<HTMLDivElement>('root')
-const wrapRef = useTemplateRef<HTMLDivElement>('wrap')
-const viewRef = useTemplateRef<HTMLElement>('view')
-const verticalTrackRef = useTemplateRef<HTMLDivElement>('verticalTrack')
-const horizontalTrackRef = useTemplateRef<HTMLDivElement>('horizontalTrack')
-const thumbHeight = shallowRef(0)
-const thumbTop = shallowRef(0)
-const horizontalThumbWidth = shallowRef(0)
-const horizontalThumbLeft = shallowRef(0)
-const visible = shallowRef(false)
-const verticalTrackHovering = shallowRef(false)
-const horizontalTrackHovering = shallowRef(false)
-const dragging = shallowRef(false)
-const horizontalDragging = shallowRef(false)
-const dragDocument = computed(() => (dragging.value || horizontalDragging.value ? document : null))
-
-interface AxisMetrics {
-  scrollRange: number
-  thumbRange: number
-}
-
-const verticalMetrics: AxisMetrics = { scrollRange: 0, thumbRange: 0 }
-const horizontalMetrics: AxisMetrics = { scrollRange: 0, thumbRange: 0 }
-
-let dragStartY = 0
-let dragStartScrollTop = 0
-let horizontalDragStartX = 0
-let horizontalDragStartScrollLeft = 0
-let scrollTopPosition = 0
-let scrollLeftPosition = 0
-let scrollFrameId: number | undefined
-const { start: startHideTimer, stop: stopHideTimer } = useTimeoutFn(hideScrollbar, 1600, {
-  immediate: false,
-})
-
-const canScrollY = computed(() => thumbHeight.value > 0)
-const canScrollX = computed(() => horizontalThumbWidth.value > 0)
-const verticalScrollbarVisible = computed(
-  () => props.alwaysVisible || dragging.value || verticalTrackHovering.value || visible.value,
-)
-const horizontalScrollbarVisible = computed(
-  () => props.alwaysVisible || horizontalDragging.value || horizontalTrackHovering.value || visible.value,
-)
-const thumbStyle = computed(() => ({
-  height: `${thumbHeight.value}px`,
-  transform: `translateY(${thumbTop.value}px)`,
-}))
-const horizontalThumbStyle = computed(() => ({
-  width: `${horizontalThumbWidth.value}px`,
-  transform: `translateX(${horizontalThumbLeft.value}px)`,
-}))
-const rootClasses = computed(() => [
-  'relative min-h-0 overflow-hidden',
-  props.maxHeight || props.height ? undefined : 'h-full',
-])
-const wrapClasses = computed(() => [
-  'min-h-0 max-h-[inherit] overflow-auto outline-none [scrollbar-width:none] [&::-webkit-scrollbar]:hidden [&::-webkit-scrollbar]:size-0',
-  props.maxHeight ? undefined : 'h-full',
-])
-const verticalTrackClass = computed(() => (props.horizontal && canScrollX.value ? 'bottom-1.5' : 'bottom-0'))
-const horizontalTrackClass = computed(() => (props.vertical && canScrollY.value ? 'right-1.5' : 'right-0'))
-
-function showScrollbar() {
-  visible.value = true
-}
-
-function clearHideTimer() {
-  stopHideTimer()
-}
-
-function scheduleHideScrollbar() {
-  clearHideTimer()
-  if (!dragging.value && !horizontalDragging.value && !verticalTrackHovering.value && !horizontalTrackHovering.value) {
-    startHideTimer()
-  }
-}
-
-function hideScrollbar() {
-  clearHideTimer()
-  visible.value = false
-}
-
-function activateScrollbar() {
-  showScrollbar()
-  scheduleHideScrollbar()
-}
-
-function handleRootMouseEnter() {
-  activateScrollbar()
-}
-
-function handleRootMouseLeave() {
-  hideScrollbar()
-}
-
-type ScrollbarAxis = 'vertical' | 'horizontal'
-
-function setTrackHovering(axis: ScrollbarAxis, hovering: boolean) {
-  if (axis === 'vertical') {
-    verticalTrackHovering.value = hovering
-    return
-  }
-
-  horizontalTrackHovering.value = hovering
-}
-
-function handleTrackMouseEnter(axis: ScrollbarAxis) {
-  setTrackHovering(axis, true)
-  showScrollbar()
-  clearHideTimer()
-}
-
-function handleTrackMouseLeave(axis: ScrollbarAxis) {
-  setTrackHovering(axis, false)
-  scheduleHideScrollbar()
-}
-
-function update() {
-  const wrap = wrapRef.value
-  if (!wrap) {
-    return
-  }
-
-  measureVerticalScrollbar(wrap)
-  measureHorizontalScrollbar(wrap)
-  syncScrollbarPosition(wrap, true)
-}
-
-function measureVerticalScrollbar(wrap: HTMLElement) {
-  if (!props.vertical) {
-    verticalMetrics.scrollRange = 0
-    verticalMetrics.thumbRange = 0
-    thumbHeight.value = 0
-    return
-  }
-
-  const clientHeight = wrap.clientHeight
-  const scrollHeight = wrap.scrollHeight
-  const scrollRange = clamp(scrollHeight - clientHeight, 0, Number.POSITIVE_INFINITY)
-  const availableTrackHeight = trackLength(verticalTrackRef.value, clientHeight, 'top', 'bottom')
-  if (scrollRange <= overflowTolerance || availableTrackHeight <= 0) {
-    wrap.scrollTop = 0
-    verticalMetrics.scrollRange = 0
-    verticalMetrics.thumbRange = 0
-    thumbHeight.value = 0
-    return
-  }
-
-  const ratio = clientHeight / scrollHeight
-  const nextThumbHeight = clamp(availableTrackHeight * ratio, 32, availableTrackHeight)
-  verticalMetrics.scrollRange = scrollRange
-  verticalMetrics.thumbRange = availableTrackHeight - nextThumbHeight
-  thumbHeight.value = nextThumbHeight
-}
-
-function measureHorizontalScrollbar(wrap: HTMLElement) {
-  if (!props.horizontal) {
-    horizontalMetrics.scrollRange = 0
-    horizontalMetrics.thumbRange = 0
-    horizontalThumbWidth.value = 0
-    return
-  }
-
-  const clientWidth = wrap.clientWidth
-  const scrollWidth = wrap.scrollWidth
-  const scrollRange = clamp(scrollWidth - clientWidth, 0, Number.POSITIVE_INFINITY)
-  const availableTrackWidth = trackLength(horizontalTrackRef.value, clientWidth, 'left', 'right')
-  if (scrollRange <= overflowTolerance || availableTrackWidth <= 0) {
-    wrap.scrollLeft = 0
-    horizontalMetrics.scrollRange = 0
-    horizontalMetrics.thumbRange = 0
-    horizontalThumbWidth.value = 0
-    return
-  }
-
-  const ratio = clientWidth / scrollWidth
-  const nextThumbWidth = clamp(availableTrackWidth * ratio, 32, availableTrackWidth)
-  horizontalMetrics.scrollRange = scrollRange
-  horizontalMetrics.thumbRange = availableTrackWidth - nextThumbWidth
-  horizontalThumbWidth.value = nextThumbWidth
-}
-
-function trackLength(
-  track: HTMLElement | null,
-  viewportLength: number,
-  startProperty: 'top' | 'left',
-  endProperty: 'bottom' | 'right',
-) {
-  if (!track)
-    return clamp(viewportLength - 8, 0, Number.POSITIVE_INFINITY)
-
-  const style = getComputedStyle(track)
-  const start = Number.parseFloat(style[startProperty])
-  const end = Number.parseFloat(style[endProperty])
-  const inset = (Number.isFinite(start) ? start : 4) + (Number.isFinite(end) ? end : 4)
-  const root = rootRef.value
-  const containerLength = root ? (startProperty === 'top' ? root.clientHeight : root.clientWidth) : viewportLength
-  return clamp(containerLength - inset, 0, Number.POSITIVE_INFINITY)
-}
-
-function updateVerticalThumbPosition(scrollTop: number) {
-  const { scrollRange, thumbRange } = verticalMetrics
-  thumbTop.value = scrollRange > 0 ? (clamp(scrollTop, 0, scrollRange) / scrollRange) * thumbRange : 0
-}
-
-function updateHorizontalThumbPosition(scrollLeft: number) {
-  const { scrollRange, thumbRange } = horizontalMetrics
-  horizontalThumbLeft.value = scrollRange > 0 ? (clamp(scrollLeft, 0, scrollRange) / scrollRange) * thumbRange : 0
-}
-
-function syncScrollbarPosition(wrap: HTMLElement, force = false) {
-  const scrollTop = wrap.scrollTop
-  const scrollLeft = wrap.scrollLeft
-
-  if (force || scrollTop !== scrollTopPosition) {
-    updateVerticalThumbPosition(scrollTop)
-  }
-  if (force || scrollLeft !== scrollLeftPosition) {
-    updateHorizontalThumbPosition(scrollLeft)
-  }
-
-  scrollTopPosition = scrollTop
-  scrollLeftPosition = scrollLeft
-}
-
-async function scrollToTop() {
-  const wrap = wrapRef.value
-  if (wrap) {
-    wrap.scrollTop = 0
-    wrap.scrollLeft = 0
-  }
-  dragging.value = false
-  horizontalDragging.value = false
-  visible.value = false
-  clearHideTimer()
-  await nextTick()
-  update()
-}
-
-async function scrollToBottom() {
-  const wrap = wrapRef.value
-  if (wrap) {
-    wrap.scrollTop = wrap.scrollHeight
-  }
-  await nextTick()
-  update()
-}
-
-function flushScrollFrame() {
-  scrollFrameId = undefined
-  const wrap = wrapRef.value
-  if (!wrap) {
-    return
-  }
-
-  syncScrollbarPosition(wrap)
-  activateScrollbar()
-  emit('scroll', {
-    scrollTop: wrap.scrollTop,
-    scrollLeft: wrap.scrollLeft,
-  })
-}
-
-function handleScroll() {
-  if (scrollFrameId !== undefined) {
-    return
-  }
-
-  scrollFrameId = requestAnimationFrame(flushScrollFrame)
-}
-
-function handleTrackPointerDown(event: PointerEvent) {
-  if (event.target !== event.currentTarget) {
-    return
-  }
-
-  const wrap = wrapRef.value
-  if (!wrap) {
-    return
-  }
-
-  update()
-  const rect = (event.currentTarget as HTMLElement).getBoundingClientRect()
-  activateScrollbar()
-  const nextThumbTop = event.clientY - rect.top - thumbHeight.value / 2
-  const { scrollRange, thumbRange } = verticalMetrics
-  wrap.scrollTop = thumbRange > 0 ? (clamp(nextThumbTop, 0, thumbRange) / thumbRange) * scrollRange : 0
-}
-
-function handleHorizontalTrackPointerDown(event: PointerEvent) {
-  if (event.target !== event.currentTarget) {
-    return
-  }
-
-  const wrap = wrapRef.value
-  if (!wrap) {
-    return
-  }
-
-  update()
-  const rect = (event.currentTarget as HTMLElement).getBoundingClientRect()
-  activateScrollbar()
-  const nextThumbLeft = event.clientX - rect.left - horizontalThumbWidth.value / 2
-  const { scrollRange, thumbRange } = horizontalMetrics
-  wrap.scrollLeft = thumbRange > 0 ? (clamp(nextThumbLeft, 0, thumbRange) / thumbRange) * scrollRange : 0
-}
-
-function handleThumbPointerDown(event: PointerEvent) {
-  const wrap = wrapRef.value
-  if (!wrap) {
-    return
-  }
-
-  event.preventDefault()
-  update()
-  dragging.value = true
-  visible.value = true
-  clearHideTimer()
-  dragStartY = event.clientY
-  dragStartScrollTop = wrap.scrollTop
-}
-
-function handleHorizontalThumbPointerDown(event: PointerEvent) {
-  const wrap = wrapRef.value
-  if (!wrap) {
-    return
-  }
-
-  event.preventDefault()
-  update()
-  horizontalDragging.value = true
-  visible.value = true
-  clearHideTimer()
-  horizontalDragStartX = event.clientX
-  horizontalDragStartScrollLeft = wrap.scrollLeft
-}
-
-function handleThumbPointerMove(event: PointerEvent) {
-  if (!dragging.value) {
-    return
-  }
-
-  const wrap = wrapRef.value
-  if (!wrap) {
-    return
-  }
-
-  const { scrollRange, thumbRange } = verticalMetrics
-  if (thumbRange <= 0) {
-    return
-  }
-
-  wrap.scrollTop = dragStartScrollTop + ((event.clientY - dragStartY) / thumbRange) * scrollRange
-}
-
-function handleHorizontalThumbPointerMove(event: PointerEvent) {
-  if (!horizontalDragging.value) {
-    return
-  }
-
-  const wrap = wrapRef.value
-  if (!wrap) {
-    return
-  }
-
-  const { scrollRange, thumbRange } = horizontalMetrics
-  if (thumbRange <= 0) {
-    return
-  }
-
-  wrap.scrollLeft = horizontalDragStartScrollLeft + ((event.clientX - horizontalDragStartX) / thumbRange) * scrollRange
-}
-
-function handleThumbPointerUp() {
-  if (!dragging.value) {
-    return
-  }
-
-  dragging.value = false
-  activateScrollbar()
-}
-
-function handleHorizontalThumbPointerUp() {
-  if (!horizontalDragging.value) {
-    return
-  }
-
-  horizontalDragging.value = false
-  activateScrollbar()
-}
-
-function handleDocumentPointerMove(event: PointerEvent) {
-  handleThumbPointerMove(event)
-  handleHorizontalThumbPointerMove(event)
-}
-
-function handleDocumentPointerUp() {
-  handleThumbPointerUp()
-  handleHorizontalThumbPointerUp()
-}
-
-onMounted(async () => {
-  await nextTick()
-  update()
-})
-
-onBeforeUnmount(() => {
-  if (scrollFrameId !== undefined) {
-    cancelAnimationFrame(scrollFrameId)
-  }
-})
-
-useResizeObserver([wrapRef, viewRef], update)
-useEventListener(wrapRef, 'scroll', handleScroll, { passive: true })
-useEventListener(dragDocument, 'pointermove', handleDocumentPointerMove)
-useEventListener(dragDocument, ['pointerup', 'pointercancel'], handleDocumentPointerUp)
-useEventListener(rootRef, 'mouseenter', handleRootMouseEnter)
-useEventListener(rootRef, 'mousemove', activateScrollbar, { passive: true })
-useEventListener(rootRef, 'mouseleave', handleRootMouseLeave)
-useEventListener(verticalTrackRef, 'mouseenter', () => handleTrackMouseEnter('vertical'))
-useEventListener(verticalTrackRef, 'mouseleave', () => handleTrackMouseLeave('vertical'))
-useEventListener(verticalTrackRef, 'pointerdown', handleTrackPointerDown)
-useEventListener(horizontalTrackRef, 'mouseenter', () => handleTrackMouseEnter('horizontal'))
-useEventListener(horizontalTrackRef, 'mouseleave', () => handleTrackMouseLeave('horizontal'))
-useEventListener(horizontalTrackRef, 'pointerdown', handleHorizontalTrackPointerDown)
-
-defineExpose({
-  update,
-  scrollToTop,
-  scrollToBottom,
-  wrapRef,
-})
-</script>
-
-<template>
-  <div ref="root" :class="rootClasses" :style="{ maxHeight, height }">
-    <div ref="wrap" :class="wrapClasses" tabindex="0">
-      <div ref="view">
-        <slot />
-      </div>
-    </div>
-
-    <div
-      v-show="canScrollY"
-      ref="verticalTrack"
-      class="absolute right-0 bottom-0 top-[var(--cp-scrollbar-track-inset-block-start,0.25rem)] z-40 flex w-3 justify-end transition-opacity duration-200"
-      :class="[verticalTrackClass, verticalScrollbarVisible ? 'opacity-100' : 'opacity-0']"
-    >
-      <div
-        class="w-1.5 rounded-full bg-(--cp-scrollbar-thumb-bg) transition-colors duration-200 hover:bg-(--cp-scrollbar-thumb-hover-bg)"
-        :class="dragging ? 'bg-(--cp-scrollbar-thumb-hover-bg)' : ''"
-        :style="thumbStyle"
-        @pointerdown="handleThumbPointerDown"
-      />
-    </div>
-
-    <div
-      v-show="canScrollX"
-      ref="horizontalTrack"
-      class="base-scrollbar-track-x absolute bottom-0 left-0 z-40 flex h-3 items-end transition-opacity duration-200"
-      :class="[horizontalTrackClass, horizontalScrollbarVisible ? 'opacity-100' : 'opacity-0']"
-    >
-      <div
-        class="h-1.5 rounded-full bg-(--cp-scrollbar-thumb-bg) transition-colors duration-200 hover:bg-(--cp-scrollbar-thumb-hover-bg)"
-        :class="horizontalDragging ? 'bg-(--cp-scrollbar-thumb-hover-bg)' : ''"
-        :style="horizontalThumbStyle"
-        @pointerdown="handleHorizontalThumbPointerDown"
-      />
-    </div>
-  </div>
-</template>
diff --git a/frontend/src/components/base/BaseSegmented.vue b/frontend/src/components/base/BaseSegmented.vue
deleted file mode 100644
index 0598f5e9c..000000000
--- a/frontend/src/components/base/BaseSegmented.vue
+++ /dev/null
@@ -1,132 +0,0 @@
-<script setup lang="ts">
-import type { Component } from 'vue'
-
-import { clamp } from 'es-toolkit'
-import { computed, nextTick } from 'vue'
-
-type SegmentedSize = 'sm' | 'md' | 'lg'
-
-export interface SegmentedOption {
-  label: string
-  value: string
-  icon?: Component
-  disabled?: boolean
-}
-
-const props = withDefaults(
-  defineProps<{
-    label: string
-    options: SegmentedOption[]
-    disabled?: boolean
-    display?: 'label' | 'icon'
-    size?: SegmentedSize
-  }>(),
-  {
-    disabled: false,
-    display: 'label',
-    size: 'md',
-  },
-)
-
-const model = defineModel<string>({ required: true })
-
-const activeIndex = computed(() => props.options.findIndex(option => option.value === model.value))
-const optionCount = computed(() => clamp(props.options.length, 1, Number.POSITIVE_INFINITY))
-const gridStyle = computed(() => ({
-  gridTemplateColumns: `repeat(${optionCount.value}, minmax(0, 1fr))`,
-}))
-const indicatorStyle = computed(() => ({
-  width: `calc((100% - 6px) / ${optionCount.value})`,
-  transform: `translateX(${activeIndex.value * 100}%)`,
-}))
-
-const rootClasses: Record<SegmentedSize, string> = {
-  sm: 'h-cp-control-sm',
-  md: 'h-cp-control',
-  lg: 'h-cp-control-lg',
-}
-const optionClasses: Record<SegmentedSize, string> = {
-  sm: 'h-6.5 px-2 text-cp-xs',
-  md: 'h-8 px-3 text-xs',
-  lg: 'h-9.5 px-4 text-cp',
-}
-
-function enabledIndexes() {
-  return props.options.flatMap((option, index) => (option.disabled ? [] : [index]))
-}
-
-function selectOption(index: number) {
-  const option = props.options[index]
-  if (props.disabled || !option || option.disabled || option.value === model.value)
-    return
-  model.value = option.value
-}
-
-async function handleKeydown(event: KeyboardEvent, index: number) {
-  const indexes = enabledIndexes()
-  if (indexes.length === 0)
-    return
-
-  const current = indexes.indexOf(index)
-  let nextIndex: number | undefined
-
-  if (event.key === 'ArrowRight' || event.key === 'ArrowDown')
-    nextIndex = indexes[(current + 1 + indexes.length) % indexes.length]
-  else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp')
-    nextIndex = indexes[(current - 1 + indexes.length) % indexes.length]
-  else if (event.key === 'Home')
-    nextIndex = indexes[0]
-  else if (event.key === 'End')
-    nextIndex = indexes[indexes.length - 1]
-  else return
-
-  if (nextIndex === undefined)
-    return
-
-  event.preventDefault()
-  selectOption(nextIndex)
-  await nextTick()
-  const buttons = (event.currentTarget as HTMLElement).parentElement?.querySelectorAll<HTMLButtonElement>('button')
-  buttons?.[nextIndex]?.focus()
-}
-</script>
-
-<template>
-  <div
-    class="relative inline-grid items-center rounded-cp bg-[var(--cp-input-bg)] p-0.75"
-    :class="rootClasses[size]"
-    :style="gridStyle"
-    role="radiogroup"
-    :aria-label="label"
-    :aria-disabled="disabled || undefined"
-  >
-    <span
-      v-if="activeIndex >= 0"
-      class="pointer-events-none absolute inset-y-0.75 left-0.75 rounded-cp bg-cp-bg-container shadow-cp-tertiary transition-transform duration-200 ease-out motion-reduce:transition-none"
-      :style="indicatorStyle"
-    />
-    <button
-      v-for="(option, index) in options"
-      :key="option.value"
-      class="relative z-10 inline-flex min-w-0 touch-manipulation items-center justify-center gap-1.5 rounded-cp border-0 bg-transparent leading-none font-emphasis outline-none transition-colors duration-150 focus-visible:ring-2 focus-visible:ring-cp-control-outline motion-reduce:transition-none"
-      :class="[
-        optionClasses[size],
-        model === option.value ? 'text-cp-text' : 'text-cp-text-secondary hover:text-cp-text',
-        disabled || option.disabled ? 'cursor-not-allowed opacity-60 hover:text-cp-text-secondary' : undefined,
-        display === 'icon' ? 'px-0' : undefined,
-      ]"
-      type="button"
-      role="radio"
-      :aria-checked="model === option.value"
-      :aria-label="display === 'icon' ? option.label : undefined"
-      :title="display === 'icon' ? option.label : undefined"
-      :tabindex="model === option.value || (activeIndex < 0 && index === 0) ? 0 : -1"
-      :disabled="disabled || option.disabled"
-      @click="selectOption(index)"
-      @keydown="handleKeydown($event, index)"
-    >
-      <component :is="option.icon" v-if="option.icon" class="size-3.5 shrink-0" />
-      <span v-if="display === 'label'" class="truncate">{{ option.label }}</span>
-    </button>
-  </div>
-</template>
diff --git a/frontend/src/components/base/BaseSelect.vue b/frontend/src/components/base/BaseSelect.vue
deleted file mode 100644
index cd743f481..000000000
--- a/frontend/src/components/base/BaseSelect.vue
+++ /dev/null
@@ -1,420 +0,0 @@
-<script setup lang="ts">
-import type { CSSProperties } from 'vue'
-
-import { Check, ChevronDown } from '@lucide/vue'
-import { onClickOutside, useEventListener, useThrottleFn } from '@vueuse/core'
-import { clamp } from 'es-toolkit'
-import { computed, inject, nextTick, ref, useAttrs, useId, watch } from 'vue'
-import { formFieldKey } from './BaseForm/context'
-import BaseScrollbar from './BaseScrollbar.vue'
-
-type SelectSize = 'sm' | 'md' | 'lg'
-
-export interface SelectOption {
-  label: string
-  value: string
-  description?: string
-  disabled?: boolean
-}
-
-defineOptions({
-  inheritAttrs: false,
-})
-
-const props = withDefaults(
-  defineProps<{
-    options: SelectOption[]
-    size?: SelectSize
-    disabled?: boolean
-    placeholder?: string
-    emptyText?: string
-  }>(),
-  {
-    size: 'md',
-    disabled: false,
-    placeholder: '请选择',
-    emptyText: '暂无选项',
-  },
-)
-
-const model = defineModel<string>({ required: true })
-const attrs = useAttrs()
-const field = inject(formFieldKey, null)
-
-const rootRef = ref<HTMLElement | null>(null)
-const triggerRef = ref<HTMLButtonElement | null>(null)
-const popoverRef = ref<HTMLElement | null>(null)
-const listboxRef = ref<HTMLElement | null>(null)
-const scrollbarRef = ref<InstanceType<typeof BaseScrollbar> | null>(null)
-const open = ref(false)
-const activeIndex = ref(-1)
-const popoverStyle = ref<CSSProperties>({})
-const popoverMaxHeight = ref('244px')
-const selectId = `base-select-${useId()}`
-const controlId = computed(() => (typeof attrs.id === 'string' ? attrs.id : (field?.controlId.value ?? selectId)))
-const invalid = computed(() =>
-  Boolean(field?.invalid.value || attrs['aria-invalid'] === true || attrs['aria-invalid'] === 'true'),
-)
-const describedBy = computed(
-  () =>
-    [typeof attrs['aria-describedby'] === 'string' ? attrs['aria-describedby'] : undefined, field?.describedBy.value]
-      .filter(Boolean)
-      .join(' ') || undefined,
-)
-const rootAttrs = computed(() => ({ class: attrs.class, style: attrs.style }))
-const triggerAttrs = computed(() =>
-  Object.fromEntries(
-    Object.entries(attrs).filter(
-      ([key]) => !['class', 'style', 'id', 'aria-describedby', 'aria-invalid', 'aria-required'].includes(key),
-    ),
-  ),
-)
-
-const sizeConfig: Record<
-  SelectSize,
-  {
-    trigger: string
-    option: string
-    icon: number
-  }
-> = {
-  md: {
-    trigger: 'h-cp-control px-3.5 pr-9 text-cp rounded-cp',
-    option: 'h-8.5 px-3 text-cp',
-    icon: 16,
-  },
-  sm: {
-    trigger: 'h-cp-control-sm px-2.5 pr-7 text-xs rounded-cp',
-    option: 'h-8 px-2.5 text-xs',
-    icon: 14,
-  },
-  lg: {
-    trigger: 'h-cp-control-lg px-4 pr-10 text-cp-lg rounded-cp',
-    option: 'h-10 px-3.5 text-cp-lg',
-    icon: 17,
-  },
-}
-
-const selectedOption = computed(() => props.options.find(option => option.value === model.value))
-
-const triggerClasses = computed(() => [
-  'relative inline-flex w-full min-w-0 items-center gap-2 overflow-visible border-0 text-left font-emphasis leading-none shadow-cp-input outline-none transition-[background-color,box-shadow,color] duration-[160ms]',
-  sizeConfig[props.size].trigger,
-  props.disabled
-    ? 'cursor-not-allowed bg-cp-bg-container-disabled text-cp-text-disabled shadow-none'
-    : invalid.value
-      ? 'cursor-pointer bg-(--cp-input-error-active-bg) text-cp-error-on-container shadow-cp-input-error-active'
-      : open.value
-        ? 'cursor-pointer bg-(--cp-input-active-bg) text-cp-text shadow-cp-input-active'
-        : [
-            'cursor-pointer bg-[var(--cp-input-bg)] text-cp-text',
-            'hover:not-focus-visible:bg-[var(--cp-input-hover-bg)] hover:not-focus-visible:shadow-cp-input-hover',
-            'focus-visible:bg-(--cp-input-active-bg) focus-visible:shadow-cp-input-active',
-          ],
-])
-
-function optionId(index: number) {
-  return `${selectId}-option-${index}`
-}
-
-function enabledIndexes() {
-  return props.options.flatMap((option, index) => (option.disabled ? [] : [index]))
-}
-
-function selectedIndex() {
-  return props.options.findIndex(option => option.value === model.value)
-}
-
-function setActiveToSelected() {
-  const selected = selectedIndex()
-  if (selected >= 0 && !props.options[selected]?.disabled) {
-    activeIndex.value = selected
-    return
-  }
-
-  activeIndex.value = enabledIndexes()[0] ?? -1
-}
-
-function updatePopoverPosition() {
-  if (!open.value || !triggerRef.value || !listboxRef.value)
-    return
-
-  const rect = triggerRef.value.getBoundingClientRect()
-  const gap = 6
-  const menuHeight = Math.min(listboxRef.value.scrollHeight, 244)
-  const belowSpace = window.innerHeight - rect.bottom - gap - 8
-  const aboveSpace = rect.top - gap - 8
-  const placeAbove = belowSpace < menuHeight && aboveSpace > belowSpace
-  const availableHeight = Math.max(placeAbove ? aboveSpace : belowSpace, 0)
-  const maxHeight = Math.min(menuHeight, availableHeight)
-  const top = placeAbove
-    ? Math.max(8, rect.top - maxHeight - gap)
-    : Math.min(rect.bottom + gap, window.innerHeight - maxHeight - 8)
-  const left = clamp(rect.left, 8, window.innerWidth - rect.width - 8)
-
-  popoverMaxHeight.value = `${maxHeight}px`
-  popoverStyle.value = {
-    left: `${left}px`,
-    top: `${top}px`,
-    width: `${rect.width}px`,
-  }
-}
-
-const updatePopoverPositionThrottled = useThrottleFn(updatePopoverPosition, 32, true)
-
-function scrollActiveIntoView() {
-  const wrap = scrollbarRef.value?.wrapRef
-  const option = listboxRef.value?.children[activeIndex.value]
-  if (!open.value || !wrap || !option)
-    return
-
-  // 只滚动菜单自身，避免键盘定位选项时带动弹窗或页面滚动。
-  const wrapRect = wrap.getBoundingClientRect()
-  const optionRect = option.getBoundingClientRect()
-  if (optionRect.top < wrapRect.top)
-    wrap.scrollTop -= wrapRect.top - optionRect.top
-  else if (optionRect.bottom > wrapRect.bottom)
-    wrap.scrollTop += optionRect.bottom - wrapRect.bottom
-}
-
-async function openMenu() {
-  if (props.disabled || open.value)
-    return
-
-  open.value = true
-  setActiveToSelected()
-  await nextTick()
-  updatePopoverPosition()
-  await nextTick()
-  scrollActiveIntoView()
-}
-
-function closeMenu() {
-  open.value = false
-}
-
-function toggleMenu() {
-  if (open.value) {
-    closeMenu()
-    return
-  }
-
-  void openMenu()
-}
-
-function moveActive(delta: number) {
-  const indexes = enabledIndexes()
-  if (indexes.length === 0)
-    return
-
-  const current = indexes.indexOf(activeIndex.value)
-  const next = current === -1 ? (delta > 0 ? 0 : indexes.length - 1) : current + delta
-  activeIndex.value = indexes[(next + indexes.length) % indexes.length]
-  // 只有键盘导航主动定位；鼠标悬停不能把半露出的选项滚入视口。
-  scrollActiveIntoView()
-}
-
-function handleOptionFocus(index: number) {
-  const option = props.options[index]
-  if (!option || option.disabled)
-    return
-
-  activeIndex.value = index
-  scrollActiveIntoView()
-}
-
-function chooseOption(option: SelectOption, index: number) {
-  if (option.disabled)
-    return
-
-  model.value = option.value
-  activeIndex.value = index
-  closeMenu()
-}
-
-function chooseActive() {
-  const option = props.options[activeIndex.value]
-  if (!option)
-    return
-
-  chooseOption(option, activeIndex.value)
-}
-
-function handleTriggerKeydown(event: KeyboardEvent) {
-  if (props.disabled)
-    return
-
-  if (event.key === 'ArrowDown') {
-    event.preventDefault()
-    if (!open.value) {
-      void openMenu()
-      return
-    }
-    moveActive(1)
-    return
-  }
-
-  if (event.key === 'ArrowUp') {
-    event.preventDefault()
-    if (!open.value) {
-      void openMenu()
-      return
-    }
-    moveActive(-1)
-    return
-  }
-
-  if (event.key === 'Enter' || event.key === ' ') {
-    event.preventDefault()
-    if (!open.value) {
-      void openMenu()
-      return
-    }
-    chooseActive()
-    return
-  }
-
-  if (event.key === 'Escape') {
-    closeMenu()
-  }
-}
-
-function optionClasses(option: SelectOption, index: number) {
-  return [
-    'flex w-full shrink-0 touch-manipulation items-center gap-2 rounded-cp-sm border-0 px-3 text-left font-emphasis leading-none outline-none transition-colors motion-reduce:transition-none',
-    sizeConfig[props.size].option,
-    option.disabled
-      ? 'cursor-not-allowed bg-transparent text-cp-text-disabled'
-      : option.value === model.value
-        ? 'cursor-pointer bg-cp-control-item-bg-active text-cp-primary-text'
-        : activeIndex.value === index
-          ? 'cursor-pointer bg-cp-bg-text-hover text-cp-text'
-          : 'cursor-pointer bg-transparent text-cp-text hover:bg-cp-bg-text-hover',
-  ]
-}
-
-watch(
-  () => [props.options, props.size, model.value],
-  async () => {
-    if (!open.value)
-      return
-    setActiveToSelected()
-    await nextTick()
-    updatePopoverPosition()
-    await nextTick()
-    scrollActiveIntoView()
-  },
-)
-
-onClickOutside(rootRef, closeMenu, { ignore: [popoverRef] })
-useEventListener(window, 'resize', updatePopoverPositionThrottled)
-useEventListener(window, 'scroll', updatePopoverPositionThrottled, { capture: true })
-</script>
-
-<template>
-  <div ref="rootRef" class="relative inline-block text-left" v-bind="rootAttrs">
-    <button
-      v-bind="triggerAttrs"
-      :id="controlId"
-      ref="triggerRef"
-      type="button"
-      :class="triggerClasses"
-      :disabled="disabled"
-      role="combobox"
-      :aria-expanded="open"
-      :aria-controls="`${selectId}-listbox`"
-      :aria-activedescendant="open && activeIndex >= 0 ? optionId(activeIndex) : undefined"
-      :aria-describedby="describedBy"
-      :aria-invalid="invalid || undefined"
-      :aria-required="field?.required.value || undefined"
-      @click="toggleMenu"
-      @keydown="handleTriggerKeydown"
-    >
-      <span class="min-w-0 truncate" :class="selectedOption?.description ? 'max-w-1/2 shrink-0' : 'flex-1'">
-        {{ selectedOption?.label ?? placeholder }}
-      </span>
-      <span
-        v-if="selectedOption?.description"
-        :title="selectedOption.description"
-        class="min-w-0 flex-1 truncate font-normal"
-        :class="disabled ? 'text-cp-text-disabled' : 'text-cp-text-tertiary'"
-      >
-        {{ selectedOption.description }}
-      </span>
-      <ChevronDown
-        class="pointer-events-none absolute top-1/2 right-3 -translate-y-1/2 transition-transform"
-        :class="
-          disabled ? 'text-cp-text-disabled' : open ? 'rotate-180 text-cp-primary-text' : 'text-cp-text-quaternary'
-        "
-        :size="sizeConfig[size].icon"
-      />
-    </button>
-
-    <Teleport to="body">
-      <Transition
-        enter-active-class="transition-[opacity,transform] duration-150 ease-out motion-reduce:transition-none"
-        enter-from-class="-translate-y-1 opacity-0"
-        enter-to-class="translate-y-0 opacity-100"
-        leave-active-class="transition-opacity duration-150 ease-in motion-reduce:transition-none"
-        leave-from-class="opacity-100"
-        leave-to-class="opacity-0"
-      >
-        <div
-          v-if="open"
-          ref="popoverRef"
-          class="fixed z-50 rounded-cp-lg border-0 bg-cp-bg-elevated shadow-cp"
-          :style="popoverStyle"
-        >
-          <BaseScrollbar ref="scrollbarRef" :max-height="popoverMaxHeight" class="rounded-cp-lg">
-            <div
-              :id="`${selectId}-listbox`"
-              ref="listboxRef"
-              class="flex flex-col gap-1 p-1"
-              role="listbox"
-              :aria-labelledby="controlId"
-            >
-              <div
-                v-if="options.length === 0"
-                class="flex h-8.5 shrink-0 items-center rounded-cp-sm px-3 text-cp leading-none font-emphasis text-cp-text-quaternary"
-              >
-                {{ emptyText }}
-              </div>
-
-              <template v-else>
-                <button
-                  v-for="(option, index) in options"
-                  :id="optionId(index)"
-                  :key="option.value"
-                  type="button"
-                  role="option"
-                  :aria-selected="option.value === model"
-                  :disabled="option.disabled"
-                  :class="optionClasses(option, index)"
-                  @mouseenter="activeIndex = option.disabled ? activeIndex : index"
-                  @focus="handleOptionFocus(index)"
-                  @mousedown.prevent
-                  @click="chooseOption(option, index)"
-                >
-                  <span class="min-w-0 truncate" :class="option.description ? 'max-w-1/2 shrink-0' : 'flex-1'">{{ option.label }}</span>
-                  <span
-                    v-if="option.description"
-                    :title="option.description"
-                    class="min-w-0 flex-1 truncate font-normal"
-                    :class="option.disabled ? 'text-cp-text-disabled' : 'text-cp-text-tertiary'"
-                  >
-                    {{ option.description }}
-                  </span>
-                  <Check
-                    v-if="option.value === model"
-                    class="shrink-0 text-cp-primary-text"
-                    :size="size === 'sm' ? 13 : size === 'lg' ? 17 : 15"
-                  />
-                </button>
-              </template>
-            </div>
-          </BaseScrollbar>
-        </div>
-      </Transition>
-    </Teleport>
-  </div>
-</template>
diff --git a/frontend/src/components/base/BaseSkeleton.vue b/frontend/src/components/base/BaseSkeleton.vue
deleted file mode 100644
index 583173ec4..000000000
--- a/frontend/src/components/base/BaseSkeleton.vue
+++ /dev/null
@@ -1,34 +0,0 @@
-<script setup lang="ts">
-import { computed } from 'vue'
-
-type SkeletonShape = 'text' | 'block' | 'circle'
-
-const props = withDefaults(
-  defineProps<{
-    as?: keyof HTMLElementTagNameMap
-    shape?: SkeletonShape
-    animated?: boolean
-  }>(),
-  {
-    as: 'span',
-    shape: 'block',
-    animated: true,
-  },
-)
-
-const shapeClasses: Record<SkeletonShape, string> = {
-  text: 'h-3 rounded-full',
-  block: 'rounded-cp',
-  circle: 'rounded-full',
-}
-
-const classes = computed(() => [
-  'block bg-cp-fill-secondary',
-  shapeClasses[props.shape],
-  props.animated ? 'motion-safe:animate-cp-skeleton motion-reduce:animate-none' : undefined,
-])
-</script>
-
-<template>
-  <component :is="as" :class="classes" />
-</template>
diff --git a/frontend/src/components/base/BaseSwitch.vue b/frontend/src/components/base/BaseSwitch.vue
deleted file mode 100644
index 73b4a3380..000000000
--- a/frontend/src/components/base/BaseSwitch.vue
+++ /dev/null
@@ -1,95 +0,0 @@
-<script setup lang="ts">
-import { computed } from 'vue'
-
-const props = withDefaults(
-  defineProps<{
-    label: string
-    disabled?: boolean
-    showLabel?: boolean
-    activeText?: string
-    inactiveText?: string
-    inlinePrompt?: boolean
-    width?: string | number
-  }>(),
-  {
-    disabled: false,
-    showLabel: false,
-    activeText: '',
-    inactiveText: '',
-    inlinePrompt: false,
-    width: '',
-  },
-)
-
-const model = defineModel<boolean>({ default: false })
-const hasStateText = computed(() => Boolean(props.activeText || props.inactiveText))
-const inlineText = computed(() => model.value ? props.activeText : props.inactiveText)
-const trackStyle = computed(() => props.width === ''
-  ? undefined
-  : {
-      width: typeof props.width === 'number' || /^\d+(?:\.\d+)?$/.test(props.width)
-        ? `${props.width}px`
-        : props.width,
-    })
-
-const trackClasses = computed(() => [
-  'relative inline-flex h-6 min-w-11 shrink-0 items-center rounded-full p-0.5 transition-[background-color,box-shadow] duration-180 motion-reduce:transition-none',
-  props.disabled
-    ? 'bg-cp-bg-container-disabled shadow-none'
-    : model.value
-      ? 'bg-cp-primary shadow-cp-tertiary'
-      : 'bg-cp-fill-tertiary shadow-cp-tertiary',
-])
-const thumbClasses = computed(() => [
-  'absolute top-0.5 z-10 size-5 rounded-full bg-cp-white shadow-cp-tertiary transition-[left] duration-180 ease-out motion-reduce:transition-none',
-  model.value ? 'left-[calc(100%-1.375rem)]' : 'left-0.5',
-])
-const inlineTextClasses = computed(() => [
-  'pointer-events-none absolute inset-0 flex min-w-0 select-none items-center justify-center overflow-hidden text-[10px] leading-none font-heavy transition-[padding,color] duration-180 motion-reduce:transition-none',
-  model.value ? 'text-cp-white' : 'text-cp-text-secondary',
-  model.value ? 'pr-6 pl-1' : 'pr-1 pl-6',
-])
-const inactiveTextClasses = computed(() => [
-  'text-cp leading-none font-emphasis transition-colors duration-150 motion-reduce:transition-none',
-  model.value ? 'text-cp-text-secondary' : 'text-cp-primary-text',
-])
-const activeTextClasses = computed(() => [
-  'text-cp leading-none font-emphasis transition-colors duration-150 motion-reduce:transition-none',
-  model.value ? 'text-cp-primary-text' : 'text-cp-text-secondary',
-])
-</script>
-
-<template>
-  <!-- The native checkbox is nested; the rule does not resolve this Vue template pattern. -->
-  <!-- eslint-disable-next-line vue-a11y/label-has-for -->
-  <label
-    class="relative inline-flex items-center gap-2.5"
-    :class="disabled ? 'cursor-not-allowed opacity-70' : 'cursor-pointer'"
-  >
-    <span v-if="inactiveText && !inlinePrompt" :class="inactiveTextClasses">
-      {{ inactiveText }}
-    </span>
-    <input
-      v-model="model"
-      type="checkbox"
-      role="switch"
-      class="peer sr-only"
-      :aria-label="label"
-      :disabled="disabled"
-    >
-    <span
-      :class="trackClasses"
-      :style="trackStyle"
-      class="peer-focus-visible:ring-2 peer-focus-visible:ring-cp-control-outline peer-focus-visible:ring-offset-2 peer-focus-visible:ring-offset-cp-bg-container"
-    >
-      <span v-if="inlinePrompt && inlineText" :class="inlineTextClasses">
-        <span class="min-w-0 truncate">{{ inlineText }}</span>
-      </span>
-      <span :class="thumbClasses" />
-    </span>
-    <span v-if="activeText && !inlinePrompt" :class="activeTextClasses">{{ activeText }}</span>
-    <span v-else-if="showLabel && !hasStateText" class="text-cp font-emphasis text-cp-text">
-      {{ label }}
-    </span>
-  </label>
-</template>
diff --git a/frontend/src/components/base/BaseTable/BaseTableColumnSettings.vue b/frontend/src/components/base/BaseTable/BaseTableColumnSettings.vue
deleted file mode 100644
index 6f80c54ad..000000000
--- a/frontend/src/components/base/BaseTable/BaseTableColumnSettings.vue
+++ /dev/null
@@ -1,241 +0,0 @@
-<script setup lang="ts">
-import type { TableColumnOption } from './useTableColumns'
-import { Columns3, GripVertical } from '@lucide/vue'
-import { usePreferredReducedMotion } from '@vueuse/core'
-import { moveArrayElement, useSortable } from '@vueuse/integrations/useSortable'
-import { computed, nextTick, shallowRef, useId, useTemplateRef, watch } from 'vue'
-import BaseButton from '../BaseButton.vue'
-import BaseCheckbox from '../BaseCheckbox.vue'
-import BaseIconButton from '../BaseIconButton.vue'
-import BasePopover from '../BasePopover.vue'
-import BaseScrollbar from '../BaseScrollbar.vue'
-
-const props = defineProps<{
-  options: TableColumnOption[]
-}>()
-
-const emit = defineEmits<{
-  change: [key: string, visible: boolean]
-  reorder: [keys: string[]]
-  reset: []
-}>()
-
-const open = shallowRef(false)
-const panelId = useId()
-const triggerRef = useTemplateRef<InstanceType<typeof BaseIconButton>>('trigger')
-const panelRef = useTemplateRef<HTMLDivElement>('panel')
-const listRef = useTemplateRef<HTMLDivElement>('list')
-const visibleCount = computed(() => props.options.filter(option => option.visible).length)
-const dragging = shallowRef(false)
-const hoveredColumnKey = shallowRef<string>()
-const announcement = shallowRef('')
-const preferredMotion = usePreferredReducedMotion()
-const reorderAnimation = computed(() => preferredMotion.value === 'reduce' ? 0 : 200)
-const sortableOptions = computed({
-  get: () => props.options,
-  set: options => emit('reorder', options.map(option => option.key)),
-})
-
-const { option: setSortableOption } = useSortable(listRef, sortableOptions, {
-  watchElement: true,
-  animation: reorderAnimation.value,
-  easing: 'cubic-bezier(0.2, 0, 0, 1)',
-  handle: '[data-column-handle]',
-  draggable: '[data-reorderable="true"]',
-  ghostClass: 'opacity-40',
-  onMove: event => event.related.dataset.reorderable !== 'false',
-  onChoose: (event) => {
-    dragging.value = true
-    hoveredColumnKey.value = event.item.dataset.columnKey
-  },
-  onUnchoose: () => { dragging.value = false },
-  onEnd: (event) => {
-    const key = event.item.dataset.columnKey
-    hoveredColumnKey.value = key
-    if (key && event.oldIndex !== event.newIndex) {
-      // useSortable 在下一次更新中同步数组，再等待父组件应用列顺序后恢复焦点。
-      void nextTick(() => focusMovedColumn(key))
-    }
-  },
-})
-
-function updateHoveredColumn(event: PointerEvent) {
-  if (dragging.value || !(event.target instanceof Element))
-    return
-
-  const item = event.target.closest<HTMLElement>('[role="listitem"][data-column-key]')
-  const option = props.options.find(option => option.key === item?.dataset.columnKey)
-  // 原生拖拽结束后 :hover 可能仍停在旧位置，只在真实指针移动时更新高亮。
-  hoveredColumnKey.value = option && (!option.disabled || option.reorderable) ? option.key : undefined
-}
-
-function clearHoveredColumn() {
-  if (!dragging.value)
-    hoveredColumnKey.value = undefined
-}
-
-watch([listRef, reorderAnimation], () => {
-  setSortableOption('animation', reorderAnimation.value)
-}, { flush: 'post' })
-
-async function focusMovedColumn(key: string) {
-  await nextTick()
-  if (!open.value)
-    return
-
-  const handles = panelRef.value?.querySelectorAll<HTMLButtonElement>('[data-column-handle]')
-  const handle = Array.from(handles ?? []).find(handle => handle.dataset.columnKey === key)
-  handle?.focus({ preventScroll: true })
-  handle?.scrollIntoView({ block: 'nearest' })
-  const index = props.options.findIndex(option => option.key === key)
-  const option = props.options[index]
-  if (option)
-    announcement.value = `${option.label}已移到第 ${index + 1} 项`
-}
-
-function moveWithKeyboard(key: string, direction: -1 | 1) {
-  const options = props.options.filter(option => option.reorderable)
-  const index = options.findIndex(option => option.key === key)
-  const target = options[index + direction]
-  if (index < 0 || !target)
-    return
-
-  moveArrayElement(sortableOptions, props.options.indexOf(options[index]!), props.options.indexOf(target))
-  void nextTick(() => focusMovedColumn(key))
-}
-
-function closeAndFocus() {
-  open.value = false
-  triggerRef.value?.$el.focus()
-}
-
-function handleTab(event: KeyboardEvent) {
-  const controls = panelRef.value?.querySelectorAll<HTMLElement>('input:not(:disabled), button:not(:disabled)')
-  if (!controls?.length)
-    return
-
-  const edge = event.shiftKey ? controls[0] : controls[controls.length - 1]
-  if (document.activeElement !== edge)
-    return
-
-  // 浮层挂在 body 下；边界处回到触发按钮，继续工具栏原有的 Tab 顺序。
-  if (event.shiftKey)
-    event.preventDefault()
-  closeAndFocus()
-}
-
-function handleFocusOut(event: FocusEvent) {
-  if (!dragging.value && event.relatedTarget instanceof Node
-    && !panelRef.value?.contains(event.relatedTarget)
-    && !triggerRef.value?.$el.contains(event.relatedTarget)) {
-    open.value = false
-  }
-}
-
-watch(open, async (value) => {
-  if (!value) {
-    dragging.value = false
-    hoveredColumnKey.value = undefined
-    announcement.value = ''
-    return
-  }
-  await nextTick()
-  panelRef.value?.querySelector<HTMLElement>('input:not(:disabled), button:not(:disabled)')?.focus({ preventScroll: true })
-})
-</script>
-
-<template>
-  <BasePopover
-    v-model="open"
-    placement="bottom-end"
-    :arrow-surface-class="{ top: 'bg-(--cp-popover-header-bg)' }"
-  >
-    <template #trigger>
-      <BaseIconButton
-        ref="trigger"
-        label="显示列"
-        variant="filled"
-        :pressed="open"
-        aria-haspopup="dialog"
-        :aria-expanded="open"
-        :aria-controls="open ? panelId : undefined"
-      >
-        <Columns3 class="size-4.5" aria-hidden="true" />
-      </BaseIconButton>
-    </template>
-
-    <div
-      role="presentation"
-      @keydown.esc.stop.prevent="closeAndFocus"
-      @keydown.tab="handleTab"
-      @focusout="handleFocusOut"
-    >
-      <div
-        :id="panelId"
-        ref="panel"
-        role="dialog"
-        aria-label="显示列"
-        class="w-60 max-w-full overflow-hidden rounded-cp-lg"
-      >
-        <div class="flex items-center justify-between gap-3 bg-cp-popover-header-bg px-3 py-2.5">
-          <span class="text-cp-sm font-bold text-cp-text">显示列</span>
-          <span class="text-cp-xs text-cp-text-secondary">{{ visibleCount }} / {{ options.length }}</span>
-        </div>
-        <p :id="`${panelId}-reorder-help`" class="sr-only">
-          拖动手柄调整列顺序，也可聚焦手柄后使用上下方向键移动。
-        </p>
-        <p class="sr-only" role="status" aria-live="polite">
-          {{ announcement }}
-        </p>
-        <BaseScrollbar max-height="min(20rem, calc(100dvh - 10rem))">
-          <div
-            ref="list"
-            class="grid gap-0.5 p-2 [&_[data-column-handle]:is(:hover,:active)]:bg-transparent"
-            role="list"
-            aria-label="表格列"
-            @pointermove="updateHoveredColumn"
-            @pointerleave="clearHoveredColumn"
-          >
-            <div
-              v-for="option in options"
-              :key="option.key"
-              role="listitem"
-              :data-column-key="option.key"
-              :data-reorderable="option.reorderable"
-              :data-highlighted="hoveredColumnKey === option.key"
-              class="flex min-h-9 items-center rounded-cp pr-1 data-[highlighted=true]:bg-cp-bg-text-hover"
-            >
-              <BaseCheckbox
-                :model-value="option.visible"
-                :label="option.label"
-                :disabled="option.disabled"
-                show-label
-                class="min-h-9 min-w-0 flex-1 px-2 py-2"
-                @update:model-value="emit('change', option.key, $event)"
-              />
-              <BaseIconButton
-                v-if="option.reorderable"
-                :label="`拖动调整${option.label}顺序`"
-                :aria-describedby="`${panelId}-reorder-help`"
-                :data-column-key="option.key"
-                data-column-handle
-                variant="ghost"
-                size="sm"
-                class="touch-none cursor-grab active:cursor-grabbing"
-                @keydown.up.stop.prevent="moveWithKeyboard(option.key, -1)"
-                @keydown.down.stop.prevent="moveWithKeyboard(option.key, 1)"
-              >
-                <GripVertical class="size-3.5" aria-hidden="true" />
-              </BaseIconButton>
-            </div>
-          </div>
-        </BaseScrollbar>
-        <div class="flex justify-end px-2 pb-2">
-          <BaseButton variant="ghost" size="sm" @click="emit('reset')">
-            恢复默认
-          </BaseButton>
-        </div>
-      </div>
-    </div>
-  </BasePopover>
-</template>
diff --git a/frontend/src/components/base/BaseTable/BaseTablePagination.vue b/frontend/src/components/base/BaseTable/BaseTablePagination.vue
deleted file mode 100644
index 2ca0ff9d3..000000000
--- a/frontend/src/components/base/BaseTable/BaseTablePagination.vue
+++ /dev/null
@@ -1,154 +0,0 @@
-<script setup lang="ts">
-import type { BaseTablePagination, PagerItem } from './pagination'
-import { ChevronLeft, ChevronRight } from '@lucide/vue'
-
-import { computed } from 'vue'
-import BaseIconButton from '../BaseIconButton.vue'
-import BaseSelect from '../BaseSelect.vue'
-import {
-  getCurrentPage,
-  getPagerItems,
-  getPageSizeOptions,
-  getTotalPages,
-} from './pagination'
-
-const props = defineProps<{
-  pagination: BaseTablePagination
-  loading: boolean
-}>()
-
-const emit = defineEmits<{
-  pageChange: [page: number]
-  pageSizeChange: [pageSize: number]
-}>()
-
-const totalPages = computed(() => getTotalPages(props.pagination))
-const currentPage = computed(() => getCurrentPage(props.pagination, totalPages.value))
-const pageSizeOptions = computed(() => getPageSizeOptions(props.pagination))
-const pagerItems = computed(() => getPagerItems(totalPages.value, currentPage.value))
-const adjacentPagerItems = computed(() => {
-  const count = Math.min(3, totalPages.value)
-  const start = Math.max(1, Math.min(currentPage.value - 1, totalPages.value - count + 1))
-  return Array.from({ length: count }, (_, index) => start + index)
-})
-const compactPagerItems = computed<PagerItem[]>(() => {
-  const total = totalPages.value
-  const current = currentPage.value
-  if (total <= 5)
-    return Array.from({ length: total }, (_, index) => index + 1)
-  if (current <= 3)
-    return [1, 2, 3, 'ellipsis', total]
-  if (current >= total - 2)
-    return [1, 'ellipsis', total - 2, total - 1, total]
-  return [1, 'ellipsis', current, 'ellipsis', total]
-})
-
-const pagerVisibilityClasses = [
-  'flex @min-[19.5rem]/pagination:hidden',
-  'hidden @min-[19.5rem]/pagination:flex @min-[24.5rem]/pagination:hidden',
-  'hidden @min-[24.5rem]/pagination:flex @min-[29.5rem]/pagination:hidden',
-  'hidden @min-[29.5rem]/pagination:flex',
-]
-
-const pageSizeModel = computed({
-  get: () => String(props.pagination.pageSize),
-  set: (value: string) => {
-    if (props.loading) {
-      return
-    }
-
-    const pageSize = Number(value)
-    if (Number.isFinite(pageSize) && pageSize > 0) {
-      emit('pageSizeChange', pageSize)
-    }
-  },
-})
-
-function goToPage(page: number) {
-  if (props.loading || page < 1 || page > totalPages.value || page === currentPage.value) {
-    return
-  }
-
-  emit('pageChange', page)
-}
-
-function paginationPageClass(page: number) {
-  return [
-    'inline-flex size-8 items-center justify-center rounded-cp border-0 text-xs font-bold leading-none transition-colors duration-150 outline-none',
-    page === currentPage.value
-      ? 'cursor-default bg-(--cp-button-primary-bg) text-(--cp-button-primary-color)'
-      : 'cursor-pointer bg-cp-fill-quaternary text-cp-text hover:bg-cp-bg-text-hover focus-visible:ring-2 focus-visible:ring-cp-control-outline focus-visible:ring-offset-2 focus-visible:ring-offset-cp-bg-container',
-  ]
-}
-</script>
-
-<template>
-  <footer
-    class="@container/pagination mt-2 min-h-10 min-w-0 shrink-0 px-0 py-1"
-  >
-    <div class="grid min-w-0 grid-cols-[auto_minmax(0,1fr)] items-center gap-2 @min-[36rem]/pagination:grid-cols-[minmax(0,1fr)_auto_auto] @min-[36rem]/pagination:gap-3">
-      <span class="hidden min-w-0 truncate text-cp-sm font-emphasis text-cp-text-secondary @min-[36rem]/pagination:block">
-        共 {{ pagination.total }} 条
-      </span>
-      <BaseSelect
-        v-model="pageSizeModel"
-        aria-label="每页条数"
-        :options="pageSizeOptions"
-        :disabled="loading"
-        size="sm"
-        class="w-28 shrink-0"
-      />
-
-      <nav
-        aria-label="分页"
-        class="flex shrink-0 items-center justify-self-end gap-2"
-      >
-        <BaseIconButton
-          variant="secondary"
-          size="sm"
-          :disabled="loading || currentPage <= 1"
-          label="上一页"
-          @click="goToPage(currentPage - 1)"
-        >
-          <ChevronLeft class="size-4" />
-        </BaseIconButton>
-
-        <div
-          v-for="(items, variant) in [[currentPage], adjacentPagerItems, compactPagerItems, pagerItems]"
-          :key="variant"
-          class="items-center gap-2"
-          :class="pagerVisibilityClasses[variant]"
-        >
-          <template v-for="(item, index) in items" :key="`${item}-${index}`">
-            <span
-              v-if="item === 'ellipsis'"
-              class="inline-flex size-8 items-center justify-center text-xs font-bold text-cp-text-quaternary"
-            >
-              …
-            </span>
-            <button
-              v-else
-              type="button"
-              :class="paginationPageClass(item)"
-              :disabled="loading || item === currentPage"
-              :aria-current="item === currentPage ? 'page' : undefined"
-              @click="goToPage(item)"
-            >
-              {{ item }}
-            </button>
-          </template>
-        </div>
-
-        <BaseIconButton
-          variant="secondary"
-          size="sm"
-          :disabled="loading || currentPage >= totalPages"
-          label="下一页"
-          @click="goToPage(currentPage + 1)"
-        >
-          <ChevronRight class="size-4" />
-        </BaseIconButton>
-      </nav>
-    </div>
-  </footer>
-</template>
diff --git a/frontend/src/components/base/BaseTable/columns.ts b/frontend/src/components/base/BaseTable/columns.ts
deleted file mode 100644
index 4775b7d86..000000000
--- a/frontend/src/components/base/BaseTable/columns.ts
+++ /dev/null
@@ -1,297 +0,0 @@
-export type TableRow = object
-
-export type TableColumnKind
-  = | 'text'
-    | 'identity'
-    | 'meta'
-    | 'status'
-    | 'numeric'
-    | 'datetime'
-    | 'mono'
-    | 'index'
-    | 'selection'
-    | 'expander'
-    | 'actions'
-    | 'custom'
-
-export type TableColumnSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'
-
-export type TableColumnAlign = 'left' | 'right' | 'center'
-type TableColumnSticky = 'left' | 'right'
-
-export interface BaseTableColumn<Row extends TableRow = TableRow> {
-  key: string
-  label?: string
-  kind?: TableColumnKind
-  size?: TableColumnSize
-  fixedWidth?: boolean
-  align?: TableColumnAlign
-  sortable?: boolean | string
-  /** 列设置中是否允许隐藏；false 时始终保留。 */
-  hideable?: boolean
-  /** 未保存用户偏好时，列设置使用此默认值。 */
-  defaultHidden?: boolean
-  format?: (value: unknown, row: Row) => unknown
-  emptyText?: string
-}
-
-export interface BaseTableSort {
-  key: string
-  direction: 'asc' | 'desc'
-}
-
-export interface BaseTableProps<Row extends TableRow> {
-  columns: BaseTableColumn<Row>[]
-  rows: Row[]
-  rowKey?: string | ((row: Row, index: number) => string | number)
-  selectedRowKeys?: Array<string | number>
-  expandedRowKeys?: Array<string | number>
-  density?: 'compact' | 'default'
-  loading?: boolean
-  emptyText?: string
-  showHeaderWhenEmpty?: boolean
-  scrollbarAlwaysVisible?: boolean
-  sort?: BaseTableSort
-}
-
-interface ColumnRecipe {
-  size: TableColumnSize
-  basisWidth?: number
-  fixedWidth?: boolean
-  align: TableColumnAlign
-  truncate: boolean
-  contentClass?: string
-  paddingClass?: string
-  sticky?: TableColumnSticky
-}
-
-const columnWidths: Record<TableColumnSize, number> = {
-  'xs': 64,
-  'sm': 88,
-  'md': 112,
-  'lg': 144,
-  'xl': 184,
-  '2xl': 240,
-  '3xl': 288,
-  '4xl': 352,
-}
-
-const columnRecipes: Record<TableColumnKind, ColumnRecipe> = {
-  text: {
-    size: '2xl',
-    align: 'left',
-    truncate: true,
-  },
-  identity: {
-    size: '2xl',
-    align: 'left',
-    truncate: true,
-  },
-  meta: {
-    size: 'lg',
-    align: 'left',
-    truncate: true,
-    contentClass: 'text-cp-text-secondary',
-  },
-  status: {
-    size: 'md',
-    align: 'center',
-    truncate: false,
-  },
-  numeric: {
-    size: 'md',
-    align: 'right',
-    truncate: false,
-    contentClass: 'font-mono tabular-nums text-cp-text-secondary',
-  },
-  datetime: {
-    size: 'xl',
-    align: 'left',
-    truncate: false,
-    contentClass: 'whitespace-nowrap font-mono text-cp-sm tabular-nums text-cp-text-secondary',
-  },
-  mono: {
-    size: 'xl',
-    align: 'left',
-    truncate: true,
-    contentClass: 'font-mono text-cp-sm font-emphasis',
-  },
-  index: {
-    size: 'xs',
-    fixedWidth: true,
-    align: 'center',
-    truncate: false,
-    contentClass: 'font-mono tabular-nums text-cp-text-secondary',
-  },
-  selection: {
-    size: 'xs',
-    basisWidth: 48,
-    fixedWidth: true,
-    align: 'center',
-    truncate: false,
-    paddingClass: 'px-2',
-    sticky: 'left',
-  },
-  expander: {
-    size: 'xs',
-    basisWidth: 40,
-    fixedWidth: true,
-    align: 'center',
-    truncate: false,
-    paddingClass: 'px-2',
-    sticky: 'left',
-  },
-  actions: {
-    size: 'md',
-    fixedWidth: true,
-    align: 'left',
-    truncate: false,
-    paddingClass: 'px-3',
-    sticky: 'right',
-  },
-  custom: {
-    size: 'lg',
-    align: 'left',
-    truncate: false,
-  },
-}
-
-export interface ResolvedTableColumn<Row extends TableRow = TableRow>
-  extends BaseTableColumn<Row> {
-  kind: TableColumnKind
-  basisWidth: number
-  fixedWidth: boolean
-  align: TableColumnAlign
-  truncate: boolean
-  contentClass?: string
-  paddingClass?: string
-  sticky?: TableColumnSticky
-  stickyOffset?: number
-}
-
-export function defineTableColumns<Row extends TableRow>(columns: BaseTableColumn<Row>[]) {
-  return columns
-}
-
-export function resolveColumns<Row extends TableRow>(
-  columns: BaseTableColumn<Row>[],
-): ResolvedTableColumn<Row>[] {
-  const resolved = columns.map((column): ResolvedTableColumn<Row> => {
-    const kind = column.kind ?? 'text'
-    const recipe = columnRecipes[kind]
-    const basisWidth = recipe.basisWidth ?? columnWidths[column.size ?? recipe.size]
-
-    return {
-      ...column,
-      kind,
-      basisWidth,
-      fixedWidth: column.fixedWidth ?? recipe.fixedWidth ?? false,
-      align: column.align ?? recipe.align,
-      truncate: recipe.truncate,
-      contentClass: recipe.contentClass,
-      paddingClass: recipe.paddingClass,
-      sticky: recipe.sticky,
-    }
-  })
-
-  let leftOffset = 0
-  for (const column of resolved) {
-    if (column.sticky !== 'left')
-      continue
-    column.stickyOffset = leftOffset
-    leftOffset += column.basisWidth
-  }
-
-  let rightOffset = 0
-  for (const column of [...resolved].reverse()) {
-    if (column.sticky !== 'right')
-      continue
-    column.stickyOffset = rightOffset
-    rightOffset += column.basisWidth
-  }
-
-  return resolved
-}
-
-export function minimumTableWidth<Row extends TableRow>(columns: ResolvedTableColumn<Row>[]) {
-  return columns.reduce((total, column) => total + column.basisWidth, 0)
-}
-
-export function tableStyle<Row extends TableRow>(columns: ResolvedTableColumn<Row>[]) {
-  // 全部列都固定时按总宽度展示，避免浏览器再次均分剩余空间。
-  if (columns.every(column => column.fixedWidth))
-    return { width: `${minimumTableWidth(columns)}px` }
-  return { width: `max(100%, ${minimumTableWidth(columns)}px)` }
-}
-
-export function columnStyle<Row extends TableRow>(
-  column: ResolvedTableColumn<Row>,
-  columns: ResolvedTableColumn<Row>[],
-) {
-  const fixedWidth = columns.reduce((total, item) => total + (item.fixedWidth ? item.basisWidth : 0), 0)
-  const flexibleWidth = minimumTableWidth(columns) - fixedWidth
-  const ratio = flexibleWidth > 0 ? column.basisWidth / flexibleWidth : 0
-
-  return {
-    width: column.fixedWidth
-      ? `${column.basisWidth}px`
-      // 用容器宽度分配剩余空间；col 的百分比 calc 会被固定表格布局忽略。
-      : `max(${column.basisWidth}px, calc(${ratio * 100}cqw - ${fixedWidth * ratio}px))`,
-    minWidth: `${column.basisWidth}px`,
-  }
-}
-
-export function stickyStyle<Row extends TableRow>(column: ResolvedTableColumn<Row>) {
-  if (!column.sticky)
-    return undefined
-  return { [column.sticky]: `${column.stickyOffset ?? 0}px` }
-}
-
-export function alignClass<Row extends TableRow>(column: ResolvedTableColumn<Row>) {
-  if (column.align === 'center')
-    return 'text-center'
-  if (column.align === 'right')
-    return 'text-right'
-  return 'text-left'
-}
-
-export function cellValue(row: TableRow, key: string) {
-  return (row as Record<string, unknown>)[key]
-}
-
-function isEmptyCellValue(value: unknown) {
-  return value === undefined || value === null || value === ''
-}
-
-export function cellDisplayValue<Row extends TableRow>(column: BaseTableColumn<Row>, row: Row) {
-  const rawValue = cellValue(row, column.key)
-  const value = column.format ? column.format(rawValue, row) : rawValue
-  return isEmptyCellValue(value) ? (column.emptyText ?? '—') : value
-}
-
-export function cellTitle<Row extends TableRow>(column: ResolvedTableColumn<Row>, row: Row) {
-  if (!column.truncate)
-    return undefined
-  const value = cellDisplayValue(column, row)
-  return typeof value === 'string' || typeof value === 'number' ? String(value) : undefined
-}
-
-export function cellContentClass<Row extends TableRow>(column: ResolvedTableColumn<Row>) {
-  if (column.kind === 'selection' || column.kind === 'expander') {
-    return [
-      'flex min-w-0 items-center overflow-visible leading-none',
-      column.align === 'right'
-        ? 'justify-end'
-        : column.align === 'center'
-          ? 'justify-center'
-          : 'justify-start',
-    ]
-  }
-  if (column.kind === 'actions')
-    return 'min-w-0 overflow-visible'
-  return ['min-w-0', column.truncate ? 'truncate' : undefined]
-}
-
-export function columnSortKey<Row extends TableRow>(column: BaseTableColumn<Row>) {
-  return typeof column.sortable === 'string' ? column.sortable : column.key
-}
diff --git a/frontend/src/components/base/BaseTable/index.vue b/frontend/src/components/base/BaseTable/index.vue
deleted file mode 100644
index 9e05f1171..000000000
--- a/frontend/src/components/base/BaseTable/index.vue
+++ /dev/null
@@ -1,330 +0,0 @@
-<script setup lang="ts" generic="Row extends object = Record<string, unknown>">
-import type { BaseTableProps, BaseTableSort, ResolvedTableColumn } from './columns'
-
-import { Triangle } from '@lucide/vue'
-import { useResizeObserver } from '@vueuse/core'
-import { computed, nextTick, onMounted, shallowRef, useSlots, useTemplateRef, watch } from 'vue'
-import BaseEmpty from '../BaseEmpty.vue'
-import BaseScrollbar from '../BaseScrollbar.vue'
-import {
-  alignClass,
-  cellContentClass,
-  cellDisplayValue,
-  cellTitle,
-  cellValue,
-  columnSortKey,
-  columnStyle,
-  resolveColumns,
-  stickyStyle,
-  tableStyle,
-} from './columns'
-import { useTableColumnMotion } from './useTableColumnMotion'
-
-const props = withDefaults(defineProps<BaseTableProps<Row>>(), {
-  rowKey: 'id',
-  selectedRowKeys: () => [],
-  expandedRowKeys: () => [],
-  density: 'default',
-  loading: false,
-  emptyText: '暂无数据',
-  showHeaderWhenEmpty: false,
-  scrollbarAlwaysVisible: false,
-  sort: undefined,
-})
-
-const emit = defineEmits<{
-  sortChange: [sort: BaseTableSort | undefined]
-}>()
-const slots = useSlots()
-const computedColumns = computed(() => resolveColumns(props.columns))
-const resolvedTableStyle = computed(() => tableStyle(computedColumns.value))
-
-const retainedRows = shallowRef<Row[]>([])
-watch(
-  [() => props.rows, () => props.loading],
-  ([rows, loading]) => {
-    if (rows.length > 0 || !loading)
-      retainedRows.value = rows
-  },
-  { immediate: true },
-)
-const displayRows = computed(() => (props.loading && props.rows.length === 0 ? retainedRows.value : props.rows))
-const hasRows = computed(() => displayRows.value.length > 0)
-
-const scrollbarRef = useTemplateRef<InstanceType<typeof BaseScrollbar>>('scrollbar')
-const tableRef = useTemplateRef<HTMLTableElement>('table')
-useTableColumnMotion(tableRef, () => computedColumns.value.map(column => column.key))
-const horizontalScrolled = shallowRef(false)
-const horizontalCanScrollRight = shallowRef(false)
-
-function updateScrollLayout() {
-  scrollbarRef.value?.update()
-  const wrap = scrollbarRef.value?.wrapRef
-  if (!wrap) {
-    horizontalScrolled.value = false
-    horizontalCanScrollRight.value = false
-    return
-  }
-  const range = Math.max(wrap.scrollWidth - wrap.clientWidth, 0)
-  horizontalScrolled.value = wrap.scrollLeft > 1
-  horizontalCanScrollRight.value = wrap.scrollLeft < range - 1
-}
-
-function handleTableScroll(payload: { scrollTop: number, scrollLeft: number }) {
-  const wrap = scrollbarRef.value?.wrapRef
-  if (!wrap)
-    return
-  const range = Math.max(wrap.scrollWidth - wrap.clientWidth, 0)
-  horizontalScrolled.value = payload.scrollLeft > 1
-  horizontalCanScrollRight.value = payload.scrollLeft < range - 1
-}
-
-onMounted(async () => {
-  await nextTick()
-  updateScrollLayout()
-})
-useResizeObserver(() => [scrollbarRef.value?.wrapRef, tableRef.value].filter(Boolean), updateScrollLayout)
-watch([() => displayRows.value.length, () => props.columns], async () => {
-  await nextTick()
-  updateScrollLayout()
-})
-
-const headerRowClass = computed(() => [
-  props.density === 'compact' ? 'h-8 text-cp-xs' : 'h-10 text-cp-sm',
-  'font-bold text-cp-text-secondary',
-])
-const bodyRowClass = computed(() => (props.density === 'compact' ? 'h-cp-table-row-sm' : 'h-cp-table-row'))
-const cellPaddingClass = computed(() => (props.density === 'compact' ? 'px-3' : 'px-4'))
-const bodyTextClass = computed(() => (props.density === 'compact' ? 'text-cp-sm' : 'text-cp'))
-const bodyCellFrameClass = computed(() =>
-  props.density === 'compact'
-    ? 'border-y-2 border-transparent bg-clip-padding'
-    : 'border-y-[3px] border-transparent bg-clip-padding',
-)
-const firstRowTopGapClass = computed(() => (props.density === 'compact' ? 'border-t-4' : 'border-t-[6px]'))
-const bodyCellContentClass = computed(() =>
-  props.density === 'compact'
-    ? 'min-h-[calc(var(--cp-table-row-height-sm)-4px)]'
-    : 'min-h-[calc(var(--cp-table-row-height)-6px)]',
-)
-
-function getRowKey(row: Row, index: number) {
-  if (typeof props.rowKey === 'function')
-    return props.rowKey(row, index)
-  const value = cellValue(row, props.rowKey)
-  return typeof value === 'string' || typeof value === 'number' ? value : index
-}
-
-function isRowSelected(row: Row, index: number) {
-  return props.selectedRowKeys.includes(getRowKey(row, index))
-}
-
-function isRowExpanded(row: Row, index: number) {
-  return props.expandedRowKeys.includes(getRowKey(row, index))
-}
-
-function rowBackgroundClass(row: Row, index: number) {
-  if (isRowSelected(row, index))
-    return 'bg-(--cp-table-row-selected-bg)'
-  if (index % 2 === 1)
-    return 'bg-(--cp-table-row-stripe-bg)'
-  return 'bg-(--cp-table-row-bg)'
-}
-
-function rowClass(row: Row, index: number) {
-  return [
-    bodyRowClass.value,
-    isRowSelected(row, index)
-      ? 'hover:[&>td]:bg-(--cp-table-row-selected-hover-bg)'
-      : 'hover:[&>td]:bg-(--cp-table-row-hover-bg)',
-  ]
-}
-
-function stickyClass(column: ResolvedTableColumn<Row>, header = false) {
-  if (!column.sticky)
-    return undefined
-  const showShadow = column.sticky === 'left' ? horizontalScrolled.value : horizontalCanScrollRight.value
-  return [
-    'sticky',
-    header ? 'z-40' : 'z-20',
-    showShadow
-      ? column.sticky === 'left'
-        ? 'shadow-[8px_0_14px_-14px_var(--cp-color-shadow)]'
-        : 'shadow-[-8px_0_14px_-14px_var(--cp-color-shadow)]'
-      : undefined,
-  ]
-}
-
-function bodyCellTitle(column: ResolvedTableColumn<Row>, row: Row) {
-  return slots[column.key] ? undefined : cellTitle(column, row)
-}
-
-function columnSortDirection(column: ResolvedTableColumn<Row>) {
-  return props.sort?.key === columnSortKey(column) ? props.sort.direction : undefined
-}
-
-function toggleColumnSort(column: ResolvedTableColumn<Row>) {
-  const key = columnSortKey(column)
-  const direction = columnSortDirection(column)
-  if (!direction)
-    emit('sortChange', { key, direction: 'asc' })
-  else if (direction === 'asc')
-    emit('sortChange', { key, direction: 'desc' })
-  else emit('sortChange', undefined)
-}
-
-function columnAriaSort(column: ResolvedTableColumn<Row>) {
-  const direction = columnSortDirection(column)
-  if (direction === 'asc')
-    return 'ascending'
-  if (direction === 'desc')
-    return 'descending'
-  return column.sortable ? 'none' : undefined
-}
-
-function sortButtonLabel(column: ResolvedTableColumn<Row>) {
-  const direction = columnSortDirection(column)
-  if (!direction)
-    return `${column.label || column.key}：升序排列`
-  if (direction === 'asc')
-    return `${column.label || column.key}：降序排列`
-  return `${column.label || column.key}：取消排序`
-}
-</script>
-
-<template>
-  <div class="@container/table isolate flex h-full min-h-0 w-full max-w-full flex-col overflow-hidden">
-    <div v-loading="loading && (hasRows || !showHeaderWhenEmpty)" class="relative flex min-h-0 max-w-full flex-1 overflow-hidden">
-      <BaseScrollbar
-        v-if="hasRows || showHeaderWhenEmpty"
-        ref="scrollbar"
-        class="min-h-0 flex-1"
-        :class="
-          density === 'compact'
-            ? '[--cp-scrollbar-track-inset-block-start:2.25rem]'
-            : '[--cp-scrollbar-track-inset-block-start:2.75rem]'
-        "
-        :always-visible="scrollbarAlwaysVisible"
-        horizontal
-        @scroll="handleTableScroll"
-      >
-        <table ref="table" class="table-fixed border-separate border-spacing-0 text-left" :style="resolvedTableStyle">
-          <colgroup>
-            <col v-for="column in computedColumns" :key="column.key" :style="columnStyle(column, computedColumns)">
-          </colgroup>
-          <thead>
-            <tr :class="headerRowClass">
-              <th
-                v-for="(column, columnIndex) in computedColumns"
-                :key="column.key"
-                class="sticky top-0 z-30 whitespace-nowrap bg-(--cp-table-header-bg) shadow-[0_10px_16px_-18px_var(--cp-color-shadow)]"
-                :class="[
-                  column.paddingClass ?? cellPaddingClass,
-                  alignClass(column),
-                  columnIndex === 0 ? 'rounded-l-cp' : undefined,
-                  columnIndex === computedColumns.length - 1 ? 'rounded-r-cp' : undefined,
-                  columnIndex === computedColumns.length - 1 ? 'pr-6' : undefined,
-                  stickyClass(column, true),
-                ]"
-                :style="stickyStyle(column)"
-                scope="col"
-                :aria-sort="columnAriaSort(column)"
-              >
-                <div :class="cellContentClass(column)" :data-column-motion="column.sticky ? undefined : column.key">
-                  <button
-                    v-if="column.sortable"
-                    type="button"
-                    class="inline-flex max-w-full touch-manipulation items-center gap-1 border-0 bg-transparent p-0 text-inherit outline-none transition-colors hover:text-cp-text focus-visible:text-cp-primary-text motion-reduce:transition-none"
-                    :aria-label="sortButtonLabel(column)"
-                    :title="sortButtonLabel(column)"
-                    @click="toggleColumnSort(column)"
-                  >
-                    <span class="truncate">
-                      <slot :name="`header-${column.key}`" :column="column">{{ column.label }}</slot>
-                    </span>
-                    <span class="inline-flex shrink-0 -translate-y-px flex-col gap-px">
-                      <Triangle
-                        class="size-1.25 fill-current"
-                        :class="
-                          columnSortDirection(column) === 'asc' ? 'text-cp-primary-text' : 'text-cp-text-tertiary'
-                        "
-                        :stroke-width="0"
-                      />
-                      <Triangle
-                        class="size-1.25 rotate-180 fill-current"
-                        :class="
-                          columnSortDirection(column) === 'desc' ? 'text-cp-primary-text' : 'text-cp-text-tertiary'
-                        "
-                        :stroke-width="0"
-                      />
-                    </span>
-                  </button>
-                  <slot v-else :name="`header-${column.key}`" :column="column">
-                    {{ column.label }}
-                  </slot>
-                </div>
-              </th>
-            </tr>
-          </thead>
-          <tbody>
-            <template v-for="(row, index) in displayRows" :key="getRowKey(row, index)">
-              <tr :class="rowClass(row, index)" :aria-selected="isRowSelected(row, index) || undefined">
-                <td
-                  v-for="(column, columnIndex) in computedColumns"
-                  :key="column.key"
-                  class="min-w-0 transition-[background-color] duration-150 ease-out motion-reduce:transition-none"
-                  :class="[
-                    column.paddingClass ?? cellPaddingClass,
-                    bodyTextClass,
-                    bodyCellFrameClass,
-                    column.contentClass,
-                    alignClass(column),
-                    index === 0 ? firstRowTopGapClass : undefined,
-                    columnIndex === 0 ? 'rounded-l-cp' : undefined,
-                    columnIndex === computedColumns.length - 1 ? 'rounded-r-cp pr-6' : undefined,
-                    stickyClass(column),
-                    rowBackgroundClass(row, index),
-                  ]"
-                  :style="stickyStyle(column)"
-                >
-                  <div class="grid content-center" :class="bodyCellContentClass" :data-column-motion="column.sticky ? undefined : column.key">
-                    <div :class="cellContentClass(column)" :title="bodyCellTitle(column, row)">
-                      <slot
-                        :name="column.key"
-                        :row="row"
-                        :value="cellValue(row, column.key)"
-                        :display-value="cellDisplayValue(column, row)"
-                        :index="index"
-                      >
-                        {{ cellDisplayValue(column, row) }}
-                      </slot>
-                    </div>
-                  </div>
-                </td>
-              </tr>
-              <tr v-if="isRowExpanded(row, index)">
-                <td
-                  :colspan="computedColumns.length"
-                  class="rounded-cp border-y-transparent bg-cp-fill-quaternary bg-clip-padding p-0"
-                  :class="bodyCellFrameClass"
-                >
-                  <slot name="expanded" :row="row" :index="index" />
-                </td>
-              </tr>
-            </template>
-          </tbody>
-        </table>
-      </BaseScrollbar>
-      <div
-        v-if="!hasRows"
-        v-loading="loading && showHeaderWhenEmpty"
-        class="grid min-h-0 flex-1 place-items-center overflow-hidden px-4"
-        :class="showHeaderWhenEmpty ? ['absolute inset-x-0 bottom-0', density === 'compact' ? 'top-8' : 'top-10'] : undefined"
-      >
-        <slot v-if="!loading" name="empty">
-          <BaseEmpty :title="emptyText" surface="none" class="w-full max-w-80" />
-        </slot>
-      </div>
-    </div>
-  </div>
-</template>
diff --git a/frontend/src/components/base/BaseTable/pagination.ts b/frontend/src/components/base/BaseTable/pagination.ts
deleted file mode 100644
index ac6563e47..000000000
--- a/frontend/src/components/base/BaseTable/pagination.ts
+++ /dev/null
@@ -1,71 +0,0 @@
-import { clamp, range } from 'es-toolkit'
-
-export interface BaseTablePagination {
-  currentPage: number
-  pageSize: number
-  total: number
-  pageSizes?: number[]
-}
-
-export type PagerItem = number | 'ellipsis'
-
-const DEFAULT_PAGE_SIZES = [10, 20, 50, 100]
-
-export function getTotalPages(pagination?: BaseTablePagination) {
-  if (!pagination) {
-    return 0
-  }
-
-  if (pagination.total <= 0) {
-    return 1
-  }
-
-  return clamp(Math.ceil(pagination.total / pagination.pageSize), 1, Number.POSITIVE_INFINITY)
-}
-
-export function getCurrentPage(pagination: BaseTablePagination | undefined, totalPages: number) {
-  if (!pagination || totalPages === 0) {
-    return 0
-  }
-
-  return clamp(pagination.currentPage, 1, totalPages)
-}
-
-export function getPageSizeOptions(pagination?: BaseTablePagination) {
-  const pageSizes = pagination?.pageSizes?.length ? pagination.pageSizes : DEFAULT_PAGE_SIZES
-
-  return pageSizes.map(pageSize => ({
-    label: `${pageSize} 条/页`,
-    value: String(pageSize),
-  }))
-}
-
-export function getPagerItems(total: number, current: number): PagerItem[] {
-  if (total <= 7) {
-    return range(1, total + 1)
-  }
-
-  const pages = new Set<number>([1, total, current, current - 1, current + 1])
-  if (current <= 3) {
-    pages.add(2)
-    pages.add(3)
-    pages.add(4)
-  }
-  if (current >= total - 2) {
-    pages.add(total - 1)
-    pages.add(total - 2)
-    pages.add(total - 3)
-  }
-
-  const sorted = [...pages].filter(page => page >= 1 && page <= total).sort((a, b) => a - b)
-  const items: PagerItem[] = []
-  for (const page of sorted) {
-    const previous = items[items.length - 1]
-    if (typeof previous === 'number' && page - previous > 1) {
-      items.push('ellipsis')
-    }
-    items.push(page)
-  }
-
-  return items
-}
diff --git a/frontend/src/components/base/BaseTable/useTableColumnMotion.ts b/frontend/src/components/base/BaseTable/useTableColumnMotion.ts
deleted file mode 100644
index 8ef46adaa..000000000
--- a/frontend/src/components/base/BaseTable/useTableColumnMotion.ts
+++ /dev/null
@@ -1,48 +0,0 @@
-import type { MaybeRefOrGetter } from 'vue'
-import { usePreferredReducedMotion } from '@vueuse/core'
-import { nextTick, toValue, watch } from 'vue'
-
-export function useTableColumnMotion(
-  table: MaybeRefOrGetter<HTMLTableElement | null>,
-  columnKeys: () => string[],
-) {
-  const preferredMotion = usePreferredReducedMotion()
-
-  watch([columnKeys, preferredMotion], async ([keys, motion], [previousKeys], onCleanup) => {
-    const root = toValue(table)
-    if (!root || motion === 'reduce'
-      || keys.length !== previousKeys.length
-      || keys.every((key, index) => key === previousKeys[index])
-      || keys.some(key => !previousKeys.includes(key))) {
-      return
-    }
-
-    // 只处理已有列换位；在列宽更新前记录位置，固定列不参与移动。
-    const elements = Array.from(root.querySelectorAll<HTMLElement>('[data-column-motion]'))
-      .filter(element => element.closest('table') === root)
-    const positions = new Map(elements.map(element => [element, element.getBoundingClientRect().left]))
-    const animations: Animation[] = []
-    let cancelled = false
-    onCleanup(() => {
-      cancelled = true
-      animations.forEach(animation => animation.cancel())
-    })
-
-    await nextTick()
-    if (cancelled || !root.isConnected)
-      return
-
-    // 先统一读取新位置，再播放位移，避免逐个单元格交替读写布局。
-    const movements = Array.from(positions)
-      .filter(([element]) => element.isConnected)
-      .map(([element, left]) => ({ element, offset: left - element.getBoundingClientRect().left }))
-    for (const { element, offset } of movements) {
-      if (Math.abs(offset) < 0.5)
-        continue
-      animations.push(element.animate([
-        { transform: `translateX(${offset}px)` },
-        { transform: 'translateX(0)' },
-      ], { duration: 200, easing: 'cubic-bezier(0.2, 0, 0, 1)' }))
-    }
-  })
-}
diff --git a/frontend/src/components/base/BaseTable/useTableColumns.ts b/frontend/src/components/base/BaseTable/useTableColumns.ts
deleted file mode 100644
index fc0f262d5..000000000
--- a/frontend/src/components/base/BaseTable/useTableColumns.ts
+++ /dev/null
@@ -1,124 +0,0 @@
-import type { MaybeRefOrGetter } from 'vue'
-import type { BaseTableColumn, TableRow } from './columns'
-import { useStorage } from '@vueuse/core'
-import { computed, toValue } from 'vue'
-import { resolveColumns } from './columns'
-
-export interface TableColumnOption {
-  key: string
-  label: string
-  visible: boolean
-  disabled: boolean
-  reorderable: boolean
-}
-
-function readVisibility(value: string): Record<string, boolean> {
-  try {
-    const parsed: unknown = JSON.parse(value)
-    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
-      return Object.fromEntries(Object.entries(parsed).filter(([, visible]) => typeof visible === 'boolean'))
-  }
-  catch {
-    // 损坏的本地偏好回退到列定义，不影响表格展示。
-  }
-  return {}
-}
-
-function readOrder(value: string): string[] {
-  try {
-    const parsed: unknown = JSON.parse(value)
-    if (Array.isArray(parsed))
-      return [...new Set(parsed.filter((key): key is string => typeof key === 'string'))]
-  }
-  catch {
-    // 顺序偏好损坏时回退到列定义，保留独立存储的显隐偏好。
-  }
-  return []
-}
-
-export function useTableColumns<Row extends TableRow>(
-  source: MaybeRefOrGetter<BaseTableColumn<Row>[]>,
-  tableId: string,
-) {
-  // 只保存用户覆盖；新增列继续使用自身默认值，不继承旧列表的隐藏状态。
-  const overrides = useStorage<Record<string, boolean>>(
-    `codex-proxy:table-columns:${tableId}`,
-    {},
-    undefined,
-    {
-      shallow: true,
-      writeDefaults: false,
-      serializer: { read: readVisibility, write: JSON.stringify },
-    },
-  )
-  const order = useStorage<string[]>(
-    `codex-proxy:table-column-order:${tableId}`,
-    [],
-    undefined,
-    {
-      shallow: true,
-      writeDefaults: false,
-      serializer: { read: readOrder, write: JSON.stringify },
-    },
-  )
-
-  const orderedColumns = computed(() => {
-    const columns = resolveColumns(toValue(source))
-    const ranks = new Map(order.value.map((key, index) => [key, index]))
-    const movable = columns.filter(column => column.label && !column.sticky)
-      .sort((a, b) => (ranks.get(a.key) ?? Number.MAX_SAFE_INTEGER) - (ranks.get(b.key) ?? Number.MAX_SAFE_INTEGER))
-
-    // 固定列保留原位；新增列沿用定义顺序，接在用户已排序的普通列之后。
-    let index = 0
-    return columns.map(column => column.label && !column.sticky ? movable[index++]! : column)
-  })
-
-  const columnStates = computed(() => {
-    const states = orderedColumns.value.map((column) => {
-      const override = overrides.value[column.key]
-      return {
-        column,
-        visible: column.hideable === false || (typeof override === 'boolean' ? override : !column.defaultHidden),
-      }
-    })
-    // 即使旧偏好隐藏了全部列，也保留一个可操作的表格。
-    if (!states.some(state => state.visible) && states[0])
-      states[0].visible = true
-    return states
-  })
-  const visibleColumns = computed(() => columnStates.value.filter(state => state.visible).map(state => state.column))
-  const columnOptions = computed<TableColumnOption[]>(() => columnStates.value
-    .filter(({ column }) => column.label)
-    .map(({ column, visible }) => ({
-      key: column.key,
-      label: column.label!,
-      visible,
-      disabled: column.hideable === false || (visible && visibleColumns.value.length === 1),
-      reorderable: !column.sticky,
-    })))
-
-  function setColumnVisible(key: string, visible: boolean) {
-    const option = columnOptions.value.find(option => option.key === key)
-    const column = toValue(source).find(column => column.key === key)
-    if (!column || !option || option.disabled)
-      return
-
-    const next = { ...overrides.value }
-    if (visible === !column.defaultHidden)
-      delete next[key]
-    else next[key] = visible
-    overrides.value = next
-  }
-
-  function setColumnOrder(keys: string[]) {
-    const movable = new Set(columnOptions.value.filter(option => option.reorderable).map(option => option.key))
-    order.value = [...new Set(keys.filter(key => movable.has(key)))]
-  }
-
-  function resetColumns() {
-    overrides.value = {}
-    order.value = []
-  }
-
-  return { visibleColumns, columnOptions, setColumnVisible, setColumnOrder, resetColumns }
-}
diff --git a/frontend/src/components/base/BaseTag.vue b/frontend/src/components/base/BaseTag.vue
deleted file mode 100644
index b456e8b94..000000000
--- a/frontend/src/components/base/BaseTag.vue
+++ /dev/null
@@ -1,68 +0,0 @@
-<script setup lang="ts">
-import { X } from '@lucide/vue'
-import { computed, useId } from 'vue'
-
-type TagType = 'neutral' | 'primary' | 'success' | 'info' | 'warning' | 'danger'
-type TagSize = 'sm' | 'md' | 'lg'
-
-const props = withDefaults(defineProps<{
-  type?: TagType
-  size?: TagSize
-  round?: boolean
-  closable?: boolean
-  disabled?: boolean
-  closeLabel?: string
-}>(), {
-  type: 'neutral',
-  size: 'md',
-  round: false,
-  closable: false,
-  disabled: false,
-  closeLabel: undefined,
-})
-
-// 关闭只通知调用方，由调用方决定是否移除标签。
-defineEmits<{ close: [event: MouseEvent] }>()
-defineSlots<{ default: () => unknown }>()
-const contentId = useId()
-const closeId = useId()
-
-const typeClasses: Record<TagType, string> = {
-  neutral: 'bg-cp-fill-tertiary text-cp-text-secondary',
-  primary: 'bg-cp-primary-container text-cp-primary-on-container',
-  success: 'bg-cp-success-container text-cp-success-on-container',
-  info: 'bg-cp-info-container text-cp-info-on-container',
-  warning: 'bg-cp-warning-container text-cp-warning-on-container',
-  danger: 'bg-cp-error-container text-cp-error-on-container',
-}
-const sizeClasses: Record<TagSize, string> = {
-  sm: 'min-h-5 gap-1 px-1.5 py-0.5 text-cp-xs',
-  md: 'min-h-6 gap-1.5 px-2 py-0.5 text-cp-xs',
-  lg: 'min-h-7 gap-2 px-2.5 py-1 text-cp-sm',
-}
-const classes = computed(() => [
-  sizeClasses[props.size],
-  props.round ? 'rounded-full' : 'rounded-cp',
-  props.disabled ? 'bg-cp-bg-container-disabled text-cp-text-disabled' : typeClasses[props.type],
-])
-</script>
-
-<template>
-  <span class="inline-flex max-w-full min-w-0 items-center align-middle font-emphasis leading-snug" :class="classes">
-    <span :id="closable ? contentId : undefined" class="min-w-0 [overflow-wrap:anywhere]">
-      <slot />
-    </span>
-    <button
-      v-if="closable"
-      type="button"
-      :disabled="disabled"
-      :aria-label="closeLabel"
-      :aria-labelledby="closeLabel ? undefined : `${closeId} ${contentId}`"
-      class="inline-grid size-5 shrink-0 cursor-pointer place-items-center rounded-full border-0 bg-transparent p-0 text-inherit outline-none transition-colors duration-150 hover:bg-current/10 focus-visible:ring-2 focus-visible:ring-cp-control-outline active:bg-current/20 disabled:cursor-not-allowed disabled:hover:bg-transparent motion-reduce:transition-none"
-      @click.stop="$emit('close', $event)"
-    >
-      <span :id="closeId" class="sr-only">移除</span>
-      <X class="size-3" aria-hidden="true" />
-    </button>
-  </span>
-</template>
diff --git a/frontend/src/components/base/BaseTextarea.vue b/frontend/src/components/base/BaseTextarea.vue
deleted file mode 100644
index eb6109103..000000000
--- a/frontend/src/components/base/BaseTextarea.vue
+++ /dev/null
@@ -1,89 +0,0 @@
-<script setup lang="ts">
-import { computed, inject, useAttrs } from 'vue'
-import { formFieldKey } from './BaseForm/context'
-
-type TextareaSize = 'sm' | 'md' | 'lg'
-
-defineOptions({ inheritAttrs: false })
-
-const props = withDefaults(
-  defineProps<{
-    placeholder?: string
-    disabled?: boolean
-    size?: TextareaSize
-    rows?: number
-    resize?: 'none' | 'both' | 'horizontal' | 'vertical'
-  }>(),
-  {
-    placeholder: '',
-    disabled: false,
-    size: 'md',
-    rows: 5,
-    resize: 'vertical',
-  },
-)
-
-const model = defineModel<string>({ default: '' })
-const attrs = useAttrs()
-const field = inject(formFieldKey, null)
-
-const controlId = computed(() => typeof attrs.id === 'string' ? attrs.id : field?.controlId.value)
-const invalid = computed(() => Boolean(
-  field?.invalid.value || attrs['aria-invalid'] === true || attrs['aria-invalid'] === 'true',
-))
-const describedBy = computed(() => [
-  typeof attrs['aria-describedby'] === 'string' ? attrs['aria-describedby'] : undefined,
-  field?.describedBy.value,
-].filter(Boolean).join(' ') || undefined)
-const rootAttrs = computed(() => ({ class: attrs.class, style: attrs.style }))
-const controlAttrs = computed(() => Object.fromEntries(
-  Object.entries(attrs).filter(([key]) => ![
-    'class',
-    'style',
-    'id',
-    'aria-describedby',
-    'aria-invalid',
-    'aria-required',
-  ].includes(key)),
-))
-
-const sizeClasses: Record<TextareaSize, string> = {
-  sm: 'px-3 py-2.5 text-xs',
-  md: 'px-3.5 py-3 text-cp',
-  lg: 'px-4 py-3.5 text-cp-lg',
-}
-
-const textareaClasses = computed(() => [
-  'cp-scrollbar w-full rounded-cp border-0 text-cp-text shadow-cp-input outline-none transition-[background-color,box-shadow,color] duration-160 placeholder:text-cp-text-quaternary motion-reduce:transition-none',
-  'leading-[1.55] font-emphasis',
-  sizeClasses[props.size],
-  props.disabled
-    ? 'cursor-not-allowed bg-cp-bg-container-disabled text-cp-text-disabled shadow-none'
-    : invalid.value
-      ? 'bg-(--cp-input-error-active-bg) shadow-cp-input-error-active'
-      : [
-          'bg-[var(--cp-input-bg)]',
-          'hover:not-focus:bg-[var(--cp-input-hover-bg)] hover:not-focus:shadow-cp-input-hover',
-          'focus:bg-(--cp-input-active-bg) focus:shadow-cp-input-active',
-        ],
-])
-</script>
-
-<template>
-  <div v-bind="rootAttrs" class="min-w-0">
-    <textarea
-      v-bind="controlAttrs"
-      :id="controlId"
-      v-model="model"
-      :class="textareaClasses"
-      :style="{ resize: disabled ? 'none' : resize }"
-      :rows="rows"
-      :placeholder="placeholder"
-      :disabled="disabled"
-      :required="field?.required.value || undefined"
-      :aria-describedby="describedBy"
-      :aria-invalid="invalid || undefined"
-      :aria-required="field?.required.value || undefined"
-    />
-  </div>
-</template>
diff --git a/frontend/src/components/base/BaseToast/BaseToast.vue b/frontend/src/components/base/BaseToast/BaseToast.vue
deleted file mode 100644
index 624c4a673..000000000
--- a/frontend/src/components/base/BaseToast/BaseToast.vue
+++ /dev/null
@@ -1,125 +0,0 @@
-<script setup lang="ts">
-import { AlertCircle, AlertTriangle, CheckCircle2, Info, X } from '@lucide/vue'
-
-import BaseIconButton from '../BaseIconButton.vue'
-import { toast } from './toast'
-
-const iconMap = {
-  success: CheckCircle2,
-  error: AlertCircle,
-  warning: AlertTriangle,
-  info: Info,
-}
-
-const titleMap = {
-  success: '成功',
-  error: '失败',
-  warning: '警告',
-  info: '信息',
-}
-
-const colorClasses = {
-  success: {
-    iconBg: 'bg-cp-success-container',
-    icon: 'text-cp-success',
-  },
-  error: {
-    iconBg: 'bg-cp-error-container',
-    icon: 'text-cp-error',
-  },
-  warning: {
-    iconBg: 'bg-cp-warning-container',
-    icon: 'text-cp-warning',
-  },
-  info: {
-    iconBg: 'bg-cp-info-container',
-    icon: 'text-cp-info',
-  },
-}
-</script>
-
-<template>
-  <Teleport to="body">
-    <div class="pointer-events-none fixed inset-x-3 top-3 z-9999 flex flex-col items-end gap-3 sm:inset-x-auto sm:top-6 sm:right-6">
-      <TransitionGroup name="toast" tag="div" class="flex flex-col gap-3">
-        <article
-          v-for="message in toast.messages"
-          :key="message.id"
-          class="pointer-events-auto flex min-h-16 w-90 max-w-[calc(100vw-1.5rem)] items-center gap-3 rounded-cp-card bg-cp-bg-elevated px-3.5 py-3 shadow-cp"
-          :role="message.type === 'error' ? 'alert' : 'status'"
-          aria-atomic="true"
-        >
-          <div
-            class="flex size-8.5 shrink-0 items-center justify-center rounded-cp"
-            :class="colorClasses[message.type].iconBg"
-          >
-            <component
-              :is="iconMap[message.type]"
-              :size="18"
-              :class="colorClasses[message.type].icon"
-            />
-          </div>
-
-          <div class="flex min-w-0 flex-1 flex-col gap-1">
-            <p class="m-0 truncate text-cp leading-[1.15] font-bold text-cp-text">
-              {{ message.title ?? titleMap[message.type] }}
-            </p>
-            <p
-              class="m-0 max-h-8 overflow-hidden text-xs leading-tight font-semibold text-cp-text-secondary"
-            >
-              {{ message.message }}
-            </p>
-          </div>
-
-          <BaseIconButton
-            size="sm"
-            variant="ghost"
-            :label="`关闭${message.title ?? titleMap[message.type]}通知`"
-            @click="toast.remove(message.id)"
-          >
-            <X :size="16" class="text-cp-text-quaternary" />
-          </BaseIconButton>
-        </article>
-      </TransitionGroup>
-    </div>
-  </Teleport>
-</template>
-
-<style scoped>
-.toast-enter-active {
-  animation: toast-in 0.3s ease-out;
-}
-
-.toast-leave-active {
-  animation: toast-out 0.2s ease-in;
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .toast-enter-active,
-  .toast-leave-active {
-    animation: none;
-  }
-}
-
-@keyframes toast-in {
-  from {
-    opacity: 0;
-    transform: translateX(100%) scale(0.95);
-  }
-  to {
-    opacity: 1;
-    transform: translateX(0) scale(1);
-  }
-}
-
-@keyframes toast-out {
-  from {
-    opacity: 1;
-    transform: translateX(0) scale(1);
-  }
-  to {
-    opacity: 0;
-    transform: translateX(100%) scale(0.95);
-  }
-}
-</style>
diff --git a/frontend/src/components/base/BaseToast/index.ts b/frontend/src/components/base/BaseToast/index.ts
deleted file mode 100644
index 08b646b4b..000000000
--- a/frontend/src/components/base/BaseToast/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export { default as BaseToast } from './BaseToast.vue'
-export { toast } from './toast'
diff --git a/frontend/src/components/base/BaseToast/toast.ts b/frontend/src/components/base/BaseToast/toast.ts
deleted file mode 100644
index e74ef8fa7..000000000
--- a/frontend/src/components/base/BaseToast/toast.ts
+++ /dev/null
@@ -1,81 +0,0 @@
-import { reactive } from 'vue'
-
-export type ToastType = 'success' | 'error' | 'warning' | 'info'
-
-interface ToastMessage {
-  id: string
-  type: ToastType
-  title?: string
-  message: string
-  duration: number
-}
-
-export interface ToastOptions {
-  title?: string
-  duration?: number
-}
-
-const DEFAULT_DURATION = 3000
-const messages = reactive<ToastMessage[]>([])
-const timers = new Map<string, number>()
-
-function normalizeOptions(options: number | ToastOptions = DEFAULT_DURATION) {
-  if (typeof options === 'number') {
-    return {
-      duration: options,
-      title: undefined,
-    }
-  }
-
-  return {
-    duration: options.duration ?? DEFAULT_DURATION,
-    title: options.title,
-  }
-}
-
-function remove(id: string) {
-  const timer = timers.get(id)
-  if (timer !== undefined) {
-    window.clearTimeout(timer)
-    timers.delete(id)
-  }
-
-  const index = messages.findIndex(message => message.id === id)
-  if (index >= 0) {
-    messages.splice(index, 1)
-  }
-}
-
-function show(type: ToastType, message: string, options?: number | ToastOptions) {
-  const { duration, title } = normalizeOptions(options)
-  const id = `toast_${Date.now()}_${Math.random().toString(16).slice(2)}`
-
-  messages.push({
-    id,
-    type,
-    message,
-    duration,
-    title,
-  })
-
-  if (duration > 0) {
-    timers.set(
-      id,
-      window.setTimeout(() => {
-        remove(id)
-      }, duration),
-    )
-  }
-
-  return id
-}
-
-export const toast = {
-  messages,
-  show,
-  remove,
-  success: (message: string, options?: number | ToastOptions) => show('success', message, options),
-  error: (message: string, options?: number | ToastOptions) => show('error', message, options),
-  warning: (message: string, options?: number | ToastOptions) => show('warning', message, options),
-  info: (message: string, options?: number | ToastOptions) => show('info', message, options),
-}
diff --git a/frontend/src/components/client-profile/ClientProfileEditor.vue b/frontend/src/components/client-profile/ClientProfileEditor.vue
index 6a2d9197b..ff63fa4cc 100644
--- a/frontend/src/components/client-profile/ClientProfileEditor.vue
+++ b/frontend/src/components/client-profile/ClientProfileEditor.vue
@@ -1,12 +1,8 @@
 <script setup lang="ts">
 import type { ClientProfilePreset, ClientProfilePreview, ClientProfileSelection } from '@/api/modules/client-profiles'
+import { BaseButton, BaseFormItem, BaseInput, BaseSegmented, BaseSelect } from '@codex-proxy/ui'
 import { computed, onMounted, shallowRef, watch } from 'vue'
 import { getClientProfileOptions, previewClientProfile } from '@/api/modules/client-profiles'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
 import { errorMessage } from '@/utils/async'
 import ClientProfilePreviewPanel from './ClientProfilePreviewPanel.vue'
 
diff --git a/frontend/src/components/client-profile/ClientProfilePreviewPanel.vue b/frontend/src/components/client-profile/ClientProfilePreviewPanel.vue
index b4066257a..08df566e8 100644
--- a/frontend/src/components/client-profile/ClientProfilePreviewPanel.vue
+++ b/frontend/src/components/client-profile/ClientProfilePreviewPanel.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { ClientProfilePreview } from '@/api/modules/client-profiles'
-import BaseSkeleton from '@/components/base/BaseSkeleton.vue'
+import { BaseSkeleton } from '@codex-proxy/ui'
 import { formatDateTime } from '@/utils/date'
 
 defineProps<{
diff --git a/frontend/src/components/client-profile/ProviderRequestProfileEditor.vue b/frontend/src/components/client-profile/ProviderRequestProfileEditor.vue
new file mode 100644
index 000000000..f10cae5c7
--- /dev/null
+++ b/frontend/src/components/client-profile/ProviderRequestProfileEditor.vue
@@ -0,0 +1,222 @@
+<script setup lang="ts">
+import type {
+  ProviderRequestProfile,
+  ProviderRequestProfileOptions,
+  ProviderRequestProfilePreview,
+} from '@/api/modules/client-profiles'
+import { BaseButton, BaseFormItem, BaseSegmented, BaseSelect, BaseSkeleton } from '@codex-proxy/ui'
+import { isEqual } from 'es-toolkit'
+import { computed, shallowRef, watch } from 'vue'
+import {
+  getProviderClientProfileOptions,
+  previewProviderClientProfile,
+} from '@/api/modules/client-profiles'
+import { errorMessage } from '@/utils/async'
+import { formatDateTime } from '@/utils/date'
+
+const props = withDefaults(defineProps<{
+  provider: string
+  active?: boolean
+  disabled?: boolean
+  allowInherit?: boolean
+}>(), {
+  active: true,
+  disabled: false,
+  allowInherit: false,
+})
+
+const model = defineModel<ProviderRequestProfile | null>({ required: true })
+const options = shallowRef<ProviderRequestProfileOptions>()
+const preview = shallowRef<ProviderRequestProfilePreview>()
+const loading = shallowRef(true)
+const loadError = shallowRef('')
+const previewing = shallowRef(false)
+const previewError = shallowRef('')
+let loadGeneration = 0
+
+const presetOptions = computed(() => options.value?.presets.map(preset => ({
+  label: preset.label,
+  value: preset.id,
+  description: preset.description ?? undefined,
+})) ?? [])
+
+const selectedPreset = computed({
+  get: () => options.value?.presets.find(preset => isEqual(preset.configuration, model.value))?.id ?? '',
+  set: (value: string) => {
+    const preset = options.value?.presets.find(item => item.id === value)
+    if (preset)
+      model.value = cloneProfile(preset.configuration)
+  },
+})
+
+const profileSource = computed({
+  get: () => model.value === null ? 'global' : 'independent',
+  set: (value: string) => {
+    if (value === 'global') {
+      model.value = null
+      return
+    }
+    const configuration = options.value?.globalConfiguration ?? options.value?.defaultConfiguration
+    if (configuration)
+      model.value = cloneProfile(configuration)
+  },
+})
+
+const releaseLabel = computed(() => {
+  switch (preview.value?.release?.status) {
+    case 'current': return '当前版本'
+    case 'update_available': return '有可用更新'
+    case 'failed': return '版本信息不可用'
+    default: return ''
+  }
+})
+
+function cloneProfile(value: ProviderRequestProfile): ProviderRequestProfile {
+  return JSON.parse(JSON.stringify(value)) as ProviderRequestProfile
+}
+
+async function load() {
+  const generation = ++loadGeneration
+  loading.value = true
+  loadError.value = ''
+  try {
+    const result = await getProviderClientProfileOptions(props.provider)
+    if (generation !== loadGeneration)
+      return
+    options.value = result
+    if (!props.allowInherit && model.value === null)
+      model.value = cloneProfile(result.globalConfiguration ?? result.defaultConfiguration)
+  }
+  catch (error) {
+    if (generation === loadGeneration)
+      loadError.value = errorMessage(error)
+  }
+  finally {
+    if (generation === loadGeneration)
+      loading.value = false
+  }
+}
+
+watch(() => props.provider, () => {
+  options.value = undefined
+  void load()
+}, { immediate: true })
+
+watch([model, () => props.active, () => props.provider, options], ([configuration, active], _, onCleanup) => {
+  let cancelled = false
+  preview.value = undefined
+  previewError.value = ''
+  previewing.value = active && !!options.value
+  if (!active || !options.value)
+    return
+
+  const timer = setTimeout(async () => {
+    try {
+      const result = await previewProviderClientProfile(props.provider, configuration)
+      if (!cancelled)
+        preview.value = result
+    }
+    catch (error) {
+      if (!cancelled)
+        previewError.value = errorMessage(error)
+    }
+    finally {
+      if (!cancelled)
+        previewing.value = false
+    }
+  }, 250)
+  onCleanup(() => {
+    cancelled = true
+    clearTimeout(timer)
+  })
+}, { immediate: true })
+</script>
+
+<template>
+  <div class="grid min-w-0 gap-4">
+    <div v-if="allowInherit" class="flex flex-wrap items-center justify-between gap-3">
+      <BaseSegmented
+        v-model="profileSource"
+        :label="`${provider} 客户端身份来源`"
+        class="w-fit"
+        :options="[{ label: '全局配置', value: 'global' }, { label: '独立配置', value: 'independent' }]"
+        :disabled="disabled || loading || !!loadError"
+      />
+      <slot name="source-extra" />
+    </div>
+
+    <div v-if="loadError" role="alert" class="flex flex-wrap items-center justify-between gap-3 text-cp text-cp-error">
+      <span>画像预设加载失败：{{ loadError }}</span>
+      <BaseButton size="sm" :disabled="disabled" @click="load">
+        重试
+      </BaseButton>
+    </div>
+    <p v-else-if="loading" role="status" class="m-0 text-cp text-cp-text-secondary">
+      正在加载画像预设…
+    </p>
+    <template v-else-if="model">
+      <BaseFormItem label="身份预设">
+        <BaseSelect
+          v-model="selectedPreset"
+          class="w-full sm:max-w-md"
+          :options="presetOptions"
+          :disabled="disabled"
+          placeholder="选择 Provider 提供的预设"
+        />
+      </BaseFormItem>
+      <p v-if="!selectedPreset" role="alert" class="m-0 text-cp-sm text-cp-error">
+        当前画像已不在 Provider 的可用预设中，请重新选择
+      </p>
+    </template>
+
+    <div class="grid min-h-24 min-w-0 content-center gap-2 rounded-cp bg-cp-fill-quaternary p-4" aria-live="polite" :aria-busy="previewing">
+      <div v-if="previewing" class="grid gap-2" role="status" aria-label="正在解析客户端画像">
+        <div class="flex h-lh items-center" aria-hidden="true">
+          <BaseSkeleton shape="text" class="w-2/5" />
+        </div>
+        <div class="flex h-lh items-center" aria-hidden="true">
+          <BaseSkeleton shape="text" class="w-4/5" />
+        </div>
+      </div>
+      <p v-else-if="previewError" role="alert" class="m-0 text-cp-sm text-cp-error">
+        {{ previewError }}
+      </p>
+      <template v-else-if="preview">
+        <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+          <strong class="text-cp font-semibold text-cp-text">{{ preview.product }}</strong>
+          <span class="text-cp-sm text-cp-text-secondary">
+            {{ preview.version }}<template v-if="preview.build">
+              · {{ preview.build }}
+            </template>
+          </span>
+          <span v-if="releaseLabel" class="text-cp-xs text-cp-text-tertiary">
+            {{ releaseLabel }}
+          </span>
+        </div>
+        <code class="break-all text-cp-sm text-cp-text">{{ preview.userAgent }}</code>
+        <p class="m-0 text-cp-xs text-cp-text-tertiary">
+          {{ preview.target.osType }} {{ preview.target.osVersion }} · {{ preview.target.arch }} · {{ preview.target.terminal }}
+          <template v-if="preview.verifiedAt">
+            · 核验于 {{ formatDateTime(preview.verifiedAt) }}
+          </template>
+        </p>
+        <dl v-if="preview.attributes.length" class="m-0 flex flex-wrap gap-x-4 gap-y-1 text-cp-xs">
+          <div v-for="attribute in preview.attributes" :key="`${attribute.label}:${attribute.value}`" class="flex min-w-0 gap-1">
+            <dt class="text-cp-text-tertiary">
+              {{ attribute.label }}
+            </dt>
+            <dd class="m-0 truncate text-cp-text-secondary">
+              {{ attribute.value }}
+            </dd>
+          </div>
+        </dl>
+        <p v-if="preview.release?.status === 'failed' && preview.release.error" class="m-0 text-cp-sm text-cp-warning">
+          {{ preview.release.error }}
+        </p>
+      </template>
+      <p v-else class="m-0 text-cp-sm text-cp-text-tertiary">
+        选择预设后显示实际上游画像
+      </p>
+    </div>
+  </div>
+</template>
diff --git a/frontend/src/components/client-profile/ProviderRequestProfilesEditor.vue b/frontend/src/components/client-profile/ProviderRequestProfilesEditor.vue
new file mode 100644
index 000000000..362cb3910
--- /dev/null
+++ b/frontend/src/components/client-profile/ProviderRequestProfilesEditor.vue
@@ -0,0 +1,217 @@
+<script setup lang="ts">
+import type {
+  ClientProfileSelection,
+  ProviderRequestProfile,
+  ProviderRequestProfiles,
+  XaiClientProfileSelection,
+} from '@/api/modules/client-profiles'
+import { BaseButton, BaseSegmented } from '@codex-proxy/ui'
+import { computed, shallowRef, watch } from 'vue'
+import { getClientProfileProviders } from '@/api/modules/client-profiles'
+import { errorMessage } from '@/utils/async'
+import { formatProviderLabel, providerIcon } from '@/utils/providers'
+import ClientProfileEditor from './ClientProfileEditor.vue'
+import ProviderRequestProfileEditor from './ProviderRequestProfileEditor.vue'
+import XaiClientProfileEditor from './XaiClientProfileEditor.vue'
+
+withDefaults(defineProps<{
+  active?: boolean
+  disabled?: boolean
+  allowInherit?: boolean
+}>(), {
+  active: true,
+  disabled: false,
+  allowInherit: false,
+})
+
+const model = defineModel<ProviderRequestProfiles>({ required: true })
+const discoveredProviders = shallowRef<string[]>([])
+const provider = shallowRef('')
+const loading = shallowRef(true)
+const loadError = shallowRef('')
+
+const providerIds = computed(() => [...new Set([
+  ...discoveredProviders.value,
+  ...Object.keys(model.value),
+])])
+
+const providerOptions = computed(() => providerIds.value.map(value => ({
+  value,
+  label: formatProviderLabel(value, value),
+  icon: providerIcon(value),
+})))
+const providerSelectorStyle = computed(() => ({
+  width: `${Math.max(providerOptions.value.length, 1) * 40}px`,
+}))
+const selectedProviderIsOrphaned = computed(() => Boolean(
+  provider.value
+  && !loading.value
+  && !loadError.value
+  && model.value[provider.value] !== undefined
+  && !discoveredProviders.value.includes(provider.value),
+))
+
+const openai = profileModel<ClientProfileSelection>('openai')
+const xai = profileModel<XaiClientProfileSelection>('xai')
+const selectedProfile = computed<ProviderRequestProfile | null>({
+  get: () => provider.value ? model.value[provider.value] ?? null : null,
+  set: value => updateProfile(provider.value, value),
+})
+
+function profileModel<T extends object>(providerId: string) {
+  return computed<T | null>({
+    get: () => (model.value[providerId] as T | undefined) ?? null,
+    set: value => updateProfile(providerId, value as ProviderRequestProfile | null),
+  })
+}
+
+function updateProfile(providerId: string, value: ProviderRequestProfile | null) {
+  if (!providerId)
+    return
+  const profiles = { ...model.value }
+  if (value === null)
+    delete profiles[providerId]
+  else
+    profiles[providerId] = value
+  model.value = profiles
+}
+
+async function loadProviders() {
+  loading.value = true
+  loadError.value = ''
+  try {
+    discoveredProviders.value = (await getClientProfileProviders()).providers
+  }
+  catch (error) {
+    loadError.value = errorMessage(error)
+  }
+  finally {
+    loading.value = false
+  }
+}
+
+watch(providerIds, (providers) => {
+  if (!providers.includes(provider.value))
+    provider.value = providers[0] ?? ''
+}, { immediate: true })
+
+void loadProviders()
+</script>
+
+<template>
+  <div class="grid min-w-0 gap-4">
+    <div v-if="!allowInherit" class="flex flex-wrap items-start justify-between gap-3">
+      <slot name="heading" />
+      <BaseSegmented
+        v-if="providerOptions.length"
+        v-model="provider"
+        class="ml-auto max-w-full shrink-0"
+        label="客户端身份 Provider"
+        :options="providerOptions"
+        :disabled="disabled || loading"
+        :style="providerSelectorStyle"
+        display="icon"
+      />
+      <p v-else class="m-0 text-cp-sm text-cp-text-tertiary" role="status">
+        {{ loading ? '正在加载…' : '暂无可配置 Provider' }}
+      </p>
+    </div>
+    <p v-else-if="!providerOptions.length" class="m-0 text-cp-sm text-cp-text-tertiary" role="status">
+      {{ loading ? '正在加载…' : '暂无可配置 Provider' }}
+    </p>
+
+    <div v-if="loadError" role="alert" class="flex flex-wrap items-center justify-between gap-3 text-cp text-cp-error">
+      <span>Provider 列表加载失败：{{ loadError }}</span>
+      <BaseButton size="sm" :disabled="disabled" @click="loadProviders">
+        重试
+      </BaseButton>
+    </div>
+
+    <div
+      v-if="selectedProviderIsOrphaned"
+      role="status"
+      class="flex flex-wrap items-center justify-between gap-3 rounded-cp bg-cp-warning-container p-4"
+    >
+      <div class="min-w-0">
+        <p class="m-0 text-cp-sm font-semibold text-cp-warning-on-container">
+          当前发布代次未注册此 Provider
+        </p>
+        <p class="mt-1 mb-0 text-cp-xs text-cp-warning-on-container">
+          历史画像会继续保留且不会参与运行
+        </p>
+      </div>
+      <BaseSegmented
+        v-if="allowInherit"
+        v-model="provider"
+        class="max-w-full shrink-0"
+        label="上游身份平台"
+        :options="providerOptions"
+        :disabled="disabled || loading"
+        :style="providerSelectorStyle"
+        display="icon"
+      />
+      <BaseButton variant="destructive" size="sm" :disabled="disabled" @click="updateProfile(provider, null)">
+        移除历史画像
+      </BaseButton>
+    </div>
+    <ClientProfileEditor
+      v-else-if="provider === 'openai'"
+      v-model="openai"
+      :allow-inherit="allowInherit"
+      :active="active"
+      :disabled="disabled"
+    >
+      <template #source-extra>
+        <BaseSegmented
+          v-model="provider"
+          class="max-w-full shrink-0"
+          label="上游身份平台"
+          :options="providerOptions"
+          :disabled="disabled || loading"
+          :style="providerSelectorStyle"
+          display="icon"
+        />
+      </template>
+    </ClientProfileEditor>
+    <XaiClientProfileEditor
+      v-else-if="provider === 'xai'"
+      v-model="xai"
+      :allow-inherit="allowInherit"
+      :active="active"
+      :disabled="disabled"
+    >
+      <template #source-extra>
+        <BaseSegmented
+          v-model="provider"
+          class="max-w-full shrink-0"
+          label="上游身份平台"
+          :options="providerOptions"
+          :disabled="disabled || loading"
+          :style="providerSelectorStyle"
+          display="icon"
+        />
+      </template>
+    </XaiClientProfileEditor>
+    <ProviderRequestProfileEditor
+      v-else-if="provider"
+      :key="provider"
+      v-model="selectedProfile"
+      :provider="provider"
+      :allow-inherit="allowInherit"
+      :active="active"
+      :disabled="disabled"
+    >
+      <template #source-extra>
+        <BaseSegmented
+          v-model="provider"
+          class="max-w-full shrink-0"
+          label="上游身份平台"
+          :options="providerOptions"
+          :disabled="disabled || loading"
+          :style="providerSelectorStyle"
+          display="icon"
+        />
+      </template>
+    </ProviderRequestProfileEditor>
+  </div>
+</template>
diff --git a/frontend/src/components/client-profile/XaiClientProfileEditor.vue b/frontend/src/components/client-profile/XaiClientProfileEditor.vue
index 165a743eb..a9f4b7275 100644
--- a/frontend/src/components/client-profile/XaiClientProfileEditor.vue
+++ b/frontend/src/components/client-profile/XaiClientProfileEditor.vue
@@ -1,12 +1,8 @@
 <script setup lang="ts">
 import type { XaiClientProfilePreview, XaiClientProfileSelection } from '@/api/modules/client-profiles'
+import { BaseButton, BaseFormItem, BaseInput, BaseSegmented, BaseSelect } from '@codex-proxy/ui'
 import { computed, onMounted, shallowRef, watch } from 'vue'
 import { getXaiClientProfileOptions, previewXaiClientProfile } from '@/api/modules/client-profiles'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
 import { errorMessage } from '@/utils/async'
 import ClientProfilePreviewPanel from './ClientProfilePreviewPanel.vue'
 
diff --git a/frontend/src/composables/useAsyncAction.ts b/frontend/src/composables/useAsyncAction.ts
index 03586192a..d03caa472 100644
--- a/frontend/src/composables/useAsyncAction.ts
+++ b/frontend/src/composables/useAsyncAction.ts
@@ -1,7 +1,7 @@
-import { shallowRef } from 'vue'
+import { toast } from '@codex-proxy/ui'
 
+import { shallowRef } from 'vue'
 import { ApiError } from '@/api/request'
-import { toast } from '@/components/base/BaseToast'
 import { errorMessage, withMinimumDuration } from '@/utils/async'
 
 type MaybePromise<T> = T | Promise<T>
diff --git a/frontend/src/composables/useCopyText.ts b/frontend/src/composables/useCopyText.ts
index 1e1938861..7a68de698 100644
--- a/frontend/src/composables/useCopyText.ts
+++ b/frontend/src/composables/useCopyText.ts
@@ -1,6 +1,6 @@
-import { useClipboard } from '@vueuse/core'
+import { toast } from '@codex-proxy/ui'
 
-import { toast } from '@/components/base/BaseToast'
+import { useClipboard } from '@vueuse/core'
 import { errorMessage } from '@/utils/async'
 
 interface CopyTextOptions {
diff --git a/frontend/src/layout/components/AppSidebar.vue b/frontend/src/layout/components/AppSidebar.vue
index ed32ab11c..30e63fdb1 100644
--- a/frontend/src/layout/components/AppSidebar.vue
+++ b/frontend/src/layout/components/AppSidebar.vue
@@ -1,7 +1,12 @@
 <script setup lang="ts">
+import type { PluginManagementView } from '@/api'
+
+import { BaseIconButton, BaseMotionIcon, BaseScrollbar } from '@codex-proxy/ui'
 import {
   ArrowUpCircle,
+  Blocks,
   ChartNoAxesColumn,
+  ChevronDown,
   FolderTree,
   Info,
   KeyRound,
@@ -12,23 +17,24 @@ import {
   Palette,
   PanelLeftClose,
   PanelLeftOpen,
+  PanelsTopLeft,
+  Puzzle,
   Settings,
   Sun,
   Users,
 } from '@lucide/vue'
 import { usePreferredReducedMotion, useTimeoutFn } from '@vueuse/core'
 import { gsap } from 'gsap'
-import { storeToRefs } from 'pinia'
-import { computed, nextTick, onBeforeUnmount, onMounted, ref, shallowRef, useTemplateRef, watch } from 'vue'
-import { useRoute, useRouter } from 'vue-router'
 
+import { storeToRefs } from 'pinia'
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, shallowRef, useId, useTemplateRef, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
 import AppBrandMark from '@/components/AppBrandMark.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseMotionIcon from '@/components/base/BaseMotionIcon.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
 import { useAuthStore } from '@/stores/modules/auth'
+import { usePluginManagementViewsStore } from '@/stores/modules/plugin-management-views'
 import { useSystemUpdateStore } from '@/stores/modules/system-update'
 import { useThemeStore } from '@/stores/modules/theme'
+import { pluginPageLocation, shortPluginInstanceId } from '@/views/plugins/utils/navigation'
 
 const props = withDefaults(
   defineProps<{
@@ -50,12 +56,17 @@ const emit = defineEmits<{
 const route = useRoute()
 const router = useRouter()
 const authStore = useAuthStore()
+const pluginViewsStore = usePluginManagementViewsStore()
 const systemUpdateStore = useSystemUpdateStore()
 const themeStore = useThemeStore()
+const { pageViews: pluginPageViews } = storeToRefs(pluginViewsStore)
 const { version, hasUpdate } = storeToRefs(systemUpdateStore)
 const { effectiveTheme } = storeToRefs(themeStore)
 const { toggleTheme } = themeStore
 const preferredMotion = usePreferredReducedMotion()
+const isCollapsed = computed(() => !props.mobile && Boolean(props.collapsed))
+const pluginMenuId = useId()
+const pluginGroupExpanded = shallowRef(route.path.startsWith('/plugins'))
 
 const navItems = [
   { label: '概览', icon: LayoutDashboard, path: '/' },
@@ -64,9 +75,20 @@ const navItems = [
   { label: '分组管理', icon: FolderTree, path: '/groups' },
   { label: 'API 密钥', icon: KeyRound, path: '/keys' },
   { label: '使用统计', icon: ChartNoAxesColumn, path: '/usage' },
+  { label: '插件', icon: Puzzle, path: '/plugins' },
   { label: '主题设置', icon: Palette, path: '/theme' },
   { label: '系统设置', icon: Settings, path: '/settings' },
 ]
+const pluginNavIndex = navItems.findIndex(item => item.path === '/plugins')
+const pluginMenuVisible = computed(() => pluginGroupExpanded.value && !isCollapsed.value)
+const pluginViewNameCounts = computed(() => pluginPageViews.value.reduce((counts, view) => {
+  const title = view.pages[0]?.title ?? view.name
+  counts.set(title, (counts.get(title) ?? 0) + 1)
+  return counts
+}, new Map<string, number>()))
+const pluginChildrenHeight = computed(() => pluginMenuVisible.value
+  ? (pluginPageViews.value.length + 1) * 44
+  : 0)
 
 function isActive(path: string) {
   if (path === '/')
@@ -79,7 +101,15 @@ const activeNavIndex = computed(() => {
   return Math.max(0, index)
 })
 const activeNavIndicatorStyle = computed(() => ({
-  transform: `translate3d(0, ${activeNavIndex.value * 58}px, 0)`,
+  transform: `translate3d(0, ${activeNavIndex.value * 58 + (activeNavIndex.value > pluginNavIndex ? pluginChildrenHeight.value : 0)}px, 0)`,
+  opacity: isActive('/plugins') && pluginMenuVisible.value ? 0 : 1,
+}))
+const activePluginIndex = computed(() => route.name === 'plugins'
+  ? 0
+  : pluginPageViews.value.findIndex(isPluginViewActive) + 1)
+const activePluginIndicatorStyle = computed(() => ({
+  transform: `translate3d(0, ${activePluginIndex.value * 44}px, 0)`,
+  opacity: isActive('/plugins') && pluginMenuVisible.value ? 1 : 0,
 }))
 const navFeedbackMuted = shallowRef(false)
 const { start: restoreNavFeedback, stop: stopNavFeedbackRestore } = useTimeoutFn(
@@ -102,6 +132,34 @@ function navigate(path: string) {
   emit('navigate')
 }
 
+function togglePluginGroup() {
+  if (isCollapsed.value) {
+    navigate('/plugins')
+    return
+  }
+  pluginGroupExpanded.value = !pluginGroupExpanded.value
+}
+
+function navigatePluginView(view: PluginManagementView) {
+  const page = view.pages[0]
+  if (page)
+    navigate(router.resolve(pluginPageLocation(view, page)).fullPath)
+}
+
+function isPluginViewActive(view: PluginManagementView) {
+  const value = route.params.instanceId
+  const routeInstanceId = Array.isArray(value) ? value[0] : value
+  return route.name === 'plugin-page' && routeInstanceId === view.target.instanceId
+}
+
+function pluginViewLabel(view: PluginManagementView) {
+  const title = view.pages[0]?.title ?? view.name
+  if (pluginViewNameCounts.value.get(title) === 1)
+    return title
+  const duplicateName = pluginPageViews.value.some(item => item !== view && item.name === view.name && item.pages[0]?.title === title)
+  return `${title} · ${duplicateName ? shortPluginInstanceId(view.target.instanceId) : view.name}`
+}
+
 function openSystemUpdate() {
   emit('openSystemUpdate')
 }
@@ -116,7 +174,7 @@ async function handleLogout() {
 const sidebarEl = ref<HTMLElement | null>(null)
 const brandLabelEl = ref<HTMLElement | null>(null)
 const navSignalEl = useTemplateRef<HTMLElement>('navSignal')
-const isCollapsed = computed(() => !props.mobile && Boolean(props.collapsed))
+const pluginNavSignalEls = useTemplateRef<HTMLElement[]>('pluginNavSignal')
 const collapsedSidebarWidth = 88
 const expandedSidebarWidth = 251
 const sidebarWidth = computed(() => (isCollapsed.value ? collapsedSidebarWidth : expandedSidebarWidth))
@@ -232,7 +290,7 @@ function animateSidebarWidth(collapsed: boolean) {
 }
 
 function animateNavSignal() {
-  const signal = navSignalEl.value
+  const signal = isActive('/plugins') && pluginMenuVisible.value ? pluginNavSignalEls.value?.[0] : navSignalEl.value
   if (!signal)
     return
 
@@ -256,6 +314,7 @@ function animateNavSignal() {
 }
 
 onMounted(() => {
+  void pluginViewsStore.ensureLoaded().catch(() => undefined)
   gsap.set(sidebarEl.value, {
     width: sidebarWidth.value,
     flexBasis: sidebarWidth.value,
@@ -296,6 +355,8 @@ watch(
   async (path, previousPath) => {
     if (path === previousPath)
       return
+    if (path.startsWith('/plugins'))
+      pluginGroupExpanded.value = true
     muteNavFeedbackDuringMove()
     await nextTick()
     animateNavSignal()
@@ -305,7 +366,7 @@ watch(
 
 onBeforeUnmount(() => {
   stopNavFeedbackRestore()
-  const targets = [sidebarEl.value, brandLabelEl.value, navSignalEl.value].filter((target): target is HTMLElement =>
+  const targets = [sidebarEl.value, brandLabelEl.value, navSignalEl.value, ...(pluginNavSignalEls.value ?? [])].filter((target): target is HTMLElement =>
     Boolean(target),
   )
   gsap.killTweensOf(targets)
@@ -363,7 +424,7 @@ onBeforeUnmount(() => {
       <div class="px-4">
         <nav class="relative grid gap-3" :class="isCollapsed ? 'mx-auto w-11.5' : 'w-full'" aria-label="主导航">
           <span
-            class="pointer-events-none absolute inset-x-0 top-0 h-11.5 overflow-hidden rounded-cp bg-cp-menu-item-selected-bg transition-transform duration-260 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none"
+            class="pointer-events-none absolute inset-x-0 top-0 h-11.5 overflow-hidden rounded-cp bg-cp-menu-item-selected-bg transition-[transform,opacity] duration-260 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none"
             :style="activeNavIndicatorStyle"
           >
             <span
@@ -371,31 +432,113 @@ onBeforeUnmount(() => {
               class="absolute inset-y-0 left-0 w-2/3 [background:linear-gradient(90deg,transparent,color-mix(in_srgb,var(--cp-color-info)_9%,transparent),transparent)]"
             />
           </span>
-          <button
-            v-for="item in navItems"
-            :key="item.label"
-            type="button"
-            class="relative z-10 inline-flex h-11.5 cursor-pointer items-center rounded-cp border-0 text-sm leading-[1.15] outline-none focus-visible:ring-2 focus-visible:ring-cp-control-outline focus-visible:ring-offset-2 focus-visible:ring-offset-cp-bg-container"
-            :class="[
-              isCollapsed ? 'w-11.5 justify-center' : 'w-full gap-3 px-4',
-              isActive(item.path)
-                ? navFeedbackMuted
-                  ? 'bg-transparent font-bold text-cp-text transition-none'
-                  : 'bg-transparent font-bold text-cp-text transition-colors duration-200'
-                : navFeedbackMuted
-                  ? 'bg-transparent font-semibold text-cp-text-secondary transition-none'
-                  : 'bg-transparent font-semibold text-cp-text-secondary transition-colors duration-200 hover:bg-cp-fill-quaternary hover:text-cp-text',
-            ]"
-            @click="navigate(item.path)"
-          >
-            <component :is="item.icon" class="shrink-0" :size="20" />
-            <span
-              class="sidebar-label overflow-hidden whitespace-nowrap transition-[opacity,transform] duration-200"
-              :class="isCollapsed ? 'pointer-events-none w-0' : 'w-auto'"
+          <template v-for="item in navItems" :key="item.label">
+            <div v-if="item.path === '/plugins'" class="relative z-10 grid min-w-0">
+              <button
+                type="button"
+                class="inline-flex h-11.5 cursor-pointer items-center rounded-cp border-0 bg-transparent text-sm leading-[1.15] outline-none focus-visible:ring-2 focus-visible:ring-cp-control-outline focus-visible:ring-offset-2 focus-visible:ring-offset-cp-bg-container"
+                :class="[
+                  isCollapsed ? 'w-11.5 justify-center' : 'w-full gap-3 px-4',
+                  isActive(item.path)
+                    ? navFeedbackMuted
+                      ? 'font-bold text-cp-text transition-none'
+                      : 'font-bold text-cp-text transition-colors duration-200'
+                    : navFeedbackMuted
+                      ? 'font-semibold text-cp-text-secondary transition-none'
+                      : 'font-semibold text-cp-text-secondary transition-colors duration-200 hover:bg-cp-fill-quaternary hover:text-cp-text',
+                ]"
+                :aria-expanded="isCollapsed ? undefined : pluginGroupExpanded"
+                :aria-controls="isCollapsed ? undefined : pluginMenuId"
+                :aria-label="isCollapsed ? item.label : undefined"
+                :title="isCollapsed ? item.label : undefined"
+                @click="togglePluginGroup"
+              >
+                <component :is="item.icon" class="shrink-0" :size="20" />
+                <span
+                  class="sidebar-label min-w-0 flex-1 overflow-hidden whitespace-nowrap text-left transition-[opacity,transform] duration-200"
+                  :class="isCollapsed ? 'hidden' : 'w-auto'"
+                >
+                  {{ item.label }}
+                </span>
+                <ChevronDown
+                  v-if="!isCollapsed"
+                  class="sidebar-label size-4 shrink-0 transition-transform duration-200 motion-reduce:transition-none"
+                  :class="pluginGroupExpanded ? undefined : '-rotate-90'"
+                />
+              </button>
+
+              <div
+                :id="pluginMenuId"
+                class="grid transition-[grid-template-rows] duration-260 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none"
+                :class="pluginMenuVisible ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'"
+                :inert="!pluginMenuVisible"
+                aria-label="插件导航"
+              >
+                <div class="min-h-0 overflow-hidden">
+                  <div class="relative ml-3 grid gap-1 pt-1 pl-3">
+                    <span
+                      aria-hidden="true"
+                      class="pointer-events-none absolute top-1 right-0 left-3 h-10 overflow-hidden rounded-cp bg-cp-menu-item-selected-bg transition-[transform,opacity] duration-260 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none"
+                      :style="activePluginIndicatorStyle"
+                    >
+                      <span ref="pluginNavSignal" class="absolute inset-y-0 left-0 w-2/3 opacity-0 [background:linear-gradient(90deg,transparent,color-mix(in_srgb,var(--cp-color-info)_9%,transparent),transparent)]" />
+                    </span>
+                    <button
+                      type="button"
+                      class="relative inline-flex h-10 min-w-0 cursor-pointer items-center gap-2 rounded-cp border-0 bg-transparent px-3 text-left text-cp-sm outline-none transition-colors focus-visible:ring-2 focus-visible:ring-cp-control-outline motion-reduce:transition-none"
+                      :class="route.name === 'plugins'
+                        ? 'font-emphasis text-cp-text'
+                        : navFeedbackMuted ? 'font-semibold text-cp-text-secondary' : 'font-semibold text-cp-text-secondary hover:bg-cp-fill-quaternary hover:text-cp-text'"
+                      :aria-current="route.name === 'plugins' ? 'page' : undefined"
+                      @click="navigate('/plugins')"
+                    >
+                      <PanelsTopLeft class="block size-4 shrink-0" />
+                      <span class="sidebar-label truncate leading-none">插件管理</span>
+                    </button>
+                    <button
+                      v-for="view in pluginPageViews"
+                      :key="view.target.instanceId"
+                      type="button"
+                      class="relative inline-flex h-10 min-w-0 cursor-pointer items-center gap-2 rounded-cp border-0 bg-transparent px-3 text-left text-cp-sm outline-none transition-colors focus-visible:ring-2 focus-visible:ring-cp-control-outline motion-reduce:transition-none"
+                      :class="isPluginViewActive(view)
+                        ? 'font-emphasis text-cp-text'
+                        : navFeedbackMuted ? 'font-semibold text-cp-text-secondary' : 'font-semibold text-cp-text-secondary hover:bg-cp-fill-quaternary hover:text-cp-text'"
+                      :aria-current="isPluginViewActive(view) ? 'page' : undefined"
+                      @click="navigatePluginView(view)"
+                    >
+                      <Blocks class="block size-4 shrink-0" />
+                      <span class="sidebar-label truncate leading-none">{{ pluginViewLabel(view) }}</span>
+                    </button>
+                  </div>
+                </div>
+              </div>
+            </div>
+
+            <button
+              v-else
+              type="button"
+              class="relative z-10 inline-flex h-11.5 cursor-pointer items-center rounded-cp border-0 text-sm leading-[1.15] outline-none focus-visible:ring-2 focus-visible:ring-cp-control-outline focus-visible:ring-offset-2 focus-visible:ring-offset-cp-bg-container"
+              :class="[
+                isCollapsed ? 'w-11.5 justify-center' : 'w-full gap-3 px-4',
+                isActive(item.path)
+                  ? navFeedbackMuted
+                    ? 'bg-transparent font-bold text-cp-text transition-none'
+                    : 'bg-transparent font-bold text-cp-text transition-colors duration-200'
+                  : navFeedbackMuted
+                    ? 'bg-transparent font-semibold text-cp-text-secondary transition-none'
+                    : 'bg-transparent font-semibold text-cp-text-secondary transition-colors duration-200 hover:bg-cp-fill-quaternary hover:text-cp-text',
+              ]"
+              @click="navigate(item.path)"
             >
-              {{ item.label }}
-            </span>
-          </button>
+              <component :is="item.icon" class="shrink-0" :size="20" />
+              <span
+                class="sidebar-label overflow-hidden whitespace-nowrap transition-[opacity,transform] duration-200"
+                :class="isCollapsed ? 'pointer-events-none w-0' : 'w-auto'"
+              >
+                {{ item.label }}
+              </span>
+            </button>
+          </template>
         </nav>
       </div>
     </BaseScrollbar>
diff --git a/frontend/src/layout/components/SystemUpdateModal/index.vue b/frontend/src/layout/components/SystemUpdateModal/index.vue
index 78601b932..d91db9524 100644
--- a/frontend/src/layout/components/SystemUpdateModal/index.vue
+++ b/frontend/src/layout/components/SystemUpdateModal/index.vue
@@ -1,5 +1,7 @@
 <script setup lang="ts">
 import type { SystemUpdateDetail } from '@/api'
+import { BaseButton, BaseConfirmModal, BaseEmpty, BaseMarkdown, BaseModal, BaseScrollbar, toast } from '@codex-proxy/ui'
+
 import {
   ArrowUpCircle,
   Circle,
@@ -8,16 +10,8 @@ import {
   RefreshCw,
   Terminal,
 } from '@lucide/vue'
-
 import { storeToRefs } from 'pinia'
 import { computed, nextTick, shallowRef, useTemplateRef, watch } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseConfirmModal from '@/components/base/BaseConfirmModal.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseMarkdown from '@/components/base/BaseMarkdown/index.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
-import { toast } from '@/components/base/BaseToast'
 import { normalizeSystemVersion, useSystemUpdateStore } from '@/stores/modules/system-update'
 import { errorMessage } from '@/utils/async'
 import { formatTime } from '@/utils/date'
diff --git a/frontend/src/layout/index.vue b/frontend/src/layout/index.vue
index d174e97da..5c80e258f 100644
--- a/frontend/src/layout/index.vue
+++ b/frontend/src/layout/index.vue
@@ -1,10 +1,10 @@
 <script setup lang="ts">
+import { BaseScrollbar } from '@codex-proxy/ui'
 import { storeToRefs } from 'pinia'
 import { nextTick, onBeforeUnmount, onMounted, ref, shallowRef, watch } from 'vue'
-import { RouterView, useRoute } from 'vue-router'
 
+import { RouterView, useRoute } from 'vue-router'
 import AppAboutModal from '@/components/AppAboutModal.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
 import { useSystemUpdateStore } from '@/stores/modules/system-update'
 import { useUiStore } from '@/stores/modules/ui'
 
diff --git a/frontend/src/main.ts b/frontend/src/main.ts
index ba84f3387..12343f747 100644
--- a/frontend/src/main.ts
+++ b/frontend/src/main.ts
@@ -8,6 +8,7 @@ import { pinia } from './stores'
 import { useThemeStore } from './stores/modules/theme'
 import '@fontsource-variable/inter'
 import '@fontsource-variable/jetbrains-mono'
+import '@codex-proxy/ui/styles.css'
 
 import './styles/index.css'
 
diff --git a/frontend/src/router/routes.ts b/frontend/src/router/routes.ts
index 88fd41324..53bcb2cec 100644
--- a/frontend/src/router/routes.ts
+++ b/frontend/src/router/routes.ts
@@ -45,6 +45,22 @@ export const routes: RouteRecordRaw[] = [
         name: 'usage',
         component: () => import('@/views/usage/index.vue'),
       },
+      {
+        path: 'plugins',
+        component: () => import('@/views/plugins/index.vue'),
+        children: [
+          {
+            path: '',
+            name: 'plugins',
+            component: () => import('@/views/plugins/components/PluginManagement.vue'),
+          },
+          {
+            path: ':instanceId/:pageId',
+            name: 'plugin-page',
+            component: () => import('@/views/plugins/components/PluginPage.vue'),
+          },
+        ],
+      },
       {
         path: 'theme',
         name: 'theme',
@@ -52,28 +68,33 @@ export const routes: RouteRecordRaw[] = [
       },
       {
         path: 'settings',
-        name: 'settings',
-        component: () => import('@/views/settings/index.vue'),
-      },
-      {
-        path: 'settings/upstream',
-        name: 'settings-upstream',
-        component: () => import('@/views/settings/index.vue'),
-      },
-      {
-        path: 'settings/access',
-        name: 'settings-access',
-        component: () => import('@/views/settings/index.vue'),
-      },
-      {
-        path: 'settings/backup',
-        name: 'settings-backup',
-        component: () => import('@/views/settings/index.vue'),
-      },
-      {
-        path: 'settings/pricing',
-        name: 'settings-pricing',
-        component: () => import('@/views/settings/index.vue'),
+        children: [
+          {
+            path: '',
+            name: 'settings',
+            component: () => import('@/views/settings/index.vue'),
+          },
+          {
+            path: 'upstream',
+            name: 'settings-upstream',
+            component: () => import('@/views/settings/index.vue'),
+          },
+          {
+            path: 'access',
+            name: 'settings-access',
+            component: () => import('@/views/settings/index.vue'),
+          },
+          {
+            path: 'backup',
+            name: 'settings-backup',
+            component: () => import('@/views/settings/index.vue'),
+          },
+          {
+            path: 'pricing',
+            name: 'settings-pricing',
+            component: () => import('@/views/settings/index.vue'),
+          },
+        ],
       },
     ],
   },
diff --git a/frontend/src/stores/modules/plugin-management-views.ts b/frontend/src/stores/modules/plugin-management-views.ts
new file mode 100644
index 000000000..5c7bf061a
--- /dev/null
+++ b/frontend/src/stores/modules/plugin-management-views.ts
@@ -0,0 +1,91 @@
+import type { PluginManagementView } from '@/api'
+
+import { acceptHMRUpdate, defineStore } from 'pinia'
+import { computed, shallowRef, watch } from 'vue'
+import { getPluginManagementViews } from '@/api'
+import { ApiError } from '@/api/request'
+import { useAuthStore } from '@/stores/modules/auth'
+import { errorMessage } from '@/utils/async'
+
+export const usePluginManagementViewsStore = defineStore('plugin-management-views', () => {
+  const authStore = useAuthStore()
+  const views = shallowRef<PluginManagementView[]>([])
+  const loading = shallowRef(false)
+  const loaded = shallowRef(false)
+  const loadError = shallowRef('')
+  const pageViews = computed(() => views.value.filter(view => view.pages.length > 0))
+
+  let controller: AbortController | undefined
+  let pending: Promise<PluginManagementView[]> | undefined
+
+  function reset() {
+    controller?.abort()
+    controller = undefined
+    pending = undefined
+    views.value = []
+    loading.value = false
+    loaded.value = false
+    loadError.value = ''
+  }
+
+  function refresh(silent = true) {
+    controller?.abort()
+    const current = new AbortController()
+    controller = current
+    loading.value = true
+    loadError.value = ''
+
+    const request = getPluginManagementViews({ signal: current.signal, silent })
+      .then((items) => {
+        if (controller === current) {
+          views.value = items
+          loaded.value = true
+        }
+        return items
+      })
+      .catch((error: unknown) => {
+        if (controller === current && error instanceof ApiError && (error.status === 401 || error.status === 403)) {
+          views.value = []
+          loaded.value = false
+        }
+        if (controller === current && !(error instanceof ApiError && error.kind === 'cancelled'))
+          loadError.value = errorMessage(error)
+        throw error
+      })
+      .finally(() => {
+        if (controller === current) {
+          controller = undefined
+          pending = undefined
+          loading.value = false
+        }
+      })
+
+    pending = request
+    return request
+  }
+
+  function ensureLoaded() {
+    if (loaded.value)
+      return Promise.resolve(views.value)
+    return pending ?? refresh()
+  }
+
+  watch(() => authStore.session, (session, previous) => {
+    if (session !== previous)
+      reset()
+  })
+
+  return {
+    views,
+    pageViews,
+    loading,
+    loaded,
+    loadError,
+    refresh,
+    ensureLoaded,
+    reset,
+  }
+})
+
+if (import.meta.hot)
+  import.meta.hot.accept(acceptHMRUpdate(usePluginManagementViewsStore, import.meta.hot))
diff --git a/frontend/src/stores/modules/theme.ts b/frontend/src/stores/modules/theme.ts
index fc4029c3d..420d8ecdc 100644
--- a/frontend/src/stores/modules/theme.ts
+++ b/frontend/src/stores/modules/theme.ts
@@ -5,12 +5,9 @@ import type {
   ThemeColorId,
   ThemeCustomization,
   ThemeMode,
-} from '@/theme'
-
-import { usePreferredDark, usePreferredReducedMotion, useTimeoutFn } from '@vueuse/core'
-import { defineStore } from 'pinia'
-import { computed, ref, shallowRef, watch } from 'vue'
+} from '@codex-proxy/ui/theme'
 
+import { normalizeHexColor } from '@codex-proxy/ui'
 import {
   applyResolvedTheme,
   DEFAULT_CUSTOM_THEME_COLOR,
@@ -21,8 +18,11 @@ import {
   normalizeThemeCustomization,
   resolveTheme,
   resolveThemeName,
-} from '@/theme'
-import { normalizeHexColor } from '@/utils/color'
+} from '@codex-proxy/ui/theme'
+import { usePreferredDark, usePreferredReducedMotion, useTimeoutFn } from '@vueuse/core'
+
+import { defineStore } from 'pinia'
+import { computed, ref, shallowRef, watch } from 'vue'
 
 interface ThemeTransitionOrigin {
   x: number
diff --git a/frontend/src/styles/base.css b/frontend/src/styles/base.css
deleted file mode 100644
index c7054c737..000000000
--- a/frontend/src/styles/base.css
+++ /dev/null
@@ -1,105 +0,0 @@
-@layer base {
-  html {
-    background: var(--cp-color-bg-layout, #f6f8fb);
-    color: var(--cp-color-text, #0e1726);
-    font-family: var(--font-sans);
-    font-synthesis: none;
-    text-rendering: optimizeLegibility;
-    -webkit-font-smoothing: antialiased;
-    -moz-osx-font-smoothing: grayscale;
-  }
-
-  body {
-    background: var(--cp-color-bg-layout, #f6f8fb);
-    font-size: var(--cp-font-size, 13px);
-  }
-
-  /* 主题作用域同时驱动 Tailwind 数值间距，保证预览草稿与已保存主题使用同一密度算法。 */
-  [data-theme] {
-    --spacing: var(--cp-size-unit, 4px);
-  }
-
-  [data-theme]:not(html) {
-    font-size: var(--cp-font-size, 13px);
-  }
-
-  html.theme-fallback-transition,
-  html.theme-fallback-transition body {
-    transition:
-      background-color 180ms cubic-bezier(0.2, 0, 0, 1),
-      color 180ms cubic-bezier(0.2, 0, 0, 1);
-  }
-
-  ::view-transition-old(root),
-  ::view-transition-new(root) {
-    animation: none;
-    mix-blend-mode: normal;
-  }
-
-  ::view-transition-old(root) {
-    z-index: 1;
-  }
-
-  ::view-transition-new(root) {
-    z-index: 2;
-  }
-
-  html.theme-view-transition-shrink::view-transition-old(root) {
-    z-index: 2;
-  }
-
-  html.theme-view-transition-shrink::view-transition-new(root) {
-    z-index: 1;
-  }
-
-  button:not(:disabled) {
-    cursor: pointer;
-  }
-
-  button:disabled {
-    cursor: not-allowed;
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    html.theme-fallback-transition,
-    html.theme-fallback-transition body {
-      transition-duration: 0ms;
-    }
-
-    ::view-transition-old(root),
-    ::view-transition-new(root) {
-      animation-duration: 0ms;
-    }
-  }
-}
-
-@utility cp-scrollbar {
-  scrollbar-color: var(--cp-scrollbar-thumb-bg) transparent;
-  scrollbar-width: thin;
-
-  &::-webkit-scrollbar {
-    width: 10px;
-    height: 10px;
-  }
-
-  &::-webkit-scrollbar-track {
-    background: transparent;
-  }
-
-  &::-webkit-scrollbar-thumb {
-    background: var(--cp-scrollbar-thumb-bg);
-    border: 3px solid transparent;
-    border-radius: 999px;
-    background-clip: content-box;
-  }
-
-  &::-webkit-scrollbar-thumb:hover {
-    background: var(--cp-scrollbar-thumb-hover-bg);
-    border: 3px solid transparent;
-    background-clip: content-box;
-  }
-
-  &::-webkit-scrollbar-corner {
-    background: transparent;
-  }
-}
diff --git a/frontend/src/styles/index.css b/frontend/src/styles/index.css
index 706a3d06a..67e3be773 100644
--- a/frontend/src/styles/index.css
+++ b/frontend/src/styles/index.css
@@ -1,210 +1,3 @@
-@import 'tailwindcss';
-@import './tokens.css';
-@import './base.css';
-
-@theme inline {
-  /* 基础 */
-  --font-sans:
-    'Inter Variable', Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
-  --font-mono: 'JetBrains Mono Variable', 'JetBrains Mono', 'SFMono-Regular', Consolas, 'Liberation Mono', monospace;
-  --font-weight-emphasis: 650;
-  --font-weight-heavy: 760;
-  --animate-cp-skeleton: cp-skeleton-breathe 2.8s cubic-bezier(0.37, 0, 0.63, 1) infinite;
-
-  /* 排版 */
-  --text-cp-xs: var(--cp-font-size-xs);
-  --text-cp-sm: var(--cp-font-size-sm);
-  --text-cp: var(--cp-font-size);
-  --text-cp-lg: var(--cp-font-size-lg);
-  --text-cp-xl: var(--cp-font-size-xl);
-
-  /* 颜色 · 基元 */
-  --color-cp-white: var(--cp-color-white);
-  --color-cp-transparent: var(--cp-color-transparent);
-
-  /* 颜色 · 表面 */
-  --color-cp-bg-layout: var(--cp-color-bg-layout);
-  --color-cp-bg-container: var(--cp-color-bg-container);
-  --color-cp-bg-elevated: var(--cp-color-bg-elevated);
-  --color-cp-bg-spotlight: var(--cp-color-bg-spotlight);
-  --color-cp-bg-mask: var(--cp-color-bg-mask);
-  --color-cp-bg-text-hover: var(--cp-color-bg-text-hover);
-  --color-cp-bg-text-active: var(--cp-color-bg-text-active);
-  --color-cp-bg-container-disabled: var(--cp-color-bg-container-disabled);
-  --color-cp-fill-secondary: var(--cp-color-fill-secondary);
-  --color-cp-fill-tertiary: var(--cp-color-fill-tertiary);
-  --color-cp-fill-quaternary: var(--cp-color-fill-quaternary);
-  --color-cp-fill-alter: var(--cp-color-fill-alter);
-  --color-cp-border: var(--cp-color-border);
-  --color-cp-border-secondary: var(--cp-color-border-secondary);
-  --color-cp-split: var(--cp-color-split);
-  --color-cp-text: var(--cp-color-text);
-  --color-cp-text-heading: var(--cp-color-text-heading);
-  --color-cp-text-secondary: var(--cp-color-text-secondary);
-  --color-cp-text-tertiary: var(--cp-color-text-tertiary);
-  --color-cp-text-quaternary: var(--cp-color-text-quaternary);
-  --color-cp-text-disabled: var(--cp-color-text-disabled);
-  --color-cp-text-light-solid: var(--cp-color-text-light-solid);
-
-  /* 颜色 · 主色与链接 */
-  --color-cp-primary-container: var(--cp-color-primary-container);
-  --color-cp-primary-container-hover: var(--cp-color-primary-container-hover);
-  --color-cp-primary-border: var(--cp-color-primary-border);
-  --color-cp-primary-border-hover: var(--cp-color-primary-border-hover);
-  --color-cp-primary-hover: var(--cp-color-primary-hover);
-  --color-cp-primary: var(--cp-color-primary);
-  --color-cp-primary-active: var(--cp-color-primary-active);
-  --color-cp-primary-text-hover: var(--cp-color-primary-text-hover);
-  --color-cp-primary-text: var(--cp-color-primary-text);
-  --color-cp-primary-on-container: var(--cp-color-primary-on-container);
-  --color-cp-primary-text-active: var(--cp-color-primary-text-active);
-  --color-cp-link: var(--cp-color-link);
-  --color-cp-link-hover: var(--cp-color-link-hover);
-  --color-cp-link-active: var(--cp-color-link-active);
-
-  /* 颜色 · 语义 */
-  --color-cp-info-container: var(--cp-color-info-container);
-  --color-cp-info-container-hover: var(--cp-color-info-container-hover);
-  --color-cp-info-container-active: var(--cp-color-info-container-active);
-  --color-cp-info-border: var(--cp-color-info-border);
-  --color-cp-info-border-hover: var(--cp-color-info-border-hover);
-  --color-cp-info-hover: var(--cp-color-info-hover);
-  --color-cp-info: var(--cp-color-info);
-  --color-cp-info-active: var(--cp-color-info-active);
-  --color-cp-info-text-hover: var(--cp-color-info-text-hover);
-  --color-cp-info-text: var(--cp-color-info-text);
-  --color-cp-info-on-container: var(--cp-color-info-on-container);
-  --color-cp-info-text-active: var(--cp-color-info-text-active);
-  --color-cp-success-container: var(--cp-color-success-container);
-  --color-cp-success-container-hover: var(--cp-color-success-container-hover);
-  --color-cp-success-container-active: var(--cp-color-success-container-active);
-  --color-cp-success-border: var(--cp-color-success-border);
-  --color-cp-success-border-hover: var(--cp-color-success-border-hover);
-  --color-cp-success-hover: var(--cp-color-success-hover);
-  --color-cp-success: var(--cp-color-success);
-  --color-cp-success-active: var(--cp-color-success-active);
-  --color-cp-success-text-hover: var(--cp-color-success-text-hover);
-  --color-cp-success-text: var(--cp-color-success-text);
-  --color-cp-success-on-container: var(--cp-color-success-on-container);
-  --color-cp-success-text-active: var(--cp-color-success-text-active);
-  --color-cp-warning-container: var(--cp-color-warning-container);
-  --color-cp-warning-container-hover: var(--cp-color-warning-container-hover);
-  --color-cp-warning-container-active: var(--cp-color-warning-container-active);
-  --color-cp-warning-border: var(--cp-color-warning-border);
-  --color-cp-warning-border-hover: var(--cp-color-warning-border-hover);
-  --color-cp-warning-hover: var(--cp-color-warning-hover);
-  --color-cp-warning: var(--cp-color-warning);
-  --color-cp-warning-active: var(--cp-color-warning-active);
-  --color-cp-warning-text-hover: var(--cp-color-warning-text-hover);
-  --color-cp-warning-text: var(--cp-color-warning-text);
-  --color-cp-warning-on-container: var(--cp-color-warning-on-container);
-  --color-cp-warning-text-active: var(--cp-color-warning-text-active);
-  --color-cp-error-container: var(--cp-color-error-container);
-  --color-cp-error-container-hover: var(--cp-color-error-container-hover);
-  --color-cp-error-container-active: var(--cp-color-error-container-active);
-  --color-cp-error-border: var(--cp-color-error-border);
-  --color-cp-error-border-hover: var(--cp-color-error-border-hover);
-  --color-cp-error-hover: var(--cp-color-error-hover);
-  --color-cp-error: var(--cp-color-error);
-  --color-cp-error-active: var(--cp-color-error-active);
-  --color-cp-error-text-hover: var(--cp-color-error-text-hover);
-  --color-cp-error-text: var(--cp-color-error-text);
-  --color-cp-error-on-container: var(--cp-color-error-on-container);
-  --color-cp-error-text-active: var(--cp-color-error-text-active);
-
-  /* 颜色 · 预设（色系按字母排序，角色顺序固定） */
-  --color-cp-blue-container: var(--cp-color-blue-container);
-  --color-cp-blue-container-strong: var(--cp-color-blue-container-strong);
-  --color-cp-blue-border: var(--cp-color-blue-border);
-  --color-cp-blue-solid: var(--cp-color-blue-solid);
-  --color-cp-blue-text: var(--cp-color-blue-text);
-  --color-cp-blue-on-container: var(--cp-color-blue-on-container);
-  --color-cp-cyan-container: var(--cp-color-cyan-container);
-  --color-cp-cyan-container-strong: var(--cp-color-cyan-container-strong);
-  --color-cp-cyan-border: var(--cp-color-cyan-border);
-  --color-cp-cyan-solid: var(--cp-color-cyan-solid);
-  --color-cp-cyan-text: var(--cp-color-cyan-text);
-  --color-cp-cyan-on-container: var(--cp-color-cyan-on-container);
-  --color-cp-green-container: var(--cp-color-green-container);
-  --color-cp-green-container-strong: var(--cp-color-green-container-strong);
-  --color-cp-green-border: var(--cp-color-green-border);
-  --color-cp-green-solid: var(--cp-color-green-solid);
-  --color-cp-green-text: var(--cp-color-green-text);
-  --color-cp-green-on-container: var(--cp-color-green-on-container);
-  --color-cp-orange-container: var(--cp-color-orange-container);
-  --color-cp-orange-container-strong: var(--cp-color-orange-container-strong);
-  --color-cp-orange-border: var(--cp-color-orange-border);
-  --color-cp-orange-solid: var(--cp-color-orange-solid);
-  --color-cp-orange-text: var(--cp-color-orange-text);
-  --color-cp-orange-on-container: var(--cp-color-orange-on-container);
-  --color-cp-purple-container: var(--cp-color-purple-container);
-  --color-cp-purple-container-strong: var(--cp-color-purple-container-strong);
-  --color-cp-purple-border: var(--cp-color-purple-border);
-  --color-cp-purple-solid: var(--cp-color-purple-solid);
-  --color-cp-purple-text: var(--cp-color-purple-text);
-  --color-cp-purple-on-container: var(--cp-color-purple-on-container);
-  --color-cp-red-container: var(--cp-color-red-container);
-  --color-cp-red-container-strong: var(--cp-color-red-container-strong);
-  --color-cp-red-border: var(--cp-color-red-border);
-  --color-cp-red-solid: var(--cp-color-red-solid);
-  --color-cp-red-text: var(--cp-color-red-text);
-  --color-cp-red-on-container: var(--cp-color-red-on-container);
-
-  /* 颜色 · 数据 */
-  --color-cp-activity-level-0: var(--cp-activity-level-0);
-  --color-cp-activity-level-1: var(--cp-activity-level-1);
-  --color-cp-activity-level-2: var(--cp-activity-level-2);
-  --color-cp-activity-level-3: var(--cp-activity-level-3);
-  --color-cp-activity-level-4: var(--cp-activity-level-4);
-
-  /* 颜色 · 组件 */
-  --color-cp-button-secondary-bg: var(--cp-button-secondary-bg);
-  --color-cp-button-secondary-hover-bg: var(--cp-button-secondary-hover-bg);
-  --color-cp-button-secondary-active-bg: var(--cp-button-secondary-active-bg);
-  --color-cp-icon-button-secondary-bg: var(--cp-icon-button-secondary-bg);
-  --color-cp-icon-button-secondary-hover-bg: var(--cp-icon-button-secondary-hover-bg);
-  --color-cp-icon-button-secondary-active-bg: var(--cp-icon-button-secondary-active-bg);
-  --color-cp-control-item-bg-active: var(--cp-control-item-bg-active);
-  --color-cp-control-item-bg-active-hover: var(--cp-control-item-bg-active-hover);
-  --color-cp-control-outline: var(--cp-control-outline);
-  --color-cp-menu-item-selected-bg: var(--cp-menu-item-selected-bg);
-  --color-cp-modal-bg: var(--cp-modal-bg);
-  --color-cp-popover-header-bg: var(--cp-popover-header-bg);
-  --color-cp-progress-remaining: var(--cp-progress-remaining-color);
-
-  /* 圆角 */
-  --radius-cp-sm: var(--cp-border-radius-sm);
-  --radius-cp: var(--cp-border-radius);
-  --radius-cp-lg: var(--cp-border-radius-lg);
-  --radius-cp-card: var(--cp-card-border-radius);
-
-  /* 阴影 */
-  --shadow-cp: var(--cp-box-shadow);
-  --shadow-cp-secondary: var(--cp-box-shadow-secondary);
-  --shadow-cp-tertiary: var(--cp-box-shadow-tertiary);
-  --shadow-cp-card: var(--cp-card-shadow);
-  --shadow-cp-input: var(--cp-input-shadow);
-  --shadow-cp-input-hover: var(--cp-input-hover-shadow);
-  --shadow-cp-input-active: var(--cp-input-active-shadow);
-  --shadow-cp-input-error-active: var(--cp-input-error-active-shadow);
-  --shadow-cp-layout-sider: var(--cp-layout-sider-shadow);
-
-  /* 间距与尺寸 */
-  --spacing-cp-control-sm: var(--cp-control-height-sm);
-  --spacing-cp-control: var(--cp-control-height);
-  --spacing-cp-control-lg: var(--cp-control-height-lg);
-  --spacing-cp-size-step: var(--cp-size-step);
-  --spacing-cp-table-row: var(--cp-table-row-height);
-  --spacing-cp-table-row-sm: var(--cp-table-row-height-sm);
-}
-
-@keyframes cp-skeleton-breathe {
-  0%,
-  100% {
-    background-color: var(--cp-color-fill-tertiary);
-  }
-
-  50% {
-    background-color: var(--cp-color-fill-secondary);
-  }
-}
+@import 'tailwindcss/theme.css' layer(theme);
+@import '@codex-proxy/ui/tailwind.css';
+@import 'tailwindcss/utilities.css' layer(utilities);
diff --git a/frontend/src/styles/tokens.css b/frontend/src/styles/tokens.css
deleted file mode 100644
index 6a00ce428..000000000
--- a/frontend/src/styles/tokens.css
+++ /dev/null
@@ -1,13 +0,0 @@
-/* 主题无关的颜色基元；皮肤 Token 由主题 Store 在 Vue 挂载前生成。 */
-:root {
-  --cp-color-white: #ffffff;
-  --cp-color-transparent: #ffffff00;
-}
-
-[data-theme='light'] {
-  color-scheme: light;
-}
-
-[data-theme='dark'] {
-  color-scheme: dark;
-}
diff --git a/frontend/src/theme/core/color.ts b/frontend/src/theme/core/color.ts
deleted file mode 100644
index 3ad16b1d7..000000000
--- a/frontend/src/theme/core/color.ts
+++ /dev/null
@@ -1,183 +0,0 @@
-import type {
-  ColorToneOptions,
-  RgbColor,
-  ThemeName,
-} from '../types'
-import { generate } from '@ant-design/colors'
-import { FastColor } from '@ant-design/fast-color'
-import { normalizeHexColor } from '../../utils/color'
-import {
-  BLACK,
-  DEFAULT_CUSTOM_THEME_COLOR,
-  DEFAULT_DIMENSIONS,
-  WHITE,
-} from './constants'
-
-const MAX_RGB_DISTANCE = Math.sqrt(3) * 255
-
-export function generateColorPalette(
-  seed: string,
-  theme: ThemeName,
-  containerBg?: string,
-): string[] {
-  return generate(seed, theme === 'dark'
-    ? { theme: 'dark', ...(containerBg ? { backgroundColor: containerBg } : {}) }
-    : undefined)
-    .map(color => normalizeHexColor(color) ?? seed)
-}
-
-/** 同一个文字角色可能出现在多个表面或交互状态，按最弱的一组对比度校正。 */
-export function ensureContrast(color: string, background: string | readonly string[], target: number): string {
-  const backgrounds = typeof background === 'string' ? [background] : background
-  const minimumContrast = (candidate: string): number =>
-    Math.min(...backgrounds.map(value => contrastRatio(candidate, value)))
-  if (minimumContrast(color) >= target)
-    return normalizeHexColor(color) ?? color
-
-  let bestColor = color
-  let bestRatio = minimumContrast(color)
-
-  for (let step = 1; step <= 100; step += 1) {
-    const amount = step / 100
-    for (const direction of [BLACK, WHITE]) {
-      const candidate = mix(color, direction, amount)
-      const ratio = minimumContrast(candidate)
-      if (ratio > bestRatio) {
-        bestColor = candidate
-        bestRatio = ratio
-      }
-      if (ratio >= target)
-        return candidate
-    }
-  }
-
-  return bestColor
-}
-
-export function ensureLightness(color: string, minimum: number): string {
-  const normalized = normalizeHexColor(color) ?? DEFAULT_CUSTOM_THEME_COLOR
-  const hsl = new FastColor(normalized).toHsl()
-  const lightness = Math.min(1, Math.max(0, minimum))
-  if (hsl.l >= lightness)
-    return normalized
-
-  return new FastColor({ ...hsl, l: lightness })
-    .toHexString()
-    .toUpperCase()
-}
-
-/** 将透明填充合成为真实表面色，再用于固定单元格或文字对比度计算。 */
-export function compositeOnBackground(fill: string, background: string): string {
-  return new FastColor(fill).onBackground(background).toHexString().toUpperCase()
-}
-
-export function mix(first: string, second: string, secondWeight: number): string {
-  const from = hexToRgb(first)
-  const to = hexToRgb(second)
-  const weight = Math.min(1, Math.max(0, secondWeight))
-  return rgbToHex({
-    red: from.red + (to.red - from.red) * weight,
-    green: from.green + (to.green - from.green) * weight,
-    blue: from.blue + (to.blue - from.blue) * weight,
-  })
-}
-
-/** RGB 空间的归一化颜色距离，用于在基准主题与带色温主题间连续过渡。 */
-export function relativeColorDistance(first: string, second: string): number {
-  const from = hexToRgb(first)
-  const to = hexToRgb(second)
-  return Math.hypot(
-    from.red - to.red,
-    from.green - to.green,
-    from.blue - to.blue,
-  ) / MAX_RGB_DISTANCE
-}
-
-/** 以背景明度和前景色相生成颜色层级，避免 RGB 混合过早丢失色相。 */
-export function mixColorTone(
-  background: string,
-  foreground: string,
-  foregroundWeight: number,
-  options: ColorToneOptions = {},
-): string {
-  const backgroundHsl = new FastColor(background).toHsl()
-  const foregroundHsl = new FastColor(foreground).toHsl()
-  const weight = Math.min(1, Math.max(0, foregroundWeight))
-  const hueWeight = Math.min(1, Math.max(0, options.hueWeight ?? 1))
-  const hue = backgroundHsl.s === 0
-    ? foregroundHsl.h
-    : mixHue(backgroundHsl.h, foregroundHsl.h, hueWeight)
-  const saturation = Math.min(
-    1,
-    foregroundHsl.s * Math.max(0, options.saturationScale ?? 1),
-    Math.max(0, options.saturationLimit ?? 1),
-  )
-  const lightness = backgroundHsl.l
-    + (foregroundHsl.l - backgroundHsl.l) * weight
-
-  return new FastColor({ h: hue, s: saturation, l: lightness })
-    .toHexString()
-    .toUpperCase()
-}
-
-function mixHue(first: number, second: number, secondWeight: number): number {
-  const difference = ((second - first + 540) % 360) - 180
-  return (first + difference * secondWeight + 360) % 360
-}
-
-export function withAlpha(color: string, alpha: number): string {
-  const normalized = normalizeHexColor(color) ?? DEFAULT_CUSTOM_THEME_COLOR
-  const alphaHex = Math.round(Math.min(1, Math.max(0, alpha)) * 255)
-    .toString(16)
-    .padStart(2, '0')
-    .toUpperCase()
-  return `${normalized}${alphaHex}`
-}
-
-export function scaleShadowAlpha(shadow: string, strength: number): string {
-  if (strength === DEFAULT_DIMENSIONS.shadowStrength)
-    return shadow
-  if (strength <= 0)
-    return 'none'
-
-  const scale = strength / DEFAULT_DIMENSIONS.shadowStrength
-  return shadow.replace(/#([\dA-F]{6})([\dA-F]{2})/gi, (_match, color: string, alpha: string) => {
-    const scaledAlpha = Math.min(255, Math.round(Number.parseInt(alpha, 16) * scale))
-      .toString(16)
-      .padStart(2, '0')
-      .toUpperCase()
-    return `#${color.toUpperCase()}${scaledAlpha}`
-  })
-}
-
-function contrastRatio(first: string, second: string): number {
-  const firstLuminance = relativeLuminance(hexToRgb(first))
-  const secondLuminance = relativeLuminance(hexToRgb(second))
-  const lightest = Math.max(firstLuminance, secondLuminance)
-  const darkest = Math.min(firstLuminance, secondLuminance)
-  return (lightest + 0.05) / (darkest + 0.05)
-}
-
-function relativeLuminance(color: RgbColor): number {
-  const channels = [color.red, color.green, color.blue].map((channel) => {
-    const value = channel / 255
-    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4
-  })
-  return channels[0]! * 0.2126 + channels[1]! * 0.7152 + channels[2]! * 0.0722
-}
-
-function hexToRgb(value: string): RgbColor {
-  const normalized = normalizeHexColor(value) ?? DEFAULT_CUSTOM_THEME_COLOR
-  return {
-    red: Number.parseInt(normalized.slice(1, 3), 16),
-    green: Number.parseInt(normalized.slice(3, 5), 16),
-    blue: Number.parseInt(normalized.slice(5, 7), 16),
-  }
-}
-
-function rgbToHex(color: RgbColor): string {
-  const value = [color.red, color.green, color.blue]
-    .map(channel => Math.round(Math.min(255, Math.max(0, channel))).toString(16).padStart(2, '0'))
-    .join('')
-  return `#${value}`.toUpperCase()
-}
diff --git a/frontend/src/theme/core/constants.ts b/frontend/src/theme/core/constants.ts
deleted file mode 100644
index 0fc34b5e5..000000000
--- a/frontend/src/theme/core/constants.ts
+++ /dev/null
@@ -1,180 +0,0 @@
-import type {
-  ThemeColorPreset,
-  ThemeColorPresetId,
-  ThemeCustomization,
-  ThemeMode,
-  ThemePresetColorName,
-  ThemeTokenName,
-} from '../types'
-import { presetPrimaryColors } from '@ant-design/colors'
-
-export const DEFAULT_THEME_MODE: ThemeMode = 'system'
-export const DEFAULT_THEME_COLOR: ThemeColorPresetId = 'relay-blue'
-export const DEFAULT_CUSTOM_THEME_COLOR = '#5983F4'
-export const DEFAULT_THEME_CUSTOMIZATION: ThemeCustomization = {}
-
-export const DEFAULT_SEED_COLORS = {
-  colorSuccess: '#12B981',
-  colorWarning: '#F59E0B',
-  colorError: '#EF4444',
-  colorInfo: DEFAULT_CUSTOM_THEME_COLOR,
-} as const
-
-export const PRESET_COLOR_SEEDS = {
-  blue: presetPrimaryColors.blue,
-  cyan: presetPrimaryColors.cyan,
-  green: presetPrimaryColors.green,
-  orange: presetPrimaryColors.orange,
-  purple: presetPrimaryColors.purple,
-  red: presetPrimaryColors.red,
-} as const satisfies Record<ThemePresetColorName, string>
-
-export const DEFAULT_DIMENSIONS = {
-  fontSize: 13,
-  sizeUnit: 4,
-  sizeStep: 4,
-  controlHeight: 38,
-  tableRowHeight: 60,
-  borderRadius: 8,
-  cardBorderRadius: 18,
-  shadowStrength: 100,
-} as const
-
-export const THEME_COLOR_PRESETS: readonly ThemeColorPreset[] = [
-  {
-    id: 'relay-blue',
-    label: '中继蓝',
-    description: '石墨表面上的清晰交互信号',
-    seed: DEFAULT_CUSTOM_THEME_COLOR,
-  },
-  {
-    id: 'deep-teal',
-    label: '深海青',
-    description: '氧化铜落入深水玻璃的冷静层次',
-    seed: '#0E7C72',
-    appearance: {
-      light: {
-        colorBgBase: '#FBFEFD',
-        colorTextBase: '#122C2A',
-      },
-      dark: {
-        colorBgBase: '#102321',
-        colorTextBase: '#D7EAE6',
-      },
-    },
-  },
-  {
-    id: 'signal-violet',
-    label: '古风色',
-    description: '赭石落在宣纸与松烟墨上的温厚层次',
-    seed: '#A0583D',
-    appearance: {
-      light: {
-        colorBgBase: '#F9F3E8',
-        colorTextBase: '#2B211B',
-      },
-      dark: {
-        colorBgBase: '#1E1713',
-        colorTextBase: '#EEE3D3',
-      },
-    },
-  },
-  {
-    id: 'graphite',
-    label: '石墨',
-    description: '铅笔粉末与工作室灰纸的材料质感',
-    seed: '#525B66',
-    appearance: {
-      light: {
-        colorBgBase: '#FAF9F6',
-        colorTextBase: '#25272B',
-      },
-      dark: {
-        colorBgBase: '#1B1C1E',
-        colorTextBase: '#E5E1D9',
-      },
-    },
-  },
-] as const
-
-export const BLACK = '#000000'
-export const WHITE = '#FFFFFF'
-export const LIGHT_FOREGROUND = WHITE
-export const LIGHT_CONTAINER_BASE = WHITE
-export const LIGHT_TEXT_BASE = '#0E1726'
-export const DARK_CONTAINER_BASE = '#111A29'
-export const DARK_TEXT_BASE = '#D8E2EE'
-
-/** 中继蓝浅色主题的稳定中性色阶；带色温主题会连续过渡到通用派生结果。 */
-export const LIGHT_SURFACE_ANCHORS = {
-  colorBgSpotlight: '#111827',
-  colorFillSecondary: '#E9EEF5',
-  colorFillTertiary: '#F1F5F9',
-  colorFillQuaternary: '#F6F8FB',
-  colorBorder: '#D8E0EA',
-  colorBorderSecondary: '#E2E8F0',
-  colorTextHeading: '#111827',
-  colorTextSecondary: '#64748B',
-  colorTextMuted: '#94A3B8',
-} as const
-
-/** 中继蓝暗色主题的视觉锚点；带色温主题会连续过渡到通用派生结果。 */
-export const DARK_SURFACE_ANCHORS = {
-  colorBgLayout: '#0B111C',
-  colorBgMask: '#030712',
-  colorBgSpotlight: '#050913',
-} as const
-
-/** 浅色阴影保持中性，不随主题文字色染色。 */
-export const LIGHT_SHADOW_BASE = LIGHT_TEXT_BASE
-
-export const EDITABLE_COLOR_TOKEN_NAMES = new Set<ThemeTokenName>([
-  '--cp-menu-item-selected-bg',
-  '--cp-input-bg',
-  '--cp-input-hover-bg',
-  '--cp-input-active-bg',
-  '--cp-button-primary-color',
-  '--cp-button-primary-bg',
-  '--cp-button-primary-hover-bg',
-  '--cp-button-primary-active-bg',
-  '--cp-button-secondary-bg',
-  '--cp-button-secondary-hover-bg',
-  '--cp-button-secondary-active-bg',
-  '--cp-icon-button-secondary-bg',
-  '--cp-icon-button-secondary-hover-bg',
-  '--cp-icon-button-secondary-active-bg',
-  '--cp-card-bg',
-  '--cp-modal-bg',
-  '--cp-popover-header-bg',
-  '--cp-table-header-bg',
-  '--cp-table-row-bg',
-  '--cp-table-row-stripe-bg',
-  '--cp-table-row-hover-bg',
-  '--cp-table-row-selected-bg',
-  '--cp-table-row-selected-hover-bg',
-  '--cp-progress-remaining-color',
-  '--cp-layout-sider-bg',
-  '--cp-scrollbar-thumb-bg',
-  '--cp-scrollbar-thumb-hover-bg',
-])
-
-export const EDITABLE_SHADOW_TOKEN_NAMES = new Set<ThemeTokenName>([
-  '--cp-input-shadow',
-  '--cp-input-hover-shadow',
-  '--cp-input-active-shadow',
-  '--cp-card-shadow',
-  '--cp-layout-sider-shadow',
-])
-
-/** 只有控件填充允许透出宿主背景；容器与固定表格单元格保持实色。 */
-export const ALPHA_COLOR_TOKEN_NAMES = new Set<string>([
-  '--cp-input-bg',
-  '--cp-input-hover-bg',
-  '--cp-input-active-bg',
-  '--cp-button-secondary-bg',
-  '--cp-button-secondary-hover-bg',
-  '--cp-button-secondary-active-bg',
-  '--cp-icon-button-secondary-bg',
-  '--cp-icon-button-secondary-hover-bg',
-  '--cp-icon-button-secondary-active-bg',
-] satisfies ThemeTokenName[])
diff --git a/frontend/src/theme/core/normalize.ts b/frontend/src/theme/core/normalize.ts
deleted file mode 100644
index cf84fabfa..000000000
--- a/frontend/src/theme/core/normalize.ts
+++ /dev/null
@@ -1,129 +0,0 @@
-import type {
-  ThemeColorId,
-  ThemeComponentOverrides,
-  ThemeCustomization,
-  ThemeMode,
-  ThemeSeedOverrides,
-  ThemeTokenName,
-  ThemeTokens,
-} from '../types'
-import { normalizeHexColor, normalizeRgbaHexColor } from '../../utils/color'
-import {
-  ALPHA_COLOR_TOKEN_NAMES,
-  EDITABLE_COLOR_TOKEN_NAMES,
-  EDITABLE_SHADOW_TOKEN_NAMES,
-  THEME_COLOR_PRESETS,
-} from './constants'
-
-export function themeTokenAllowsAlpha(name: string): boolean {
-  return ALPHA_COLOR_TOKEN_NAMES.has(name)
-}
-
-export function normalizeThemeCustomization(value: unknown): ThemeCustomization {
-  if (!value || typeof value !== 'object')
-    return {}
-
-  const source = value as { seed?: unknown, component?: unknown, tokenOverrides?: unknown }
-  const seed = normalizeThemeSeedOverrides(source.seed)
-  const component = normalizeThemeComponentOverrides(source.component)
-  const tokenOverrides = normalizeThemeTokenOverrides(source.tokenOverrides)
-  return {
-    ...(Object.keys(seed).length > 0 ? { seed } : {}),
-    ...(Object.keys(component).length > 0 ? { component } : {}),
-    ...(Object.keys(tokenOverrides).length > 0 ? { tokenOverrides } : {}),
-  }
-}
-
-export function isThemeMode(value: unknown): value is ThemeMode {
-  return value === 'system' || value === 'light' || value === 'dark'
-}
-
-export function isThemeColorId(value: unknown): value is ThemeColorId {
-  return value === 'custom' || THEME_COLOR_PRESETS.some(preset => preset.id === value)
-}
-
-function normalizeThemeSeedOverrides(value: unknown): ThemeSeedOverrides {
-  if (!value || typeof value !== 'object')
-    return {}
-
-  const source = value as Record<string, unknown>
-  const colors = [
-    'colorSuccess',
-    'colorWarning',
-    'colorError',
-    'colorInfo',
-    'colorLink',
-    'colorTextBase',
-    'colorBgBase',
-  ] as const
-  const result: ThemeSeedOverrides = {}
-
-  for (const key of colors) {
-    const normalized = normalizeHexColor(source[key])
-    if (normalized)
-      result[key] = normalized
-  }
-
-  assignBoundedNumber(result, source, 'fontSize', 11, 17)
-  assignBoundedNumber(result, source, 'sizeUnit', 3, 6)
-  assignBoundedNumber(result, source, 'sizeStep', 2, 8)
-  assignBoundedNumber(result, source, 'controlHeight', 28, 52)
-  assignBoundedNumber(result, source, 'borderRadius', 0, 20)
-  assignBoundedNumber(result, source, 'shadowStrength', 0, 140)
-  return result
-}
-
-function normalizeThemeComponentOverrides(value: unknown): ThemeComponentOverrides {
-  if (!value || typeof value !== 'object')
-    return {}
-
-  const source = value as Record<string, unknown>
-  const result: ThemeComponentOverrides = {}
-  assignBoundedNumber(result, source, 'tableRowHeight', 44, 84)
-  assignBoundedNumber(result, source, 'cardBorderRadius', 0, 32)
-  return result
-}
-
-function assignBoundedNumber<Target extends object, Key extends keyof Target>(
-  target: Target,
-  source: Record<string, unknown>,
-  key: Key,
-  min: number,
-  max: number,
-): void {
-  const value = source[key as string]
-  if (typeof value === 'number' && Number.isFinite(value))
-    target[key] = Math.round(Math.min(max, Math.max(min, value))) as Target[Key]
-}
-
-function normalizeThemeTokenOverrides(value: unknown): Partial<ThemeTokens> {
-  if (!value || typeof value !== 'object')
-    return {}
-
-  const result: Partial<ThemeTokens> = {}
-  for (const [rawName, rawValue] of Object.entries(value)) {
-    const name = rawName as ThemeTokenName
-    if (typeof rawValue !== 'string')
-      continue
-
-    if (EDITABLE_COLOR_TOKEN_NAMES.has(name)) {
-      const normalized = normalizeHexColor(rawValue)
-        ?? (themeTokenAllowsAlpha(name) ? normalizeRgbaHexColor(rawValue) : null)
-      if (normalized)
-        result[name] = normalized
-      continue
-    }
-
-    if (EDITABLE_SHADOW_TOKEN_NAMES.has(name) && isSafeShadowValue(rawValue))
-      result[name] = rawValue.trim()
-  }
-  return result
-}
-
-function isSafeShadowValue(value: string): boolean {
-  const normalized = value.trim()
-  return normalized.length > 0
-    && normalized.length <= 240
-    && !/[;{}]/.test(normalized)
-    && !/url\s*\(/i.test(normalized)
-}
diff --git a/frontend/src/theme/core/resolve.ts b/frontend/src/theme/core/resolve.ts
deleted file mode 100644
index 762e3b8f6..000000000
--- a/frontend/src/theme/core/resolve.ts
+++ /dev/null
@@ -1,155 +0,0 @@
-import type {
-  ResolvedTheme,
-  ResolvedThemeSeedTokens,
-  ThemeAppearanceSeed,
-  ThemeColorId,
-  ThemeColorPreset,
-  ThemeColorPresetId,
-  ThemeCustomization,
-  ThemeMap,
-  ThemeMode,
-  ThemeName,
-  ThemeSeedOverrides,
-  ThemeTokens,
-} from '../types'
-import { normalizeHexColor } from '../../utils/color'
-import { deriveCustomThemeAppearance } from '../derive/appearance'
-import {
-  deriveLightThemeFillMap,
-  deriveThemeAliasMap,
-  deriveThemeDataMap,
-  deriveThemeLinkMap,
-  deriveThemePresetColorMap,
-  deriveThemePrimaryMap,
-  deriveThemeSemanticMap,
-  deriveThemeSurfaceMap,
-  ensureThemeSurfaceContrast,
-} from '../derive/colors'
-import {
-  deriveThemeComponentMap,
-  deriveThemeDimensionMap,
-  deriveThemeShadowMap,
-} from '../derive/components'
-import {
-  DARK_CONTAINER_BASE,
-  DARK_TEXT_BASE,
-  DEFAULT_CUSTOM_THEME_COLOR,
-  DEFAULT_DIMENSIONS,
-  DEFAULT_SEED_COLORS,
-  DEFAULT_THEME_CUSTOMIZATION,
-  LIGHT_CONTAINER_BASE,
-  LIGHT_TEXT_BASE,
-  THEME_COLOR_PRESETS,
-} from './constants'
-import { normalizeThemeCustomization } from './normalize'
-import { createThemeTokens } from './tokens'
-
-export function resolveThemeName(mode: ThemeMode, prefersDark: boolean): ThemeName {
-  if (mode === 'system')
-    return prefersDark ? 'dark' : 'light'
-  return mode
-}
-
-export function resolveThemeSeed(colorId: ThemeColorId, customColor: string): string {
-  if (colorId === 'custom')
-    return normalizeHexColor(customColor) ?? DEFAULT_CUSTOM_THEME_COLOR
-  return themeColorPreset(colorId).seed
-}
-
-export function resolveTheme(
-  name: ThemeName,
-  colorId: ThemeColorId,
-  customColor: string,
-  customization: ThemeCustomization = DEFAULT_THEME_CUSTOMIZATION,
-): ResolvedTheme {
-  const seed = resolveThemeSeed(colorId, customColor)
-  const normalizedCustomization = normalizeThemeCustomization(customization)
-  const appearance = colorId === 'custom'
-    ? deriveCustomThemeAppearance(name, seed)
-    : themeColorPreset(colorId).appearance?.[name]
-  const seedTokens = resolveThemeSeedTokens(
-    name,
-    seed,
-    normalizedCustomization.seed,
-    appearance,
-  )
-  const themeMap = deriveThemeMap(name, seed, seedTokens, normalizedCustomization)
-  const tokensWithOverrides: ThemeTokens = {
-    ...createThemeTokens(themeMap),
-    ...normalizedCustomization.tokenOverrides,
-  }
-
-  return {
-    name,
-    colorId,
-    seed,
-    seedTokens,
-    tokens: tokensWithOverrides,
-  }
-}
-
-export function themeColorPreset(id: ThemeColorPresetId): ThemeColorPreset {
-  return THEME_COLOR_PRESETS.find(preset => preset.id === id) ?? THEME_COLOR_PRESETS[0]!
-}
-
-function deriveThemeMap(
-  name: ThemeName,
-  seed: string,
-  seedTokens: ResolvedThemeSeedTokens,
-  customization: ThemeCustomization,
-): ThemeMap {
-  const fills = name === 'light' ? deriveLightThemeFillMap(seedTokens) : null
-  const baseSurfaces = deriveThemeSurfaceMap(name, seedTokens)
-  const primary = deriveThemePrimaryMap(seed, name, baseSurfaces.colorBgContainer)
-  const surfaces = ensureThemeSurfaceContrast(baseSurfaces, fills, primary)
-  const aliases = deriveThemeAliasMap(surfaces)
-  const link = deriveThemeLinkMap(seedTokens.colorLink, name, surfaces.colorBgContainer)
-  const semantics = deriveThemeSemanticMap(name, surfaces, seedTokens, fills, primary)
-
-  return {
-    surfaces,
-    aliases,
-    primary,
-    link,
-    semantics,
-    presetColors: deriveThemePresetColorMap(name, surfaces.colorBgContainer, seedTokens),
-    data: deriveThemeDataMap(aliases, semantics),
-    shadows: deriveThemeShadowMap(name, seedTokens.shadowStrength),
-    components: deriveThemeComponentMap(
-      surfaces,
-      fills,
-      primary,
-      semantics.error,
-      seedTokens.shadowStrength,
-    ),
-    dimensions: deriveThemeDimensionMap(seedTokens, customization.component),
-  }
-}
-
-function resolveThemeSeedTokens(
-  theme: ThemeName,
-  colorPrimary: string,
-  overrides: ThemeSeedOverrides | undefined,
-  appearance: ThemeAppearanceSeed | undefined,
-): ResolvedThemeSeedTokens {
-  return {
-    colorPrimary,
-    colorSuccess: overrides?.colorSuccess ?? DEFAULT_SEED_COLORS.colorSuccess,
-    colorWarning: overrides?.colorWarning ?? DEFAULT_SEED_COLORS.colorWarning,
-    colorError: overrides?.colorError ?? DEFAULT_SEED_COLORS.colorError,
-    colorInfo: overrides?.colorInfo ?? DEFAULT_SEED_COLORS.colorInfo,
-    colorLink: overrides?.colorLink ?? colorPrimary,
-    colorTextBase: overrides?.colorTextBase
-      ?? appearance?.colorTextBase
-      ?? (theme === 'dark' ? DARK_TEXT_BASE : LIGHT_TEXT_BASE),
-    colorBgBase: overrides?.colorBgBase
-      ?? appearance?.colorBgBase
-      ?? (theme === 'dark' ? DARK_CONTAINER_BASE : LIGHT_CONTAINER_BASE),
-    fontSize: overrides?.fontSize ?? DEFAULT_DIMENSIONS.fontSize,
-    sizeUnit: overrides?.sizeUnit ?? DEFAULT_DIMENSIONS.sizeUnit,
-    sizeStep: overrides?.sizeStep ?? DEFAULT_DIMENSIONS.sizeStep,
-    controlHeight: overrides?.controlHeight ?? DEFAULT_DIMENSIONS.controlHeight,
-    borderRadius: overrides?.borderRadius ?? DEFAULT_DIMENSIONS.borderRadius,
-    shadowStrength: overrides?.shadowStrength ?? DEFAULT_DIMENSIONS.shadowStrength,
-  }
-}
diff --git a/frontend/src/theme/core/tokens.ts b/frontend/src/theme/core/tokens.ts
deleted file mode 100644
index b8a1d2d85..000000000
--- a/frontend/src/theme/core/tokens.ts
+++ /dev/null
@@ -1,142 +0,0 @@
-import type {
-  ActivityLevel,
-  ControlTokenName,
-  DirectThemeMapKey,
-  DirectTokenName,
-  FunctionalColorMap,
-  FunctionalTokenSuffix,
-  PresetColorRoleMap,
-  PresetTokenName,
-  PresetTokenSuffix,
-  SemanticTokenName,
-  ThemeMap,
-  ThemePresetColorMap,
-  ThemePrimaryMap,
-  ThemeSemanticMap,
-  ThemeTokenName,
-  ThemeTokens,
-} from '../types'
-
-const DIRECT_THEME_MAP_KEYS = [
-  'surfaces',
-  'aliases',
-  'primary',
-  'link',
-  'components',
-  'shadows',
-  'dimensions',
-] as const satisfies readonly DirectThemeMapKey[]
-
-const FUNCTIONAL_TOKEN_ROLES = [
-  ['container', '-container'],
-  ['containerHover', '-container-hover'],
-  ['containerActive', '-container-active'],
-  ['border', '-border'],
-  ['borderHover', '-border-hover'],
-  ['hover', '-hover'],
-  ['color', ''],
-  ['active', '-active'],
-  ['textHover', '-text-hover'],
-  ['text', '-text'],
-  ['onContainer', '-on-container'],
-  ['textActive', '-text-active'],
-] as const satisfies readonly (readonly [keyof FunctionalColorMap, FunctionalTokenSuffix])[]
-
-const PRESET_TOKEN_ROLES = [
-  ['container', 'container'],
-  ['containerStrong', 'container-strong'],
-  ['border', 'border'],
-  ['solid', 'solid'],
-  ['text', 'text'],
-  ['onContainer', 'on-container'],
-] as const satisfies readonly (readonly [keyof PresetColorRoleMap, PresetTokenSuffix])[]
-
-const CONTROL_TOKEN_BINDINGS = [
-  ['--cp-control-item-bg-active', 'colorPrimaryContainer'],
-  ['--cp-control-item-bg-active-hover', 'colorPrimaryContainerHover'],
-  ['--cp-control-outline', 'colorPrimaryBorder'],
-] as const satisfies readonly (readonly [ControlTokenName, keyof ThemePrimaryMap])[]
-
-export function createThemeTokens(themeMap: ThemeMap): ThemeTokens {
-  const tokens: Partial<ThemeTokens> = {}
-
-  for (const group of DIRECT_THEME_MAP_KEYS)
-    appendDirectTokens(tokens, themeMap[group])
-
-  appendPresetTokens(tokens, themeMap.presetColors)
-  appendControlTokens(tokens, themeMap.primary)
-  appendSemanticTokens(tokens, themeMap.semantics)
-  appendActivityTokens(tokens, themeMap.data.activityLevels)
-
-  return tokens as ThemeTokens
-}
-
-function appendDirectTokens<Source extends object>(
-  target: Partial<ThemeTokens>,
-  source: Source,
-): void {
-  for (const [key, value] of Object.entries(source))
-    setToken(target, directTokenName(key), value)
-}
-
-function appendPresetTokens(
-  target: Partial<ThemeTokens>,
-  presetColors: ThemePresetColorMap,
-): void {
-  for (const [colorName, roles] of Object.entries(presetColors)) {
-    for (const [role, suffix] of PRESET_TOKEN_ROLES) {
-      setToken(
-        target,
-        `--cp-color-${colorName}-${suffix}` as PresetTokenName,
-        roles[role],
-      )
-    }
-  }
-}
-
-function appendControlTokens(
-  target: Partial<ThemeTokens>,
-  primary: ThemePrimaryMap,
-): void {
-  for (const [token, role] of CONTROL_TOKEN_BINDINGS)
-    setToken(target, token, primary[role])
-}
-
-function appendSemanticTokens(
-  target: Partial<ThemeTokens>,
-  semantics: ThemeSemanticMap,
-): void {
-  for (const [colorName, roles] of Object.entries(semantics)) {
-    for (const [role, suffix] of FUNCTIONAL_TOKEN_ROLES) {
-      setToken(
-        target,
-        `--cp-color-${colorName}${suffix}` as SemanticTokenName,
-        roles[role],
-      )
-    }
-  }
-}
-
-function appendActivityTokens(
-  target: Partial<ThemeTokens>,
-  activityLevels: ThemeMap['data']['activityLevels'],
-): void {
-  activityLevels.forEach((value, level) => {
-    setToken(target, `--cp-activity-level-${level as ActivityLevel}`, value)
-  })
-}
-
-function directTokenName(key: string): DirectTokenName {
-  const kebab = key.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
-  return `--cp-${kebab}` as DirectTokenName
-}
-
-function setToken(
-  target: Partial<ThemeTokens>,
-  name: ThemeTokenName,
-  value: string,
-): void {
-  if (name in target)
-    throw new Error(`Duplicate theme token: ${name}`)
-  target[name] = value
-}
diff --git a/frontend/src/theme/derive/appearance.ts b/frontend/src/theme/derive/appearance.ts
deleted file mode 100644
index ca617aa19..000000000
--- a/frontend/src/theme/derive/appearance.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import type {
-  ThemeAppearanceSeed,
-  ThemeName,
-} from '../types'
-import { normalizeHexColor } from '../../utils/color'
-import { generateColorPalette, mix } from '../core/color'
-import {
-  DARK_CONTAINER_BASE,
-  DARK_TEXT_BASE,
-  DEFAULT_CUSTOM_THEME_COLOR,
-  LIGHT_CONTAINER_BASE,
-  LIGHT_TEXT_BASE,
-} from '../core/constants'
-
-const CUSTOM_APPEARANCE_DERIVERS = {
-  light: deriveLightCustomAppearance,
-  dark: deriveDarkCustomAppearance,
-} satisfies Record<ThemeName, (colorPrimary: string) => ThemeAppearanceSeed>
-
-/** 自定义主色仅向中性界面注入少量色温，再交给统一 Surface Map 派生。 */
-export function deriveCustomThemeAppearance(
-  theme: ThemeName,
-  colorPrimary: string,
-): ThemeAppearanceSeed {
-  const normalized = normalizeHexColor(colorPrimary) ?? DEFAULT_CUSTOM_THEME_COLOR
-  return CUSTOM_APPEARANCE_DERIVERS[theme](normalized)
-}
-
-function deriveDarkCustomAppearance(colorPrimary: string): ThemeAppearanceSeed {
-  const [paletteBackground = DARK_CONTAINER_BASE] = generateColorPalette(
-    colorPrimary,
-    'dark',
-  )
-
-  return {
-    colorBgBase: mix(DARK_CONTAINER_BASE, paletteBackground, 0.3),
-    colorTextBase: DARK_TEXT_BASE,
-  }
-}
-
-function deriveLightCustomAppearance(colorPrimary: string): ThemeAppearanceSeed {
-  return {
-    colorBgBase: mix(LIGHT_CONTAINER_BASE, colorPrimary, 0.028),
-    colorTextBase: LIGHT_TEXT_BASE,
-  }
-}
diff --git a/frontend/src/theme/derive/colors.ts b/frontend/src/theme/derive/colors.ts
deleted file mode 100644
index 73317dc06..000000000
--- a/frontend/src/theme/derive/colors.ts
+++ /dev/null
@@ -1,575 +0,0 @@
-import type {
-  FunctionalColorMap,
-  PresetColorRoleMap,
-  ResolvedThemeSeedTokens,
-  ThemeAliasMap,
-  ThemeColorRoleRecipe,
-  ThemeDataMap,
-  ThemeFillMap,
-  ThemeLinkMap,
-  ThemeName,
-  ThemePaletteSource,
-  ThemePresetColorMap,
-  ThemePresetColorName,
-  ThemePresetColorRoleRecipe,
-  ThemePrimaryMap,
-  ThemeSemanticMap,
-  ThemeSurfaceMap,
-} from '../types'
-import { normalizeHexColor } from '../../utils/color'
-import {
-  compositeOnBackground,
-  ensureContrast,
-  ensureLightness,
-  generateColorPalette,
-  mix,
-  mixColorTone,
-  relativeColorDistance,
-  withAlpha,
-} from '../core/color'
-import {
-  BLACK,
-  DARK_CONTAINER_BASE,
-  DARK_SURFACE_ANCHORS,
-  DARK_TEXT_BASE,
-  DEFAULT_CUSTOM_THEME_COLOR,
-  LIGHT_CONTAINER_BASE,
-  LIGHT_FOREGROUND,
-  LIGHT_SURFACE_ANCHORS,
-  LIGHT_TEXT_BASE,
-  PRESET_COLOR_SEEDS,
-  WHITE,
-} from '../core/constants'
-import { THEME_COLOR_ROLE_RECIPES } from './roles'
-
-const FULL_SURFACE_APPEARANCE_DISTANCE = 0.02
-const ACTIVITY_LEVEL_MIX = {
-  low: 0.22,
-  medium: 0.46,
-  high: 0.7,
-} as const
-
-const SURFACE_MAP_DERIVERS = {
-  light: deriveNeutralLightSurfaceMap,
-  dark: deriveNeutralDarkSurfaceMap,
-} satisfies Record<ThemeName, (seedTokens: ResolvedThemeSeedTokens) => ThemeSurfaceMap>
-
-const LIGHT_SURFACE_MIX = {
-  secondary: 0.09,
-  tertiary: 0.06,
-  quaternary: 0.035,
-} as const
-
-// 中性基线使用提亮色源；带色温主题复用 Surface 层级，避免填充被二次弱化。
-const LIGHT_FILL_OPACITIES = {
-  controlBg: [0.075, LIGHT_SURFACE_MIX.secondary * 0.78],
-  controlHoverBg: [0.105, LIGHT_SURFACE_MIX.secondary],
-  controlActiveBg: [0.14, LIGHT_SURFACE_MIX.tertiary * 2],
-  contentBg: [0.095, LIGHT_SURFACE_MIX.tertiary],
-  contentStripeBg: [0.045, LIGHT_SURFACE_MIX.quaternary],
-  contentHoverBg: [0.09, LIGHT_SURFACE_MIX.tertiary],
-} satisfies Record<keyof ThemeFillMap, [number, number]>
-
-export function deriveLightThemeFillMap(seedTokens: ResolvedThemeSeedTokens): ThemeFillMap {
-  const appearanceInfluence = deriveSurfaceAppearanceInfluence(
-    seedTokens.colorBgBase,
-    seedTokens.colorTextBase,
-    LIGHT_CONTAINER_BASE,
-    LIGHT_TEXT_BASE,
-  )
-  const fillColor = mix(
-    mixColorTone(WHITE, seedTokens.colorTextBase, 0.5),
-    seedTokens.colorTextBase,
-    appearanceInfluence,
-  )
-  const fills = {} as ThemeFillMap
-  for (const name of Object.keys(LIGHT_FILL_OPACITIES) as (keyof ThemeFillMap)[]) {
-    const [neutralOpacity, appearanceOpacity] = LIGHT_FILL_OPACITIES[name]
-    fills[name] = withAlpha(fillColor, neutralOpacity + (appearanceOpacity - neutralOpacity) * appearanceInfluence)
-  }
-  return fills
-}
-
-function themeTextBackgrounds(surfaces: ThemeSurfaceMap, fills: ThemeFillMap | null, primary: ThemePrimaryMap): string[] {
-  const hosts = [surfaces.colorBgLayout, surfaces.colorBgContainer, surfaces.colorBgElevated]
-  const backgrounds = [
-    ...hosts,
-    surfaces.colorBgTextHover,
-    surfaces.colorBgTextActive,
-    surfaces.colorFillSecondary,
-    surfaces.colorFillTertiary,
-    surfaces.colorFillQuaternary,
-  ]
-  if (!fills)
-    return backgrounds
-
-  return [
-    ...backgrounds,
-    primary.colorPrimaryContainer,
-    primary.colorPrimaryContainerHover,
-    // 透明控件在页面、卡片和浮层上颜色不同，不能把带 Alpha 的值当作实色校正。
-    ...hosts.flatMap(background => [fills.controlBg, fills.controlHoverBg, fills.controlActiveBg]
-      .map(fill => compositeOnBackground(fill, background))),
-    ...[fills.contentBg, fills.contentStripeBg, fills.contentHoverBg]
-      .map(fill => compositeOnBackground(fill, surfaces.colorBgContainer)),
-  ]
-}
-
-export function deriveThemeSurfaceMap(
-  theme: ThemeName,
-  seedTokens: ResolvedThemeSeedTokens,
-): ThemeSurfaceMap {
-  return SURFACE_MAP_DERIVERS[theme](seedTokens)
-}
-
-export function ensureThemeSurfaceContrast(
-  surfaces: ThemeSurfaceMap,
-  fills: ThemeFillMap | null,
-  primary: ThemePrimaryMap,
-): ThemeSurfaceMap {
-  const backgrounds = themeTextBackgrounds(surfaces, fills, primary)
-
-  // 辅助文字仍用于正常信息；按最深/最亮填充面保留可读的三级梯度。
-  return {
-    ...surfaces,
-    colorText: ensureContrast(surfaces.colorText, backgrounds, 7),
-    colorTextHeading: ensureContrast(surfaces.colorTextHeading, backgrounds, 7),
-    colorTextSecondary: ensureContrast(surfaces.colorTextSecondary, backgrounds, 7),
-    colorTextTertiary: ensureContrast(surfaces.colorTextTertiary, backgrounds, 5.5),
-    colorTextQuaternary: ensureContrast(surfaces.colorTextQuaternary, backgrounds, 4.5),
-  }
-}
-
-export function deriveThemeAliasMap(surfaces: ThemeSurfaceMap): ThemeAliasMap {
-  return {
-    colorFillAlter: surfaces.colorFillQuaternary,
-  }
-}
-
-export function deriveThemePrimaryMap(
-  seed: string,
-  theme: ThemeName,
-  containerBg: string,
-): ThemePrimaryMap {
-  const roles = deriveColorRoleMap(
-    seed,
-    theme,
-    containerBg,
-    THEME_COLOR_ROLE_RECIPES[theme].primary,
-  )
-
-  return {
-    colorPrimaryContainer: roles.container,
-    colorPrimaryContainerHover: roles.containerHover,
-    colorPrimaryBorder: roles.border,
-    colorPrimaryBorderHover: roles.borderHover,
-    colorPrimaryHover: roles.hover,
-    colorPrimary: roles.color,
-    colorPrimaryActive: roles.active,
-    colorPrimaryTextHover: roles.textHover,
-    colorPrimaryText: roles.text,
-    colorPrimaryOnContainer: roles.onContainer,
-    colorPrimaryTextActive: roles.textActive,
-    colorTextLightSolid: LIGHT_FOREGROUND,
-  }
-}
-
-export function deriveThemeLinkMap(
-  seed: string,
-  theme: ThemeName,
-  containerBg: string,
-): ThemeLinkMap {
-  const roles = deriveColorRoleMap(
-    seed,
-    theme,
-    containerBg,
-    THEME_COLOR_ROLE_RECIPES[theme].primary,
-  )
-
-  return {
-    colorLinkHover: roles.textHover,
-    colorLink: roles.text,
-    colorLinkActive: roles.textActive,
-  }
-}
-
-export function deriveThemeSemanticMap(
-  theme: ThemeName,
-  surfaces: ThemeSurfaceMap,
-  seedTokens: ResolvedThemeSeedTokens,
-  fills: ThemeFillMap | null,
-  primary: ThemePrimaryMap,
-): ThemeSemanticMap {
-  const recipe = THEME_COLOR_ROLE_RECIPES[theme].semantic
-  const containerBg = surfaces.colorBgContainer
-  const textBackgrounds = themeTextBackgrounds(surfaces, fills, primary)
-
-  return {
-    info: deriveColorRoleMap(
-      seedTokens.colorInfo,
-      theme,
-      containerBg,
-      recipe,
-      textBackgrounds,
-    ),
-    success: deriveColorRoleMap(
-      seedTokens.colorSuccess,
-      theme,
-      containerBg,
-      recipe,
-      textBackgrounds,
-    ),
-    warning: deriveColorRoleMap(
-      seedTokens.colorWarning,
-      theme,
-      containerBg,
-      recipe,
-      textBackgrounds,
-    ),
-    error: deriveColorRoleMap(
-      seedTokens.colorError,
-      theme,
-      containerBg,
-      recipe,
-      textBackgrounds,
-    ),
-  }
-}
-
-export function deriveThemePresetColorMap(
-  theme: ThemeName,
-  containerBg: string,
-  seedTokens: ResolvedThemeSeedTokens,
-): ThemePresetColorMap {
-  const seeds: Record<ThemePresetColorName, string> = {
-    ...PRESET_COLOR_SEEDS,
-    blue: seedTokens.colorInfo,
-    green: seedTokens.colorSuccess,
-    orange: seedTokens.colorWarning,
-    red: seedTokens.colorError,
-  }
-  const presetColors = {} as ThemePresetColorMap
-
-  for (const colorName of Object.keys(seeds) as ThemePresetColorName[]) {
-    presetColors[colorName] = derivePresetColorRoleMap(
-      generateColorPalette(seeds[colorName], theme, containerBg),
-      containerBg,
-      THEME_COLOR_ROLE_RECIPES[theme].preset,
-    )
-  }
-
-  return presetColors
-}
-
-export function deriveThemeDataMap(
-  aliases: ThemeAliasMap,
-  semantics: ThemeSemanticMap,
-): ThemeDataMap {
-  const activityBase = semantics.success.container
-  const activitySolid = semantics.success.color
-
-  return {
-    activityLevels: [
-      aliases.colorFillAlter,
-      mix(activityBase, activitySolid, ACTIVITY_LEVEL_MIX.low),
-      mix(activityBase, activitySolid, ACTIVITY_LEVEL_MIX.medium),
-      mix(activityBase, activitySolid, ACTIVITY_LEVEL_MIX.high),
-      activitySolid,
-    ],
-  }
-}
-
-function deriveNeutralDarkSurfaceMap(
-  seedTokens: ResolvedThemeSeedTokens,
-): ThemeSurfaceMap {
-  const background = seedTokens.colorBgBase
-  const colorText = seedTokens.colorTextBase
-  const appearanceInfluence = deriveSurfaceAppearanceInfluence(
-    background,
-    colorText,
-    DARK_CONTAINER_BASE,
-    DARK_TEXT_BASE,
-  )
-  const adaptiveTone = (neutral: string, chromatic: string): string =>
-    mix(neutral, chromatic, appearanceInfluence)
-  const neutralFillQuaternary = mixColorTone(background, colorText, 0.04, {
-    hueWeight: 0,
-  })
-  const neutralFillTertiary = mixColorTone(background, colorText, 0.0765, {
-    hueWeight: 0.64,
-    saturationScale: 0.95,
-  })
-  const neutralFillSecondary = mixColorTone(background, colorText, 0.139, {
-    hueWeight: 0.52,
-    saturationScale: 0.99,
-  })
-  const neutralBorderSecondary = mixColorTone(background, colorText, 0.1395, {
-    hueWeight: 0.62,
-    saturationScale: 0.85,
-  })
-  const neutralBorder = mixColorTone(background, colorText, 0.1495, {
-    hueWeight: 0.58,
-    saturationScale: 0.78,
-  })
-  const colorFillQuaternary = adaptiveTone(
-    neutralFillQuaternary,
-    mix(background, colorText, 0.045),
-  )
-  const colorFillTertiary = adaptiveTone(
-    neutralFillTertiary,
-    mix(background, colorText, 0.075),
-  )
-  const colorFillSecondary = adaptiveTone(
-    neutralFillSecondary,
-    mix(background, colorText, 0.12),
-  )
-  const colorBorderSecondary = adaptiveTone(
-    neutralBorderSecondary,
-    mix(background, colorText, 0.105),
-  )
-  const colorBorder = adaptiveTone(
-    neutralBorder,
-    mix(background, colorText, 0.155),
-  )
-  const adaptiveMutedText = (
-    weight: number,
-    hueWeight: number,
-    saturationScale: number,
-    chromaticBackgroundWeight: number,
-  ): string => adaptiveTone(
-    mixColorTone(
-      background,
-      colorText,
-      weight,
-      { hueWeight, saturationScale },
-    ),
-    mix(colorText, background, chromaticBackgroundWeight),
-  )
-
-  return {
-    colorBgLayout: adaptiveTone(
-      DARK_SURFACE_ANCHORS.colorBgLayout,
-      mix(background, BLACK, 0.3),
-    ),
-    colorBgContainer: background,
-    colorBgElevated: adaptiveTone(
-      neutralFillQuaternary,
-      mix(background, WHITE, 0.045),
-    ),
-    colorBgSpotlight: adaptiveTone(
-      DARK_SURFACE_ANCHORS.colorBgSpotlight,
-      mix(background, BLACK, 0.74),
-    ),
-    colorBgMask: withAlpha(
-      adaptiveTone(
-        DARK_SURFACE_ANCHORS.colorBgMask,
-        mix(background, BLACK, 0.8),
-      ),
-      0.65 + appearanceInfluence * 0.03,
-    ),
-    colorBgTextHover: adaptiveTone(
-      mixColorTone(background, colorText, 0.0815, {
-        hueWeight: 0.5,
-        saturationScale: 1.04,
-      }),
-      mix(background, colorText, 0.08),
-    ),
-    colorBgTextActive: colorFillSecondary,
-    colorBgContainerDisabled: adaptiveTone(
-      mixColorTone(background, colorText, 0.036, {
-        hueWeight: 0.5,
-        saturationScale: 0.88,
-      }),
-      mix(background, colorText, 0.035),
-    ),
-    colorFillSecondary,
-    colorFillTertiary,
-    colorFillQuaternary,
-    colorBorder,
-    colorBorderSecondary,
-    colorSplit: withAlpha(colorBorderSecondary, 0.5),
-    colorText,
-    colorTextHeading: adaptiveTone(
-      mixColorTone(WHITE, colorText, 0.23, {
-        saturationScale: 1.35,
-      }),
-      mix(colorText, WHITE, 0.74),
-    ),
-    colorTextSecondary: adaptiveMutedText(0.6745, 0.7, 0.55, 0.36),
-    colorTextTertiary: adaptiveMutedText(0.531, 0.58, 0.45, 0.5),
-    colorTextQuaternary: adaptiveMutedText(0.4555, 0.48, 0.42, 0.58),
-    colorTextDisabled: adaptiveMutedText(0.37, 1, 0.48, 0.66),
-    colorShadow: withAlpha(BLACK, 0.75),
-  }
-}
-
-function deriveNeutralLightSurfaceMap(
-  seedTokens: ResolvedThemeSeedTokens,
-): ThemeSurfaceMap {
-  const background = seedTokens.colorBgBase
-  const colorText = seedTokens.colorTextBase
-  const appearanceInfluence = deriveSurfaceAppearanceInfluence(
-    background,
-    colorText,
-    LIGHT_CONTAINER_BASE,
-    LIGHT_TEXT_BASE,
-  )
-  const adaptiveTone = (neutral: string, chromatic: string): string =>
-    mix(neutral, chromatic, appearanceInfluence)
-  const colorFillQuaternary = adaptiveTone(
-    LIGHT_SURFACE_ANCHORS.colorFillQuaternary,
-    mix(background, colorText, LIGHT_SURFACE_MIX.quaternary),
-  )
-  const colorFillTertiary = adaptiveTone(
-    LIGHT_SURFACE_ANCHORS.colorFillTertiary,
-    mix(background, colorText, LIGHT_SURFACE_MIX.tertiary),
-  )
-  const colorFillSecondary = adaptiveTone(
-    LIGHT_SURFACE_ANCHORS.colorFillSecondary,
-    mix(background, colorText, LIGHT_SURFACE_MIX.secondary),
-  )
-  const colorBorderSecondary = adaptiveTone(
-    LIGHT_SURFACE_ANCHORS.colorBorderSecondary,
-    mix(background, colorText, 0.105),
-  )
-  const colorBorder = adaptiveTone(
-    LIGHT_SURFACE_ANCHORS.colorBorder,
-    mix(background, colorText, 0.145),
-  )
-
-  return {
-    colorBgLayout: colorFillQuaternary,
-    colorBgContainer: background,
-    colorBgElevated: background,
-    colorBgSpotlight: adaptiveTone(
-      LIGHT_SURFACE_ANCHORS.colorBgSpotlight,
-      mix(colorText, BLACK, 0.08),
-    ),
-    colorBgMask: withAlpha(colorText, 0.3),
-    colorBgTextHover: colorFillTertiary,
-    colorBgTextActive: colorFillSecondary,
-    colorBgContainerDisabled: colorFillTertiary,
-    colorFillSecondary,
-    colorFillTertiary,
-    colorFillQuaternary,
-    colorBorder,
-    colorBorderSecondary,
-    colorSplit: withAlpha(colorBorder, 0.42),
-    colorText,
-    colorTextHeading: adaptiveTone(
-      LIGHT_SURFACE_ANCHORS.colorTextHeading,
-      mix(colorText, BLACK, 0.18),
-    ),
-    colorTextSecondary: adaptiveTone(
-      LIGHT_SURFACE_ANCHORS.colorTextSecondary,
-      mix(colorText, background, 0.36),
-    ),
-    colorTextTertiary: adaptiveTone(
-      LIGHT_SURFACE_ANCHORS.colorTextMuted,
-      mix(colorText, background, 0.55),
-    ),
-    colorTextQuaternary: adaptiveTone(
-      LIGHT_SURFACE_ANCHORS.colorTextMuted,
-      mix(colorText, background, 0.6),
-    ),
-    colorTextDisabled: adaptiveTone(
-      LIGHT_SURFACE_ANCHORS.colorTextMuted,
-      mix(colorText, background, 0.62),
-    ),
-    colorShadow: withAlpha(colorText, 0.38),
-  }
-}
-
-function deriveSurfaceAppearanceInfluence(
-  background: string,
-  text: string,
-  baselineBackground: string,
-  baselineText: string,
-): number {
-  const distance = Math.max(
-    relativeColorDistance(background, baselineBackground),
-    relativeColorDistance(text, baselineText),
-  )
-  const normalized = Math.min(1, distance / FULL_SURFACE_APPEARANCE_DISTANCE)
-  return normalized * normalized * (3 - 2 * normalized)
-}
-
-function deriveColorRoleMap(
-  seed: string,
-  theme: ThemeName,
-  containerBg: string,
-  recipe: ThemeColorRoleRecipe,
-  textBackgrounds: string | readonly string[] = containerBg,
-): FunctionalColorMap {
-  const normalizedSeed = normalizeHexColor(seed) ?? DEFAULT_CUSTOM_THEME_COLOR
-  const palette = generateColorPalette(normalizedSeed, theme, containerBg)
-  const resolve = (source: ThemePaletteSource): string => source === 'seed'
-    ? normalizedSeed
-    : normalizeHexColor(palette[source - 1]) ?? normalizedSeed
-  const color = resolve(recipe.color)
-  const hover = resolve(recipe.hover)
-  const active = resolve(recipe.active)
-  const container = mix(containerBg, color, recipe.containerMix)
-  const containerHover = mix(containerBg, hover, recipe.containerHoverMix)
-  const containerActive = mix(containerBg, active, recipe.containerActiveMix)
-  const semanticContainers = [container, containerHover, containerActive]
-  const resolveText = (
-    source: ThemePaletteSource,
-    backgrounds: string | readonly string[] = textBackgrounds,
-  ): string => {
-    const value = resolve(source)
-    const toned = recipe.minimumTextLightness === undefined
-      ? value
-      : ensureLightness(value, recipe.minimumTextLightness)
-    return ensureContrast(toned, backgrounds, 4.5)
-  }
-
-  return {
-    container,
-    containerHover,
-    containerActive,
-    border: ensureContrast(mix(containerBg, color, recipe.borderMix), containerBg, 3),
-    borderHover: ensureContrast(mix(containerBg, hover, recipe.borderHoverMix), containerBg, 3),
-    hover: recipe.hoverContrast === undefined
-      ? hover
-      : ensureContrast(hover, containerBg, recipe.hoverContrast),
-    color,
-    active: recipe.activeContrast === undefined
-      ? active
-      : ensureContrast(active, containerBg, recipe.activeContrast),
-    textHover: resolveText(recipe.textHover),
-    text: resolveText(recipe.text),
-    onContainer: resolveText(
-      recipe.onContainer ?? recipe.text,
-      semanticContainers,
-    ),
-    textActive: resolveText(recipe.textActive),
-  }
-}
-
-/** 容器、边框和实心色对齐 Colorful Tag；文字在当前 Surface 上保持可读。 */
-function derivePresetColorRoleMap(
-  palette: readonly string[],
-  containerBg: string,
-  recipe: ThemePresetColorRoleRecipe,
-): PresetColorRoleMap {
-  const color = (step: number): string =>
-    normalizeHexColor(palette[step - 1]) ?? DEFAULT_CUSTOM_THEME_COLOR
-  const solid = color(recipe.solid)
-  const container = mix(containerBg, solid, recipe.containerMix)
-  const containerStrong = mix(containerBg, solid, recipe.containerStrongMix)
-  const text = color(recipe.text)
-  const onContainer = color(recipe.onContainer)
-  const toneText = (value: string): string => recipe.minimumTextLightness === undefined
-    ? value
-    : ensureLightness(value, recipe.minimumTextLightness)
-
-  return {
-    container,
-    containerStrong,
-    border: ensureContrast(mix(containerBg, solid, recipe.borderMix), containerBg, 3),
-    solid,
-    text: ensureContrast(toneText(text), containerBg, 4.5),
-    onContainer: ensureContrast(toneText(onContainer), [container, containerStrong], 4.5),
-  }
-}
diff --git a/frontend/src/theme/derive/components.ts b/frontend/src/theme/derive/components.ts
deleted file mode 100644
index 656eaec09..000000000
--- a/frontend/src/theme/derive/components.ts
+++ /dev/null
@@ -1,213 +0,0 @@
-import type {
-  FunctionalColorMap,
-  ResolvedThemeSeedTokens,
-  ThemeComponentMap,
-  ThemeComponentOverrides,
-  ThemeDimensionMap,
-  ThemeFillMap,
-  ThemeName,
-  ThemePrimaryMap,
-  ThemeShadowMap,
-  ThemeSurfaceMap,
-} from '../types'
-import {
-  compositeOnBackground,
-  ensureContrast,
-  mix,
-  scaleShadowAlpha,
-  withAlpha,
-} from '../core/color'
-import {
-  BLACK,
-  DEFAULT_DIMENSIONS,
-  LIGHT_SHADOW_BASE,
-} from '../core/constants'
-
-type SurfaceComponentMap = Omit<ThemeComponentMap, `buttonPrimary${string}` | 'tableRowSelectedHoverBg'>
-
-const SHADOW_MAP_DERIVERS = {
-  light: deriveLightShadowMap,
-  dark: deriveDarkShadowMap,
-} satisfies Record<ThemeName, (shadowStrength: number) => ThemeShadowMap>
-
-export function deriveThemeDimensionMap(
-  seedTokens: ResolvedThemeSeedTokens,
-  componentOverrides: ThemeComponentOverrides | undefined,
-): ThemeDimensionMap {
-  const fontSize = seedTokens.fontSize
-  const fontSizeXs = Math.max(9, fontSize - 2)
-  const fontSizeSm = Math.max(10, fontSize - 1)
-  const fontSizeLg = fontSize + 1
-  const fontSizeXl = fontSize + 2
-  const controlHeight = seedTokens.controlHeight
-  const controlHeightStep = Math.max(2, Math.round(seedTokens.sizeStep * 1.5))
-  const tableRowHeight = componentOverrides?.tableRowHeight ?? DEFAULT_DIMENSIONS.tableRowHeight
-  const borderRadius = seedTokens.borderRadius
-  const radiusStep = Math.max(1, Math.round(seedTokens.sizeStep / 2))
-  const cardBorderRadius = componentOverrides?.cardBorderRadius
-    ?? DEFAULT_DIMENSIONS.cardBorderRadius
-
-  return {
-    fontSizeXs: `${fontSizeXs}px`,
-    fontSizeSm: `${fontSizeSm}px`,
-    fontSize: `${fontSize}px`,
-    fontSizeLg: `${fontSizeLg}px`,
-    fontSizeXl: `${fontSizeXl}px`,
-    lineHeightXs: `${fontSizeXs + 5}px`,
-    lineHeightSm: `${fontSizeSm + 6}px`,
-    lineHeight: `${fontSize + 7}px`,
-    lineHeightLg: `${fontSizeLg + 8}px`,
-    lineHeightXl: `${fontSizeXl + 9}px`,
-    sizeUnit: `${seedTokens.sizeUnit}px`,
-    sizeStep: `${seedTokens.sizeStep}px`,
-    controlHeightSm: `${Math.max(24, controlHeight - controlHeightStep)}px`,
-    controlHeight: `${controlHeight}px`,
-    controlHeightLg: `${controlHeight + controlHeightStep}px`,
-    tableRowHeight: `${tableRowHeight}px`,
-    tableRowHeightSm: `${Math.max(32, tableRowHeight - 20)}px`,
-    borderRadiusSm: `${Math.max(0, borderRadius - radiusStep)}px`,
-    borderRadius: `${borderRadius}px`,
-    borderRadiusLg: `${borderRadius + seedTokens.sizeStep}px`,
-    cardBorderRadius: `${cardBorderRadius}px`,
-  }
-}
-
-export function deriveThemeShadowMap(
-  theme: ThemeName,
-  shadowStrength: number,
-): ThemeShadowMap {
-  return SHADOW_MAP_DERIVERS[theme](shadowStrength)
-}
-
-function deriveDarkShadowMap(shadowStrength: number): ThemeShadowMap {
-  return {
-    boxShadow: scaleShadowAlpha(`0 24px 52px -26px ${withAlpha(BLACK, 0.82)}`, shadowStrength),
-    boxShadowSecondary: scaleShadowAlpha(`0 18px 34px -26px ${withAlpha(BLACK, 0.64)}`, shadowStrength),
-    boxShadowTertiary: scaleShadowAlpha(`0 12px 24px -20px ${withAlpha(BLACK, 0.66)}`, shadowStrength),
-  }
-}
-
-function deriveLightShadowMap(shadowStrength: number): ThemeShadowMap {
-  return {
-    boxShadow: scaleShadowAlpha(`0 18px 38px -18px ${withAlpha(LIGHT_SHADOW_BASE, 0.17)}`, shadowStrength),
-    boxShadowSecondary: scaleShadowAlpha(`0 10px 22px -18px ${withAlpha(LIGHT_SHADOW_BASE, 0.08)}`, shadowStrength),
-    boxShadowTertiary: scaleShadowAlpha(`0 9px 18px -14px ${withAlpha(LIGHT_SHADOW_BASE, 0.086)}`, shadowStrength),
-  }
-}
-
-export function deriveThemeComponentMap(
-  surfaces: ThemeSurfaceMap,
-  fills: ThemeFillMap | null,
-  primary: ThemePrimaryMap,
-  error: FunctionalColorMap,
-  shadowStrength: number,
-): ThemeComponentMap {
-  // 明暗模式共用组件合同，各自保留适合宿主表面的填充配方。
-  const components = fills
-    ? deriveLightComponentMap(surfaces, fills, primary, error, shadowStrength)
-    : deriveDarkComponentMap(surfaces, primary, error, shadowStrength)
-  const buttonPrimaryBg = ensureContrast(primary.colorPrimary, primary.colorTextLightSolid, 4.5)
-  return {
-    ...components,
-    // 暗色选中行只轻微提亮，保留原有蓝灰色温和选中语义。
-    tableRowSelectedHoverBg: fills
-      ? primary.colorPrimaryContainerHover
-      : mix(primary.colorPrimaryContainer, surfaces.colorText, 0.04),
-    buttonPrimaryColor: primary.colorTextLightSolid,
-    buttonPrimaryBg,
-    buttonPrimaryHoverBg: mix(buttonPrimaryBg, BLACK, 0.08),
-    buttonPrimaryActiveBg: mix(buttonPrimaryBg, BLACK, 0.16),
-  }
-}
-
-function deriveDarkComponentMap(
-  surfaces: ThemeSurfaceMap,
-  primary: ThemePrimaryMap,
-  error: FunctionalColorMap,
-  shadowStrength: number,
-): SurfaceComponentMap {
-  const inputInteractionBg = mix(surfaces.colorBgContainer, surfaces.colorFillSecondary, 0.69)
-  // 悬停与聚焦共用反馈；装饰阴影关闭时仍保留可见外圈。
-  const inputInteractionShadow = [
-    '0 0 0 3px var(--cp-color-primary-container-hover)',
-    shadowStrength > 0
-      ? scaleShadowAlpha(`0 14px 28px -22px ${withAlpha(BLACK, 0.72)}`, shadowStrength)
-      : null,
-  ].filter(Boolean).join(', ')
-
-  return {
-    buttonSecondaryBg: surfaces.colorFillTertiary,
-    buttonSecondaryHoverBg: surfaces.colorBgTextActive,
-    buttonSecondaryActiveBg: surfaces.colorBgTextActive,
-    iconButtonSecondaryBg: surfaces.colorBgContainer,
-    iconButtonSecondaryHoverBg: surfaces.colorBgTextHover,
-    iconButtonSecondaryActiveBg: surfaces.colorBgTextActive,
-    menuItemSelectedBg: surfaces.colorBgTextHover,
-    inputBg: mix(surfaces.colorBgContainer, surfaces.colorFillSecondary, 0.375),
-    inputHoverBg: inputInteractionBg,
-    inputActiveBg: inputInteractionBg,
-    inputErrorActiveBg: error.container,
-    brandMarkBg: surfaces.colorBgElevated,
-    cardBg: surfaces.colorBgContainer,
-    modalBg: surfaces.colorBgContainer,
-    popoverHeaderBg: surfaces.colorFillTertiary,
-    tableHeaderBg: surfaces.colorFillTertiary,
-    tableRowBg: surfaces.colorBgContainer,
-    tableRowStripeBg: surfaces.colorFillQuaternary,
-    tableRowHoverBg: surfaces.colorBgTextHover,
-    tableRowSelectedBg: primary.colorPrimaryContainer,
-    progressRemainingColor: mix(surfaces.colorBgContainer, surfaces.colorBorderSecondary, 0.92),
-    layoutSiderBg: surfaces.colorBgContainer,
-    cardShadow: scaleShadowAlpha(`0 18px 34px -26px ${withAlpha(BLACK, 0.64)}`, shadowStrength),
-    inputShadow: scaleShadowAlpha(`0 12px 24px -20px ${withAlpha(BLACK, 0.66)}`, shadowStrength),
-    inputHoverShadow: inputInteractionShadow,
-    inputActiveShadow: inputInteractionShadow,
-    inputErrorActiveShadow: `0 0 0 3px ${withAlpha(error.color, 0.28)}`,
-    layoutSiderShadow: scaleShadowAlpha(`2px 0 18px -14px ${withAlpha(BLACK, 0.72)}`, shadowStrength),
-    scrollbarThumbBg: mix(surfaces.colorBorderSecondary, surfaces.colorTextSecondary, 0.16),
-    scrollbarThumbHoverBg: mix(surfaces.colorBorderSecondary, surfaces.colorTextSecondary, 0.3),
-  }
-}
-
-function deriveLightComponentMap(
-  surfaces: ThemeSurfaceMap,
-  fills: ThemeFillMap,
-  primary: ThemePrimaryMap,
-  error: FunctionalColorMap,
-  shadowStrength: number,
-): SurfaceComponentMap {
-  const inputInteractionShadow = `0 0 0 3px ${withAlpha(primary.colorPrimary, 0.16)}`
-  return {
-    buttonSecondaryBg: fills.controlBg,
-    buttonSecondaryHoverBg: fills.controlHoverBg,
-    buttonSecondaryActiveBg: fills.controlActiveBg,
-    iconButtonSecondaryBg: fills.controlBg,
-    iconButtonSecondaryHoverBg: fills.controlHoverBg,
-    iconButtonSecondaryActiveBg: fills.controlActiveBg,
-    inputBg: fills.controlBg,
-    inputHoverBg: surfaces.colorBgContainer,
-    inputActiveBg: surfaces.colorBgContainer,
-    inputErrorActiveBg: error.container,
-    inputShadow: 'none',
-    inputHoverShadow: inputInteractionShadow,
-    inputActiveShadow: inputInteractionShadow,
-    inputErrorActiveShadow: `0 0 0 3px ${withAlpha(error.color, 0.18)}`,
-    // 先合成实色，固定列滚动时不会透出下层内容。
-    tableHeaderBg: compositeOnBackground(fills.contentBg, surfaces.colorBgContainer),
-    tableRowBg: surfaces.colorBgContainer,
-    tableRowStripeBg: compositeOnBackground(fills.contentStripeBg, surfaces.colorBgContainer),
-    tableRowHoverBg: compositeOnBackground(fills.contentHoverBg, surfaces.colorBgContainer),
-    tableRowSelectedBg: primary.colorPrimaryContainer,
-    menuItemSelectedBg: surfaces.colorBgTextActive,
-    brandMarkBg: surfaces.colorBgSpotlight,
-    cardBg: surfaces.colorBgContainer,
-    modalBg: surfaces.colorBgContainer,
-    popoverHeaderBg: surfaces.colorFillSecondary,
-    progressRemainingColor: surfaces.colorBorderSecondary,
-    layoutSiderBg: surfaces.colorBgContainer,
-    cardShadow: scaleShadowAlpha(`0 10px 22px -18px ${withAlpha(LIGHT_SHADOW_BASE, 0.08)}`, shadowStrength),
-    layoutSiderShadow: scaleShadowAlpha(`2px 0 12px -12px ${withAlpha(LIGHT_SHADOW_BASE, 0.027)}`, shadowStrength),
-    scrollbarThumbBg: mix(surfaces.colorBgLayout, surfaces.colorTextSecondary, 0.2),
-    scrollbarThumbHoverBg: mix(surfaces.colorBgLayout, surfaces.colorTextSecondary, 0.34),
-  }
-}
diff --git a/frontend/src/theme/derive/roles.ts b/frontend/src/theme/derive/roles.ts
deleted file mode 100644
index e7c29aa75..000000000
--- a/frontend/src/theme/derive/roles.ts
+++ /dev/null
@@ -1,87 +0,0 @@
-import type {
-  ThemeColorRoleRecipes,
-  ThemeName,
-} from '../types'
-
-/** 明暗算法只描述 Palette 到 Map Token 的角色关系，不携带具体品牌颜色。 */
-export const THEME_COLOR_ROLE_RECIPES = {
-  light: {
-    primary: {
-      color: 'seed',
-      hover: 5,
-      active: 7,
-      textHover: 5,
-      text: 6,
-      textActive: 7,
-      containerMix: 0.09,
-      containerHoverMix: 0.14,
-      containerActiveMix: 0.18,
-      borderMix: 0.46,
-      borderHoverMix: 0.56,
-    },
-    semantic: {
-      color: 6,
-      hover: 5,
-      active: 7,
-      textHover: 5,
-      text: 7,
-      onContainer: 6,
-      textActive: 7,
-      containerMix: 0.08,
-      containerHoverMix: 0.12,
-      containerActiveMix: 0.18,
-      borderMix: 0.4,
-      borderHoverMix: 0.5,
-      hoverContrast: 3,
-      activeContrast: 3,
-    },
-    preset: {
-      solid: 6,
-      text: 7,
-      onContainer: 7,
-      containerMix: 0.08,
-      containerStrongMix: 0.22,
-      borderMix: 0.4,
-    },
-  },
-  dark: {
-    primary: {
-      color: 'seed',
-      hover: 8,
-      active: 6,
-      textHover: 8,
-      text: 7,
-      textActive: 6,
-      containerMix: 0.17,
-      containerHoverMix: 0.24,
-      containerActiveMix: 0.3,
-      borderMix: 0.52,
-      borderHoverMix: 0.62,
-    },
-    semantic: {
-      color: 6,
-      hover: 8,
-      active: 6,
-      textHover: 8,
-      text: 7,
-      onContainer: 9,
-      textActive: 10,
-      containerMix: 0.18,
-      containerHoverMix: 0.24,
-      containerActiveMix: 0.3,
-      borderMix: 0.46,
-      borderHoverMix: 0.56,
-      hoverContrast: 3,
-      activeContrast: 3,
-    },
-    preset: {
-      solid: 6,
-      text: 8,
-      onContainer: 8,
-      containerMix: 0.18,
-      containerStrongMix: 0.24,
-      borderMix: 0.46,
-      minimumTextLightness: 0.7,
-    },
-  },
-} as const satisfies Record<ThemeName, ThemeColorRoleRecipes>
diff --git a/frontend/src/theme/index.ts b/frontend/src/theme/index.ts
deleted file mode 100644
index 0018c3473..000000000
--- a/frontend/src/theme/index.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-export {
-  DEFAULT_CUSTOM_THEME_COLOR,
-  DEFAULT_THEME_COLOR,
-  DEFAULT_THEME_CUSTOMIZATION,
-  DEFAULT_THEME_MODE,
-  THEME_COLOR_PRESETS,
-} from './core/constants'
-export {
-  isThemeColorId,
-  isThemeMode,
-  normalizeThemeCustomization,
-  themeTokenAllowsAlpha,
-} from './core/normalize'
-export {
-  resolveTheme,
-  resolveThemeName,
-  resolveThemeSeed,
-  themeColorPreset,
-} from './core/resolve'
-export { applyResolvedTheme } from './runtime/browser'
-export type {
-  ResolvedTheme,
-  ResolvedThemeSeedTokens,
-  ThemeAppearanceSeed,
-  ThemeColorId,
-  ThemeColorPreset,
-  ThemeColorPresetId,
-  ThemeComponentOverrides,
-  ThemeCustomization,
-  ThemeMode,
-  ThemeName,
-  ThemeSeedOverrides,
-  ThemeTokenName,
-  ThemeTokens,
-} from './types'
diff --git a/frontend/src/theme/runtime/browser.ts b/frontend/src/theme/runtime/browser.ts
deleted file mode 100644
index 9ccbfea3e..000000000
--- a/frontend/src/theme/runtime/browser.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-// @env browser
-
-import type { ResolvedTheme } from '../types'
-
-const RUNTIME_THEME_STYLE_ID = 'cp-runtime-theme'
-
-export function applyResolvedTheme(root: HTMLElement, theme: ResolvedTheme): void {
-  root.dataset.theme = theme.name
-  root.dataset.themeColor = theme.colorId
-
-  const style = ensureRuntimeThemeStyle(root.ownerDocument)
-  style.dataset.theme = theme.name
-  style.dataset.themeColor = theme.colorId
-  style.textContent = serializeTheme(theme)
-}
-
-function ensureRuntimeThemeStyle(document: Document): HTMLStyleElement {
-  const existing = document.getElementById(RUNTIME_THEME_STYLE_ID)
-  if (existing?.tagName === 'STYLE')
-    return existing as HTMLStyleElement
-
-  existing?.remove()
-  const style = document.createElement('style')
-  style.id = RUNTIME_THEME_STYLE_ID
-  style.setAttribute('data-cp-runtime-theme', '')
-  document.head.append(style)
-  return style
-}
-
-function serializeTheme(theme: ResolvedTheme): string {
-  const declarations = Object.entries(theme.tokens)
-    .map(([name, value]) => `  ${name}: ${value};`)
-    .join('\n')
-
-  return `:root[data-theme='${theme.name}'][data-theme-color='${theme.colorId}'] {\n  color-scheme: ${theme.name};\n${declarations}\n}\n`
-}
diff --git a/frontend/src/theme/types.ts b/frontend/src/theme/types.ts
deleted file mode 100644
index 1d3963d1b..000000000
--- a/frontend/src/theme/types.ts
+++ /dev/null
@@ -1,366 +0,0 @@
-export type ThemeMode = 'system' | 'light' | 'dark'
-export type ThemeName = 'light' | 'dark'
-export type ThemeColorPresetId = 'relay-blue' | 'deep-teal' | 'signal-violet' | 'graphite'
-export type ThemeColorId = ThemeColorPresetId | 'custom'
-
-export interface ThemeColorPreset {
-  id: ThemeColorPresetId
-  label: string
-  description: string
-  seed: string
-  appearance?: Partial<Record<ThemeName, ThemeAppearanceSeed>>
-}
-
-/** 品牌 Seed 派生出的界面底色与正文基色。 */
-export interface ThemeAppearanceSeed {
-  colorBgBase: string
-  colorTextBase: string
-}
-
-export interface ThemeSeedOverrides {
-  colorSuccess?: string
-  colorWarning?: string
-  colorError?: string
-  colorInfo?: string
-  colorLink?: string
-  colorTextBase?: string
-  colorBgBase?: string
-  fontSize?: number
-  sizeUnit?: number
-  sizeStep?: number
-  controlHeight?: number
-  borderRadius?: number
-  shadowStrength?: number
-}
-
-export interface ThemeComponentOverrides {
-  tableRowHeight?: number
-  cardBorderRadius?: number
-}
-
-export interface ThemeCustomization {
-  seed?: ThemeSeedOverrides
-  component?: ThemeComponentOverrides
-  tokenOverrides?: Partial<ThemeTokens>
-}
-
-export interface ResolvedThemeSeedTokens {
-  colorPrimary: string
-  colorSuccess: string
-  colorWarning: string
-  colorError: string
-  colorInfo: string
-  colorLink: string
-  colorTextBase: string
-  colorBgBase: string
-  fontSize: number
-  sizeUnit: number
-  sizeStep: number
-  controlHeight: number
-  borderRadius: number
-  shadowStrength: number
-}
-
-export interface ResolvedTheme {
-  name: ThemeName
-  colorId: ThemeColorId
-  seed: string
-  seedTokens: ResolvedThemeSeedTokens
-  tokens: ThemeTokens
-}
-
-export interface RgbColor {
-  red: number
-  green: number
-  blue: number
-}
-
-export interface ColorToneOptions {
-  hueWeight?: number
-  saturationScale?: number
-  saturationLimit?: number
-}
-
-export type ThemePaletteStep = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10
-export type ThemePaletteSource = ThemePaletteStep | 'seed'
-
-export interface ThemeColorRoleRecipe {
-  color: ThemePaletteSource
-  hover: ThemePaletteSource
-  active: ThemePaletteSource
-  textHover: ThemePaletteSource
-  text: ThemePaletteSource
-  onContainer?: ThemePaletteSource
-  textActive: ThemePaletteSource
-  containerMix: number
-  containerHoverMix: number
-  containerActiveMix: number
-  borderMix: number
-  borderHoverMix: number
-  hoverContrast?: number
-  activeContrast?: number
-  minimumTextLightness?: number
-}
-
-export interface ThemeColorRoleRecipes {
-  primary: ThemeColorRoleRecipe
-  semantic: ThemeColorRoleRecipe
-  preset: ThemePresetColorRoleRecipe
-}
-
-export interface ThemePresetColorRoleRecipe {
-  solid: ThemePaletteStep
-  text: ThemePaletteStep
-  onContainer: ThemePaletteStep
-  containerMix: number
-  containerStrongMix: number
-  borderMix: number
-  minimumTextLightness?: number
-}
-
-export interface ThemePrimaryMap {
-  colorPrimaryContainer: string
-  colorPrimaryContainerHover: string
-  colorPrimaryBorder: string
-  colorPrimaryBorderHover: string
-  colorPrimaryHover: string
-  colorPrimary: string
-  colorPrimaryActive: string
-  colorPrimaryTextHover: string
-  colorPrimaryText: string
-  colorPrimaryOnContainer: string
-  colorPrimaryTextActive: string
-  colorTextLightSolid: string
-}
-
-export interface ThemeLinkMap {
-  colorLink: string
-  colorLinkHover: string
-  colorLinkActive: string
-}
-
-export interface ThemeSurfaceMap {
-  colorBgLayout: string
-  colorBgContainer: string
-  colorBgElevated: string
-  colorBgSpotlight: string
-  colorBgMask: string
-  colorBgTextHover: string
-  colorBgTextActive: string
-  colorBgContainerDisabled: string
-  colorFillSecondary: string
-  colorFillTertiary: string
-  colorFillQuaternary: string
-  colorBorder: string
-  colorBorderSecondary: string
-  colorSplit: string
-  colorText: string
-  colorTextHeading: string
-  colorTextSecondary: string
-  colorTextTertiary: string
-  colorTextQuaternary: string
-  colorTextDisabled: string
-  colorShadow: string
-}
-
-export interface ThemeAliasMap {
-  colorFillAlter: string
-}
-
-export interface ThemeShadowMap {
-  boxShadow: string
-  boxShadowSecondary: string
-  boxShadowTertiary: string
-}
-
-/** 中性填充的派生中间值，不直接暴露为全局 CSS Token。 */
-export interface ThemeFillMap {
-  controlBg: string
-  controlHoverBg: string
-  controlActiveBg: string
-  contentBg: string
-  contentStripeBg: string
-  contentHoverBg: string
-}
-
-export interface ThemeComponentMap {
-  menuItemSelectedBg: string
-  inputBg: string
-  inputHoverBg: string
-  inputActiveBg: string
-  inputErrorActiveBg: string
-  buttonPrimaryColor: string
-  buttonPrimaryBg: string
-  buttonPrimaryHoverBg: string
-  buttonPrimaryActiveBg: string
-  buttonSecondaryBg: string
-  buttonSecondaryHoverBg: string
-  buttonSecondaryActiveBg: string
-  iconButtonSecondaryBg: string
-  iconButtonSecondaryHoverBg: string
-  iconButtonSecondaryActiveBg: string
-  brandMarkBg: string
-  cardBg: string
-  modalBg: string
-  popoverHeaderBg: string
-  tableHeaderBg: string
-  tableRowBg: string
-  tableRowStripeBg: string
-  tableRowHoverBg: string
-  tableRowSelectedBg: string
-  tableRowSelectedHoverBg: string
-  progressRemainingColor: string
-  layoutSiderBg: string
-  cardShadow: string
-  inputShadow: string
-  inputHoverShadow: string
-  inputActiveShadow: string
-  inputErrorActiveShadow: string
-  layoutSiderShadow: string
-  scrollbarThumbBg: string
-  scrollbarThumbHoverBg: string
-}
-
-export interface FunctionalColorMap {
-  color: string
-  hover: string
-  active: string
-  container: string
-  containerHover: string
-  containerActive: string
-  border: string
-  borderHover: string
-  textHover: string
-  /** 语义色在中性表面上的强调文字。 */
-  text: string
-  /** 语义色容器内文字与图标使用的高对比前景色。 */
-  onContainer: string
-  textActive: string
-}
-
-export interface ThemeSemanticMap {
-  info: FunctionalColorMap
-  success: FunctionalColorMap
-  warning: FunctionalColorMap
-  error: FunctionalColorMap
-}
-
-export interface PresetColorRoleMap {
-  container: string
-  containerStrong: string
-  border: string
-  solid: string
-  text: string
-  onContainer: string
-}
-
-export type ThemePresetColorName
-  = 'blue'
-    | 'cyan'
-    | 'green'
-    | 'orange'
-    | 'purple'
-    | 'red'
-
-export type ThemePresetColorMap = Record<ThemePresetColorName, PresetColorRoleMap>
-
-export interface ThemeDataMap {
-  activityLevels: readonly [string, string, string, string, string]
-}
-
-export interface ThemeDimensionMap {
-  fontSizeXs: string
-  fontSizeSm: string
-  fontSize: string
-  fontSizeLg: string
-  fontSizeXl: string
-  lineHeightXs: string
-  lineHeightSm: string
-  lineHeight: string
-  lineHeightLg: string
-  lineHeightXl: string
-  sizeUnit: string
-  sizeStep: string
-  controlHeightSm: string
-  controlHeight: string
-  controlHeightLg: string
-  tableRowHeight: string
-  tableRowHeightSm: string
-  borderRadiusSm: string
-  borderRadius: string
-  borderRadiusLg: string
-  cardBorderRadius: string
-}
-
-export interface ThemeMap {
-  surfaces: ThemeSurfaceMap
-  aliases: ThemeAliasMap
-  primary: ThemePrimaryMap
-  link: ThemeLinkMap
-  semantics: ThemeSemanticMap
-  presetColors: ThemePresetColorMap
-  data: ThemeDataMap
-  shadows: ThemeShadowMap
-  components: ThemeComponentMap
-  dimensions: ThemeDimensionMap
-}
-
-export type DirectThemeMapKey = Exclude<
-  keyof ThemeMap,
-  'semantics' | 'presetColors' | 'data'
->
-
-type CamelToKebab<Value extends string> = Value extends `${infer Head}${infer Tail}`
-  ? Tail extends Uncapitalize<Tail>
-    ? `${Lowercase<Head>}${CamelToKebab<Tail>}`
-    : `${Lowercase<Head>}-${CamelToKebab<Tail>}`
-  : Value
-
-export type DirectTokenName = {
-  [Group in DirectThemeMapKey]: `--cp-${CamelToKebab<Extract<keyof ThemeMap[Group], string>>}`
-}[DirectThemeMapKey]
-
-export type FunctionalTokenSuffix
-  = ''
-    | '-hover'
-    | '-active'
-    | '-container'
-    | '-container-hover'
-    | '-container-active'
-    | '-border'
-    | '-border-hover'
-    | '-text-hover'
-    | '-text'
-    | '-on-container'
-    | '-text-active'
-
-type SemanticColorName = Extract<keyof ThemeSemanticMap, string>
-export type SemanticTokenName = `--cp-color-${SemanticColorName}${FunctionalTokenSuffix}`
-
-export type PresetTokenSuffix
-  = 'container'
-    | 'container-strong'
-    | 'border'
-    | 'solid'
-    | 'text'
-    | 'on-container'
-
-type PresetColorName = Extract<keyof ThemePresetColorMap, string>
-export type PresetTokenName = `--cp-color-${PresetColorName}-${PresetTokenSuffix}`
-
-export type ActivityLevel = 0 | 1 | 2 | 3 | 4
-type ActivityTokenName = `--cp-activity-level-${ActivityLevel}`
-
-export type ControlTokenName
-  = '--cp-control-item-bg-active'
-    | '--cp-control-item-bg-active-hover'
-    | '--cp-control-outline'
-
-export type ThemeTokenName
-  = DirectTokenName
-    | SemanticTokenName
-    | PresetTokenName
-    | ActivityTokenName
-    | ControlTokenName
-
-export type ThemeTokens = Record<ThemeTokenName, string>
diff --git a/frontend/src/utils/color.ts b/frontend/src/utils/color.ts
deleted file mode 100644
index 0e81bbbc8..000000000
--- a/frontend/src/utils/color.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-const HEX_COLOR_PATTERN = /^#[0-9A-F]{6}$/i
-const RGBA_HEX_COLOR_PATTERN = /^#[0-9A-F]{8}$/i
-
-export function normalizeHexColor(value: unknown) {
-  if (typeof value !== 'string')
-    return null
-  const normalized = value.trim().toUpperCase()
-  return HEX_COLOR_PATTERN.test(normalized) ? normalized : null
-}
-
-export function normalizeRgbaHexColor(value: unknown) {
-  if (typeof value !== 'string')
-    return null
-  const normalized = value.trim().toUpperCase()
-  return RGBA_HEX_COLOR_PATTERN.test(normalized) ? normalized : null
-}
diff --git a/frontend/src/utils/jsonObject.ts b/frontend/src/utils/jsonObject.ts
new file mode 100644
index 000000000..3de20944e
--- /dev/null
+++ b/frontend/src/utils/jsonObject.ts
@@ -0,0 +1,26 @@
+import { isRecord } from '@/utils/object'
+
+export function parseJsonObject(text: string, maximumBytes?: number): Record<string, unknown> {
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  }
+  catch {
+    throw new Error('请输入有效的 JSON 对象')
+  }
+  if (!isRecord(value))
+    throw new Error('输入必须是 JSON 对象')
+  if (maximumBytes !== undefined && new TextEncoder().encode(JSON.stringify(value)).byteLength > maximumBytes)
+    throw new Error(`输入不能超过 ${maximumBytes / 1024} KiB`)
+  return value
+}
+
+export function jsonObjectError(text: string, maximumBytes?: number) {
+  try {
+    parseJsonObject(text, maximumBytes)
+    return undefined
+  }
+  catch (error) {
+    return (error as Error).message
+  }
+}
diff --git a/frontend/src/utils/providers.ts b/frontend/src/utils/providers.ts
index 2c7f70b4d..02b94e26f 100644
--- a/frontend/src/utils/providers.ts
+++ b/frontend/src/utils/providers.ts
@@ -1,3 +1,7 @@
+import type { Component } from 'vue'
+import { Key, LinkAlt, Openai, Xai } from '@boxicons/vue'
+import { Fingerprint, Plug } from '@lucide/vue'
+
 export const PROVIDER_DISPLAY_NAMES = {
   openai: 'OpenAI',
   xai: 'xAI',
@@ -6,7 +10,7 @@ export const PROVIDER_DISPLAY_NAMES = {
 export type SupportedProvider = keyof typeof PROVIDER_DISPLAY_NAMES
 
 export function isSupportedProvider(value: unknown): value is SupportedProvider {
-  return typeof value === 'string' && value in PROVIDER_DISPLAY_NAMES
+  return typeof value === 'string' && Object.hasOwn(PROVIDER_DISPLAY_NAMES, value)
 }
 
 export function providerDisplayName(value?: string | null) {
@@ -17,3 +21,30 @@ export function formatProviderLabel(value?: string | null, fallback = '—') {
   const normalized = value?.trim()
   return providerDisplayName(normalized?.toLowerCase()) ?? (normalized || fallback)
 }
+
+export function providerIcon(value: string): Component {
+  switch (value.trim().toLowerCase()) {
+    case 'openai': return Openai
+    case 'xai': return Xai
+    default: return Plug
+  }
+}
+
+export function formatAuthenticationLabel(value?: string | null) {
+  const normalized = value?.trim()
+  switch (normalized?.toLowerCase()) {
+    case 'oauth': return 'OAuth'
+    case 'api_key': return 'API Key'
+    default: return normalized ? `自定义认证 · ${normalized}` : '未知认证类型'
+  }
+}
+
+export function authenticationIcon(value?: string | null): Component | undefined {
+  switch (value?.trim().toLowerCase()) {
+    case 'oauth': return LinkAlt
+    case 'api_key': return Key
+    case undefined:
+    case '': return undefined
+    default: return Fingerprint
+  }
+}
diff --git a/frontend/src/views/accounts/components/AccountApiKeyFields.vue b/frontend/src/views/accounts/components/AccountApiKeyFields.vue
index e9a713397..51e970699 100644
--- a/frontend/src/views/accounts/components/AccountApiKeyFields.vue
+++ b/frontend/src/views/accounts/components/AccountApiKeyFields.vue
@@ -1,8 +1,6 @@
 <script setup lang="ts">
 import type { ApiKeyAccountForm } from '../utils/upstreamApiKey'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
+import { BaseFormItem, BaseInput, BaseSegmented } from '@codex-proxy/ui'
 
 defineProps<{ disabled?: boolean, editing?: boolean }>()
 const form = defineModel<ApiKeyAccountForm>({ required: true })
diff --git a/frontend/src/views/accounts/components/AccountBatchEditModal.vue b/frontend/src/views/accounts/components/AccountBatchEditModal.vue
index e923550d7..959858f2c 100644
--- a/frontend/src/views/accounts/components/AccountBatchEditModal.vue
+++ b/frontend/src/views/accounts/components/AccountBatchEditModal.vue
@@ -1,8 +1,7 @@
 <script setup lang="ts">
 import type { AccountGroup, AccountModelAccess } from '@/api'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
+import { BaseButton, BaseModal } from '@codex-proxy/ui'
 import AccountSettingsFields from './AccountSettingsFields.vue'
 
 defineProps<{
diff --git a/frontend/src/views/accounts/components/AccountConnectionTestModal.vue b/frontend/src/views/accounts/components/AccountConnectionTestModal.vue
index 660c82fbe..eb87ab550 100644
--- a/frontend/src/views/accounts/components/AccountConnectionTestModal.vue
+++ b/frontend/src/views/accounts/components/AccountConnectionTestModal.vue
@@ -1,11 +1,8 @@
 <script setup lang="ts">
 import type { useAccountConnectionTest } from '../composables/useAccountConnectionTest'
 
+import { BaseButton, BaseIconButton, BaseModal, BaseSelect } from '@codex-proxy/ui'
 import { RefreshCw } from '@lucide/vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
 import AccountIdentityCell from './AccountIdentityCell.vue'
 import AccountStatusBadge from './AccountStatusBadge/index.vue'
 
diff --git a/frontend/src/views/accounts/components/AccountCreateModal/AccountImportFields.vue b/frontend/src/views/accounts/components/AccountCreateModal/AccountImportFields.vue
index 39b7b97d9..a7c846067 100644
--- a/frontend/src/views/accounts/components/AccountCreateModal/AccountImportFields.vue
+++ b/frontend/src/views/accounts/components/AccountCreateModal/AccountImportFields.vue
@@ -1,10 +1,8 @@
 <script setup lang="ts">
+import { BaseButton, BaseFormItem, BaseTextarea } from '@codex-proxy/ui'
 import { Upload } from '@lucide/vue'
 import { useFileDialog } from '@vueuse/core'
 import { onScopeDispose, ref } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseTextarea from '@/components/base/BaseTextarea.vue'
 
 defineProps<{
   label: string
diff --git a/frontend/src/views/accounts/components/AccountCreateModal/AccountOAuthFields.vue b/frontend/src/views/accounts/components/AccountCreateModal/AccountOAuthFields.vue
index bc1b1e469..4b893f050 100644
--- a/frontend/src/views/accounts/components/AccountCreateModal/AccountOAuthFields.vue
+++ b/frontend/src/views/accounts/components/AccountCreateModal/AccountOAuthFields.vue
@@ -1,14 +1,11 @@
 <script setup lang="ts">
+import type { AccountAuthorizationView } from '../../composables/useAccountAuthorization'
+import { BaseButton, BaseForm, BaseFormItem, BaseIconButton, BaseScrollbar, BaseTextarea } from '@codex-proxy/ui'
 import { Copy, KeyRound } from '@lucide/vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
-import BaseTextarea from '@/components/base/BaseTextarea.vue'
+import { computed } from 'vue'
 import { useCopyText } from '@/composables/useCopyText'
 
-defineProps<{
+const props = defineProps<{
   authUrl: string
   panelTitle: string
   panelDescription: string
@@ -16,10 +13,33 @@ defineProps<{
   callbackPlaceholder: string
   loading: boolean
   disabled: boolean
+  authorization: AccountAuthorizationView
+  canStart: boolean
+  poll: boolean
 }>()
-const emit = defineEmits<{ regenerate: [] }>()
+const emit = defineEmits<{ regenerate: [], reset: [] }>()
 const callback = defineModel<string>({ required: true })
 const copyWithToast = useCopyText()
+const safeAuthUrl = computed(() => {
+  try {
+    const url = new URL(props.authUrl)
+    return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password ? url.href : undefined
+  }
+  catch {
+    return undefined
+  }
+})
+const statusText = computed(() => {
+  if (props.authorization.status === 'expired')
+    return '授权已过期，可重新开始或检查已完成的授权结果'
+  if (props.authorization.status === 'paused')
+    return '查询已暂停，可检查授权结果后继续'
+  if (props.authorization.status === 'polling')
+    return '正在检查授权结果'
+  if (props.authorization.flow && props.poll)
+    return '等待浏览器授权，完成后将自动更新'
+  return ''
+})
 </script>
 
 <template>
@@ -46,11 +66,12 @@ const copyWithToast = useCopyText()
       <BaseButton
         variant="secondary"
         :loading="loading"
-        :disabled="disabled"
-        @click="emit('regenerate')"
+        :disabled="disabled || (!authorization.flow && !canStart)"
+        @click="authorization.flow ? emit('reset') : emit('regenerate')"
       >
-        {{ authUrl ? '重新生成授权链接' : '生成授权链接' }}
+        {{ authorization.flow ? '重新开始授权' : '生成授权链接' }}
       </BaseButton>
+      <a v-if="safeAuthUrl" :href="safeAuthUrl" target="_blank" rel="noopener noreferrer" class="text-cp-sm text-cp-link underline underline-offset-4">打开授权页面</a>
     </div>
 
     <BaseForm v-if="authUrl">
@@ -78,8 +99,15 @@ const copyWithToast = useCopyText()
       </BaseFormItem>
     </BaseForm>
 
-    <BaseForm>
-      <BaseFormItem :label="callbackLabel" required>
+    <p v-if="statusText" class="m-0 text-cp-sm text-cp-text-secondary" role="status">
+      {{ statusText }}
+    </p>
+    <p v-if="authorization.error" class="m-0 text-cp-sm text-cp-error" role="alert">
+      {{ authorization.error }}
+    </p>
+
+    <BaseForm v-if="authorization.flow">
+      <BaseFormItem :label="callbackLabel" :required="!poll">
         <BaseTextarea
           v-model="callback"
           :aria-label="callbackLabel"
diff --git a/frontend/src/views/accounts/components/AccountCreateModal/AccountProviderChooser.vue b/frontend/src/views/accounts/components/AccountCreateModal/AccountProviderChooser.vue
index 1dc849d8d..2bf30d196 100644
--- a/frontend/src/views/accounts/components/AccountCreateModal/AccountProviderChooser.vue
+++ b/frontend/src/views/accounts/components/AccountCreateModal/AccountProviderChooser.vue
@@ -1,57 +1,50 @@
 <script setup lang="ts">
-import type { AccountCreateProvider } from './model'
-import { Openai, Xai } from '@boxicons/vue'
+import type { AccountCreateSource } from './model'
+import type { AccountProvider } from '@/api'
+import { BaseSegmented } from '@codex-proxy/ui'
 import { LayoutGrid } from '@lucide/vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import { PROVIDER_DISPLAY_NAMES } from '@/utils/providers'
+import { computed } from 'vue'
+import { formatProviderLabel, providerIcon } from '@/utils/providers'
 
-withDefaults(
-  defineProps<{
-    disabled?: boolean
-    selected?: AccountCreateProvider | ''
-  }>(),
-  {
-    disabled: false,
-  },
-)
-
-const emit = defineEmits<{
-  select: [provider: 'openai' | 'xai' | 'batch']
+const props = defineProps<{
+  providers: AccountProvider[]
+  disabled: boolean
 }>()
+const source = defineModel<AccountCreateSource | null>({ required: true })
 
-const providers = [
-  {
-    value: 'batch' as const,
-    label: '批量导入',
-    icon: LayoutGrid,
+const options = computed(() => [
+  ...(props.providers.some(provider => provider.credentials.import)
+    ? [{ value: 'bundle', label: '批量导入', icon: LayoutGrid }]
+    : []),
+  ...props.providers
+    .filter(provider => provider.credentials.import || provider.credentials.login)
+    .map(provider => ({
+      value: `provider:${provider.provider}`,
+      label: formatProviderLabel(provider.provider),
+      icon: providerIcon(provider.provider),
+    })),
+])
+const selected = computed({
+  get: () => source.value?.kind === 'provider' ? `provider:${source.value.id}` : source.value?.kind ?? '',
+  set: (value: string) => {
+    if (!options.value.some(option => option.value === value))
+      return
+    source.value = value === 'bundle' ? { kind: 'bundle' } : { kind: 'provider', id: value.slice('provider:'.length) }
   },
-  {
-    value: 'openai' as const,
-    label: PROVIDER_DISPLAY_NAMES.openai,
-    icon: Openai,
-  },
-  {
-    value: 'xai' as const,
-    label: PROVIDER_DISPLAY_NAMES.xai,
-    icon: Xai,
-  },
-]
-
-function selectProvider(value: string) {
-  const provider = providers.find(provider => provider.value === value)
-  if (provider)
-    emit('select', provider.value)
-}
+})
 </script>
 
 <template>
   <BaseSegmented
-    :model-value="selected ?? ''"
+    v-if="options.length"
+    v-model="selected"
+    class="w-full"
     label="选择账号平台"
-    :options="providers"
+    :options="options"
     :disabled="disabled"
     size="lg"
-    class="w-full"
-    @update:model-value="selectProvider"
   />
+  <p v-else class="m-0 text-cp-sm text-cp-text-tertiary">
+    暂无可录入账号的平台
+  </p>
 </template>
diff --git a/frontend/src/views/accounts/components/AccountCreateModal/AccountSetupFields.vue b/frontend/src/views/accounts/components/AccountCreateModal/AccountSetupFields.vue
index f90013fe9..0ab18b3dd 100644
--- a/frontend/src/views/accounts/components/AccountCreateModal/AccountSetupFields.vue
+++ b/frontend/src/views/accounts/components/AccountCreateModal/AccountSetupFields.vue
@@ -1,8 +1,7 @@
 <script setup lang="ts">
 import type { AccountCreateForm } from './model'
-import type { AccountGroup } from '@/api'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseTextarea from '@/components/base/BaseTextarea.vue'
+import type { AccountGroup, AccountProvider } from '@/api'
+import { BaseFormItem, BaseTextarea } from '@codex-proxy/ui'
 import AccountSettingsFields from '../AccountSettingsFields.vue'
 import AccountProviderChooser from './AccountProviderChooser.vue'
 
@@ -10,6 +9,7 @@ defineProps<{
   groups: AccountGroup[]
   groupsLoading: boolean
   disabled: boolean
+  providers: AccountProvider[]
   proxyError?: string
 }>()
 const form = defineModel<AccountCreateForm>({ required: true })
@@ -21,7 +21,7 @@ const form = defineModel<AccountCreateForm>({ required: true })
       <legend class="mb-3 p-0 text-cp font-medium text-cp-text-secondary">
         账号平台
       </legend>
-      <AccountProviderChooser :selected="form.provider" :disabled="disabled" @select="form.provider = $event" />
+      <AccountProviderChooser v-model="form.source" :providers="providers" :disabled="disabled" />
     </fieldset>
     <AccountSettingsFields
       v-model:enabled="form.enabled"
diff --git a/frontend/src/views/accounts/components/AccountCreateModal/index.vue b/frontend/src/views/accounts/components/AccountCreateModal/index.vue
index 1c07583f3..2d15216d2 100644
--- a/frontend/src/views/accounts/components/AccountCreateModal/index.vue
+++ b/frontend/src/views/accounts/components/AccountCreateModal/index.vue
@@ -1,16 +1,16 @@
 <script setup lang="ts">
+import type { AccountAuthorizationView } from '../../composables/useAccountAuthorization'
 import type { AccountRow } from '../../constants'
 import type { AccountCreateForm, AccountImportMode } from './model'
-import type { AccountGroup } from '@/api'
+import type { AccountGroup, AccountProvider } from '@/api'
 import { Openai, Xai } from '@boxicons/vue'
-import { Copy, LayoutGrid, Settings2 } from '@lucide/vue'
+import { BaseButton, BaseIconButton, BaseModal, BaseSegmented } from '@codex-proxy/ui'
+import { Copy, LayoutGrid, Plug, Settings2 } from '@lucide/vue'
 import { computed } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
 import ProviderIconGroup from '@/components/ProviderIconGroup.vue'
+import SchemaForm from '@/components/SchemaForm/index.vue'
 import { useCopyText } from '@/composables/useCopyText'
+import { jsonObjectError } from '@/utils/jsonObject'
 import { accountModelAccessError } from '../../utils/modelAccess'
 import { parseAccountSchedulingForm } from '../../utils/schedulingForm'
 import AccountApiKeyFields from '../AccountApiKeyFields.vue'
@@ -19,7 +19,7 @@ import AccountPlanBadge from '../AccountPlanBadge.vue'
 import AccountImportFields from './AccountImportFields.vue'
 import AccountOAuthFields from './AccountOAuthFields.vue'
 import AccountSetupFields from './AccountSetupFields.vue'
-import { accountProxyError } from './model'
+import { accountCreateProvider, accountCreateSourceKey, accountProxyError } from './model'
 import { resolveAccountCreatePresentation } from './presenter'
 
 const props = withDefaults(defineProps<{
@@ -29,11 +29,16 @@ const props = withDefaults(defineProps<{
   oauthLoading?: boolean
   reauthorizing?: boolean
   account?: AccountRow | null
+  providers: AccountProvider[]
+  providersLoading: boolean
+  providersError: string
+  authorization: AccountAuthorizationView
 }>(), { saving: false, oauthLoading: false, reauthorizing: false, account: null })
 
-const emit = defineEmits<{ create: [], generateOauth: [] }>()
+const emit = defineEmits<{ create: [], generateOauth: [], resetAuthorization: [], reloadProviders: [] }>()
 const open = defineModel<boolean>({ default: false })
 const form = defineModel<AccountCreateForm>('form', { required: true })
+const callback = defineModel<string>('callback', { required: true })
 const copyWithToast = useCopyText()
 const accountCopyValue = computed(() =>
   props.account?.email?.trim()
@@ -42,14 +47,22 @@ const accountCopyValue = computed(() =>
   || '',
 )
 const busy = computed(() => props.saving || props.oauthLoading)
+const provider = computed(() => props.providers.find(provider => provider.provider === accountCreateProvider(form.value)))
+const catalogReady = computed(() => !props.providersLoading && !props.providersError)
+const canSelect = computed(() => catalogReady.value && (form.value.source?.kind === 'bundle'
+  ? props.providers.some(provider => provider.credentials.import)
+  : Boolean(provider.value?.credentials.import || provider.value?.credentials.login)))
+const inputKey = computed(() => accountCreateSourceKey(form.value))
+const loginInputError = computed(() => jsonObjectError(form.value.loginInput, 64 * 1024))
 const proxyError = computed(() => accountProxyError(form.value))
 const modelError = computed(() => accountModelAccessError(form.value.modelAccess))
 const scheduling = computed(() => parseAccountSchedulingForm(form.value.concurrencyLimit, form.value.weight))
 const view = computed(() => resolveAccountCreatePresentation({
   form: form.value,
-  account: props.account,
-  saving: props.saving,
-  oauthLoading: props.oauthLoading,
+  provider: provider.value,
+  authorization: props.authorization,
+  callback: callback.value,
+  busy: busy.value || (!catalogReady.value && !props.authorization.flow),
   reauthorizing: props.reauthorizing,
 }))
 const mode = computed({
@@ -60,15 +73,15 @@ const mode = computed({
   },
 })
 const importText = computed({
-  get: () => form.value.mode === 'oauth' || form.value.mode === 'api_key' ? '' : form.value.importTexts[form.value.mode],
+  get: () => form.value.mode === 'oauth' || form.value.mode === 'api_key' || form.value.mode === 'form' ? '' : form.value.importTexts[form.value.mode],
   set: (value: string) => {
-    if (form.value.mode !== 'oauth' && form.value.mode !== 'api_key')
+    if (form.value.mode !== 'oauth' && form.value.mode !== 'api_key' && form.value.mode !== 'form')
       form.value.importTexts[form.value.mode] = value
   },
 })
 
 function continueToImport() {
-  if (form.value.provider && !modelError.value && scheduling.value.valid && !props.groupsLoading && !proxyError.value && !busy.value)
+  if (canSelect.value && !modelError.value && scheduling.value.valid && !props.groupsLoading && !proxyError.value && !busy.value)
     form.value.step = 'import'
 }
 </script>
@@ -85,11 +98,23 @@ function continueToImport() {
     <template #icon>
       <Settings2 v-if="view.configuring" class="text-cp-text" :size="20" aria-hidden="true" />
       <LayoutGrid v-else-if="view.isBatch" class="text-cp-text" :size="20" aria-hidden="true" />
-      <Xai v-else-if="view.isXai" class="text-cp-text" :width="20" :height="20" aria-hidden="true" />
-      <Openai v-else class="text-cp-text" :width="20" :height="20" aria-hidden="true" />
+      <Xai v-else-if="view.provider === 'xai'" class="text-cp-text" :width="20" :height="20" aria-hidden="true" />
+      <Openai v-else-if="view.provider === 'openai'" class="text-cp-text" :width="20" :height="20" aria-hidden="true" />
+      <Plug v-else class="text-cp-text" :size="20" aria-hidden="true" />
     </template>
 
     <div class="grid gap-4">
+      <p v-if="providersLoading" class="m-0 text-cp-sm text-cp-text-secondary" role="status">
+        正在加载平台能力
+      </p>
+      <div v-else-if="providersError || (form.source && !canSelect)" class="flex items-center justify-between gap-3">
+        <p class="m-0 text-cp-sm text-cp-error" role="alert">
+          {{ providersError || '当前平台不可录入账号，请刷新列表或选择其他平台' }}
+        </p>
+        <BaseButton variant="secondary" size="sm" :disabled="busy" @click="emit('reloadProviders')">
+          重试
+        </BaseButton>
+      </div>
       <div
         v-if="reauthorizing && account"
         class="flex flex-wrap items-center justify-between gap-4 rounded-cp bg-cp-fill-quaternary px-4 py-3.5"
@@ -124,7 +149,8 @@ function continueToImport() {
       <AccountSetupFields
         v-if="view.configuring"
         v-model="form"
-        :disabled="busy"
+        :disabled="busy || !catalogReady"
+        :providers="providers"
         :groups="groups"
         :groups-loading="groupsLoading"
         :proxy-error="form.proxyId.trim() ? proxyError : undefined"
@@ -138,24 +164,43 @@ function continueToImport() {
           v-model="mode"
           label="账号添加方式"
           :options="view.modeOptions"
-          :disabled="busy"
+          :disabled="busy || !catalogReady"
           class="w-full"
         />
+        <SchemaForm
+          v-if="mode === 'oauth' && provider?.credentials.login && !authorization.flow"
+          :key="`${inputKey}:login`"
+          v-model="form.loginInput"
+          :schema="provider.credentials.login.inputSchema"
+          :maximum-bytes="64 * 1024"
+          :disabled="busy || !catalogReady"
+        />
         <AccountOAuthFields
           v-if="mode === 'oauth'"
-          v-model="form.oauthCallback"
-          :auth-url="view.oauth.authUrl"
-          :panel-title="`${view.isXai ? 'xAI' : 'OpenAI'} OAuth ${reauthorizing ? '重新授权' : '授权'}`"
-          :panel-description="view.isXai ? '生成并打开授权链接、完成浏览器授权、粘贴回调地址或授权码' : '生成并打开授权链接、完成浏览器授权、粘贴回调地址'"
+          v-model="callback"
+          :auth-url="authorization.flow?.authorizationUrl ?? ''"
+          :authorization="authorization"
+          :can-start="catalogReady && Boolean(provider?.credentials.login) && !loginInputError"
+          :poll="view.oauth.poll"
+          :panel-title="`${view.label} ${reauthorizing ? '重新授权' : '授权'}`"
+          :panel-description="view.oauth.description"
           :loading="oauthLoading"
           :callback-label="view.oauth.callbackLabel"
           :callback-placeholder="view.oauth.callbackPlaceholder"
           :disabled="busy"
           @regenerate="emit('generateOauth')"
+          @reset="emit('resetAuthorization')"
         />
         <AccountApiKeyFields v-else-if="mode === 'api_key'" v-model="form.apiKey" :disabled="busy" />
+        <SchemaForm
+          v-else-if="mode === 'form' && provider?.credentials.import"
+          :key="`${inputKey}:import`"
+          v-model="form.importInput"
+          :schema="provider.credentials.import"
+          :disabled="busy || !catalogReady"
+        />
         <AccountImportFields
-          v-else
+          v-else-if="mode !== 'form'"
           :key="mode"
           v-model="importText"
           :label="view.importInput.label"
@@ -173,7 +218,7 @@ function continueToImport() {
       <BaseButton v-else class="mr-auto" variant="secondary" :disabled="busy" @click="form.step = 'settings'">
         上一步
       </BaseButton>
-      <BaseButton v-if="view.configuring" variant="primary" :disabled="!form.provider || !scheduling.valid || groupsLoading || Boolean(proxyError) || busy" @click="continueToImport">
+      <BaseButton v-if="view.configuring" variant="primary" :disabled="!canSelect || !scheduling.valid || Boolean(modelError) || groupsLoading || Boolean(proxyError) || busy" @click="continueToImport">
         继续导入
       </BaseButton>
       <BaseButton v-else variant="primary" :loading="saving || oauthLoading" :disabled="!view.canSubmit" @click="emit('create')">
diff --git a/frontend/src/views/accounts/components/AccountCreateModal/model.ts b/frontend/src/views/accounts/components/AccountCreateModal/model.ts
index f38b52bd3..ae83f35a9 100644
--- a/frontend/src/views/accounts/components/AccountCreateModal/model.ts
+++ b/frontend/src/views/accounts/components/AccountCreateModal/model.ts
@@ -4,12 +4,12 @@ import { accountModelAccessError } from '../../utils/modelAccess'
 import { parseAccountSchedulingForm } from '../../utils/schedulingForm'
 import { emptyApiKeyAccountForm } from '../../utils/upstreamApiKey'
 
-export type AccountCreateProvider = 'batch' | 'openai' | 'xai'
-export type AccountImportMode = 'oauth' | 'api_key' | 'access_token' | 'refresh_token' | 'json'
-export type AccountImportInputMode = Exclude<AccountImportMode, 'oauth' | 'api_key'>
+export type AccountCreateSource = { kind: 'bundle' } | { kind: 'provider', id: string }
+export type AccountImportMode = 'oauth' | 'api_key' | 'access_token' | 'refresh_token' | 'json' | 'form'
+export type AccountImportInputMode = 'access_token' | 'refresh_token' | 'json'
 
 export interface AccountCreateForm {
-  provider: AccountCreateProvider | ''
+  source: AccountCreateSource | null
   apiKey: ApiKeyAccountForm
   notes: string
   enabled: boolean
@@ -20,16 +20,15 @@ export interface AccountCreateForm {
   step: 'settings' | 'import'
   mode: AccountImportMode
   importTexts: Record<AccountImportInputMode, string>
-  oauthFlowId: string
-  oauthAuthUrl: string
-  oauthCallback: string
+  loginInput: string
+  importInput: string
   proxyMode: string
   proxyId: string
 }
 
 export function emptyAccountCreateForm(): AccountCreateForm {
   return {
-    provider: '',
+    source: null,
     apiKey: emptyApiKeyAccountForm(),
     notes: '',
     enabled: true,
@@ -39,14 +38,21 @@ export function emptyAccountCreateForm(): AccountCreateForm {
     step: 'settings',
     mode: 'oauth',
     importTexts: { access_token: '', refresh_token: '', json: '' },
-    oauthFlowId: '',
-    oauthAuthUrl: '',
-    oauthCallback: '',
+    loginInput: '{}',
+    importInput: '{}',
     proxyMode: 'direct',
     proxyId: '',
   }
 }
 
+export function accountCreateProvider(form: AccountCreateForm) {
+  return form.source?.kind === 'provider' ? form.source.id : undefined
+}
+
+export function accountCreateSourceKey(form: AccountCreateForm) {
+  return form.source?.kind === 'provider' ? `provider:${form.source.id}` : form.source?.kind ?? ''
+}
+
 export function accountProxyError(form: AccountCreateForm): string | undefined {
   if (form.proxyMode !== 'proxy')
     return undefined
@@ -63,7 +69,7 @@ export function accountImportSettings(form: AccountCreateForm) {
   if (modelError)
     throw new Error(modelError)
   return {
-    modelAccess: form.modelAccess,
+    modelAccess: form.modelAccess ? { ...form.modelAccess, models: [...form.modelAccess.models] } : undefined,
     enabled: form.enabled,
     ...scheduling.values,
     groupIds: [...new Set(form.groupIds)],
diff --git a/frontend/src/views/accounts/components/AccountCreateModal/presenter.ts b/frontend/src/views/accounts/components/AccountCreateModal/presenter.ts
index c8d69683d..d6827249d 100644
--- a/frontend/src/views/accounts/components/AccountCreateModal/presenter.ts
+++ b/frontend/src/views/accounts/components/AccountCreateModal/presenter.ts
@@ -1,187 +1,98 @@
-import type { AccountRow } from '../../constants'
-import type { AccountCreateForm, AccountCreateProvider } from './model'
+import type { AccountAuthorizationView } from '../../composables/useAccountAuthorization'
+import type { AccountCreateForm, AccountImportMode } from './model'
+import type { AccountProvider } from '@/api'
+import { jsonObjectError } from '@/utils/jsonObject'
+import { formatProviderLabel } from '@/utils/providers'
 import { apiKeyAccountError } from '../../utils/upstreamApiKey'
+import { accountCreateProvider } from './model'
 
-interface AccountCreatePresentationInput {
-  form: AccountCreateForm
-  account: AccountRow | null
-  saving: boolean
-  oauthLoading: boolean
-  reauthorizing: boolean
+export function accountImportModes(provider: AccountProvider | undefined) {
+  const options: Array<{ label: string, value: AccountImportMode }> = []
+  if (provider?.credentials.login)
+    options.push({ label: provider.credentials.login.completion === 'callback' ? 'OAuth' : '登录', value: 'oauth' })
+  if (provider?.credentials.import) {
+    if (provider.provider === 'openai') {
+      options.push(
+        { label: 'API Key', value: 'api_key' },
+        { label: 'AT', value: 'access_token' },
+        { label: 'RT', value: 'refresh_token' },
+      )
+    }
+    else if (provider.provider !== 'xai') {
+      options.push({ label: '填写凭据', value: 'form' })
+    }
+    options.push({ label: '账号文件', value: 'json' })
+  }
+  return options
 }
 
-const modeOptions = {
-  openai: [
-    { label: 'OAuth', value: 'oauth' },
-    { label: 'API Key', value: 'api_key' },
-    { label: 'AT', value: 'access_token' },
-    { label: 'RT', value: 'refresh_token' },
-    { label: '账号文件', value: 'json' },
-  ],
-  xai: [
-    { label: 'OAuth', value: 'oauth' },
-    { label: '账号文件', value: 'json' },
-  ],
-} satisfies Record<Exclude<AccountCreateProvider, 'batch'>, Array<{ label: string, value: string }>>
-
-export function resolveAccountCreatePresentation(input: AccountCreatePresentationInput) {
-  const { form } = input
-  const provider = isAccountCreateProvider(form.provider) ? form.provider : undefined
+export function resolveAccountCreatePresentation(input: {
+  form: AccountCreateForm
+  provider: AccountProvider | undefined
+  authorization: AccountAuthorizationView
+  callback: string
+  busy: boolean
+  reauthorizing: boolean
+}) {
+  const { form, provider, authorization } = input
+  const id = accountCreateProvider(form)
+  const label = formatProviderLabel(id)
+  const isBatch = form.source?.kind === 'bundle'
   const configuring = !input.reauthorizing && form.step === 'settings'
-  const oauthAuthUrl = form.oauthAuthUrl || ''
+  const modes = accountImportModes(provider)
+  const available = isBatch || (form.mode === 'oauth' && Boolean(authorization.flow)) || modes.some(mode => mode.value === form.mode)
+  const poll = (authorization.completion ?? provider?.credentials.login?.completion) === 'poll'
+  let description = '粘贴或上传账号 JSON，匹配已有账号时更新凭据'
+  if (isBatch)
+    description = '粘贴或上传 CPR 账号包，一次导入多个平台账号'
+  else if (form.mode === 'oauth')
+    description = `通过浏览器授权导入 ${label} 账号`
+  else if (form.mode === 'api_key')
+    description = '接入 OpenAI Responses 兼容上游'
+  else if (form.mode === 'form')
+    description = `填写 ${label} 账号凭据`
+  else if (form.mode === 'access_token')
+    description = '逐行粘贴 Access Token，未包含 Refresh Token 时无法自动续期'
+  else if (form.mode === 'refresh_token')
+    description = '逐行粘贴 Refresh Token，导入时将自动换取 Access Token'
+
+  let canSubmit = available && !input.busy
+  if (form.mode === 'oauth')
+    canSubmit &&= Boolean(authorization.flow && (poll || input.callback.trim()) && authorization.status !== 'polling')
+  else if (form.mode === 'api_key')
+    canSubmit &&= !apiKeyAccountError(form.apiKey)
+  else if (form.mode === 'form')
+    canSubmit &&= !jsonObjectError(form.importInput)
+  else
+    canSubmit &&= Boolean(form.importTexts[form.mode].trim())
 
   return {
     configuring,
-    isXai: provider === 'xai',
-    isBatch: provider === 'batch',
-    modeOptions: resolveModeOptions(provider),
-    modal: resolveModal(input, provider, configuring),
-    oauth: resolveOAuth(provider, oauthAuthUrl),
-    importInput: resolveImportInput(form, provider),
-    canSubmit: canSubmit(input, provider, oauthAuthUrl),
-    submitLabel: resolveSubmitLabel(input, provider),
+    isBatch,
+    provider: id,
+    label,
+    modeOptions: modes,
+    available,
+    modal: {
+      title: configuring ? '账号设置' : input.reauthorizing ? '重新授权账号' : '导入账号',
+      description: configuring ? '设置将应用于本次导入的账号' : input.reauthorizing ? '完成授权后更新账号凭据' : description,
+      tone: configuring ? 'neutral' as const : 'info' as const,
+      size: configuring ? 'md-wide' as const : 'md' as const,
+    },
+    oauth: {
+      poll,
+      callbackLabel: poll ? '回调地址或授权码（可选）' : id === 'xai' ? '回调地址或授权码' : '回调地址',
+      callbackPlaceholder: id === 'openai' ? 'http://localhost:1455/auth/callback?code=...&state=...' : '回调地址、?code=...&state=... 或授权码',
+      description: poll ? '打开授权链接，完成后自动检查结果' : '打开授权链接，完成浏览器授权后粘贴回调地址或授权码',
+    },
+    importInput: form.mode === 'access_token'
+      ? { label: 'Access Token', placeholder: '每行粘贴一个 Access Token', uploadable: false }
+      : form.mode === 'refresh_token'
+        ? { label: 'Refresh Token', placeholder: '每行粘贴一个 Refresh Token', uploadable: false }
+        : { label: isBatch ? '批量账号文件' : '账号文件', placeholder: isBatch ? '粘贴 CPR 多平台导出文件内容' : '粘贴账号 JSON 内容', uploadable: true },
+    canSubmit,
+    submitLabel: form.mode === 'oauth'
+      ? poll ? '检查授权结果' : input.reauthorizing ? '完成重新授权' : '完成导入'
+      : isBatch ? '批量导入' : '导入账号',
   }
 }
-
-function resolveModeOptions(provider: AccountCreateProvider | undefined) {
-  if (provider === 'openai' || provider === 'xai')
-    return modeOptions[provider]
-  return []
-}
-
-function resolveModal(
-  input: AccountCreatePresentationInput,
-  provider: AccountCreateProvider | undefined,
-  configuring: boolean,
-) {
-  if (configuring) {
-    return {
-      title: '账号设置',
-      description: '设置将应用于本次导入的账号',
-      tone: 'neutral' as const,
-      size: 'md-wide' as const,
-    }
-  }
-
-  if (input.reauthorizing) {
-    return {
-      title: '重新授权账号',
-      description: '完成授权后更新账号凭据',
-      tone: 'info' as const,
-      size: 'md' as const,
-    }
-  }
-
-  let description = '粘贴或上传包含 OAuth Token 的 JSON，匹配已有账号时更新凭据'
-  if (provider === 'batch')
-    description = '粘贴或上传 CPR 账号包，一次导入多个平台账号'
-  else if (provider === 'xai' && input.form.mode === 'oauth')
-    description = '通过浏览器授权导入 xAI 账号'
-  else if (provider === 'xai')
-    description = '粘贴或上传 xAI 账号文件，匹配已有账号时更新凭据'
-  else if (input.form.mode === 'api_key')
-    description = '接入 OpenAI Responses 兼容上游'
-  else if (input.form.mode === 'oauth')
-    description = '通过浏览器授权导入 OpenAI 账号'
-  else if (input.form.mode === 'access_token')
-    description = '逐行粘贴 Access Token，未包含 Refresh Token 时无法自动续期'
-  else if (input.form.mode === 'refresh_token')
-    description = '逐行粘贴 Refresh Token，导入时将自动换取 Access Token'
-
-  return {
-    title: '导入账号',
-    description,
-    tone: 'info' as const,
-    size: 'md' as const,
-  }
-}
-
-function resolveOAuth(provider: AccountCreateProvider | undefined, authUrl: string) {
-  if (provider === 'xai') {
-    return {
-      authUrl,
-      callbackLabel: '回调地址或授权码',
-      callbackPlaceholder: '回调地址、?code=...&state=... 或授权码',
-    }
-  }
-
-  return {
-    authUrl,
-    callbackLabel: '回调地址',
-    callbackPlaceholder: 'http://localhost:1455/auth/callback?code=...&state=...',
-  }
-}
-
-function resolveImportInput(
-  form: AccountCreateForm,
-  provider: AccountCreateProvider | undefined,
-) {
-  if (form.mode === 'access_token') {
-    return {
-      label: 'Access Token',
-      placeholder: '每行粘贴一个 Access Token',
-      uploadable: false,
-    }
-  }
-  if (form.mode === 'refresh_token') {
-    return {
-      label: 'Refresh Token',
-      placeholder: '每行粘贴一个 Refresh Token',
-      uploadable: false,
-    }
-  }
-  if (provider === 'batch') {
-    return {
-      label: '批量账号文件',
-      placeholder: '粘贴 CPR 多平台导出文件内容',
-      uploadable: true,
-    }
-  }
-  if (provider === 'xai') {
-    return {
-      label: '账号文件',
-      placeholder: '粘贴包含 xAI OAuth 凭据的 JSON 内容',
-      uploadable: true,
-    }
-  }
-  return {
-    label: '账号文件',
-    placeholder: '粘贴 OAuth 或 API Key 账号 JSON 内容',
-    uploadable: true,
-  }
-}
-
-function resolveSubmitLabel(
-  input: AccountCreatePresentationInput,
-  provider: AccountCreateProvider | undefined,
-) {
-  if (input.reauthorizing)
-    return '完成重新授权'
-  if (input.form.mode === 'oauth')
-    return '完成导入'
-  if (provider === 'batch')
-    return '批量导入'
-  return '导入账号'
-}
-
-function canSubmit(
-  input: AccountCreatePresentationInput,
-  provider: AccountCreateProvider | undefined,
-  oauthAuthUrl: string,
-) {
-  if (!provider || input.saving || input.oauthLoading)
-    return false
-  if (input.form.mode === 'api_key')
-    return !apiKeyAccountError(input.form.apiKey)
-  if (input.form.mode !== 'oauth')
-    return input.form.importTexts[input.form.mode].trim().length > 0
-  return Boolean(
-    input.form.oauthFlowId
-    && oauthAuthUrl
-    && input.form.oauthCallback.trim(),
-  )
-}
-
-function isAccountCreateProvider(value: string): value is AccountCreateProvider {
-  return value === 'openai' || value === 'xai' || value === 'batch'
-}
diff --git a/frontend/src/views/accounts/components/AccountEditModal.vue b/frontend/src/views/accounts/components/AccountEditModal.vue
index c71bb35f8..1c0c4f854 100644
--- a/frontend/src/views/accounts/components/AccountEditModal.vue
+++ b/frontend/src/views/accounts/components/AccountEditModal.vue
@@ -3,11 +3,9 @@ import type { AccountRow } from '../constants'
 import type { ApiKeyAccountForm } from '../utils/upstreamApiKey'
 import type { AccountGroup, AccountModelAccess } from '@/api'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseTextarea from '@/components/base/BaseTextarea.vue'
+import { BaseButton, BaseFormItem, BaseModal, BaseTextarea } from '@codex-proxy/ui'
 import ProviderIconGroup from '@/components/ProviderIconGroup.vue'
+import { isOpenAiApiKeyAccount } from '../utils/upstreamApiKey'
 import AccountApiKeyFields from './AccountApiKeyFields.vue'
 import AccountIdentityCell from './AccountIdentityCell.vue'
 import AccountPlanBadge from './AccountPlanBadge.vue'
@@ -63,7 +61,7 @@ const selectedGroupIds = defineModel<string[]>('selectedGroupIds', { required: t
         </div>
       </div>
 
-      <section v-if="account.authenticationKind === 'api_key'" class="grid gap-4">
+      <section v-if="isOpenAiApiKeyAccount(account)" class="grid gap-4">
         <h3 class="m-0 text-cp font-heavy text-cp-text">
           上游连接
         </h3>
@@ -109,7 +107,7 @@ const selectedGroupIds = defineModel<string[]>('selectedGroupIds', { required: t
       <BaseButton
         variant="primary"
         :loading="saving"
-        :disabled="!account || groupsLoading || (account.authenticationKind === 'api_key' && !configurationReady)"
+        :disabled="!account || groupsLoading || (isOpenAiApiKeyAccount(account) && !configurationReady)"
         @click="emit('save')"
       >
         保存更改
diff --git a/frontend/src/views/accounts/components/AccountFilters.vue b/frontend/src/views/accounts/components/AccountFilters.vue
index 641e65003..8a38563e5 100644
--- a/frontend/src/views/accounts/components/AccountFilters.vue
+++ b/frontend/src/views/accounts/components/AccountFilters.vue
@@ -1,20 +1,20 @@
 <script setup lang="ts">
 import type { AccountGroup } from '@/api'
+import { BaseButton, BaseInput, BaseSelect } from '@codex-proxy/ui'
+
 import { Download, ListTodo, Pencil, Search, Trash2, Upload } from '@lucide/vue'
 import { computed } from 'vue'
-
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
-import ProviderFilterSegmented from '@/components/ProviderFilterSegmented.vue'
+import ProviderFilter from '@/components/ProviderFilter.vue'
 import { accountStatusFilterOptions } from '../constants'
 
 const props = defineProps<{
+  providers: string[]
   hasImportTasks: boolean
   activeImportCount: number
   selectedCount: number
   batchDeleting: boolean
   exportingAccounts: boolean
+  exportDisabledReason: string
   groups: AccountGroup[]
   groupsLoading: boolean
 }>()
@@ -75,9 +75,10 @@ const groupOptions = computed(() => [
         class="w-full min-w-0 xl:w-40 xl:shrink-0"
       />
 
-      <ProviderFilterSegmented
+      <ProviderFilter
         v-model="provider"
-        class="col-span-2 w-full sm:col-span-1 xl:w-31 xl:shrink-0"
+        :providers="providers"
+        class="col-span-2 w-full sm:col-span-1 xl:w-auto xl:shrink-0"
       />
     </div>
 
@@ -108,6 +109,9 @@ const groupOptions = computed(() => [
         variant="secondary"
         class="w-full whitespace-nowrap xl:w-auto"
         :loading="exportingAccounts"
+        :disabled="Boolean(exportDisabledReason)"
+        :title="exportDisabledReason || undefined"
+        :aria-description="exportDisabledReason || undefined"
         @click="emit('exportSelected')"
       >
         <template #icon>
diff --git a/frontend/src/views/accounts/components/AccountImportTasks/TaskDetail.vue b/frontend/src/views/accounts/components/AccountImportTasks/TaskDetail.vue
index 3f1e94696..3b828a638 100644
--- a/frontend/src/views/accounts/components/AccountImportTasks/TaskDetail.vue
+++ b/frontend/src/views/accounts/components/AccountImportTasks/TaskDetail.vue
@@ -1,11 +1,8 @@
 <script setup lang="ts">
 import type { AccountImportTaskDetail } from '@/api'
+import { BaseButton, BaseEmpty, BaseScrollbar, BaseSegmented } from '@codex-proxy/ui'
 import { ArrowUpRight, Check, CircleAlert, Square, X } from '@lucide/vue'
 import { computed, shallowRef, watch } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
 import ProviderIconGroup from '@/components/ProviderIconGroup.vue'
 import { itemDescription, itemStates, outcomeOrder, processed, taskLabel, taskTime } from './presenter'
 
diff --git a/frontend/src/views/accounts/components/AccountImportTasks/index.vue b/frontend/src/views/accounts/components/AccountImportTasks/index.vue
index 009234cad..3dd8b2bbf 100644
--- a/frontend/src/views/accounts/components/AccountImportTasks/index.vue
+++ b/frontend/src/views/accounts/components/AccountImportTasks/index.vue
@@ -1,13 +1,8 @@
 <script setup lang="ts">
 import type { AccountImportTask, AccountImportTaskDetail } from '@/api'
+import { BaseButton, BaseEmpty, BaseIconButton, BaseModal, BasePopover, BaseSelect } from '@codex-proxy/ui'
 import { CircleAlert, ListTodo } from '@lucide/vue'
 import { computed, shallowRef, useId, watch } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BasePopover from '@/components/base/BasePopover.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
 import { taskLabel, taskTime } from './presenter'
 import TaskDetail from './TaskDetail.vue'
 
diff --git a/frontend/src/views/accounts/components/AccountModelAccessField.vue b/frontend/src/views/accounts/components/AccountModelAccessField.vue
index c6f296c87..259e616cb 100644
--- a/frontend/src/views/accounts/components/AccountModelAccessField.vue
+++ b/frontend/src/views/accounts/components/AccountModelAccessField.vue
@@ -1,16 +1,10 @@
 <script setup lang="ts">
 import type { AccountModelAccess } from '@/api'
 
+import { BaseCheckbox, BaseEmpty, BaseFormItem, BaseIconButton, BaseInput, BaseScrollbar, BaseSegmented } from '@codex-proxy/ui'
 import { RefreshCw, Search } from '@lucide/vue'
 import { computed, ref, watch } from 'vue'
 import { getAccountModels, refreshAccountModels } from '@/api'
-import BaseCheckbox from '@/components/base/BaseCheckbox.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
 import { useRequestState } from '@/composables/useRequestState'
 import { accountModelAccessError, accountModelIdError } from '../utils/modelAccess'
 
diff --git a/frontend/src/views/accounts/components/AccountNotesPopover.vue b/frontend/src/views/accounts/components/AccountNotesPopover.vue
index 0955522f7..3b8a820d7 100644
--- a/frontend/src/views/accounts/components/AccountNotesPopover.vue
+++ b/frontend/src/views/accounts/components/AccountNotesPopover.vue
@@ -1,10 +1,9 @@
 <script setup lang="ts">
+import { BasePopover, BaseScrollbar } from '@codex-proxy/ui'
+
 import { useEventListener } from '@vueuse/core'
 import { computed, shallowRef, useId, useTemplateRef, watch } from 'vue'
 
-import BasePopover from '@/components/base/BasePopover.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
-
 const props = defineProps<{
   notes: string
 }>()
diff --git a/frontend/src/views/accounts/components/AccountOverviewCards.vue b/frontend/src/views/accounts/components/AccountOverviewCards.vue
index 9d60cf8aa..9434bf14d 100644
--- a/frontend/src/views/accounts/components/AccountOverviewCards.vue
+++ b/frontend/src/views/accounts/components/AccountOverviewCards.vue
@@ -1,10 +1,9 @@
 <script setup lang="ts">
 import type { getAccounts } from '@/api'
-import { AlertTriangle, Gauge, ShieldCheck, Users } from '@lucide/vue'
+import { BaseCard, BaseMotionIcon } from '@codex-proxy/ui'
 
+import { AlertTriangle, Gauge, ShieldCheck, Users } from '@lucide/vue'
 import { computed } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseMotionIcon from '@/components/base/BaseMotionIcon.vue'
 import { formatInteger } from '@/utils/number'
 
 const props = defineProps<{
diff --git a/frontend/src/views/accounts/components/AccountProfileModal/Metrics.vue b/frontend/src/views/accounts/components/AccountProfileModal/Metrics.vue
index fe8c77929..884a9ae26 100644
--- a/frontend/src/views/accounts/components/AccountProfileModal/Metrics.vue
+++ b/frontend/src/views/accounts/components/AccountProfileModal/Metrics.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import type { AccountProfileStatisticsResponse } from '@/api'
+import { BaseSkeleton } from '@codex-proxy/ui'
 import { computed } from 'vue'
-import BaseSkeleton from '@/components/base/BaseSkeleton.vue'
 import { formatCompactNumber, formatInteger } from '@/utils/number'
 
 const props = defineProps<{
diff --git a/frontend/src/views/accounts/components/AccountProfileModal/ProfileHero.vue b/frontend/src/views/accounts/components/AccountProfileModal/ProfileHero.vue
index 11425072b..77d133133 100644
--- a/frontend/src/views/accounts/components/AccountProfileModal/ProfileHero.vue
+++ b/frontend/src/views/accounts/components/AccountProfileModal/ProfileHero.vue
@@ -15,7 +15,7 @@ const props = defineProps<{
 
 const imageFailed = shallowRef(false)
 const displayName = computed(
-  () => props.profile?.displayName || props.profile?.username || props.account.email || props.account.name || 'Codex 用户',
+  () => props.profile?.displayName || props.profile?.username || props.account.email || props.account.name || '账号用户',
 )
 const username = computed(() => (props.profile?.username ? `@${props.profile?.username.replace(/^@/, '')}` : null))
 const accountIdentity = computed(() => props.account.email?.trim() || props.account.accountId?.trim())
@@ -25,7 +25,7 @@ const avatarToneClass = computed(() =>
 )
 const avatarUrl = computed(() => {
   const sourceUrl = props.profile?.imageUrl?.trim()
-  return sourceUrl ? accountProfileAvatarUrl(props.account.id, sourceUrl) : null
+  return props.account.capabilities.avatar && sourceUrl ? accountProfileAvatarUrl(props.account.id, sourceUrl) : null
 })
 watch(
   avatarUrl,
diff --git a/frontend/src/views/accounts/components/AccountProfileModal/Skeleton.vue b/frontend/src/views/accounts/components/AccountProfileModal/Skeleton.vue
index 508dcdc90..334399b67 100644
--- a/frontend/src/views/accounts/components/AccountProfileModal/Skeleton.vue
+++ b/frontend/src/views/accounts/components/AccountProfileModal/Skeleton.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import BaseSkeleton from '@/components/base/BaseSkeleton.vue'
+import { BaseSkeleton } from '@codex-proxy/ui'
 </script>
 
 <template>
diff --git a/frontend/src/views/accounts/components/AccountProfileModal/TokenActivity.vue b/frontend/src/views/accounts/components/AccountProfileModal/TokenActivity.vue
index 553488077..0d6d68c17 100644
--- a/frontend/src/views/accounts/components/AccountProfileModal/TokenActivity.vue
+++ b/frontend/src/views/accounts/components/AccountProfileModal/TokenActivity.vue
@@ -1,10 +1,9 @@
 <script setup lang="ts">
 import type { ProfileActivityLevel, ProfileActivityMode } from '../../utils/accountProfileStatistics'
 import type { AccountProfileDailyUsage } from '@/api'
-import { computed, shallowRef } from 'vue'
+import { BaseEmpty, BaseSegmented } from '@codex-proxy/ui'
 
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
+import { computed, shallowRef } from 'vue'
 import { buildProfileActivityGrid, profileActivityCellLabel } from '../../utils/accountProfileStatistics'
 
 const props = defineProps<{
diff --git a/frontend/src/views/accounts/components/AccountProfileModal/index.vue b/frontend/src/views/accounts/components/AccountProfileModal/index.vue
index d2915f450..4398486b5 100644
--- a/frontend/src/views/accounts/components/AccountProfileModal/index.vue
+++ b/frontend/src/views/accounts/components/AccountProfileModal/index.vue
@@ -1,11 +1,9 @@
 <script setup lang="ts">
 import type { AccountRow } from '../../constants'
+import { BaseButton, BaseEmpty, BaseModal, BaseSkeleton } from '@codex-proxy/ui'
+
 import { RefreshCw, TriangleAlert } from '@lucide/vue'
 import { toRef } from 'vue'
-
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
 import { useAccountPersonalInfo } from '../../composables/useAccountPersonalInfo'
 import AccountProfileActivityInsights from './ActivityInsights.vue'
 import AccountProfileMetrics from './Metrics.vue'
@@ -17,15 +15,19 @@ import AccountProfileTokenActivity from './TokenActivity.vue'
 const props = defineProps<{ account: AccountRow }>()
 const open = defineModel<boolean>({ required: true })
 const accountId = toRef(() => props.account.id)
-const { profile, subscription, loading, error, load } = useAccountPersonalInfo(accountId, open)
+const { profile, subscription, loading, error, load } = useAccountPersonalInfo({
+  accountId,
+  open,
+  capabilities: toRef(() => props.account.capabilities),
+})
 </script>
 
 <template>
   <BaseModal v-model="open" title="个人信息" size="xl">
     <div class="flex min-h-0 min-w-0 flex-col gap-6 pb-2">
-      <div class="grid min-w-0 grid-cols-1 gap-4 rounded-cp-lg bg-cp-fill-alter p-4 sm:p-5 lg:grid-cols-[minmax(310px,1.05fr)_minmax(0,1.95fr)] lg:items-center">
+      <div class="grid min-w-0 grid-cols-1 gap-4 rounded-cp-lg bg-cp-fill-alter p-4 sm:p-5 lg:items-center" :class="account.capabilities.profile ? 'lg:grid-cols-[minmax(310px,1.05fr)_minmax(0,1.95fr)]' : undefined">
         <AccountProfileHero :account="account" :profile="profile" />
-        <AccountProfileMetrics :profile="profile" :loading="loading" />
+        <AccountProfileMetrics v-if="account.capabilities.profile" :profile="profile" :loading="loading" />
       </div>
 
       <section v-if="subscription" class="grid min-w-0 grid-cols-1 gap-4" aria-labelledby="profile-subscription-title">
@@ -35,10 +37,16 @@ const { profile, subscription, loading, error, load } = useAccountPersonalInfo(a
         <AccountSubscription :subscription="subscription" />
       </section>
 
-      <AccountProfileSkeleton v-if="loading && !profile" />
+      <template v-if="loading && !profile">
+        <AccountProfileSkeleton v-if="account.capabilities.profile" />
+        <div v-else role="status" aria-busy="true">
+          <span class="sr-only">正在加载订阅信息</span>
+          <BaseSkeleton class="h-24 w-full rounded-cp-lg" />
+        </div>
+      </template>
       <BaseEmpty
         v-else-if="error && !profile"
-        title="个人资料加载失败"
+        title="个人信息加载失败"
         :description="error"
         :icon="TriangleAlert"
         surface="none"
@@ -59,6 +67,11 @@ const { profile, subscription, loading, error, load } = useAccountPersonalInfo(a
           本次信息刷新未完成，保留已获取的结果
         </p>
       </template>
+      <BaseEmpty
+        v-else-if="!loading && !account.capabilities.profile && !subscription"
+        title="暂无订阅信息"
+        surface="none"
+      />
     </div>
     <template #footer>
       <BaseButton variant="secondary" @click="open = false">
diff --git a/frontend/src/views/accounts/components/AccountProxyField.vue b/frontend/src/views/accounts/components/AccountProxyField.vue
index 008cef9e8..a63e3dd9d 100644
--- a/frontend/src/views/accounts/components/AccountProxyField.vue
+++ b/frontend/src/views/accounts/components/AccountProxyField.vue
@@ -1,7 +1,6 @@
 <script setup lang="ts">
+import { BaseFormItem, BaseSelect } from '@codex-proxy/ui'
 import { computed } from 'vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
 import { useProxyCatalog } from '@/composables/useProxyCatalog'
 
 const props = withDefaults(defineProps<{ accountId?: string, endpoint?: string | null, disabled?: boolean, preserve?: boolean, error?: string }>(), { preserve: true })
diff --git a/frontend/src/views/accounts/components/AccountQuotaForecastModal/Skeleton.vue b/frontend/src/views/accounts/components/AccountQuotaForecastModal/Skeleton.vue
index f58aa64b4..c4c6ea928 100644
--- a/frontend/src/views/accounts/components/AccountQuotaForecastModal/Skeleton.vue
+++ b/frontend/src/views/accounts/components/AccountQuotaForecastModal/Skeleton.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import BaseSkeleton from '@/components/base/BaseSkeleton.vue'
+import { BaseSkeleton } from '@codex-proxy/ui'
 </script>
 
 <template>
diff --git a/frontend/src/views/accounts/components/AccountQuotaForecastModal/index.vue b/frontend/src/views/accounts/components/AccountQuotaForecastModal/index.vue
index 27639e20f..2ccbc8226 100644
--- a/frontend/src/views/accounts/components/AccountQuotaForecastModal/index.vue
+++ b/frontend/src/views/accounts/components/AccountQuotaForecastModal/index.vue
@@ -1,15 +1,10 @@
 <script setup lang="ts">
 import type { AccountRow } from '../../constants'
 import type { Account } from '@/api'
+import { BaseButton, BaseEmpty, BaseIconButton, BaseModal, BasePopover, BaseSegmented } from '@codex-proxy/ui'
 import { ChartNoAxesCombined, CircleAlert, RefreshCw } from '@lucide/vue'
 import { useIntervalFn, useNow } from '@vueuse/core'
 import { computed, ref, toRef, useId, watch } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BasePopover from '@/components/base/BasePopover.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
 import ProviderIconGroup from '@/components/ProviderIconGroup.vue'
 import { useAccountQuotaForecast } from '../../composables/useAccountQuotaForecast'
 import AccountIdentityCell from '../AccountIdentityCell.vue'
diff --git a/frontend/src/views/accounts/components/AccountQuotaPanel/ResetCredits.vue b/frontend/src/views/accounts/components/AccountQuotaPanel/ResetCredits.vue
index 1d56345f5..d124a5292 100644
--- a/frontend/src/views/accounts/components/AccountQuotaPanel/ResetCredits.vue
+++ b/frontend/src/views/accounts/components/AccountQuotaPanel/ResetCredits.vue
@@ -1,14 +1,11 @@
 <script setup lang="ts">
 import type { Account, AccountResetCredit } from '@/api'
+import { BaseButton, BaseEmpty, BaseIconButton, BaseModal } from '@codex-proxy/ui'
+
 import { AlertTriangle, RefreshCw, TicketCheck } from '@lucide/vue'
 import dayjs from 'dayjs'
 import utc from 'dayjs/plugin/utc'
 import { computed, shallowRef, watch } from 'vue'
-
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
 import { useAccountResetCredits } from '../../composables/useAccountResetCredits'
 import UsageLimits from './UsageLimits.vue'
 
@@ -41,6 +38,7 @@ const {
   confirmConsume,
 } = useAccountResetCredits({
   accountId: () => props.account.id,
+  capabilities: () => props.account.capabilities,
   onConsumed: (accountId) => {
     if (props.account.id === accountId)
       panelOpen.value = false
@@ -103,7 +101,7 @@ function creditTitle(credit: AccountResetCredit | undefined) {
 }
 
 function handleRequestConsume(creditId: string) {
-  if (loading.value || consuming.value || ambiguous.value)
+  if (!props.account.capabilities.consumeResetCredit || loading.value || consuming.value || ambiguous.value)
     return
   selectCredit(creditId)
   requestConsume()
@@ -230,7 +228,7 @@ function handleRequestConsume(creditId: string) {
               <BaseButton
                 size="sm"
                 variant="primary"
-                :disabled="loading || consuming || ambiguous || availableCount <= 0"
+                :disabled="!account.capabilities.consumeResetCredit || loading || consuming || ambiguous || availableCount <= 0"
                 :aria-label="`使用重置：${credit.title}，${credit.expiry}`"
                 @click="handleRequestConsume(credit.id)"
               >
diff --git a/frontend/src/views/accounts/components/AccountQuotaPanel/index.vue b/frontend/src/views/accounts/components/AccountQuotaPanel/index.vue
index 2c73489b3..5af5835ae 100644
--- a/frontend/src/views/accounts/components/AccountQuotaPanel/index.vue
+++ b/frontend/src/views/accounts/components/AccountQuotaPanel/index.vue
@@ -1,10 +1,10 @@
 <script setup lang="ts">
 import type { AccountRow } from '../../constants'
-import { RefreshCw, UserRound } from '@lucide/vue'
+import { BaseEmpty, BaseIconButton } from '@codex-proxy/ui'
 
-import { computed, shallowRef } from 'vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
+import { RefreshCw, UserRound } from '@lucide/vue'
+import { computed, shallowRef, watch } from 'vue'
+import { formatProviderLabel } from '@/utils/providers'
 import { groupedAccountQuotaWindows, orderedPanelQuotaWindows } from '../../constants'
 import AccountPlanBadge from '../AccountPlanBadge.vue'
 import AccountProfileModal from '../AccountProfileModal/index.vue'
@@ -25,6 +25,12 @@ const quotaEntries = computed(() => groupedAccountQuotaWindows(
   orderedPanelQuotaWindows(props.account.quota.windows),
 ))
 const profileOpen = shallowRef(false)
+const hasPersonalInfo = computed(() => props.account.capabilities.profile || props.account.capabilities.subscription)
+const hasActions = computed(() => hasPersonalInfo.value || props.account.capabilities.quotaRefresh || props.account.capabilities.resetCredits)
+watch(hasPersonalInfo, (available) => {
+  if (!available)
+    profileOpen.value = false
+})
 </script>
 
 <template>
@@ -35,11 +41,11 @@ const profileOpen = shallowRef(false)
           账号额度
         </h3>
         <p
-          v-if="account.authenticationKind !== 'api_key'"
+          v-if="account.capabilities.quota || quotaEntries.length > 0"
           class="m-0 mt-1 flex min-w-0 items-center gap-1.5 text-cp-xs font-emphasis text-cp-text-secondary"
         >
-          <span>{{ account.provider === 'xai' ? 'xAI 用量窗口' : 'Codex 额度' }}</span>
-          <template v-if="account.provider === 'openai' && account.authenticationKind === 'oauth'">
+          <span>{{ formatProviderLabel(account.provider) }} 额度</span>
+          <template v-if="account.planType">
             <span>·</span>
             <AccountPlanBadge :plan-type="account.planType" :plan-type-display="account.planTypeDisplay" size="sm" />
           </template>
@@ -47,9 +53,9 @@ const profileOpen = shallowRef(false)
           <span>最近刷新: {{ account.quota.refreshedAtDisplay }}</span>
         </p>
       </div>
-      <div v-if="account.authenticationKind !== 'api_key'" class="flex shrink-0 items-center gap-0.5">
+      <div v-if="hasActions" class="flex shrink-0 items-center gap-0.5">
         <BaseIconButton
-          v-if="account.provider === 'openai' && account.authenticationKind === 'oauth'"
+          v-if="hasPersonalInfo"
           label="查看个人信息"
           size="sm"
           variant="ghost"
@@ -59,11 +65,12 @@ const profileOpen = shallowRef(false)
           <UserRound class="size-3.5" />
         </BaseIconButton>
         <AccountResetCredits
-          v-if="account.provider === 'openai' && account.authenticationKind === 'oauth'"
+          v-if="account.capabilities.resetCredits"
           :account="account"
           @consumed="emit('quotaReset', $event)"
         />
         <BaseIconButton
+          v-if="account.capabilities.quotaRefresh"
           variant="ghost"
           size="sm"
           label="刷新额度"
@@ -79,7 +86,7 @@ const profileOpen = shallowRef(false)
       </div>
     </div>
 
-    <div v-if="account.authenticationKind === 'api_key'" class="grid flex-1 place-items-center">
+    <div v-if="!account.capabilities.quota && quotaEntries.length === 0" class="grid flex-1 place-items-center">
       <BaseEmpty title="暂不支持查询上游额度" surface="none" />
     </div>
     <div v-else class="grid min-h-0 gap-3">
@@ -96,7 +103,7 @@ const profileOpen = shallowRef(false)
   </section>
 
   <AccountProfileModal
-    v-if="account.provider === 'openai' && account.authenticationKind === 'oauth'"
+    v-if="hasPersonalInfo"
     v-model="profileOpen"
     :account="account"
   />
diff --git a/frontend/src/views/accounts/components/AccountQuotaSummaryCell/Entry.vue b/frontend/src/views/accounts/components/AccountQuotaSummaryCell/Entry.vue
index 929ebdef6..df81d0890 100644
--- a/frontend/src/views/accounts/components/AccountQuotaSummaryCell/Entry.vue
+++ b/frontend/src/views/accounts/components/AccountQuotaSummaryCell/Entry.vue
@@ -1,9 +1,9 @@
 <script setup lang="ts">
 import type { AccountQuotaWindow } from '../../constants'
 
-import { computed } from 'vue'
+import { BasePopover } from '@codex-proxy/ui'
 
-import BasePopover from '@/components/base/BasePopover.vue'
+import { computed } from 'vue'
 import { useUiClock } from '@/composables/useUiClock'
 import AccountRequestTimeline from '../AccountUsageWindow/AccountRequestTimeline.vue'
 import AccountUsageWindow from '../AccountUsageWindow/index.vue'
diff --git a/frontend/src/views/accounts/components/AccountSettingsFields.vue b/frontend/src/views/accounts/components/AccountSettingsFields.vue
index 326697342..1d01fc7e1 100644
--- a/frontend/src/views/accounts/components/AccountSettingsFields.vue
+++ b/frontend/src/views/accounts/components/AccountSettingsFields.vue
@@ -1,9 +1,7 @@
 <script setup lang="ts">
 import type { AccountGroup, AccountModelAccess } from '@/api'
+import { BaseFormItem, BaseInput, BaseSwitch } from '@codex-proxy/ui'
 import AccountGroupCheckboxGrid from '@/components/AccountGroupCheckboxGrid.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseSwitch from '@/components/base/BaseSwitch.vue'
 import AccountModelAccessField from './AccountModelAccessField.vue'
 import AccountProxyField from './AccountProxyField.vue'
 
diff --git a/frontend/src/views/accounts/components/AccountStatusBadge/index.vue b/frontend/src/views/accounts/components/AccountStatusBadge/index.vue
index ea5e94f40..f807e3dd5 100644
--- a/frontend/src/views/accounts/components/AccountStatusBadge/index.vue
+++ b/frontend/src/views/accounts/components/AccountStatusBadge/index.vue
@@ -1,9 +1,8 @@
 <script setup lang="ts">
 import type { AccountErrorReason, AccountStatus } from '@/api'
-import { computed } from 'vue'
+import { BasePopover, BaseScrollbar } from '@codex-proxy/ui'
 
-import BasePopover from '@/components/base/BasePopover.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
+import { computed } from 'vue'
 import { useUiClock } from '@/composables/useUiClock'
 import { resolveAccountStatusPresentation } from './presenter'
 
diff --git a/frontend/src/views/accounts/components/AccountTableActions.vue b/frontend/src/views/accounts/components/AccountTableActions.vue
index f96ffeb48..dd5421f25 100644
--- a/frontend/src/views/accounts/components/AccountTableActions.vue
+++ b/frontend/src/views/accounts/components/AccountTableActions.vue
@@ -1,19 +1,20 @@
 <script setup lang="ts">
 import type { AccountRow } from '../constants'
+import type { AccountProvider } from '@/api'
+import { BaseIconButton, BaseMenuItem, BasePopover } from '@codex-proxy/ui'
+
 import { KeyRound, MoreHorizontal, Pencil, RefreshCw, RotateCcw, Trash2, Wifi } from '@lucide/vue'
+import { computed } from 'vue'
+import { isSupportedProvider } from '@/utils/providers'
 
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseMenuItem from '@/components/base/BaseMenuItem.vue'
-import BasePopover from '@/components/base/BasePopover.vue'
-
-defineProps<{
+const props = defineProps<{
   account: AccountRow
+  provider?: AccountProvider
   deleting: boolean
   recovering: boolean
   refreshing: boolean
   testing: boolean
 }>()
-
 const emit = defineEmits<{
   edit: [account: AccountRow]
   delete: [account: AccountRow]
@@ -22,6 +23,8 @@ const emit = defineEmits<{
   refresh: [accountId: string]
   reauthorize: [account: AccountRow]
 }>()
+
+const credentialEligible = computed(() => !isSupportedProvider(props.account.provider) || props.account.authenticationKind === 'oauth')
 </script>
 
 <template>
@@ -65,7 +68,7 @@ const emit = defineEmits<{
             测试连接
           </BaseMenuItem>
           <BaseMenuItem
-            v-if="account.authenticationKind === 'oauth'"
+            v-if="credentialEligible && provider?.credentials.refresh"
             :loading="refreshing"
             :disabled="refreshing"
             @click.stop="(close(), emit('refresh', account.id))"
@@ -78,7 +81,7 @@ const emit = defineEmits<{
             </template>
             刷新令牌
           </BaseMenuItem>
-          <BaseMenuItem v-if="account.authenticationKind === 'oauth'" @click.stop="(close(), emit('reauthorize', account))">
+          <BaseMenuItem v-if="credentialEligible && provider?.credentials.login" @click.stop="(close(), emit('reauthorize', account))">
             <template #icon>
               <KeyRound class="size-3.5 text-cp-text-quaternary" />
             </template>
diff --git a/frontend/src/views/accounts/components/AccountUsagePanel.vue b/frontend/src/views/accounts/components/AccountUsagePanel.vue
index 80a90878d..7523a8cd2 100644
--- a/frontend/src/views/accounts/components/AccountUsagePanel.vue
+++ b/frontend/src/views/accounts/components/AccountUsagePanel.vue
@@ -1,11 +1,9 @@
 <script setup lang="ts">
 import type { AccountRow } from '../constants'
 
+import { BaseIconButton, BaseTable, defineTableColumns } from '@codex-proxy/ui'
 import { ChartNoAxesCombined, Sigma } from '@lucide/vue'
 import { computed, ref } from 'vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import { defineTableColumns } from '@/components/base/BaseTable/columns'
-import BaseTable from '@/components/base/BaseTable/index.vue'
 import { modelSuccessRateTextClass } from '../constants'
 import AccountQuotaForecastModal from './AccountQuotaForecastModal/index.vue'
 
diff --git a/frontend/src/views/accounts/composables/useAccountAuthorization.ts b/frontend/src/views/accounts/composables/useAccountAuthorization.ts
new file mode 100644
index 000000000..77c97a3bd
--- /dev/null
+++ b/frontend/src/views/accounts/composables/useAccountAuthorization.ts
@@ -0,0 +1,167 @@
+import type { AccountImportSettings, AccountOAuthStartResponse, AccountProvider } from '@/api'
+import { computed, onScopeDispose, shallowRef } from 'vue'
+import { completeAccountOAuth, pollAccountAuthorization, startAccountOAuth } from '@/api'
+import { errorMessage } from '@/utils/async'
+
+type Completion = NonNullable<AccountProvider['credentials']['login']>['completion']
+type Status = 'idle' | 'starting' | 'waiting' | 'polling' | 'paused' | 'expired' | 'completing'
+
+export interface AccountAuthorizationView {
+  flow: AccountOAuthStartResponse | null
+  completion: Completion | null
+  status: Status
+  error: string
+}
+
+interface AuthorizationRequest {
+  start: Parameters<typeof startAccountOAuth>[0]
+  completion: Completion
+  settings?: AccountImportSettings
+}
+
+export function useAccountAuthorization(onComplete: () => Promise<void>) {
+  const flow = shallowRef<AccountOAuthStartResponse | null>(null)
+  const completion = shallowRef<Completion | null>(null)
+  const status = shallowRef<Status>('idle')
+  const error = shallowRef('')
+  const callback = shallowRef('')
+  const busy = computed(() => status.value === 'starting' || status.value === 'completing')
+  const view = computed<AccountAuthorizationView>(() => ({
+    flow: flow.value,
+    completion: completion.value,
+    status: status.value,
+    error: error.value,
+  }))
+  let context: { provider: string, settings?: AccountImportSettings } | undefined
+  let controller: AbortController | undefined
+  let pollTimer: ReturnType<typeof setTimeout> | undefined
+  let expiryTimer: ReturnType<typeof setTimeout> | undefined
+
+  function clearTimers() {
+    clearTimeout(pollTimer)
+    clearTimeout(expiryTimer)
+    pollTimer = undefined
+    expiryTimer = undefined
+  }
+
+  function reset() {
+    controller?.abort()
+    controller = undefined
+    clearTimers()
+    context = undefined
+    flow.value = null
+    completion.value = null
+    status.value = 'idle'
+    error.value = ''
+    callback.value = ''
+  }
+
+  function expired() {
+    return !flow.value || Date.parse(flow.value.expiresAt) <= Date.now()
+  }
+
+  async function start(request: AuthorizationRequest) {
+    reset()
+    const current = new AbortController()
+    controller = current
+    status.value = 'starting'
+    try {
+      const result = await startAccountOAuth(request.start, { signal: current.signal, silent: true })
+      if (current.signal.aborted)
+        return
+      const expiresAt = Date.parse(result.expiresAt)
+      if (!Number.isFinite(expiresAt))
+        throw new Error('授权有效期无效，请重新生成链接')
+      context = { provider: request.start.provider, settings: request.settings }
+      completion.value = request.completion
+      flow.value = result
+      status.value = expired() ? 'expired' : 'waiting'
+      expiryTimer = setTimeout(() => {
+        clearTimeout(pollTimer)
+        // 不取消正在确认的提交，过期后仍接收服务端已经提交的结果。
+        if (status.value !== 'polling' && status.value !== 'completing')
+          status.value = 'expired'
+      }, Math.max(0, Math.min(expiresAt - Date.now(), 2_147_483_647)))
+      if (request.completion === 'poll' && !expired())
+        void poll()
+    }
+    catch (cause) {
+      if (!current.signal.aborted) {
+        error.value = errorMessage(cause, '生成授权链接失败')
+        status.value = 'idle'
+      }
+    }
+  }
+
+  async function poll() {
+    const current = controller
+    const currentFlow = flow.value
+    if (!current || !currentFlow || !context || status.value === 'polling')
+      return
+    clearTimeout(pollTimer)
+    status.value = 'polling'
+    error.value = ''
+    try {
+      const result = await pollAccountAuthorization({
+        ...context,
+        flowId: currentFlow.flowId,
+        callbackUrl: callback.value.trim() || undefined,
+      }, { signal: current.signal, silent: true })
+      if (current.signal.aborted)
+        return
+      if (result.status === 'complete') {
+        clearTimers()
+        await onComplete()
+        return
+      }
+      status.value = expired() ? 'expired' : 'waiting'
+      if (!expired()) {
+        const delay = Number.isFinite(result.retryAfterMs) ? Math.max(250, result.retryAfterMs) : 1000
+        pollTimer = setTimeout(() => void poll(), Math.min(delay, 2_147_483_647))
+      }
+    }
+    catch (cause) {
+      if (!current.signal.aborted) {
+        status.value = expired() ? 'expired' : 'paused'
+        error.value = errorMessage(cause, '授权状态查询失败，可重试查询')
+      }
+    }
+  }
+
+  async function complete() {
+    if (completion.value === 'poll') {
+      await poll()
+      return
+    }
+    const current = controller
+    const currentFlow = flow.value
+    if (!current || !currentFlow || !context || busy.value)
+      return
+    if (!callback.value.trim()) {
+      error.value = '请粘贴回调地址或授权码'
+      return
+    }
+    status.value = 'completing'
+    error.value = ''
+    try {
+      await completeAccountOAuth({
+        ...context,
+        flowId: currentFlow.flowId,
+        callbackUrl: callback.value.trim(),
+      }, { signal: current.signal, silent: true })
+      if (!current.signal.aborted) {
+        clearTimers()
+        await onComplete()
+      }
+    }
+    catch (cause) {
+      if (!current.signal.aborted) {
+        status.value = expired() ? 'expired' : 'paused'
+        error.value = errorMessage(cause, '完成授权失败，可重试提交')
+      }
+    }
+  }
+
+  onScopeDispose(reset)
+  return { view, callback, busy, start, complete, reset }
+}
diff --git a/frontend/src/views/accounts/composables/useAccountBatchEditor.ts b/frontend/src/views/accounts/composables/useAccountBatchEditor.ts
index 65680c814..1c0bc9164 100644
--- a/frontend/src/views/accounts/composables/useAccountBatchEditor.ts
+++ b/frontend/src/views/accounts/composables/useAccountBatchEditor.ts
@@ -1,9 +1,9 @@
 import type { Ref } from 'vue'
 import type { AccountModelAccess, getAccounts } from '@/api'
 
+import { toast } from '@codex-proxy/ui'
 import { computed, ref, shallowRef, watch } from 'vue'
 import { batchUpdateAccounts } from '@/api'
-import { toast } from '@/components/base/BaseToast'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 import { accountModelAccessError } from '../utils/modelAccess'
 import { concurrencyLimitInput, parseAccountSchedulingForm } from '../utils/schedulingForm'
diff --git a/frontend/src/views/accounts/composables/useAccountConnectionTest.ts b/frontend/src/views/accounts/composables/useAccountConnectionTest.ts
index fade9b481..92c1498b6 100644
--- a/frontend/src/views/accounts/composables/useAccountConnectionTest.ts
+++ b/frontend/src/views/accounts/composables/useAccountConnectionTest.ts
@@ -1,12 +1,12 @@
 import type { Account, AccountModelsResponse } from '@/api'
-import { CheckCircle2, Clock3, Wifi, XCircle } from '@lucide/vue'
+import { toast } from '@codex-proxy/ui'
 
+import { CheckCircle2, Clock3, Wifi, XCircle } from '@lucide/vue'
 import { useEventSource } from '@vueuse/core'
 import { clamp } from 'es-toolkit'
 import { computed, onBeforeUnmount, ref, shallowRef, watch } from 'vue'
 import { getAccountModels, refreshAccountModels } from '@/api'
 import { API_BASE_URL } from '@/api/constants'
-import { toast } from '@/components/base/BaseToast'
 import { useIdSet } from '@/composables/useIdSet'
 import { useRequestState } from '@/composables/useRequestState'
 import { errorMessage, withMinimumDuration } from '@/utils/async'
diff --git a/frontend/src/views/accounts/composables/useAccountEditor.ts b/frontend/src/views/accounts/composables/useAccountEditor.ts
index 682229a37..af4c8260c 100644
--- a/frontend/src/views/accounts/composables/useAccountEditor.ts
+++ b/frontend/src/views/accounts/composables/useAccountEditor.ts
@@ -1,14 +1,14 @@
 import type { Ref } from 'vue'
 import type { AccountModelAccess, ApiKeyConfiguration, getAccounts } from '@/api'
 
+import { toast } from '@codex-proxy/ui'
 import { computed, ref, shallowRef, watch } from 'vue'
-import { getAccountDetail, updateAccount, updateAccountApiKey } from '@/api'
-import { toast } from '@/components/base/BaseToast'
+import { getAccountDetail, updateAccount } from '@/api'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 import { useRequestState } from '@/composables/useRequestState'
 import { accountModelAccessError } from '../utils/modelAccess'
 import { concurrencyLimitInput, parseAccountSchedulingForm } from '../utils/schedulingForm'
-import { apiKeyAccountError, emptyApiKeyAccountForm } from '../utils/upstreamApiKey'
+import { apiKeyAccountError, emptyApiKeyAccountForm, isOpenAiApiKeyAccount, parseApiKeyConfiguration } from '../utils/upstreamApiKey'
 
 type AccountRow = Awaited<ReturnType<typeof getAccounts>>['items'][number]
 
@@ -41,10 +41,11 @@ export function useAccountEditor(options: {
       const detail = await getAccountDetail({ accountId }, { signal: configurationRequest.signal })
       if (!configurationRequest.isCurrent(requestId))
         return
-      if (!detail.credentialConfiguration)
+      const configuration = parseApiKeyConfiguration(detail.credentialConfiguration)
+      if (!configuration)
         throw new Error('该账号没有 API Key 上游设置')
-      apiKey.value = { ...emptyApiKeyAccountForm(), ...detail.credentialConfiguration }
-      savedConfiguration.value = detail.credentialConfiguration
+      apiKey.value = { ...emptyApiKeyAccountForm(), ...configuration }
+      savedConfiguration.value = configuration
       configurationReady.value = true
     }
     catch (error) {
@@ -77,7 +78,7 @@ export function useAccountEditor(options: {
     savedConfiguration.value = undefined
     configurationReady.value = false
     showEditModal.value = true
-    if (account.authenticationKind === 'api_key')
+    if (isOpenAiApiKeyAccount(account))
       void loadConfiguration(account.id)
   }
 
@@ -85,7 +86,7 @@ export function useAccountEditor(options: {
     const accountId = editingAccountId.value
     if (!accountId || saving.value)
       return
-    const isApiKey = editingAccount.value?.authenticationKind === 'api_key'
+    const isApiKey = isOpenAiApiKeyAccount(editingAccount.value)
     if (isApiKey) {
       if (!configurationReady.value)
         return
@@ -126,12 +127,12 @@ export function useAccountEditor(options: {
         || apiKey.value.base_url.trim() !== savedConfiguration.value?.base_url
         || apiKey.value.transport !== savedConfiguration.value?.transport
       )
-      if (connectionChanged) {
-        await updateAccountApiKey({ accountId, baseUrl: apiKey.value.base_url.trim(), transport: apiKey.value.transport, apiKey: apiKey.value.apiKey || undefined, settings })
-      }
-      else {
-        await updateAccount(settings)
-      }
+      await updateAccount({
+        ...settings,
+        connection: connectionChanged
+          ? { baseUrl: apiKey.value.base_url.trim(), transport: apiKey.value.transport, apiKey: apiKey.value.apiKey || undefined }
+          : undefined,
+      })
       showEditModal.value = false
       await Promise.all([options.reloadAccounts(), options.reloadGroups()])
       toast.success('账号已更新')
diff --git a/frontend/src/views/accounts/composables/useAccountMutations.ts b/frontend/src/views/accounts/composables/useAccountMutations.ts
index c21548f31..1efd64a2d 100644
--- a/frontend/src/views/accounts/composables/useAccountMutations.ts
+++ b/frontend/src/views/accounts/composables/useAccountMutations.ts
@@ -1,8 +1,9 @@
 import type { Ref } from 'vue'
 import type { AccountImportTask, getAccounts } from '@/api'
 import type { RequestOptions } from '@/api/request'
+import { toast } from '@codex-proxy/ui'
 import dayjs from 'dayjs'
-import { ref, watch } from 'vue'
+import { computed, ref, shallowReactive, watch } from 'vue'
 import {
   deleteAccounts,
   exportAccounts,
@@ -10,7 +11,6 @@ import {
   refreshAccount,
   refreshAccountQuota,
 } from '@/api'
-import { toast } from '@/components/base/BaseToast'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 import { useDownload } from '@/composables/useDownload'
 import { useIdSet } from '@/composables/useIdSet'
@@ -33,7 +33,7 @@ export function useAccountMutations(options: {
     reload: loadAccounts,
     onImportTaskCreated: options.onImportTaskCreated,
   })
-  const selectedAccountsById = new Map<string, AccountRow>()
+  const selectedAccountsById = shallowReactive(new Map<string, AccountRow>())
   const showDeleteModal = ref(false)
   const showSingleDeleteModal = ref(false)
   const pendingDeleteAccount = ref<AccountRow | null>(null)
@@ -49,6 +49,22 @@ export function useAccountMutations(options: {
   const deletingAccount = deletingAccountAction.loading
   const batchDeleting = batchDeletingAction.loading
   const exportingAccounts = exportingAccountsAction.loading
+  const exportDisabledReason = computed(() => {
+    if (options.selectedIds.value.size === 0)
+      return ''
+    if (onboarding.accountProvidersLoading.value)
+      return '正在加载平台能力'
+    if (onboarding.accountProvidersError.value)
+      return '平台能力加载失败，请刷新后重试'
+    for (const id of options.selectedIds.value) {
+      const account = selectedAccountsById.get(id)
+      if (!account)
+        return '所选账号数据已失效，请重新选择'
+      if (!onboarding.accountProvidersById.value.get(account.provider)?.credentials.export)
+        return '所选账号包含不支持导出的平台'
+    }
+    return ''
+  })
 
   watch(
     [options.accounts, options.selectedIds],
@@ -132,6 +148,10 @@ export function useAccountMutations(options: {
       toast.warning('请选择要导出的账号')
       return
     }
+    if (exportDisabledReason.value) {
+      toast.warning(exportDisabledReason.value)
+      return
+    }
 
     await exportingAccountsAction.run(
       async () => {
@@ -187,6 +207,8 @@ export function useAccountMutations(options: {
   }
 
   async function handleQuotaReset(accountId: string) {
+    if (!options.accounts.value.find(account => account.id === accountId)?.capabilities.quotaRefresh)
+      return
     try {
       const result = await refreshAccountQuota({ accountId }, { silent: true })
       await options.replaceAccount(result.account)
@@ -263,6 +285,7 @@ export function useAccountMutations(options: {
     deletingAccount,
     batchDeleting,
     exportingAccounts,
+    exportDisabledReason,
     requestDeleteAccount,
     handleDelete,
     handleBatchDelete,
diff --git a/frontend/src/views/accounts/composables/useAccountOnboarding.ts b/frontend/src/views/accounts/composables/useAccountOnboarding.ts
index 29b329bec..17a387ab8 100644
--- a/frontend/src/views/accounts/composables/useAccountOnboarding.ts
+++ b/frontend/src/views/accounts/composables/useAccountOnboarding.ts
@@ -1,43 +1,32 @@
 import type { AccountImportTask, getAccounts } from '@/api'
-
+import { toast } from '@codex-proxy/ui'
 import { computed, ref, shallowRef, watch } from 'vue'
-import {
-  completeAccountOAuth,
-  createAccountImportTask,
-  importAccounts,
-  startAccountOAuth,
-} from '@/api'
-import { toast } from '@/components/base/BaseToast'
+import { createAccountImportTask, importAccounts } from '@/api'
 import { useAsyncAction } from '@/composables/useAsyncAction'
-import { isRecord } from '@/utils/object'
+import { errorMessage } from '@/utils/async'
+import { parseJsonObject } from '@/utils/jsonObject'
 import { formatProviderLabel, isSupportedProvider } from '@/utils/providers'
 import { generateRequestId } from '@/utils/uuid'
-import { accountImportSettings, accountProxyError, emptyAccountCreateForm } from '../components/AccountCreateModal/model'
+import { accountCreateProvider, accountCreateSourceKey, accountImportSettings, accountProxyError, emptyAccountCreateForm } from '../components/AccountCreateModal/model'
+import { accountImportModes } from '../components/AccountCreateModal/presenter'
+import { accountImportDocuments, MAX_ACCOUNT_IMPORT_COUNT, mixedImportDocuments } from '../utils/accountImport'
 import { apiKeyAccountError, emptyApiKeyAccountForm } from '../utils/upstreamApiKey'
+import { useAccountAuthorization } from './useAccountAuthorization'
+import { useAccountProviders } from './useAccountProviders'
 
 type AccountRow = Awaited<ReturnType<typeof getAccounts>>['items'][number]
-type ImportProvider = 'openai' | 'xai'
-
-interface MixedImportDocument {
-  provider: ImportProvider
-  document: Record<string, unknown>
-}
-
-type OpenAiTokenImportMode = 'access_token' | 'refresh_token'
-
-const MAX_TOKEN_IMPORT_COUNT = 200
 
 export function useAccountOnboarding(options: {
   reload: () => Promise<unknown>
   onImportTaskCreated: (task: AccountImportTask) => void
 }) {
+  const catalog = useAccountProviders()
   const createModalOpen = shallowRef(false)
   const reauthorizingAccount = shallowRef<AccountRow | null>(null)
   const creatingAccountAction = useAsyncAction()
-  const authorizingOAuthAction = useAsyncAction()
-  const creatingAccount = creatingAccountAction.loading
-  const authorizingOAuth = authorizingOAuthAction.loading
   const createForm = ref(emptyAccountCreateForm())
+  const authorization = useAccountAuthorization(() => finishCreate(reauthorizingAccount.value ? '账号重新授权成功' : '账号已添加'))
+  const selectedProvider = computed(() => catalog.byId.value.get(accountCreateProvider(createForm.value) ?? ''))
   let submissionId: string | undefined
   watch(createForm, () => {
     submissionId = undefined
@@ -48,199 +37,162 @@ export function useAccountOnboarding(options: {
     set: (value: boolean) => {
       createModalOpen.value = value
       if (!value) {
+        authorization.reset()
         reauthorizingAccount.value = null
         createForm.value = emptyAccountCreateForm()
       }
     },
   })
 
+  function requireImportProvider(provider: string | undefined) {
+    if (!provider)
+      throw new Error('请选择账号平台')
+    if (catalog.loading.value || !catalog.byId.value.get(provider)?.credentials.import)
+      throw new Error(`${formatProviderLabel(provider)} 当前不可导入，请刷新平台列表`)
+    return provider
+  }
+
   async function handleCreate() {
     if (createForm.value.mode === 'oauth') {
-      await completeOAuth()
+      await authorization.complete()
       return
     }
-    if (creatingAccount.value)
-      return
-
-    await creatingAccountAction.run(
-      async () => {
-        const proxyError = accountProxyError(createForm.value)
-        if (proxyError)
-          throw new Error(proxyError)
-        const mode = createForm.value.mode
-        if (mode === 'oauth')
-          throw new Error('请选择凭据导入方式')
-        if (mode === 'api_key') {
-          const provider = requireImportProvider(createForm.value.provider)
-          if (provider !== 'openai')
-            throw new Error('当前平台不支持 API Key 账号')
-          const form = createForm.value.apiKey
-          const error = apiKeyAccountError(form)
-          if (error)
-            throw new Error(error)
-          await importAccounts({
-            provider,
-            settings: accountImportSettings(createForm.value),
-            outboundProxyId: createForm.value.proxyMode === 'proxy' ? createForm.value.proxyId.trim() : undefined,
-            data: { provider, authentication_kind: 'api_key', name: form.name.trim(), base_url: form.base_url.trim(), api_key: form.apiKey, transport: form.transport },
-          })
-          await finishCreate('API Key 账号已添加')
-          return
-        }
-        const documents = createForm.value.provider === 'batch'
-          ? parseMixedImportDocuments(parseImportJson(createForm.value.importTexts.json))
-          : accountImportDocuments(requireImportProvider(createForm.value.provider), mode, createForm.value.importTexts[mode])
-        if (documents.length > MAX_TOKEN_IMPORT_COUNT)
-          throw new Error(`单次最多导入 ${MAX_TOKEN_IMPORT_COUNT} 个条目`)
-        submissionId ??= generateRequestId()
-        const task = await createAccountImportTask({
-          submissionId,
-          items: documents.map(entry => ({
-            provider: entry.provider,
-            data: entry.document,
-            settings: accountImportSettings(createForm.value),
-            outboundProxyId: createForm.value.proxyMode === 'proxy' ? createForm.value.proxyId.trim() : undefined,
-          })),
+    await creatingAccountAction.run(async () => {
+      const form = createForm.value
+      const proxyError = accountProxyError(form)
+      if (proxyError)
+        throw new Error(proxyError)
+      const settings = accountImportSettings(form)
+      const outboundProxyId = form.proxyMode === 'proxy' ? form.proxyId.trim() : undefined
+      const mode = form.mode
+      if (mode === 'oauth')
+        return
+      const provider = accountCreateProvider(form)
+      if (mode === 'api_key') {
+        if (requireImportProvider(provider) !== 'openai')
+          throw new Error('当前平台不支持 API Key 账号')
+        const error = apiKeyAccountError(form.apiKey)
+        if (error)
+          throw new Error(error)
+        await importAccounts({
+          provider: 'openai',
+          settings,
+          outboundProxyId,
+          data: { provider: 'openai', authentication_kind: 'api_key', name: form.apiKey.name.trim(), base_url: form.apiKey.base_url.trim(), api_key: form.apiKey.apiKey, transport: form.apiKey.transport },
         })
-        showCreateModal.value = false
-        options.onImportTaskCreated(task)
-        toast.success('导入任务已创建')
-      },
-    )
+        await finishCreate('API Key 账号已添加')
+        return
+      }
+      const documents = form.source?.kind === 'bundle'
+        ? mixedImportDocuments(form.importTexts.json)
+        : mode === 'form'
+          ? [{ provider: requireImportProvider(provider), document: parseJsonObject(form.importInput) }]
+          : accountImportDocuments(requireImportProvider(provider), mode, form.importTexts[mode])
+      if (documents.length > MAX_ACCOUNT_IMPORT_COUNT)
+        throw new Error(`单次最多导入 ${MAX_ACCOUNT_IMPORT_COUNT} 个条目`)
+      for (const document of documents)
+        requireImportProvider(document.provider)
+      submissionId ??= generateRequestId()
+      const task = await createAccountImportTask({
+        submissionId,
+        items: documents.map(entry => ({ provider: entry.provider, data: entry.document, settings, outboundProxyId })),
+      })
+      showCreateModal.value = false
+      options.onImportTaskCreated(task)
+      toast.success('导入任务已创建')
+    })
   }
 
   async function handleAuthorizeOAuth() {
-    if (authorizingOAuth.value)
+    if (authorization.busy.value)
       return
-
-    await authorizingOAuthAction.run(
-      async () => {
-        const input = newAccountInput()
-        const account = reauthorizingAccount.value
-        const proxyError = accountProxyError(createForm.value)
-        if (!account && proxyError)
-          throw new Error(proxyError)
-        const result = await startAccountOAuth({
-          ...input,
-          outboundProxyId: !account && createForm.value.proxyMode === 'proxy' ? createForm.value.proxyId.trim() : undefined,
-          ...(account
-            ? {
-                accountId: account.id,
-              }
-            : {}),
-        })
-
-        createForm.value = {
-          ...createForm.value,
-          oauthFlowId: result.flowId,
-          oauthAuthUrl: result.authorizationUrl,
-          oauthCallback: '',
-        }
-        toast.success('授权链接已生成')
-      },
-    )
-  }
-
-  async function completeOAuth() {
-    if (creatingAccount.value)
-      return
-
-    await creatingAccountAction.run(
-      async () => {
-        if (!createForm.value.oauthFlowId)
-          throw new Error('请先生成授权链接')
-
-        const callbackUrl = createForm.value.oauthCallback.trim()
-        if (!callbackUrl) {
-          throw new Error(createForm.value.provider === 'xai'
-            ? '请粘贴 OAuth 回调地址、含 code 和 state 的查询字符串或授权码'
-            : '请粘贴 OAuth 回调地址')
-        }
-        await completeAccountOAuth({
-          provider: createForm.value.provider,
-          flowId: createForm.value.oauthFlowId,
-          callbackUrl,
-          settings: reauthorizingAccount.value ? undefined : accountImportSettings(createForm.value),
-        })
-        await finishCreate(
-          reauthorizingAccount.value
-            ? '账号重新授权成功'
-            : createForm.value.provider === 'xai'
-              ? 'xAI OAuth 账号已添加'
-              : 'OpenAI OAuth 账号已添加',
-        )
-      },
-    )
+    try {
+      const form = createForm.value
+      const provider = selectedProvider.value
+      if (catalog.loading.value || !provider?.credentials.login)
+        throw new Error('当前平台不可授权，请刷新平台列表')
+      const account = reauthorizingAccount.value
+      const proxyError = accountProxyError(form)
+      if (proxyError)
+        throw new Error(proxyError)
+      await authorization.start({
+        start: {
+          provider: provider.provider,
+          name: account?.name || account?.email || `${formatProviderLabel(provider.provider)} 账号`,
+          accountId: account?.id,
+          outboundProxyId: account ? undefined : form.proxyMode === 'proxy' ? form.proxyId.trim() : undefined,
+          input: parseJsonObject(form.loginInput, 64 * 1024),
+        },
+        completion: provider.credentials.login.completion,
+        settings: account ? undefined : accountImportSettings(form),
+      })
+      if (authorization.view.value.flow)
+        form.loginInput = '{}'
+    }
+    catch (cause) {
+      toast.error(errorMessage(cause, '启动授权失败'))
+    }
   }
 
   function openCreateAccount() {
+    authorization.reset()
     reauthorizingAccount.value = null
     createForm.value = emptyAccountCreateForm()
     showCreateModal.value = true
+    void catalog.load()
   }
 
   function openReauthorizeAccount(account: AccountRow) {
-    if (account.authenticationKind !== 'oauth' || (account.provider !== 'openai' && account.provider !== 'xai'))
+    if (isSupportedProvider(account.provider) && account.authenticationKind !== 'oauth')
       return
+    authorization.reset()
     reauthorizingAccount.value = account
-    createForm.value = {
-      ...emptyAccountCreateForm(),
-      provider: account.provider,
-      step: 'import',
-      mode: 'oauth',
-    }
+    createForm.value = { ...emptyAccountCreateForm(), source: { kind: 'provider', id: account.provider }, step: 'import' }
     showCreateModal.value = true
-    void handleAuthorizeOAuth()
-  }
-
-  function newAccountInput() {
-    const account = reauthorizingAccount.value
-    return {
-      provider: createForm.value.provider,
-      name: account?.name || account?.email || `${createForm.value.provider} OAuth`,
-    }
+    void catalog.load()
   }
 
   async function finishCreate(message: string) {
     showCreateModal.value = false
-    await options.reload()
     toast.success(message)
+    await options.reload()
   }
 
-  watch(
-    () => createForm.value.provider,
-    () => {
-      createForm.value = {
-        ...createForm.value,
-        mode: createForm.value.provider === 'batch' ? 'json' : 'oauth',
-        apiKey: emptyApiKeyAccountForm(),
-        importTexts: { access_token: '', refresh_token: '', json: '' },
-        oauthFlowId: '',
-        oauthAuthUrl: '',
-        oauthCallback: '',
-      }
-    },
-    { flush: 'sync' },
-  )
+  watch(() => accountCreateSourceKey(createForm.value), () => {
+    createForm.value = {
+      ...createForm.value,
+      mode: reauthorizingAccount.value ? 'oauth' : createForm.value.source?.kind === 'bundle' ? 'json' : accountImportModes(selectedProvider.value)[0]?.value ?? 'json',
+      apiKey: emptyApiKeyAccountForm(),
+      importTexts: { access_token: '', refresh_token: '', json: '' },
+      loginInput: '{}',
+      importInput: '{}',
+    }
+  }, { flush: 'sync' })
 
-  watch(
-    [
-      () => createForm.value.proxyMode,
-      () => createForm.value.proxyMode === 'proxy' ? createForm.value.proxyId.trim() : '',
-    ],
-    () => {
-      createForm.value.oauthFlowId = ''
-      createForm.value.oauthAuthUrl = ''
-      createForm.value.oauthCallback = ''
-    },
-    { flush: 'sync' },
-  )
+  watch([
+    () => accountCreateSourceKey(createForm.value),
+    () => createForm.value.mode,
+    () => createForm.value.step,
+    () => createForm.value.proxyMode,
+    () => createForm.value.proxyMode === 'proxy' ? createForm.value.proxyId.trim() : '',
+  ], () => {
+    authorization.reset()
+    createForm.value.loginInput = '{}'
+  }, { flush: 'sync' })
 
   return {
     showCreateModal,
     reauthorizingAccount,
-    creatingAccount,
-    authorizingOAuth,
+    creatingAccount: creatingAccountAction.loading,
+    authorizingOAuth: authorization.busy,
+    authorization: authorization.view,
+    authorizationCallback: authorization.callback,
+    resetAuthorization: authorization.reset,
+    accountProviders: catalog.providers,
+    accountProvidersById: catalog.byId,
+    accountProvidersLoading: catalog.loading,
+    accountProvidersError: catalog.error,
+    loadAccountProviders: catalog.load,
     createForm,
     handleCreate,
     handleAuthorizeOAuth,
@@ -248,85 +200,3 @@ export function useAccountOnboarding(options: {
     openReauthorizeAccount,
   }
 }
-
-function parseImportJson(value: string) {
-  try {
-    return JSON.parse(value)
-  }
-  catch {
-    throw new Error('JSON 格式不正确')
-  }
-}
-
-function requireImportProvider(value: string): ImportProvider {
-  if (isSupportedProvider(value))
-    return value
-  throw new Error('请选择要导入的账号平台')
-}
-
-function accountImportDocuments(
-  provider: ImportProvider,
-  mode: string,
-  value: string,
-): MixedImportDocument[] {
-  if (provider === 'openai' && isOpenAiTokenImportMode(mode)) {
-    return parseOpenAiTokenImport(value, mode).map(document => ({ provider, document }))
-  }
-  return providerImportDocuments(parseImportJson(value), provider)
-}
-
-function parseOpenAiTokenImport(value: string, mode: OpenAiTokenImportMode) {
-  const tokens = value
-    .split(/\r?\n/)
-    .map(token => token.trim())
-    .filter(Boolean)
-  const label = mode === 'access_token' ? 'Access Token' : 'Refresh Token'
-
-  if (tokens.length === 0)
-    throw new Error(`请至少粘贴一个 ${label}`)
-  if (tokens.length > MAX_TOKEN_IMPORT_COUNT)
-    throw new Error(`单次最多导入 ${MAX_TOKEN_IMPORT_COUNT} 个 ${label}`)
-
-  const credentialKey = mode === 'access_token' ? 'accessToken' : 'refreshToken'
-  return tokens.map(token => ({ accounts: [{ [credentialKey]: token }] }))
-}
-
-function isOpenAiTokenImportMode(value: string): value is OpenAiTokenImportMode {
-  return value === 'access_token' || value === 'refresh_token'
-}
-
-function providerImportDocuments(value: unknown, provider: ImportProvider): MixedImportDocument[] {
-  if (isRecord(value) && Array.isArray(value.documents)) {
-    const documents = parseMixedImportDocuments(value)
-      .filter(entry => entry.provider === provider)
-    if (documents.length === 0) {
-      const label = formatProviderLabel(provider)
-      throw new Error(`批量导入文件不包含 ${label} 账号文档`)
-    }
-    return documents
-  }
-  if (!isRecord(value))
-    throw new Error('导入文件必须是 JSON object')
-  return [{ provider, document: value }]
-}
-
-function parseMixedImportDocuments(value: unknown): MixedImportDocument[] {
-  if (!isRecord(value) || !Array.isArray(value.documents))
-    throw new Error('批量导入文件必须是 CPR 多平台导出文件')
-
-  const documents: MixedImportDocument[] = []
-  for (const entry of value.documents) {
-    if (!isRecord(entry))
-      throw new Error('批量导入文件包含无效的 Provider 文档')
-    const provider = entry.provider
-    if (!isSupportedProvider(provider))
-      throw new Error('批量导入文件包含无效的 Provider 文档')
-    if (!isRecord(entry.document))
-      throw new Error('批量导入文件包含无效的 Provider 文档')
-    documents.push({ provider, document: entry.document })
-  }
-
-  if (documents.length === 0)
-    throw new Error('批量文件没有可导入的账号文档')
-  return documents
-}
diff --git a/frontend/src/views/accounts/composables/useAccountPersonalInfo.ts b/frontend/src/views/accounts/composables/useAccountPersonalInfo.ts
index 2d5acf049..693f63b89 100644
--- a/frontend/src/views/accounts/composables/useAccountPersonalInfo.ts
+++ b/frontend/src/views/accounts/composables/useAccountPersonalInfo.ts
@@ -1,17 +1,21 @@
 import type { Ref } from 'vue'
-import type { AccountPersonalInfoResponse } from '@/api'
+import type { AccountCapabilities, AccountPersonalInfoResponse } from '@/api'
 import { computed, shallowRef, watch } from 'vue'
 
 import { getAccountPersonalInfo } from '@/api'
 import { useRequestState } from '@/composables/useRequestState'
 
-export function useAccountPersonalInfo(accountId: Ref<string>, open: Ref<boolean>) {
+export function useAccountPersonalInfo({ accountId, open, capabilities }: {
+  accountId: Ref<string>
+  open: Ref<boolean>
+  capabilities: Ref<AccountCapabilities>
+}) {
   const info = shallowRef<AccountPersonalInfoResponse | null>(null)
   const request = useRequestState()
   const { loading } = request
-  const profile = computed(() => info.value?.profile ?? null)
-  const subscription = computed(() => info.value?.subscription ?? null)
-  const error = computed(() => request.error.value || info.value?.profileError || '')
+  const profile = computed(() => capabilities.value.profile ? info.value?.profile ?? null : null)
+  const subscription = computed(() => capabilities.value.subscription ? info.value?.subscription ?? null : null)
+  const error = computed(() => request.error.value || (capabilities.value.profile ? info.value?.profileError : '') || '')
 
   async function load() {
     const targetAccountId = accountId.value
@@ -35,7 +39,7 @@ export function useAccountPersonalInfo(accountId: Ref<string>, open: Ref<boolean
   }
 
   // 打开或切换账号只请求一次；关闭取消等待，刷新按钮复用同一入口。
-  watch([open, accountId], ([isOpen]) => {
+  watch([open, accountId, () => capabilities.value.profile, () => capabilities.value.subscription], ([isOpen]) => {
     request.invalidate()
     info.value = null
     request.error.value = ''
diff --git a/frontend/src/views/accounts/composables/useAccountProviders.ts b/frontend/src/views/accounts/composables/useAccountProviders.ts
new file mode 100644
index 000000000..b5c14940a
--- /dev/null
+++ b/frontend/src/views/accounts/composables/useAccountProviders.ts
@@ -0,0 +1,39 @@
+import type { AccountProvider } from '@/api'
+import { computed, onMounted, onScopeDispose, shallowRef } from 'vue'
+import { getAccountProviders } from '@/api'
+import { errorMessage } from '@/utils/async'
+
+export function useAccountProviders() {
+  const providers = shallowRef<AccountProvider[]>([])
+  const loading = shallowRef(false)
+  const error = shallowRef('')
+  const byId = computed(() => new Map(providers.value.map(provider => [provider.provider, provider])))
+  let controller: AbortController | undefined
+
+  async function load() {
+    controller?.abort()
+    const current = new AbortController()
+    controller = current
+    loading.value = true
+    error.value = ''
+    try {
+      const result = await getAccountProviders({ signal: current.signal, silent: true })
+      if (!current.signal.aborted)
+        providers.value = result
+    }
+    catch (cause) {
+      if (!current.signal.aborted) {
+        providers.value = []
+        error.value = errorMessage(cause, '平台能力加载失败')
+      }
+    }
+    finally {
+      if (!current.signal.aborted)
+        loading.value = false
+    }
+  }
+
+  onMounted(load)
+  onScopeDispose(() => controller?.abort())
+  return { providers, byId, loading, error, load }
+}
diff --git a/frontend/src/views/accounts/composables/useAccountQuotaForecast.ts b/frontend/src/views/accounts/composables/useAccountQuotaForecast.ts
index 41a4550de..69a1dccce 100644
--- a/frontend/src/views/accounts/composables/useAccountQuotaForecast.ts
+++ b/frontend/src/views/accounts/composables/useAccountQuotaForecast.ts
@@ -1,8 +1,8 @@
 import type { Ref } from 'vue'
 import type { Account, AccountQuotaForecastResponse } from '@/api'
+import { toast } from '@codex-proxy/ui'
 import { onScopeDispose, shallowRef, watch } from 'vue'
 import { getAccountQuotaForecast, refreshAccountQuota } from '@/api'
-import { toast } from '@/components/base/BaseToast'
 
 export function useAccountQuotaForecast(
   accountId: Ref<string>,
diff --git a/frontend/src/views/accounts/composables/useAccountResetCredits.ts b/frontend/src/views/accounts/composables/useAccountResetCredits.ts
index 980a658c3..3c79e844d 100644
--- a/frontend/src/views/accounts/composables/useAccountResetCredits.ts
+++ b/frontend/src/views/accounts/composables/useAccountResetCredits.ts
@@ -1,12 +1,12 @@
 import type { AccountResetCredit } from '@/api'
+import { toast } from '@codex-proxy/ui'
 import { computed, shallowReactive, shallowRef, watch } from 'vue'
+
 import {
   consumeAccountResetCredit,
   getAccountResetCredits,
 } from '@/api'
-
 import { ApiError } from '@/api/request'
-import { toast } from '@/components/base/BaseToast'
 import { errorMessage } from '@/utils/async'
 import { generateRequestId } from '@/utils/uuid'
 
@@ -83,6 +83,7 @@ async function loadSessionCredits(session: ResetCreditsSession, silent = false)
 export function useAccountResetCredits(options: {
   accountId: () => string
   onConsumed: (accountId: string) => void
+  capabilities: () => { consumeResetCredit: boolean }
 }) {
   const session = shallowRef(getResetCreditsSession(options.accountId()))
   const credits = computed(() => session.value.snapshot?.credits ?? [])
@@ -110,7 +111,7 @@ export function useAccountResetCredits(options: {
     && (selectedCredit.value !== undefined || availableCredits.value.length === 0),
   )
   const canRequestConsume = computed(() =>
-    ambiguous.value || canStartConsume.value,
+    options.capabilities().consumeResetCredit && (ambiguous.value || canStartConsume.value),
   )
 
   function reconcileSelectedCredit() {
@@ -160,7 +161,7 @@ export function useAccountResetCredits(options: {
 
   async function confirmConsume(): Promise<boolean> {
     const target = session.value
-    if (!showConfirm.value || target.consuming || target.loading)
+    if (!options.capabilities().consumeResetCredit || !showConfirm.value || target.consuming || target.loading)
       return false
 
     const credit = selectedCredit.value
diff --git a/frontend/src/views/accounts/composables/useAccountsQuery.ts b/frontend/src/views/accounts/composables/useAccountsQuery.ts
index 863a767fc..19c4ee020 100644
--- a/frontend/src/views/accounts/composables/useAccountsQuery.ts
+++ b/frontend/src/views/accounts/composables/useAccountsQuery.ts
@@ -1,4 +1,4 @@
-import type { BaseTableSort } from '@/components/base/BaseTable/columns'
+import type { BaseTableSort } from '@codex-proxy/ui'
 import { watchDebounced } from '@vueuse/core'
 
 import { computed, onMounted, shallowRef, watch } from 'vue'
@@ -10,6 +10,7 @@ type AccountRow = Awaited<ReturnType<typeof getAccounts>>['items'][number]
 export function useAccountsQuery() {
   const searchQuery = shallowRef('')
   const providerQuery = shallowRef('')
+  const providers = shallowRef<string[]>([])
   const statusQuery = shallowRef('')
   const groupQuery = shallowRef('')
   const sort = shallowRef<BaseTableSort>()
@@ -37,6 +38,7 @@ export function useAccountsQuery() {
       }, options),
     onSuccess: (result) => {
       accountSummary.value = result.summary
+      providers.value = result.providers
     },
   })
 
@@ -102,6 +104,7 @@ export function useAccountsQuery() {
     refreshAccountsSilently: () => query.execute({ silent: true }),
     searchQuery,
     providerQuery,
+    providers,
     statusQuery,
     groupQuery,
     sort,
diff --git a/frontend/src/views/accounts/constants.ts b/frontend/src/views/accounts/constants.ts
index 21a50199b..ccbbaf222 100644
--- a/frontend/src/views/accounts/constants.ts
+++ b/frontend/src/views/accounts/constants.ts
@@ -1,5 +1,5 @@
 import type { AccountErrorReason, AccountStatus, getAccounts } from '@/api'
-import { defineTableColumns } from '@/components/base/BaseTable/columns'
+import { defineTableColumns } from '@codex-proxy/ui'
 import { formatProviderLabel } from '@/utils/providers'
 
 export type AccountRow = Awaited<ReturnType<typeof getAccounts>>['items'][number]
diff --git a/frontend/src/views/accounts/index.vue b/frontend/src/views/accounts/index.vue
index edc4695f7..adfe97bac 100644
--- a/frontend/src/views/accounts/index.vue
+++ b/frontend/src/views/accounts/index.vue
@@ -1,16 +1,9 @@
 <script setup lang="ts">
+import { BaseCard, BaseCheckbox, BaseConfirmModal, BasePageHeader, BaseTable, BaseTableColumnSettings, BaseTablePagination, useTableColumns } from '@codex-proxy/ui'
+
 import { ChevronDown } from '@lucide/vue'
 import { ref } from 'vue'
-
 import AccountGroupMarks from '@/components/AccountGroupMarks.vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseCheckbox from '@/components/base/BaseCheckbox.vue'
-import BaseConfirmModal from '@/components/base/BaseConfirmModal.vue'
-import BasePageHeader from '@/components/base/BasePageHeader.vue'
-import BaseTableColumnSettings from '@/components/base/BaseTable/BaseTableColumnSettings.vue'
-import BaseTablePagination from '@/components/base/BaseTable/BaseTablePagination.vue'
-import BaseTable from '@/components/base/BaseTable/index.vue'
-import { useTableColumns } from '@/components/base/BaseTable/useTableColumns'
 import LastUsedAtCell from '@/components/LastUsedAtCell.vue'
 import ProviderIconGroup from '@/components/ProviderIconGroup.vue'
 import { useAccountGroupCatalog } from '@/composables/useAccountGroupCatalog'
@@ -46,6 +39,7 @@ const {
   refreshAccountsSilently,
   searchQuery,
   providerQuery,
+  providers: accountFilterProviders,
   statusQuery,
   groupQuery,
   sort,
@@ -88,8 +82,17 @@ const {
   deletingAccount,
   creatingAccount,
   authorizingOAuth,
+  authorization,
+  authorizationCallback,
+  resetAuthorization,
+  accountProviders,
+  accountProvidersById,
+  accountProvidersLoading,
+  accountProvidersError,
+  loadAccountProviders,
   batchDeleting,
   exportingAccounts,
+  exportDisabledReason,
   reauthorizingAccount,
   createForm,
   handleCreate,
@@ -208,11 +211,13 @@ const {
           v-model:status="statusQuery"
           v-model:provider="providerQuery"
           v-model:group="groupQuery"
+          :providers="accountFilterProviders"
           :groups="groups"
           :groups-loading="groupsLoading"
           :selected-count="selectedIds.size"
           :batch-deleting="batchDeleting"
           :exporting-accounts="exportingAccounts"
+          :export-disabled-reason="exportDisabledReason"
           :has-import-tasks="recentImportTasks.length > 0"
           :active-import-count="activeImportCount"
           @import-tasks="showImportTasks = true"
@@ -320,6 +325,7 @@ const {
             <template #actions="{ row }">
               <AccountTableActions
                 :account="row"
+                :provider="accountProvidersById.get(row.provider)"
                 :deleting="deletingAccount"
                 :recovering="recoveringAccountIds.has(row.id)"
                 :refreshing="refreshingAccountIds.has(row.id)"
@@ -394,6 +400,11 @@ const {
     <AccountCreateModal
       v-model="showCreateModal"
       v-model:form="createForm"
+      v-model:callback="authorizationCallback"
+      :authorization="authorization"
+      :providers="accountProviders"
+      :providers-loading="accountProvidersLoading"
+      :providers-error="accountProvidersError"
       :account="reauthorizingAccount"
       :groups="groups"
       :groups-loading="groupsLoading"
@@ -402,6 +413,8 @@ const {
       :saving="creatingAccount"
       @create="handleCreate"
       @generate-oauth="handleAuthorizeOAuth"
+      @reset-authorization="resetAuthorization"
+      @reload-providers="loadAccountProviders"
     />
 
     <AccountEditModal
diff --git a/frontend/src/views/accounts/utils/accountImport.ts b/frontend/src/views/accounts/utils/accountImport.ts
new file mode 100644
index 000000000..fa135de31
--- /dev/null
+++ b/frontend/src/views/accounts/utils/accountImport.ts
@@ -0,0 +1,53 @@
+import { isRecord } from '@/utils/object'
+import { formatProviderLabel, isSupportedProvider } from '@/utils/providers'
+
+export const MAX_ACCOUNT_IMPORT_COUNT = 200
+export interface AccountImportDocument {
+  provider: string
+  document: Record<string, unknown>
+}
+
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  }
+  catch {
+    throw new Error('JSON 格式不正确')
+  }
+}
+
+export function mixedImportDocuments(text: string): AccountImportDocument[] {
+  const value = parseJson(text)
+  if (!isRecord(value) || !Array.isArray(value.documents))
+    throw new Error('批量导入文件必须是 CPR 多平台导出文件')
+  const documents = value.documents.map((entry): AccountImportDocument => {
+    if (!isRecord(entry) || typeof entry.provider !== 'string' || !entry.provider.trim() || !isRecord(entry.document))
+      throw new Error('批量导入文件包含无效的 Provider 文档')
+    return { provider: entry.provider, document: entry.document }
+  })
+  if (!documents.length)
+    throw new Error('批量文件没有可导入的账号文档')
+  return documents
+}
+
+export function accountImportDocuments(provider: string, mode: string, text: string): AccountImportDocument[] {
+  if (provider === 'openai' && (mode === 'access_token' || mode === 'refresh_token')) {
+    const tokens = text.split(/\r?\n/).map(token => token.trim()).filter(Boolean)
+    const label = mode === 'access_token' ? 'Access Token' : 'Refresh Token'
+    if (!tokens.length)
+      throw new Error(`请至少粘贴一个 ${label}`)
+    const key = mode === 'access_token' ? 'accessToken' : 'refreshToken'
+    return tokens.map(token => ({ provider, document: { accounts: [{ [key]: token }] } }))
+  }
+  const value = parseJson(text)
+  // 原生快捷入口保留 CPR 文件展开，插件文档的字段含义由插件自己解释。
+  if (isSupportedProvider(provider) && isRecord(value) && Array.isArray(value.documents)) {
+    const documents = mixedImportDocuments(text).filter(entry => entry.provider === provider)
+    if (!documents.length)
+      throw new Error(`批量导入文件不包含 ${formatProviderLabel(provider)} 账号文档`)
+    return documents
+  }
+  if (!isRecord(value))
+    throw new Error('导入文件必须是 JSON 对象')
+  return [{ provider, document: value }]
+}
diff --git a/frontend/src/views/accounts/utils/upstreamApiKey.ts b/frontend/src/views/accounts/utils/upstreamApiKey.ts
index fc18b2b6b..ce0a55d86 100644
--- a/frontend/src/views/accounts/utils/upstreamApiKey.ts
+++ b/frontend/src/views/accounts/utils/upstreamApiKey.ts
@@ -1,4 +1,8 @@
-import type { ApiKeyConfiguration } from '@/api'
+import type { Account, ApiKeyConfiguration } from '@/api'
+
+export function isOpenAiApiKeyAccount(account: Pick<Account, 'provider' | 'authenticationKind'> | null | undefined): boolean {
+  return account?.provider === 'openai' && account.authenticationKind === 'api_key'
+}
 
 export interface ApiKeyAccountForm extends ApiKeyConfiguration {
   name: string
@@ -9,6 +13,12 @@ export function emptyApiKeyAccountForm(): ApiKeyAccountForm {
   return { name: '', base_url: '', apiKey: '', transport: 'http' }
 }
 
+export function parseApiKeyConfiguration(value: Record<string, unknown> | undefined): ApiKeyConfiguration | undefined {
+  if (!value || typeof value.base_url !== 'string' || (value.transport !== 'http' && value.transport !== 'prefer_websocket'))
+    return undefined
+  return { base_url: value.base_url, transport: value.transport }
+}
+
 export function apiKeyAccountError(form: ApiKeyAccountForm, editing = false): string | undefined {
   if (!editing && !form.name.trim())
     return '请输入账号名称'
diff --git a/frontend/src/views/dashboard/components/AccountOverviewCard.vue b/frontend/src/views/dashboard/components/AccountOverviewCard.vue
index 01135803c..be0bf41ff 100644
--- a/frontend/src/views/dashboard/components/AccountOverviewCard.vue
+++ b/frontend/src/views/dashboard/components/AccountOverviewCard.vue
@@ -1,10 +1,9 @@
 <script setup lang="ts">
 import type { dashboardSnapshotView, MetricTone } from '../composables/useDashboard'
-import { CircleCheck, RefreshCw, ShieldAlert, TriangleAlert } from '@lucide/vue'
+import { BaseCard, BaseEmpty } from '@codex-proxy/ui'
 
+import { CircleCheck, RefreshCw, ShieldAlert, TriangleAlert } from '@lucide/vue'
 import { computed } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
 import { formatCompactNumber } from '@/utils/number'
 import AccountUsageWindow from '@/views/accounts/components/AccountUsageWindow/index.vue'
 import { metricToneIconClasses, metricToneValueClasses } from '../constants'
diff --git a/frontend/src/views/dashboard/components/DashboardAccountIdentity.vue b/frontend/src/views/dashboard/components/DashboardAccountIdentity.vue
index 5ea56c24c..3daf6daaa 100644
--- a/frontend/src/views/dashboard/components/DashboardAccountIdentity.vue
+++ b/frontend/src/views/dashboard/components/DashboardAccountIdentity.vue
@@ -1,9 +1,8 @@
 <script setup lang="ts">
 import type { dashboardSnapshotView } from '../composables/useDashboard'
-import { Key, LinkAlt, Openai, Xai } from '@boxicons/vue'
 import { computed } from 'vue'
 
-import { formatProviderLabel } from '@/utils/providers'
+import { authenticationIcon, formatAuthenticationLabel, formatProviderLabel, providerIcon } from '@/utils/providers'
 import AccountPlanBadge from '@/views/accounts/components/AccountPlanBadge.vue'
 import { stablePresetVisualToneClass } from '@/views/accounts/utils/visualTone'
 
@@ -17,18 +16,11 @@ const props = defineProps<{
 const email = computed(() => props.account.email?.trim() || String(props.account.id))
 const displayTitle = computed(() => email.value.split('@')[0] || email.value)
 const normalizedProvider = computed(() => props.account.provider?.trim().toLowerCase() || '')
-const normalizedAuthenticationKind = computed(() =>
-  props.account.authenticationKind?.trim().toLowerCase() || '',
-)
+const providerIconComponent = computed(() => normalizedProvider.value ? providerIcon(normalizedProvider.value) : undefined)
+const authenticationIconComponent = computed(() => authenticationIcon(props.account.authenticationKind))
 const providerLabel = computed(() => formatProviderLabel(props.account.provider, '未知平台'))
 
-const authenticationLabel = computed(() => {
-  if (normalizedAuthenticationKind.value === 'oauth')
-    return 'OAuth'
-  if (normalizedAuthenticationKind.value === 'api_key')
-    return 'API Key'
-  return props.account.authenticationKind?.trim() || '未知认证类型'
-})
+const authenticationLabel = computed(() => formatAuthenticationLabel(props.account.authenticationKind))
 
 const avatarToneClass = computed(() =>
   stablePresetVisualToneClass(props.account.id || props.account.email || email.value),
@@ -43,8 +35,7 @@ const avatarToneClass = computed(() =>
         :class="avatarToneClass"
         :title="providerLabel"
       >
-        <Openai v-if="normalizedProvider === 'openai'" class="size-3.5" />
-        <Xai v-else-if="normalizedProvider === 'xai'" class="size-3.5" />
+        <component :is="providerIconComponent" v-if="providerIconComponent" class="size-3.5" />
         <span v-else class="text-cp-xs font-heavy">?</span>
         <span class="sr-only">{{ providerLabel }}</span>
       </span>
@@ -53,8 +44,7 @@ const avatarToneClass = computed(() =>
         class="absolute -right-1 -bottom-1 inline-flex size-4 items-center justify-center rounded-[5px] bg-cp-bg-container text-cp-text shadow-cp-tertiary"
         :title="authenticationLabel"
       >
-        <LinkAlt v-if="normalizedAuthenticationKind === 'oauth'" class="size-2.5" />
-        <Key v-else-if="normalizedAuthenticationKind === 'api_key'" class="size-2.5" />
+        <component :is="authenticationIconComponent" v-if="authenticationIconComponent" class="size-2.5" />
         <span v-else class="text-[8px] font-heavy text-cp-text-quaternary">?</span>
         <span class="sr-only">{{ authenticationLabel }}</span>
       </span>
diff --git a/frontend/src/views/dashboard/components/DashboardContent.vue b/frontend/src/views/dashboard/components/DashboardContent.vue
index c35cfdde7..60a487333 100644
--- a/frontend/src/views/dashboard/components/DashboardContent.vue
+++ b/frontend/src/views/dashboard/components/DashboardContent.vue
@@ -1,10 +1,9 @@
 <script setup lang="ts">
 import type { dashboardSnapshotView, dashboardTrendView } from '../composables/useDashboard'
 import type { DashboardTrendKind } from '@/api/modules/dashboard'
-import { RefreshCw } from '@lucide/vue'
+import { BaseIconButton, BasePageHeader } from '@codex-proxy/ui'
 
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BasePageHeader from '@/components/base/BasePageHeader.vue'
+import { RefreshCw } from '@lucide/vue'
 
 import AccountOverviewCard from './AccountOverviewCard.vue'
 import DashboardHeartbeat from './DashboardHeartbeat.vue'
diff --git a/frontend/src/views/dashboard/components/MetricCard.vue b/frontend/src/views/dashboard/components/MetricCard.vue
index e4b73851a..bcc0fc471 100644
--- a/frontend/src/views/dashboard/components/MetricCard.vue
+++ b/frontend/src/views/dashboard/components/MetricCard.vue
@@ -2,9 +2,8 @@
 import type { EChartsOption } from 'echarts'
 import type { MetricCardView, MetricTone } from '../composables/useDashboard'
 
+import { BaseCard, BaseMotionIcon } from '@codex-proxy/ui'
 import { computed } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseMotionIcon from '@/components/base/BaseMotionIcon.vue'
 
 import BaseChart from '@/components/charts/BaseChart.vue'
 import { useThemeColor } from '@/composables/useThemeColor'
diff --git a/frontend/src/views/dashboard/components/RequestHealthTimelineCard.vue b/frontend/src/views/dashboard/components/RequestHealthTimelineCard.vue
index d556ceac2..c341d2af3 100644
--- a/frontend/src/views/dashboard/components/RequestHealthTimelineCard.vue
+++ b/frontend/src/views/dashboard/components/RequestHealthTimelineCard.vue
@@ -1,11 +1,10 @@
 <script setup lang="ts">
 import type { HealthTimeline, HealthTimelinePoint } from '../constants'
+import { BaseCard, BasePopover } from '@codex-proxy/ui'
+
 import { usePreferredReducedMotion } from '@vueuse/core'
 import { gsap } from 'gsap'
-
 import { computed, onBeforeUnmount, shallowRef, useTemplateRef, watch } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BasePopover from '@/components/base/BasePopover.vue'
 import { formatHealthCount, healthLegend, healthReliabilityValueClass, healthStatusMeta } from '../constants'
 import HealthTimelinePointPopover from './HealthTimelinePointPopover.vue'
 
diff --git a/frontend/src/views/dashboard/components/RequestTrendCard.vue b/frontend/src/views/dashboard/components/RequestTrendCard.vue
index 8565ba0f9..c890b5495 100644
--- a/frontend/src/views/dashboard/components/RequestTrendCard.vue
+++ b/frontend/src/views/dashboard/components/RequestTrendCard.vue
@@ -1,10 +1,8 @@
 <script setup lang="ts">
 import type { dashboardTrendView, normalizeDashboardTrendKind } from '../composables/useDashboard'
 
+import { BaseCard, BaseEmpty, BaseSegmented } from '@codex-proxy/ui'
 import { toRef } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
 import BaseChart from '@/components/charts/BaseChart.vue'
 import { useRequestTrendChart } from '../composables/useRequestTrendChart'
 
diff --git a/frontend/src/views/dashboard/components/UsageRecordCard.vue b/frontend/src/views/dashboard/components/UsageRecordCard.vue
index e234bb63d..75f4bc544 100644
--- a/frontend/src/views/dashboard/components/UsageRecordCard.vue
+++ b/frontend/src/views/dashboard/components/UsageRecordCard.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import type { dashboardSnapshotView } from '../composables/useDashboard'
 
-import BaseCard from '@/components/base/BaseCard.vue'
+import { BaseCard } from '@codex-proxy/ui'
 import UsageRecordsTable from '@/views/usage/components/UsageRecordsTable.vue'
 import { usageRecordColumns } from '@/views/usage/constants'
 
diff --git a/frontend/src/views/dashboard/components/WireProfileCard.vue b/frontend/src/views/dashboard/components/WireProfileCard.vue
index 2dc018d9a..b6ec217ad 100644
--- a/frontend/src/views/dashboard/components/WireProfileCard.vue
+++ b/frontend/src/views/dashboard/components/WireProfileCard.vue
@@ -1,13 +1,10 @@
 <script setup lang="ts">
-import { Openai, Xai } from '@boxicons/vue'
-import { Box, CheckCircle2, Monitor, RefreshCw, ShieldCheck, Terminal, TriangleAlert } from '@lucide/vue'
+import { BaseCard, BaseEmpty, BaseSegmented } from '@codex-proxy/ui'
 
+import { Box, CheckCircle2, Monitor, RefreshCw, ShieldCheck, Terminal, TriangleAlert } from '@lucide/vue'
 import { computed, shallowRef, watch } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
 import { formatDateTime } from '@/utils/date'
-import { formatProviderLabel } from '@/utils/providers'
+import { formatProviderLabel, isSupportedProvider, providerIcon } from '@/utils/providers'
 
 interface WireProfile {
   provider: string
@@ -40,9 +37,9 @@ const activeProvider = shallowRef('')
 
 const providerOptions = computed(() =>
   props.profiles.map(profile => ({
-    label: providerLabel(profile.provider),
+    label: formatProviderLabel(profile.provider),
     value: profile.provider,
-    icon: profile.provider === 'openai' ? Openai : profile.provider === 'xai' ? Xai : undefined,
+    icon: providerIcon(profile.provider),
   })),
 )
 
@@ -138,6 +135,15 @@ const clientIdentity = computed(() => {
   return current.provider === 'xai' ? toPascalCase(value) : value
 })
 
+const identityAttributes = computed(() => {
+  const current = profile.value
+  if (!current)
+    return []
+  return isSupportedProvider(current.provider)
+    ? [{ label: '客户端标识', value: clientIdentity.value }]
+    : current.attributes
+})
+
 const authProtocol = computed(() => {
   const value = profile.value?.attributes.find(attribute => attribute.label === 'Token 认证')?.value
   if (!value)
@@ -168,23 +174,25 @@ watch(
   },
   { immediate: true },
 )
-
-function providerLabel(provider: string) {
-  return formatProviderLabel(provider)
-}
 </script>
 
 <template>
-  <BaseCard as="article" title="通用上游身份" class="flex min-h-95 w-full flex-col">
-    <template #actions>
-      <BaseSegmented
-        v-if="providerOptions.length > 1"
-        v-model="activeProvider"
-        label="上游平台"
-        :options="providerOptions"
-        display="icon"
-        class="w-21"
-      />
+  <BaseCard as="article" class="flex min-h-95 w-full flex-col">
+    <template #header>
+      <div class="flex min-w-0 flex-wrap items-start justify-between gap-3">
+        <h2 class="m-0 pt-0.5 text-xl leading-[1.15] font-heavy text-cp-text text-balance">
+          通用上游身份
+        </h2>
+        <div v-if="providerOptions.length > 1" class="min-w-0 max-w-full overflow-x-auto">
+          <BaseSegmented
+            v-model="activeProvider"
+            label="上游平台"
+            :options="providerOptions"
+            :style="{ width: `${providerOptions.length * 40 + 4}px` }"
+            display="icon"
+          />
+        </div>
+      </div>
     </template>
 
     <template #body>
@@ -205,7 +213,7 @@ function providerLabel(provider: string) {
               <span class="inline-flex size-7 shrink-0 items-center justify-center rounded-lg bg-cp-fill-tertiary">
                 <Box class="size-3.75 text-cp-text-secondary" />
               </span>
-              <span class="truncate text-cp-xs leading-none font-heavy">{{ profile.product }}</span>
+              <span class="truncate text-cp-xs leading-none font-heavy" :title="profile.product">{{ profile.product }}</span>
             </div>
             <span
               class="inline-flex h-7 shrink-0 items-center gap-1.5 rounded-lg px-2.5 text-cp-sm leading-none font-bold"
@@ -240,17 +248,14 @@ function providerLabel(provider: string) {
             </div>
           </div>
 
-          <dl
-            class="m-0 grid min-w-0 gap-5 sm:gap-7"
-            :class="profile.provider === 'xai' ? 'sm:grid-cols-[0.62fr_1.28fr_0.94fr]' : 'sm:grid-cols-[0.72fr_1.28fr]'"
-          >
+          <dl class="m-0 grid min-w-0 grid-cols-[repeat(auto-fit,minmax(min(100%,12rem),1fr))] gap-x-7 gap-y-5">
             <div v-if="profile.provider === 'xai'" class="min-w-0">
               <dt class="flex items-center gap-1.5 text-[10px] leading-none font-bold text-cp-text-quaternary">
                 <ShieldCheck class="size-3.25 text-cp-text-tertiary" />
                 认证协议
               </dt>
               <dd
-                class="mt-2 mb-0 truncate font-mono text-cp-lg leading-none font-bold tabular-nums text-cp-text"
+                class="mt-2 mb-0 font-mono text-cp-lg leading-snug font-bold wrap-anywhere tabular-nums text-cp-text"
                 :title="authProtocol"
               >
                 {{ authProtocol }}
@@ -263,7 +268,7 @@ function providerLabel(provider: string) {
                 {{ profile.provider === 'openai' ? '模拟运行环境' : '运行环境' }}
               </dt>
               <dd
-                class="mt-2 mb-0 truncate font-mono text-cp-lg leading-none font-bold tabular-nums text-cp-text"
+                class="mt-2 mb-0 font-mono text-cp-lg leading-snug font-bold wrap-anywhere tabular-nums text-cp-text"
                 :title="runtimeEnvironment.title"
               >
                 {{ runtimeEnvironment.primary }}
@@ -273,16 +278,16 @@ function providerLabel(provider: string) {
               </dd>
             </div>
 
-            <div class="min-w-0">
+            <div v-for="(attribute, index) in identityAttributes" :key="index" class="min-w-0">
               <dt class="flex items-center gap-1.5 text-[10px] leading-none font-bold text-cp-text-quaternary">
                 <Terminal class="size-3.25 text-cp-text-tertiary" />
-                客户端标识
+                {{ attribute.label }}
               </dt>
               <dd
-                class="mt-2 mb-0 truncate font-mono text-[16px] leading-none font-heavy tabular-nums text-cp-text"
-                :title="clientIdentity"
+                class="mt-2 mb-0 font-mono text-[16px] leading-snug font-heavy wrap-anywhere tabular-nums text-cp-text"
+                :title="attribute.value"
               >
-                {{ clientIdentity }}
+                {{ attribute.value }}
               </dd>
             </div>
           </dl>
diff --git a/frontend/src/views/groups/components/AccountGroupActions.vue b/frontend/src/views/groups/components/AccountGroupActions.vue
index 86b3e9174..74444911d 100644
--- a/frontend/src/views/groups/components/AccountGroupActions.vue
+++ b/frontend/src/views/groups/components/AccountGroupActions.vue
@@ -1,8 +1,8 @@
 <script setup lang="ts">
 import type { AccountGroup } from '@/api'
-import { Pencil, Power, Trash2 } from '@lucide/vue'
+import { BaseIconButton } from '@codex-proxy/ui'
 
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
+import { Pencil, Power, Trash2 } from '@lucide/vue'
 
 defineProps<{
   group: AccountGroup
diff --git a/frontend/src/views/groups/components/AccountGroupFilters.vue b/frontend/src/views/groups/components/AccountGroupFilters.vue
index c10ea424b..146328d13 100644
--- a/frontend/src/views/groups/components/AccountGroupFilters.vue
+++ b/frontend/src/views/groups/components/AccountGroupFilters.vue
@@ -1,9 +1,7 @@
 <script setup lang="ts">
-import { Plus, Search, Trash2 } from '@lucide/vue'
+import { BaseButton, BaseInput, BaseSelect } from '@codex-proxy/ui'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
+import { Plus, Search, Trash2 } from '@lucide/vue'
 import { accountGroupStatusOptions } from '../constants'
 
 defineProps<{
diff --git a/frontend/src/views/groups/components/AccountGroupFormModal.vue b/frontend/src/views/groups/components/AccountGroupFormModal.vue
index afec3a3ce..d85e42b40 100644
--- a/frontend/src/views/groups/components/AccountGroupFormModal.vue
+++ b/frontend/src/views/groups/components/AccountGroupFormModal.vue
@@ -1,16 +1,9 @@
 <script setup lang="ts">
 import type { AccountGroupFormValue } from '../composables/useAccountGroups'
 import type { AccountGroup } from '@/api'
-import { computed } from 'vue'
+import { BaseButton, BaseColorPicker, BaseForm, BaseFormItem, BaseInput, BaseModal, BaseSegmented, BaseTextarea } from '@codex-proxy/ui'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseColorPicker from '@/components/base/BaseColorPicker/index.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import BaseTextarea from '@/components/base/BaseTextarea.vue'
+import { computed } from 'vue'
 import { ACCOUNT_GROUP_COLOR_PRESETS } from '../constants'
 
 const props = defineProps<{
diff --git a/frontend/src/views/groups/composables/useAccountGroups.ts b/frontend/src/views/groups/composables/useAccountGroups.ts
index cb56d5fff..efd9749f7 100644
--- a/frontend/src/views/groups/composables/useAccountGroups.ts
+++ b/frontend/src/views/groups/composables/useAccountGroups.ts
@@ -1,7 +1,8 @@
 import type { AccountGroup, ApiKey } from '@/api'
+import { normalizeRgbaHexColor, toast } from '@codex-proxy/ui'
+
 import { watchDebounced } from '@vueuse/core'
 import { computed, onMounted, ref, shallowRef, watch } from 'vue'
-
 import {
   createAccountGroup,
   deleteAccountGroup,
@@ -11,12 +12,10 @@ import {
   getApiKeys,
   updateAccountGroup,
 } from '@/api'
-import { toast } from '@/components/base/BaseToast'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 import { useIdSet } from '@/composables/useIdSet'
 import { usePagedQuery } from '@/composables/usePagedQuery'
 import { errorMessage } from '@/utils/async'
-import { normalizeRgbaHexColor } from '@/utils/color'
 import { formatDateTime } from '@/utils/date'
 import { DEFAULT_ACCOUNT_GROUP_COLOR } from '../constants'
 
diff --git a/frontend/src/views/groups/constants.ts b/frontend/src/views/groups/constants.ts
index 24beb0c65..bb4160736 100644
--- a/frontend/src/views/groups/constants.ts
+++ b/frontend/src/views/groups/constants.ts
@@ -1,5 +1,5 @@
 import type { AccountGroup } from '@/api'
-import { defineTableColumns } from '@/components/base/BaseTable/columns'
+import { defineTableColumns } from '@codex-proxy/ui'
 
 export const DEFAULT_ACCOUNT_GROUP_COLOR = '#60A5FA80'
 
diff --git a/frontend/src/views/groups/index.vue b/frontend/src/views/groups/index.vue
index 581a96537..97e90265f 100644
--- a/frontend/src/views/groups/index.vue
+++ b/frontend/src/views/groups/index.vue
@@ -1,10 +1,5 @@
 <script setup lang="ts">
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseCheckbox from '@/components/base/BaseCheckbox.vue'
-import BaseConfirmModal from '@/components/base/BaseConfirmModal.vue'
-import BasePageHeader from '@/components/base/BasePageHeader.vue'
-import BaseTablePagination from '@/components/base/BaseTable/BaseTablePagination.vue'
-import BaseTable from '@/components/base/BaseTable/index.vue'
+import { BaseCard, BaseCheckbox, BaseConfirmModal, BasePageHeader, BaseTable, BaseTablePagination } from '@codex-proxy/ui'
 import { usePageSelection } from '@/composables/usePageSelection'
 import AccountGroupActions from './components/AccountGroupActions.vue'
 import AccountGroupFilters from './components/AccountGroupFilters.vue'
diff --git a/frontend/src/views/key-usage/components/KeyUsageBudget.vue b/frontend/src/views/key-usage/components/KeyUsageBudget.vue
index 8b72daa62..7fa938dd5 100644
--- a/frontend/src/views/key-usage/components/KeyUsageBudget.vue
+++ b/frontend/src/views/key-usage/components/KeyUsageBudget.vue
@@ -1,8 +1,8 @@
 <script setup lang="ts">
 import type { KeyUsageBudget } from '@/api/modules/key-usage'
+import { BaseCard } from '@codex-proxy/ui'
 import { Clock3, Gauge, Network } from '@lucide/vue'
 import { computed } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
 import { keyUsageTime, money } from '../utils/format'
 
 const props = defineProps<{ budget: KeyUsageBudget }>()
diff --git a/frontend/src/views/key-usage/components/KeyUsageHeader.vue b/frontend/src/views/key-usage/components/KeyUsageHeader.vue
index 84cbb9c23..45bb96c1a 100644
--- a/frontend/src/views/key-usage/components/KeyUsageHeader.vue
+++ b/frontend/src/views/key-usage/components/KeyUsageHeader.vue
@@ -1,11 +1,8 @@
 <script setup lang="ts">
+import { BaseButton, BaseIconButton, BasePageHeader, BaseSelect } from '@codex-proxy/ui'
 import { Info, KeyRound, LogOut, Moon, RefreshCw, Sun, Terminal } from '@lucide/vue'
 import { shallowRef } from 'vue'
 import { useRouter } from 'vue-router'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BasePageHeader from '@/components/base/BasePageHeader.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
 import { useAuthStore } from '@/stores/modules/auth'
 import { useThemeStore } from '@/stores/modules/theme'
 
diff --git a/frontend/src/views/key-usage/components/KeyUsageRecords.vue b/frontend/src/views/key-usage/components/KeyUsageRecords.vue
index 86f8bfba2..42a2c128e 100644
--- a/frontend/src/views/key-usage/components/KeyUsageRecords.vue
+++ b/frontend/src/views/key-usage/components/KeyUsageRecords.vue
@@ -1,12 +1,8 @@
 <script setup lang="ts">
+import type { BaseTablePaginationState as Pagination } from '@codex-proxy/ui'
 import type { KeyUsageRecord, KeyUsageRecordKind } from '@/api/modules/key-usage'
-import type { BaseTablePagination as Pagination } from '@/components/base/BaseTable/pagination'
+import { BaseCard, BaseSegmented, BaseTable, BaseTablePagination, defineTableColumns } from '@codex-proxy/ui'
 import { computed } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import BaseTablePagination from '@/components/base/BaseTable/BaseTablePagination.vue'
-import { defineTableColumns } from '@/components/base/BaseTable/columns'
-import BaseTable from '@/components/base/BaseTable/index.vue'
 import UsageBillingCell from '@/views/usage/components/UsageBillingCell.vue'
 import UsageClientIpCell from '@/views/usage/components/UsageClientIpCell.vue'
 import UsageLatencyCell from '@/views/usage/components/UsageLatencyCell.vue'
diff --git a/frontend/src/views/key-usage/components/KeyUsageSkeleton.vue b/frontend/src/views/key-usage/components/KeyUsageSkeleton.vue
index a489332f7..ebcef290c 100644
--- a/frontend/src/views/key-usage/components/KeyUsageSkeleton.vue
+++ b/frontend/src/views/key-usage/components/KeyUsageSkeleton.vue
@@ -1,7 +1,6 @@
 <script setup lang="ts">
+import { BaseCard, BaseSkeleton } from '@codex-proxy/ui'
 import { Gauge, Zap } from '@lucide/vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseSkeleton from '@/components/base/BaseSkeleton.vue'
 import { keyUsageTokenMetrics } from '../utils/metrics'
 
 const metrics = [
diff --git a/frontend/src/views/key-usage/components/KeyUsageSummary.vue b/frontend/src/views/key-usage/components/KeyUsageSummary.vue
index 818d41050..78cea94a8 100644
--- a/frontend/src/views/key-usage/components/KeyUsageSummary.vue
+++ b/frontend/src/views/key-usage/components/KeyUsageSummary.vue
@@ -1,9 +1,8 @@
 <script setup lang="ts">
 import type { KeyUsageMetrics } from '@/api/modules/key-usage'
+import { BaseCard, BaseMotionIcon } from '@codex-proxy/ui'
 import { Gauge, Zap } from '@lucide/vue'
 import { computed } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseMotionIcon from '@/components/base/BaseMotionIcon.vue'
 import { formatCompactNumber, formatInteger } from '@/utils/number'
 import AnimatedMetricValue from '@/views/dashboard/components/AnimatedMetricValue.vue'
 import { money } from '../utils/format'
diff --git a/frontend/src/views/key-usage/components/KeyUsageTrend.vue b/frontend/src/views/key-usage/components/KeyUsageTrend.vue
index 7d93245b3..e00850919 100644
--- a/frontend/src/views/key-usage/components/KeyUsageTrend.vue
+++ b/frontend/src/views/key-usage/components/KeyUsageTrend.vue
@@ -1,9 +1,8 @@
 <script setup lang="ts">
 import type { EChartsOption, LineSeriesOption } from 'echarts'
 import type { KeyUsageTrendPoint } from '@/api/modules/key-usage'
+import { BaseCard, BaseEmpty } from '@codex-proxy/ui'
 import { computed } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
 import BaseChart from '@/components/charts/BaseChart.vue'
 import { chartTooltipStyle } from '@/components/charts/tooltip'
 import { useChartPalette } from '@/composables/useChartPalette'
diff --git a/frontend/src/views/key-usage/index.vue b/frontend/src/views/key-usage/index.vue
index c2e08eac4..3a259f6a2 100644
--- a/frontend/src/views/key-usage/index.vue
+++ b/frontend/src/views/key-usage/index.vue
@@ -1,12 +1,11 @@
 <script setup lang="ts">
 import type { KeyUsageVersion } from '@/api/modules/key-usage'
+import { BaseInput, BaseScrollbar } from '@codex-proxy/ui'
 import { Search } from '@lucide/vue'
 import { shallowRef } from 'vue'
 import { getKeyUsageVersion } from '@/api/modules/key-usage'
 import ApiKeyConfigModal from '@/components/ApiKeyConfigModal.vue'
 import AppAboutModal from '@/components/AppAboutModal.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
 import RequestHealthTimelineCard from '@/views/dashboard/components/RequestHealthTimelineCard.vue'
 import KeyUsageBudget from './components/KeyUsageBudget.vue'
 import KeyUsageHeader from './components/KeyUsageHeader.vue'
diff --git a/frontend/src/views/keys/components/ApiKeyActions.vue b/frontend/src/views/keys/components/ApiKeyActions.vue
index 78b75619b..f3cc3dcba 100644
--- a/frontend/src/views/keys/components/ApiKeyActions.vue
+++ b/frontend/src/views/keys/components/ApiKeyActions.vue
@@ -1,10 +1,8 @@
 <script setup lang="ts">
 import type { getApiKeys } from '@/api'
-import { MoreHorizontal, Pencil, Power, RotateCcw, Terminal, Trash2, Upload } from '@lucide/vue'
+import { BaseIconButton, BaseMenuItem, BasePopover } from '@codex-proxy/ui'
 
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseMenuItem from '@/components/base/BaseMenuItem.vue'
-import BasePopover from '@/components/base/BasePopover.vue'
+import { MoreHorizontal, Pencil, Power, RotateCcw, Terminal, Trash2, Upload } from '@lucide/vue'
 
 type ApiKeyRow = Awaited<ReturnType<typeof getApiKeys>>['items'][number]
 
diff --git a/frontend/src/views/keys/components/ApiKeyBudgetCell.vue b/frontend/src/views/keys/components/ApiKeyBudgetCell.vue
index bea10395e..c4098310e 100644
--- a/frontend/src/views/keys/components/ApiKeyBudgetCell.vue
+++ b/frontend/src/views/keys/components/ApiKeyBudgetCell.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import type { ApiKey } from '@/api'
+import { BasePopover } from '@codex-proxy/ui'
 import { computed } from 'vue'
-import BasePopover from '@/components/base/BasePopover.vue'
 import { formatDateTime } from '@/utils/date'
 
 const props = defineProps<{ apiKey: ApiKey }>()
diff --git a/frontend/src/views/keys/components/ApiKeyBudgetResetModal.vue b/frontend/src/views/keys/components/ApiKeyBudgetResetModal.vue
index 101f6094c..4765c1710 100644
--- a/frontend/src/views/keys/components/ApiKeyBudgetResetModal.vue
+++ b/frontend/src/views/keys/components/ApiKeyBudgetResetModal.vue
@@ -1,12 +1,9 @@
 <script setup lang="ts">
 import type { ApiKey } from '@/api'
+import { BaseButton, BaseModal, BaseSegmented, toast } from '@codex-proxy/ui'
 import { ArrowRight } from '@lucide/vue'
 import { computed, shallowRef, watch } from 'vue'
 import { resetApiKeyBudget } from '@/api'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import { toast } from '@/components/base/BaseToast'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 
 const props = defineProps<{ apiKey: ApiKey | null }>()
diff --git a/frontend/src/views/keys/components/ApiKeyCreateModal.vue b/frontend/src/views/keys/components/ApiKeyCreateModal.vue
index 9d47fcfa2..14381c210 100644
--- a/frontend/src/views/keys/components/ApiKeyCreateModal.vue
+++ b/frontend/src/views/keys/components/ApiKeyCreateModal.vue
@@ -1,21 +1,12 @@
 <script setup lang="ts">
 import type { ApiKeyFormValue } from '../composables/useApiKeyMutations'
 import type { AccountGroup } from '@/api'
-import { Openai, Xai } from '@boxicons/vue'
-import { Copy, DollarSign, KeyRound, Upload } from '@lucide/vue'
-import { computed, shallowRef } from 'vue'
+import { BaseButton, BaseForm, BaseFormItem, BaseIconButton, BaseInput, BaseModal } from '@codex-proxy/ui'
 
+import { Copy, DollarSign, KeyRound, Upload } from '@lucide/vue'
+import { computed } from 'vue'
 import AccountGroupCheckboxGrid from '@/components/AccountGroupCheckboxGrid.vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import ClientProfileEditor from '@/components/client-profile/ClientProfileEditor.vue'
-import XaiClientProfileEditor from '@/components/client-profile/XaiClientProfileEditor.vue'
-import { PROVIDER_DISPLAY_NAMES } from '@/utils/providers'
+import ProviderRequestProfilesEditor from '@/components/client-profile/ProviderRequestProfilesEditor.vue'
 
 const props = defineProps<{
   groups: AccountGroup[]
@@ -33,11 +24,6 @@ const open = defineModel<boolean>({ default: false })
 const createdOpen = defineModel<boolean>('createdOpen', { default: false })
 const form = defineModel<ApiKeyFormValue>('form', { required: true })
 const title = computed(() => props.editing ? '编辑密钥' : '创建 API Key')
-const profileProvider = shallowRef('openai')
-const profileProviderOptions = [
-  { label: PROVIDER_DISPLAY_NAMES.openai, value: 'openai', icon: Openai },
-  { label: PROVIDER_DISPLAY_NAMES.xai, value: 'xai', icon: Xai },
-]
 </script>
 
 <template>
@@ -97,44 +83,13 @@ const profileProviderOptions = [
       </BaseFormItem>
 
       <BaseFormItem label="上游身份">
-        <ClientProfileEditor
+        <ProviderRequestProfilesEditor
           v-if="open"
-          v-show="profileProvider === 'openai'"
-          v-model="form.openaiClientProfileOverride"
+          v-model="form.providerRequestProfileOverrides"
           allow-inherit
-          :active="profileProvider === 'openai'"
+          :active="open"
           :disabled="saving"
-        >
-          <template #source-extra>
-            <BaseSegmented
-              v-model="profileProvider"
-              label="上游身份平台"
-              class="w-20 shrink-0"
-              display="icon"
-              :options="profileProviderOptions"
-              :disabled="saving"
-            />
-          </template>
-        </ClientProfileEditor>
-        <XaiClientProfileEditor
-          v-if="open"
-          v-show="profileProvider === 'xai'"
-          v-model="form.xaiClientProfileOverride"
-          allow-inherit
-          :active="profileProvider === 'xai'"
-          :disabled="saving"
-        >
-          <template #source-extra>
-            <BaseSegmented
-              v-model="profileProvider"
-              label="上游身份平台"
-              class="w-20 shrink-0"
-              display="icon"
-              :options="profileProviderOptions"
-              :disabled="saving"
-            />
-          </template>
-        </XaiClientProfileEditor>
+        />
       </BaseFormItem>
 
       <div class="grid gap-6 sm:grid-cols-2">
diff --git a/frontend/src/views/keys/components/ApiKeyFilters.vue b/frontend/src/views/keys/components/ApiKeyFilters.vue
index 43c677170..398b2eeef 100644
--- a/frontend/src/views/keys/components/ApiKeyFilters.vue
+++ b/frontend/src/views/keys/components/ApiKeyFilters.vue
@@ -1,8 +1,7 @@
 <script setup lang="ts">
-import { Plus, Search, Trash2 } from '@lucide/vue'
+import { BaseButton, BaseInput } from '@codex-proxy/ui'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
+import { Plus, Search, Trash2 } from '@lucide/vue'
 
 defineProps<{
   batchDeleting: boolean
diff --git a/frontend/src/views/keys/components/ApiKeyPrefixCell.vue b/frontend/src/views/keys/components/ApiKeyPrefixCell.vue
index 1ec35a603..3ba7acca8 100644
--- a/frontend/src/views/keys/components/ApiKeyPrefixCell.vue
+++ b/frontend/src/views/keys/components/ApiKeyPrefixCell.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
-import { Copy } from '@lucide/vue'
+import { BaseIconButton } from '@codex-proxy/ui'
 
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
+import { Copy } from '@lucide/vue'
 
 defineProps<{
   prefix: string
diff --git a/frontend/src/views/keys/composables/useApiKeyMutations.ts b/frontend/src/views/keys/composables/useApiKeyMutations.ts
index 40c5fadfc..363fb8ac7 100644
--- a/frontend/src/views/keys/composables/useApiKeyMutations.ts
+++ b/frontend/src/views/keys/composables/useApiKeyMutations.ts
@@ -1,6 +1,7 @@
 import type { Ref } from 'vue'
 import type { getApiKeys } from '@/api'
-import type { ClientProfileSelection, XaiClientProfileSelection } from '@/api/modules/client-profiles'
+import type { ProviderRequestProfile, ProviderRequestProfiles } from '@/api/modules/client-profiles'
+import { toast } from '@codex-proxy/ui'
 import { ref, shallowRef, watch } from 'vue'
 import {
   createApiKey,
@@ -10,7 +11,6 @@ import {
   revealApiKey,
   updateApiKey,
 } from '@/api'
-import { toast } from '@/components/base/BaseToast'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 import { useCopyText } from '@/composables/useCopyText'
 import { useIdSet } from '@/composables/useIdSet'
@@ -18,8 +18,7 @@ import { useIdSet } from '@/composables/useIdSet'
 type ApiKeyRow = Awaited<ReturnType<typeof getApiKeys>>['items'][number]
 
 export interface ApiKeyFormValue {
-  openaiClientProfileOverride: ClientProfileSelection | null
-  xaiClientProfileOverride: XaiClientProfileSelection | null
+  providerRequestProfileOverrides: ProviderRequestProfiles
   customKey: string
   name: string
   label: string
@@ -65,8 +64,7 @@ export function useApiKeyMutations(options: {
   function openEdit(key: ApiKeyRow) {
     editingKey.value = key
     form.value = {
-      openaiClientProfileOverride: key.openaiClientProfileOverride ? { ...key.openaiClientProfileOverride } : null,
-      xaiClientProfileOverride: key.xaiClientProfileOverride ? { ...key.xaiClientProfileOverride } : null,
+      providerRequestProfileOverrides: cloneProfiles(key.providerRequestProfileOverrides),
       customKey: '',
       name: key.name,
       label: key.label ?? '',
@@ -101,8 +99,6 @@ export function useApiKeyMutations(options: {
     await savingKeyAction.run(
       async () => {
         const payload = {
-          openaiClientProfileOverride: form.value.openaiClientProfileOverride,
-          xaiClientProfileOverride: form.value.xaiClientProfileOverride,
           name: form.value.name.trim(),
           label: form.value.label.trim() || null,
           groupIds: [...new Set(form.value.groupIds)],
@@ -113,11 +109,19 @@ export function useApiKeyMutations(options: {
         }
         const current = editingKey.value
         if (current) {
-          await updateApiKey({ id: current.id, ...payload })
+          await updateApiKey({
+            id: current.id,
+            ...payload,
+            providerRequestProfileOverrides: profileOverrideUpdates(
+              current.providerRequestProfileOverrides,
+              form.value.providerRequestProfileOverrides,
+            ),
+          })
         }
         else {
           const result = await createApiKey({
             ...payload,
+            providerRequestProfileOverrides: cloneProfiles(form.value.providerRequestProfileOverrides),
             customKey: form.value.customKey || undefined,
           })
           createdKey.value = result.plaintextKey
@@ -301,8 +305,7 @@ export function useApiKeyMutations(options: {
 
 function emptyForm(): ApiKeyFormValue {
   return {
-    openaiClientProfileOverride: null,
-    xaiClientProfileOverride: null,
+    providerRequestProfileOverrides: {},
     customKey: '',
     name: '',
     label: '',
@@ -314,6 +317,22 @@ function emptyForm(): ApiKeyFormValue {
   }
 }
 
+function cloneProfiles(value: ProviderRequestProfiles): ProviderRequestProfiles {
+  return JSON.parse(JSON.stringify(value)) as ProviderRequestProfiles
+}
+
+function profileOverrideUpdates(
+  previous: ProviderRequestProfiles,
+  current: ProviderRequestProfiles,
+): Record<string, ProviderRequestProfile | null> {
+  const updates: Record<string, ProviderRequestProfile | null> = cloneProfiles(current)
+  for (const provider of Object.keys(previous)) {
+    if (!Object.hasOwn(current, provider))
+      updates[provider] = null
+  }
+  return updates
+}
+
 function limitInputValue(limit: string | number) {
   return Number(limit) === 0 ? '' : String(limit)
 }
diff --git a/frontend/src/views/keys/composables/useApiKeysQuery.ts b/frontend/src/views/keys/composables/useApiKeysQuery.ts
index 08b7e8366..8c602a81d 100644
--- a/frontend/src/views/keys/composables/useApiKeysQuery.ts
+++ b/frontend/src/views/keys/composables/useApiKeysQuery.ts
@@ -1,4 +1,4 @@
-import type { BaseTableSort } from '@/components/base/BaseTable/columns'
+import type { BaseTableSort } from '@codex-proxy/ui'
 import { watchDebounced } from '@vueuse/core'
 
 import { computed, onMounted, shallowRef } from 'vue'
diff --git a/frontend/src/views/keys/constants.ts b/frontend/src/views/keys/constants.ts
index 626750084..00cf9373f 100644
--- a/frontend/src/views/keys/constants.ts
+++ b/frontend/src/views/keys/constants.ts
@@ -1,5 +1,5 @@
 import type { getApiKeys } from '@/api'
-import { defineTableColumns } from '@/components/base/BaseTable/columns'
+import { defineTableColumns } from '@codex-proxy/ui'
 
 type ApiKeyRow = Awaited<ReturnType<typeof getApiKeys>>['items'][number] & {
   createdAtDisplay: string
diff --git a/frontend/src/views/keys/index.vue b/frontend/src/views/keys/index.vue
index 2f4c69ac2..18c6c6300 100644
--- a/frontend/src/views/keys/index.vue
+++ b/frontend/src/views/keys/index.vue
@@ -1,14 +1,9 @@
 <script setup lang="ts">
 import type { ApiKey } from '@/api'
-import { ref, shallowRef, watch } from 'vue'
+import { BaseCard, BaseCheckbox, BaseConfirmModal, BasePageHeader, BaseTable, BaseTablePagination } from '@codex-proxy/ui'
 
+import { ref, shallowRef, watch } from 'vue'
 import ApiKeyConfigModal from '@/components/ApiKeyConfigModal.vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseCheckbox from '@/components/base/BaseCheckbox.vue'
-import BaseConfirmModal from '@/components/base/BaseConfirmModal.vue'
-import BasePageHeader from '@/components/base/BasePageHeader.vue'
-import BaseTablePagination from '@/components/base/BaseTable/BaseTablePagination.vue'
-import BaseTable from '@/components/base/BaseTable/index.vue'
 import LastUsedAtCell from '@/components/LastUsedAtCell.vue'
 import { useAccountGroupCatalog } from '@/composables/useAccountGroupCatalog'
 import { usePageSelection } from '@/composables/usePageSelection'
diff --git a/frontend/src/views/login/components/LoginPanel.vue b/frontend/src/views/login/components/LoginPanel.vue
index 5a1d05deb..165998828 100644
--- a/frontend/src/views/login/components/LoginPanel.vue
+++ b/frontend/src/views/login/components/LoginPanel.vue
@@ -1,14 +1,9 @@
 <script setup lang="ts">
+import { BaseButton, BaseCard, BaseIconButton, BaseInput, BaseMotionIcon, BaseSegmented } from '@codex-proxy/ui'
+
 import { Eye, EyeOff, KeyRound, Mail, ShieldCheck } from '@lucide/vue'
 import { computed, shallowRef, watch } from 'vue'
-
 import AppBrandMark from '@/components/AppBrandMark.vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseMotionIcon from '@/components/base/BaseMotionIcon.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
 
 type LoginRealm = 'admin' | 'key'
 type SecretInputType = 'password' | 'text'
diff --git a/frontend/src/views/plugins/components/PluginBindingEditor.vue b/frontend/src/views/plugins/components/PluginBindingEditor.vue
new file mode 100644
index 000000000..7c4dc9688
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginBindingEditor.vue
@@ -0,0 +1,116 @@
+<script setup lang="ts">
+import type { PluginArtifactMetadata, PluginCapabilityBinding } from '@/api'
+import { BaseCheckbox, BaseFormItem, BaseNumberInput, BaseSelect, BaseSwitch } from '@codex-proxy/ui'
+import { computed, ref, watch } from 'vue'
+import { pluginCapabilityLabel } from '../utils/model'
+import PluginHelpPopover from './PluginHelpPopover.vue'
+import PluginResourcePicker from './PluginResourcePicker.vue'
+import PluginScopeInput from './PluginScopeInput.vue'
+
+const props = defineProps<{ metadata: PluginArtifactMetadata, disabled?: boolean }>()
+const emit = defineEmits<{ validityChange: [valid: boolean] }>()
+const bindings = defineModel<PluginCapabilityBinding[]>({ required: true })
+const stages: Record<string, string[]> = {
+  middleware: ['request', 'attempt'],
+  model_router: ['routing'],
+  scheduler: ['scheduling'],
+  request_lifecycle: ['observation'],
+  usage: ['observation'],
+  web_socket_observer: ['observation'],
+}
+const stageLabels: Record<string, string> = { request: '请求开始', attempt: '每次尝试', routing: '模型路由', scheduling: '账号调度', observation: '请求结束' }
+const entries = computed(() => Object.entries(props.metadata.contributes).flatMap(([capability, contribution]) =>
+  contribution.stages.filter(stage => stages[capability]?.includes(stage))
+    .map(stage => ({ capability, contribution: contribution.id, stage, key: `${contribution.id}:${stage}` })),
+))
+function keyOf(binding: PluginCapabilityBinding) {
+  return `${binding.contribution}:${binding.stage}`
+}
+function hasScope(binding: PluginCapabilityBinding) {
+  return Boolean(binding.clientKeyIds.length || binding.accountGroupIds.length || binding.models.length || binding.providerIds.length)
+}
+const globalScopes = ref(new Set(bindings.value.filter(binding => !hasScope(binding)).map(keyOf)))
+type RequestScope = Pick<PluginCapabilityBinding, 'clientKeyIds' | 'accountGroupIds' | 'models' | 'providerIds'>
+const scopeDrafts = new Map<string, RequestScope>()
+function bindingFor(key: string) {
+  return bindings.value.find(binding => keyOf(binding) === key)
+}
+function patch(key: string, value: Partial<PluginCapabilityBinding>) {
+  bindings.value = bindings.value.map(binding => keyOf(binding) === key ? { ...binding, ...value } : binding)
+}
+function toggle(entry: typeof entries.value[number], enabled: boolean) {
+  globalScopes.value.delete(entry.key)
+  scopeDrafts.delete(entry.key)
+  bindings.value = bindings.value.filter(binding => keyOf(binding) !== entry.key)
+  if (enabled) {
+    const order = entry.stage === 'observation' ? bindings.value.find(binding => binding.stage === 'observation')?.order ?? 0 : 0
+    bindings.value = [...bindings.value, { contribution: entry.contribution, stage: entry.stage, order, failurePolicy: entry.stage === 'observation' ? 'observe' : 'reject', providerIds: [], models: [], clientKeyIds: [], accountGroupIds: [], identityBindings: [] }]
+  }
+}
+function setGlobal(key: string, value: boolean) {
+  if (value) {
+    const binding = bindingFor(key)
+    if (binding && !globalScopes.value.has(key)) {
+      const { clientKeyIds, accountGroupIds, models, providerIds } = binding
+      scopeDrafts.set(key, { clientKeyIds, accountGroupIds, models, providerIds })
+    }
+    globalScopes.value.add(key)
+    patch(key, { clientKeyIds: [], accountGroupIds: [], models: [], providerIds: [] })
+  }
+  else {
+    globalScopes.value.delete(key)
+    const draft = scopeDrafts.get(key)
+    if (draft)
+      patch(key, draft)
+  }
+}
+const valid = computed(() => entries.value.every((entry) => {
+  const binding = bindingFor(entry.key)
+  return !binding || globalScopes.value.has(entry.key) || hasScope(binding)
+}))
+watch(valid, value => emit('validityChange', value), { immediate: true })
+</script>
+
+<template>
+  <div class="grid gap-4">
+    <article v-for="entry in entries" :key="entry.key" class="grid gap-4 rounded-cp bg-cp-fill-alter p-4">
+      <div class="flex items-center gap-2">
+        <BaseSwitch :model-value="Boolean(bindingFor(entry.key))" :label="`${pluginCapabilityLabel(entry.capability)} · ${stageLabels[entry.stage]}`" show-label :disabled="disabled" @update:model-value="toggle(entry, $event)" />
+        <PluginHelpPopover v-if="entry.stage === 'observation'" label="请求观察说明">
+          仅观察请求，不改变请求结果
+        </PluginHelpPopover>
+      </div>
+      <template v-if="bindingFor(entry.key)">
+        <div class="flex items-center gap-2">
+          <BaseCheckbox :model-value="globalScopes.has(entry.key)" label="应用于所有请求" show-label :disabled="disabled" @update:model-value="setGlobal(entry.key, $event)" />
+          <PluginHelpPopover label="生效请求范围说明">
+            关闭后至少选择一项范围，不同条件同时满足才生效，同一条件内任意一项匹配即可
+          </PluginHelpPopover>
+        </div>
+        <div v-if="!globalScopes.has(entry.key)" class="grid gap-4 sm:grid-cols-2">
+          <BaseFormItem label="客户端 Key">
+            <PluginResourcePicker :model-value="bindingFor(entry.key)!.clientKeyIds" kind="keys" :disabled="disabled" @update:model-value="patch(entry.key, { clientKeyIds: $event })" />
+          </BaseFormItem>
+          <BaseFormItem label="账号分组">
+            <PluginResourcePicker :model-value="bindingFor(entry.key)!.accountGroupIds" kind="groups" :disabled="disabled" @update:model-value="patch(entry.key, { accountGroupIds: $event })" />
+          </BaseFormItem>
+          <PluginScopeInput :model-value="bindingFor(entry.key)!.models" label="模型范围" placeholder="每行一个模型名称，精确匹配" :class="['routing', 'request'].includes(entry.stage) ? 'sm:col-span-2' : undefined" :disabled="disabled" @update:model-value="patch(entry.key, { models: $event })" />
+          <PluginScopeInput v-if="!['routing', 'request'].includes(entry.stage)" :model-value="bindingFor(entry.key)!.providerIds" label="Provider 范围" placeholder="每行一个 Provider 标识" :disabled="disabled" @update:model-value="patch(entry.key, { providerIds: $event })" />
+        </div>
+        <div v-if="entry.stage !== 'observation'" class="grid items-end gap-4 sm:grid-cols-2">
+          <BaseFormItem label="执行顺序">
+            <template #label-extra>
+              <PluginHelpPopover label="执行顺序说明">
+                数值较小的先执行
+              </PluginHelpPopover>
+            </template>
+            <BaseNumberInput :model-value="bindingFor(entry.key)!.order" label="执行顺序" size="md" :min="-2147483648" :max="2147483647" :disabled="disabled" class="w-full" @update:model-value="patch(entry.key, { order: $event })" />
+          </BaseFormItem>
+          <BaseFormItem label="插件失败时">
+            <BaseSelect :model-value="bindingFor(entry.key)!.failurePolicy" :options="[{ label: '拒绝请求', value: 'reject' }, { label: '交给后续处理', value: 'delegate' }]" :disabled="disabled" class="w-full" @update:model-value="patch(entry.key, { failurePolicy: $event as 'reject' | 'delegate' })" />
+          </BaseFormItem>
+        </div>
+      </template>
+    </article>
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginCapabilityTags.vue b/frontend/src/views/plugins/components/PluginCapabilityTags.vue
new file mode 100644
index 000000000..072195e27
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginCapabilityTags.vue
@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import type { PluginArtifactMetadata } from '@/api'
+import { BasePopover, BaseTag } from '@codex-proxy/ui'
+import { computed, shallowRef, useId } from 'vue'
+import { pluginCapabilityLabel, pluginContributionEntries } from '../utils/model'
+
+const props = withDefaults(defineProps<{
+  metadata: PluginArtifactMetadata
+  primary?: boolean
+}>(), { primary: false })
+
+const open = shallowRef(false)
+const contentId = useId()
+const entries = computed(() => pluginContributionEntries(props.metadata))
+const visible = computed(() => entries.value.slice(0, 2))
+const hidden = computed(() => entries.value.slice(2))
+</script>
+
+<template>
+  <div class="flex min-w-0 items-center gap-1 whitespace-nowrap">
+    <BaseTag v-for="[capability, contribution] in visible" :key="capability" size="sm" :type="primary ? 'primary' : 'neutral'" class="min-w-0">
+      <span class="block truncate" :title="`${pluginCapabilityLabel(capability)} · ${contribution.id}`">{{ pluginCapabilityLabel(capability) }}</span>
+    </BaseTag>
+    <BasePopover v-if="hidden.length" v-model="open" trigger="hover-click" placement="top" class="shrink-0">
+      <template #trigger>
+        <button
+          type="button"
+          class="cursor-pointer rounded-cp border-0 bg-transparent p-0 outline-none focus-visible:ring-2 focus-visible:ring-cp-control-outline"
+          :aria-label="`另有 ${hidden.length} 项声明能力`"
+          :aria-expanded="open"
+          :aria-describedby="open ? contentId : undefined"
+        >
+          <BaseTag size="sm" :type="primary ? 'primary' : 'neutral'">
+            +{{ hidden.length }}
+          </BaseTag>
+        </button>
+      </template>
+      <div :id="contentId" role="tooltip" class="flex max-w-72 flex-wrap gap-1.5 p-3">
+        <BaseTag v-for="[capability, contribution] in hidden" :key="capability" size="sm" :type="primary ? 'primary' : 'neutral'">
+          <span :title="contribution.id">{{ pluginCapabilityLabel(capability) }}</span>
+        </BaseTag>
+      </div>
+    </BasePopover>
+    <span v-if="!entries.length" class="text-cp-text-quaternary">无</span>
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginCatalogPanel.vue b/frontend/src/views/plugins/components/PluginCatalogPanel.vue
new file mode 100644
index 000000000..03f5e59ac
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginCatalogPanel.vue
@@ -0,0 +1,139 @@
+<script setup lang="ts">
+import type { InstalledPlugin } from '../utils/catalog'
+import { BaseButton, BaseCard, BaseEmpty, BaseIconButton, BaseInput, BaseScrollbar, BaseSegmented, BaseSelect, BaseTable, BaseTablePagination, BaseTag, defineTableColumns } from '@codex-proxy/ui'
+import { CircleAlert, LayoutGrid, List, Puzzle, Search, Settings2 } from '@lucide/vue'
+import { computed, shallowRef, watch } from 'vue'
+import { currentPluginInstance, PLUGIN_STATUS_LABELS, pluginStatus, pluginStatusType } from '../utils/catalog'
+import PluginCapabilityTags from './PluginCapabilityTags.vue'
+import PluginIcon from './PluginIcon.vue'
+
+const props = defineProps<{ plugins: InstalledPlugin[], loading: boolean }>()
+defineEmits<{ manage: [plugin: InstalledPlugin] }>()
+const search = shallowRef('')
+const status = shallowRef('all')
+const display = shallowRef('cards')
+const page = shallowRef(1)
+const pageSize = shallowRef(20)
+const statusOptions = [{ label: '全部状态', value: 'all' }, ...Object.entries(PLUGIN_STATUS_LABELS).map(([value, label]) => ({ value, label }))]
+const displayOptions = [{ label: '卡片视图', value: 'cards', icon: LayoutGrid }, { label: '列表视图', value: 'list', icon: List }]
+const filtered = computed(() => props.plugins.filter((plugin) => {
+  const metadata = plugin.artifact.metadata
+  return (status.value === 'all' || pluginStatus(plugin) === status.value)
+    && [metadata.displayName, metadata.pluginId, metadata.publisher, metadata.description].some(value => value.toLocaleLowerCase().includes(search.value.trim().toLocaleLowerCase()))
+}))
+const rows = computed(() => filtered.value
+  .slice((page.value - 1) * pageSize.value, page.value * pageSize.value)
+  .map((plugin) => {
+    const current = currentPluginInstance(plugin)
+    const version = plugin.artifacts.find(artifact => artifact.metadata.sha256 === current?.artifactSha256)?.metadata.version ?? plugin.artifact.metadata.version
+    return {
+      ...plugin,
+      versionLabel: version,
+      versionTitle: `${current ? '当前版本' : '已安装版本'}：${version}`,
+    }
+  }))
+const pagination = computed(() => ({ currentPage: page.value, pageSize: pageSize.value, total: filtered.value.length }))
+watch([search, status, pageSize], () => {
+  page.value = 1
+})
+watch(() => filtered.value.length, (total) => {
+  page.value = Math.min(page.value, Math.max(1, Math.ceil(total / pageSize.value)))
+})
+const columns = defineTableColumns<(typeof rows.value)[number]>([
+  { key: 'plugin', label: '插件', kind: 'identity', size: '3xl' },
+  { key: 'status', label: '状态', kind: 'custom', size: 'lg' },
+  { key: 'capabilities', label: '提供功能', kind: 'custom', size: 'xl' },
+  { key: 'configurations', label: '已安装版本', kind: 'custom', size: 'lg' },
+  { key: 'actions', label: '操作', kind: 'actions', size: 'sm' },
+])
+</script>
+
+<template>
+  <div class="flex h-full min-h-0 flex-col gap-2">
+    <div class="flex shrink-0 flex-wrap items-center gap-3 p-1">
+      <BaseInput v-model="search" aria-label="搜索已安装插件" placeholder="搜索插件、发布者" class="min-w-0 flex-1 basis-full sm:max-w-72 sm:basis-auto">
+        <template #prefix>
+          <Search class="size-4" />
+        </template>
+      </BaseInput>
+      <BaseSelect v-model="status" :options="statusOptions" aria-label="插件状态" class="w-36" />
+      <BaseSegmented v-model="display" :options="displayOptions" label="插件显示方式" display="icon" class="ml-auto w-20 shrink-0" />
+    </div>
+    <div v-if="loading && !plugins.length" class="min-h-0 flex-1" aria-busy="true" />
+    <BaseEmpty v-else-if="!filtered.length" :icon="Puzzle" :title="plugins.length ? '没有匹配的插件' : '安装第一个插件'" :description="plugins.length ? '试试其他名称或状态' : '从上方安装插件，查看权限后即可开始使用'" surface="none" class="flex-1 content-center">
+      <template v-if="plugins.length" #action>
+        <BaseButton variant="secondary" @click="search = ''; status = 'all'">
+          清除筛选
+        </BaseButton>
+      </template>
+    </BaseEmpty>
+    <BaseScrollbar v-else-if="display === 'cards'" class="min-h-0 flex-1" :aria-busy="loading">
+      <ul class="m-0 grid list-none grid-cols-[repeat(auto-fill,minmax(min(100%,30rem),1fr))] items-start gap-4 p-1" aria-label="已安装插件">
+        <li v-for="plugin in rows" :key="plugin.id">
+          <BaseCard padding="compact">
+            <div class="flex min-w-0 items-start gap-3">
+              <PluginIcon :artifact="plugin.artifact" class="size-10 shrink-0 rounded-cp" />
+              <div class="grid min-w-0 flex-1 gap-1">
+                <div class="flex min-w-0 items-center gap-2">
+                  <strong class="truncate text-cp-sm">{{ plugin.artifact.metadata.displayName }}</strong>
+                  <BaseTag size="sm" class="shrink-0" :title="plugin.versionTitle" :aria-label="plugin.versionTitle">
+                    <span class="block max-w-28 truncate">{{ plugin.versionLabel }}</span>
+                  </BaseTag>
+                </div>
+                <span class="truncate text-cp-xs text-cp-text-secondary">{{ plugin.artifact.metadata.publisher }}</span>
+              </div>
+              <BaseTag :type="pluginStatusType(pluginStatus(plugin))" size="sm">
+                <CircleAlert v-if="pluginStatus(plugin) === 'failed'" class="mr-1 size-3.5" />
+                {{ PLUGIN_STATUS_LABELS[pluginStatus(plugin)] }}
+              </BaseTag>
+            </div>
+            <p class="my-4 line-clamp-2 min-h-10 text-cp-sm leading-relaxed text-cp-text-secondary">
+              {{ plugin.artifact.metadata.description || '发布者未提供说明' }}
+            </p>
+            <PluginCapabilityTags :metadata="plugin.artifact.metadata" />
+            <div class="mt-5 flex flex-wrap items-center justify-between gap-3">
+              <span class="text-cp-xs text-cp-text-secondary">{{ plugin.artifacts.length }} 个版本</span>
+              <BaseIconButton class="ml-auto" :label="`管理 ${plugin.artifact.metadata.displayName}`" variant="secondary" size="sm" @click="$emit('manage', plugin)">
+                <Settings2 class="size-4" />
+              </BaseIconButton>
+            </div>
+          </BaseCard>
+        </li>
+      </ul>
+    </BaseScrollbar>
+    <BaseTable v-else class="min-h-0 flex-1" :columns="columns" :rows="rows" :row-key="row => row.id" :aria-busy="loading">
+      <template #plugin="{ row }">
+        <div class="flex min-w-0 items-center gap-3">
+          <PluginIcon :artifact="row.artifact" class="size-9 rounded-cp" />
+          <div class="grid min-w-0 gap-1">
+            <div class="flex min-w-0 items-center gap-2">
+              <strong class="truncate">{{ row.artifact.metadata.displayName }}</strong>
+              <BaseTag size="sm" class="shrink-0" :title="row.versionTitle" :aria-label="row.versionTitle">
+                <span class="block max-w-28 truncate">{{ row.versionLabel }}</span>
+              </BaseTag>
+            </div>
+            <span class="truncate text-cp-xs text-cp-text-secondary">{{ row.artifact.metadata.publisher }}</span>
+          </div>
+        </div>
+      </template>
+      <template #status="{ row }">
+        <BaseTag :type="pluginStatusType(pluginStatus(row))">
+          <CircleAlert v-if="pluginStatus(row) === 'failed'" class="mr-1 size-3.5" />
+          {{ PLUGIN_STATUS_LABELS[pluginStatus(row)] }}
+        </BaseTag>
+      </template>
+      <template #capabilities="{ row }">
+        <PluginCapabilityTags :metadata="row.artifact.metadata" />
+      </template>
+      <template #configurations="{ row }">
+        {{ row.artifacts.length }} 个版本
+      </template>
+      <template #actions="{ row }">
+        <BaseIconButton size="sm" variant="secondary" :label="`管理 ${row.artifact.metadata.displayName}`" @click="$emit('manage', row)">
+          <Settings2 class="size-4" />
+        </BaseIconButton>
+      </template>
+    </BaseTable>
+    <BaseTablePagination :pagination="pagination" :loading="loading" @page-change="page = $event" @page-size-change="pageSize = $event" />
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginConfigurationFields.vue b/frontend/src/views/plugins/components/PluginConfigurationFields.vue
new file mode 100644
index 000000000..a569280f5
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginConfigurationFields.vue
@@ -0,0 +1,212 @@
+<script setup lang="ts">
+import type { JsonSchema } from '../utils/model'
+
+import { BaseEmpty, BaseFormItem, BaseInput, BaseTag } from '@codex-proxy/ui'
+
+import { computed, nextTick, shallowRef, useTemplateRef, watch } from 'vue'
+import SchemaForm from '@/components/SchemaForm/index.vue'
+import { jsonObjectError, parseJsonObject } from '@/utils/jsonObject'
+import PluginHelpPopover from './PluginHelpPopover.vue'
+
+const props = withDefaults(defineProps<{
+  schema: Record<string, unknown>
+  secretFields: string[]
+  existingSecretFields?: string[]
+  secretMode?: 'preserve' | 'replace' | 'clear'
+  disabled?: boolean
+}>(), {
+  existingSecretFields: () => [],
+  secretMode: 'replace',
+  disabled: false,
+})
+
+const emit = defineEmits<{
+  validityChange: [valid: boolean]
+}>()
+
+const configuration = defineModel<Record<string, unknown>>('configuration', { required: true })
+const secrets = defineModel<Record<string, string>>('secrets', { required: true })
+const configurationText = shallowRef('{}')
+const schemaForm = useTemplateRef<{ focusField: (key?: string) => Promise<boolean> }>('schemaForm')
+const secretFieldsRoot = useTemplateRef<HTMLElement>('secretFieldsRoot')
+const configurationError = computed(() => jsonObjectError(configurationText.value, 48 * 1024))
+const configurationSchema = computed(() => {
+  const schema = { ...props.schema } as JsonSchema
+  if (schema.properties) {
+    schema.properties = Object.fromEntries(
+      Object.entries(schema.properties).filter(([name]) => !props.secretFields.includes(name)),
+    )
+  }
+  if (schema.required)
+    schema.required = schema.required.filter(name => !props.secretFields.includes(name))
+  return schema as Record<string, unknown>
+})
+const secretSchemas = computed(() => {
+  const properties = (props.schema as JsonSchema).properties ?? {}
+  const required = (props.schema as JsonSchema).required ?? []
+  return props.secretFields.map(name => ({
+    name,
+    schema: properties[name] ?? { type: 'string' },
+    required: required.includes(name),
+  }))
+})
+const requiredConfigurationFields = computed(() => (configurationSchema.value as JsonSchema).required ?? [])
+const missingConfigurationFields = computed(() => requiredConfigurationFields.value.filter(name =>
+  !Object.hasOwn(configuration.value, name),
+))
+const configurationFieldErrors = computed(() => Object.fromEntries(
+  missingConfigurationFields.value.map(name => [name, '请填写必填配置']),
+))
+const requiredSecretFields = computed(() => secretSchemas.value.filter(field => field.required))
+const missingSecretFields = computed(() => requiredSecretFields.value.filter((field) => {
+  if (props.secretMode === 'clear')
+    return true
+  if (props.secretMode === 'preserve')
+    return !props.existingSecretFields.includes(field.name)
+  return !valuePresent(secrets.value[field.name])
+}))
+const secretModeError = computed(() => {
+  if (props.secretMode === 'preserve' && props.existingSecretFields.some(name => !props.secretFields.includes(name)))
+    return '目标版本不支持部分已保存的敏感配置，请选择替换或清除'
+  if (!missingSecretFields.value.length || props.secretMode === 'replace')
+    return ''
+  const labels = missingSecretFields.value.map(field => field.schema.title || field.name).join('、')
+  return props.secretMode === 'clear'
+    ? `必填敏感配置不能清除：${labels}`
+    : `没有可保留的必填敏感配置：${labels}`
+})
+const hasConfiguration = computed(() => {
+  const properties = (configurationSchema.value as JsonSchema).properties
+  return Boolean(properties && Object.keys(properties).length > 0)
+    || (configurationSchema.value as JsonSchema).additionalProperties !== false
+    || Object.keys(configuration.value).length > 0
+})
+const hasFields = computed(() => hasConfiguration.value || props.secretFields.length > 0)
+
+function setSecret(name: string, value: unknown) {
+  const next = { ...secrets.value }
+  if (typeof value !== 'string' || !value) {
+    delete next[name]
+    secrets.value = next
+    return
+  }
+  // 计算属性保留 __proto__ 等合法 JSON 字段，不触发普通对象的原型 setter
+  secrets.value = { ...next, [name]: value }
+}
+
+function valuePresent(value: unknown) {
+  return value !== undefined && value !== null && value !== ''
+}
+
+const valid = computed(() => !configurationError.value
+  && !secretModeError.value
+  && !missingConfigurationFields.value.length
+  && !missingSecretFields.value.length)
+const validationMessage = computed(() => secretModeError.value
+  || configurationError.value
+  || (missingSecretFields.value.length ? '请填写必填敏感配置' : '请检查基本设置'))
+
+watch(valid, value => emit('validityChange', value), { immediate: true })
+
+watch(
+  configuration,
+  (value) => {
+    const next = JSON.stringify(value, null, 2)
+    if (configurationText.value !== next)
+      configurationText.value = next
+  },
+  { immediate: true },
+)
+
+watch(configurationText, (text) => {
+  if (!jsonObjectError(text, 48 * 1024))
+    configuration.value = parseJsonObject(text, 48 * 1024)
+})
+
+async function focusInvalid() {
+  if (secretModeError.value)
+    return 'secretMode' as const
+  if (configurationError.value) {
+    await schemaForm.value?.focusField()
+    return 'configuration' as const
+  }
+  if (missingConfigurationFields.value.length) {
+    await schemaForm.value?.focusField(missingConfigurationFields.value[0])
+    return 'configuration' as const
+  }
+  if (!missingSecretFields.value.length)
+    return null
+  if (props.secretMode !== 'replace')
+    return 'secretMode' as const
+
+  await nextTick()
+  const missingName = missingSecretFields.value[0]?.name
+  const container = [...(secretFieldsRoot.value?.querySelectorAll<HTMLElement>('[data-secret-field]') ?? [])]
+    .find(element => element.dataset.secretField === missingName)
+  container?.querySelector<HTMLElement>('input:not([type="hidden"]), textarea, button, [tabindex]:not([tabindex="-1"])')?.focus()
+  return 'secret' as const
+}
+
+defineExpose({ focusInvalid, validationMessage })
+</script>
+
+<template>
+  <BaseEmpty
+    v-if="!hasFields"
+    title="无需填写插件参数"
+    size="sm"
+    surface="inset"
+    class="min-h-40 content-center"
+  />
+  <div v-else class="grid gap-5">
+    <SchemaForm
+      v-if="hasConfiguration"
+      ref="schemaForm"
+      v-model="configurationText"
+      :schema="configurationSchema"
+      :disabled="disabled"
+      :maximum-bytes="48 * 1024"
+      :field-errors="configurationFieldErrors"
+    />
+
+    <template v-if="secretFields.length > 0">
+      <div class="flex min-w-0 flex-wrap items-center gap-2">
+        <strong class="text-cp leading-none text-cp-text">敏感配置</strong>
+        <PluginHelpPopover label="敏感配置说明">
+          敏感配置单独保存，不回显已有值，选择保留时不会更改，选择替换时以本次填写的全部值覆盖
+        </PluginHelpPopover>
+        <BaseTag v-if="existingSecretFields.length > 0" type="success" size="sm">
+          已保存 {{ existingSecretFields.length }} 项
+        </BaseTag>
+      </div>
+      <p v-if="secretMode === 'clear'" class="m-0 text-cp-xs text-cp-warning-text">
+        保存时清除全部敏感配置
+      </p>
+      <div ref="secretFieldsRoot" class="contents">
+        <BaseFormItem
+          v-for="field in secretMode === 'replace' ? secretSchemas : []"
+          :key="field.name"
+          :label="field.schema.title || field.name"
+          :required="field.required"
+          :data-secret-field="field.name"
+        >
+          <template v-if="field.schema.description" #label-extra>
+            <PluginHelpPopover :label="`${field.schema.title || field.name}说明`">
+              {{ field.schema.description }}
+            </PluginHelpPopover>
+          </template>
+          <BaseInput
+            :model-value="secrets[field.name] ?? ''"
+            type="password"
+            autocomplete="new-password"
+            :disabled="disabled"
+            :aria-label="field.schema.title || field.name"
+            :aria-invalid="field.required && !valuePresent(secrets[field.name])"
+            placeholder="输入新值"
+            @update:model-value="setSecret(field.name, $event)"
+          />
+        </BaseFormItem>
+      </div>
+    </template>
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginConfigurationModal.vue b/frontend/src/views/plugins/components/PluginConfigurationModal.vue
new file mode 100644
index 000000000..a24fb0d61
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginConfigurationModal.vue
@@ -0,0 +1,167 @@
+<script setup lang="ts">
+import type { ConfigurePluginInstanceRequest, PluginArtifact, PluginInstance, PluginVersionPlan } from '@/api'
+import { BaseButton, BaseModal, BaseSegmented, toast } from '@codex-proxy/ui'
+import { Blocks, Save, Settings2, ShieldCheck } from '@lucide/vue'
+import { computed, nextTick, ref, shallowRef, useTemplateRef, watch } from 'vue'
+import { cloneJsonValue, pluginContributionForCapability } from '../utils/model'
+import PluginBindingEditor from './PluginBindingEditor.vue'
+import PluginConfigurationFields from './PluginConfigurationFields.vue'
+import PluginFrontendAuthenticationEditor from './PluginFrontendAuthenticationEditor.vue'
+
+const props = defineProps<{
+  instance: PluginInstance | null
+  artifact: PluginArtifact | null
+  draft: PluginVersionPlan | null
+  error: string
+  saving: boolean
+}>()
+const emit = defineEmits<{ save: [value: ConfigurePluginInstanceRequest] }>()
+const open = defineModel<boolean>({ required: true })
+const section = shallowRef('general')
+const configurationValid = shallowRef(true)
+const authenticationValid = shallowRef(true)
+const bindingsValid = shallowRef(true)
+const secretMode = shallowRef<'preserve' | 'replace' | 'clear'>('preserve')
+const secretValues = ref<Record<string, string>>({})
+const configuration = ref<Record<string, unknown>>({})
+const bindings = ref<ConfigurePluginInstanceRequest['bindings']>([])
+const configurationFields = useTemplateRef<{ focusInvalid: () => Promise<unknown>, validationMessage: string }>('configurationFields')
+const authenticationEditor = useTemplateRef<{ validationError: string }>('authenticationEditor')
+const existingSecretFields = computed(() => props.draft?.secretFields ?? props.instance?.secretFields ?? [])
+const versionChanged = computed(() => Boolean(props.instance && props.artifact && props.instance.artifactSha256 !== props.artifact.metadata.sha256))
+const authenticationContribution = computed(() => props.artifact && pluginContributionForCapability(props.artifact.metadata, 'frontend_authentication'))
+const authenticationBinding = computed({
+  get: () => bindings.value.find(binding => binding.contribution === authenticationContribution.value?.id) ?? null,
+  set: (binding) => {
+    const others = bindings.value.filter(value => value.contribution !== authenticationContribution.value?.id)
+    bindings.value = binding ? [...others, cloneJsonValue(binding)] : others
+  },
+})
+const hasRequestBindings = computed(() => Object.values(props.artifact?.metadata.contributes ?? {}).some(contribution => contribution.stages.some(stage => ['request', 'attempt', 'routing', 'scheduling', 'observation'].includes(stage))))
+const sections = computed(() => [
+  { label: '插件参数', value: 'general', icon: Settings2 },
+  ...(hasRequestBindings.value ? [{ label: '高级设置', value: 'requests', icon: Blocks }] : []),
+  ...(authenticationContribution.value ? [{ label: '客户端认证', value: 'authentication', icon: ShieldCheck }] : []),
+])
+const primaryLabel = computed(() => versionChanged.value ? '应用并切换' : props.instance?.configurationRequired ? '保存并启用' : '保存设置')
+const secretModes = [
+  { label: '保留已有值', value: 'preserve' },
+  { label: '替换全部值', value: 'replace' },
+  { label: '清除全部值', value: 'clear' },
+]
+
+async function focusConfigurationInvalid() {
+  section.value = 'general'
+  await nextTick()
+  await configurationFields.value?.focusInvalid()
+}
+
+async function submit() {
+  const instance = props.instance
+  const artifact = props.artifact
+  if (!instance || !artifact)
+    return
+  if (!configurationValid.value) {
+    toast.warning(configurationFields.value?.validationMessage || '请检查插件参数')
+    await focusConfigurationInvalid()
+    return
+  }
+  if (!bindingsValid.value) {
+    section.value = 'requests'
+    toast.warning('请设置请求范围，或勾选“应用于所有请求”')
+    return
+  }
+  if (!authenticationValid.value) {
+    section.value = 'authentication'
+    toast.warning(authenticationEditor.value?.validationError || '请检查客户端认证身份映射')
+    return
+  }
+  const input: ConfigurePluginInstanceRequest = {
+    name: instance.name,
+    artifactSha256: artifact.metadata.sha256,
+    enabled: instance.enabled || (!versionChanged.value && instance.configurationRequired),
+    configuration: cloneJsonValue(configuration.value),
+    bindings: cloneJsonValue(bindings.value),
+  }
+  if (secretMode.value !== 'preserve')
+    input.secrets = secretMode.value === 'clear' ? {} : cloneJsonValue(secretValues.value)
+  emit('save', input)
+}
+
+watch(open, async (value) => {
+  secretValues.value = {}
+  if (!value)
+    return
+  configuration.value = cloneJsonValue(props.draft?.configuration ?? props.instance?.configuration ?? {})
+  bindings.value = cloneJsonValue(props.draft?.bindings ?? props.instance?.bindings ?? [])
+  secretMode.value = existingSecretFields.value.length ? 'preserve' : 'replace'
+  configurationValid.value = true
+  authenticationValid.value = true
+  bindingsValid.value = true
+  section.value = 'general'
+  if (props.instance?.configurationRequired)
+    await focusConfigurationInvalid()
+}, { immediate: true })
+</script>
+
+<template>
+  <BaseModal v-model="open" :title="versionChanged ? `切换至 ${artifact?.metadata.version}` : '插件设置'" :description="artifact ? `${artifact.metadata.displayName} · ${artifact.metadata.version}` : undefined" size="lg" :dismissible="!saving">
+    <div v-if="artifact && instance" class="grid gap-5">
+      <div v-if="error" role="alert" class="grid gap-1 text-cp-sm text-cp-warning-text">
+        <span>{{ error }}</span>
+        <span class="text-cp-xs text-cp-text-secondary">当前版本保持不变，修改后再应用</span>
+      </div>
+      <BaseSegmented v-if="sections.length > 1" v-model="section" :options="sections" label="插件设置分区" :disabled="saving" class="w-fit max-w-full" />
+      <div v-show="section === 'general'" class="grid gap-5">
+        <BaseSegmented
+          v-if="existingSecretFields.length"
+          v-model="secretMode"
+          :options="secretModes"
+          label="敏感配置保存方式"
+          :disabled="saving"
+          class="w-full sm:w-auto"
+        />
+        <PluginConfigurationFields
+          ref="configurationFields"
+          v-model:configuration="configuration"
+          v-model:secrets="secretValues"
+          :schema="artifact.metadata.configurationSchema"
+          :secret-fields="artifact.metadata.secretFields"
+          :existing-secret-fields="existingSecretFields"
+          :secret-mode="secretMode"
+          :disabled="saving"
+          @validity-change="configurationValid = $event"
+        />
+      </div>
+      <PluginBindingEditor
+        v-if="open && hasRequestBindings"
+        v-show="section === 'requests'"
+        v-model="bindings"
+        :metadata="artifact.metadata"
+        :disabled="saving"
+        @validity-change="bindingsValid = $event"
+      />
+      <PluginFrontendAuthenticationEditor
+        v-if="authenticationContribution"
+        v-show="section === 'authentication'"
+        ref="authenticationEditor"
+        v-model="authenticationBinding"
+        :contribution="authenticationContribution"
+        :active="open"
+        :disabled="saving"
+        @validity-change="authenticationValid = $event"
+      />
+    </div>
+    <template #footer>
+      <BaseButton variant="secondary" :disabled="saving" @click="open = false">
+        取消
+      </BaseButton>
+      <BaseButton variant="primary" :loading="saving" :disabled="!instance || !artifact" @click="submit">
+        <template #icon>
+          <Save class="size-4" />
+        </template>
+        {{ primaryLabel }}
+      </BaseButton>
+    </template>
+  </BaseModal>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginConfigurationSummary.vue b/frontend/src/views/plugins/components/PluginConfigurationSummary.vue
new file mode 100644
index 000000000..2dcd80a77
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginConfigurationSummary.vue
@@ -0,0 +1,127 @@
+<script setup lang="ts">
+import type { PluginArtifactMetadata, PluginCapabilityBinding, PluginInstance } from '@/api'
+import { BaseScrollbar } from '@codex-proxy/ui'
+import { ChevronDown } from '@lucide/vue'
+import { computed } from 'vue'
+import { pluginCapabilityForContribution, pluginCapabilityLabel } from '../utils/model'
+
+const props = defineProps<{
+  instance: Pick<PluginInstance, 'name' | 'bindings'> & { id?: string }
+  metadata?: PluginArtifactMetadata
+  showCommand: boolean
+}>()
+
+const stageLabels: Record<string, string> = {
+  request: '请求开始',
+  attempt: '每次尝试',
+  routing: '模型路由',
+  scheduling: '账号调度',
+  observation: '请求观察',
+  management: '管理操作',
+  execution: '模型执行',
+  maintenance: '后台维护',
+  authentication: '客户端认证',
+}
+const requestStages = new Set(['request', 'attempt', 'routing', 'scheduling', 'observation'])
+const groups = computed(() => {
+  const result = new Map<string, { label: string, bindings: PluginCapabilityBinding[] }>()
+  for (const binding of props.instance.bindings) {
+    const capability = props.metadata
+      ? pluginCapabilityForContribution(props.metadata, binding.contribution)
+      : undefined
+    if (capability === 'management' || capability === 'command_line')
+      continue
+    const group = result.get(binding.contribution)
+    if (group)
+      group.bindings.push(binding)
+    else result.set(binding.contribution, { label: pluginCapabilityLabel(capability ?? binding.contribution), bindings: [binding] })
+  }
+  return [...result.entries()].map(([id, group]) => {
+    const scopes = new Map<string, { binding: PluginCapabilityBinding, stages: string[] }>()
+    for (const binding of group.bindings) {
+      // 按实际范围合并，不能把数量相同、目标不同的绑定当成同一项。
+      const key = JSON.stringify([
+        requestStages.has(binding.stage),
+        binding.stage === 'authentication',
+        [...binding.clientKeyIds].sort(),
+        [...binding.accountGroupIds].sort(),
+        [...binding.providerIds].sort(),
+        [...binding.models].sort(),
+        binding.identityBindings.map(identity => JSON.stringify([identity.principal, identity.clientKeyId])).sort(),
+      ])
+      const scope = scopes.get(key)
+      if (scope)
+        scope.stages.push(binding.stage)
+      else scopes.set(key, { binding, stages: [binding.stage] })
+    }
+    return {
+      id,
+      label: group.label,
+      scopes: [...scopes.entries()].map(([key, scope]) => ({
+        key,
+        stages: scope.stages.map(stage => stageLabels[stage] ?? stage).filter(label => label !== group.label).join('、'),
+        label: scopeLabel(scope.binding),
+      })),
+    }
+  })
+})
+
+function hasScope(binding: PluginCapabilityBinding) {
+  return Boolean(binding.clientKeyIds.length || binding.accountGroupIds.length || binding.providerIds.length || binding.models.length)
+}
+
+const summary = computed(() => {
+  const bindings = props.instance.bindings
+  const requests = bindings.filter(binding => requestStages.has(binding.stage))
+  return [
+    requests.length && `请求处理：${requests.some(hasScope) ? '自定义范围' : '所有请求'}`,
+    bindings.some(binding => binding.stage === 'maintenance') && '后台维护',
+    bindings.some(binding => binding.stage === 'authentication') && '客户端认证',
+  ].filter(Boolean).join(' · ') || (groups.value.length ? '按配置提供扩展功能' : props.showCommand ? '提供终端命令' : '未配置请求处理')
+})
+
+function scopeLabel(binding: PluginCapabilityBinding) {
+  const scope = [
+    binding.clientKeyIds.length && `${binding.clientKeyIds.length} 个 Key`,
+    binding.accountGroupIds.length && `${binding.accountGroupIds.length} 个分组`,
+    binding.providerIds.length && `${binding.providerIds.length} 个 Provider`,
+    binding.models.length && binding.models.join('、'),
+  ].filter(Boolean).join(' · ')
+  if (binding.stage === 'authentication')
+    return [`${binding.identityBindings.length} 组身份映射`, scope].filter(Boolean).join(' · ')
+  return scope || (requestStages.has(binding.stage) ? '所有请求' : '不限制范围')
+}
+</script>
+
+<template>
+  <details v-if="groups.length || showCommand" class="group text-cp-xs text-cp-text-secondary">
+    <summary class="flex cursor-pointer list-none flex-wrap items-center justify-between gap-x-3 gap-y-2 rounded-cp py-1 outline-none focus-visible:ring-2 focus-visible:ring-cp-control-outline [&::-webkit-details-marker]:hidden">
+      <span class="min-w-0 break-words">{{ summary }}</span>
+      <span class="inline-flex shrink-0 items-center gap-1 text-cp-primary-text">
+        功能详情
+        <ChevronDown class="size-3.5 transition-transform group-open:rotate-180 motion-reduce:transition-none" aria-hidden="true" />
+      </span>
+    </summary>
+    <BaseScrollbar class="mt-4 -mr-3" max-height="min(22rem, 38dvh)" role="region" :aria-label="`${instance.name} 的功能详情`">
+      <div class="grid gap-5 pr-6">
+        <dl v-if="groups.length" class="m-0 grid grid-cols-1 gap-x-8 gap-y-4 sm:grid-cols-2">
+          <div v-for="group in groups" :key="group.id" class="grid min-w-0 content-start gap-1">
+            <dt class="break-words text-cp-sm font-emphasis text-cp-text">
+              {{ group.label }}
+            </dt>
+            <dd class="m-0 grid min-w-0 gap-1 leading-relaxed">
+              <div v-for="scope in group.scopes" :key="scope.key" class="break-words">
+                <span v-if="scope.stages">{{ scope.stages }} · </span>
+                <span>{{ scope.label }}</span>
+              </div>
+            </dd>
+          </div>
+        </dl>
+        <div v-if="showCommand" class="grid gap-1.5">
+          <span class="text-cp-sm font-emphasis text-cp-text">终端命令</span>
+          <code class="break-all">codex-proxy-rs plugin {{ instance.id }} --help</code>
+        </div>
+      </div>
+    </BaseScrollbar>
+  </details>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginDetailModal.vue b/frontend/src/views/plugins/components/PluginDetailModal.vue
new file mode 100644
index 000000000..d8aadca52
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginDetailModal.vue
@@ -0,0 +1,151 @@
+<script setup lang="ts">
+import type { InstalledPlugin } from '../utils/catalog'
+import type { PluginArtifact, PluginInstance, PluginManagementView } from '@/api'
+import { ArrowInDownSquareHalf } from '@boxicons/vue'
+import { BaseButton, BaseEmpty, BaseIconButton, BaseModal, BaseSegmented, BaseTag } from '@codex-proxy/ui'
+import { ArrowUpRight, CircleAlert, History, Layers, Play, Power, RefreshCw, Settings2 } from '@lucide/vue'
+import { computed, shallowRef, watch } from 'vue'
+import { RouterLink } from 'vue-router'
+import { configurationStatus, currentPluginInstance, hasPluginSettings, PLUGIN_STATUS_LABELS, pluginStatusType } from '../utils/catalog'
+import { artifactForInstance } from '../utils/model'
+import { pluginPageLocation } from '../utils/navigation'
+import PluginConfigurationSummary from './PluginConfigurationSummary.vue'
+import PluginHelpPopover from './PluginHelpPopover.vue'
+import PluginLegacyConfigurations from './PluginLegacyConfigurations.vue'
+import PluginVersionsPanel from './PluginVersionsPanel.vue'
+
+const props = defineProps<{ plugin: InstalledPlugin | null, initialSection: 'configurations' | 'versions', views: PluginManagementView[], busy: boolean }>()
+defineEmits<{
+  accept: [artifact: PluginArtifact]
+  edit: [instance: PluginInstance]
+  enable: [instance: PluginInstance]
+  disable: [instance: PluginInstance]
+  deleteConfiguration: [instance: PluginInstance]
+  deleteVersion: [artifact: PluginArtifact]
+  rollback: [instance: PluginInstance]
+  installVersion: [plugin: InstalledPlugin]
+  checkUpdate: [plugin: InstalledPlugin]
+  switchVersion: [artifact: PluginArtifact]
+  uninstall: [plugin: InstalledPlugin]
+}>()
+const open = defineModel<boolean>({ required: true })
+const section = shallowRef('configurations')
+const sections = [{ label: '概览', value: 'configurations', icon: Settings2 }, { label: '版本', value: 'versions', icon: Layers }]
+const current = computed(() => props.plugin && currentPluginInstance(props.plugin))
+const legacy = computed(() => props.plugin?.configurations.filter(instance => instance.id !== current.value?.id) ?? [])
+const currentArtifact = computed(() => current.value && artifactForInstance(current.value, props.plugin?.artifacts ?? []))
+const acceptedArtifact = computed(() => props.plugin?.artifacts.find(artifact => artifact.acceptedAt) ?? null)
+const pendingArtifact = computed(() => props.plugin?.artifacts.find(artifact => !artifact.acceptedAt) ?? null)
+const viewByInstance = computed(() => new Map(props.views.map(view => [view.target.instanceId, view])))
+function capabilities(instance: PluginInstance) {
+  return artifactForInstance(instance, props.plugin?.artifacts ?? [])?.metadata.contributes ?? {}
+}
+function configurationNotes(instance: PluginInstance) {
+  const notes: string[] = []
+  if (instance.runtime.failure)
+    notes.push(instance.runtime.failure.message)
+  if (configurationStatus(instance) === 'pending')
+    notes.push('配置已保存，等待生效，状态会自动刷新')
+  if (configurationStatus(instance) === 'unconfigured')
+    notes.push('补充必填配置后即可启用')
+  if (instance.runtime.drainingRevisions.length || instance.runtime.retainedContinuations)
+    notes.push('旧版本仍有进行中的调用或保留流程，完成前暂不能删除')
+  return notes
+}
+watch(open, (value) => {
+  if (value)
+    section.value = props.initialSection
+})
+watch(() => props.initialSection, value => section.value = value)
+</script>
+
+<template>
+  <BaseModal v-model="open" :title="plugin?.artifact.metadata.displayName ?? '插件详情'" :description="plugin?.artifact.metadata.description" size="md-wide" :dismissible="!busy">
+    <div v-if="plugin" class="grid gap-5">
+      <div class="flex flex-wrap items-center gap-3">
+        <BaseSegmented v-model="section" :options="sections" label="插件详情分区" class="w-44" />
+        <div v-if="plugin.artifact.source.kind !== 'builtin'" class="ml-auto flex items-center gap-2">
+          <BaseIconButton v-if="plugin.source?.source.kind === 'github' || plugin.source?.source.kind === 'url'" label="检查更新" variant="secondary" :disabled="busy" @click="$emit('checkUpdate', plugin)">
+            <RefreshCw class="size-4" />
+          </BaseIconButton>
+          <BaseIconButton label="更新插件" variant="secondary" :disabled="busy" @click="$emit('installVersion', plugin)">
+            <ArrowInDownSquareHalf pack="filled" class="size-5" />
+          </BaseIconButton>
+        </div>
+      </div>
+      <template v-if="section === 'configurations'">
+        <BaseEmpty v-if="!plugin.configurations.length" :title="acceptedArtifact ? '插件尚未初始化' : '插件待安装'" size="sm" surface="inset">
+          <template #action>
+            <BaseButton v-if="acceptedArtifact" variant="primary" @click="$emit('accept', acceptedArtifact)">
+              初始化插件
+            </BaseButton>
+            <BaseButton v-else-if="pendingArtifact" variant="primary" @click="$emit('accept', pendingArtifact)">
+              安装
+            </BaseButton>
+          </template>
+        </BaseEmpty>
+        <article v-for="instance in current ? [current] : []" :key="instance.id" class="grid min-h-36 content-between gap-3 rounded-cp bg-cp-fill-alter p-4">
+          <div class="flex flex-wrap items-center gap-2">
+            <strong class="min-w-0 flex-1 wrap-break-word text-cp-sm">当前版本</strong>
+            <BaseTag>{{ artifactForInstance(instance, plugin.artifacts)?.metadata.version ?? '版本不可用' }}</BaseTag>
+            <BaseTag :type="pluginStatusType(configurationStatus(instance))">
+              <CircleAlert v-if="configurationStatus(instance) === 'failed'" class="mr-1 size-3.5" />
+              {{ PLUGIN_STATUS_LABELS[configurationStatus(instance)] }}
+            </BaseTag>
+            <PluginHelpPopover v-if="configurationNotes(instance).length" :label="`${instance.name}配置状态说明`">
+              <p v-for="note in configurationNotes(instance)" :key="note" class="m-0">
+                {{ note }}
+              </p>
+            </PluginHelpPopover>
+          </div>
+          <PluginConfigurationSummary
+            :instance="instance"
+            :metadata="artifactForInstance(instance, plugin.artifacts)?.metadata"
+            :show-command="configurationStatus(instance) === 'enabled' && Boolean(capabilities(instance).command_line)"
+          />
+          <div class="flex flex-wrap items-center gap-2">
+            <div v-if="configurationStatus(instance) === 'enabled'" class="mr-auto flex min-w-0 flex-wrap items-center gap-2">
+              <RouterLink v-for="page in viewByInstance.get(instance.id)?.pages ?? []" :key="page.id" :to="pluginPageLocation(viewByInstance.get(instance.id)!, page)" class="inline-flex h-cp-control-sm min-w-0 items-center gap-1.5 rounded-cp bg-cp-primary-container px-2.5 text-cp-sm leading-none text-cp-primary-on-container no-underline outline-none transition-colors hover:bg-cp-primary-container-hover focus-visible:ring-2 focus-visible:ring-cp-control-outline motion-reduce:transition-none" @click="open = false">
+                <span class="truncate">{{ page.title }}</span>
+                <ArrowUpRight class="size-3.5 shrink-0" />
+              </RouterLink>
+            </div>
+            <BaseIconButton v-if="instance.configurationRequired || (currentArtifact && hasPluginSettings(currentArtifact))" size="sm" variant="secondary" label="设置" :disabled="busy" @click="$emit('edit', instance)">
+              <Settings2 class="size-4" />
+            </BaseIconButton>
+            <BaseIconButton v-if="configurationStatus(instance) === 'failed'" label="重新启动" size="sm" variant="secondary" :disabled="busy" @click="$emit('enable', instance)">
+              <RefreshCw class="size-4" />
+            </BaseIconButton>
+            <BaseIconButton v-if="instance.enabled" label="停用" size="sm" variant="secondary" :disabled="busy" @click="$emit('disable', instance)">
+              <Power class="size-4" />
+            </BaseIconButton>
+            <BaseIconButton v-else :label="instance.configurationRequired ? '完成设置并启用' : '启用'" size="sm" variant="secondary" :disabled="busy" @click="$emit('enable', instance)">
+              <Play class="size-4" />
+            </BaseIconButton>
+            <BaseIconButton v-if="plugin.artifacts.length > 1" label="回退版本" size="sm" variant="secondary" :disabled="busy" @click="$emit('rollback', instance)">
+              <History class="size-4" />
+            </BaseIconButton>
+          </div>
+        </article>
+        <PluginLegacyConfigurations
+          :instances="legacy"
+          :artifacts="plugin.artifacts"
+          :busy="busy"
+          @edit="$emit('edit', $event)"
+          @enable="$emit('enable', $event)"
+          @disable="$emit('disable', $event)"
+          @delete="$emit('deleteConfiguration', $event)"
+        />
+      </template>
+      <PluginVersionsPanel v-else :plugin="plugin" :busy="busy" @accept="$emit('accept', $event)" @switch-version="$emit('switchVersion', $event)" @delete-version="$emit('deleteVersion', $event)" />
+    </div>
+    <template #footer>
+      <BaseButton v-if="plugin && plugin.artifacts.every(artifact => artifact.source.kind !== 'builtin')" variant="destructive" :disabled="busy" @click="$emit('uninstall', plugin)">
+        卸载插件
+      </BaseButton>
+      <BaseButton variant="secondary" :disabled="busy" @click="open = false">
+        关闭
+      </BaseButton>
+    </template>
+  </BaseModal>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginDownloadAuthentication.vue b/frontend/src/views/plugins/components/PluginDownloadAuthentication.vue
new file mode 100644
index 000000000..cc442e4df
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginDownloadAuthentication.vue
@@ -0,0 +1,151 @@
+<script setup lang="ts">
+import type { CreatePluginSourceCredentialRequest, PluginSourceAuthentication, PluginSourceCredential } from '@/api'
+import { BaseFormItem, BaseInput, BaseSelect } from '@codex-proxy/ui'
+import { computed, reactive, shallowRef, watch } from 'vue'
+import { normalizePluginRepository } from '../utils/model'
+import PluginHelpPopover from './PluginHelpPopover.vue'
+import SourceCredentialPicker from './SourceCredentialPicker.vue'
+
+const props = defineProps<{
+  kind: 'url' | 'github'
+  location: string
+  credentials: PluginSourceCredential[]
+  disabled: boolean
+}>()
+defineEmits<{
+  deleteCredential: [credential: PluginSourceCredential]
+}>()
+const selected = defineModel<string[]>({ required: true })
+const pending = defineModel<boolean>('pending', { required: true })
+const draft = defineModel<CreatePluginSourceCredentialRequest | null>('draft', { required: true })
+const mode = shallowRef(selected.value.length ? 'saved' : 'public')
+const form = reactive({ kind: 'bearer', token: '', username: '', password: '', headerName: '', headerValue: '' })
+const authOptions = [
+  { label: '访问令牌', value: 'bearer' },
+  { label: '用户名与密码', value: 'basic' },
+  { label: '自定义请求头', value: 'header' },
+]
+const modeOptions = computed(() => [
+  { label: '无需认证', value: 'public' },
+  { label: props.kind === 'github' ? '填写 GitHub 令牌' : '填写认证信息', value: 'new' },
+  ...(props.credentials.length ? [{ label: '使用已保存凭据', value: 'saved' }] : []),
+])
+const scope = computed(() => {
+  if (props.kind === 'github') {
+    const repository = normalizePluginRepository(props.location)
+    return /^[-\w.]+\/[-\w.]+$/.test(repository)
+      ? { origin: 'https://api.github.com', pathPrefix: `/repos/${repository}`, name: `GitHub · ${repository}` }
+      : null
+  }
+  try {
+    const url = new URL(props.location.trim())
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)
+    if (!(url.protocol === 'https:' || (url.protocol === 'http:' && loopback)) || url.username || url.password || url.hash || /[%\\]/.test(url.pathname))
+      return null
+    return { origin: url.origin, pathPrefix: url.pathname, name: `下载 · ${url.hostname}` }
+  }
+  catch {
+    return null
+  }
+})
+const authentication = computed<PluginSourceAuthentication | null>(() => {
+  if (props.kind === 'github')
+    return form.token.trim() ? { kind: 'github', token: form.token.trim() } : null
+  if (form.kind === 'basic')
+    return form.username.trim() && form.password ? { kind: 'basic', username: form.username.trim(), password: form.password } : null
+  if (form.kind === 'header')
+    return form.headerName.trim() && form.headerValue ? { kind: 'header', name: form.headerName.trim(), value: form.headerValue } : null
+  return form.token.trim() ? { kind: 'bearer', token: form.token.trim() } : null
+})
+
+function clearSecrets() {
+  Object.assign(form, { token: '', username: '', password: '', headerName: '', headerValue: '' })
+}
+
+function changeMode(value: string) {
+  mode.value = value
+  selected.value = []
+  clearSecrets()
+}
+
+watch(selected, (ids) => {
+  // 弹窗统一提交保存成功后，切换为安全的凭据引用并清掉明文草稿。
+  if (mode.value === 'new' && ids.length) {
+    mode.value = 'saved'
+    clearSecrets()
+  }
+})
+watch(() => [props.kind, props.location], () => {
+  // 切换目标必须重新选择凭据，不把当前目标的认证默认带到另一个来源。
+  mode.value = 'public'
+  selected.value = []
+  clearSecrets()
+})
+watch(() => props.credentials, (credentials) => {
+  selected.value = selected.value.filter(id => credentials.some(item => item.id === id))
+  if (mode.value === 'saved' && !credentials.length)
+    mode.value = 'public'
+})
+watch([mode, selected], () => {
+  pending.value = mode.value === 'new' || (mode.value === 'saved' && !selected.value.length)
+}, { immediate: true })
+watch([mode, scope, authentication], () => {
+  draft.value = mode.value === 'new' && scope.value && authentication.value
+    ? {
+        ...scope.value,
+        name: scope.value.name.slice(0, 128),
+        purposes: props.kind === 'github' ? ['metadata', 'artifact'] : ['artifact'],
+        authentication: authentication.value,
+      }
+    : null
+}, { immediate: true })
+</script>
+
+<template>
+  <div class="grid gap-4">
+    <BaseFormItem label="下载认证">
+      <template #label-extra>
+        <PluginHelpPopover label="下载认证说明">
+          <p class="m-0">
+            {{ kind === 'github' ? '公开仓库无需认证，私有仓库需要有读取权限的 GitHub 令牌' : '仅在下载地址要求认证时填写' }}
+          </p>
+          <p class="m-0">
+            认证信息在查询或解析时保存，仅用于当前来源，不会提供给插件
+          </p>
+        </PluginHelpPopover>
+      </template>
+      <BaseSelect :model-value="mode" :options="modeOptions" :disabled="disabled" class="w-full" aria-label="下载认证" @update:model-value="changeMode" />
+    </BaseFormItem>
+    <template v-if="mode === 'new'">
+      <BaseFormItem v-if="kind === 'url'" label="认证方式">
+        <BaseSelect v-model="form.kind" :options="authOptions" :disabled="disabled" class="w-full" aria-label="认证方式" @update:model-value="clearSecrets" />
+      </BaseFormItem>
+      <BaseFormItem v-if="kind === 'github' || form.kind === 'bearer'" :label="kind === 'github' ? 'GitHub 令牌' : '访问令牌'" required>
+        <BaseInput v-model="form.token" type="password" autocomplete="new-password" :disabled="disabled" aria-label="下载令牌" placeholder="输入令牌" />
+      </BaseFormItem>
+      <div v-else-if="form.kind === 'basic'" class="grid gap-4 sm:grid-cols-2">
+        <BaseFormItem label="用户名" required>
+          <BaseInput v-model="form.username" autocomplete="off" :disabled="disabled" aria-label="下载用户名" />
+        </BaseFormItem>
+        <BaseFormItem label="密码" required>
+          <BaseInput v-model="form.password" type="password" autocomplete="new-password" :disabled="disabled" aria-label="下载密码" />
+        </BaseFormItem>
+      </div>
+      <div v-else class="grid gap-4 sm:grid-cols-2">
+        <BaseFormItem label="请求头名称" required>
+          <BaseInput v-model="form.headerName" :disabled="disabled" aria-label="请求头名称" placeholder="X-Download-Token" />
+        </BaseFormItem>
+        <BaseFormItem label="请求头值" required>
+          <BaseInput v-model="form.headerValue" type="password" autocomplete="new-password" :disabled="disabled" aria-label="请求头值" />
+        </BaseFormItem>
+      </div>
+    </template>
+    <SourceCredentialPicker
+      v-else-if="mode === 'saved'"
+      v-model="selected"
+      :credentials="credentials"
+      :disabled="disabled"
+      @delete="$emit('deleteCredential', $event)"
+    />
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginEnableModal.vue b/frontend/src/views/plugins/components/PluginEnableModal.vue
new file mode 100644
index 000000000..f977d13f1
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginEnableModal.vue
@@ -0,0 +1,85 @@
+<script setup lang="ts">
+import type { JsonSchema } from '../utils/model'
+import type { ConfigurePluginInstanceRequest, PluginArtifactMetadata, PluginInstance } from '@/api'
+import { BaseButton, BaseModal, BaseTag } from '@codex-proxy/ui'
+import { computed } from 'vue'
+import PluginConfigurationSummary from './PluginConfigurationSummary.vue'
+import PluginHelpPopover from './PluginHelpPopover.vue'
+
+const props = defineProps<{
+  request?: ConfigurePluginInstanceRequest
+  metadata?: PluginArtifactMetadata
+  replacements: (Pick<PluginInstance, 'id' | 'name'> & { version?: string })[]
+  saving: boolean
+}>()
+defineEmits<{ confirm: [] }>()
+const open = defineModel<boolean>({ required: true })
+const parameters = computed(() => {
+  const schema = props.metadata?.configurationSchema as JsonSchema | undefined
+  return Object.entries(props.request?.configuration ?? {})
+    .filter(([key]) => !props.metadata?.secretFields.includes(key))
+    .map(([key, value]) => ({
+      key,
+      label: schema?.properties?.[key]?.title ?? key,
+      value: value == null ? '未设置' : typeof value === 'string' ? value : JSON.stringify(value),
+    }))
+})
+</script>
+
+<template>
+  <BaseModal v-model="open" :title="replacements.length ? '切换启用配置' : '启用插件配置'" size="md" :dismissible="!saving">
+    <div v-if="request" class="grid gap-4">
+      <div class="grid gap-3 rounded-cp bg-cp-fill-alter p-4">
+        <div class="flex min-w-0 flex-wrap items-center gap-2">
+          <strong class="min-w-0 flex-1 wrap-anywhere text-cp-sm">{{ request.name }}</strong>
+          <BaseTag v-if="metadata">
+            {{ metadata.version }}
+          </BaseTag>
+          <BaseTag type="primary">
+            将启用
+          </BaseTag>
+        </div>
+        <dl v-if="parameters.length" class="m-0 grid grid-cols-1 gap-3 text-cp-sm sm:grid-cols-2">
+          <div v-for="parameter in parameters" :key="parameter.key" class="grid min-w-0 gap-1">
+            <dt class="wrap-anywhere text-cp-text-secondary">
+              {{ parameter.label }}
+            </dt>
+            <dd class="m-0 max-h-24 overflow-y-auto whitespace-pre-wrap wrap-anywhere">
+              {{ parameter.value }}
+            </dd>
+          </div>
+        </dl>
+        <PluginConfigurationSummary :instance="request" :metadata="metadata" :show-command="false" />
+      </div>
+      <div v-if="replacements.length" class="grid gap-2">
+        <div class="flex items-center gap-1.5 text-cp-xs text-cp-text-secondary">
+          <span>将停用 {{ replacements.length }} 项</span>
+          <PluginHelpPopover label="切换启用说明">
+            以下配置将停止处理新请求，设置、密钥与私有数据保留
+          </PluginHelpPopover>
+        </div>
+        <ul class="m-0 max-h-40 list-none space-y-2 overflow-y-auto p-0">
+          <li v-for="instance in replacements" :key="instance.id" class="flex items-center gap-3 rounded-cp bg-cp-fill-alter p-3">
+            <span class="min-w-0 flex-1 wrap-anywhere text-cp-sm font-emphasis">{{ instance.name }}</span>
+            <div class="flex shrink-0 flex-wrap items-center justify-end gap-2">
+              <BaseTag v-if="instance.version">
+                {{ instance.version }}
+              </BaseTag>
+              <BaseTag type="warning">
+                将停用
+              </BaseTag>
+            </div>
+          </li>
+        </ul>
+      </div>
+    </div>
+    <template #footer>
+      <BaseButton variant="secondary" :disabled="saving" @click="open = false">
+        取消
+      </BaseButton>
+      <BaseButton variant="primary" :loading="saving" :disabled="!request" @click="$emit('confirm')">
+        {{ replacements.length ? '确认切换' : '确认启用' }}
+      </BaseButton>
+    </template>
+  </BaseModal>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginExtensionsPanel.vue b/frontend/src/views/plugins/components/PluginExtensionsPanel.vue
new file mode 100644
index 000000000..b9e20ea6f
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginExtensionsPanel.vue
@@ -0,0 +1,74 @@
+<script setup lang="ts">
+import type { PluginManagementView } from '@/api'
+
+import { BaseButton, BaseEmpty, BaseTag } from '@codex-proxy/ui'
+import { Blocks, ExternalLink } from '@lucide/vue'
+import { computed } from 'vue'
+import { useRouter } from 'vue-router'
+import { pluginPageLocation, shortPluginInstanceId } from '../utils/navigation'
+
+const props = defineProps<{
+  views: PluginManagementView[]
+  loading: boolean
+}>()
+
+const router = useRouter()
+const pageViews = computed(() => props.views.filter(view => view.pages.length > 0))
+
+function openView(view: PluginManagementView) {
+  const page = view.pages[0]
+  if (page)
+    void router.push(pluginPageLocation(view, page))
+}
+</script>
+
+<template>
+  <div class="flex h-full min-h-0 flex-col gap-4">
+    <div v-if="loading && pageViews.length === 0" class="min-h-0 flex-1" aria-busy="true" />
+
+    <BaseEmpty
+      v-else-if="pageViews.length === 0"
+      class="flex-1 content-center"
+      surface="none"
+      :icon="Blocks"
+      title="暂无插件管理页面"
+      description="启用带有管理页面的插件后，可从此处或侧栏进入"
+    />
+
+    <div v-else class="grid content-start gap-3 overflow-y-auto sm:grid-cols-2 xl:grid-cols-3">
+      <article
+        v-for="view in pageViews"
+        :key="view.target.instanceId"
+        class="flex min-w-0 flex-col gap-3 rounded-cp-card bg-cp-bg-container p-4 shadow-cp-card"
+      >
+        <div class="flex min-w-0 items-start gap-3">
+          <span class="inline-flex size-9 shrink-0 items-center justify-center rounded-cp bg-cp-primary-container text-cp-primary-on-container">
+            <Blocks class="size-4" />
+          </span>
+          <div class="min-w-0 flex-1">
+            <h2 class="m-0 truncate text-cp-lg font-heavy text-cp-text" :title="view.name">
+              {{ view.name }}
+            </h2>
+            <p class="mt-1 mb-0 truncate font-mono text-cp-xs text-cp-text-quaternary" :title="view.target.instanceId">
+              配置 {{ shortPluginInstanceId(view.target.instanceId) }}
+            </p>
+          </div>
+          <BaseTag size="sm">
+            {{ view.pages.length }} 页
+          </BaseTag>
+        </div>
+
+        <p class="m-0 line-clamp-2 text-cp-sm leading-relaxed text-cp-text-secondary">
+          {{ view.pages.map(page => page.title).join('、') }}
+        </p>
+
+        <BaseButton class="mt-auto self-start" size="sm" variant="secondary" @click="openView(view)">
+          <template #icon>
+            <ExternalLink class="size-3.5" />
+          </template>
+          打开页面
+        </BaseButton>
+      </article>
+    </div>
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginFrontendAuthenticationEditor.vue b/frontend/src/views/plugins/components/PluginFrontendAuthenticationEditor.vue
new file mode 100644
index 000000000..8b208e30e
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginFrontendAuthenticationEditor.vue
@@ -0,0 +1,330 @@
+<script setup lang="ts">
+import type {
+  ApiKey,
+  PluginCapabilityBinding,
+  PluginContribution,
+  PluginFailurePolicy,
+  PluginFrontendIdentityBinding,
+} from '@/api'
+
+import { BaseButton, BaseFormItem, BaseIconButton, BaseInput, BaseSegmented, BaseSelect, BaseSwitch, toast } from '@codex-proxy/ui'
+
+import { Plus, RefreshCw, Trash2 } from '@lucide/vue'
+import { computed, shallowRef, watch } from 'vue'
+import { getApiKeys } from '@/api'
+import { errorMessage } from '@/utils/async'
+import PluginHelpPopover from './PluginHelpPopover.vue'
+
+const props = withDefaults(defineProps<{
+  contribution: PluginContribution
+  active?: boolean
+  disabled?: boolean
+}>(), {
+  active: false,
+  disabled: false,
+})
+
+const emit = defineEmits<{
+  validityChange: [valid: boolean]
+}>()
+
+const binding = defineModel<PluginCapabilityBinding | null>({ required: true })
+const clientKeys = shallowRef<ApiKey[]>([])
+const loadingKeys = shallowRef(false)
+const keysFailed = shallowRef(false)
+let keyLoadController: AbortController | null = null
+
+const fallbackOptions = [
+  { label: '独占认证', value: 'reject' },
+  { label: '未匹配时回退 API Key', value: 'delegate' },
+]
+
+const keyOptions = computed(() => {
+  const options = clientKeys.value.map(key => ({
+    label: `${key.name || key.prefix}${key.enabled ? '' : '（已停用）'}`,
+    value: key.id,
+    description: `${key.prefix} · ${key.id}`,
+  }))
+  const knownIds = new Set(clientKeys.value.map(key => key.id))
+  for (const identity of binding.value?.identityBindings ?? []) {
+    if (identity.clientKeyId && !knownIds.has(identity.clientKeyId)) {
+      options.push({
+        label: '已配置但当前不可用',
+        value: identity.clientKeyId,
+        description: identity.clientKeyId,
+      })
+      knownIds.add(identity.clientKeyId)
+    }
+  }
+  return options
+})
+
+const validationError = computed(() => {
+  const value = binding.value
+  if (!value)
+    return ''
+  if (
+    value.contribution !== props.contribution.id
+    || value.stage !== 'authentication'
+    || !props.contribution.stages.includes(value.stage)
+    || (value.failurePolicy !== 'reject' && value.failurePolicy !== 'delegate')
+  ) {
+    return '客户端认证绑定必须使用认证阶段和受支持的未匹配处理'
+  }
+  if (
+    value.providerIds.length
+    || value.models.length
+    || value.clientKeyIds.length
+    || value.accountGroupIds.length
+  ) {
+    return '客户端认证不支持 Provider、模型或分组范围，请关闭后重新启用该绑定'
+  }
+  if (value.identityBindings.length === 0)
+    return '请添加至少一条身份映射'
+  if (value.identityBindings.length > 256)
+    return '身份映射不能超过 256 条'
+
+  const principals = new Set<string>()
+  for (const identity of value.identityBindings) {
+    if (
+      !identity.principal
+      || identity.principal !== identity.principal.trim()
+      || new TextEncoder().encode(identity.principal).byteLength > 256
+      || /\p{Cc}/u.test(identity.principal)
+    ) {
+      return '身份标识必须是 1–256 个 UTF-8 字节，且不能含首尾空白或控制字符'
+    }
+    if (principals.has(identity.principal))
+      return '同一身份标识只能配置一次'
+    if (!identity.clientKeyId)
+      return '请为每个身份标识选择客户端 Key'
+    principals.add(identity.principal)
+  }
+  return ''
+})
+
+function enableAuthentication(enabled: boolean) {
+  binding.value = enabled
+    ? {
+        contribution: props.contribution.id,
+        stage: 'authentication',
+        order: 0,
+        failurePolicy: 'reject',
+        providerIds: [],
+        models: [],
+        clientKeyIds: [],
+        accountGroupIds: [],
+        identityBindings: [{ principal: '', clientKeyId: '' }],
+      }
+    : null
+}
+
+function setFailurePolicy(value: string) {
+  if (!binding.value || (value !== 'reject' && value !== 'delegate'))
+    return
+  binding.value = { ...binding.value, failurePolicy: value as PluginFailurePolicy }
+}
+
+function addIdentity() {
+  if (!binding.value || binding.value.identityBindings.length >= 256)
+    return
+  binding.value = {
+    ...binding.value,
+    identityBindings: [
+      ...binding.value.identityBindings,
+      { principal: '', clientKeyId: '' },
+    ],
+  }
+}
+
+function updateIdentity(index: number, update: Partial<PluginFrontendIdentityBinding>) {
+  if (!binding.value)
+    return
+  binding.value = {
+    ...binding.value,
+    identityBindings: binding.value.identityBindings.map((identity, identityIndex) =>
+      identityIndex === index ? { ...identity, ...update } : identity,
+    ),
+  }
+}
+
+function removeIdentity(index: number) {
+  if (!binding.value)
+    return
+  binding.value = {
+    ...binding.value,
+    identityBindings: binding.value.identityBindings.filter((_, identityIndex) => identityIndex !== index),
+  }
+}
+
+async function loadClientKeys() {
+  keyLoadController?.abort()
+  const controller = new AbortController()
+  keyLoadController = controller
+  loadingKeys.value = true
+  keysFailed.value = false
+  try {
+    const items: ApiKey[] = []
+    const seenCursors = new Set<string>()
+    let cursor: string | undefined
+    do {
+      const result = await getApiKeys({ limit: 200, cursor }, { signal: controller.signal, silent: true })
+      items.push(...result.items)
+      cursor = result.nextCursor ?? undefined
+      if (cursor && seenCursors.has(cursor))
+        throw new Error('服务返回了重复的分页位置')
+      if (cursor)
+        seenCursors.add(cursor)
+    } while (cursor)
+    if (!controller.signal.aborted)
+      clientKeys.value = items
+  }
+  catch (error: unknown) {
+    if (!controller.signal.aborted) {
+      keysFailed.value = true
+      toast.error(errorMessage(error, '加载客户端 Key 失败'))
+    }
+  }
+  finally {
+    if (keyLoadController === controller && !controller.signal.aborted) {
+      loadingKeys.value = false
+      keyLoadController = null
+    }
+  }
+}
+
+watch(validationError, error => emit('validityChange', !error), { immediate: true })
+watch(() => props.active, (active, _, onCleanup) => {
+  if (!active) {
+    keyLoadController?.abort()
+    keyLoadController = null
+    loadingKeys.value = false
+    return
+  }
+  void loadClientKeys()
+  onCleanup(() => keyLoadController?.abort())
+}, { immediate: true })
+
+defineExpose({ validationError })
+</script>
+
+<template>
+  <div class="grid gap-4">
+    <div class="flex items-center gap-2 rounded-cp-lg bg-cp-fill-alter p-4">
+      <BaseSwitch
+        :model-value="Boolean(binding)"
+        label="启用客户端认证"
+        show-label
+        :disabled="disabled"
+        @update:model-value="enableAuthentication"
+      />
+      <PluginHelpPopover label="客户端认证说明">
+        <p class="m-0">
+          插件识别请求中的外部身份，宿主再将该身份映射到已有 Client Key，沿用这个 Key 的限额、账号范围与并发策略
+        </p>
+        <p class="m-0">
+          此功能用于客户端 API 请求，不替代管理端登录
+        </p>
+        <p class="m-0 break-all font-mono text-cp-text-quaternary">
+          {{ contribution.id }}
+        </p>
+      </PluginHelpPopover>
+    </div>
+
+    <template v-if="binding">
+      <BaseFormItem label="未匹配处理">
+        <template #label-extra>
+          <PluginHelpPopover label="未匹配处理说明">
+            <p class="m-0">
+              独占认证：插件未识别到身份时拒绝请求
+            </p>
+            <p class="m-0">
+              未匹配时回退 API Key：插件未识别到身份时，继续使用宿主原有的 API Key 认证
+            </p>
+            <p class="m-0">
+              插件明确拒绝或调用失败时始终拒绝请求，不会回退
+            </p>
+          </PluginHelpPopover>
+        </template>
+        <BaseSegmented
+          :model-value="binding.failurePolicy"
+          :options="fallbackOptions"
+          label="客户端认证未匹配处理"
+          :disabled="disabled"
+          @update:model-value="setFailurePolicy"
+        />
+      </BaseFormItem>
+
+      <div class="grid gap-2">
+        <div class="flex min-w-0 items-end justify-between gap-3">
+          <div class="flex min-w-0 items-center gap-1.5">
+            <p class="m-0 text-cp leading-none font-medium text-cp-text-secondary">
+              身份映射
+            </p>
+            <PluginHelpPopover label="身份映射说明">
+              <p class="m-0">
+                身份标识必须与插件返回的值完全一致，同一身份只能映射一次
+              </p>
+              <p class="m-0">
+                选择该身份使用的 Client Key，已停用或删除的 Key 不会获得执行权限
+              </p>
+            </PluginHelpPopover>
+          </div>
+          <div class="flex shrink-0 items-center gap-1">
+            <BaseIconButton v-if="keysFailed" size="sm" label="重新加载客户端 Key" :disabled="disabled" :loading="loadingKeys" @click="loadClientKeys()">
+              <RefreshCw class="size-3.5" />
+            </BaseIconButton>
+            <BaseButton
+              size="sm"
+              variant="secondary"
+              :disabled="disabled || binding.identityBindings.length >= 256"
+              @click="addIdentity"
+            >
+              <template #icon>
+                <Plus class="size-3.5" />
+              </template>
+              添加映射
+            </BaseButton>
+          </div>
+        </div>
+
+        <div
+          v-for="(identity, index) in binding.identityBindings"
+          :key="index"
+          class="grid min-w-0 gap-3 rounded-cp-lg bg-cp-fill-alter p-3 md:grid-cols-[minmax(0,1fr)_minmax(0,1fr)_auto] md:items-end"
+        >
+          <BaseFormItem label="身份标识" required>
+            <BaseInput
+              :model-value="identity.principal"
+              maxlength="256"
+              placeholder="填写插件返回的身份标识"
+              :disabled="disabled"
+              @update:model-value="updateIdentity(index, { principal: $event })"
+            />
+          </BaseFormItem>
+          <BaseFormItem label="客户端 Key" required>
+            <BaseSelect
+              :model-value="identity.clientKeyId"
+              :options="keyOptions"
+              :disabled="disabled || loadingKeys"
+              :placeholder="loadingKeys ? '加载中…' : keysFailed ? '加载失败，请重试' : '选择客户端 Key'"
+              empty-text="暂无客户端 Key"
+              class="w-full min-w-0"
+              @update:model-value="updateIdentity(index, { clientKeyId: $event })"
+            />
+          </BaseFormItem>
+          <BaseIconButton
+            size="md"
+            variant="ghost"
+            :disabled="disabled"
+            :label="`移除第 ${index + 1} 条身份映射`"
+            class="justify-self-end"
+            @click="removeIdentity(index)"
+          >
+            <Trash2 class="size-3.5" />
+          </BaseIconButton>
+        </div>
+      </div>
+    </template>
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginHelpPopover.vue b/frontend/src/views/plugins/components/PluginHelpPopover.vue
new file mode 100644
index 000000000..c77f2013f
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginHelpPopover.vue
@@ -0,0 +1,40 @@
+<script setup lang="ts">
+import { BaseIconButton, BasePopover } from '@codex-proxy/ui'
+import { Info } from '@lucide/vue'
+import { shallowRef, useId } from 'vue'
+
+defineProps<{ label: string }>()
+
+const open = shallowRef(false)
+const descriptionId = useId()
+
+function handleKeydown(event: KeyboardEvent) {
+  if (event.key !== 'Escape' || !open.value)
+    return
+  // 先关闭说明，避免一次按键连带关闭正在编辑的配置弹窗。
+  event.preventDefault()
+  event.stopPropagation()
+  open.value = false
+}
+</script>
+
+<template>
+  <BasePopover v-model="open" trigger="hover-click" placement="top-start" :hover-delay="240" class="shrink-0">
+    <template #trigger>
+      <BaseIconButton
+        :label="label"
+        size="sm"
+        class="size-5!"
+        :title="undefined"
+        :aria-expanded="open"
+        :aria-describedby="open ? descriptionId : undefined"
+        @keydown="handleKeydown"
+      >
+        <Info class="size-3.5" />
+      </BaseIconButton>
+    </template>
+    <div :id="descriptionId" role="tooltip" class="grid max-w-80 gap-2 p-3 text-cp-xs leading-relaxed break-words text-cp-text-secondary">
+      <slot />
+    </div>
+  </BasePopover>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginIcon.vue b/frontend/src/views/plugins/components/PluginIcon.vue
new file mode 100644
index 000000000..bf9394647
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginIcon.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+import type { PluginArtifact } from '@/api'
+import { Package } from '@lucide/vue'
+import { computed, shallowRef } from 'vue'
+import { pluginArtifactIconPath } from '@/api'
+import { useThemeStore } from '@/stores/modules/theme'
+
+const props = defineProps<{
+  artifact: PluginArtifact
+}>()
+
+const theme = useThemeStore()
+const failedSource = shallowRef('')
+const source = computed(() => props.artifact.metadata.icon
+  ? pluginArtifactIconPath(props.artifact.metadata.sha256, theme.effectiveTheme)
+  : '')
+</script>
+
+<template>
+  <span class="inline-flex shrink-0 items-center justify-center overflow-hidden bg-cp-fill-alter text-cp-text-secondary" aria-hidden="true">
+    <img
+      v-if="source && source !== failedSource"
+      :key="source"
+      :src="source"
+      alt=""
+      class="size-full object-contain p-1"
+      loading="lazy"
+      decoding="async"
+      @error="failedSource = source"
+    >
+    <Package v-else class="size-2/3" />
+  </span>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginInstallModal.vue b/frontend/src/views/plugins/components/PluginInstallModal.vue
new file mode 100644
index 000000000..2a97edb00
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginInstallModal.vue
@@ -0,0 +1,640 @@
+<script setup lang="ts">
+import type { PluginUpdateSelection } from '../composables/usePluginUpdateCheck'
+import type { PluginInstallSelection } from '../utils/model'
+import type {
+  CreatePluginSourceCredentialRequest,
+  PluginArtifact,
+  PluginRelease,
+  PluginSourceCredential,
+  PluginUpdateSourceBinding,
+  QueryPluginReleaseRequest,
+  VerifiedPluginArtifact,
+  VerifyRemotePluginRequest,
+} from '@/api'
+
+import { Github } from '@boxicons/vue'
+import { BaseButton, BaseCheckbox, BaseForm, BaseFormItem, BaseInput, BaseModal, BaseSegmented, BaseSelect, BaseTag, toast } from '@codex-proxy/ui'
+
+import { CheckCircle2, Download, FileArchive, Link, PackageOpen } from '@lucide/vue'
+import { useEventListener, useSessionStorage } from '@vueuse/core'
+import { isEqual } from 'es-toolkit'
+import { computed, nextTick, reactive, shallowRef, watch } from 'vue'
+import { formatDateTime } from '@/utils/date'
+import { normalizePluginRepository, pluginInstallSelectionKey } from '../utils/model'
+import PluginDownloadAuthentication from './PluginDownloadAuthentication.vue'
+import PluginHelpPopover from './PluginHelpPopover.vue'
+import PluginPermissionSummary from './PluginPermissionSummary.vue'
+import PluginSourceProxyField from './PluginSourceProxyField.vue'
+
+export type PluginInstallMode = 'upload' | 'url' | 'github'
+
+const props = defineProps<{
+  mode: PluginInstallMode
+  installedArtifacts: PluginArtifact[]
+  acceptanceArtifact: PluginArtifact | null
+  updateSource: PluginUpdateSourceBinding | null
+  updateSelection: PluginUpdateSelection | null
+  saveSource: (source: PluginUpdateSourceBinding) => Promise<boolean>
+  credentials: PluginSourceCredential[]
+  savingCredential: boolean
+  saveCredential: (request: CreatePluginSourceCredentialRequest) => Promise<PluginSourceCredential | null>
+  release: PluginRelease | null
+  saving: boolean
+  querying: boolean
+  verifying: boolean
+  verified: { requestKey: string | File, artifact: VerifiedPluginArtifact } | null
+}>()
+
+const emit = defineEmits<{
+  install: [request: PluginInstallSelection]
+  accept: [artifact: PluginArtifact]
+  query: [request: QueryPluginReleaseRequest]
+  verify: [request: PluginInstallSelection]
+  resetVerification: []
+  resetQuery: []
+  changeMode: [mode: PluginInstallMode]
+  deleteCredential: [credential: PluginSourceCredential]
+}>()
+
+const open = defineModel<boolean>({ required: true })
+const uploadFile = shallowRef<File | null>(null)
+const urlForm = reactive({
+  url: '',
+  sha256: '',
+  credentialIds: [] as string[],
+  outboundProxyId: '',
+})
+const githubForm = reactive({
+  repository: '',
+  tag: '',
+  allowPrerelease: false,
+  credentialIds: [] as string[],
+  outboundProxyId: '',
+  asset: '',
+  sha256: '',
+})
+interface InstallDraft {
+  mode: PluginInstallMode
+  url: typeof urlForm
+  github: Omit<typeof githubForm, 'asset'>
+}
+const drafts = useSessionStorage<Record<string, InstallDraft>>('cp-plugin-install-drafts', {}, { flush: 'sync' })
+const draftKey = computed(() => props.updateSource ? `plugin:${props.updateSource.pluginId}` : 'install')
+let activeDraftKey: string | null = null
+const queriedGithubKey = shallowRef('')
+const pendingAuthentication = shallowRef(false)
+const credentialDraft = shallowRef<CreatePluginSourceCredentialRequest | null>(null)
+const submitting = shallowRef(false)
+const authenticationIncomplete = computed(() => pendingAuthentication.value && !credentialDraft.value)
+const modeOptions = [
+  { label: '上传包', value: 'upload', icon: FileArchive },
+  { label: 'URL', value: 'url', icon: Link },
+  { label: 'GitHub', value: 'github', icon: Github },
+]
+const busy = computed(() => submitting.value || props.saving || props.querying || props.verifying || props.savingCredential)
+const connectionForm = computed(() => props.mode === 'url' ? urlForm : githubForm)
+
+function changeMode(value: string) {
+  if (busy.value || (value !== 'upload' && value !== 'url' && value !== 'github'))
+    return
+  emit('changeMode', value)
+}
+const assetOptions = computed(() => (props.release?.assets ?? []).filter(asset => /\.(?:tar\.gz|tgz)$/i.test(asset.name)).map(asset => ({
+  label: `${asset.name} · ${formatFileSize(asset.size)}`,
+  value: asset.name,
+  description: asset.sha256 ? `SHA-256 ${asset.sha256}` : undefined,
+})))
+const digestPattern = /^[a-f0-9]{64}$/
+const digestError = computed(() => {
+  const digest = connectionForm.value.sha256.trim().toLowerCase()
+  return digest && !digestPattern.test(digest) ? '请输入 64 位十六进制摘要' : ''
+})
+const remoteRequest = computed<VerifyRemotePluginRequest | null>(() => {
+  if (digestError.value)
+    return null
+  if (props.mode === 'url') {
+    const url = urlForm.url.trim()
+    const sha256 = urlForm.sha256.trim().toLowerCase()
+    return url
+      ? {
+          expectedPluginId: props.updateSource?.pluginId ?? null,
+          credentialIds: [...urlForm.credentialIds],
+          outboundProxyId: urlForm.outboundProxyId || null,
+          location: { kind: 'url', url, sha256: sha256 || null },
+        }
+      : null
+  }
+  const release = props.release
+  const sha256 = githubForm.sha256.trim().toLowerCase()
+  if (props.mode !== 'github' || !release || !githubForm.asset)
+    return null
+  return {
+    expectedPluginId: props.updateSource?.pluginId ?? null,
+    credentialIds: [...githubForm.credentialIds],
+    outboundProxyId: githubForm.outboundProxyId || null,
+    location: { kind: 'github', repository: release.repository, tag: release.tag, asset: githubForm.asset, allow_prerelease: release.prerelease, sha256: sha256 || null },
+  }
+})
+const selection = computed(() => props.mode === 'upload' ? uploadFile.value : remoteRequest.value)
+const requestKey = computed(() => selection.value ? pluginInstallSelectionKey(selection.value) : null)
+const verified = computed<VerifiedPluginArtifact | null>(() => {
+  if (props.acceptanceArtifact) {
+    return {
+      metadata: props.acceptanceArtifact.metadata,
+      source: props.acceptanceArtifact.source,
+    }
+  }
+  return !pendingAuthentication.value && props.verified?.requestKey === requestKey.value
+    ? props.verified.artifact
+    : null
+})
+const previousArtifact = computed(() => props.installedArtifacts
+  .filter(artifact => artifact.acceptedAt && artifact.metadata.pluginId === verified.value?.metadata.pluginId)
+  .sort((left, right) => right.acceptedAt!.localeCompare(left.acceptedAt!))[0])
+const addedPermissions = computed(() => verified.value?.metadata.permissionDescriptions.filter(permission =>
+  !previousArtifact.value?.metadata.requestedPermissions.includes(permission.permission),
+) ?? [])
+const installationLabel = computed(() => previousArtifact.value ? '安装新版本' : '安装')
+const sourceDraft = computed<PluginUpdateSourceBinding | null>(() => {
+  const previous = props.updateSource
+  if (!previous)
+    return null
+  const source = props.mode === 'upload'
+    ? { kind: 'upload' as const }
+    : props.mode === 'url'
+      ? { kind: 'url' as const, url: urlForm.url.trim() }
+      : { kind: 'github' as const, repository: githubRepository() }
+  return {
+    pluginId: previous.pluginId,
+    source,
+    policy: isEqual(source, previous.source) ? previous.policy : { kind: 'manual' },
+    outboundProxyId: props.mode === 'upload' ? null : connectionForm.value.outboundProxyId || null,
+  }
+})
+const sourceChanged = computed(() => sourceDraft.value !== null && !isEqual(sourceDraft.value, { ...props.updateSource, outboundProxyId: props.updateSource?.outboundProxyId ?? null }))
+
+async function prepareSource() {
+  return !sourceChanged.value || (sourceDraft.value !== null && await props.saveSource(sourceDraft.value))
+}
+
+watch(requestKey, () => emit('resetVerification'))
+
+async function prepareAuthentication() {
+  if (!pendingAuthentication.value)
+    return true
+  if (!credentialDraft.value)
+    return false
+  const credential = await props.saveCredential(credentialDraft.value)
+  if (!credential)
+    return false
+  connectionForm.value.credentialIds = [credential.id]
+  // 等认证字段切换为已保存引用、旧校验失效后，再发起下载，避免 watcher 取消新请求。
+  await nextTick()
+  return true
+}
+
+async function verifySelected() {
+  if (busy.value || !selection.value || authenticationIncomplete.value)
+    return
+  submitting.value = true
+  try {
+    if (await prepareSource() && await prepareAuthentication() && selection.value)
+      emit('verify', selection.value)
+  }
+  finally {
+    submitting.value = false
+  }
+}
+
+function reset() {
+  activeDraftKey = props.acceptanceArtifact ? null : draftKey.value
+  uploadFile.value = null
+  Object.assign(urlForm, {
+    url: '',
+    sha256: '',
+    credentialIds: [],
+    outboundProxyId: '',
+  })
+  Object.assign(githubForm, {
+    repository: '',
+    tag: '',
+    allowPrerelease: false,
+    credentialIds: [],
+    outboundProxyId: '',
+    asset: '',
+    sha256: '',
+  })
+  queriedGithubKey.value = ''
+  pendingAuthentication.value = false
+  credentialDraft.value = null
+  const history = props.installedArtifacts
+    .filter(artifact => artifact.metadata.pluginId === props.updateSource?.pluginId)
+    .sort((left, right) => right.installedAt.localeCompare(left.installedAt))
+  const previousUrl = history.find(artifact => artifact.source.kind === 'url')?.source
+  const previousGithub = history.find(artifact => artifact.source.kind === 'github')?.source
+  if (previousUrl?.kind === 'url') {
+    urlForm.url = previousUrl.url
+    urlForm.credentialIds = previousUrl.credential_ids.filter(id => props.credentials.some(credential => credential.id === id))
+    urlForm.outboundProxyId = previousUrl.outbound_proxy?.id ?? ''
+  }
+  if (previousGithub?.kind === 'github') {
+    githubForm.repository = previousGithub.repository
+    githubForm.tag = previousGithub.tag
+    githubForm.credentialIds = previousGithub.credential_ids.filter(id => props.credentials.some(credential => credential.id === id))
+    githubForm.outboundProxyId = previousGithub.outbound_proxy?.id ?? ''
+  }
+  const source = props.updateSource
+  if (source?.source.kind === 'url') {
+    if (urlForm.url !== source.source.url)
+      urlForm.credentialIds = []
+    urlForm.url = source.source.url
+    urlForm.outboundProxyId = source.outboundProxyId ?? ''
+  }
+  if (source?.source.kind === 'github') {
+    if (githubForm.repository !== source.source.repository) {
+      githubForm.credentialIds = []
+      githubForm.tag = ''
+    }
+    githubForm.repository = source.source.repository
+    githubForm.outboundProxyId = source.outboundProxyId ?? ''
+    if (source.policy.kind !== 'manual')
+      githubForm.tag = source.policy.kind === 'pinned' ? source.policy.tag : ''
+    githubForm.allowPrerelease = source.policy.kind === 'pinned' && source.policy.allow_prerelease
+  }
+  const draft = drafts.value[draftKey.value]
+  if (draft && !props.acceptanceArtifact) {
+    Object.assign(urlForm, draft.url, { credentialIds: draft.url.credentialIds.filter(id => props.credentials.some(credential => credential.id === id)) })
+    Object.assign(githubForm, draft.github, { credentialIds: draft.github.credentialIds.filter(id => props.credentials.some(credential => credential.id === id)) })
+    emit('changeMode', draft.mode)
+  }
+  // 明确选择的检查结果优先于旧草稿，仍需重新校验包并确认安装权限。
+  const selection = props.updateSelection
+  if (selection?.binding.source.kind === 'github' && selection.release) {
+    Object.assign(githubForm, {
+      repository: selection.release.repository,
+      tag: selection.release.tag,
+      allowPrerelease: selection.release.prerelease,
+      credentialIds: [...selection.credentialIds],
+      outboundProxyId: selection.binding.outboundProxyId ?? '',
+      sha256: '',
+    })
+    emit('changeMode', 'github')
+  }
+  else if (selection?.binding.source.kind === 'url' && selection.artifact) {
+    Object.assign(urlForm, {
+      url: selection.binding.source.url,
+      credentialIds: [...selection.credentialIds],
+      outboundProxyId: selection.binding.outboundProxyId ?? '',
+      sha256: selection.artifact.metadata.sha256,
+    })
+    emit('changeMode', 'url')
+  }
+  emit('resetQuery')
+}
+
+function rememberDraft() {
+  if (!activeDraftKey)
+    return
+  // 只保存安装参数和凭据引用，不缓存文件、令牌、密码或认证明文草稿。
+  const { asset: _asset, ...github } = githubForm
+  drafts.value = {
+    ...drafts.value,
+    [activeDraftKey]: {
+      mode: props.mode,
+      url: { ...urlForm, credentialIds: [...urlForm.credentialIds] },
+      github: { ...github, credentialIds: [...github.credentialIds] },
+    },
+  }
+}
+useEventListener('pagehide', () => {
+  if (open.value)
+    rememberDraft()
+})
+
+function chooseFile(event: Event) {
+  const file = (event.target as HTMLInputElement).files?.[0] ?? null
+  if (file && file.size > 32 * 1024 * 1024) {
+    toast.warning('插件包不能超过 32 MiB')
+    uploadFile.value = null
+    ;(event.target as HTMLInputElement).value = ''
+    return
+  }
+  uploadFile.value = file
+}
+
+function installSelected() {
+  if (props.acceptanceArtifact) {
+    emit('accept', props.acceptanceArtifact)
+    return
+  }
+  if (!selection.value || !verified.value) {
+    toast.warning('请先校验当前选择的插件包')
+    return
+  }
+  emit('install', selection.value)
+}
+
+function githubRepository() {
+  return normalizePluginRepository(githubForm.repository)
+}
+
+async function queryRelease() {
+  if (busy.value || authenticationIncomplete.value)
+    return
+  const repository = githubRepository()
+  const tag = githubForm.tag.trim()
+  if (!/^[-\w.]+\/[-\w.]+$/.test(repository)) {
+    toast.warning('请输入 GitHub 仓库链接或 owner/repo')
+    return
+  }
+  if (githubForm.allowPrerelease && !tag) {
+    toast.warning('查询预发行版需要明确填写 tag')
+    return
+  }
+  submitting.value = true
+  try {
+    if (!await prepareSource() || !await prepareAuthentication())
+      return
+    queriedGithubKey.value = githubQueryKey()
+    emit('query', {
+      query: {
+        repository,
+        tag: tag || null,
+        allowPrerelease: githubForm.allowPrerelease,
+      },
+      credentialIds: [...githubForm.credentialIds],
+      outboundProxyId: githubForm.outboundProxyId || null,
+    })
+  }
+  finally {
+    submitting.value = false
+  }
+}
+
+function githubQueryKey() {
+  return JSON.stringify({
+    repository: githubRepository().toLowerCase(),
+    tag: githubForm.tag.trim(),
+    allowPrerelease: githubForm.allowPrerelease,
+    credentialIds: [...githubForm.credentialIds].sort(),
+    outboundProxyId: githubForm.outboundProxyId || null,
+  })
+}
+
+function formatFileSize(bytes: number) {
+  if (bytes < 1024)
+    return `${bytes} B`
+  if (bytes < 1024 * 1024)
+    return `${(bytes / 1024).toFixed(1)} KiB`
+  return `${(bytes / 1024 / 1024).toFixed(1)} MiB`
+}
+
+watch(open, (isOpen) => {
+  if (isOpen) {
+    reset()
+  }
+  else {
+    rememberDraft()
+    credentialDraft.value = null
+  }
+})
+watch(() => props.mode, () => {
+  pendingAuthentication.value = false
+  credentialDraft.value = null
+})
+watch([pendingAuthentication, credentialDraft], () => {
+  emit('resetVerification')
+  if (props.mode === 'github') {
+    queriedGithubKey.value = ''
+    emit('resetQuery')
+  }
+})
+watch(
+  () => githubQueryKey(),
+  (key) => {
+    if (!queriedGithubKey.value || key === queriedGithubKey.value)
+      return
+    queriedGithubKey.value = ''
+    emit('resetQuery')
+  },
+)
+watch(
+  () => props.release,
+  async (release) => {
+    // 唯一归档可直接解析，多个归档交给用户选择，平台兼容性仍由包检查器确认。
+    githubForm.asset = release && assetOptions.value.length === 1 ? assetOptions.value[0]!.value : ''
+    if (githubForm.asset) {
+      await nextTick()
+      await verifySelected()
+    }
+  },
+)
+</script>
+
+<template>
+  <BaseModal
+    v-model="open"
+    :title="updateSource ? '更新插件' : '安装插件'"
+    :description="acceptanceArtifact ? '确认访问权限后安装' : updateSource ? '检查设置兼容性后切换版本' : '支持本地插件包、URL 与 GitHub'"
+    size="md"
+    :dismissible="!busy"
+  >
+    <BaseSegmented
+      v-if="!acceptanceArtifact && !verified"
+      :model-value="mode"
+      :options="modeOptions"
+      :disabled="busy"
+      label="安装方式"
+      class="mb-5 w-full"
+      @update:model-value="changeMode"
+    />
+    <BaseForm v-if="!verified && mode === 'upload'">
+      <BaseFormItem label="插件包" required>
+        <!-- 原生文件输入放在样式化上传区内，保留键盘与读屏语义。 -->
+        <!-- eslint-disable-next-line vue-a11y/label-has-for -->
+        <label
+          class="flex cursor-pointer items-center gap-3 rounded-cp bg-cp-fill-alter p-4 outline-none transition-colors hover:bg-cp-fill-tertiary focus-within:ring-2 focus-within:ring-cp-control-outline"
+        >
+          <FileArchive class="size-5 shrink-0 text-cp-text-secondary" aria-hidden="true" />
+          <span class="grid min-w-0 flex-1 gap-1">
+            <span class="truncate text-cp-sm font-emphasis text-cp-text">{{ uploadFile?.name ?? '选择插件包' }}</span>
+            <span class="text-cp-xs text-cp-text-secondary">{{ uploadFile ? formatFileSize(uploadFile.size) : 'tar.gz / tgz，最大 32 MiB' }}</span>
+          </span>
+          <span class="shrink-0 text-cp-xs text-cp-primary-text">{{ uploadFile ? '更换' : '浏览文件' }}</span>
+          <input
+            type="file"
+            accept=".tar.gz,.tgz,application/gzip,application/x-gzip"
+            class="sr-only"
+            :disabled="busy"
+            aria-label="选择插件包"
+            @change="chooseFile"
+          >
+        </label>
+      </BaseFormItem>
+    </BaseForm>
+
+    <BaseForm v-else-if="!verified && mode === 'url'" class="grid gap-4">
+      <BaseFormItem label="下载 URL" required>
+        <template #label-extra>
+          <PluginHelpPopover label="下载地址说明">
+            仅支持 HTTPS，本机回环地址可使用 HTTP
+          </PluginHelpPopover>
+        </template>
+        <BaseInput v-model="urlForm.url" :disabled="busy" aria-label="下载 URL" placeholder="https://downloads.example.org/plugin.tar.gz" />
+      </BaseFormItem>
+    </BaseForm>
+
+    <BaseForm v-else-if="!verified" class="grid gap-4">
+      <BaseFormItem label="GitHub 仓库" required>
+        <BaseInput v-model="githubForm.repository" :disabled="busy" aria-label="GitHub 仓库" placeholder="仓库链接或 owner/repo">
+          <template #prefix>
+            <Github class="size-4" />
+          </template>
+        </BaseInput>
+      </BaseFormItem>
+      <BaseFormItem label="版本标签">
+        <template #label-extra>
+          <PluginHelpPopover label="版本标签说明">
+            留空查询最新稳定版，查询预发行版时必须指定标签
+          </PluginHelpPopover>
+        </template>
+        <BaseInput v-model="githubForm.tag" :disabled="busy" aria-label="版本标签" placeholder="留空查最新稳定版" />
+      </BaseFormItem>
+      <BaseCheckbox v-model="githubForm.allowPrerelease" label="允许查询预发行版" show-label :disabled="busy" />
+    </BaseForm>
+
+    <div v-if="!verified && mode !== 'upload'" class="mt-4 grid gap-4">
+      <PluginDownloadAuthentication
+        v-if="open"
+        :key="mode"
+        v-model="connectionForm.credentialIds"
+        v-model:pending="pendingAuthentication"
+        v-model:draft="credentialDraft"
+        :kind="mode"
+        :location="mode === 'github' ? githubForm.repository : urlForm.url"
+        :credentials="credentials"
+        :disabled="busy"
+        @delete-credential="$emit('deleteCredential', $event)"
+      />
+      <div class="grid items-end gap-4 sm:grid-cols-2">
+        <BaseFormItem label="校验摘要">
+          <template #label-extra>
+            <PluginHelpPopover label="校验摘要说明">
+              可选，填写发布者提供的 64 位 SHA-256 十六进制摘要，用于核对下载内容
+            </PluginHelpPopover>
+          </template>
+          <BaseInput v-model="connectionForm.sha256" :disabled="busy" :aria-invalid="Boolean(digestError)" maxlength="64" aria-label="SHA-256 校验摘要" placeholder="可选，SHA-256" class="font-mono [&_input::placeholder]:font-normal" />
+        </BaseFormItem>
+        <PluginSourceProxyField v-model="connectionForm.outboundProxyId" :disabled="busy" />
+      </div>
+    </div>
+
+    <section v-if="!verified && mode === 'github' && release" class="mt-4 grid gap-3">
+      <div class="flex min-w-0 flex-wrap items-center gap-2">
+        <strong class="min-w-0 wrap-break-word text-cp text-cp-text">{{ release.name || release.tag }}</strong>
+        <BaseTag type="primary">
+          {{ release.tag }}
+        </BaseTag>
+        <BaseTag v-if="release.prerelease" type="warning">
+          预发行版
+        </BaseTag>
+      </div>
+      <BaseFormItem v-if="assetOptions.length > 1" label="插件包" required>
+        <BaseSelect v-model="githubForm.asset" :options="assetOptions" :disabled="busy" placeholder="选择插件包" class="w-full" />
+      </BaseFormItem>
+      <p v-else class="m-0 break-all text-cp-sm text-cp-text-secondary">
+        {{ githubForm.asset || '此版本没有 tar.gz 或 tgz 插件包' }}
+      </p>
+    </section>
+
+    <section v-if="verified" aria-label="待安装插件" class="rounded-cp bg-cp-fill-alter p-4">
+      <div class="flex items-start gap-3">
+        <div class="flex size-10 shrink-0 items-center justify-center rounded-cp bg-cp-bg-container text-cp-text-secondary">
+          <PackageOpen class="size-5" aria-hidden="true" />
+        </div>
+        <div class="min-w-0 flex-1">
+          <div class="flex flex-wrap items-center gap-x-2 gap-y-1">
+            <h3 class="m-0 min-w-0 break-words text-cp-sm font-emphasis text-cp-text">
+              {{ verified.metadata.displayName }}
+            </h3>
+            <BaseTag>{{ verified.metadata.version }}</BaseTag>
+            <span role="status" class="ml-auto inline-flex shrink-0 items-center gap-1 text-cp-xs text-cp-success-text">
+              <CheckCircle2 class="size-3.5" aria-hidden="true" />
+              解析完成
+            </span>
+          </div>
+          <p class="mt-1 mb-0 break-all font-mono text-cp-xs text-cp-text-secondary" :title="`SHA-256 ${verified.metadata.sha256}`">
+            {{ verified.metadata.pluginId }}
+          </p>
+        </div>
+      </div>
+      <dl class="mt-3 mb-0 grid grid-cols-[auto_minmax(0,1fr)] items-center gap-x-4 gap-y-2 text-cp-xs leading-relaxed">
+        <dt class="text-cp-text-secondary">
+          发布者
+        </dt>
+        <dd class="m-0 min-w-0 break-words">
+          {{ verified.metadata.publisher }}
+        </dd>
+        <dt class="text-cp-text-secondary">
+          适用平台
+        </dt>
+        <dd class="m-0 flex min-w-0 flex-wrap gap-1.5">
+          <BaseTag v-for="platform in verified.metadata.platforms" :key="platform" size="sm">
+            {{ platform }}
+          </BaseTag>
+        </dd>
+      </dl>
+      <div class="mt-4 grid gap-3">
+        <p v-if="previousArtifact" class="m-0 text-cp-sm font-emphasis">
+          {{ addedPermissions.length ? '新增访问权限' : '没有新增访问权限' }}
+        </p>
+        <PluginPermissionSummary v-if="!previousArtifact || addedPermissions.length" :permissions="addedPermissions" />
+        <details v-if="previousArtifact && verified.metadata.permissionDescriptions.length" class="text-cp-xs text-cp-text-secondary">
+          <summary class="cursor-pointer py-1 outline-none focus-visible:ring-2 focus-visible:ring-cp-control-outline">
+            全部访问权限
+          </summary>
+          <PluginPermissionSummary class="mt-3" :permissions="verified.metadata.permissionDescriptions" />
+        </details>
+      </div>
+      <p class="mt-4 mb-0 text-cp-xs leading-relaxed text-cp-text-secondary">
+        安装即授权，插件以网关身份运行，请仅安装可信来源
+      </p>
+      <div v-if="previousArtifact" class="mt-2 flex items-center gap-1.5 text-cp-xs text-cp-text-secondary">
+        <span>安装后确认切换到新版本</span>
+        <PluginHelpPopover label="安装新版本说明">
+          沿用设置并补充新版本默认值，需要调整时会打开设置，已使用版本保留恢复设置
+        </PluginHelpPopover>
+      </div>
+    </section>
+
+    <template #footer>
+      <BaseButton v-if="verified && !acceptanceArtifact" variant="ghost" :disabled="busy" class="mr-auto" @click="$emit('resetVerification')">
+        返回
+      </BaseButton>
+      <BaseButton v-if="!verified && mode === 'github' && release" variant="secondary" :disabled="busy || authenticationIncomplete" :title="`缓存至 ${formatDateTime(release.expiresAt)}`" @click="queryRelease">
+        重新查询
+      </BaseButton>
+      <BaseButton variant="secondary" :disabled="busy" @click="open = false">
+        取消
+      </BaseButton>
+      <BaseButton v-if="mode === 'github' && !release" variant="primary" :loading="submitting || querying" :disabled="busy || authenticationIncomplete || !githubForm.repository.trim()" @click="queryRelease">
+        {{ querying ? '正在查询版本' : sourceChanged ? '保存来源并继续' : '下一步' }}
+      </BaseButton>
+      <BaseButton
+        v-else-if="!verified"
+        variant="primary"
+        :loading="submitting || verifying"
+        :disabled="!selection || busy || authenticationIncomplete"
+        @click="verifySelected"
+      >
+        {{ verifying ? '正在解析插件包' : sourceChanged ? '保存来源并继续' : '下一步' }}
+      </BaseButton>
+      <BaseButton v-if="verified" variant="primary" :loading="saving" :disabled="busy || pendingAuthentication" @click="installSelected">
+        <template #icon>
+          <Download class="size-4" />
+        </template>
+        {{ installationLabel }}
+      </BaseButton>
+    </template>
+  </BaseModal>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginLegacyConfigurations.vue b/frontend/src/views/plugins/components/PluginLegacyConfigurations.vue
new file mode 100644
index 000000000..22bd90343
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginLegacyConfigurations.vue
@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import type { PluginArtifact, PluginInstance } from '@/api'
+import { BaseIconButton, BaseTag } from '@codex-proxy/ui'
+import { Play, Power, Settings2, Trash2 } from '@lucide/vue'
+import { configurationStatus, PLUGIN_STATUS_LABELS, pluginStatusType } from '../utils/catalog'
+import { artifactForInstance } from '../utils/model'
+
+defineProps<{ instances: PluginInstance[], artifacts: PluginArtifact[], busy: boolean }>()
+defineEmits<{
+  edit: [instance: PluginInstance]
+  enable: [instance: PluginInstance]
+  disable: [instance: PluginInstance]
+  delete: [instance: PluginInstance]
+}>()
+</script>
+
+<template>
+  <p v-if="instances.some(instance => instance.enabled)" role="status" class="m-0 text-cp-sm text-cp-warning-text">
+    检测到多套启用配置，请在历史配置中停用不再使用的一套
+  </p>
+  <details v-if="instances.length" :open="instances.some(instance => instance.enabled)">
+    <summary class="cursor-pointer text-cp-sm text-cp-text-secondary">
+      历史配置 · {{ instances.length }}
+    </summary>
+    <p class="text-cp-xs text-cp-text-secondary">
+      保留已有设置和数据，使用历史配置会替换当前启用配置
+    </p>
+    <div v-for="instance in instances" :key="instance.id" class="mt-2 flex flex-wrap items-center gap-2 rounded-cp bg-cp-fill-alter p-3">
+      <span class="min-w-0 flex-1 wrap-anywhere text-cp-sm">{{ instance.name }}</span>
+      <BaseTag size="sm">
+        {{ artifactForInstance(instance, artifacts)?.metadata.version }}
+      </BaseTag>
+      <BaseTag size="sm" :type="pluginStatusType(configurationStatus(instance))">
+        {{ PLUGIN_STATUS_LABELS[configurationStatus(instance)] }}
+      </BaseTag>
+      <div class="flex shrink-0 items-center gap-1">
+        <BaseIconButton label="设置" variant="secondary" size="sm" :disabled="busy" @click="$emit('edit', instance)">
+          <Settings2 class="size-4" />
+        </BaseIconButton>
+        <BaseIconButton v-if="instance.enabled" label="停用历史配置" variant="secondary" size="sm" :disabled="busy" @click="$emit('disable', instance)">
+          <Power class="size-4" />
+        </BaseIconButton>
+        <BaseIconButton v-else label="启动" size="sm" variant="secondary" :disabled="busy" @click="$emit('enable', instance)">
+          <Play class="size-4" />
+        </BaseIconButton>
+        <BaseIconButton v-if="!instance.enabled" label="删除历史配置" variant="secondary" size="sm" class="group" :disabled="busy" @click="$emit('delete', instance)">
+          <Trash2 class="size-4 text-cp-error-text group-disabled:text-cp-text-disabled" />
+        </BaseIconButton>
+      </div>
+    </div>
+  </details>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginManagement.vue b/frontend/src/views/plugins/components/PluginManagement.vue
new file mode 100644
index 000000000..e58873d5b
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginManagement.vue
@@ -0,0 +1,268 @@
+<script setup lang="ts">
+import { ArrowInDownSquareHalf } from '@boxicons/vue'
+import { BaseCheckbox, BaseConfirmModal, BaseIconButton, BasePageHeader, BaseScrollbar, BaseSegmented } from '@codex-proxy/ui'
+
+import { PackageOpen, PanelsTopLeft, RefreshCw } from '@lucide/vue'
+import { shallowRef } from 'vue'
+import { usePluginManagement } from '../composables/usePluginManagement'
+import PluginCatalogPanel from './PluginCatalogPanel.vue'
+import PluginConfigurationModal from './PluginConfigurationModal.vue'
+import PluginDetailModal from './PluginDetailModal.vue'
+import PluginEnableModal from './PluginEnableModal.vue'
+import PluginExtensionsPanel from './PluginExtensionsPanel.vue'
+import PluginHelpPopover from './PluginHelpPopover.vue'
+import PluginInstallModal from './PluginInstallModal.vue'
+import PluginRollbackModal from './PluginRollbackModal.vue'
+import PluginUpdateCheckModal from './PluginUpdateCheckModal.vue'
+
+const activeTab = shallowRef<'artifacts' | 'extensions'>('artifacts')
+const management = usePluginManagement()
+
+const tabOptions = [
+  { label: '已安装', value: 'artifacts', icon: PackageOpen },
+  { label: '扩展页', value: 'extensions', icon: PanelsTopLeft },
+]
+</script>
+
+<template>
+  <div class="flex h-[calc(100dvh-2rem)] min-h-0 w-full flex-none! flex-col gap-3 overflow-hidden min-[961px]:h-[calc(100dvh-3rem)]">
+    <BasePageHeader title="插件管理" description="管理插件、版本和扩展页面" />
+
+    <div class="flex shrink-0 items-start gap-3">
+      <BaseScrollbar horizontal :vertical="false" height="var(--cp-control-height)" class="min-w-0">
+        <BaseSegmented
+          v-model="activeTab"
+          :options="tabOptions"
+          label="插件管理分区"
+          class="w-44"
+        />
+      </BaseScrollbar>
+      <div class="flex shrink-0 items-center gap-1">
+        <BaseIconButton label="安装插件" variant="secondary" @click="management.openInstall('upload')">
+          <ArrowInDownSquareHalf pack="filled" class="size-5" />
+        </BaseIconButton>
+        <BaseIconButton label="刷新插件" variant="secondary" :loading="management.loading.value" @click="management.refresh()">
+          <template #loading>
+            <RefreshCw class="size-4.5 animate-spin motion-reduce:animate-none" />
+          </template>
+          <RefreshCw class="size-4.5" />
+        </BaseIconButton>
+      </div>
+    </div>
+
+    <div class="flex min-h-0 flex-1 flex-col gap-3">
+      <PluginCatalogPanel
+        v-if="activeTab === 'artifacts'"
+        class="min-h-0 flex-1"
+        :plugins="management.catalog.value"
+        :loading="management.loading.value"
+        @manage="management.openDetail($event.id)"
+      />
+      <PluginExtensionsPanel
+        v-else
+        class="min-h-0 flex-1"
+        :views="management.extensions.value"
+        :loading="management.loading.value"
+      />
+    </div>
+
+    <PluginDetailModal
+      v-model="management.showDetail.value"
+      :plugin="management.selectedPlugin.value"
+      :initial-section="management.detailSection.value"
+      :views="management.extensions.value"
+      :busy="management.savingInstance.value || management.uninstall.busy.value || Boolean(management.busyInstanceId.value || management.busyDigest.value)"
+      @accept="management.openAcceptance"
+      @edit="management.openEditInstance"
+      @enable="management.requestInstanceEnable"
+      @disable="management.requestInstanceDisable"
+      @delete-configuration="management.requestInstanceDelete"
+      @delete-version="management.requestArtifactDelete"
+      @rollback="management.openRollback"
+      @install-version="management.openVersionInstall"
+      @check-update="management.updateCheck.check"
+      @switch-version="management.requestVersionSwitch"
+      @uninstall="management.uninstall.request"
+    />
+
+    <PluginInstallModal
+      v-model="management.showInstall.value"
+      :mode="management.installMode.value"
+      :installed-artifacts="management.artifacts.value"
+      :acceptance-artifact="management.acceptanceArtifact.value"
+      :credentials="management.credentials.value"
+      :saving-credential="management.savingCredential.value"
+      :save-credential="management.saveCredential"
+      :release="management.release.value"
+      :update-source="management.updateSource.value"
+      :update-selection="management.updateSelection.value"
+      :save-source="management.saveInstallSource"
+      :saving="management.installing.value"
+      :querying="management.queryingRelease.value"
+      :verifying="management.verifyingArtifact.value"
+      :verified="management.verifiedArtifact.value"
+      @install="management.installArtifact"
+      @accept="management.acceptArtifact"
+      @query="management.queryRelease"
+      @verify="management.verifyArtifact"
+      @reset-verification="management.resetArtifactVerification"
+      @reset-query="management.resetReleaseQuery"
+      @change-mode="management.changeInstallMode"
+      @delete-credential="management.requestCredentialDelete"
+    />
+
+    <PluginUpdateCheckModal
+      v-model="management.updateCheck.open.value"
+      :plugin="management.updateCheck.plugin.value"
+      :result="management.updateCheck.result.value"
+      :checking="management.updateCheck.checking.value"
+      @install="management.updateCheck.open.value = false; management.openCheckedUpdate($event)"
+    />
+
+    <PluginConfigurationModal
+      v-model="management.showInstance.value"
+      :instance="management.editingInstance.value"
+      :artifact="management.configurationArtifact.value"
+      :draft="management.configurationDraft.value"
+      :error="management.configurationError.value"
+      :saving="management.savingInstance.value"
+      @save="management.saveInstance"
+    />
+
+    <BaseConfirmModal
+      v-model="management.showVersionSwitch.value"
+      title="切换插件版本"
+      description="切换前会检查目标版本设置，失败时保留当前版本"
+      confirm-text="确认切换"
+      :loading="Boolean(management.busyInstanceId.value)"
+      @confirm="management.confirmVersionSwitch"
+    >
+      <p class="m-0 text-cp-sm">
+        {{ management.pendingVersionSwitch.value?.artifact.metadata.displayName }}：
+        {{ management.pendingVersionSwitch.value?.currentVersion }} → {{ management.pendingVersionSwitch.value?.artifact.metadata.version }}
+      </p>
+    </BaseConfirmModal>
+
+    <PluginRollbackModal
+      v-model="management.showRollback.value"
+      :instance="management.rollbackInstance.value"
+      :plan="management.rollbackPlan.value"
+      :loading="management.loadingRollback.value"
+      :saving="Boolean(management.busyInstanceId.value)"
+      @confirm="management.confirmRollback"
+      @reload="management.openRollback"
+    />
+
+    <PluginEnableModal
+      v-model="management.showEnableConfirmation.value"
+      :request="management.pendingEnable.value?.request"
+      :metadata="management.pendingEnable.value?.artifact.metadata"
+      :replacements="management.pendingEnable.value?.replacements ?? []"
+      :saving="management.savingInstance.value"
+      @confirm="management.confirmInstanceEnable"
+    />
+
+    <BaseConfirmModal
+      v-model="management.showArtifactDelete.value"
+      title="删除插件版本"
+      description="使用中的版本不可删除，删除版本也会清除对应的恢复设置"
+      destructive
+      confirm-text="确认删除"
+      :loading="Boolean(management.busyDigest.value)"
+      @confirm="management.confirmArtifactDelete"
+    >
+      <div class="flex min-w-0 items-center gap-2 text-cp-sm font-normal">
+        <p class="m-0 min-w-0 wrap-anywhere">
+          删除 {{ management.pendingArtifact.value?.metadata.displayName }} {{ management.pendingArtifact.value?.metadata.version }}？
+        </p>
+        <PluginHelpPopover label="版本删除详情">
+          <p class="m-0">
+            被配置或运行中的调用引用时不能删除，不会自动停用其他配置
+          </p>
+          <p class="m-0">
+            只清理此版本独用的下载认证，删除最后一个版本时同时清理来源规则，共享认证与代理不受影响
+          </p>
+          <p class="m-0">
+            SHA-256
+          </p>
+          <p class="m-0 break-all font-mono">
+            {{ management.pendingArtifact.value?.metadata.sha256 }}
+          </p>
+        </PluginHelpPopover>
+      </div>
+      <p class="mt-3 mb-0 text-cp-xs font-normal text-cp-text-secondary">
+        同时清理独用下载认证，最后一版还会清理来源
+      </p>
+    </BaseConfirmModal>
+
+    <BaseConfirmModal
+      v-model="management.showInstanceDelete.value"
+      title="删除插件配置"
+      description="配置、密钥与私有数据将永久删除"
+      destructive
+      confirm-text="确认删除"
+      :loading="Boolean(management.busyInstanceId.value)"
+      @confirm="management.confirmInstanceDelete"
+    >
+      <div class="grid gap-3 text-cp-sm font-normal">
+        <p class="m-0 wrap-anywhere">
+          {{ management.pendingDeleteInstance.value?.name }}
+        </p>
+        <p class="m-0 text-cp-xs">
+          无法恢复，已安装版本与其他配置不受影响
+        </p>
+      </div>
+    </BaseConfirmModal>
+
+    <BaseConfirmModal
+      v-model="management.uninstall.open.value"
+      title="卸载插件"
+      description="删除全部版本、配置、密钥与私有数据"
+      destructive
+      confirm-text="确认卸载"
+      :loading="management.uninstall.busy.value"
+      :confirm-disabled="!management.uninstall.acknowledged.value"
+      @confirm="management.uninstall.confirm"
+    >
+      <div class="grid gap-3 text-cp-sm font-normal">
+        <p class="m-0 wrap-anywhere">
+          {{ management.uninstall.pending.value?.artifact.metadata.displayName }} · {{ management.uninstall.pending.value?.artifacts.length }} 个版本
+        </p>
+        <ul v-if="management.uninstall.pending.value?.configurations.length" class="m-0 max-h-40 space-y-1 overflow-y-auto pl-4">
+          <li v-for="instance in management.uninstall.pending.value.configurations" :key="instance.id" class="wrap-anywhere">
+            {{ instance.name }}
+          </li>
+        </ul>
+        <div class="flex items-center gap-1.5 text-cp-xs text-cp-text-secondary">
+          <span>同时清理来源与独用下载认证</span>
+          <PluginHelpPopover label="卸载清理说明">
+            <p class="m-0">
+              只清理被卸载版本使用且不再被其他版本引用的下载认证，不删除共享认证、代理或审计记录
+            </p>
+            <p class="m-0">
+              暂时不用可停用配置，无需卸载
+            </p>
+          </PluginHelpPopover>
+        </div>
+        <BaseCheckbox v-model="management.uninstall.acknowledged.value" label="确认永久删除，无法恢复" show-label :disabled="management.uninstall.busy.value" />
+        <p v-if="management.uninstall.progress.value" role="status" class="m-0 text-cp-xs text-cp-text-secondary">
+          {{ management.uninstall.progress.value }}
+        </p>
+      </div>
+    </BaseConfirmModal>
+
+    <BaseConfirmModal
+      v-model="management.showCredentialDelete.value"
+      title="删除下载认证"
+      description="仍被使用时不可删除，删除后无法恢复"
+      destructive
+      confirm-text="确认删除"
+      :loading="Boolean(management.busyDistributionId.value)"
+      @confirm="management.confirmCredentialDelete"
+    >
+      <p class="m-0 wrap-anywhere text-cp-sm font-normal">
+        {{ management.pendingCredential.value?.name }}
+      </p>
+    </BaseConfirmModal>
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginManagementFrame.vue b/frontend/src/views/plugins/components/PluginManagementFrame.vue
new file mode 100644
index 000000000..6e422d430
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginManagementFrame.vue
@@ -0,0 +1,776 @@
+<script setup lang="ts">
+import type { PluginManagementPage, PluginManagementRoute, PluginManagementView } from '@/api'
+
+import { BaseButton } from '@codex-proxy/ui'
+import { RotateCw } from '@lucide/vue'
+import { useEventListener, useResizeObserver } from '@vueuse/core'
+
+import { computed, nextTick, onMounted, onScopeDispose, shallowRef, useTemplateRef, watch } from 'vue'
+import {
+  callPluginManagementRoute,
+  callPluginModelResponses,
+  createPluginManagementCallbackTicket,
+  pluginManagementCallbackPath,
+} from '@/api'
+import { API_BASE_URL } from '@/api/constants'
+import { ApiError } from '@/api/request'
+import { useThemeStore } from '@/stores/modules/theme'
+import { errorMessage } from '@/utils/async'
+import {
+  assemblePluginManagementPage,
+  MAXIMUM_MANAGEMENT_BODY_BYTES,
+  MAXIMUM_MANAGEMENT_IN_FLIGHT,
+  MAXIMUM_MANAGEMENT_QUERY_BYTES,
+  MAXIMUM_MODEL_BODY_BYTES,
+  MAXIMUM_MODEL_CHUNK_BYTES,
+  MAXIMUM_MODEL_IN_FLIGHT,
+  MODEL_REQUEST_DEADLINE_MS,
+  MODEL_RESPONSE_IDLE_MS,
+  PLUGIN_MANAGEMENT_BRIDGE,
+  PLUGIN_MANAGEMENT_BRIDGE_VERSION,
+  readPluginFrameTheme,
+} from '../management/frame'
+import PluginPageLoading from './PluginPageLoading.vue'
+
+interface BridgeMessage {
+  target: string
+  version: number
+  channel: string
+  session: string
+  type: string
+  id: number
+  payload?: unknown
+}
+
+interface FrameSession {
+  channel: string
+  session: string
+  controller: AbortController
+  view: PluginManagementView
+  page: PluginManagementPage
+  revoke: () => void
+  inFlight: number
+  requestIds: Set<number>
+  modelRequests: Map<number, ModelRequest>
+  loaded: boolean
+}
+
+interface ModelRequest {
+  id: number
+  source: Window
+  controller: AbortController
+  reader?: ReadableStreamDefaultReader<Uint8Array>
+  buffered?: Uint8Array
+  bufferedOffset: number
+  reading: boolean
+  nextPullId: number
+  activePullId?: number
+  totalTimer?: ReturnType<typeof setTimeout>
+  idleTimer?: ReturnType<typeof setTimeout>
+}
+
+const props = defineProps<{
+  view: PluginManagementView
+  page: PluginManagementPage
+}>()
+
+const emit = defineEmits<{
+  stale: []
+}>()
+
+const SAFE_MODEL_RESPONSE_HEADERS = new Set([
+  'content-type',
+  'openai-processing-ms',
+  'openai-request-id',
+  'request-id',
+  'retry-after',
+  'x-client-request-id',
+  'x-gateway-request-id',
+  'x-oai-request-id',
+  'x-openai-request-id',
+  'x-processing-ms',
+  'x-request-id',
+  'x-ratelimit-limit-requests',
+  'x-ratelimit-limit-tokens',
+  'x-ratelimit-remaining-requests',
+  'x-ratelimit-remaining-tokens',
+  'x-ratelimit-reset-requests',
+  'x-ratelimit-reset-tokens',
+])
+
+const themeStore = useThemeStore()
+const containerRef = useTemplateRef<HTMLDivElement>('container')
+const iframeRef = useTemplateRef<HTMLIFrameElement>('iframe')
+const srcdoc = shallowRef('')
+const loading = shallowRef(false)
+const loadError = shallowRef('')
+const contentHeight = shallowRef(0)
+const viewportHeight = shallowRef(0)
+const frameReady = computed(() => contentHeight.value > 0)
+let session: FrameSession | undefined
+let loadSequence = 0
+let previousViewportHeight = -1
+
+function disposeSession() {
+  const current = session
+  session = undefined
+  srcdoc.value = ''
+  contentHeight.value = 0
+  previousViewportHeight = -1
+  if (!current)
+    return
+  current.controller.abort()
+  for (const request of current.modelRequests.values())
+    terminateModelRequest(current, request)
+  current.revoke()
+}
+
+async function loadPage() {
+  const sequence = ++loadSequence
+  disposeSession()
+  loading.value = true
+  loadError.value = ''
+  const controller = new AbortController()
+  const channel = crypto.randomUUID()
+  const sessionId = crypto.randomUUID()
+  try {
+    await nextTick()
+    if (sequence !== loadSequence)
+      return
+    pushLayout()
+    const assembled = await assemblePluginManagementPage(
+      props.view,
+      props.page,
+      channel,
+      sessionId,
+      window.location.origin,
+      readPluginFrameTheme(),
+      viewportHeight.value,
+      controller.signal,
+    )
+    if (sequence !== loadSequence || controller.signal.aborted) {
+      assembled.revoke()
+      return
+    }
+    session = {
+      channel,
+      session: sessionId,
+      controller,
+      view: props.view,
+      page: props.page,
+      revoke: assembled.revoke,
+      inFlight: 0,
+      requestIds: new Set(),
+      modelRequests: new Map(),
+      loaded: false,
+    }
+    srcdoc.value = assembled.srcdoc
+  }
+  catch (error) {
+    if (sequence === loadSequence && !controller.signal.aborted) {
+      if (error instanceof ApiError && error.status === 409) {
+        loadError.value = '插件页面版本已变更，正在刷新'
+        emit('stale')
+      }
+      else {
+        loadError.value = errorMessage(error)
+      }
+    }
+  }
+  finally {
+    if (sequence === loadSequence)
+      loading.value = false
+  }
+}
+
+function handleFrameLoad() {
+  const current = session
+  if (!current)
+    return
+  if (!current.loaded) {
+    current.loaded = true
+    pushLayout()
+    return
+  }
+  loadError.value = '插件页面尝试离开已隔离的管理文档，已停止加载'
+  disposeSession()
+}
+
+function isBridgeMessage(value: unknown): value is BridgeMessage {
+  if (!value || typeof value !== 'object')
+    return false
+  const message = value as Record<string, unknown>
+  return message.target === PLUGIN_MANAGEMENT_BRIDGE
+    && message.version === PLUGIN_MANAGEMENT_BRIDGE_VERSION
+    && typeof message.channel === 'string'
+    && typeof message.session === 'string'
+    && typeof message.type === 'string'
+    && Number.isSafeInteger(message.id)
+    && Number(message.id) > 0
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value))
+}
+
+function postResult(
+  current: FrameSession,
+  source: Window,
+  id: number,
+  ok: boolean,
+  payload?: unknown,
+  error?: string,
+  transfer: Transferable[] = [],
+) {
+  if (session !== current || iframeRef.value?.contentWindow !== source)
+    return
+  source.postMessage({
+    target: PLUGIN_MANAGEMENT_BRIDGE,
+    version: PLUGIN_MANAGEMENT_BRIDGE_VERSION,
+    channel: current.channel,
+    session: current.session,
+    type: 'result',
+    id,
+    ok,
+    payload,
+    error,
+  }, '*', transfer)
+}
+
+function routeForMessage(view: PluginManagementView, payload: Record<string, unknown>) {
+  const method = typeof payload.method === 'string' ? payload.method.toUpperCase() : ''
+  const path = typeof payload.path === 'string' ? payload.path : ''
+  return view.routes.find(route => route.method === method && route.path === path)
+}
+
+function validateRoutePayload(route: PluginManagementRoute, payload: Record<string, unknown>) {
+  const query = payload.query
+  const contentType = payload.contentType
+  const body = payload.body
+  if (typeof query !== 'string' || query.startsWith('?') || query.includes('#') || hasControlCharacter(query))
+    throw new Error('查询参数无效')
+  if (new TextEncoder().encode(query).byteLength > MAXIMUM_MANAGEMENT_QUERY_BYTES)
+    throw new Error('查询参数超过 8 KiB')
+  if (!(body instanceof ArrayBuffer) || body.byteLength > MAXIMUM_MANAGEMENT_BODY_BYTES)
+    throw new Error('请求正文无效或超过 1 MiB')
+  if ((route.method === 'GET' || route.method === 'HEAD') && body.byteLength > 0)
+    throw new Error(`${route.method} 路由不接受请求正文`)
+  if (contentType !== undefined && typeof contentType !== 'string')
+    throw new Error('Content-Type 无效')
+  if (typeof contentType === 'string' && !route.requestContentTypes.includes(contentType))
+    throw new Error('Content-Type 未在插件路由中注册')
+  if (body.byteLength > 0 && typeof contentType !== 'string')
+    throw new Error('包含正文的请求必须声明 Content-Type')
+  return {
+    query,
+    contentType: typeof contentType === 'string' ? contentType : undefined,
+    body,
+  }
+}
+
+function hasControlCharacter(value: string) {
+  return [...value].some((character) => {
+    const code = character.codePointAt(0) ?? 0
+    return code < 0x20 || code === 0x7F
+  })
+}
+
+async function handleRouteRequest(
+  current: FrameSession,
+  source: Window,
+  message: BridgeMessage,
+) {
+  if (!isRecord(message.payload))
+    throw new Error('请求参数无效')
+  const route = routeForMessage(current.view, message.payload)
+  if (!route)
+    throw new Error('请求未在当前插件版本中注册')
+  const payload = validateRoutePayload(route, message.payload)
+  const response = await callPluginManagementRoute(current.view.target, {
+    method: route.method,
+    path: route.path,
+    query: payload.query,
+    contentType: payload.contentType,
+    body: payload.body,
+  }, { signal: current.controller.signal, silent: true })
+  const body = response.body
+  postResult(current, source, message.id, true, {
+    status: response.status,
+    contentType: response.contentType,
+    body,
+  }, undefined, [body])
+}
+
+async function handleCallbackTicket(
+  current: FrameSession,
+  source: Window,
+  message: BridgeMessage,
+) {
+  if (!isRecord(message.payload))
+    throw new Error('回调票据参数无效')
+  const path = typeof message.payload.path === 'string' ? message.payload.path : ''
+  const ttlSeconds = message.payload.ttlSeconds
+  if (!current.view.callbacks.some(callback => callback.path === path))
+    throw new Error('回调路径未在当前插件版本中注册')
+  if (!Number.isSafeInteger(ttlSeconds) || Number(ttlSeconds) < 1 || Number(ttlSeconds) > 600)
+    throw new Error('回调票据有效期必须为 1 到 600 秒')
+  const ticket = await createPluginManagementCallbackTicket(current.view.target, {
+    path,
+    ttlSeconds: Number(ttlSeconds),
+  }, { signal: current.controller.signal, silent: true })
+  const callbackPath = `${API_BASE_URL}${pluginManagementCallbackPath(current.view.target, path, ticket.state)}`
+  postResult(current, source, message.id, true, {
+    state: ticket.state,
+    expiresAtMs: ticket.expiresAtMs,
+    callbackUrl: new URL(callbackPath, window.location.origin).toString(),
+  })
+}
+
+function postModelMessage(
+  current: FrameSession,
+  source: Window,
+  type: 'models-response' | 'models-chunk' | 'models-complete' | 'models-error',
+  id: number,
+  payload?: unknown,
+  error?: string,
+  transfer: Transferable[] = [],
+) {
+  if (session !== current || iframeRef.value?.contentWindow !== source)
+    return
+  source.postMessage({
+    target: PLUGIN_MANAGEMENT_BRIDGE,
+    version: PLUGIN_MANAGEMENT_BRIDGE_VERSION,
+    channel: current.channel,
+    session: current.session,
+    type,
+    id,
+    payload,
+    error,
+  }, '*', transfer)
+}
+
+function validateModelRequestPayload(payload: unknown) {
+  if (!isRecord(payload))
+    throw new Error('模型请求参数无效')
+  const clientKeyId = payload.clientKeyId
+  const body = payload.body
+  if (
+    typeof clientKeyId !== 'string'
+    || !clientKeyId
+    || clientKeyId !== clientKeyId.trim()
+    || clientKeyId.length > 128
+    || hasControlCharacter(clientKeyId)
+  ) {
+    throw new Error('clientKeyId 无效')
+  }
+  if (typeof body !== 'string' || new TextEncoder().encode(body).byteLength > MAXIMUM_MODEL_BODY_BYTES)
+    throw new Error('Responses 请求正文无效或超过 8 MiB')
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(body)
+  }
+  catch {
+    throw new Error('Responses 请求正文不是有效 JSON')
+  }
+  if (!isRecord(parsed))
+    throw new Error('Responses 请求正文必须是 JSON 对象')
+  return { clientKeyId, body }
+}
+
+function modelResponseHeaders(response: Response) {
+  const headers: [string, string][] = []
+  let total = 0
+  for (const [rawName, value] of response.headers) {
+    const name = rawName.toLowerCase()
+    const nextTotal = total + name.length + value.length
+    if (
+      !SAFE_MODEL_RESPONSE_HEADERS.has(name)
+      || value.length > 8192
+      || nextTotal > 32768
+      || hasControlCharacter(value.replaceAll('\t', ''))
+    ) {
+      continue
+    }
+    headers.push([name, value])
+    total = nextTotal
+  }
+  return headers
+}
+
+function supportedModelResponse(response: Response) {
+  if (!response.body)
+    return true
+  const contentType = response.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase()
+  return contentType === 'application/json'
+    || contentType === 'text/event-stream'
+    || Boolean(contentType?.endsWith('+json'))
+}
+
+function detachModelRequest(current: FrameSession, request: ModelRequest) {
+  if (current.modelRequests.get(request.id) !== request)
+    return false
+  current.modelRequests.delete(request.id)
+  clearTimeout(request.totalTimer)
+  clearTimeout(request.idleTimer)
+  request.totalTimer = undefined
+  request.idleTimer = undefined
+  return true
+}
+
+function cancelModelReader(request: ModelRequest) {
+  const reader = request.reader
+  if (!reader)
+    return
+  void reader.cancel()
+    .finally(() => {
+      try {
+        reader.releaseLock()
+      }
+      catch {
+        // 取消中的 read 会自行释放；会话清理不能因此产生未处理拒绝。
+      }
+    })
+    .catch(() => undefined)
+}
+
+function terminateModelRequest(current: FrameSession, request: ModelRequest, error?: string) {
+  if (!detachModelRequest(current, request))
+    return
+  request.controller.abort()
+  cancelModelReader(request)
+  if (error)
+    postModelMessage(current, request.source, 'models-error', request.id, undefined, error)
+}
+
+function completeModelRequest(current: FrameSession, request: ModelRequest, pullId: number) {
+  if (!detachModelRequest(current, request))
+    return
+  try {
+    request.reader?.releaseLock()
+  }
+  catch {
+    // EOF 已确定，锁清理失败不应阻断结束标记。
+  }
+  postModelMessage(current, request.source, 'models-complete', request.id, { pullId })
+}
+
+function armModelIdleTimeout(current: FrameSession, request: ModelRequest) {
+  clearTimeout(request.idleTimer)
+  request.idleTimer = setTimeout(() => {
+    terminateModelRequest(current, request, '页面 30 秒未继续读取模型响应')
+  }, MODEL_RESPONSE_IDLE_MS)
+}
+
+async function handleModelRequest(current: FrameSession, source: Window, message: BridgeMessage) {
+  if (current.modelRequests.size >= MAXIMUM_MODEL_IN_FLIGHT) {
+    postModelMessage(current, source, 'models-error', message.id, undefined, '模型请求已达并发上限')
+    return
+  }
+  if (current.requestIds.has(message.id) || current.modelRequests.has(message.id)) {
+    postModelMessage(current, source, 'models-error', message.id, undefined, '模型请求序号重复')
+    return
+  }
+
+  let payload: ReturnType<typeof validateModelRequestPayload>
+  try {
+    payload = validateModelRequestPayload(message.payload)
+  }
+  catch (error) {
+    postModelMessage(current, source, 'models-error', message.id, undefined, errorMessage(error))
+    return
+  }
+
+  const request: ModelRequest = {
+    id: message.id,
+    source,
+    controller: new AbortController(),
+    bufferedOffset: 0,
+    reading: false,
+    nextPullId: 1,
+  }
+  current.modelRequests.set(message.id, request)
+  request.totalTimer = setTimeout(() => {
+    terminateModelRequest(current, request, '模型请求超过 10 分钟')
+  }, MODEL_REQUEST_DEADLINE_MS)
+
+  try {
+    const response = await callPluginModelResponses(
+      current.view.target,
+      payload.clientKeyId,
+      payload.body,
+      request.controller.signal,
+    )
+    if (current.modelRequests.get(request.id) !== request)
+      return
+    if (!supportedModelResponse(response))
+      throw new Error('模型接口返回了不受支持的内容类型')
+
+    const hasBody = response.body !== null
+    if (response.body)
+      request.reader = response.body.getReader()
+    const statusText = response.statusText.length <= 256 && !hasControlCharacter(response.statusText)
+      ? response.statusText
+      : ''
+    postModelMessage(current, source, 'models-response', message.id, {
+      status: response.status,
+      statusText,
+      headers: modelResponseHeaders(response),
+      hasBody,
+    })
+    if (!hasBody) {
+      detachModelRequest(current, request)
+      return
+    }
+    armModelIdleTimeout(current, request)
+  }
+  catch (error) {
+    if (current.modelRequests.get(request.id) === request)
+      terminateModelRequest(current, request, errorMessage(error, '模型请求失败'))
+  }
+}
+
+async function handleModelPull(current: FrameSession, source: Window, message: BridgeMessage) {
+  const request = current.modelRequests.get(message.id)
+  if (!request || request.source !== source)
+    return
+  const pullId = isRecord(message.payload) ? message.payload.pullId : undefined
+  if (!Number.isSafeInteger(pullId) || Number(pullId) < 1) {
+    terminateModelRequest(current, request, '模型响应拉取序号无效')
+    return
+  }
+  if (request.reading) {
+    if (request.activePullId !== pullId)
+      terminateModelRequest(current, request, '模型响应拉取发生重入')
+    return
+  }
+  if (pullId !== request.nextPullId) {
+    terminateModelRequest(current, request, '模型响应拉取序号已失效')
+    return
+  }
+  clearTimeout(request.idleTimer)
+  request.idleTimer = undefined
+  request.reading = true
+  request.activePullId = Number(pullId)
+  try {
+    while (current.modelRequests.get(message.id) === request) {
+      if (!request.buffered || request.bufferedOffset >= request.buffered.byteLength) {
+        request.buffered = undefined
+        request.bufferedOffset = 0
+        const result = await request.reader?.read()
+        if (current.modelRequests.get(message.id) !== request)
+          return
+        if (!result || result.done) {
+          completeModelRequest(current, request, Number(pullId))
+          return
+        }
+        if (result.value.byteLength === 0)
+          continue
+        request.buffered = result.value
+      }
+
+      const end = Math.min(request.bufferedOffset + MAXIMUM_MODEL_CHUNK_BYTES, request.buffered.byteLength)
+      const chunk = request.buffered.slice(request.bufferedOffset, end)
+      request.bufferedOffset = end
+      if (request.bufferedOffset >= request.buffered.byteLength) {
+        request.buffered = undefined
+        request.bufferedOffset = 0
+      }
+      const body = chunk.buffer
+      request.nextPullId += 1
+      postModelMessage(current, source, 'models-chunk', message.id, { pullId, body }, undefined, [body])
+      armModelIdleTimeout(current, request)
+      return
+    }
+  }
+  catch (error) {
+    if (current.modelRequests.get(message.id) === request)
+      terminateModelRequest(current, request, errorMessage(error, '模型响应读取失败'))
+  }
+  finally {
+    request.reading = false
+    request.activePullId = undefined
+  }
+}
+
+async function handleBridgeMessage(event: MessageEvent) {
+  const current = session
+  const source = event.source
+  if (
+    !current
+    || source !== iframeRef.value?.contentWindow
+    || event.origin !== 'null'
+    || !isBridgeMessage(event.data)
+    || event.data.channel !== current.channel
+    || event.data.session !== current.session
+  ) {
+    return
+  }
+  const frame = source as Window
+  if (event.data.type === 'resize') {
+    const height = isRecord(event.data.payload) ? event.data.payload.height : undefined
+    if (typeof height === 'number' && Number.isSafeInteger(height) && height > 0 && height <= 1_000_000)
+      contentHeight.value = height
+    return
+  }
+  if (event.data.type === 'models-request') {
+    void handleModelRequest(current, frame, event.data)
+    return
+  }
+  if (event.data.type === 'models-pull') {
+    void handleModelPull(current, frame, event.data)
+    return
+  }
+  if (event.data.type === 'models-cancel') {
+    const request = current.modelRequests.get(event.data.id)
+    if (request?.source === frame)
+      terminateModelRequest(current, request)
+    return
+  }
+  if (!['request', 'callback-ticket'].includes(event.data.type))
+    return
+  if (current.requestIds.has(event.data.id) || current.modelRequests.has(event.data.id)) {
+    postResult(current, frame, event.data.id, false, undefined, '插件管理请求序号重复')
+    return
+  }
+  if (current.inFlight >= MAXIMUM_MANAGEMENT_IN_FLIGHT) {
+    postResult(current, frame, event.data.id, false, undefined, '插件管理请求已达并发上限')
+    return
+  }
+  current.inFlight += 1
+  current.requestIds.add(event.data.id)
+  try {
+    if (event.data.type === 'request')
+      await handleRouteRequest(current, frame, event.data)
+    else await handleCallbackTicket(current, frame, event.data)
+  }
+  catch (error) {
+    if (session !== current || current.controller.signal.aborted)
+      return
+    if (error instanceof ApiError && error.status === 409) {
+      loadError.value = '插件页面版本已变更，正在刷新'
+      emit('stale')
+      disposeSession()
+      return
+    }
+    postResult(current, frame, event.data.id, false, undefined, errorMessage(error))
+  }
+  finally {
+    current.requestIds.delete(event.data.id)
+    current.inFlight = Math.max(0, current.inFlight - 1)
+  }
+}
+
+function pushLayout() {
+  const container = containerRef.value
+  if (!container)
+    return
+
+  // 在 iframe 创建前预留可用空间，计算不依赖插件内容高度。
+  let top = container.getBoundingClientRect().top
+  let bottomPadding = 0
+  for (let parent = container.parentElement; parent; parent = parent.parentElement) {
+    top += parent.scrollTop
+    bottomPadding += Number.parseFloat(getComputedStyle(parent).paddingBottom) || 0
+  }
+  const height = Math.max(0, Math.floor(document.documentElement.clientHeight - top - bottomPadding))
+  viewportHeight.value = height
+  const current = session
+  const frame = iframeRef.value
+  if (!current?.loaded || !frame?.contentWindow)
+    return
+  if (height === previousViewportHeight)
+    return
+  previousViewportHeight = height
+  frame.contentWindow.postMessage({
+    target: PLUGIN_MANAGEMENT_BRIDGE,
+    version: PLUGIN_MANAGEMENT_BRIDGE_VERSION,
+    channel: current.channel,
+    session: current.session,
+    type: 'layout',
+    payload: { viewportHeight: height },
+  }, '*')
+}
+
+async function pushTheme() {
+  await nextTick()
+  const current = session
+  const target = iframeRef.value?.contentWindow
+  if (!current || !target)
+    return
+  target.postMessage({
+    target: PLUGIN_MANAGEMENT_BRIDGE,
+    version: PLUGIN_MANAGEMENT_BRIDGE_VERSION,
+    channel: current.channel,
+    session: current.session,
+    type: 'theme',
+    payload: readPluginFrameTheme(),
+  }, '*')
+  pushLayout()
+}
+
+useResizeObserver(containerRef, pushLayout)
+useEventListener('resize', pushLayout)
+
+watch(
+  [
+    () => props.view.target.instanceId,
+    () => props.view.target.artifactSha256,
+    () => props.view.target.revision,
+    () => props.page.id,
+  ],
+  () => void loadPage(),
+  { immediate: true },
+)
+watch(
+  () => [themeStore.effectiveTheme, themeStore.themeRevision],
+  () => void pushTheme(),
+)
+
+onMounted(() => {
+  window.addEventListener('message', handleBridgeMessage)
+  pushLayout()
+})
+onScopeDispose(() => {
+  loadSequence += 1
+  window.removeEventListener('message', handleBridgeMessage)
+  disposeSession()
+})
+</script>
+
+<template>
+  <div ref="container" class="relative isolate flex min-w-0 w-full" :style="{ minHeight: `${viewportHeight}px` }" :aria-busy="loading || (!frameReady && !loadError)">
+    <div v-if="!loadError && (loading || !frameReady)" class="absolute inset-0 z-10 flex bg-cp-bg-layout">
+      <PluginPageLoading />
+    </div>
+    <div v-if="loadError" class="grid min-h-0 flex-1 place-items-center p-6 text-center">
+      <div class="grid max-w-md justify-items-center gap-3">
+        <p class="m-0 text-cp font-heavy text-cp-text">
+          插件页面无法加载
+        </p>
+        <p class="m-0 text-xs leading-relaxed text-cp-text-secondary">
+          {{ loadError }}
+        </p>
+        <BaseButton size="sm" variant="secondary" @click="loadPage">
+          <template #icon>
+            <RotateCw class="size-3.5" />
+          </template>
+          重试
+        </BaseButton>
+      </div>
+    </div>
+    <iframe
+      v-else-if="srcdoc"
+      ref="iframe"
+      :key="session?.channel"
+      :srcdoc="srcdoc"
+      :title="`${view.name}：${page.title}`"
+      class="block w-full border-0 bg-transparent"
+      :style="{ height: `${Math.max(viewportHeight, contentHeight)}px` }"
+      :inert="!frameReady"
+      :aria-hidden="!frameReady"
+      sandbox="allow-scripts"
+      referrerpolicy="no-referrer"
+      @load="handleFrameLoad"
+    />
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginPage.vue b/frontend/src/views/plugins/components/PluginPage.vue
new file mode 100644
index 000000000..fce84bc95
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginPage.vue
@@ -0,0 +1,126 @@
+<script setup lang="ts">
+import { BaseButton, BaseEmpty, BaseIconButton, BasePageHeader, BaseSegmented } from '@codex-proxy/ui'
+import { Blocks, CircleAlert, RefreshCw } from '@lucide/vue'
+import { storeToRefs } from 'pinia'
+import { computed, onMounted, shallowRef } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { usePluginManagementViewsStore } from '@/stores/modules/plugin-management-views'
+import { pluginPageLocation } from '../utils/navigation'
+import PluginManagementFrame from './PluginManagementFrame.vue'
+import PluginPageLoading from './PluginPageLoading.vue'
+
+const route = useRoute()
+const router = useRouter()
+const directory = usePluginManagementViewsStore()
+const { pageViews, loading, loaded, loadError } = storeToRefs(directory)
+const frameReload = shallowRef(0)
+
+const instanceId = computed(() => routeParam(route.params.instanceId))
+const pageId = computed(() => routeParam(route.params.pageId))
+const view = computed(() => pageViews.value.find(item => item.target.instanceId === instanceId.value) ?? null)
+const page = computed(() => view.value?.pages.find(item => item.id === pageId.value) ?? null)
+const pageOptions = computed(() => view.value?.pages.map(item => ({
+  label: item.title,
+  value: item.id,
+})) ?? [])
+const selectedPageId = computed({
+  get: () => pageId.value,
+  set: (nextPageId: string) => {
+    const currentView = view.value
+    const nextPage = currentView?.pages.find(item => item.id === nextPageId)
+    if (currentView && nextPage)
+      void router.push(pluginPageLocation(currentView, nextPage))
+  },
+})
+const frameKey = computed(() => {
+  const currentView = view.value
+  const currentPage = page.value
+  if (!currentView || !currentPage)
+    return ''
+  const target = currentView.target
+  return [target.instanceId, target.artifactSha256, target.revision, currentPage.id, frameReload.value].join(':')
+})
+
+function routeParam(value: string | string[] | undefined) {
+  return Array.isArray(value) ? (value[0] ?? '') : (value ?? '')
+}
+
+async function refreshDirectory() {
+  try {
+    await directory.refresh()
+    frameReload.value += 1
+  }
+  catch {
+    // Store 保留可展示的错误；旧目录继续留在页面上，避免把暂时失败误判为撤销。
+  }
+}
+
+onMounted(() => {
+  void directory.ensureLoaded().catch(() => undefined)
+})
+</script>
+
+<template>
+  <div class="flex min-w-0 w-full flex-col gap-5">
+    <BasePageHeader
+      :title="page?.title ?? '插件页面'"
+      :description="page?.description || (view ? `使用插件提供的功能，当前配置为「${view.name}」` : '加载已启用插件的管理页面')"
+    >
+      <template #actions>
+        <BaseIconButton label="刷新页面" variant="secondary" :loading="loading" @click="refreshDirectory">
+          <template #loading>
+            <RefreshCw class="size-4 animate-spin motion-reduce:animate-none" />
+          </template>
+          <RefreshCw class="size-4" />
+        </BaseIconButton>
+      </template>
+    </BasePageHeader>
+
+    <PluginPageLoading v-if="loading && !loaded" />
+
+    <BaseEmpty
+      v-else-if="!view || !page"
+      class="min-h-0 flex-1 content-center"
+      :icon="Blocks"
+      title="插件页面不可用"
+      :description="loadError || '该配置或页面未发布，可能已停用或切换版本'"
+    >
+      <template #action>
+        <BaseButton variant="secondary" @click="router.push('/plugins')">
+          返回插件管理
+        </BaseButton>
+      </template>
+    </BaseEmpty>
+
+    <div
+      v-else-if="loadError"
+      class="flex shrink-0 flex-wrap items-center gap-2 rounded-cp bg-cp-warning-container px-4 py-3 text-cp-warning-on-container"
+      role="alert"
+    >
+      <CircleAlert class="size-4 shrink-0" />
+      <p class="m-0 min-w-0 flex-1 text-cp-sm font-semibold">
+        页面目录刷新失败，当前显示上次成功加载的版本：{{ loadError }}
+      </p>
+      <BaseButton size="sm" variant="secondary" :loading="loading" @click="refreshDirectory">
+        重试
+      </BaseButton>
+    </div>
+
+    <section v-if="view && page" class="flex min-w-0 flex-col gap-4">
+      <BaseSegmented
+        v-if="view.pages.length > 1"
+        v-model="selectedPageId"
+        class="w-max max-w-full shrink-0 overflow-x-auto"
+        :options="pageOptions"
+        label="插件页面"
+        size="sm"
+      />
+      <PluginManagementFrame
+        :key="frameKey"
+        :view="view"
+        :page="page"
+        @stale="refreshDirectory"
+      />
+    </section>
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginPageLoading.vue b/frontend/src/views/plugins/components/PluginPageLoading.vue
new file mode 100644
index 000000000..a8fd564cc
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginPageLoading.vue
@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { Box } from '@lucide/vue'
+import { usePreferredReducedMotion } from '@vueuse/core'
+import { gsap } from 'gsap'
+import { onMounted, onScopeDispose, useTemplateRef, watch } from 'vue'
+
+const icon = useTemplateRef<HTMLElement>('icon')
+const preferredMotion = usePreferredReducedMotion()
+let motion: gsap.core.Tween | undefined
+
+function animate() {
+  motion?.kill()
+  if (!icon.value)
+    return
+  gsap.set(icon.value, { y: 0 })
+  if (preferredMotion.value !== 'reduce')
+    motion = gsap.to(icon.value, { y: -5, duration: 0.8, repeat: -1, yoyo: true, ease: 'power1.inOut' })
+}
+
+onMounted(animate)
+watch(preferredMotion, animate)
+onScopeDispose(() => motion?.kill())
+</script>
+
+<template>
+  <div class="grid min-h-0 flex-1 place-items-center px-6 py-8" role="status" aria-label="正在加载页面">
+    <span ref="icon" class="inline-flex size-16 items-center justify-center text-cp-text-secondary" aria-hidden="true">
+      <Box :size="40" :stroke-width="1.5" />
+    </span>
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginPermissionSummary.vue b/frontend/src/views/plugins/components/PluginPermissionSummary.vue
new file mode 100644
index 000000000..cde1467a7
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginPermissionSummary.vue
@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import type { PluginPermissionDescription } from '@/api'
+import { Globe2, KeyRound, MessagesSquare, Network, ScanLine, Shield } from '@lucide/vue'
+
+defineProps<{ permissions: PluginPermissionDescription[] }>()
+
+const icons = {
+  network: Globe2,
+  models: MessagesSquare,
+  accounts: KeyRound,
+  requests: ScanLine,
+  public_endpoints: Network,
+} as const
+
+function permissionIcon(permission: string) {
+  return icons[permission as keyof typeof icons] ?? Shield
+}
+</script>
+
+<template>
+  <dl v-if="permissions.length" class="m-0 grid gap-3">
+    <div v-for="permission in permissions" :key="permission.permission" class="grid grid-cols-[1rem_minmax(0,1fr)] gap-x-2.5 gap-y-1">
+      <component :is="permissionIcon(permission.permission)" class="mt-0.5 size-4 text-cp-text-secondary" aria-hidden="true" />
+      <dt class="text-cp-sm font-emphasis text-cp-text">
+        {{ permission.label }}
+      </dt>
+      <dd class="col-start-2 m-0 text-cp-xs leading-relaxed text-cp-text-secondary">
+        {{ permission.description }}
+      </dd>
+    </div>
+  </dl>
+  <p v-else class="m-0 text-cp-sm text-cp-text-secondary">
+    未声明额外的宿主访问权限
+  </p>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginResourcePicker.vue b/frontend/src/views/plugins/components/PluginResourcePicker.vue
new file mode 100644
index 000000000..d06ce5e8d
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginResourcePicker.vue
@@ -0,0 +1,168 @@
+<script setup lang="ts">
+import { BaseButton, BaseCheckbox, BaseInput, BasePopover, BaseScrollbar, toast } from '@codex-proxy/ui'
+import { ChevronDown } from '@lucide/vue'
+import { useElementSize, useEventListener } from '@vueuse/core'
+import { computed, nextTick, onScopeDispose, shallowRef, useId, useTemplateRef, watch } from 'vue'
+import { getAccountGroups, getApiKeys } from '@/api'
+import { errorMessage } from '@/utils/async'
+
+const props = defineProps<{ kind: 'keys' | 'groups', disabled?: boolean, single?: boolean }>()
+const selected = defineModel<string[]>({ required: true })
+const options = shallowRef<{ id: string, label: string, disabled: boolean }[]>([])
+const loading = shallowRef(false)
+const error = shallowRef('')
+const search = shallowRef('')
+const open = shallowRef(false)
+const trigger = useTemplateRef<HTMLButtonElement>('trigger')
+const { width: triggerWidth } = useElementSize(trigger, undefined, { box: 'border-box' })
+const panel = useTemplateRef<HTMLDivElement>('panel')
+const panelId = useId()
+const label = computed(() => props.kind === 'keys' ? '客户端 Key' : '账号分组')
+let controller: AbortController | undefined
+const choices = computed(() => {
+  const known = new Set(options.value.map(option => option.id))
+  return [...selected.value.filter(id => !known.has(id)).map(id => ({ id, label: `不可用 · ${id}`, disabled: true })), ...options.value]
+})
+const displayed = computed(() => choices.value.filter(option => option.label.toLocaleLowerCase().includes(search.value.toLocaleLowerCase())))
+const selectionLabel = computed(() => {
+  if (selected.value.length)
+    return choices.value.find(option => option.id === selected.value[0])?.label ?? selected.value[0]
+  if (loading.value)
+    return '正在加载…'
+  if (error.value)
+    return '加载失败'
+  return options.value.length ? '不限' : `暂无${label.value}`
+})
+async function load() {
+  controller?.abort()
+  const current = new AbortController()
+  controller = current
+  loading.value = true
+  error.value = ''
+  const items: typeof options.value = []
+  try {
+    const requestOptions = { signal: current.signal, silent: true }
+    if (props.kind === 'keys') {
+      let cursor: string | undefined
+      do {
+        const result = await getApiKeys({ limit: 200, cursor }, requestOptions)
+        items.push(...result.items.map(item => ({ id: item.id, label: `${item.name} · ${item.prefix}`, disabled: !item.enabled })))
+        cursor = result.nextCursor ?? undefined
+      } while (cursor)
+    }
+    else {
+      let page = 1
+      let totalPages = 1
+      do {
+        const result = await getAccountGroups({ page, pageSize: 100 }, requestOptions)
+        items.push(...result.items.map(item => ({ id: item.id, label: item.name, disabled: !item.enabled })))
+        totalPages = result.page.totalPages
+        page++
+      } while (page <= totalPages)
+    }
+    if (controller === current)
+      options.value = items
+  }
+  catch (cause) {
+    if (!current.signal.aborted) {
+      error.value = errorMessage(cause)
+      // 同一弹窗可能挂载多个范围选择器，只显示一份相同错误。
+      if (!toast.messages.some(message => message.type === 'error' && message.message === error.value))
+        toast.error(error.value)
+    }
+  }
+  finally {
+    if (controller === current)
+      loading.value = false
+  }
+}
+function toggle(id: string, checked: boolean) {
+  selected.value = checked ? (props.single ? [id] : [...selected.value, id]) : selected.value.filter(value => value !== id)
+}
+function handleKeydown(event: KeyboardEvent) {
+  if (event.key !== 'Escape' || !open.value)
+    return
+  event.preventDefault()
+  event.stopPropagation()
+  open.value = false
+  trigger.value?.focus()
+}
+useEventListener(panel, 'keydown', handleKeydown)
+watch(open, async (value) => {
+  if (!value)
+    return
+  search.value = ''
+  await nextTick()
+  if (open.value)
+    (panel.value?.querySelector<HTMLElement>('input:not(:disabled), button:not(:disabled)') ?? panel.value)?.focus()
+})
+watch(() => props.disabled, (value) => {
+  if (value)
+    open.value = false
+})
+watch(() => props.kind, load, { immediate: true })
+onScopeDispose(() => controller?.abort())
+</script>
+
+<template>
+  <div class="grid min-w-0 gap-2">
+    <BasePopover v-model="open" placement="bottom-start" :disabled="disabled" class="w-full min-w-0">
+      <template #trigger>
+        <button
+          ref="trigger"
+          type="button"
+          :disabled="disabled"
+          :aria-label="`${label}：${selectionLabel}${selected.length > 1 ? `，共 ${selected.length} 项` : ''}`"
+          aria-haspopup="dialog"
+          :aria-expanded="open"
+          :aria-controls="open ? panelId : undefined"
+          class="flex h-cp-control w-full min-w-0 items-center gap-2 rounded-cp border-0 px-3.5 text-left text-cp shadow-cp-input outline-none transition-[background-color,box-shadow] duration-160 motion-reduce:transition-none"
+          :class="disabled
+            ? 'cursor-not-allowed bg-cp-bg-container-disabled text-cp-text-disabled shadow-none'
+            : open
+              ? 'cursor-pointer bg-(--cp-input-active-bg) text-cp-text shadow-cp-input-active'
+              : 'cursor-pointer bg-(--cp-input-bg) text-cp-text hover:bg-(--cp-input-hover-bg) hover:shadow-cp-input-hover focus-visible:bg-(--cp-input-active-bg) focus-visible:shadow-cp-input-active'"
+          @keydown="handleKeydown"
+        >
+          <span class="min-w-0 flex-1 truncate" :class="selected.length ? 'font-emphasis' : 'text-cp-text-quaternary'">{{ selectionLabel }}</span>
+          <span v-if="selected.length > 1" class="shrink-0 text-cp-xs text-cp-text-secondary">+{{ selected.length - 1 }}</span>
+          <ChevronDown class="size-4 shrink-0 text-cp-text-quaternary" :class="{ 'rotate-180': open }" />
+        </button>
+      </template>
+      <div :id="panelId" ref="panel" role="dialog" :aria-label="`选择${label}`" tabindex="-1" :style="{ width: `${triggerWidth}px` }" class="max-w-[calc(100vw-2rem)] p-2 outline-none">
+        <BaseInput v-if="choices.length > 6" v-model="search" :disabled="disabled" size="sm" :aria-label="`搜索${label}`" placeholder="输入名称筛选" class="mb-2" />
+        <p v-if="loading" role="status" class="m-0 p-3 text-cp-xs text-cp-text-secondary">
+          正在加载…
+        </p>
+        <div v-else-if="error" class="flex items-center gap-2 p-2 text-cp-xs text-cp-error-text">
+          加载失败
+          <BaseButton size="sm" variant="secondary" :disabled="disabled" @click="load">
+            重试
+          </BaseButton>
+        </div>
+        <BaseScrollbar v-else max-height="min(15rem, 50dvh)">
+          <div class="grid gap-1">
+            <BaseCheckbox
+              v-for="option in displayed"
+              :key="option.id"
+              :model-value="selected.includes(option.id)"
+              :label="`${option.label}${option.disabled ? '（不可用）' : ''}`"
+              show-label
+              :disabled="disabled || (option.disabled && !selected.includes(option.id))"
+              class="min-w-0 rounded-cp px-3 py-2.5"
+              :class="selected.includes(option.id) ? 'bg-cp-primary-container' : 'hover:bg-cp-fill-quaternary'"
+              @update:model-value="toggle(option.id, $event)"
+            >
+              <template #label>
+                <span class="block truncate" :title="option.label">{{ option.label }}{{ option.disabled ? '（不可用）' : '' }}</span>
+              </template>
+            </BaseCheckbox>
+            <p v-if="!displayed.length" class="m-0 p-3 text-cp-xs text-cp-text-secondary">
+              {{ choices.length ? '没有匹配项' : `暂无${label}，请先在${kind === 'keys' ? 'API 密钥' : '分组管理'}中创建` }}
+            </p>
+          </div>
+        </BaseScrollbar>
+      </div>
+    </BasePopover>
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginRollbackModal.vue b/frontend/src/views/plugins/components/PluginRollbackModal.vue
new file mode 100644
index 000000000..de67d2df1
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginRollbackModal.vue
@@ -0,0 +1,80 @@
+<script setup lang="ts">
+import type { PluginInstance, PluginRollbackPlan } from '@/api'
+
+import { BaseButton, BaseForm, BaseFormItem, BaseModal, BaseSelect } from '@codex-proxy/ui'
+
+import { computed, shallowRef, watch } from 'vue'
+import { shortDigest } from '../utils/model'
+import PluginHelpPopover from './PluginHelpPopover.vue'
+
+const props = defineProps<{
+  instance: PluginInstance | null
+  plan: PluginRollbackPlan | null
+  loading: boolean
+  saving: boolean
+}>()
+
+defineEmits<{
+  confirm: [artifactSha256: string]
+  reload: [instance: PluginInstance]
+}>()
+
+const open = defineModel<boolean>({ required: true })
+const selected = shallowRef('')
+const options = computed(() => (props.plan?.targets ?? []).map(target => ({
+  value: target.artifactSha256,
+  label: `${target.version} · ${target.platforms.join(', ')}`,
+  description: shortDigest(target.artifactSha256),
+})))
+const canConfirm = computed(() => !props.loading && options.value.some(option => option.value === selected.value))
+
+watch(() => props.plan, () => {
+  selected.value = props.plan?.targets[0]?.artifactSha256 ?? ''
+})
+</script>
+
+<template>
+  <BaseModal v-model="open" title="回退插件版本" description="恢复对应版本的设置，保持当前启停状态" size="md" :dismissible="!saving">
+    <BaseForm class="grid gap-4">
+      <BaseFormItem label="当前版本">
+        <p class="m-0 break-all text-cp-sm text-cp-text">
+          {{ instance?.name }} <span v-if="plan" class="font-mono">· {{ plan.currentVersion }}</span>
+        </p>
+      </BaseFormItem>
+      <BaseFormItem v-if="loading || options.length" label="目标版本" required>
+        <template #label-extra>
+          <PluginHelpPopover label="回退说明">
+            <p class="m-0">
+              恢复目标版本上次启用时的参数和密钥，私有数据仍须通过兼容检查
+            </p>
+            <p v-if="selected" class="m-0 break-all font-mono">
+              SHA-256 {{ selected }}
+            </p>
+          </PluginHelpPopover>
+        </template>
+        <BaseSelect
+          v-model="selected"
+          class="w-full"
+          :options="options"
+          :disabled="loading || saving"
+          :placeholder="loading ? '正在加载旧版' : '请选择回退目标'"
+          aria-label="回退目标版本"
+        />
+      </BaseFormItem>
+      <p v-else-if="plan" role="status" class="m-0 text-cp-sm text-cp-text-secondary">
+        没有保留恢复设置的旧版，其他版本可在“版本”中切换
+      </p>
+    </BaseForm>
+    <template #footer>
+      <BaseButton v-if="instance" variant="secondary" :disabled="saving" :loading="loading" @click="$emit('reload', instance)">
+        重新加载
+      </BaseButton>
+      <BaseButton variant="secondary" :disabled="saving" @click="open = false">
+        取消
+      </BaseButton>
+      <BaseButton variant="primary" :disabled="!canConfirm" :loading="saving" @click="$emit('confirm', selected)">
+        确认回退
+      </BaseButton>
+    </template>
+  </BaseModal>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginScopeInput.vue b/frontend/src/views/plugins/components/PluginScopeInput.vue
new file mode 100644
index 000000000..cd7e1c00c
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginScopeInput.vue
@@ -0,0 +1,37 @@
+<script setup lang="ts">
+import { BaseFormItem, BaseTextarea } from '@codex-proxy/ui'
+
+import { computed } from 'vue'
+
+withDefaults(defineProps<{
+  label: string
+  description?: string
+  placeholder?: string
+  disabled?: boolean
+}>(), {
+  description: undefined,
+  placeholder: '每行一项',
+  disabled: false,
+})
+
+const values = defineModel<string[]>({ required: true })
+const text = computed({
+  get: () => values.value.join('\n'),
+  set: (value) => {
+    values.value = [...new Set(value.split(/[\n,]/).map(item => item.trim()).filter(Boolean))]
+  },
+})
+</script>
+
+<template>
+  <BaseFormItem :label="label" :description="description">
+    <BaseTextarea
+      v-model="text"
+      :rows="2"
+      :disabled="disabled"
+      :placeholder="placeholder"
+      :aria-label="label"
+      class="font-mono"
+    />
+  </BaseFormItem>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginSourceProxyField.vue b/frontend/src/views/plugins/components/PluginSourceProxyField.vue
new file mode 100644
index 000000000..7d3c18b06
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginSourceProxyField.vue
@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import { BaseFormItem, BaseSelect } from '@codex-proxy/ui'
+
+import { computed } from 'vue'
+import { useProxyCatalog } from '@/composables/useProxyCatalog'
+
+defineProps<{ disabled?: boolean }>()
+
+const proxyId = defineModel<string>({ required: true })
+const { proxies, loading } = useProxyCatalog()
+const options = computed(() => [
+  { label: '不使用代理（直连）', value: '' },
+  ...proxies.value.map(proxy => ({
+    label: proxy.name,
+    value: proxy.id,
+    description: proxy.endpoint,
+  })),
+  // 目录加载失败或代理已被删除时保留已选 ID，不能静默改为直连。
+  ...(proxyId.value && !proxies.value.some(proxy => proxy.id === proxyId.value)
+    ? [{ label: '已选代理（目录暂不可用）', value: proxyId.value, description: proxyId.value, disabled: true }]
+    : []),
+])
+</script>
+
+<template>
+  <BaseFormItem label="下载代理">
+    <BaseSelect
+      v-model="proxyId"
+      :options="options"
+      :disabled="disabled || loading"
+      class="w-full"
+      aria-label="下载代理"
+    />
+  </BaseFormItem>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginUpdateCheckModal.vue b/frontend/src/views/plugins/components/PluginUpdateCheckModal.vue
new file mode 100644
index 000000000..70bf4e243
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginUpdateCheckModal.vue
@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import type { PluginUpdateSelection } from '../composables/usePluginUpdateCheck'
+import type { InstalledPlugin } from '../utils/catalog'
+import { BaseButton, BaseModal, BaseTag } from '@codex-proxy/ui'
+import { LoaderCircle } from '@lucide/vue'
+import { computed } from 'vue'
+import PluginHelpPopover from './PluginHelpPopover.vue'
+
+const props = defineProps<{ plugin: InstalledPlugin | null, result: PluginUpdateSelection | null, checking: boolean }>()
+defineEmits<{ install: [selection: PluginUpdateSelection] }>()
+const open = defineModel<boolean>({ required: true })
+const installed = computed(() => props.plugin?.artifacts.some(artifact => artifact.acceptedAt && (props.result?.artifact
+  ? artifact.metadata.sha256 === props.result.artifact.metadata.sha256
+  : props.result?.release && artifact.source.kind === 'github' && artifact.source.repository === props.result.release.repository && artifact.source.tag === props.result.release.tag)))
+const canInstall = computed(() => props.result?.artifact || props.result?.release?.assets.some(asset => /\.(?:tar\.gz|tgz)$/i.test(asset.name)))
+</script>
+
+<template>
+  <BaseModal v-model="open" title="检查更新" description="仅查询来源，不安装或切换版本" size="md">
+    <div v-if="checking" role="status" class="flex items-center gap-2 py-4 text-cp-sm text-cp-text-secondary">
+      <LoaderCircle class="size-4 animate-spin motion-reduce:animate-none" />
+      {{ plugin?.source?.source.kind === 'url' ? '正在下载并解析插件包' : '正在查询发布版本' }}
+    </div>
+    <div v-else-if="result" class="grid gap-3 text-cp-sm">
+      <div class="flex flex-wrap items-center gap-2">
+        <span class="min-w-0 flex-1 break-words">{{ plugin?.artifact.metadata.displayName }}</span>
+        <BaseTag type="primary">
+          {{ result.artifact?.metadata.version ?? result.release?.tag }}
+        </BaseTag>
+        <BaseTag v-if="result.release?.prerelease" type="warning">
+          预发行版
+        </BaseTag>
+      </div>
+      <div class="flex items-center gap-1.5 text-cp-xs text-cp-text-secondary">
+        <span>{{ installed ? result.artifact ? '此版本已安装' : '此发布已有已安装版本' : result.artifact ? '发现未安装版本' : '发现未安装发布' }}</span>
+        <PluginHelpPopover label="更新检查说明">
+          GitHub 查询发布标签，标签不等于包内版本，继续安装时仍需校验插件包，URL 按包内版本和摘要比对，本地上传不支持检查更新
+        </PluginHelpPopover>
+      </div>
+      <span v-if="!canInstall" class="text-cp-xs text-cp-text-secondary">此发布没有 tar.gz 或 tgz 插件包</span>
+    </div>
+    <template #footer>
+      <BaseButton variant="secondary" @click="open = false">
+        {{ checking ? '取消' : '关闭' }}
+      </BaseButton>
+      <BaseButton v-if="result && canInstall" variant="primary" @click="$emit('install', result)">
+        {{ installed ? '查看安装选项' : '继续安装' }}
+      </BaseButton>
+    </template>
+  </BaseModal>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginVersionCard.vue b/frontend/src/views/plugins/components/PluginVersionCard.vue
new file mode 100644
index 000000000..8b1172eb2
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginVersionCard.vue
@@ -0,0 +1,101 @@
+<script setup lang="ts">
+import type { PluginArtifact, PluginInstance } from '@/api'
+import { BaseIconButton, BaseTag } from '@codex-proxy/ui'
+import { ArrowDownToLine, ChevronDown, CircleAlert, Play, Trash2 } from '@lucide/vue'
+import { computed, shallowRef, useId } from 'vue'
+import { configurationStatus, PLUGIN_STATUS_LABELS, pluginStatusType } from '../utils/catalog'
+import { shortDigest, sourceDetail, sourceLabel } from '../utils/model'
+
+const props = defineProps<{
+  artifact: PluginArtifact
+  current?: PluginInstance
+  configurations: PluginInstance[]
+  busy: boolean
+}>()
+defineEmits<{
+  switchVersion: [artifact: PluginArtifact]
+  deleteVersion: [artifact: PluginArtifact]
+  accept: [artifact: PluginArtifact]
+}>()
+const isCurrent = computed(() => props.current?.artifactSha256 === props.artifact.metadata.sha256)
+const uses = computed(() => props.configurations.filter(instance => instance.artifactSha256 === props.artifact.metadata.sha256))
+const detailsOpen = shallowRef(false)
+const detailsId = useId()
+</script>
+
+<template>
+  <article class="min-w-0 rounded-cp bg-cp-fill-alter" :class="isCurrent ? 'grid min-h-36 content-between gap-3 p-4' : 'flex flex-wrap items-center gap-2 px-3 py-2 sm:gap-3'">
+    <div v-if="isCurrent && current" class="flex flex-wrap items-center gap-2">
+      <strong class="min-w-0 flex-1 wrap-break-word text-cp-sm">当前版本</strong>
+      <BaseTag>{{ artifact.metadata.version }}</BaseTag>
+      <BaseTag :type="pluginStatusType(configurationStatus(current))">
+        <CircleAlert v-if="configurationStatus(current) === 'failed'" class="mr-1 size-3.5" />
+        {{ PLUGIN_STATUS_LABELS[configurationStatus(current)] }}
+      </BaseTag>
+    </div>
+    <div class="flex min-w-0 items-center justify-between gap-3" :class="isCurrent ? 'flex-wrap py-1' : 'flex-1'">
+      <div class="grid min-w-0 gap-1 sm:flex sm:flex-wrap sm:items-center sm:gap-x-3">
+        <strong v-if="!isCurrent" class="truncate text-cp-sm">{{ artifact.metadata.version }}</strong>
+        <span class="text-cp-xs text-cp-text-secondary">{{ sourceLabel(artifact.source) }}</span>
+        <span class="truncate font-mono text-cp-xs text-cp-text-quaternary">{{ shortDigest(artifact.metadata.sha256) }}</span>
+      </div>
+      <button
+        v-if="isCurrent"
+        type="button"
+        class="inline-flex shrink-0 cursor-pointer items-center gap-1 rounded-cp border-0 bg-transparent p-0 text-cp-xs text-cp-primary-text outline-none focus-visible:ring-2 focus-visible:ring-cp-control-outline"
+        :aria-expanded="detailsOpen"
+        :aria-controls="detailsId"
+        @click="detailsOpen = !detailsOpen"
+      >
+        版本详情
+        <ChevronDown class="size-3.5 transition-transform motion-reduce:transition-none" :class="detailsOpen ? 'rotate-180' : undefined" aria-hidden="true" />
+      </button>
+    </div>
+    <BaseTag v-if="!artifact.acceptedAt" type="warning" size="sm">
+      待安装
+    </BaseTag>
+    <BaseTag v-else-if="!isCurrent && uses.length" size="sm">
+      历史配置
+    </BaseTag>
+    <dl :id="detailsId" v-show="detailsOpen" class="m-0 grid min-w-0 grid-cols-1 gap-x-8 gap-y-4 text-cp-xs text-cp-text-secondary sm:grid-cols-2" :class="!isCurrent ? 'order-last w-full pt-2' : undefined">
+      <div class="grid min-w-0 content-start gap-1">
+        <dt class="text-cp-sm font-emphasis text-cp-text">
+          {{ sourceLabel(artifact.source) }}
+        </dt>
+        <dd class="m-0 break-all leading-relaxed">
+          {{ sourceDetail(artifact.source) }}
+        </dd>
+      </div>
+      <div v-if="uses.length" class="grid min-w-0 content-start gap-1">
+        <dt class="text-cp-sm font-emphasis text-cp-text">
+          引用配置
+        </dt>
+        <dd class="m-0 wrap-anywhere leading-relaxed">
+          {{ uses.map(instance => instance.name).join('、') }}
+        </dd>
+      </div>
+      <div class="grid min-w-0 content-start gap-1 sm:col-span-2">
+        <dt class="text-cp-sm font-emphasis text-cp-text">
+          SHA-256
+        </dt>
+        <dd class="m-0 break-all font-mono leading-relaxed">
+          {{ artifact.metadata.sha256 }}
+        </dd>
+      </div>
+    </dl>
+    <div class="flex shrink-0 items-center gap-1" :class="isCurrent ? 'justify-self-end' : undefined">
+      <BaseIconButton v-if="!isCurrent" :label="`${artifact.metadata.version} 版本详情`" variant="secondary" size="sm" :aria-expanded="detailsOpen" :aria-controls="detailsId" @click="detailsOpen = !detailsOpen">
+        <ChevronDown class="size-4 transition-transform motion-reduce:transition-none" :class="detailsOpen ? 'rotate-180' : undefined" />
+      </BaseIconButton>
+      <BaseIconButton v-if="!artifact.acceptedAt" :label="`安装 ${artifact.metadata.version}`" size="sm" variant="primary" :disabled="busy" @click="$emit('accept', artifact)">
+        <ArrowDownToLine class="size-4" />
+      </BaseIconButton>
+      <BaseIconButton v-else :label="`切换至 ${artifact.metadata.version}`" size="sm" variant="secondary" :disabled="busy || !current || isCurrent" @click="$emit('switchVersion', artifact)">
+        <Play class="size-4" />
+      </BaseIconButton>
+      <BaseIconButton v-if="artifact.acceptedAt" :label="`删除版本 ${artifact.metadata.version}`" size="sm" variant="secondary" class="group" :disabled="busy || uses.length > 0 || artifact.source.kind === 'builtin'" @click="$emit('deleteVersion', artifact)">
+        <Trash2 class="size-4 text-cp-error-text group-disabled:text-cp-text-disabled" />
+      </BaseIconButton>
+    </div>
+  </article>
+</template>
diff --git a/frontend/src/views/plugins/components/PluginVersionsPanel.vue b/frontend/src/views/plugins/components/PluginVersionsPanel.vue
new file mode 100644
index 000000000..acd539f33
--- /dev/null
+++ b/frontend/src/views/plugins/components/PluginVersionsPanel.vue
@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import type { InstalledPlugin } from '../utils/catalog'
+import type { PluginArtifact } from '@/api'
+import { computed } from 'vue'
+import { currentPluginInstance } from '../utils/catalog'
+import { artifactForInstance } from '../utils/model'
+import PluginVersionCard from './PluginVersionCard.vue'
+
+const props = defineProps<{ plugin: InstalledPlugin, busy: boolean }>()
+defineEmits<{
+  switchVersion: [artifact: PluginArtifact]
+  deleteVersion: [artifact: PluginArtifact]
+  accept: [artifact: PluginArtifact]
+}>()
+const current = computed(() => currentPluginInstance(props.plugin))
+const currentArtifact = computed(() => current.value && artifactForInstance(current.value, props.plugin.artifacts))
+const history = computed(() => props.plugin.artifacts.filter(artifact => artifact.metadata.sha256 !== currentArtifact.value?.metadata.sha256))
+</script>
+
+<template>
+  <div class="grid gap-5">
+    <PluginVersionCard
+      v-if="currentArtifact"
+      :artifact="currentArtifact"
+      :current="current"
+      :configurations="plugin.configurations"
+      :busy="busy"
+      @accept="$emit('accept', $event)"
+      @switch-version="$emit('switchVersion', $event)"
+      @delete-version="$emit('deleteVersion', $event)"
+    />
+    <details v-if="history.length" :open="!currentArtifact">
+      <summary class="cursor-pointer text-cp-sm text-cp-text-secondary">
+        {{ currentArtifact ? '历史版本' : '已安装版本' }} · {{ history.length }}
+      </summary>
+      <ul class="mt-4 mb-0 grid list-none gap-2 p-0" :aria-label="currentArtifact ? '历史版本' : '已安装版本'">
+        <li v-for="artifact in history" :key="artifact.metadata.sha256" class="min-w-0">
+          <PluginVersionCard
+            :artifact="artifact"
+            :current="current"
+            :configurations="plugin.configurations"
+            :busy="busy"
+            @accept="$emit('accept', $event)"
+            @switch-version="$emit('switchVersion', $event)"
+            @delete-version="$emit('deleteVersion', $event)"
+          />
+        </li>
+      </ul>
+    </details>
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/components/SourceCredentialPicker.vue b/frontend/src/views/plugins/components/SourceCredentialPicker.vue
new file mode 100644
index 000000000..050e9fde8
--- /dev/null
+++ b/frontend/src/views/plugins/components/SourceCredentialPicker.vue
@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import type { PluginSourceCredential } from '@/api'
+
+import { BaseCheckbox, BaseIconButton } from '@codex-proxy/ui'
+import { Trash2 } from '@lucide/vue'
+
+withDefaults(defineProps<{
+  credentials: PluginSourceCredential[]
+  disabled?: boolean
+}>(), {
+  disabled: false,
+})
+
+defineEmits<{ delete: [credential: PluginSourceCredential] }>()
+const selected = defineModel<string[]>({ required: true })
+function isSelected(id: string) {
+  return selected.value.includes(id)
+}
+
+function toggle(id: string, checked: boolean) {
+  selected.value = checked
+    ? [...selected.value, id]
+    : selected.value.filter(value => value !== id)
+}
+</script>
+
+<template>
+  <div class="grid gap-2">
+    <div
+      v-for="credential in credentials"
+      :key="credential.id"
+      class="flex min-w-0 items-center gap-3 rounded-cp bg-cp-fill-alter px-3 py-1.5"
+      :class="disabled ? 'opacity-60' : undefined"
+    >
+      <BaseCheckbox
+        :model-value="isSelected(credential.id)"
+        :disabled="disabled"
+        :label="`选择下载认证 ${credential.name}`"
+        @update:model-value="toggle(credential.id, $event)"
+      />
+      <span class="flex min-w-0 flex-1 items-center gap-3">
+        <strong class="max-w-[45%] shrink-0 truncate text-cp-sm text-cp-text" :title="credential.name">{{ credential.name }}</strong>
+        <span class="min-w-0 flex-1 truncate font-mono text-cp-xs text-cp-text-secondary" :title="`${credential.origin}${credential.pathPrefix}`">
+          {{ credential.origin }}{{ credential.pathPrefix }}
+        </span>
+      </span>
+      <BaseIconButton size="sm" :label="`删除下载认证 ${credential.name}`" :disabled="disabled" @click="$emit('delete', credential)">
+        <Trash2 class="size-3.5 text-cp-error" />
+      </BaseIconButton>
+    </div>
+  </div>
+</template>
diff --git a/frontend/src/views/plugins/composables/usePluginInstallation.ts b/frontend/src/views/plugins/composables/usePluginInstallation.ts
new file mode 100644
index 000000000..81f8231d2
--- /dev/null
+++ b/frontend/src/views/plugins/composables/usePluginInstallation.ts
@@ -0,0 +1,236 @@
+import type { Ref } from 'vue'
+import type { PluginInstallMode } from '../components/PluginInstallModal.vue'
+import type { InstalledPlugin } from '../utils/catalog'
+import type { PluginInstallSelection } from '../utils/model'
+import type { PluginUpdateSelection } from './usePluginUpdateCheck'
+import type { PluginArtifact, PluginArtifactMutationResponse, PluginRelease, PluginUpdateSourceBinding, QueryPluginReleaseRequest, VerifiedPluginArtifact } from '@/api'
+import { toast } from '@codex-proxy/ui'
+import { isEqual } from 'es-toolkit'
+import { onScopeDispose, shallowRef, watch } from 'vue'
+import { acceptPluginArtifact, getPluginUpdateSources, installRemotePlugin, queryPluginRelease, updatePluginSource, uploadPluginArtifact, verifyRemotePlugin, verifyUploadedPlugin } from '@/api'
+import { pluginInstallSelectionKey } from '../utils/model'
+
+interface InstallationContext {
+  runAction: <T>(flag: Ref<boolean>, title: string, task: () => Promise<T>) => Promise<T | undefined>
+  notifyError: (title: string, error: unknown) => void
+  onInstalled: (result: PluginArtifactMutationResponse) => Promise<void>
+  onSourceSaved: (source: PluginUpdateSourceBinding) => void
+}
+
+export function usePluginInstallation({ runAction, notifyError, onInstalled, onSourceSaved }: InstallationContext) {
+  const showInstall = shallowRef(false)
+  const installMode = shallowRef<PluginInstallMode>('upload')
+  const updateSource = shallowRef<PluginUpdateSourceBinding | null>(null)
+  const updateSelection = shallowRef<PluginUpdateSelection | null>(null)
+  const acceptanceArtifact = shallowRef<PluginArtifact | null>(null)
+  const release = shallowRef<PluginRelease | null>(null)
+  const installing = shallowRef(false)
+  const queryingRelease = shallowRef(false)
+  const verifyingArtifact = shallowRef(false)
+  const verifiedArtifact = shallowRef<{ requestKey: string | File, artifact: VerifiedPluginArtifact } | null>(null)
+
+  let releaseController: AbortController | undefined
+  let verificationController: AbortController | undefined
+
+  function openInstall(mode: PluginInstallMode) {
+    resetArtifactVerification()
+    resetReleaseQuery()
+    installMode.value = mode
+    updateSource.value = null
+    updateSelection.value = null
+    acceptanceArtifact.value = null
+    release.value = null
+    showInstall.value = true
+  }
+
+  function openAcceptance(artifact: PluginArtifact) {
+    resetArtifactVerification()
+    resetReleaseQuery()
+    updateSource.value = null
+    updateSelection.value = null
+    acceptanceArtifact.value = artifact
+    showInstall.value = true
+  }
+
+  function openVersionInstall(plugin: InstalledPlugin) {
+    const source = plugin.source
+    if (!source || source.source.kind === 'builtin') {
+      toast.warning('此插件没有可用的安装来源')
+      return
+    }
+    openInstall(source.source.kind)
+    updateSource.value = source
+  }
+
+  function changeInstallMode(mode: PluginInstallMode) {
+    resetArtifactVerification()
+    resetReleaseQuery()
+    installMode.value = mode
+  }
+
+  function openCheckedUpdate(selection: PluginUpdateSelection) {
+    const kind = selection.binding.source.kind
+    if (kind !== 'github' && kind !== 'url')
+      return
+    openInstall(kind)
+    updateSource.value = selection.binding
+    updateSelection.value = selection
+  }
+
+  async function saveInstallSource(source: PluginUpdateSourceBinding) {
+    const previous = updateSource.value
+    if (!previous || previous.pluginId !== source.pluginId)
+      return false
+    const result = await runAction(installing, '安装来源保存失败', async () => {
+      const current = (await getPluginUpdateSources({ silent: true })).find(value => value.pluginId === source.pluginId)
+      if (!isEqual(current, previous))
+        throw new Error('安装来源已变更，请关闭后重新打开')
+      await updatePluginSource(source, { silent: true })
+      updateSource.value = source
+      onSourceSaved(source)
+      return true
+    })
+    return result === true
+  }
+
+  function resetReleaseQuery() {
+    releaseController?.abort()
+    releaseController = undefined
+    queryingRelease.value = false
+    release.value = null
+  }
+
+  async function queryRelease(request: QueryPluginReleaseRequest) {
+    releaseController?.abort()
+    const controller = new AbortController()
+    releaseController = controller
+    queryingRelease.value = true
+    release.value = null
+    try {
+      const result = await queryPluginRelease(request, { signal: controller.signal, silent: true })
+      if (releaseController === controller)
+        release.value = result
+    }
+    catch (error) {
+      if (releaseController === controller)
+        notifyError('GitHub Release 查询失败', error)
+    }
+    finally {
+      if (releaseController === controller) {
+        releaseController = undefined
+        queryingRelease.value = false
+      }
+    }
+  }
+
+  async function installArtifact(request: PluginInstallSelection) {
+    const verified = verifiedArtifact.value
+    if (!verified || verified.requestKey !== pluginInstallSelectionKey(request)) {
+      toast.warning('请先校验当前选择的插件包')
+      return
+    }
+    const result = await runAction(installing, '插件安装失败', async () => {
+      const { pluginId, version, sha256 } = verified.artifact.metadata
+      if (request instanceof File) {
+        return uploadPluginArtifact(request, sha256, { silent: true })
+      }
+      else {
+        return installRemotePlugin({
+          pluginId,
+          version,
+          credentialIds: request.credentialIds,
+          outboundProxyId: request.outboundProxyId,
+          location: { ...request.location, sha256 },
+        }, { silent: true })
+      }
+    })
+    if (!result)
+      return
+    showInstall.value = false
+    toast.success(result.configurationRequired ? '插件已安装，请补充必要配置' : result.defaultInstanceId ? '插件已安装，正在准备' : '插件版本已安装')
+    await onInstalled(result)
+  }
+
+  async function acceptArtifact(artifact: PluginArtifact) {
+    if (acceptanceArtifact.value?.metadata.sha256 !== artifact.metadata.sha256) {
+      toast.warning('请选择待安装的插件版本')
+      return
+    }
+    const result = await runAction(installing, '插件安装失败', () => acceptPluginArtifact({ sha256: artifact.metadata.sha256 }, { silent: true }))
+    if (!result)
+      return
+    showInstall.value = false
+    toast.success(result.configurationRequired ? '插件已安装，请补充必要配置' : result.defaultInstanceId ? '插件已安装，正在准备' : '插件版本已安装')
+    await onInstalled(result)
+  }
+
+  function resetArtifactVerification() {
+    verificationController?.abort()
+    verificationController = undefined
+    verifiedArtifact.value = null
+    verifyingArtifact.value = false
+  }
+
+  async function verifyArtifact(request: PluginInstallSelection) {
+    resetArtifactVerification()
+    const controller = new AbortController()
+    verificationController = controller
+    verifyingArtifact.value = true
+    try {
+      const options = { signal: controller.signal, silent: true }
+      const artifact = request instanceof File
+        ? await verifyUploadedPlugin(request, options)
+        : await verifyRemotePlugin(request, options)
+      if (updateSource.value && artifact.metadata.pluginId !== updateSource.value.pluginId)
+        throw new Error('插件包与当前插件不符，请重新选择')
+      if (verificationController === controller)
+        verifiedArtifact.value = { requestKey: pluginInstallSelectionKey(request), artifact }
+    }
+    catch (error) {
+      if (verificationController === controller)
+        notifyError('插件包校验失败', error)
+    }
+    finally {
+      if (verificationController === controller) {
+        verificationController = undefined
+        verifyingArtifact.value = false
+      }
+    }
+  }
+
+  watch(showInstall, (open) => {
+    if (!open) {
+      resetReleaseQuery()
+      resetArtifactVerification()
+      acceptanceArtifact.value = null
+    }
+  })
+  onScopeDispose(() => {
+    releaseController?.abort()
+    verificationController?.abort()
+  })
+  return {
+    showInstall,
+    installMode,
+    updateSource,
+    updateSelection,
+    openCheckedUpdate,
+    acceptanceArtifact,
+    openAcceptance,
+    openVersionInstall,
+    changeInstallMode,
+    saveInstallSource,
+    release,
+    installing,
+    queryingRelease,
+    verifiedArtifact,
+    verifyingArtifact,
+    verifyArtifact,
+    resetArtifactVerification,
+    openInstall,
+    resetReleaseQuery,
+    queryRelease,
+    installArtifact,
+    acceptArtifact,
+  }
+}
diff --git a/frontend/src/views/plugins/composables/usePluginManagement.ts b/frontend/src/views/plugins/composables/usePluginManagement.ts
new file mode 100644
index 000000000..0be12f4f4
--- /dev/null
+++ b/frontend/src/views/plugins/composables/usePluginManagement.ts
@@ -0,0 +1,609 @@
+import type { Ref } from 'vue'
+import type {
+  ConfigurePluginInstanceRequest,
+  CreatePluginSourceCredentialRequest,
+  PluginArtifact,
+  PluginArtifactMutationResponse,
+  PluginInstance,
+  PluginRollbackPlan,
+  PluginSourceCredential,
+  PluginUpdateSourceBinding,
+  PluginVersionPlan,
+} from '@/api'
+
+import { toast } from '@codex-proxy/ui'
+import { storeToRefs } from 'pinia'
+import { computed, onMounted, onScopeDispose, shallowRef, watch } from 'vue'
+import {
+  createPluginSourceCredential,
+  deletePluginArtifact,
+  deletePluginInstance,
+  deletePluginSourceCredential,
+  disablePluginInstance,
+  getPluginArtifacts,
+  getPluginInstances,
+  getPluginRollbackPlan,
+  getPluginSourceCredentials,
+  getPluginUpdateSources,
+  getPluginVersionPlan,
+  rollbackPluginInstance,
+  switchPluginVersion,
+  updatePluginInstance,
+} from '@/api'
+import { ApiError } from '@/api/request'
+import { usePluginManagementViewsStore } from '@/stores/modules/plugin-management-views'
+import { errorMessage } from '@/utils/async'
+import { configurationStatus, currentPluginInstance, groupInstalledPlugins } from '../utils/catalog'
+import { usePluginInstallation } from './usePluginInstallation'
+import { usePluginUninstall } from './usePluginUninstall'
+import { usePluginUpdateCheck } from './usePluginUpdateCheck'
+
+export function usePluginManagement() {
+  const artifacts = shallowRef<PluginArtifact[]>([])
+  const instances = shallowRef<PluginInstance[]>([])
+  const sources = shallowRef<PluginUpdateSourceBinding[]>([])
+  const credentials = shallowRef<PluginSourceCredential[]>([])
+  const extensionDirectory = usePluginManagementViewsStore()
+  const { views: extensions } = storeToRefs(extensionDirectory)
+  const loading = shallowRef(false)
+  const catalog = computed(() => groupInstalledPlugins(artifacts.value, instances.value, sources.value))
+  const selectedPluginId = shallowRef('')
+  const selectedPlugin = computed(() => catalog.value.find(plugin => plugin.id === selectedPluginId.value) ?? null)
+  const showDetail = shallowRef(false)
+  const detailSection = shallowRef<'configurations' | 'versions'>('configurations')
+  const configurationArtifact = shallowRef<PluginArtifact | null>(null)
+  const showInstance = shallowRef(false)
+  const configurationDraft = shallowRef<PluginVersionPlan | null>(null)
+  const configurationError = shallowRef('')
+  const editingInstance = shallowRef<PluginInstance | null>(null)
+  const savingInstance = shallowRef(false)
+  const pendingEnable = shallowRef<{
+    request: ConfigurePluginInstanceRequest
+    instanceId?: string
+    artifact: PluginArtifact
+    replacements: (Pick<PluginInstance, 'id' | 'name' | 'revision'> & { version?: string })[]
+  } | null>(null)
+  const showEnableConfirmation = computed({
+    get: () => pendingEnable.value !== null,
+    set: (open: boolean) => {
+      if (!open && !savingInstance.value)
+        pendingEnable.value = null
+    },
+  })
+  const showRollback = shallowRef(false)
+  const rollbackInstance = shallowRef<PluginInstance | null>(null)
+  const rollbackPlan = shallowRef<PluginRollbackPlan | null>(null)
+  const loadingRollback = shallowRef(false)
+
+  const savingCredential = shallowRef(false)
+
+  const showArtifactDelete = shallowRef(false)
+  const pendingArtifact = shallowRef<PluginArtifact | null>(null)
+  const showInstanceDelete = shallowRef(false)
+  const pendingDeleteInstance = shallowRef<PluginInstance | null>(null)
+  const showCredentialDelete = shallowRef(false)
+  const pendingCredential = shallowRef<PluginSourceCredential | null>(null)
+
+  const busyDigest = shallowRef('')
+  const busyInstanceId = shallowRef('')
+  const busyDistributionId = shallowRef('')
+  const pendingVersionSwitch = shallowRef<{ instance: PluginInstance, artifact: PluginArtifact, currentVersion: string } | null>(null)
+  const showVersionSwitch = computed({
+    get: () => pendingVersionSwitch.value !== null,
+    set: (open: boolean) => {
+      if (!open && !busyInstanceId.value)
+        pendingVersionSwitch.value = null
+    },
+  })
+  let refreshController: AbortController | undefined
+  let rollbackController: AbortController | undefined
+
+  function notifyError(title: string, error: unknown) {
+    if (error instanceof ApiError && error.kind === 'cancelled')
+      return
+    toast.error(errorMessage(error, title))
+  }
+
+  async function refresh(silent = false, suppressErrors = false) {
+    refreshController?.abort()
+    const controller = new AbortController()
+    refreshController = controller
+    if (!silent)
+      loading.value = true
+    try {
+      const options = { signal: controller.signal, silent: true }
+      const extensionRequest = extensionDirectory.refresh(silent)
+        .then(items => ({ ok: true as const, items }))
+        .catch((error: unknown) => ({ ok: false as const, error }))
+      const [artifactItems, instanceItems, sourceItems, credentialItems, extensionResult] = await Promise.all([
+        getPluginArtifacts(options),
+        getPluginInstances(options),
+        getPluginUpdateSources(options),
+        getPluginSourceCredentials(options),
+        extensionRequest,
+      ])
+      if (refreshController !== controller)
+        return
+      artifacts.value = artifactItems
+      instances.value = instanceItems
+      sources.value = sourceItems
+      credentials.value = credentialItems
+      if (!extensionResult.ok && !suppressErrors)
+        notifyError('插件扩展页加载失败', extensionResult.error)
+    }
+    catch (error) {
+      if (refreshController === controller && !suppressErrors)
+        notifyError('插件数据加载失败', error)
+    }
+    finally {
+      if (refreshController === controller) {
+        refreshController = undefined
+        loading.value = false
+      }
+    }
+  }
+
+  async function runAction<T>(
+    flag: Ref<boolean>,
+    title: string,
+    task: () => Promise<T>,
+  ): Promise<T | undefined> {
+    if (flag.value)
+      return undefined
+    flag.value = true
+    try {
+      return await task()
+    }
+    catch (error) {
+      notifyError(title, error)
+      return undefined
+    }
+    finally {
+      flag.value = false
+    }
+  }
+
+  const installation = usePluginInstallation({
+    runAction,
+    notifyError,
+    onInstalled,
+    onSourceSaved: (source) => {
+      sources.value = [...sources.value.filter(value => value.pluginId !== source.pluginId), source]
+    },
+  })
+  const updateCheck = usePluginUpdateCheck(credentials, notifyError)
+
+  async function onInstalled({ artifact, defaultInstanceId, configurationRequired }: PluginArtifactMutationResponse) {
+    const artifactIndex = artifacts.value.findIndex(value => value.metadata.sha256 === artifact.metadata.sha256)
+    artifacts.value = artifactIndex < 0
+      ? [...artifacts.value, artifact]
+      : artifacts.value.map((value, index) => index === artifactIndex ? artifact : value)
+    selectedPluginId.value = artifact.metadata.pluginId
+    await refresh(true)
+    if (configurationRequired && defaultInstanceId) {
+      const instance = instances.value.find(instance => instance.id === defaultInstanceId)
+      if (instance) {
+        openEditInstance(instance)
+        return
+      }
+    }
+    const plugin = catalog.value.find(plugin => plugin.id === artifact.metadata.pluginId)
+    const current = plugin && currentPluginInstance(plugin)
+    if (current && current.artifactSha256 !== artifact.metadata.sha256) {
+      requestVersionSwitch(artifact)
+      return
+    }
+    detailSection.value = 'configurations'
+    showDetail.value = true
+  }
+
+  function requestArtifactDelete(artifact: PluginArtifact) {
+    pendingArtifact.value = artifact
+    showArtifactDelete.value = true
+  }
+
+  async function confirmArtifactDelete() {
+    const artifact = pendingArtifact.value
+    if (!artifact || busyDigest.value)
+      return
+    busyDigest.value = artifact.metadata.sha256
+    try {
+      await deletePluginArtifact({ sha256: artifact.metadata.sha256 }, { silent: true })
+      showArtifactDelete.value = false
+      pendingArtifact.value = null
+      toast.success('插件制品已删除')
+      await refresh(true)
+    }
+    catch (error) {
+      notifyError('插件制品删除失败', error)
+    }
+    finally {
+      busyDigest.value = ''
+    }
+  }
+
+  function openDetail(pluginId: string) {
+    selectedPluginId.value = pluginId
+    const plugin = catalog.value.find(value => value.id === pluginId)
+    detailSection.value = plugin?.artifacts.some(artifact => artifact.acceptedAt) ? 'configurations' : 'versions'
+    showDetail.value = true
+  }
+
+  function openEditInstance(instance: PluginInstance) {
+    configurationDraft.value = null
+    configurationError.value = ''
+    configurationArtifact.value = artifacts.value.find(value => value.metadata.sha256 === instance.artifactSha256) ?? null
+    selectedPluginId.value = configurationArtifact.value?.metadata.pluginId ?? ''
+    editingInstance.value = instance
+    showInstance.value = true
+  }
+
+  async function saveInstance(request: ConfigurePluginInstanceRequest) {
+    if (savingInstance.value || pendingEnable.value)
+      return
+    const instance = editingInstance.value
+    if (!instance)
+      return
+    const input = { ...request, expectedRevision: configurationDraft.value?.instanceRevision ?? instance.revision }
+    const result = await runAction(savingInstance, '插件配置保存失败', async () => {
+      if (request.enabled) {
+        const pending = await prepareInstanceEnable(input, instance?.id)
+        if (pending.replacements.length) {
+          pendingEnable.value = pending
+          return true
+        }
+      }
+      await persistInstance(input, instance?.id)
+      return true
+    })
+    if (!result)
+      await refresh(true, true)
+  }
+
+  async function prepareInstanceEnable(request: ConfigurePluginInstanceRequest, instanceId?: string) {
+    // 启用入口共用确认快照，不自动停用确认后出现或修改的配置。
+    const [currentArtifacts, currentInstances] = await Promise.all([
+      getPluginArtifacts({ silent: true }),
+      getPluginInstances({ silent: true }),
+    ])
+    const artifact = currentArtifacts.find(artifact => artifact.metadata.sha256 === request.artifactSha256)
+    if (!artifact)
+      throw new Error('所选版本已不存在，请重新选择')
+    const digests = new Set(currentArtifacts.filter(value => value.metadata.pluginId === artifact.metadata.pluginId).map(value => value.metadata.sha256))
+    const replacements = currentInstances
+      .filter(current => current.enabled && current.id !== (instanceId ?? request.creationId) && digests.has(current.artifactSha256))
+      .map(({ id, name, revision, artifactSha256 }) => ({ id, name, revision, version: currentArtifacts.find(value => value.metadata.sha256 === artifactSha256)?.metadata.version }))
+    return { request, instanceId, artifact, replacements }
+  }
+
+  async function requestInstanceEnable(instance: PluginInstance) {
+    if ((instance.enabled && configurationStatus(instance) !== 'failed') || savingInstance.value || pendingEnable.value)
+      return
+    if (instance.configurationRequired) {
+      openEditInstance(instance)
+      return
+    }
+    const result = await runAction(savingInstance, '启用配置加载失败', async () => {
+      // 不传 secrets，沿用已保存密钥，不读取或回填明文。
+      const pending = await prepareInstanceEnable({
+        expectedRevision: instance.revision,
+        name: instance.name,
+        artifactSha256: instance.artifactSha256,
+        enabled: true,
+        configuration: instance.configuration,
+        bindings: instance.bindings,
+      }, instance.id)
+      if (pending.replacements.length)
+        pendingEnable.value = pending
+      else await persistInstance(pending.request, instance.id)
+      return true
+    })
+    if (!result)
+      await refresh(true, true)
+  }
+
+  async function confirmInstanceEnable() {
+    const pending = pendingEnable.value
+    if (!pending || savingInstance.value)
+      return
+    const result = await runAction(savingInstance, '配置启用失败', async () => {
+      await persistInstance({
+        ...pending.request,
+        replaceInstances: pending.replacements.map(instance => ({ id: instance.id, expectedRevision: instance.revision })),
+      }, pending.instanceId)
+      return true
+    })
+    // 失败后保留编辑草稿或已保存配置，再次提交需重新读取并确认停用范围。
+    pendingEnable.value = null
+    if (!result)
+      await refresh(true, true)
+  }
+
+  async function persistInstance(request: ConfigurePluginInstanceRequest, instanceId?: string) {
+    if (!instanceId)
+      return
+    await updatePluginInstance({ id: instanceId, instance: request }, { silent: true })
+    pendingEnable.value = null
+    showInstance.value = false
+    editingInstance.value = null
+    toast.success(request.replaceInstances?.length ? '已切换当前配置' : request.enabled ? '插件设置已应用' : '设置已保存，插件保持停用')
+    await refresh(true)
+    detailSection.value = 'configurations'
+    showDetail.value = true
+  }
+
+  async function requestInstanceDisable(instance: PluginInstance) {
+    if (busyInstanceId.value)
+      return
+    busyInstanceId.value = instance.id
+    try {
+      await disablePluginInstance({ id: instance.id }, { silent: true })
+      toast.success('插件已停用')
+      await refresh(true)
+    }
+    catch (error) {
+      notifyError('插件停用失败', error)
+    }
+    finally {
+      busyInstanceId.value = ''
+    }
+  }
+
+  function requestVersionSwitch(artifact: PluginArtifact) {
+    const plugin = catalog.value.find(plugin => plugin.id === artifact.metadata.pluginId)
+    const instance = plugin && currentPluginInstance(plugin)
+    if (!plugin || !instance || !artifact.acceptedAt || busyInstanceId.value || instance.artifactSha256 === artifact.metadata.sha256)
+      return
+    pendingVersionSwitch.value = { instance, artifact, currentVersion: plugin.artifact.metadata.version }
+  }
+
+  async function confirmVersionSwitch() {
+    if (!pendingVersionSwitch.value || busyInstanceId.value)
+      return
+    const { instance, artifact } = pendingVersionSwitch.value
+    busyInstanceId.value = instance.id
+    try {
+      await switchPluginVersion({
+        id: instance.id,
+        target: { artifactSha256: artifact.metadata.sha256, expectedRevision: instance.revision },
+      }, { silent: true })
+      pendingVersionSwitch.value = null
+      toast.success(`已切换至 ${artifact.metadata.version}`)
+      await refresh(true)
+      detailSection.value = 'configurations'
+      showDetail.value = true
+    }
+    catch (error) {
+      await refresh(true, true)
+      const current = instances.value.find(value => value.id === instance.id)
+      if (error instanceof ApiError && error.status === 400 && current?.revision === instance.revision) {
+        try {
+          const plan = await getPluginVersionPlan(instance.id, artifact.metadata.sha256, { silent: true })
+          if (plan.instanceRevision !== instance.revision)
+            throw new Error('插件设置已变更，请刷新后重试')
+          configurationArtifact.value = artifact
+          pendingVersionSwitch.value = null
+          configurationDraft.value = plan
+          configurationError.value = errorMessage(error, '请调整不兼容的设置后重试')
+          editingInstance.value = current
+          showDetail.value = false
+          showInstance.value = true
+        }
+        catch (planError) {
+          notifyError('版本设置加载失败', planError)
+        }
+      }
+      else {
+        notifyError('版本切换失败', error)
+      }
+    }
+    finally {
+      busyInstanceId.value = ''
+    }
+  }
+
+  async function openRollback(instance: PluginInstance) {
+    rollbackController?.abort()
+    const controller = new AbortController()
+    rollbackController = controller
+    rollbackInstance.value = instance
+    rollbackPlan.value = null
+    showRollback.value = true
+    loadingRollback.value = true
+    try {
+      const plan = await getPluginRollbackPlan(instance.id, { signal: controller.signal, silent: true })
+      if (rollbackController === controller)
+        rollbackPlan.value = plan
+    }
+    catch (error) {
+      if (rollbackController === controller)
+        notifyError('回退版本加载失败', error)
+    }
+    finally {
+      if (rollbackController === controller) {
+        rollbackController = undefined
+        loadingRollback.value = false
+      }
+    }
+  }
+
+  async function confirmRollback(artifactSha256: string) {
+    const instance = rollbackInstance.value
+    const plan = rollbackPlan.value
+    const target = plan?.targets.find(target => target.artifactSha256 === artifactSha256)
+    if (!instance || !plan || !target || busyInstanceId.value)
+      return
+    busyInstanceId.value = instance.id
+    try {
+      await rollbackPluginInstance({ id: instance.id, target: { artifactSha256, expectedRevision: plan.instanceRevision } }, { silent: true })
+      showRollback.value = false
+      rollbackInstance.value = null
+      rollbackPlan.value = null
+      toast.success(`已回退至 ${target.version}，并恢复对应设置`)
+      await refresh(true)
+    }
+    catch (error) {
+      notifyError('插件版本回退失败', error)
+    }
+    finally {
+      busyInstanceId.value = ''
+    }
+  }
+
+  function requestInstanceDelete(instance: PluginInstance) {
+    pendingDeleteInstance.value = instance
+    showInstanceDelete.value = true
+  }
+
+  async function confirmInstanceDelete() {
+    const instance = pendingDeleteInstance.value
+    if (!instance || busyInstanceId.value)
+      return
+    busyInstanceId.value = instance.id
+    try {
+      await deletePluginInstance({ id: instance.id }, { silent: true })
+      showInstanceDelete.value = false
+      pendingDeleteInstance.value = null
+      toast.success('配置、密钥与私有数据已删除，无法恢复')
+      await refresh(true)
+    }
+    catch (error) {
+      notifyError('插件实例删除失败', error)
+    }
+    finally {
+      busyInstanceId.value = ''
+    }
+  }
+
+  async function saveCredential(request: CreatePluginSourceCredentialRequest) {
+    const result = await runAction(savingCredential, '下载认证保存失败', () => createPluginSourceCredential(request, { silent: true }))
+    if (!result)
+      return null
+    credentials.value = [...credentials.value, result]
+    return result
+  }
+
+  function requestCredentialDelete(credential: PluginSourceCredential) {
+    pendingCredential.value = credential
+    showCredentialDelete.value = true
+  }
+
+  async function confirmCredentialDelete() {
+    const credential = pendingCredential.value
+    if (!credential || busyDistributionId.value)
+      return
+    busyDistributionId.value = credential.id
+    try {
+      await deletePluginSourceCredential({ id: credential.id }, { silent: true })
+      showCredentialDelete.value = false
+      pendingCredential.value = null
+      toast.success('来源凭据已删除')
+      await refresh(true)
+    }
+    catch (error) {
+      notifyError('来源凭据删除失败', error)
+    }
+    finally {
+      busyDistributionId.value = ''
+    }
+  }
+
+  watch(showInstance, (open) => {
+    if (!open && !savingInstance.value) {
+      editingInstance.value = null
+      pendingEnable.value = null
+    }
+  })
+  watch(showRollback, (open) => {
+    if (!open) {
+      rollbackController?.abort()
+      rollbackController = undefined
+      loadingRollback.value = false
+    }
+  })
+
+  onMounted(() => void refresh())
+  const uninstall = usePluginUninstall(() => refresh(true), notifyError)
+  let pollTimer: ReturnType<typeof setTimeout> | undefined
+  let disposed = false
+  function schedulePoll() {
+    clearTimeout(pollTimer)
+    if (disposed)
+      return
+    if (instances.value.some(instance => instance.enabled && ['awaiting_publication', 'preparing', 'draining'].includes(instance.runtime.status))) {
+      pollTimer = setTimeout(async () => {
+        await refresh(true, true)
+        schedulePoll()
+      }, 3000)
+    }
+  }
+  watch(instances, schedulePoll)
+  watch(selectedPlugin, (plugin) => {
+    if (!plugin)
+      showDetail.value = false
+  })
+  onScopeDispose(() => {
+    disposed = true
+    clearTimeout(pollTimer)
+    refreshController?.abort()
+    rollbackController?.abort()
+  })
+
+  return {
+    ...installation,
+    updateCheck,
+    catalog,
+    selectedPlugin,
+    showDetail,
+    detailSection,
+    openDetail,
+    configurationArtifact,
+    configurationDraft,
+    configurationError,
+    uninstall,
+    artifacts,
+    instances,
+    sources,
+    credentials,
+    extensions,
+    loading,
+    showInstance,
+    editingInstance,
+    savingInstance,
+    pendingEnable,
+    showEnableConfirmation,
+    confirmInstanceEnable,
+    showRollback,
+    rollbackInstance,
+    rollbackPlan,
+    loadingRollback,
+    openRollback,
+    confirmRollback,
+    savingCredential,
+    requestVersionSwitch,
+    confirmVersionSwitch,
+    pendingVersionSwitch,
+    showVersionSwitch,
+    showArtifactDelete,
+    pendingArtifact,
+    showInstanceDelete,
+    pendingDeleteInstance,
+    showCredentialDelete,
+    pendingCredential,
+    busyDigest,
+    busyInstanceId,
+    busyDistributionId,
+    refresh,
+    requestArtifactDelete,
+    confirmArtifactDelete,
+    openEditInstance,
+    saveInstance,
+    requestInstanceEnable,
+    requestInstanceDisable,
+    requestInstanceDelete,
+    confirmInstanceDelete,
+    saveCredential,
+    requestCredentialDelete,
+    confirmCredentialDelete,
+  }
+}
diff --git a/frontend/src/views/plugins/composables/usePluginUninstall.ts b/frontend/src/views/plugins/composables/usePluginUninstall.ts
new file mode 100644
index 000000000..02d61b3c8
--- /dev/null
+++ b/frontend/src/views/plugins/composables/usePluginUninstall.ts
@@ -0,0 +1,68 @@
+import type { InstalledPlugin } from '../utils/catalog'
+import { toast } from '@codex-proxy/ui'
+import { shallowRef } from 'vue'
+import { deletePluginArtifact, deletePluginInstance, disablePluginInstance, getPluginArtifacts, getPluginInstances } from '@/api'
+
+export function usePluginUninstall(refresh: () => Promise<void>, notifyError: (title: string, cause: unknown) => void) {
+  const open = shallowRef(false)
+  const pending = shallowRef<InstalledPlugin | null>(null)
+  const acknowledged = shallowRef(false)
+  const busy = shallowRef(false)
+  const progress = shallowRef('')
+
+  function request(plugin: InstalledPlugin) {
+    // 固定确认范围，重试不扩大到此后新建的配置或版本。
+    pending.value = { ...plugin, artifacts: [...plugin.artifacts], configurations: [...plugin.configurations] }
+    acknowledged.value = false
+    progress.value = ''
+    open.value = true
+  }
+
+  async function confirm() {
+    const plugin = pending.value
+    if (!plugin || !acknowledged.value || busy.value)
+      return
+    busy.value = true
+    const options = { silent: true }
+    try {
+      const current = await getPluginInstances(options)
+      const digests = new Set(plugin.artifacts.map(artifact => artifact.metadata.sha256))
+      const ids = new Set(plugin.configurations.map(instance => instance.id))
+      if (current.some(instance => digests.has(instance.artifactSha256) && !ids.has(instance.id)))
+        throw new Error('出现了新的插件配置，请关闭并重新确认卸载范围')
+      for (const configured of plugin.configurations) {
+        const instance = current.find(value => value.id === configured.id)
+        if (!instance)
+          continue
+        if (instance.artifactSha256 !== configured.artifactSha256)
+          throw new Error(`“${instance.name}”已切换版本，请重新确认卸载范围`)
+        progress.value = `正在停用并删除配置：${instance.name}`
+        if (instance.enabled)
+          await disablePluginInstance({ id: instance.id }, options)
+        await deletePluginInstance({ id: instance.id }, options)
+      }
+      const remaining = await getPluginArtifacts(options)
+      for (const artifact of plugin.artifacts) {
+        if (!remaining.some(value => value.metadata.sha256 === artifact.metadata.sha256))
+          continue
+        progress.value = `正在删除版本：${artifact.metadata.version}`
+        await deletePluginArtifact({ sha256: artifact.metadata.sha256 }, options)
+      }
+      if ((await getPluginArtifacts(options)).some(artifact => artifact.metadata.pluginId === plugin.id))
+        throw new Error('已删除确认范围，但还有新安装的版本，请关闭并重新确认剩余内容')
+      open.value = false
+      toast.success('插件已卸载，相关数据与来源设置已清理')
+      await refresh()
+    }
+    catch (cause) {
+      // 卸载不是跨请求事务，刷新已完成的步骤后提示失败原因，可从剩余部分重试。
+      await refresh()
+      notifyError('卸载尚未完成，可重试剩余步骤', cause)
+    }
+    finally {
+      busy.value = false
+      progress.value = ''
+    }
+  }
+  return { open, pending, acknowledged, busy, progress, request, confirm }
+}
diff --git a/frontend/src/views/plugins/composables/usePluginUpdateCheck.ts b/frontend/src/views/plugins/composables/usePluginUpdateCheck.ts
new file mode 100644
index 000000000..33956b48e
--- /dev/null
+++ b/frontend/src/views/plugins/composables/usePluginUpdateCheck.ts
@@ -0,0 +1,87 @@
+import type { Ref } from 'vue'
+import type { InstalledPlugin } from '../utils/catalog'
+import type { PluginArtifact, PluginRelease, PluginSourceCredential, PluginUpdateSourceBinding, VerifiedPluginArtifact } from '@/api'
+import { isEqual } from 'es-toolkit'
+import { onScopeDispose, shallowRef, watch } from 'vue'
+import { checkPluginUpdate, getPluginUpdateSources, queryPluginRelease, verifyRemotePlugin } from '@/api'
+
+export interface PluginUpdateSelection {
+  binding: PluginUpdateSourceBinding
+  credentialIds: string[]
+  release?: PluginRelease
+  artifact?: VerifiedPluginArtifact
+}
+
+export function usePluginUpdateCheck(credentials: Ref<PluginSourceCredential[]>, notifyError: (title: string, error: unknown) => void) {
+  const open = shallowRef(false)
+  const checking = shallowRef(false)
+  const plugin = shallowRef<InstalledPlugin | null>(null)
+  const result = shallowRef<PluginUpdateSelection | null>(null)
+  let controller: AbortController | undefined
+
+  function cancel() {
+    controller?.abort()
+    controller = undefined
+    checking.value = false
+  }
+
+  async function check(target: InstalledPlugin) {
+    cancel()
+    const current = new AbortController()
+    controller = current
+    plugin.value = target
+    result.value = null
+    open.value = true
+    checking.value = true
+    try {
+      const options = { signal: current.signal, silent: true }
+      const binding = (await getPluginUpdateSources(options)).find(value => value.pluginId === target.id)
+      if (!binding || (binding.source.kind !== 'github' && binding.source.kind !== 'url'))
+        throw new Error('此来源不支持检查更新，请安装新版本')
+      const source = binding.source
+      const history = [...target.artifacts].sort((left, right) => right.installedAt.localeCompare(left.installedAt))
+      const previous = history.find((artifact: PluginArtifact) => source.kind === 'github'
+        ? artifact.source.kind === 'github' && artifact.source.repository === source.repository
+        : artifact.source.kind === 'url' && artifact.source.url === source.url)?.source
+      const credentialIds = previous && (previous.kind === 'github' || previous.kind === 'url')
+        ? previous.credential_ids.filter(id => credentials.value.some(credential => credential.id === id))
+        : []
+      let candidate: PluginUpdateSelection
+      if (source.kind === 'github') {
+        // 手动来源仍可按需查询稳定发布，不为一次查询修改持久化策略。
+        const release = binding.policy.kind === 'manual'
+          ? await queryPluginRelease({ query: { repository: source.repository, tag: null, allowPrerelease: false }, credentialIds, outboundProxyId: binding.outboundProxyId }, options)
+          : (await checkPluginUpdate({ pluginId: target.id, credentialIds }, options)).release
+        candidate = { binding, credentialIds, release }
+      }
+      else {
+        const artifact = await verifyRemotePlugin({ expectedPluginId: target.id, credentialIds, outboundProxyId: binding.outboundProxyId, location: { kind: 'url', url: source.url, sha256: null } }, options)
+        candidate = { binding, credentialIds, artifact }
+      }
+      const latest = (await getPluginUpdateSources(options)).find(value => value.pluginId === target.id)
+      if (!isEqual(binding, latest))
+        throw new Error('安装来源已变更，请重新检查')
+      if (controller === current)
+        result.value = candidate
+    }
+    catch (error) {
+      if (controller === current) {
+        open.value = false
+        notifyError('检查更新失败', error)
+      }
+    }
+    finally {
+      if (controller === current) {
+        controller = undefined
+        checking.value = false
+      }
+    }
+  }
+
+  watch(open, (value) => {
+    if (!value)
+      cancel()
+  })
+  onScopeDispose(cancel)
+  return { open, checking, plugin, result, check }
+}
diff --git a/frontend/src/views/plugins/index.vue b/frontend/src/views/plugins/index.vue
new file mode 100644
index 000000000..a78fb6fd3
--- /dev/null
+++ b/frontend/src/views/plugins/index.vue
@@ -0,0 +1,7 @@
+<script setup lang="ts">
+import { RouterView } from 'vue-router'
+</script>
+
+<template>
+  <RouterView />
+</template>
diff --git a/frontend/src/views/plugins/management/frame.ts b/frontend/src/views/plugins/management/frame.ts
new file mode 100644
index 000000000..47891c407
--- /dev/null
+++ b/frontend/src/views/plugins/management/frame.ts
@@ -0,0 +1,846 @@
+import type {
+  PluginManagementPage,
+  PluginManagementResource,
+  PluginManagementView,
+} from '@/api'
+import { THEME_TOKEN_NAMES } from '@codex-proxy/ui/theme'
+import { generate, parse, walk } from 'css-tree'
+
+import { getPluginManagementResource } from '@/api'
+
+export const PLUGIN_MANAGEMENT_BRIDGE = 'codex-proxy-plugin-management'
+export const PLUGIN_MANAGEMENT_BRIDGE_VERSION = 2
+export const MAXIMUM_MANAGEMENT_BODY_BYTES = 1024 * 1024
+export const MAXIMUM_MANAGEMENT_QUERY_BYTES = 8192
+export const MAXIMUM_MANAGEMENT_IN_FLIGHT = 8
+export const MAXIMUM_MODEL_BODY_BYTES = 8 * 1024 * 1024
+export const MAXIMUM_MODEL_CHUNK_BYTES = 64 * 1024
+export const MAXIMUM_MODEL_IN_FLIGHT = 4
+export const MODEL_REQUEST_DEADLINE_MS = 10 * 60 * 1000
+export const MODEL_RESPONSE_IDLE_MS = 30 * 1000
+
+const MAXIMUM_MANAGEMENT_RESOURCES = 128
+const MAXIMUM_MANAGEMENT_RESOURCE_BYTES = 1024 * 1024
+const MAXIMUM_MANAGEMENT_TOTAL_BYTES = 8 * 1024 * 1024
+const RESOURCE_CONCURRENCY = 4
+const PATH_SEGMENT = /^(?!\.{1,2}$)[\w.-]+$/u
+
+const FRAME_CSP = [
+  'default-src \'none\'',
+  'script-src \'unsafe-inline\' data:',
+  'style-src \'unsafe-inline\' data:',
+  'img-src data:',
+  'font-src data:',
+  'media-src data:',
+  'connect-src \'none\'',
+  'worker-src \'none\'',
+  'child-src \'none\'',
+  'frame-src \'none\'',
+  'object-src \'none\'',
+  'manifest-src \'none\'',
+  'base-uri \'none\'',
+  'form-action \'none\'',
+].join('; ')
+
+const JAVASCRIPT_CONTENT_TYPES = new Set([
+  'application/ecmascript',
+  'application/javascript',
+  'text/ecmascript',
+  'text/javascript',
+])
+
+export interface PluginFrameTheme {
+  name: 'light' | 'dark'
+  tokens: Record<string, string>
+}
+
+export interface AssembledPluginPage {
+  srcdoc: string
+  revoke: () => void
+}
+
+interface LoadedResource {
+  descriptor: PluginManagementResource
+  body: ArrayBuffer
+}
+
+export async function assemblePluginManagementPage(
+  view: PluginManagementView,
+  page: PluginManagementPage,
+  channel: string,
+  session: string,
+  parentOrigin: string,
+  theme: PluginFrameTheme,
+  viewportHeight: number,
+  signal: AbortSignal,
+): Promise<AssembledPluginPage> {
+  validateView(view, page)
+  const resources = await loadResources(view, signal)
+  if (signal.aborted)
+    throw new DOMException('Aborted', 'AbortError')
+
+  const resourceUrls = new Map<string, string>()
+  const building = new Set<string>()
+  const entry = resources.get(page.entry)
+  if (!entry || contentType(entry.descriptor.contentType) !== 'text/html')
+    throw new Error('插件页面入口不是已注册的 HTML 资源')
+
+  const ensureResourceUrl = (path: string): string => {
+    const existing = resourceUrls.get(path)
+    if (existing)
+      return existing
+    const resource = resources.get(path)
+    if (!resource)
+      throw new Error(`插件页面引用了未注册资源：${path}`)
+    const mime = contentType(resource.descriptor.contentType)
+    if (mime === 'text/html')
+      throw new Error('插件 HTML 资源不能作为子资源加载')
+    if (building.has(path))
+      throw new Error(`插件 CSS 资源存在循环引用：${path}`)
+    building.add(path)
+    try {
+      const body = mime === 'text/css'
+        ? rewriteCss(decodeText(resource.body, path), path, resources, ensureResourceUrl)
+        : resource.body
+      const url = dataUrl(body, resource.descriptor.contentType)
+      resourceUrls.set(path, url)
+      return url
+    }
+    finally {
+      building.delete(path)
+    }
+  }
+
+  for (const [path, resource] of resources) {
+    if (contentType(resource.descriptor.contentType) !== 'text/html')
+      ensureResourceUrl(path)
+  }
+  const document = new DOMParser().parseFromString(decodeText(entry.body, page.entry), 'text/html')
+  rewriteDocument(document, page.entry, resources, ensureResourceUrl)
+  injectFrameBoundary(document, createBridgeScript({
+    view,
+    page,
+    channel,
+    session,
+    parentOrigin,
+    theme,
+    viewportHeight,
+    resourceUrls: Object.fromEntries(resourceUrls),
+  }))
+  return {
+    srcdoc: `<!doctype html>\n${document.documentElement.outerHTML}`,
+    revoke: () => {},
+  }
+}
+
+export function readPluginFrameTheme(): PluginFrameTheme {
+  const root = document.documentElement
+  const computed = getComputedStyle(root)
+  const tokens: Record<string, string> = {}
+  for (const token of THEME_TOKEN_NAMES) {
+    const value = safeThemeValue(computed.getPropertyValue(token))
+    if (value)
+      tokens[token] = value
+  }
+  const font = safeThemeValue(computed.getPropertyValue('--font-sans')) || safeThemeValue(computed.fontFamily)
+  const fontCode = safeThemeValue(computed.getPropertyValue('--font-mono'))
+  if (font)
+    tokens['--cp-font-family'] = font
+  if (fontCode)
+    tokens['--cp-font-family-code'] = fontCode
+  return {
+    name: root.dataset.theme === 'dark' ? 'dark' : 'light',
+    tokens,
+  }
+}
+
+function validateView(view: PluginManagementView, page: PluginManagementPage) {
+  if (!Number.isSafeInteger(view.target.revision) || view.target.revision < 1)
+    throw new Error('插件页面版本无效，请刷新后重试')
+  if (view.resources.length > MAXIMUM_MANAGEMENT_RESOURCES)
+    throw new Error('插件页面资源数量超过限制')
+  for (const resource of view.resources)
+    validateDeclaredPath(resource.path)
+  validateDeclaredPath(page.entry)
+  if (!view.pages.some(candidate => candidate.id === page.id && candidate.entry === page.entry))
+    throw new Error('插件页面已变更，请刷新后重试')
+}
+
+async function loadResources(view: PluginManagementView, signal: AbortSignal) {
+  const resources = new Map<string, LoadedResource>()
+  let cursor = 0
+  let total = 0
+  const workers = Array.from(
+    { length: Math.min(RESOURCE_CONCURRENCY, view.resources.length) },
+    async () => {
+      while (cursor < view.resources.length) {
+        const descriptor = view.resources[cursor++]
+        if (!descriptor)
+          return
+        const response = await getPluginManagementResource(view.target, descriptor.path, { signal, silent: true })
+        if (response.status < 200 || response.status >= 300)
+          throw new Error(`插件资源返回 HTTP ${response.status}`)
+        if (contentType(response.contentType) !== contentType(descriptor.contentType))
+          throw new Error(`插件资源类型与注册值不一致：${descriptor.path}`)
+        if (response.body.byteLength > MAXIMUM_MANAGEMENT_RESOURCE_BYTES)
+          throw new Error(`插件资源超过 1 MiB：${descriptor.path}`)
+        total += response.body.byteLength
+        if (total > MAXIMUM_MANAGEMENT_TOTAL_BYTES)
+          throw new Error('插件页面资源总量超过 8 MiB')
+        resources.set(descriptor.path, { descriptor, body: response.body })
+      }
+    },
+  )
+  await Promise.all(workers)
+  return resources
+}
+
+function rewriteDocument(
+  document: Document,
+  entryPath: string,
+  resources: Map<string, LoadedResource>,
+  ensureResourceUrl: (path: string) => string,
+) {
+  const unsupported = document.querySelector('base, iframe, frame, frameset, object, embed, portal, template')
+  if (unsupported)
+    throw new Error(`插件页面使用了不受支持的 <${unsupported.tagName.toLowerCase()}> 元素`)
+  if ([...document.querySelectorAll('meta[http-equiv]')].some(meta => meta.getAttribute('http-equiv')?.toLowerCase() === 'refresh'))
+    throw new Error('插件页面不能使用自动跳转')
+
+  for (const script of document.querySelectorAll('script')) {
+    if (script.getAttribute('type')?.trim().toLowerCase() === 'module')
+      throw new Error('插件页面暂不支持 ES Module 脚本，请使用经典脚本包')
+    const source = script.getAttribute('src')
+    if (!source)
+      continue
+    const path = resolveResourceReference(entryPath, source, resources)
+    if (!JAVASCRIPT_CONTENT_TYPES.has(contentType(resources.get(path)?.descriptor.contentType ?? '')))
+      throw new Error(`插件脚本资源类型无效：${path}`)
+    script.setAttribute('src', ensureResourceUrl(path))
+  }
+
+  for (const link of document.querySelectorAll('link[href]')) {
+    const rel = new Set((link.getAttribute('rel') ?? '').toLowerCase().split(/\s+/u).filter(Boolean))
+    if (![...rel].every(value => value === 'stylesheet' || value === 'icon') || rel.size === 0)
+      throw new Error('插件页面只支持 stylesheet 和 icon 链接资源')
+    const path = resolveResourceReference(entryPath, link.getAttribute('href') ?? '', resources)
+    const mime = contentType(resources.get(path)?.descriptor.contentType ?? '')
+    if (rel.has('stylesheet') && mime !== 'text/css')
+      throw new Error(`插件样式资源类型无效：${path}`)
+    if (rel.has('icon') && !mime.startsWith('image/'))
+      throw new Error(`插件图标资源类型无效：${path}`)
+    link.setAttribute('href', ensureResourceUrl(path))
+  }
+
+  const supportedSourceElements = new Set(['AUDIO', 'IMG', 'SCRIPT', 'SOURCE', 'TRACK', 'VIDEO'])
+  for (const element of document.querySelectorAll<HTMLElement>('[src]')) {
+    if (element.tagName === 'SCRIPT')
+      continue
+    if (!supportedSourceElements.has(element.tagName))
+      throw new Error(`插件页面不支持 <${element.tagName.toLowerCase()}> 的 src 加载`)
+    const path = resolveResourceReference(entryPath, element.getAttribute('src') ?? '', resources)
+    if (element.tagName === 'IMG' && !contentType(resources.get(path)?.descriptor.contentType ?? '').startsWith('image/'))
+      throw new Error(`插件图像资源类型无效：${path}`)
+    element.setAttribute('src', ensureResourceUrl(path))
+  }
+
+  for (const element of document.querySelectorAll<HTMLElement>('[poster]')) {
+    const path = resolveResourceReference(entryPath, element.getAttribute('poster') ?? '', resources)
+    if (!contentType(resources.get(path)?.descriptor.contentType ?? '').startsWith('image/'))
+      throw new Error(`插件 poster 资源类型无效：${path}`)
+    element.setAttribute('poster', ensureResourceUrl(path))
+  }
+
+  for (const element of document.querySelectorAll<HTMLElement>('[srcset]')) {
+    const rewritten = (element.getAttribute('srcset') ?? '').split(',').map((candidate) => {
+      const [reference, ...descriptor] = candidate.trim().split(/\s+/u)
+      if (!reference)
+        throw new Error('插件 srcset 资源引用为空')
+      const path = resolveResourceReference(entryPath, reference, resources)
+      return [ensureResourceUrl(path), ...descriptor].join(' ')
+    }).join(', ')
+    element.setAttribute('srcset', rewritten)
+  }
+
+  for (const style of document.querySelectorAll('style'))
+    style.textContent = rewriteCss(style.textContent ?? '', entryPath, resources, ensureResourceUrl)
+  for (const element of document.querySelectorAll<HTMLElement>('[style]'))
+    element.setAttribute('style', rewriteCss(element.getAttribute('style') ?? '', entryPath, resources, ensureResourceUrl, false))
+
+  for (const element of document.querySelectorAll<HTMLElement>('*')) {
+    for (const attribute of [...element.attributes]) {
+      const name = attribute.name.toLowerCase()
+      if (name === 'href' || name === 'xlink:href') {
+        if (element.tagName === 'LINK')
+          continue
+        if (attribute.value.startsWith('#'))
+          continue
+        throw new Error('插件页面不能导航到外部或未注册地址')
+      }
+      if (['action', 'formaction', 'ping', 'background'].includes(name) && attribute.value)
+        throw new Error(`插件页面不支持 ${name} 地址`)
+      if (
+        name !== 'style'
+        && /\burl\s*\(/iu.test(attribute.value)
+        && !/^url\(\s*#[\w.-]+\s*\)$/iu.test(attribute.value.trim())
+      ) {
+        throw new Error(`插件页面属性不能引用外部资源：${name}`)
+      }
+    }
+  }
+}
+
+function injectFrameBoundary(document: Document, bridgeScript: string) {
+  const head = document.head || document.documentElement.insertBefore(document.createElement('head'), document.body)
+  const policy = document.createElement('meta')
+  policy.setAttribute('http-equiv', 'Content-Security-Policy')
+  policy.setAttribute('content', FRAME_CSP)
+  const referrer = document.createElement('meta')
+  referrer.setAttribute('name', 'referrer')
+  referrer.setAttribute('content', 'no-referrer')
+  const bridge = document.createElement('script')
+  bridge.textContent = bridgeScript
+  const layout = document.createElement('style')
+  // 宿主统一提供最小高度与整页滚动；flow-root 包含子元素外边距与浮动。
+  layout.textContent = `
+    html { overflow: hidden; }
+    body { margin: 0; display: flow-root; box-sizing: border-box; min-height: var(--cp-plugin-viewport-height, 0px); }
+  `
+  head.append(layout)
+  head.prepend(bridge)
+  head.prepend(referrer)
+  head.prepend(policy)
+}
+
+function rewriteCss(
+  source: string,
+  ownerPath: string,
+  resources: Map<string, LoadedResource>,
+  ensureResourceUrl: (path: string) => string,
+  allowImports = true,
+) {
+  // 按 CSS 语法区分选择器转义与资源地址，避免拒绝 Tailwind 类名或漏过转义 URL。
+  const tree = parse(source, {
+    context: allowImports ? 'stylesheet' : 'declarationList',
+    parseRulePrelude: false,
+    parseCustomProperty: true,
+    onParseError(_error, fallback) {
+      // 条件表达式会先尝试不同语法；只有落入原始文本兜底才算解析失败。
+      if (fallback)
+        throw new Error(`插件 CSS 语法不受支持：${ownerPath}`)
+    },
+  })
+  const imported = new WeakSet<object>()
+  walk(tree, function (node) {
+    // 选择器不加载资源，原样保留其转义；声明值则必须完整解析后再检查地址。
+    if (node.type === 'Raw' && node !== this.rule?.prelude)
+      throw new Error(`插件 CSS 包含无法解析的内容：${ownerPath}`)
+    if ((node.type === 'Atrule' || node.type === 'Function') && node.name.includes('\\'))
+      throw new Error(`插件 CSS 规则或函数名不能使用转义：${ownerPath}`)
+    if (node.type === 'Atrule' && node.name.toLowerCase() === 'import') {
+      if (!allowImports)
+        throw new Error('内联 style 属性不能导入样式表')
+      const reference = node.prelude?.type === 'AtrulePrelude' ? node.prelude.children.first : null
+      if (node.block || !reference || (reference.type !== 'String' && reference.type !== 'Url'))
+        throw new Error(`插件 @import 语法不受支持：${ownerPath}`)
+      const path = resolveResourceReference(ownerPath, reference.value, resources)
+      if (contentType(resources.get(path)?.descriptor.contentType ?? '') !== 'text/css')
+        throw new Error(`插件 @import 目标不是 CSS：${path}`)
+      reference.value = ensureResourceUrl(path)
+      imported.add(reference)
+    }
+    if (node.type === 'Url' && !imported.has(node)) {
+      if (node.value.startsWith('#'))
+        return
+      const path = resolveResourceReference(ownerPath, node.value, resources)
+      node.value = ensureResourceUrl(path)
+    }
+  })
+  return generate(tree)
+}
+
+function resolveResourceReference(
+  ownerPath: string,
+  rawReference: string,
+  resources: Map<string, LoadedResource>,
+) {
+  const reference = rawReference.trim()
+  if (
+    !reference
+    || reference.startsWith('/')
+    || reference.startsWith('//')
+    || reference.includes('\\')
+    || reference.includes('%')
+    || hasControlCharacter(reference)
+    || /^[a-z][a-z\d+.-]*:/iu.test(reference)
+  ) {
+    throw new Error(`插件资源地址不受支持：${rawReference}`)
+  }
+  const queryIndex = reference.indexOf('?')
+  if (queryIndex >= 0)
+    throw new Error(`插件资源地址不支持查询参数：${rawReference}`)
+  if (reference.includes('#'))
+    throw new Error(`插件资源地址不支持片段标识：${rawReference}`)
+  const pathReference = reference
+  const base = ownerPath.split('/').slice(0, -1)
+  for (const segment of pathReference.split('/')) {
+    if (!segment || segment === '.')
+      continue
+    if (segment === '..') {
+      if (base.length === 0)
+        throw new Error(`插件资源地址越过制品边界：${rawReference}`)
+      base.pop()
+      continue
+    }
+    if (!PATH_SEGMENT.test(segment))
+      throw new Error(`插件资源路径片段无效：${rawReference}`)
+    base.push(segment)
+  }
+  const path = base.join('/')
+  if (!resources.has(path))
+    throw new Error(`插件页面引用了未注册资源：${path}`)
+  return path
+}
+
+function validateDeclaredPath(path: string) {
+  if (!path || path.length > 512 || path.split('/').some(segment => !PATH_SEGMENT.test(segment)))
+    throw new Error(`插件注册了无效资源路径：${path}`)
+}
+
+function contentType(value: string) {
+  return value.split(';', 1)[0]?.trim().toLowerCase() ?? ''
+}
+
+function decodeText(body: ArrayBuffer, path: string) {
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(new Uint8Array(body))
+  }
+  catch {
+    throw new Error(`插件文本资源不是有效 UTF-8：${path}`)
+  }
+}
+
+function dataUrl(body: ArrayBuffer | string, mime: string) {
+  const bytes = typeof body === 'string'
+    ? new TextEncoder().encode(body)
+    : new Uint8Array(body)
+  let binary = ''
+  const chunkSize = 32 * 1024
+  for (let offset = 0; offset < bytes.byteLength; offset += chunkSize)
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize))
+  return `data:${mime};base64,${btoa(binary)}`
+}
+
+function safeThemeValue(value: string) {
+  const normalized = value.trim()
+  if (!normalized || normalized.length > 512 || /url\s*\(|[<>]/iu.test(normalized) || hasControlCharacter(normalized))
+    return ''
+  return normalized
+}
+
+function hasControlCharacter(value: string) {
+  return [...value].some((character) => {
+    const code = character.codePointAt(0) ?? 0
+    return code < 0x20 || code === 0x7F
+  })
+}
+
+function createBridgeScript(input: {
+  view: PluginManagementView
+  page: PluginManagementPage
+  channel: string
+  session: string
+  parentOrigin: string
+  theme: PluginFrameTheme
+  viewportHeight: number
+  resourceUrls: Record<string, string>
+}) {
+  const initial = JSON.stringify({
+    target: PLUGIN_MANAGEMENT_BRIDGE,
+    version: PLUGIN_MANAGEMENT_BRIDGE_VERSION,
+    channel: input.channel,
+    session: input.session,
+    parentOrigin: input.parentOrigin,
+    plugin: { name: input.view.name },
+    page: { id: input.page.id, title: input.page.title },
+    theme: input.theme,
+    viewportHeight: input.viewportHeight,
+    resourceUrls: input.resourceUrls,
+  }).replace(/</gu, '\\u003c')
+  return `(() => {
+    'use strict';
+    const initial = ${initial};
+    const pending = new Map();
+    const modelOperations = new Map();
+    const safeModelHeaders = new Set([
+      'content-type', 'openai-processing-ms', 'openai-request-id', 'request-id', 'retry-after',
+      'x-client-request-id', 'x-gateway-request-id', 'x-oai-request-id', 'x-openai-request-id', 'x-processing-ms', 'x-request-id',
+      'x-ratelimit-limit-requests', 'x-ratelimit-limit-tokens', 'x-ratelimit-remaining-requests',
+      'x-ratelimit-remaining-tokens', 'x-ratelimit-reset-requests', 'x-ratelimit-reset-tokens',
+    ]);
+    let sequence = 0;
+    let resizeObserver;
+    let resizeFrame = 0;
+    let previousHeight = 0;
+    let disposed = false;
+    let currentTheme = initial.theme.name;
+    const maximumBodyBytes = ${MAXIMUM_MANAGEMENT_BODY_BYTES};
+    const maximumQueryBytes = ${MAXIMUM_MANAGEMENT_QUERY_BYTES};
+    const maximumInFlight = ${MAXIMUM_MANAGEMENT_IN_FLIGHT};
+    const maximumModelBodyBytes = ${MAXIMUM_MODEL_BODY_BYTES};
+    const maximumModelChunkBytes = ${MAXIMUM_MODEL_CHUNK_BYTES};
+    const maximumModelInFlight = ${MAXIMUM_MODEL_IN_FLIGHT};
+    const modelRequestDeadlineMs = ${MODEL_REQUEST_DEADLINE_MS};
+
+    function applyLayout(height) {
+      if (Number.isSafeInteger(height) && height >= 0) {
+        document.documentElement.style.setProperty('--cp-plugin-viewport-height', height + 'px');
+      }
+    }
+
+    function applyTheme(theme) {
+      if (!theme || (theme.name !== 'light' && theme.name !== 'dark') || !theme.tokens || typeof theme.tokens !== 'object') return;
+      const root = document.documentElement;
+      root.dataset.theme = theme.name;
+      root.style.colorScheme = theme.name;
+      for (const [name, value] of Object.entries(theme.tokens)) {
+        if (typeof name === 'string' && name.startsWith('--cp-') && typeof value === 'string') root.style.setProperty(name, value);
+      }
+      currentTheme = theme.name;
+      window.dispatchEvent(new CustomEvent('codex-proxy-themechange', { detail: { theme: currentTheme } }));
+    }
+
+    async function bodyBytes(body) {
+      if (body == null) return new ArrayBuffer(0);
+      if (typeof body === 'string') return new TextEncoder().encode(body).buffer;
+      if (body instanceof ArrayBuffer) return body.slice(0);
+      if (ArrayBuffer.isView(body)) return body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
+      throw new TypeError('请求正文只支持 string、ArrayBuffer 或 TypedArray');
+    }
+
+    function nextRequestId() {
+      sequence += 1;
+      if (!Number.isSafeInteger(sequence)) throw new Error('插件页面请求序号已耗尽');
+      return sequence;
+    }
+
+    function post(type, id, payload, transfer = []) {
+      parent.postMessage({
+        target: initial.target,
+        version: initial.version,
+        channel: initial.channel,
+        session: initial.session,
+        type,
+        id,
+        payload,
+      }, initial.parentOrigin, transfer);
+    }
+
+    function invoke(kind, payload, transfer = []) {
+      if (pending.size >= maximumInFlight) return Promise.reject(new Error('插件管理请求已达并发上限'));
+      const id = nextRequestId();
+      return new Promise((resolve, reject) => {
+        const timer = window.setTimeout(() => {
+          pending.delete(id);
+          reject(new Error('插件管理请求超时'));
+        }, 30000);
+        pending.set(id, { resolve, reject, timer });
+        post(kind, id, payload, transfer);
+      });
+    }
+
+    function reportContentHeight() {
+      // 不读 documentElement.scrollHeight，避免当前 iframe 高度阻止内容收缩。
+      const height = Math.max(1, Math.ceil(document.body.getBoundingClientRect().height));
+      if (height === previousHeight) return;
+      previousHeight = height;
+      post('resize', nextRequestId(), { height });
+    }
+
+    async function observeContentHeight() {
+      // load 后先触发布局，让实际使用的字体进入加载集合，再等待字体与布局就绪。
+      document.body.getBoundingClientRect();
+      await document.fonts.ready;
+      if (disposed) return;
+      // 首次上报不依赖渲染回调，后台或视口外的 iframe 也能完成初始化。
+      reportContentHeight();
+      resizeObserver = new ResizeObserver(() => {
+        if (resizeFrame) return;
+        resizeFrame = requestAnimationFrame(() => {
+          resizeFrame = 0;
+          reportContentHeight();
+        });
+      });
+      resizeObserver.observe(document.body, { box: 'border-box' });
+    }
+
+    window.addEventListener('load', observeContentHeight, { once: true });
+
+    async function request(input) {
+      if (!input || typeof input !== 'object') throw new TypeError('插件管理请求无效');
+      const method = String(input.method || '').toUpperCase();
+      const path = String(input.path || '');
+      const query = input.query == null ? '' : String(input.query);
+      const contentType = input.contentType == null ? undefined : String(input.contentType);
+      if (new TextEncoder().encode(query).byteLength > maximumQueryBytes || query.includes('#') || query.startsWith('?')) throw new TypeError('插件管理查询参数无效');
+      const body = await bodyBytes(input.body);
+      if (body.byteLength > maximumBodyBytes) throw new TypeError('插件管理请求正文超过 1 MiB');
+      return invoke('request', { method, path, query, contentType, body }, [body]);
+    }
+
+    function callbackTicket(input) {
+      if (!input || typeof input !== 'object') return Promise.reject(new TypeError('插件回调票据请求无效'));
+      return invoke('callback-ticket', { path: String(input.path || ''), ttlSeconds: Number(input.ttlSeconds) });
+    }
+
+    function abortError(reason) {
+      return reason instanceof Error ? reason : new DOMException('模型请求已取消', 'AbortError');
+    }
+
+    function clearModelOperation(operation) {
+      if (modelOperations.get(operation.id) !== operation) return;
+      modelOperations.delete(operation.id);
+      clearTimeout(operation.timer);
+      if (operation.signal) operation.signal.removeEventListener('abort', operation.abort);
+    }
+
+    function settleModelPull(operation, error) {
+      const resolve = operation.pullResolve;
+      const reject = operation.pullReject;
+      operation.pullResolve = undefined;
+      operation.pullReject = undefined;
+      operation.pullPromise = undefined;
+      operation.pullId = undefined;
+      if (error) reject?.(error);
+      else resolve?.();
+    }
+
+    function failModelOperation(operation, error, notifyParent) {
+      if (modelOperations.get(operation.id) !== operation) return;
+      clearModelOperation(operation);
+      settleModelPull(operation, error);
+      if (operation.controller) {
+        try { operation.controller.error(error); } catch {}
+      } else {
+        operation.reject(error);
+      }
+      if (notifyParent) post('models-cancel', operation.id);
+    }
+
+    function finishModelOperation(operation) {
+      if (modelOperations.get(operation.id) !== operation) return;
+      clearModelOperation(operation);
+      settleModelPull(operation);
+    }
+
+    function validateResponseHeaders(value) {
+      if (!Array.isArray(value) || value.length > 32) throw new Error('模型响应头无效');
+      const headers = [];
+      let total = 0;
+      for (const entry of value) {
+        if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== 'string' || typeof entry[1] !== 'string') throw new Error('模型响应头无效');
+        const name = entry[0].toLowerCase();
+        const headerValue = entry[1];
+        total += name.length + headerValue.length;
+        if (!safeModelHeaders.has(name) || headerValue.length > 8192 || total > 32768 || /[\\u0000-\\u0008\\u000A-\\u001F\\u007F]/u.test(headerValue)) throw new Error('模型响应头无效');
+        headers.push([name, headerValue]);
+      }
+      return headers;
+    }
+
+    function handleModelMessage(message) {
+      const operation = modelOperations.get(message.id);
+      if (!operation) return;
+      if (message.type === 'models-error') {
+        const text = typeof message.error === 'string' && message.error ? message.error : '模型请求失败';
+        failModelOperation(operation, new Error(text), false);
+        return;
+      }
+      if (message.type === 'models-response') {
+        if (operation.controller || operation.responseStarted || !message.payload || typeof message.payload !== 'object') {
+          failModelOperation(operation, new Error('模型响应协议无效'), true);
+          return;
+        }
+        try {
+          const status = message.payload.status;
+          const statusText = message.payload.statusText == null ? '' : message.payload.statusText;
+          const hasBody = message.payload.hasBody;
+          if (!Number.isSafeInteger(status) || status < 200 || status > 599 || typeof statusText !== 'string' || statusText.length > 256 || /[\\u0000-\\u001F\\u007F]/u.test(statusText) || typeof hasBody !== 'boolean') throw new Error('模型响应状态无效');
+          const headers = validateResponseHeaders(message.payload.headers);
+          operation.responseStarted = true;
+          if (!hasBody) {
+            finishModelOperation(operation);
+            operation.resolve(new Response(null, { status, statusText, headers }));
+            return;
+          }
+          const stream = new ReadableStream({
+            start(controller) {
+              operation.controller = controller;
+            },
+            pull() {
+              if (modelOperations.get(operation.id) !== operation) return undefined;
+              if (operation.pullPromise) return operation.pullPromise;
+              operation.pullSequence += 1;
+              operation.pullId = operation.pullSequence;
+              operation.pullPromise = new Promise((resolve, reject) => {
+                operation.pullResolve = resolve;
+                operation.pullReject = reject;
+                post('models-pull', operation.id, { pullId: operation.pullId });
+              });
+              return operation.pullPromise;
+            },
+            cancel() {
+              if (modelOperations.get(operation.id) === operation) {
+                clearModelOperation(operation);
+                settleModelPull(operation);
+                post('models-cancel', operation.id);
+              }
+            },
+          }, { highWaterMark: 0 });
+          operation.resolve(new Response(stream, { status, statusText, headers }));
+        } catch (error) {
+          failModelOperation(operation, error instanceof Error ? error : new Error('模型响应协议无效'), true);
+        }
+        return;
+      }
+      if (!operation.controller || !operation.responseStarted) {
+        failModelOperation(operation, new Error('模型响应协议无效'), true);
+        return;
+      }
+      if (message.type === 'models-chunk') {
+        const pullId = message.payload?.pullId;
+        const body = message.payload?.body;
+        if (!operation.pullPromise || !Number.isSafeInteger(pullId) || pullId !== operation.pullId || !(body instanceof ArrayBuffer) || body.byteLength === 0 || body.byteLength > maximumModelChunkBytes) {
+          failModelOperation(operation, new Error('模型响应分块无效'), true);
+          return;
+        }
+        try {
+          operation.controller.enqueue(new Uint8Array(body));
+          settleModelPull(operation);
+        } catch (error) {
+          failModelOperation(operation, error instanceof Error ? error : new Error('模型响应读取失败'), true);
+        }
+        return;
+      }
+      if (message.type === 'models-complete') {
+        const pullId = message.payload?.pullId;
+        if (!operation.pullPromise || !Number.isSafeInteger(pullId) || pullId !== operation.pullId) {
+          failModelOperation(operation, new Error('模型响应结束标记无效'), true);
+          return;
+        }
+        try { operation.controller.close(); } catch {}
+        finishModelOperation(operation);
+      }
+    }
+
+    function modelResponses(input) {
+      if (!input || typeof input !== 'object' || !input.body || typeof input.body !== 'object' || Array.isArray(input.body)) return Promise.reject(new TypeError('Responses 请求正文必须是 JSON 对象'));
+      if (typeof input.clientKeyId !== 'string' || !input.clientKeyId || input.clientKeyId !== input.clientKeyId.trim() || input.clientKeyId.length > 128 || /[\\u0000-\\u001F\\u007F]/u.test(input.clientKeyId)) return Promise.reject(new TypeError('clientKeyId 无效'));
+      if (input.signal !== undefined && !(input.signal instanceof AbortSignal)) return Promise.reject(new TypeError('signal 必须是 AbortSignal'));
+      if (input.signal?.aborted) return Promise.reject(abortError(input.signal.reason));
+      if (modelOperations.size >= maximumModelInFlight) return Promise.reject(new Error('模型请求已达并发上限'));
+      let body;
+      try {
+        body = JSON.stringify(input.body);
+      } catch {
+        return Promise.reject(new TypeError('Responses 请求正文必须可序列化为 JSON'));
+      }
+      if (typeof body !== 'string' || new TextEncoder().encode(body).byteLength > maximumModelBodyBytes) return Promise.reject(new TypeError('Responses 请求正文超过 8 MiB'));
+      const id = nextRequestId();
+      return new Promise((resolve, reject) => {
+        const operation = {
+          id,
+          resolve,
+          reject,
+          signal: input.signal,
+          abort: undefined,
+          timer: undefined,
+          controller: undefined,
+          responseStarted: false,
+          pullPromise: undefined,
+          pullResolve: undefined,
+          pullReject: undefined,
+          pullSequence: 0,
+          pullId: undefined,
+        };
+        operation.abort = () => failModelOperation(operation, abortError(input.signal?.reason), true);
+        operation.timer = window.setTimeout(() => failModelOperation(operation, new Error('模型请求超过 10 分钟'), true), modelRequestDeadlineMs);
+        modelOperations.set(id, operation);
+        input.signal?.addEventListener('abort', operation.abort, { once: true });
+        post('models-request', id, { clientKeyId: input.clientKeyId, body });
+      });
+    }
+
+    document.addEventListener('click', (event) => {
+      if (event.defaultPrevented || !(event.target instanceof Element)) return;
+      const submitter = event.target.closest('button, input');
+      if (!(submitter instanceof HTMLButtonElement || submitter instanceof HTMLInputElement)) return;
+      const type = submitter.type.toLowerCase();
+      if (type !== 'submit' && type !== 'image') return;
+      const form = submitter.form;
+      if (!form) return;
+      event.preventDefault();
+      queueMicrotask(() => {
+        if (!form.isConnected || !submitter.isConnected) return;
+        if (!submitter.formNoValidate && !form.reportValidity()) return;
+        form.dispatchEvent(new SubmitEvent('submit', { bubbles: true, cancelable: true, submitter }));
+      });
+    });
+
+    window.addEventListener('message', (event) => {
+      if (event.source !== parent || event.origin !== initial.parentOrigin) return;
+      const message = event.data;
+      if (!message || message.target !== initial.target || message.version !== initial.version || message.channel !== initial.channel || message.session !== initial.session) return;
+      if (message.type === 'theme') {
+        applyTheme(message.payload);
+        return;
+      }
+      if (message.type === 'layout') {
+        applyLayout(message.payload?.viewportHeight);
+        return;
+      }
+      if (!Number.isSafeInteger(message.id) || message.id < 1) return;
+      if (message.type === 'models-response' || message.type === 'models-chunk' || message.type === 'models-complete' || message.type === 'models-error') {
+        handleModelMessage(message);
+        return;
+      }
+      if (message.type !== 'result') return;
+      const operation = pending.get(message.id);
+      if (!operation) return;
+      pending.delete(message.id);
+      clearTimeout(operation.timer);
+      if (message.ok) operation.resolve(message.payload);
+      else operation.reject(new Error(typeof message.error === 'string' ? message.error : '插件管理请求失败'));
+    });
+
+    window.addEventListener('pagehide', () => {
+      disposed = true;
+      resizeObserver?.disconnect();
+      cancelAnimationFrame(resizeFrame);
+      for (const operation of [...modelOperations.values()]) {
+        clearModelOperation(operation);
+        settleModelPull(operation);
+        post('models-cancel', operation.id);
+      }
+    }, { once: true });
+
+    const api = {
+      version: initial.version,
+      plugin: Object.freeze(initial.plugin),
+      page: Object.freeze(initial.page),
+      get theme() { return currentTheme; },
+      request,
+      callbackTicket,
+      models: Object.freeze({ responses: modelResponses }),
+      resourceUrl(path) {
+        const key = String(path);
+        if (!Object.prototype.hasOwnProperty.call(initial.resourceUrls, key)) throw new Error('资源未注册或不可作为页面子资源');
+        const value = initial.resourceUrls[key];
+        return value;
+      },
+    };
+    Object.defineProperty(window, 'codexProxyPlugin', { value: Object.freeze(api), configurable: false, writable: false });
+    applyTheme(initial.theme);
+    applyLayout(initial.viewportHeight);
+  })();`
+}
diff --git a/frontend/src/views/plugins/utils/catalog.ts b/frontend/src/views/plugins/utils/catalog.ts
new file mode 100644
index 000000000..0bb630ed4
--- /dev/null
+++ b/frontend/src/views/plugins/utils/catalog.ts
@@ -0,0 +1,84 @@
+import type { PluginArtifact, PluginInstance, PluginUpdateSourceBinding } from '@/api'
+
+export interface InstalledPlugin {
+  id: string
+  artifact: PluginArtifact
+  artifacts: PluginArtifact[]
+  configurations: PluginInstance[]
+  source?: PluginUpdateSourceBinding
+}
+
+export type PluginCatalogStatus = 'unaccepted' | 'unconfigured' | 'enabled' | 'disabled' | 'pending' | 'failed'
+
+export function groupInstalledPlugins(artifacts: PluginArtifact[], instances: PluginInstance[], sources: PluginUpdateSourceBinding[]): InstalledPlugin[] {
+  const groups = new Map<string, InstalledPlugin>()
+  // 尚无当前配置时使用最近安装的包，不把字符串排序误当作语义版本比较。
+  for (const artifact of [...artifacts].sort((a, b) => b.installedAt.localeCompare(a.installedAt))) {
+    const id = artifact.metadata.pluginId
+    const group = groups.get(id)
+    if (group)
+      group.artifacts.push(artifact)
+    else groups.set(id, { id, artifact, artifacts: [artifact], configurations: [], source: sources.find(source => source.pluginId === id) })
+  }
+  const artifactPlugins = new Map(artifacts.map(artifact => [artifact.metadata.sha256, artifact.metadata.pluginId]))
+  for (const instance of instances) {
+    const id = artifactPlugins.get(instance.artifactSha256)
+    if (id)
+      groups.get(id)?.configurations.push(instance)
+  }
+  for (const plugin of groups.values()) {
+    const current = currentPluginInstance(plugin)
+    plugin.artifact = plugin.artifacts.find(artifact => artifact.metadata.sha256 === current?.artifactSha256) ?? plugin.artifact
+  }
+  return [...groups.values()]
+}
+
+export function configurationStatus(instance: PluginInstance): PluginCatalogStatus {
+  if (instance.configurationRequired)
+    return 'unconfigured'
+  if (!instance.enabled)
+    return 'disabled'
+  if (['blocked', 'preparation_failed', 'faulted'].includes(instance.runtime.status))
+    return 'failed'
+  return instance.runtime.status === 'running' ? 'enabled' : 'pending'
+}
+
+export function pluginStatus(plugin: InstalledPlugin): PluginCatalogStatus {
+  if (!plugin.artifacts.some(artifact => artifact.acceptedAt))
+    return 'unaccepted'
+  if (plugin.configurations.filter(instance => instance.enabled).length > 1)
+    return 'failed'
+  const instance = currentPluginInstance(plugin)
+  return instance ? configurationStatus(instance) : 'unconfigured'
+}
+
+export const PLUGIN_STATUS_LABELS: Record<PluginCatalogStatus, string> = {
+  unaccepted: '待安装',
+  unconfigured: '待配置',
+  enabled: '已启用',
+  disabled: '已停用',
+  pending: '等待生效',
+  failed: '需要处理',
+}
+
+export function pluginStatusType(status: PluginCatalogStatus) {
+  if (status === 'enabled')
+    return 'success' as const
+  if (status === 'failed')
+    return 'danger' as const
+  if (status === 'pending' || status === 'unconfigured' || status === 'unaccepted')
+    return 'warning' as const
+  return 'neutral' as const
+}
+
+export function currentPluginInstance(plugin: InstalledPlugin): PluginInstance | undefined {
+  return [...plugin.configurations].sort((left, right) => Number(right.enabled) - Number(left.enabled) || right.revision - left.revision)[0]
+}
+
+export function hasPluginSettings(artifact: PluginArtifact): boolean {
+  const schema = artifact.metadata.configurationSchema
+  return Boolean(artifact.metadata.secretFields.length
+    || Object.keys((schema.properties ?? {}) as Record<string, unknown>).length
+    || schema.additionalProperties !== false
+    || artifact.metadata.contributes.frontend_authentication)
+}
diff --git a/frontend/src/views/plugins/utils/model.ts b/frontend/src/views/plugins/utils/model.ts
new file mode 100644
index 000000000..72d906fef
--- /dev/null
+++ b/frontend/src/views/plugins/utils/model.ts
@@ -0,0 +1,164 @@
+import type {
+  PluginArtifact,
+  PluginArtifactMetadata,
+  PluginInstance,
+  PluginInstanceRuntimeStatus,
+  PluginSource,
+  PluginUpdateSource,
+  VerifyRemotePluginRequest,
+} from '@/api'
+
+export type PluginInstallSelection = File | VerifyRemotePluginRequest
+
+export function pluginInstallSelectionKey(selection: PluginInstallSelection) {
+  return selection instanceof File ? selection : JSON.stringify(selection)
+}
+
+export interface JsonSchema {
+  type?: string | string[]
+  title?: string
+  description?: string
+  default?: unknown
+  enum?: unknown[]
+  properties?: Record<string, JsonSchema>
+  required?: string[]
+  minimum?: number
+  maximum?: number
+  minLength?: number
+  maxLength?: number
+  pattern?: string
+  items?: JsonSchema
+  additionalProperties?: boolean | JsonSchema
+}
+
+export const PLUGIN_CAPABILITY_LABELS: Record<string, string> = {
+  models: '模型目录',
+  authentication: '账号认证',
+  frontend_authentication: '客户端认证',
+  scheduler: '请求调度',
+  model_router: '模型路由',
+  executor: 'Provider 执行',
+  middleware: '请求中间件',
+  request_lifecycle: '请求生命周期',
+  web_socket_observer: 'WebSocket 观察',
+  usage: '用量处理',
+  command_line: '命令行',
+  management: '管理扩展',
+  quota: '额度查询',
+  request_profile: '请求画像',
+  account_management: '账号管理',
+  billing: '计费处理',
+  maintenance: '维护任务',
+}
+
+export function pluginCapabilityLabel(capability: string) {
+  return PLUGIN_CAPABILITY_LABELS[capability] ?? capability
+}
+
+export function pluginContributionEntries(metadata: PluginArtifactMetadata) {
+  return Object.entries(metadata.contributes)
+}
+
+export function normalizePluginRepository(value: string) {
+  // GitHub 下载端使用小写仓库路径，凭据的路径范围必须采用相同规范。
+  return value.trim().replace(/^https:\/\/github\.com\//i, '').replace(/\/$/, '').replace(/\.git$/i, '').toLowerCase()
+}
+
+export function pluginContributionForCapability(
+  metadata: PluginArtifactMetadata,
+  capability: string,
+) {
+  return metadata.contributes[capability]
+}
+
+export function pluginCapabilityForContribution(
+  metadata: PluginArtifactMetadata,
+  contributionId: string,
+) {
+  return pluginContributionEntries(metadata).find(([, contribution]) =>
+    contribution.id === contributionId,
+  )?.[0]
+}
+
+export const PLUGIN_RUNTIME_STATUS_LABELS: Record<PluginInstanceRuntimeStatus, string> = {
+  disabled: '已停用',
+  awaiting_publication: '等待发布',
+  preparing: '准备中',
+  running: '已启用',
+  blocked: '发布阻塞',
+  preparation_failed: '准备失败',
+  faulted: '运行故障',
+  draining: '排空中',
+}
+
+export function pluginRuntimeStatusLabel(status: PluginInstanceRuntimeStatus) {
+  return PLUGIN_RUNTIME_STATUS_LABELS[status]
+}
+
+export function sourceLabel(source: PluginSource | PluginUpdateSource) {
+  switch (source.kind) {
+    case 'builtin':
+      return '随版本提供'
+    case 'upload':
+      return '本地上传'
+    case 'url':
+      return '固定 URL'
+    case 'github':
+      return 'GitHub Release'
+  }
+}
+
+export function sourceDetail(source: PluginSource | PluginUpdateSource) {
+  switch (source.kind) {
+    case 'builtin':
+      return 'release' in source ? source.release : '发行清单'
+    case 'upload':
+      return '无远程更新来源'
+    case 'url':
+      return source.url
+    case 'github':
+      return 'tag' in source ? `${source.repository}@${source.tag}` : source.repository
+  }
+}
+
+export function shortDigest(digest: string) {
+  return digest.length > 15 ? `${digest.slice(0, 8)}…${digest.slice(-6)}` : digest
+}
+
+export function artifactForInstance(instance: PluginInstance, artifacts: PluginArtifact[]) {
+  return artifacts.find(artifact => artifact.metadata.sha256 === instance.artifactSha256)
+}
+
+export function cloneJsonValue<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T
+}
+
+export function configurationForSchema(
+  schemaValue: Record<string, unknown>,
+  current: Record<string, unknown> = {},
+  excludedFields: string[] = [],
+) {
+  const schema = schemaValue as JsonSchema
+  let result: Record<string, unknown> = cloneJsonValue(current)
+  for (const [name, property] of Object.entries(schema.properties ?? {})) {
+    if (!excludedFields.includes(name) && !Object.hasOwn(result, name) && property.default !== undefined) {
+      // 计算属性保留 __proto__ 等合法 JSON 字段，不触发普通对象的原型 setter
+      result = { ...result, [name]: cloneJsonValue(property.default) }
+    }
+  }
+  return result
+}
+
+export function pluginIdOptions(artifacts: PluginArtifact[]) {
+  const names = new Map<string, string>()
+  for (const artifact of artifacts)
+    names.set(artifact.metadata.pluginId, artifact.metadata.displayName)
+  return [...names].map(([value, name]) => ({ value, label: `${name} · ${value}` }))
+}
+
+export function uniquePluginArtifacts(artifacts: PluginArtifact[]) {
+  return [...artifacts].sort((left, right) => {
+    const byId = left.metadata.pluginId.localeCompare(right.metadata.pluginId)
+    return byId || right.metadata.version.localeCompare(left.metadata.version, undefined, { numeric: true })
+  })
+}
diff --git a/frontend/src/views/plugins/utils/navigation.ts b/frontend/src/views/plugins/utils/navigation.ts
new file mode 100644
index 000000000..0d63c60a7
--- /dev/null
+++ b/frontend/src/views/plugins/utils/navigation.ts
@@ -0,0 +1,22 @@
+import type { PluginManagementPage, PluginManagementView } from '@/api'
+
+export const PLUGIN_PAGE_ROUTE_NAME = 'plugin-page'
+
+export function pluginPageLocation(
+  view: PluginManagementView,
+  page: PluginManagementPage,
+) {
+  return {
+    name: PLUGIN_PAGE_ROUTE_NAME,
+    params: {
+      instanceId: view.target.instanceId,
+      pageId: page.id,
+    },
+  }
+}
+
+export function shortPluginInstanceId(instanceId: string) {
+  return instanceId.length > 12
+    ? `${instanceId.slice(0, 7)}…${instanceId.slice(-4)}`
+    : instanceId
+}
diff --git a/frontend/src/views/proxies/components/ProxyAccountsModal.vue b/frontend/src/views/proxies/components/ProxyAccountsModal.vue
index 4b2023263..5734f1f77 100644
--- a/frontend/src/views/proxies/components/ProxyAccountsModal.vue
+++ b/frontend/src/views/proxies/components/ProxyAccountsModal.vue
@@ -1,15 +1,9 @@
 <script setup lang="ts">
 import type { OutboundProxyAccount, OutboundProxyRecord } from '@/api'
+import { BaseConfirmModal, BaseIconButton, BaseInput, BaseModal, BaseTable, BaseTablePagination, defineTableColumns } from '@codex-proxy/ui'
 import { Search, Unlink } from '@lucide/vue'
 import { computed, shallowRef, watch } from 'vue'
 import AccountGroupMarks from '@/components/AccountGroupMarks.vue'
-import BaseConfirmModal from '@/components/base/BaseConfirmModal.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseTablePagination from '@/components/base/BaseTable/BaseTablePagination.vue'
-import { defineTableColumns } from '@/components/base/BaseTable/columns'
-import BaseTable from '@/components/base/BaseTable/index.vue'
 import ProviderIconGroup from '@/components/ProviderIconGroup.vue'
 import AccountPlanBadge from '@/views/accounts/components/AccountPlanBadge.vue'
 import { stablePresetVisualToneClass } from '@/views/accounts/utils/visualTone'
diff --git a/frontend/src/views/proxies/components/ProxyFormModal.vue b/frontend/src/views/proxies/components/ProxyFormModal.vue
index 46d2a5410..af7f8e418 100644
--- a/frontend/src/views/proxies/components/ProxyFormModal.vue
+++ b/frontend/src/views/proxies/components/ProxyFormModal.vue
@@ -1,14 +1,8 @@
 <script setup lang="ts">
 import type { OutboundProxyRecord, RequestLocation } from '@/api'
+import { BaseButton, BaseForm, BaseFormItem, BaseIconButton, BaseInput, BaseModal, BaseSwitch } from '@codex-proxy/ui'
 import { Eye, EyeOff, Save, Wifi } from '@lucide/vue'
 import { computed, shallowRef, watch } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseSwitch from '@/components/base/BaseSwitch.vue'
 import RequestLocationFields from '@/components/RequestLocationFields.vue'
 
 const props = defineProps<{
diff --git a/frontend/src/views/proxies/composables/useProxyAccounts.ts b/frontend/src/views/proxies/composables/useProxyAccounts.ts
index 50cc12f32..b23e89012 100644
--- a/frontend/src/views/proxies/composables/useProxyAccounts.ts
+++ b/frontend/src/views/proxies/composables/useProxyAccounts.ts
@@ -1,7 +1,7 @@
+import { toast } from '@codex-proxy/ui'
 import { watchDebounced } from '@vueuse/core'
 import { computed, shallowRef, watch } from 'vue'
 import { getProxyAccounts, removeProxyAccount } from '@/api'
-import { toast } from '@/components/base/BaseToast'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 import { usePagedQuery } from '@/composables/usePagedQuery'
 
diff --git a/frontend/src/views/proxies/index.vue b/frontend/src/views/proxies/index.vue
index ddda2ccdb..505d2c9c8 100644
--- a/frontend/src/views/proxies/index.vue
+++ b/frontend/src/views/proxies/index.vue
@@ -1,19 +1,10 @@
 <script setup lang="ts">
 import type { OutboundProxyRecord } from '@/api'
+import { BaseButton, BaseCard, BaseConfirmModal, BaseIconButton, BaseInput, BasePageHeader, BaseTable, BaseTablePagination, defineTableColumns, toast } from '@codex-proxy/ui'
 import { LockKeyhole, MapPin, Pencil, Plus, Search, Trash2, Users, Wifi } from '@lucide/vue'
 import { watchDebounced } from '@vueuse/core'
 import { computed, onMounted, reactive, ref, shallowRef, watch } from 'vue'
 import { createProxy, deleteProxy, getProxies, probeProxy, testProxy, updateProxy } from '@/api'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseConfirmModal from '@/components/base/BaseConfirmModal.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BasePageHeader from '@/components/base/BasePageHeader.vue'
-import BaseTablePagination from '@/components/base/BaseTable/BaseTablePagination.vue'
-import { defineTableColumns } from '@/components/base/BaseTable/columns'
-import BaseTable from '@/components/base/BaseTable/index.vue'
-import { toast } from '@/components/base/BaseToast'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 import { usePagedQuery } from '@/composables/usePagedQuery'
 import { formatDateTime } from '@/utils/date'
diff --git a/frontend/src/views/settings/components/AccountAutoFreezeCard.vue b/frontend/src/views/settings/components/AccountAutoFreezeCard.vue
index 7ec67a016..8549b6a64 100644
--- a/frontend/src/views/settings/components/AccountAutoFreezeCard.vue
+++ b/frontend/src/views/settings/components/AccountAutoFreezeCard.vue
@@ -1,15 +1,9 @@
 <script setup lang="ts">
+import { BaseCard, BaseCheckbox, BaseForm, BaseFormItem, BaseInput, BasePopover, BaseSwitch } from '@codex-proxy/ui'
+
 import { Activity, CircleAlert, Gauge, Snowflake, Timer } from '@lucide/vue'
 import { useId } from 'vue'
 
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseCheckbox from '@/components/base/BaseCheckbox.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BasePopover from '@/components/base/BasePopover.vue'
-import BaseSwitch from '@/components/base/BaseSwitch.vue'
-
 const enabled = defineModel<boolean>('enabled', { required: true })
 const threshold = defineModel<string>('threshold', { required: true })
 const windowSeconds = defineModel<string>('windowSeconds', { required: true })
diff --git a/frontend/src/views/settings/components/AdminApiKeyCard.vue b/frontend/src/views/settings/components/AdminApiKeyCard.vue
index ffba6b104..bd8f077ba 100644
--- a/frontend/src/views/settings/components/AdminApiKeyCard.vue
+++ b/frontend/src/views/settings/components/AdminApiKeyCard.vue
@@ -1,10 +1,7 @@
 <script setup lang="ts">
-import { Copy, KeyRound, Trash2 } from '@lucide/vue'
+import { BaseButton, BaseCard, BaseIconButton, BaseMotionIcon } from '@codex-proxy/ui'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseMotionIcon from '@/components/base/BaseMotionIcon.vue'
+import { Copy, KeyRound, Trash2 } from '@lucide/vue'
 
 interface AdminApiKeyStatus {
   exists: boolean
diff --git a/frontend/src/views/settings/components/AdminPasswordCard.vue b/frontend/src/views/settings/components/AdminPasswordCard.vue
index f70a95b2e..b973eb691 100644
--- a/frontend/src/views/settings/components/AdminPasswordCard.vue
+++ b/frontend/src/views/settings/components/AdminPasswordCard.vue
@@ -1,9 +1,7 @@
 <script setup lang="ts">
+import { BaseButton, BaseCard, BaseMotionIcon } from '@codex-proxy/ui'
 import { LockKeyhole } from '@lucide/vue'
 import { shallowRef } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseMotionIcon from '@/components/base/BaseMotionIcon.vue'
 import ChangePasswordModal from './ChangePasswordModal.vue'
 
 const open = shallowRef(false)
diff --git a/frontend/src/views/settings/components/ChangePasswordModal.vue b/frontend/src/views/settings/components/ChangePasswordModal.vue
index 52e763dab..508e4545b 100644
--- a/frontend/src/views/settings/components/ChangePasswordModal.vue
+++ b/frontend/src/views/settings/components/ChangePasswordModal.vue
@@ -1,12 +1,8 @@
 <script setup lang="ts">
+import { BaseButton, BaseInput, BaseModal, BaseFormItem as FormItem, toast } from '@codex-proxy/ui'
 import { computed, reactive, shallowRef, useId, watch } from 'vue'
 import { useRouter } from 'vue-router'
 import { changeAdminPassword } from '@/api'
-import BaseButton from '@/components/base/BaseButton.vue'
-import FormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import { toast } from '@/components/base/BaseToast'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 import { useAuthStore } from '@/stores/modules/auth'
 
diff --git a/frontend/src/views/settings/components/ClientProfileCard.vue b/frontend/src/views/settings/components/ClientProfileCard.vue
index ca79f7ed1..1d9349869 100644
--- a/frontend/src/views/settings/components/ClientProfileCard.vue
+++ b/frontend/src/views/settings/components/ClientProfileCard.vue
@@ -1,31 +1,25 @@
 <script setup lang="ts">
-import type { ClientProfileSelection, XaiClientProfileSelection } from '@/api/modules/client-profiles'
-import { Openai, Xai } from '@boxicons/vue'
-import { shallowRef } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import ClientProfileEditor from '@/components/client-profile/ClientProfileEditor.vue'
-import XaiClientProfileEditor from '@/components/client-profile/XaiClientProfileEditor.vue'
-import { PROVIDER_DISPLAY_NAMES } from '@/utils/providers'
+import type { ProviderRequestProfiles } from '@/api/modules/client-profiles'
+import { BaseCard } from '@codex-proxy/ui'
+import ProviderRequestProfilesEditor from '@/components/client-profile/ProviderRequestProfilesEditor.vue'
 
 withDefaults(defineProps<{ active?: boolean, disabled?: boolean }>(), {
   active: true,
   disabled: false,
 })
 
-const openai = defineModel<ClientProfileSelection | null>('openai', { required: true })
-const xai = defineModel<XaiClientProfileSelection | null>('xai', { required: true })
-const provider = shallowRef('openai')
-const providerOptions = [
-  { label: PROVIDER_DISPLAY_NAMES.openai, value: 'openai', icon: Openai },
-  { label: PROVIDER_DISPLAY_NAMES.xai, value: 'xai', icon: Xai },
-]
+const model = defineModel<ProviderRequestProfiles>({ required: true })
 </script>
 
 <template>
   <BaseCard>
-    <template #header>
-      <div class="flex max-w-6xl items-start justify-between gap-4">
+    <ProviderRequestProfilesEditor
+      v-model="model"
+      :active="active"
+      :disabled="disabled"
+      class="max-w-6xl"
+    >
+      <template #heading>
         <div class="min-w-0 pt-0.5">
           <h2 class="m-0 text-xl leading-[1.15] font-heavy text-cp-text text-balance">
             客户端身份
@@ -34,31 +28,7 @@ const providerOptions = [
             配置网关向上游声明的客户端类型、版本与请求头
           </p>
         </div>
-        <BaseSegmented
-          v-model="provider"
-          label="客户端身份平台"
-          class="w-20 shrink-0"
-          display="icon"
-          :options="providerOptions"
-          :disabled="disabled"
-        />
-      </div>
-    </template>
-    <ClientProfileEditor
-      v-if="openai"
-      v-show="provider === 'openai'"
-      v-model="openai"
-      :active="active"
-      :disabled="disabled"
-      class="max-w-6xl"
-    />
-    <XaiClientProfileEditor
-      v-if="xai"
-      v-show="provider === 'xai'"
-      v-model="xai"
-      :active="active"
-      :disabled="disabled"
-      class="max-w-6xl"
-    />
+      </template>
+    </ProviderRequestProfilesEditor>
   </BaseCard>
 </template>
diff --git a/frontend/src/views/settings/components/ModelAliasesCard.vue b/frontend/src/views/settings/components/ModelAliasesCard.vue
index 683ba44c2..4875e3ce5 100644
--- a/frontend/src/views/settings/components/ModelAliasesCard.vue
+++ b/frontend/src/views/settings/components/ModelAliasesCard.vue
@@ -1,10 +1,7 @@
 <script setup lang="ts">
-import { Plus, Trash2 } from '@lucide/vue'
+import { BaseButton, BaseCard, BaseIconButton, BaseInput } from '@codex-proxy/ui'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
+import { Plus, Trash2 } from '@lucide/vue'
 
 withDefaults(defineProps<{
   mappings: Array<{ requestedModel: string, upstreamModel: string }>
diff --git a/frontend/src/views/settings/components/RequestLocationCard.vue b/frontend/src/views/settings/components/RequestLocationCard.vue
index 5442d0e70..3fcc69f40 100644
--- a/frontend/src/views/settings/components/RequestLocationCard.vue
+++ b/frontend/src/views/settings/components/RequestLocationCard.vue
@@ -1,8 +1,6 @@
 <script setup lang="ts">
 import type { RequestLocation } from '@/api'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseSwitch from '@/components/base/BaseSwitch.vue'
+import { BaseCard, BaseForm, BaseSwitch } from '@codex-proxy/ui'
 import RequestLocationFields from '@/components/RequestLocationFields.vue'
 
 defineProps<{ disabled: boolean }>()
diff --git a/frontend/src/views/settings/components/RequestQueueCard.vue b/frontend/src/views/settings/components/RequestQueueCard.vue
index cbfb9ab6a..25f6f82c2 100644
--- a/frontend/src/views/settings/components/RequestQueueCard.vue
+++ b/frontend/src/views/settings/components/RequestQueueCard.vue
@@ -1,8 +1,5 @@
 <script setup lang="ts">
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
+import { BaseCard, BaseForm, BaseFormItem, BaseInput } from '@codex-proxy/ui'
 
 const maxWaitingPerKey = defineModel<string>('maxWaitingPerKey', { required: true })
 const maxWaitingPerAccount = defineModel<string>('maxWaitingPerAccount', { required: true })
diff --git a/frontend/src/views/settings/components/ResponseBodyLimitCard.vue b/frontend/src/views/settings/components/ResponseBodyLimitCard.vue
index d4559b576..af8b604a6 100644
--- a/frontend/src/views/settings/components/ResponseBodyLimitCard.vue
+++ b/frontend/src/views/settings/components/ResponseBodyLimitCard.vue
@@ -1,8 +1,5 @@
 <script setup lang="ts">
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
+import { BaseCard, BaseForm, BaseFormItem, BaseInput } from '@codex-proxy/ui'
 
 const model = defineModel<string>({ required: true })
 </script>
diff --git a/frontend/src/views/settings/components/RotationStrategyCard.vue b/frontend/src/views/settings/components/RotationStrategyCard.vue
index fcfc90d6c..733f55cc3 100644
--- a/frontend/src/views/settings/components/RotationStrategyCard.vue
+++ b/frontend/src/views/settings/components/RotationStrategyCard.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { rotationOptions } from '../constants'
-import BaseCard from '@/components/base/BaseCard.vue'
+import { BaseCard } from '@codex-proxy/ui'
 
 type RotationOption = (typeof rotationOptions)[number]
 type RotationStrategy = RotationOption['value']
diff --git a/frontend/src/views/settings/components/RuntimeSettingsCard.vue b/frontend/src/views/settings/components/RuntimeSettingsCard.vue
index bc397dd19..720f93456 100644
--- a/frontend/src/views/settings/components/RuntimeSettingsCard.vue
+++ b/frontend/src/views/settings/components/RuntimeSettingsCard.vue
@@ -1,10 +1,7 @@
 <script setup lang="ts">
-import { Gauge, Timer } from '@lucide/vue'
+import { BaseCard, BaseForm, BaseFormItem, BaseInput } from '@codex-proxy/ui'
 
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
+import { Gauge, Timer } from '@lucide/vue'
 
 const maxConcurrentPerAccount = defineModel<string>('maxConcurrentPerAccount', { required: true })
 const requestIntervalMs = defineModel<string>('requestIntervalMs', { required: true })
diff --git a/frontend/src/views/settings/components/SettingsAccessSection.vue b/frontend/src/views/settings/components/SettingsAccessSection.vue
index 42dbdf480..013d348f3 100644
--- a/frontend/src/views/settings/components/SettingsAccessSection.vue
+++ b/frontend/src/views/settings/components/SettingsAccessSection.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
+import { BaseConfirmModal } from '@codex-proxy/ui'
 import { onMounted } from 'vue'
-import BaseConfirmModal from '@/components/base/BaseConfirmModal.vue'
 import { useAdminApiKey } from '../composables/useAdminApiKey'
 import AdminApiKeyCard from './AdminApiKeyCard.vue'
 import AdminPasswordCard from './AdminPasswordCard.vue'
diff --git a/frontend/src/views/settings/components/TokenRefreshCard.vue b/frontend/src/views/settings/components/TokenRefreshCard.vue
index f11b64d01..a840c84f3 100644
--- a/frontend/src/views/settings/components/TokenRefreshCard.vue
+++ b/frontend/src/views/settings/components/TokenRefreshCard.vue
@@ -1,9 +1,6 @@
 <script setup lang="ts">
+import { BaseCard, BaseForm, BaseFormItem, BaseInput } from '@codex-proxy/ui'
 import { Timer, Zap } from '@lucide/vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
 
 const refreshMarginSeconds = defineModel<string>('refreshMarginSeconds', { required: true })
 const refreshConcurrency = defineModel<string>('refreshConcurrency', { required: true })
diff --git a/frontend/src/views/settings/components/backup/BackupRecordsCard.vue b/frontend/src/views/settings/components/backup/BackupRecordsCard.vue
index 96a31ee66..dbba9013e 100644
--- a/frontend/src/views/settings/components/backup/BackupRecordsCard.vue
+++ b/frontend/src/views/settings/components/backup/BackupRecordsCard.vue
@@ -1,14 +1,8 @@
 <script setup lang="ts">
 import type { BackupRecord } from '@/api'
 
+import { BaseButton, BaseCard, BaseConfirmModal, BaseIconButton, BaseTable, BaseTablePagination, defineTableColumns } from '@codex-proxy/ui'
 import { Download, Play, RefreshCw, Trash2 } from '@lucide/vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseConfirmModal from '@/components/base/BaseConfirmModal.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseTablePagination from '@/components/base/BaseTable/BaseTablePagination.vue'
-import { defineTableColumns } from '@/components/base/BaseTable/columns'
-import BaseTable from '@/components/base/BaseTable/index.vue'
 import { formatDateTime } from '@/utils/date'
 
 import BackupStatusBadge from './BackupStatusBadge.vue'
diff --git a/frontend/src/views/settings/components/backup/BackupScheduleCard.vue b/frontend/src/views/settings/components/backup/BackupScheduleCard.vue
index 2a1c2a8f2..7754bce54 100644
--- a/frontend/src/views/settings/components/backup/BackupScheduleCard.vue
+++ b/frontend/src/views/settings/components/backup/BackupScheduleCard.vue
@@ -1,13 +1,7 @@
 <script setup lang="ts">
-import { CalendarClock, Save } from '@lucide/vue'
+import { BaseButton, BaseCard, BaseCheckbox, BaseForm, BaseFormItem, BaseInput, BaseSelect } from '@codex-proxy/ui'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseCheckbox from '@/components/base/BaseCheckbox.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
+import { CalendarClock, Save } from '@lucide/vue'
 
 interface ScheduleForm {
   scheduleEnabled: boolean
diff --git a/frontend/src/views/settings/components/backup/BackupStorageCard.vue b/frontend/src/views/settings/components/backup/BackupStorageCard.vue
index 4a25a4d59..0691212f1 100644
--- a/frontend/src/views/settings/components/backup/BackupStorageCard.vue
+++ b/frontend/src/views/settings/components/backup/BackupStorageCard.vue
@@ -1,15 +1,9 @@
 <script setup lang="ts">
+import { BaseButton, BaseCard, BaseCheckbox, BaseForm, BaseFormItem, BaseIconButton, BaseInput } from '@codex-proxy/ui'
+
 import { CircleAlert, CircleCheck, DatabaseZap, Eye, EyeOff, Save } from '@lucide/vue'
 import { computed, shallowRef } from 'vue'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseCheckbox from '@/components/base/BaseCheckbox.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-
 interface StorageForm {
   endpoint: string
   region: string
diff --git a/frontend/src/views/settings/components/backup/R2GuideModal.vue b/frontend/src/views/settings/components/backup/R2GuideModal.vue
index 530bcc6c2..ce480f194 100644
--- a/frontend/src/views/settings/components/backup/R2GuideModal.vue
+++ b/frontend/src/views/settings/components/backup/R2GuideModal.vue
@@ -1,6 +1,5 @@
 <script setup lang="ts">
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
+import { BaseButton, BaseModal } from '@codex-proxy/ui'
 
 const open = defineModel<boolean>({ default: false })
 </script>
diff --git a/frontend/src/views/settings/components/client-version/components/ClientDesktopOfflineDownloads.vue b/frontend/src/views/settings/components/client-version/components/ClientDesktopOfflineDownloads.vue
index 4b24c168f..b2f76e919 100644
--- a/frontend/src/views/settings/components/client-version/components/ClientDesktopOfflineDownloads.vue
+++ b/frontend/src/views/settings/components/client-version/components/ClientDesktopOfflineDownloads.vue
@@ -1,11 +1,8 @@
 <script setup lang="ts">
 import type { ClientDownloadPackage, CodexDesktopWindowsDownloads } from '@/api'
-import { ArrowDownToLine, PackageOpen, RefreshCw } from '@lucide/vue'
+import { BaseButton, BaseEmpty, BaseIconButton, BaseSkeleton } from '@codex-proxy/ui'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseSkeleton from '@/components/base/BaseSkeleton.vue'
+import { ArrowDownToLine, PackageOpen, RefreshCw } from '@lucide/vue'
 import { formatDateTime } from '@/utils/date'
 
 import ClientInstallCommandList from './ClientInstallCommandList.vue'
diff --git a/frontend/src/views/settings/components/client-version/components/ClientInstallCommandList.vue b/frontend/src/views/settings/components/client-version/components/ClientInstallCommandList.vue
index 47241c1c2..9dbc3bf97 100644
--- a/frontend/src/views/settings/components/client-version/components/ClientInstallCommandList.vue
+++ b/frontend/src/views/settings/components/client-version/components/ClientInstallCommandList.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
-import { Copy } from '@lucide/vue'
+import { BaseIconButton } from '@codex-proxy/ui'
 
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
+import { Copy } from '@lucide/vue'
 import { useCopyText } from '@/composables/useCopyText'
 
 defineOptions({ name: 'ClientInstallCommandList' })
diff --git a/frontend/src/views/settings/components/client-version/components/ClientVersionGuideModal.vue b/frontend/src/views/settings/components/client-version/components/ClientVersionGuideModal.vue
index 4a425bcbe..e190959de 100644
--- a/frontend/src/views/settings/components/client-version/components/ClientVersionGuideModal.vue
+++ b/frontend/src/views/settings/components/client-version/components/ClientVersionGuideModal.vue
@@ -1,12 +1,10 @@
 <script setup lang="ts">
 import type { CodexDesktopWindowsDownloads } from '@/api'
+import { BaseButton, BaseModal, BaseSegmented } from '@codex-proxy/ui'
+
 import { MonitorUp, PackageOpen, TerminalSquare } from '@lucide/vue'
 import { shallowRef } from 'vue'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-
 import ClientCliInstallPanel from './ClientCliInstallPanel.vue'
 import ClientDesktopInstallPanel from './ClientDesktopInstallPanel.vue'
 
diff --git a/frontend/src/views/settings/components/client-version/components/ClientVersionPolicyCard.vue b/frontend/src/views/settings/components/client-version/components/ClientVersionPolicyCard.vue
index 96c4dd2a9..e24251024 100644
--- a/frontend/src/views/settings/components/client-version/components/ClientVersionPolicyCard.vue
+++ b/frontend/src/views/settings/components/client-version/components/ClientVersionPolicyCard.vue
@@ -1,10 +1,7 @@
 <script setup lang="ts">
-import { CircleHelp, MonitorUp, TerminalSquare } from '@lucide/vue'
+import { BaseCard, BaseForm, BaseFormItem, BaseInput } from '@codex-proxy/ui'
 
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
+import { CircleHelp, MonitorUp, TerminalSquare } from '@lucide/vue'
 
 defineOptions({ name: 'ClientVersionPolicyCard' })
 
diff --git a/frontend/src/views/settings/composables/useAdminApiKey.ts b/frontend/src/views/settings/composables/useAdminApiKey.ts
index 340574dab..8a120967f 100644
--- a/frontend/src/views/settings/composables/useAdminApiKey.ts
+++ b/frontend/src/views/settings/composables/useAdminApiKey.ts
@@ -1,11 +1,11 @@
-import { reactive, shallowRef } from 'vue'
+import { toast } from '@codex-proxy/ui'
 
+import { reactive, shallowRef } from 'vue'
 import {
   deleteAdminApiKey,
   getAdminApiKeyStatus,
   regenerateAdminApiKey,
 } from '@/api'
-import { toast } from '@/components/base/BaseToast'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 import { useCopyText } from '@/composables/useCopyText'
 
diff --git a/frontend/src/views/settings/composables/useBackupRecords.ts b/frontend/src/views/settings/composables/useBackupRecords.ts
index 750794526..8219f8e9d 100644
--- a/frontend/src/views/settings/composables/useBackupRecords.ts
+++ b/frontend/src/views/settings/composables/useBackupRecords.ts
@@ -1,5 +1,6 @@
 import type { BackupRecord, BackupStatus } from '@/api'
 
+import { toast } from '@codex-proxy/ui'
 import { computed, onScopeDispose, shallowRef } from 'vue'
 import {
   createBackup,
@@ -8,7 +9,6 @@ import {
   getBackupRecords,
 } from '@/api'
 import { ApiError } from '@/api/request'
-import { toast } from '@/components/base/BaseToast'
 import { usePagedQuery } from '@/composables/usePagedQuery'
 import { errorMessage } from '@/utils/async'
 
diff --git a/frontend/src/views/settings/composables/useBackupSettings.ts b/frontend/src/views/settings/composables/useBackupSettings.ts
index 2f02eb397..b1f012732 100644
--- a/frontend/src/views/settings/composables/useBackupSettings.ts
+++ b/frontend/src/views/settings/composables/useBackupSettings.ts
@@ -1,5 +1,6 @@
 import type { BackupSettingsView, UpdateBackupStoragePayload } from '@/api'
 
+import { toast } from '@codex-proxy/ui'
 import { reactive, shallowRef } from 'vue'
 import {
   getBackupSettings,
@@ -7,7 +8,6 @@ import {
   updateBackupSchedule,
   updateBackupStorage,
 } from '@/api'
-import { toast } from '@/components/base/BaseToast'
 import { errorMessage } from '@/utils/async'
 
 /** 存储与计划配置共用的加载/保存/测试 composable。 */
diff --git a/frontend/src/views/settings/composables/useSettingsForm.ts b/frontend/src/views/settings/composables/useSettingsForm.ts
index 4d76e1a33..8def84d22 100644
--- a/frontend/src/views/settings/composables/useSettingsForm.ts
+++ b/frontend/src/views/settings/composables/useSettingsForm.ts
@@ -1,11 +1,12 @@
 import type { rotationOptions } from '../constants'
 import type { RequestLocation } from '@/api'
-import type { ClientProfileSelection, XaiClientProfileSelection } from '@/api/modules/client-profiles'
-import { computed, reactive, ref, shallowRef } from 'vue'
+import type { ProviderRequestProfiles, ProviderRequestProfileUpdates } from '@/api/modules/client-profiles'
+import { toast } from '@codex-proxy/ui'
+import { isEqual } from 'es-toolkit'
 
+import { computed, reactive, ref, shallowRef } from 'vue'
 import { getSettings, updateSettings } from '@/api'
 import { ApiError } from '@/api/request'
-import { toast } from '@/components/base/BaseToast'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 import { errorMessage } from '@/utils/async'
 import { normalizeRequestLocation, requestLocationError } from '@/utils/request-location'
@@ -22,8 +23,7 @@ export function useSettingsForm() {
   const mappings = ref<Array<{ requestedModel: string, upstreamModel: string }>>([])
   const savedRequestLocation = shallowRef<RequestLocation>()
   const form = reactive({
-    openaiClientProfile: null as ClientProfileSelection | null,
-    xaiClientProfile: null as XaiClientProfileSelection | null,
+    providerRequestProfiles: {} as ProviderRequestProfiles,
     requestLocationEnabled: false,
     requestLocation: { country: '', region: '', city: '', timezone: '' },
     refreshMarginSeconds: null as number | null,
@@ -53,7 +53,11 @@ export function useSettingsForm() {
 
   function snapshot() {
     return {
-      form: { ...form, requestLocation: { ...form.requestLocation } },
+      form: {
+        ...form,
+        providerRequestProfiles: cloneProfiles(form.providerRequestProfiles),
+        requestLocation: { ...form.requestLocation },
+      },
       mappings: mappings.value.map(row => ({ ...row })),
     }
   }
@@ -65,7 +69,10 @@ export function useSettingsForm() {
   function resetSettings() {
     if (!saved.value || saving.value)
       return
-    Object.assign(form, saved.value.form, { requestLocation: { ...saved.value.form.requestLocation } })
+    Object.assign(form, saved.value.form, {
+      providerRequestProfiles: cloneProfiles(saved.value.form.providerRequestProfiles),
+      requestLocation: { ...saved.value.form.requestLocation },
+    })
     mappings.value = saved.value.mappings.map(row => ({ ...row }))
   }
 
@@ -118,8 +125,7 @@ export function useSettingsForm() {
 
     form.rotationStrategy = data.rotationStrategy
     form.minCodexDesktopVersion = data.minCodexDesktopVersion ?? ''
-    form.openaiClientProfile = data.openaiClientProfile
-    form.xaiClientProfile = data.xaiClientProfile
+    form.providerRequestProfiles = cloneProfiles(data.providerRequestProfiles)
     form.minCodexCliVersion = data.minCodexCliVersion ?? ''
     form.usageRetentionDays = data.usageRetentionDays
     form.opsEventRetentionDays = data.opsEventRetentionDays
@@ -185,7 +191,8 @@ export function useSettingsForm() {
   }
 
   async function saveSettings() {
-    if (saving.value || loading.value || !savedRequestLocation.value || !form.openaiClientProfile || !form.xaiClientProfile)
+    const savedSettings = saved.value
+    if (saving.value || loading.value || !savedRequestLocation.value || !savedSettings)
       return
     const { refreshMarginSeconds, refreshConcurrency, maxConcurrentPerAccount, requestIntervalMs, rotationStrategy, maxWaitingPerKey, maxWaitingPerAccount, concurrencyWaitTimeoutSeconds, responsesMaxDecompressedBodyMiB, accountAutoFreezeThreshold, accountAutoFreezeWindowSeconds, accountAutoFreezeDurationSeconds } = form
     if (refreshMarginSeconds === null || refreshConcurrency === null || maxConcurrentPerAccount === null || requestIntervalMs === null || !rotationStrategy || maxWaitingPerKey === null || maxWaitingPerAccount === null || concurrencyWaitTimeoutSeconds === null) {
@@ -234,12 +241,12 @@ export function useSettingsForm() {
       toast.warning('探测模型名称不能超过 128 个字符')
       return
     }
-    const xaiClientProfile = form.xaiClientProfile
-    const openaiClientProfile = form.openaiClientProfile
     await saveAction.run(async () => {
       const result = await updateSettings({
-        openaiClientProfile,
-        xaiClientProfile,
+        providerRequestProfiles: requestProfileUpdates(
+          savedSettings.form.providerRequestProfiles,
+          form.providerRequestProfiles,
+        ),
         requestLocationEnabled: form.requestLocationEnabled,
         requestLocation,
         modelMappings: mappingPayload(),
@@ -304,6 +311,24 @@ export function useSettingsForm() {
   }
 }
 
+function cloneProfiles(value: ProviderRequestProfiles): ProviderRequestProfiles {
+  return JSON.parse(JSON.stringify(value)) as ProviderRequestProfiles
+}
+
+function requestProfileUpdates(
+  previous: ProviderRequestProfiles,
+  current: ProviderRequestProfiles,
+): ProviderRequestProfileUpdates {
+  const updates: ProviderRequestProfileUpdates = {}
+  const clonedCurrent = cloneProfiles(current)
+  for (const provider of new Set([...Object.keys(previous), ...Object.keys(current)])) {
+    if (isEqual(previous[provider], current[provider]))
+      continue
+    updates[provider] = clonedCurrent[provider] ?? null
+  }
+  return updates
+}
+
 function isSemver(value: string): boolean {
   if (value.length > 64 || value.startsWith('v'))
     return false
diff --git a/frontend/src/views/settings/index.vue b/frontend/src/views/settings/index.vue
index 5fa9dff6d..b7f63d37d 100644
--- a/frontend/src/views/settings/index.vue
+++ b/frontend/src/views/settings/index.vue
@@ -1,14 +1,10 @@
 <script setup lang="ts">
+import { BaseButton, BaseIconButton, BasePageHeader, BaseSegmented, BaseSelect } from '@codex-proxy/ui'
+
 import { Save, Undo2 } from '@lucide/vue'
 import { computed, reactive, shallowRef, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BasePageHeader from '@/components/base/BasePageHeader.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
-
 import AccountAutoFreezeCard from './components/AccountAutoFreezeCard.vue'
 import SettingsBackupSection from './components/backup/SettingsBackupSection.vue'
 import ClientProfileCard from './components/ClientProfileCard.vue'
@@ -170,8 +166,7 @@ watch(section, (value) => {
         <div v-if="visited.has('upstream')" v-show="section === 'upstream'" class="grid min-w-0 gap-5">
           <TokenRefreshCard v-model:refresh-margin-seconds="refreshMarginSecondsValue" v-model:refresh-concurrency="refreshConcurrencyValue" />
           <ClientProfileCard
-            v-model:openai="form.openaiClientProfile"
-            v-model:xai="form.xaiClientProfile"
+            v-model="form.providerRequestProfiles"
             :active="section === 'upstream'"
             :disabled="disabled"
           />
diff --git a/frontend/src/views/settings/pricing/PricingBatchModal.vue b/frontend/src/views/settings/pricing/PricingBatchModal.vue
index 9ea085d83..3f6ddb9f3 100644
--- a/frontend/src/views/settings/pricing/PricingBatchModal.vue
+++ b/frontend/src/views/settings/pricing/PricingBatchModal.vue
@@ -1,12 +1,8 @@
 <script setup lang="ts">
 import type { PricingRow } from './model'
 import type { PricingChange } from '@/api'
+import { BaseButton, BaseFormItem, BaseInput, BaseModal, BaseScrollbar } from '@codex-proxy/ui'
 import { computed, ref, watch } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
 import { multiplierText, parseMultiplier } from './model'
 
 defineProps<{ rows: PricingRow[], reset: boolean, saving: boolean }>()
diff --git a/frontend/src/views/settings/pricing/PricingEditor.vue b/frontend/src/views/settings/pricing/PricingEditor.vue
index 6a600c3e7..f9c52db07 100644
--- a/frontend/src/views/settings/pricing/PricingEditor.vue
+++ b/frontend/src/views/settings/pricing/PricingEditor.vue
@@ -1,15 +1,9 @@
 <script setup lang="ts">
 import type { PricingRow } from './model'
 import type { ModelPricing, PriceBand, TokenPrices } from '@/api'
+import { BaseButton, BaseFormItem, BaseInput, BaseModal, BasePopover, BaseSegmented, BaseSelect } from '@codex-proxy/ui'
 import { Info } from '@lucide/vue'
 import { computed, ref, shallowRef, useId, watch } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BasePopover from '@/components/base/BasePopover.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
 import ProviderIconGroup from '@/components/ProviderIconGroup.vue'
 import { bands, parseMultiplier, validPrice } from './model'
 import PricingRateFields from './PricingRateFields.vue'
diff --git a/frontend/src/views/settings/pricing/PricingRateFields.vue b/frontend/src/views/settings/pricing/PricingRateFields.vue
index 71d5d82cb..9421e9ea3 100644
--- a/frontend/src/views/settings/pricing/PricingRateFields.vue
+++ b/frontend/src/views/settings/pricing/PricingRateFields.vue
@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import type { TokenPrices } from '@/api'
-import BaseFormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
+import { BaseFormItem, BaseInput } from '@codex-proxy/ui'
 import { effectivePrice, priceFields, validPrice } from './model'
 
 const props = defineProps<{
diff --git a/frontend/src/views/settings/pricing/PricingSyncModal.vue b/frontend/src/views/settings/pricing/PricingSyncModal.vue
index e8f89c048..e5ebda17b 100644
--- a/frontend/src/views/settings/pricing/PricingSyncModal.vue
+++ b/frontend/src/views/settings/pricing/PricingSyncModal.vue
@@ -1,11 +1,7 @@
 <script setup lang="ts">
 import type { PricingCatalog, PricingSyncPreview } from '@/api'
+import { BaseButton, BaseCheckbox, BaseModal, BaseScrollbar, BaseTag } from '@codex-proxy/ui'
 import { computed, shallowRef, watch } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseCheckbox from '@/components/base/BaseCheckbox.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
-import BaseTag from '@/components/base/BaseTag.vue'
 import { bands, effectivePrice, priceFields } from './model'
 
 const props = defineProps<{ preview?: PricingSyncPreview, catalog: PricingCatalog, saving: boolean }>()
diff --git a/frontend/src/views/settings/pricing/PricingTable.vue b/frontend/src/views/settings/pricing/PricingTable.vue
index c4856795b..9bbc748d8 100644
--- a/frontend/src/views/settings/pricing/PricingTable.vue
+++ b/frontend/src/views/settings/pricing/PricingTable.vue
@@ -1,10 +1,8 @@
 <script setup lang="ts">
+import type { BaseTableColumn } from '@codex-proxy/ui'
 import type { PricingRow } from './model'
-import type { BaseTableColumn } from '@/components/base/BaseTable/columns'
+import { BaseCheckbox, BaseIconButton, BaseTable } from '@codex-proxy/ui'
 import { Pencil, Trash2 } from '@lucide/vue'
-import BaseCheckbox from '@/components/base/BaseCheckbox.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseTable from '@/components/base/BaseTable/index.vue'
 import { effectivePrice, multiplierText, sourceLabels } from './model'
 import PricingUnit from './PricingUnit.vue'
 
diff --git a/frontend/src/views/settings/pricing/PricingToolbar.vue b/frontend/src/views/settings/pricing/PricingToolbar.vue
index d31b8554f..a71ae2722 100644
--- a/frontend/src/views/settings/pricing/PricingToolbar.vue
+++ b/frontend/src/views/settings/pricing/PricingToolbar.vue
@@ -1,14 +1,8 @@
 <script setup lang="ts">
-import { Openai, Xai } from '@boxicons/vue'
+import { BaseButton, BaseIconButton, BaseInput, BasePopover, BaseSegmented, BaseSelect } from '@codex-proxy/ui'
 import { CircleAlert, Download, Percent, Plus, RotateCcw, Search, X } from '@lucide/vue'
 import { computed, shallowRef, useId } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BasePopover from '@/components/base/BasePopover.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
-import { PROVIDER_DISPLAY_NAMES } from '@/utils/providers'
+import { formatProviderLabel, providerIcon } from '@/utils/providers'
 import { sourceLabels } from './model'
 
 const props = defineProps<{
@@ -17,6 +11,7 @@ const props = defineProps<{
   saving: boolean
   syncing: boolean
   syncedAt?: string | null
+  providers: string[]
 }>()
 defineEmits<{ add: [], sync: [], setMultiplier: [], reset: [], clear: [] }>()
 const search = defineModel<string>('search', { required: true })
@@ -25,10 +20,11 @@ const source = defineModel<string>('source', { required: true })
 const syncInfoOpen = shallowRef(false)
 const syncInfoId = useId()
 const syncTime = computed(() => props.syncedAt ? new Date(props.syncedAt).toLocaleString() : '尚未同步')
-const providerOptions = [
-  { label: PROVIDER_DISPLAY_NAMES.openai, value: 'openai', icon: Openai },
-  { label: PROVIDER_DISPLAY_NAMES.xai, value: 'xai', icon: Xai },
-]
+const providerOptions = computed(() => props.providers.map(value => ({
+  label: formatProviderLabel(value),
+  value,
+  icon: providerIcon(value),
+})))
 </script>
 
 <template>
@@ -39,7 +35,16 @@ const providerOptions = [
           <Search class="size-4" />
         </template>
       </BaseInput>
-      <BaseSegmented v-model="provider" class="w-21 shrink-0 bg-(--cp-input-bg)!" label="模型提供商" :options="providerOptions" :disabled="saving" display="icon" />
+      <div v-if="providerOptions.length" class="min-w-0 max-w-full overflow-x-auto">
+        <BaseSegmented
+          v-model="provider"
+          label="模型提供商"
+          display="icon"
+          :style="{ width: `${providerOptions.length * 40 + 4}px` }"
+          :options="providerOptions"
+          :disabled="saving"
+        />
+      </div>
       <BaseSelect v-model="source" class="w-32" aria-label="价格来源" :options="[{ label: '全部来源', value: 'all' }, { label: sourceLabels.custom, value: 'custom' }, { label: sourceLabels.synced, value: 'synced' }, { label: sourceLabels.builtin, value: 'builtin' }]" />
       <div v-if="selectedCount" class="ml-auto flex w-full flex-wrap items-center justify-end gap-2 sm:w-auto" role="group" aria-label="批量操作">
         <span class="inline-flex h-cp-control w-full items-center gap-1 whitespace-nowrap text-cp text-cp-text-secondary sm:mr-1 sm:w-auto" aria-live="polite">
diff --git a/frontend/src/views/settings/pricing/PricingUnit.vue b/frontend/src/views/settings/pricing/PricingUnit.vue
index be56fb077..179574992 100644
--- a/frontend/src/views/settings/pricing/PricingUnit.vue
+++ b/frontend/src/views/settings/pricing/PricingUnit.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
+import { BasePopover } from '@codex-proxy/ui'
 import { Info } from '@lucide/vue'
 import { shallowRef, useId } from 'vue'
-import BasePopover from '@/components/base/BasePopover.vue'
 
 const infoOpen = shallowRef(false)
 const infoId = useId()
diff --git a/frontend/src/views/settings/pricing/index.vue b/frontend/src/views/settings/pricing/index.vue
index 9c7e27fa8..c2b2fe297 100644
--- a/frontend/src/views/settings/pricing/index.vue
+++ b/frontend/src/views/settings/pricing/index.vue
@@ -1,12 +1,9 @@
 <script setup lang="ts">
 import type { PricingRow } from './model'
 import type { ModelPricing, PricingChange } from '@/api'
+import { BaseButton, BaseConfirmModal, BaseEmpty, BaseTablePagination } from '@codex-proxy/ui'
 import { CircleAlert } from '@lucide/vue'
 import { computed, ref, shallowRef } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseConfirmModal from '@/components/base/BaseConfirmModal.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseTablePagination from '@/components/base/BaseTable/BaseTablePagination.vue'
 import PricingBatchModal from './PricingBatchModal.vue'
 import PricingEditor from './PricingEditor.vue'
 import PricingSyncModal from './PricingSyncModal.vue'
@@ -14,7 +11,7 @@ import PricingTable from './PricingTable.vue'
 import PricingToolbar from './PricingToolbar.vue'
 import { usePricing } from './usePricing'
 
-const { catalog, provider, search, source, page, pageSize, selected, error, rows, visible, pagination, loading, saving, syncing, preview, load, save, startSync, confirmSync, toggle, togglePage } = usePricing()
+const { catalog, providers, provider, search, source, page, pageSize, selected, error, rows, visible, pagination, loading, saving, syncing, preview, load, save, startSync, confirmSync, toggle, togglePage } = usePricing()
 const editorOpen = ref(false)
 const editing = shallowRef<PricingRow>()
 const deleting = shallowRef<PricingRow>()
@@ -57,6 +54,7 @@ async function deleteModel() {
       :saving="saving"
       :syncing="syncing"
       :synced-at="catalog.syncedAt"
+      :providers="providers"
       @add="edit()"
       @sync="startSync"
       @set-multiplier="batch(false)"
diff --git a/frontend/src/views/settings/pricing/model.ts b/frontend/src/views/settings/pricing/model.ts
index a21f0ed01..e4ee448ca 100644
--- a/frontend/src/views/settings/pricing/model.ts
+++ b/frontend/src/views/settings/pricing/model.ts
@@ -24,6 +24,9 @@ export interface PricingRow {
   custom?: ModelPricing
   effective: ModelPricing
 }
+export function pricingProviders(catalog: PricingCatalog): string[] {
+  return Object.keys(catalog.defaults).sort((left, right) => left.localeCompare(right))
+}
 export function pricingRows(catalog: PricingCatalog, provider: string): PricingRow[] {
   const defaults = catalog.defaults[provider] ?? {}
   const synced = catalog.synced[provider] ?? {}
diff --git a/frontend/src/views/settings/pricing/usePricing.ts b/frontend/src/views/settings/pricing/usePricing.ts
index 09c4d6509..dcd5b05f1 100644
--- a/frontend/src/views/settings/pricing/usePricing.ts
+++ b/frontend/src/views/settings/pricing/usePricing.ts
@@ -1,10 +1,10 @@
 import type { PricingCatalog, PricingChange, PricingSyncPreview } from '@/api'
+import { toast } from '@codex-proxy/ui'
 import { computed, onMounted, ref, shallowRef, watch } from 'vue'
 import { getPricing, previewPricingSync, syncPricing, updatePricing } from '@/api'
-import { toast } from '@/components/base/BaseToast'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 import { errorMessage } from '@/utils/async'
-import { pricingRows } from './model'
+import { pricingProviders, pricingRows } from './model'
 
 export function usePricing() {
   const catalog = shallowRef<PricingCatalog>({ defaults: {}, overrides: {}, synced: {}, syncedAt: null })
@@ -19,6 +19,7 @@ export function usePricing() {
   const writeAction = useAsyncAction()
   const previewAction = useAsyncAction()
   const preview = shallowRef<PricingSyncPreview>()
+  const providers = computed(() => pricingProviders(catalog.value))
   const rows = computed(() => pricingRows(catalog.value, provider.value))
   const filtered = computed(() => rows.value.filter(row => row.model.toLowerCase().includes(search.value.trim().toLowerCase())
     && (source.value === 'all' || row.source === source.value)))
@@ -35,6 +36,8 @@ export function usePricing() {
   async function load() {
     await loadAction.run(async () => {
       catalog.value = await getPricing()
+      if (!providers.value.includes(provider.value))
+        provider.value = providers.value[0] ?? ''
       error.value = ''
       page.value = Math.min(page.value, Math.max(1, Math.ceil(filtered.value.length / pageSize.value)))
     }, { onError: (cause) => { error.value = errorMessage(cause, '无法加载价目') } })
@@ -72,5 +75,5 @@ export function usePricing() {
     selected.value = checked ? [...new Set([...selected.value, ...ids])] : selected.value.filter(id => !ids.includes(id))
   }
   onMounted(load)
-  return { catalog, provider, search, source, page, pageSize, selected, error, rows, filtered, visible, pagination, loading: loadAction.loading, saving: writeAction.loading, syncing: previewAction.loading, preview, load, save, startSync, confirmSync, toggle, togglePage }
+  return { catalog, providers, provider, search, source, page, pageSize, selected, error, rows, filtered, visible, pagination, loading: loadAction.loading, saving: writeAction.loading, syncing: previewAction.loading, preview, load, save, startSync, confirmSync, toggle, togglePage }
 }
diff --git a/frontend/src/views/theme/components/AppearanceSettingsSection.vue b/frontend/src/views/theme/components/AppearanceSettingsSection.vue
index 7668861d9..8c2297e1b 100644
--- a/frontend/src/views/theme/components/AppearanceSettingsSection.vue
+++ b/frontend/src/views/theme/components/AppearanceSettingsSection.vue
@@ -1,12 +1,7 @@
 <script setup lang="ts">
-import { Check, RotateCcw, Save, Search, Undo2 } from '@lucide/vue'
+import { BaseButton, BaseInput, BasePageHeader, BaseScrollbar, BaseSegmented, toast } from '@codex-proxy/ui'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BasePageHeader from '@/components/base/BasePageHeader.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import { toast } from '@/components/base/BaseToast'
+import { Check, RotateCcw, Save, Search, Undo2 } from '@lucide/vue'
 
 import { useThemeEditor } from '../composables/useThemeEditor'
 import ThemeComponentTokenPanel from './ThemeComponentTokenPanel.vue'
diff --git a/frontend/src/views/theme/components/ThemeColorTokenField.vue b/frontend/src/views/theme/components/ThemeColorTokenField.vue
index 332fe76d3..658b93154 100644
--- a/frontend/src/views/theme/components/ThemeColorTokenField.vue
+++ b/frontend/src/views/theme/components/ThemeColorTokenField.vue
@@ -1,9 +1,8 @@
 <script setup lang="ts">
-import { RotateCcw } from '@lucide/vue'
+import { BaseColorPicker, BaseIconButton } from '@codex-proxy/ui'
 
-import BaseColorPicker from '@/components/base/BaseColorPicker/index.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import { themeTokenAllowsAlpha } from '@/theme'
+import { themeTokenAllowsAlpha } from '@codex-proxy/ui/theme'
+import { RotateCcw } from '@lucide/vue'
 
 withDefaults(defineProps<{
   label: string
diff --git a/frontend/src/views/theme/components/ThemeComponentPreview.vue b/frontend/src/views/theme/components/ThemeComponentPreview.vue
index 84fddaa67..e3474a91c 100644
--- a/frontend/src/views/theme/components/ThemeComponentPreview.vue
+++ b/frontend/src/views/theme/components/ThemeComponentPreview.vue
@@ -1,5 +1,7 @@
 <script setup lang="ts">
-import type { BaseTablePagination as BaseTablePaginationState } from '@/components/base/BaseTable/pagination'
+import type { BaseTablePaginationState } from '@codex-proxy/ui'
+
+import { BaseButton, BaseCard, BaseCheckbox, BaseColorPicker, BaseEmpty, BaseForm, BaseIconButton, BaseInput, BaseMenuItem, BaseMotionIcon, BaseNumberInput, BasePopover, BaseRadio, BaseRange, BaseSegmented, BaseSelect, BaseSkeleton, BaseSwitch, BaseTable, BaseTablePagination, BaseTag, BaseTextarea, defineTableColumns, BaseFormItem as FormItem } from '@codex-proxy/ui'
 
 import {
   Bell,
@@ -16,31 +18,6 @@ import {
 } from '@lucide/vue'
 import { shallowRef } from 'vue'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseCheckbox from '@/components/base/BaseCheckbox.vue'
-import BaseColorPicker from '@/components/base/BaseColorPicker/index.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import FormItem from '@/components/base/BaseForm/FormItem.vue'
-import BaseForm from '@/components/base/BaseForm/index.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseMenuItem from '@/components/base/BaseMenuItem.vue'
-import BaseMotionIcon from '@/components/base/BaseMotionIcon.vue'
-import BaseNumberInput from '@/components/base/BaseNumberInput.vue'
-import BasePopover from '@/components/base/BasePopover.vue'
-import BaseRadio from '@/components/base/BaseRadio.vue'
-import BaseRange from '@/components/base/BaseRange.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
-import BaseSkeleton from '@/components/base/BaseSkeleton.vue'
-import BaseSwitch from '@/components/base/BaseSwitch.vue'
-import BaseTablePagination from '@/components/base/BaseTable/BaseTablePagination.vue'
-import { defineTableColumns } from '@/components/base/BaseTable/columns'
-import BaseTable from '@/components/base/BaseTable/index.vue'
-import BaseTag from '@/components/base/BaseTag.vue'
-import BaseTextarea from '@/components/base/BaseTextarea.vue'
-
 interface PreviewTableRow {
   id: string
   account: string
diff --git a/frontend/src/views/theme/components/ThemeComponentTokenPanel.vue b/frontend/src/views/theme/components/ThemeComponentTokenPanel.vue
index 5d277a135..d3ece3714 100644
--- a/frontend/src/views/theme/components/ThemeComponentTokenPanel.vue
+++ b/frontend/src/views/theme/components/ThemeComponentTokenPanel.vue
@@ -1,10 +1,10 @@
 <script setup lang="ts">
+import type { ResolvedTheme, ThemeComponentOverrides, ThemeTokenName } from '@codex-proxy/ui/theme'
 import type { Component } from 'vue'
 import type {
   ThemeEditorComponent,
   ThemeEditorDraft,
 } from '../composables/useThemeEditor'
-import type { ResolvedTheme, ThemeComponentOverrides, ThemeTokenName } from '@/theme'
 
 import {
   AppWindow,
diff --git a/frontend/src/views/theme/components/ThemeEditorPreview.vue b/frontend/src/views/theme/components/ThemeEditorPreview.vue
index 66d6804a1..2f73c88ba 100644
--- a/frontend/src/views/theme/components/ThemeEditorPreview.vue
+++ b/frontend/src/views/theme/components/ThemeEditorPreview.vue
@@ -1,9 +1,9 @@
 <script setup lang="ts">
+import type { ThemeName } from '@codex-proxy/ui/theme'
 import type { CSSProperties } from 'vue'
 import type { ThemeEditorPreview } from '../composables/useThemeEditor'
-import type { ThemeName } from '@/theme'
 
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
+import { BaseSegmented } from '@codex-proxy/ui'
 
 import ThemeComponentPreview from './ThemeComponentPreview.vue'
 import ThemeDashboardPreview from './ThemeDashboardPreview.vue'
diff --git a/frontend/src/views/theme/components/ThemeGlobalTokenPanel.vue b/frontend/src/views/theme/components/ThemeGlobalTokenPanel.vue
index 414252181..6f0e11fa5 100644
--- a/frontend/src/views/theme/components/ThemeGlobalTokenPanel.vue
+++ b/frontend/src/views/theme/components/ThemeGlobalTokenPanel.vue
@@ -1,13 +1,13 @@
 <script setup lang="ts">
+import type { ResolvedTheme, ThemeColorPreset, ThemeColorPresetId, ThemeMode, ThemeSeedOverrides } from '@codex-proxy/ui/theme'
 import type { ThemeEditorDraft, ThemeEditorGlobalCategory } from '../composables/useThemeEditor'
-import type { ResolvedTheme, ThemeColorPreset, ThemeColorPresetId, ThemeMode, ThemeSeedOverrides } from '@/theme'
+
+import { BaseSegmented } from '@codex-proxy/ui'
+import { resolveTheme, THEME_COLOR_PRESETS } from '@codex-proxy/ui/theme'
 
 import { Check, ChevronDown, Laptop, Moon, Sun } from '@lucide/vue'
 import { computed } from 'vue'
 
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import { resolveTheme, THEME_COLOR_PRESETS } from '@/theme'
-
 import ThemeColorTokenField from './ThemeColorTokenField.vue'
 import ThemeNumberTokenField from './ThemeNumberTokenField.vue'
 
diff --git a/frontend/src/views/theme/components/ThemeNumberTokenField.vue b/frontend/src/views/theme/components/ThemeNumberTokenField.vue
index a08130d5a..859c5f353 100644
--- a/frontend/src/views/theme/components/ThemeNumberTokenField.vue
+++ b/frontend/src/views/theme/components/ThemeNumberTokenField.vue
@@ -1,9 +1,7 @@
 <script setup lang="ts">
-import { RotateCcw } from '@lucide/vue'
+import { BaseIconButton, BaseNumberInput, BaseRange } from '@codex-proxy/ui'
 
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseNumberInput from '@/components/base/BaseNumberInput.vue'
-import BaseRange from '@/components/base/BaseRange.vue'
+import { RotateCcw } from '@lucide/vue'
 
 defineProps<{
   label: string
diff --git a/frontend/src/views/theme/components/ThemePreviewCanvas.vue b/frontend/src/views/theme/components/ThemePreviewCanvas.vue
index 799d651a2..6dfdcf662 100644
--- a/frontend/src/views/theme/components/ThemePreviewCanvas.vue
+++ b/frontend/src/views/theme/components/ThemePreviewCanvas.vue
@@ -1,12 +1,11 @@
 <script setup lang="ts">
+import type { ThemeName } from '@codex-proxy/ui/theme'
 import type { CSSProperties } from 'vue'
-import type { ThemeName } from '@/theme'
+import { BaseButton, BaseIconButton } from '@codex-proxy/ui'
+
 import { Maximize2, Minus, Move, Plus } from '@lucide/vue'
 import { computed, useTemplateRef } from 'vue'
 
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-
 import { useThemePreviewCanvas } from '../composables/useThemePreviewCanvas'
 import ThemePreviewScope from './ThemePreviewScope.vue'
 
diff --git a/frontend/src/views/theme/components/ThemePreviewScope.vue b/frontend/src/views/theme/components/ThemePreviewScope.vue
index 18c806521..7471c3475 100644
--- a/frontend/src/views/theme/components/ThemePreviewScope.vue
+++ b/frontend/src/views/theme/components/ThemePreviewScope.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
+import type { ThemeName } from '@codex-proxy/ui/theme'
 import type { CSSProperties } from 'vue'
 import type { ThemeColorTokens } from '@/composables/useThemeColor'
-import type { ThemeName } from '@/theme'
 
 import { computed, onMounted, shallowRef, useTemplateRef } from 'vue'
 
diff --git a/frontend/src/views/theme/components/ThemeTextTokenField.vue b/frontend/src/views/theme/components/ThemeTextTokenField.vue
index 21d13cfa2..a566903d5 100644
--- a/frontend/src/views/theme/components/ThemeTextTokenField.vue
+++ b/frontend/src/views/theme/components/ThemeTextTokenField.vue
@@ -1,8 +1,7 @@
 <script setup lang="ts">
-import { RotateCcw } from '@lucide/vue'
+import { BaseIconButton, BaseInput } from '@codex-proxy/ui'
 
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
+import { RotateCcw } from '@lucide/vue'
 
 defineProps<{
   label: string
diff --git a/frontend/src/views/theme/composables/useThemeEditor.ts b/frontend/src/views/theme/composables/useThemeEditor.ts
index 753289e9f..f3b5d633f 100644
--- a/frontend/src/views/theme/composables/useThemeEditor.ts
+++ b/frontend/src/views/theme/composables/useThemeEditor.ts
@@ -7,12 +7,9 @@ import type {
   ThemeName,
   ThemeSeedOverrides,
   ThemeTokenName,
-} from '@/theme'
+} from '@codex-proxy/ui/theme'
 
-import { storeToRefs } from 'pinia'
-import { computed, ref, shallowRef, watch } from 'vue'
-
-import { useThemeStore } from '@/stores/modules/theme'
+import { normalizeHexColor } from '@codex-proxy/ui'
 import {
   DEFAULT_CUSTOM_THEME_COLOR,
   DEFAULT_THEME_COLOR,
@@ -21,8 +18,11 @@ import {
   isThemeMode,
   normalizeThemeCustomization,
   resolveTheme,
-} from '@/theme'
-import { normalizeHexColor } from '@/utils/color'
+} from '@codex-proxy/ui/theme'
+
+import { storeToRefs } from 'pinia'
+import { computed, ref, shallowRef, watch } from 'vue'
+import { useThemeStore } from '@/stores/modules/theme'
 
 export type ThemeEditorScope = 'global' | 'component'
 export type ThemeEditorGlobalCategory = 'color' | 'size' | 'style'
diff --git a/frontend/src/views/usage/components/OpsErrorDetailModal.vue b/frontend/src/views/usage/components/OpsErrorDetailModal.vue
index 9d230b1a4..c8eb5b79e 100644
--- a/frontend/src/views/usage/components/OpsErrorDetailModal.vue
+++ b/frontend/src/views/usage/components/OpsErrorDetailModal.vue
@@ -1,9 +1,8 @@
 <script setup lang="ts">
 import type { OpsError } from '@/api'
 
+import { BaseButton, BaseModal } from '@codex-proxy/ui'
 import { computed } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
 import { failureClassText } from '../utils/opsErrorPresentation'
 import RequestDiagnosticsPanel from './RequestDiagnosticsPanel.vue'
 import UsageDetailCodePanel from './UsageDetailCodePanel.vue'
diff --git a/frontend/src/views/usage/components/OpsErrorPanel.vue b/frontend/src/views/usage/components/OpsErrorPanel.vue
index 4c97e2ad9..c7678d775 100644
--- a/frontend/src/views/usage/components/OpsErrorPanel.vue
+++ b/frontend/src/views/usage/components/OpsErrorPanel.vue
@@ -2,14 +2,9 @@
 import type { UsageTimeRangeParams } from '../composables/useUsageTimeRange'
 import type { OpsError } from '@/api'
 
+import { BaseIconButton, BaseInput, BaseTable, BaseTableColumnSettings, BaseTablePagination, useTableColumns } from '@codex-proxy/ui'
 import { Eye, RefreshCw, Search } from '@lucide/vue'
 import { shallowRef, toRef } from 'vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
-import BaseTableColumnSettings from '@/components/base/BaseTable/BaseTableColumnSettings.vue'
-import BaseTablePagination from '@/components/base/BaseTable/BaseTablePagination.vue'
-import BaseTable from '@/components/base/BaseTable/index.vue'
-import { useTableColumns } from '@/components/base/BaseTable/useTableColumns'
 import ProviderIconGroup from '@/components/ProviderIconGroup.vue'
 import { useOpsErrorsTable } from '../composables/useOpsErrorsTable'
 import { opsErrorColumns } from '../constants'
@@ -24,6 +19,7 @@ const props = defineProps<{
   provider: string
   active: boolean
 }>()
+const emit = defineEmits<{ refresh: [] }>()
 
 const {
   loading,
@@ -57,6 +53,11 @@ function showDetail(record: OpsError) {
   detailOpen.value = true
 }
 
+function handleRefresh() {
+  void refresh()
+  emit('refresh')
+}
+
 function accountText(record: OpsError) {
   return record.accountEmail
     || record.accountName
@@ -117,7 +118,7 @@ function upstreamSendStateText(value: string | null | undefined) {
           label="刷新错误明细"
           :loading="refreshing"
           :disabled="loading || refreshing"
-          @click="refresh"
+          @click="handleRefresh"
         >
           <template #loading>
             <RefreshCw class="size-4.5 animate-spin motion-reduce:animate-none" />
diff --git a/frontend/src/views/usage/components/RequestDiagnosticsPanel.vue b/frontend/src/views/usage/components/RequestDiagnosticsPanel.vue
index b8c24913c..487496fe3 100644
--- a/frontend/src/views/usage/components/RequestDiagnosticsPanel.vue
+++ b/frontend/src/views/usage/components/RequestDiagnosticsPanel.vue
@@ -1,10 +1,8 @@
 <script setup lang="ts">
 import type { OpsError, OpsErrorMetadata } from '@/api'
+import { BaseButton, BaseEmpty, BaseScrollbar } from '@codex-proxy/ui'
 import { Download, RefreshCw } from '@lucide/vue'
 import { computed } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
 import { useAsyncAction } from '@/composables/useAsyncAction'
 import { useDownload } from '@/composables/useDownload'
 import { useRequestDiagnostics } from '../composables/useRequestDiagnostics'
diff --git a/frontend/src/views/usage/components/UsageCostCard.vue b/frontend/src/views/usage/components/UsageCostCard.vue
index 33c07cc95..d55e09f8b 100644
--- a/frontend/src/views/usage/components/UsageCostCard.vue
+++ b/frontend/src/views/usage/components/UsageCostCard.vue
@@ -2,10 +2,8 @@
 import type { EChartsOption, LineSeriesOption } from 'echarts'
 import type { getUsageRecordInsightsOverview } from '@/api'
 
+import { BaseCard, BaseEmpty, BaseSegmented } from '@codex-proxy/ui'
 import { computed, shallowRef } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
 import BaseChart from '@/components/charts/BaseChart.vue'
 import {
   requestActivityByBucket,
diff --git a/frontend/src/views/usage/components/UsageDetailCodePanel.vue b/frontend/src/views/usage/components/UsageDetailCodePanel.vue
index e872ef624..4798df8c7 100644
--- a/frontend/src/views/usage/components/UsageDetailCodePanel.vue
+++ b/frontend/src/views/usage/components/UsageDetailCodePanel.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import BaseScrollbar from '@/components/base/BaseScrollbar.vue'
+import { BaseScrollbar } from '@codex-proxy/ui'
 
 // 详情弹窗的代码面板：标题 + 滚动区内的预格式化文本。
 defineProps<{
diff --git a/frontend/src/views/usage/components/UsageDetailPopover.vue b/frontend/src/views/usage/components/UsageDetailPopover.vue
index e60efc89c..90b15e111 100644
--- a/frontend/src/views/usage/components/UsageDetailPopover.vue
+++ b/frontend/src/views/usage/components/UsageDetailPopover.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
-import { Info } from '@lucide/vue'
+import { BasePopover } from '@codex-proxy/ui'
 
-import BasePopover from '@/components/base/BasePopover.vue'
+import { Info } from '@lucide/vue'
 
 // 表格单元格的“信息点”悬浮明细：统一触发按钮与面板壳。
 defineProps<{
diff --git a/frontend/src/views/usage/components/UsageDiagnosticCard.vue b/frontend/src/views/usage/components/UsageDiagnosticCard.vue
index b30fa8a5a..6b531aed3 100644
--- a/frontend/src/views/usage/components/UsageDiagnosticCard.vue
+++ b/frontend/src/views/usage/components/UsageDiagnosticCard.vue
@@ -1,13 +1,9 @@
 <script setup lang="ts">
 import type { getUsageRecordInsightsDiagnostics } from '@/api'
-import { CornerDownRight } from '@lucide/vue'
+import { BaseCard, BaseEmpty, BaseSegmented, BaseTable, defineTableColumns } from '@codex-proxy/ui'
 
+import { CornerDownRight } from '@lucide/vue'
 import { computed } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import { defineTableColumns } from '@/components/base/BaseTable/columns'
-import BaseTable from '@/components/base/BaseTable/index.vue'
 import { formatLocalizedCompactNumber as formatCompactNumber } from '@/utils/number'
 
 import { formatDuration, formatPercent, formatUsd } from '../utils/format'
diff --git a/frontend/src/views/usage/components/UsageFilters.vue b/frontend/src/views/usage/components/UsageFilters.vue
index 09b322682..af3f8ae18 100644
--- a/frontend/src/views/usage/components/UsageFilters.vue
+++ b/frontend/src/views/usage/components/UsageFilters.vue
@@ -1,8 +1,7 @@
 <script setup lang="ts">
-import { RefreshCw, Search } from '@lucide/vue'
+import { BaseIconButton, BaseInput } from '@codex-proxy/ui'
 
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BaseInput from '@/components/base/BaseInput.vue'
+import { RefreshCw, Search } from '@lucide/vue'
 
 defineProps<{
   refreshing: boolean
diff --git a/frontend/src/views/usage/components/UsageHealthCard.vue b/frontend/src/views/usage/components/UsageHealthCard.vue
index 7e5ce7668..e4c7a4a25 100644
--- a/frontend/src/views/usage/components/UsageHealthCard.vue
+++ b/frontend/src/views/usage/components/UsageHealthCard.vue
@@ -1,12 +1,11 @@
 <script setup lang="ts">
 import type { BarSeriesOption, EChartsOption, LineSeriesOption } from 'echarts'
 import type { getUsageRecordInsightsOverview } from '@/api'
+import { BaseCard, BaseEmpty } from '@codex-proxy/ui'
+
 import { BarChart } from 'echarts/charts'
 import { use } from 'echarts/core'
-
 import { computed } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
 import BaseChart from '@/components/charts/BaseChart.vue'
 import { useChartPalette } from '@/composables/useChartPalette'
 import { formatLocalizedCompactNumber as formatCompactNumber } from '@/utils/number'
diff --git a/frontend/src/views/usage/components/UsagePerformanceCard.vue b/frontend/src/views/usage/components/UsagePerformanceCard.vue
index 446ddc86a..fffebdd06 100644
--- a/frontend/src/views/usage/components/UsagePerformanceCard.vue
+++ b/frontend/src/views/usage/components/UsagePerformanceCard.vue
@@ -2,10 +2,8 @@
 import type { EChartsOption } from 'echarts'
 import type { getUsageRecordInsightsOverview } from '@/api'
 
+import { BaseCard, BaseEmpty, BaseSegmented } from '@codex-proxy/ui'
 import { computed, shallowRef } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseEmpty from '@/components/base/BaseEmpty.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
 import BaseChart from '@/components/charts/BaseChart.vue'
 import { requestActivityByBucket, zeroInactiveValues } from '@/components/charts/timeSeriesGap'
 import { useChartPalette } from '@/composables/useChartPalette'
diff --git a/frontend/src/views/usage/components/UsageRecordDetailModal.vue b/frontend/src/views/usage/components/UsageRecordDetailModal.vue
index fc52a7d73..ce458f627 100644
--- a/frontend/src/views/usage/components/UsageRecordDetailModal.vue
+++ b/frontend/src/views/usage/components/UsageRecordDetailModal.vue
@@ -2,11 +2,8 @@
 import type { EChartsOption } from 'echarts'
 import type { UsageViewModel } from '../utils/records'
 
+import { BaseButton, BaseModal, BaseTable, defineTableColumns } from '@codex-proxy/ui'
 import { computed } from 'vue'
-import BaseButton from '@/components/base/BaseButton.vue'
-import BaseModal from '@/components/base/BaseModal/index.vue'
-import { defineTableColumns } from '@/components/base/BaseTable/columns'
-import BaseTable from '@/components/base/BaseTable/index.vue'
 import BaseChart from '@/components/charts/BaseChart.vue'
 import { chartTooltipStyle } from '@/components/charts/tooltip'
 import { useChartPalette } from '@/composables/useChartPalette'
diff --git a/frontend/src/views/usage/components/UsageRecordsTable.vue b/frontend/src/views/usage/components/UsageRecordsTable.vue
index 24b97df17..479795c69 100644
--- a/frontend/src/views/usage/components/UsageRecordsTable.vue
+++ b/frontend/src/views/usage/components/UsageRecordsTable.vue
@@ -1,8 +1,8 @@
 <script setup lang="ts">
+import type { BaseTableColumn } from '@codex-proxy/ui'
 import type { UsageDisplayRecord } from '../utils/records'
-import type { BaseTableColumn } from '@/components/base/BaseTable/columns'
+import { BaseTable } from '@codex-proxy/ui'
 import { Minimize2 } from '@lucide/vue'
-import BaseTable from '@/components/base/BaseTable/index.vue'
 import ProviderIconGroup from '@/components/ProviderIconGroup.vue'
 import {
   usageAccountText,
diff --git a/frontend/src/views/usage/components/UsageSummaryCards.vue b/frontend/src/views/usage/components/UsageSummaryCards.vue
index e9cdb2ce5..c42cfbb28 100644
--- a/frontend/src/views/usage/components/UsageSummaryCards.vue
+++ b/frontend/src/views/usage/components/UsageSummaryCards.vue
@@ -1,10 +1,9 @@
 <script setup lang="ts">
 import type { getUsageRecordSummary } from '@/api'
-import { Activity, Database, FileText, Timer } from '@lucide/vue'
+import { BaseCard, BaseMotionIcon } from '@codex-proxy/ui'
 
+import { Activity, Database, FileText, Timer } from '@lucide/vue'
 import { computed } from 'vue'
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseMotionIcon from '@/components/base/BaseMotionIcon.vue'
 
 const props = defineProps<{
   summary: Awaited<ReturnType<typeof getUsageRecordSummary>>
diff --git a/frontend/src/views/usage/composables/useUsageRecordsTable.ts b/frontend/src/views/usage/composables/useUsageRecordsTable.ts
index 472326c4a..fa665cca0 100644
--- a/frontend/src/views/usage/composables/useUsageRecordsTable.ts
+++ b/frontend/src/views/usage/composables/useUsageRecordsTable.ts
@@ -5,11 +5,13 @@ import { watchDebounced } from '@vueuse/core'
 
 import { computed, onMounted, onScopeDispose, shallowRef, watch } from 'vue'
 import {
+  getUsageProviders,
   getUsageRecordInsightsDiagnostics,
   getUsageRecordInsightsOverview,
   getUsageRecords,
   getUsageRecordSummary,
 } from '@/api'
+import { useRequestState } from '@/composables/useRequestState'
 import { withMinimumDuration } from '@/utils/async'
 
 interface UseUsageRecordsTableOptions {
@@ -37,6 +39,8 @@ export function useUsageRecordsTable(options: UseUsageRecordsTableOptions) {
   const searchQuery = shallowRef('')
   const search = computed(() => searchQuery.value.trim() || undefined)
   const providerQuery = shallowRef('')
+  const providers = shallowRef<string[]>([])
+  const providerRequest = useRequestState()
   let tableParams = snapshot()
   const refreshingList = shallowRef(false)
   const diagnosticDimension = shallowRef('model')
@@ -79,11 +83,29 @@ export function useUsageRecordsTable(options: UseUsageRecordsTableOptions) {
     }
 
     await Promise.all([
+      ...(scope === 'all' ? [loadProviders(globalParams)] : []),
       ...(options.active.value ? [loadUsagePage(background)] : []),
       ...(scope === 'all' ? [loadUsageAnalytics(globalParams, background)] : []),
     ])
   }
 
+  async function loadProviders(range = options.latestTimeRangeParams()) {
+    const requestId = providerRequest.start()
+    try {
+      const result = await getUsageProviders({ startTime: range.startTime, endTime: range.endTime }, { signal: providerRequest.signal, silent: true })
+      if (providerRequest.isCurrent(requestId))
+        providers.value = result
+    }
+    catch (cause) {
+      if (providerRequest.isCurrent(requestId))
+        providers.value = []
+      providerRequest.fail(requestId, cause)
+    }
+    finally {
+      providerRequest.finish(requestId)
+    }
+  }
+
   async function loadUsagePage(background: boolean) {
     const requestId = ++tableRequestId
     tableController?.abort()
@@ -175,7 +197,7 @@ export function useUsageRecordsTable(options: UseUsageRecordsTableOptions) {
       return
     refreshingList.value = true
     try {
-      await withMinimumDuration(reloadLatestTable)
+      await withMinimumDuration(() => Promise.all([reloadLatestTable(), loadProviders()]))
     }
     finally {
       refreshingList.value = false
@@ -253,6 +275,10 @@ export function useUsageRecordsTable(options: UseUsageRecordsTableOptions) {
     pageSize,
     searchQuery,
     providerQuery,
+    providers,
+    providersLoading: providerRequest.loading,
+    providersError: providerRequest.error,
+    loadProviders,
     usagePagination,
     loading,
     analyticsLoading,
diff --git a/frontend/src/views/usage/constants.ts b/frontend/src/views/usage/constants.ts
index effa21231..9ce6719df 100644
--- a/frontend/src/views/usage/constants.ts
+++ b/frontend/src/views/usage/constants.ts
@@ -1,6 +1,6 @@
 import type { UsageDisplayRecord } from './utils/records'
 import type { OpsError } from '@/api'
-import { defineTableColumns } from '@/components/base/BaseTable/columns'
+import { defineTableColumns } from '@codex-proxy/ui'
 import { formatProvider } from './utils/format'
 
 type OpsErrorRow = OpsError
diff --git a/frontend/src/views/usage/index.vue b/frontend/src/views/usage/index.vue
index 6d57a6ad3..5c9bb87a2 100644
--- a/frontend/src/views/usage/index.vue
+++ b/frontend/src/views/usage/index.vue
@@ -1,16 +1,9 @@
 <script setup lang="ts">
+import { BaseCard, BaseIconButton, BasePageHeader, BaseSegmented, BaseSelect, BaseTableColumnSettings, BaseTablePagination, useTableColumns } from '@codex-proxy/ui'
+
 import { Eye } from '@lucide/vue'
 import { computed, shallowRef, watch } from 'vue'
-
-import BaseCard from '@/components/base/BaseCard.vue'
-import BaseIconButton from '@/components/base/BaseIconButton.vue'
-import BasePageHeader from '@/components/base/BasePageHeader.vue'
-import BaseSegmented from '@/components/base/BaseSegmented.vue'
-import BaseSelect from '@/components/base/BaseSelect.vue'
-import BaseTableColumnSettings from '@/components/base/BaseTable/BaseTableColumnSettings.vue'
-import BaseTablePagination from '@/components/base/BaseTable/BaseTablePagination.vue'
-import { useTableColumns } from '@/components/base/BaseTable/useTableColumns'
-import ProviderFilterSegmented from '@/components/ProviderFilterSegmented.vue'
+import ProviderFilter from '@/components/ProviderFilter.vue'
 import OpsErrorPanel from './components/OpsErrorPanel.vue'
 import UsageFilters from './components/UsageFilters.vue'
 import UsageInsightsGrid from './components/UsageInsightsGrid.vue'
@@ -35,6 +28,10 @@ const {
   currentPage,
   searchQuery,
   providerQuery,
+  providers,
+  providersLoading,
+  providersError,
+  loadProviders,
   usagePagination,
   loading,
   analyticsLoading,
@@ -67,10 +64,14 @@ watch(timeRange, () => {
     <BasePageHeader title="使用统计" description="查看请求用量、性能趋势与调用错误记录">
       <template #actions>
         <BaseSelect v-model="timeRange" :options="usageTimeRangeOptions" class="w-34" />
-        <ProviderFilterSegmented
+        <ProviderFilter
           v-model="providerQuery"
+          :providers="providers"
+          :loading="providersLoading"
+          :error="providersError"
           :disabled="refreshingList"
-          class="w-31 shrink-0"
+          class="shrink-0"
+          @retry="loadProviders()"
         />
       </template>
     </BasePageHeader>
@@ -159,6 +160,7 @@ watch(timeRange, () => {
             :latest-time-range-params="latestTimeRangeParams"
             :provider="providerQuery"
             :active="recordView === 'errors'"
+            @refresh="loadProviders()"
           />
         </div>
       </template>
diff --git a/frontend/tsconfig.app.json b/frontend/tsconfig.app.json
index a093243c1..b07604f27 100644
--- a/frontend/tsconfig.app.json
+++ b/frontend/tsconfig.app.json
@@ -7,7 +7,8 @@
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "paths": {
-      "@/*": ["./src/*"]
+      "@/*": ["./src/*"],
+      "vue": ["./node_modules/vue"]
     },
     "strict": true,
     "noUnusedLocals": true,
diff --git a/frontend/tsconfig.node.json b/frontend/tsconfig.node.json
index bd916875e..a82fc6fc2 100644
--- a/frontend/tsconfig.node.json
+++ b/frontend/tsconfig.node.json
@@ -6,6 +6,7 @@
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "types": ["node"],
+    "allowImportingTsExtensions": true,
     "strict": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index b27e5a34b..66e3c425e 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -7,6 +7,7 @@ export default defineConfig({
   base: '/',
   plugins: [vue(), tailwindcss()],
   resolve: {
+    dedupe: ['vue'],
     alias: {
       '@': fileURLToPath(new URL('./src', import.meta.url)),
     },