Files
codex-proxy-rs/backend/crates/gateway-plugin/sdk/docs/capabilities.md
T

801 lines
67 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 插件能力与回调
[返回 SDK](../README.md) · [清单与图标](manifest.md)
`contributes` 声明插件提供的处理器。安装者完整信任插件,宿主回调不需要权限声明或阶段授权,参见[完整信任](manifest.md#完整信任)
| 开发任务 | 入口 |
| --- | --- |
| 组合处理器 | [作者入口](#类型化作者入口) · [请求上下文](#请求上下文) · [能力与方法](#能力与方法) |
| 使用宿主资源 | [基础事实](#基础事实) · [额度刷新](#额度观测刷新) · [账号](#账号与凭据) · [自有资源](#自有资源与维护) · [Key 预算](#client-key-预算) · [模型](#key模型与模型调用) · [网络](#网络) |
| 扩展请求链 | [中间件](#洋葱中间件) · [上游适配器](upstream-adapters.md) · [模型目录](#模型目录) · [重试](#重试决策) · [路由、调度与观察](#路由调度与观察) · [入口认证](#数据面入口认证) |
| 管理与交互 | [状态、日志与迁移](#状态日志与迁移) · [管理页面](#管理页面公开入口与-cli) · [页面宿主桥](#页面宿主桥-v2) · [命令行](#命令行) |
## 类型化作者入口
启用 `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` 与打包 CLI 共用[作者清单入口](manifest.md),按清单响应 `plugin.register`,并在 `build()` 时核对必需处理器。
构建器在分派前检查阶段、解码控制参数与载荷。`TypedCall` 携带上下文、宿主客户端及取消信号,结果编码为 `TypedReply`,流式结果使用有界 `ResponseStream`
`management`、`command_line` 和 `middleware` 是常用组合入口;其余能力使用
`on(methods::..., handler)`。方法常量固定请求、响应、阶段与载荷位置,作者不手写 RPC 方法名。
状态迁移不是 capability:清单任一 `state[]` 声明了 `migratesFrom` 时,注册
`methods::STATE_MIGRATE`,构建器也会要求该处理器存在
控制参数只放普通元数据。CLI 参数、账号凭据和状态迁移批次使用二进制 JSON,管理 HTTP 正文使用原始字节。敏感载荷放进控制参数会在分派前被拒绝
## 请求上下文
关联入口请求的调用通过 `call.context().request` 读取同一个入口快照,覆盖认证、所有中间件挂载、路由、调度、重试、上游适配、观察事件和管理 HTTP/公开回调。注册、维护、命令行等没有入口请求的调用为 `None`
`RequestContext` 包含 `method`、`uri`(路径与查询串)、`http_version`、`headers`、`peer_addr` 和 `client_ip`。`headers` 保留重复项和原始字节;`peer_addr` 是直接连接对端的 IP 与端口,`client_ip` 是宿主按入口规则解析的来源 IP。插件可使用解析结果,也可结合地址和原始 headers 自行判断代理来源
快照在中间件修改请求前捕获,内部派生调用沿用原入口;WebSocket 回调使用握手上下文。当前处理阶段的正文、消息和变换后请求继续从各能力参数或正文资源读取,不复制到快照。上下文可能包含认证头等敏感信息,应避免直接记录或输出
## 能力与方法
Provider 固定为宿主内置的 OpenAI 与 xAI。宿主开放以下 11 类扩展能力,版本与声明规则见[扩展项简写](manifest.md#扩展项简写):
| 能力 | 类型化方法 |
| --- | --- |
| `middleware` | `PluginBuilder::middleware` / `middleware.handle` |
| `upstream_adapter` | `methods::UPSTREAM_ADAPTER_REGISTER`、`methods::UPSTREAM_ADAPTER_EXECUTE`,见[受管上游](upstream-adapters.md) |
| `model_router` | `methods::ROUTE_MODEL` |
| `model_catalog` | `PluginBuilder::model_catalog` / `methods::MODEL_CATALOG_REGISTER_V2` |
| `retry_policy` | `methods::RETRY_DECISION` |
| `scheduler` | `methods::SCHEDULE_ACCOUNT` |
| `observer` | `methods::OBSERVE` / `observer.observe`,按事件类型订阅 |
| `frontend_authentication` | `methods::FRONTEND_IDENTIFIER`、`methods::FRONTEND_AUTHENTICATE` |
| `management` | `PluginBuilder::management`;公开回调另用 `methods::MANAGEMENT_CALLBACK` |
| `command_line` | `PluginBuilder::command_line` |
| `maintenance` | `methods::RECONCILE`;无需功能绑定 |
## 宿主资源回调
所有回调都通过当前 `TypedCall.host` 发起,关联父调用及其取消信号。普通调用使用父调用剩余期限;已经建立的资源流按[会话生命周期](../README.md#帧与会话)回收,网络操作单独计时
用量扫描和完整分组统计使用 `HostClient::scan_usage_records`、`query_usage_statistics`,
对应 `host.usage.records.scan`、`host.usage.statistics.query`。返回的读取资源通过
`host.usage.read.next` 和 `host.usage.read.close` 拉取与关闭,SDK 提供 `UsageReader` 封装。
这些回调使用空控制参数和二进制 JSON 载荷,查询语义、快照与预算见[用量查询](usage-data.md#完整扫描与分组统计)
### 基础事实
基础事实接口提供账号分页、Key 分组绑定及额度观测。查询不进入模型执行链,也不触发计费;账号凭据使用[账号接口](#账号与凭据)读取
| SDK 方法 | 回调 | 查询与结果 |
| --- | --- | --- |
| `call.host.account_facts(query)` | `host.data.accounts.list` | `AccountFactsQuery`:可选 `provider_id`、`cursor`,必填 `limit`(1~200);按账号 ID 升序,`next_cursor=null` 表示本页已结束 |
| `call.host.quota_details(query)` | `host.data.quota.details` | `QuotaFactsQuery { account_id }`:读取完整额度事实,包含窗口归属、触顶和点数 |
| `call.host.check_access(query)` | `host.data.access.check` | `AccessQuery { client_key_id, account_ids, upstream_model }`:读取 Key 对指定账号及可选上游模型的冻结授权 |
| `call.host.verify_client(request)` | `host.client.verify` | `VerifyClientRequest { authorization }`:复用入口认证,返回 `VerifiedClient { client_key_id }` |
| `call.host.quota_history(query)` | `host.data.quota.history` | 按账号、窗口键和时间范围分页读取已保留的额度观测 |
| `call.host.quota_facts(query)` | `host.data.quota.get` | `QuotaFactsQuery { account_id }`:读取 Provider 现有观测,不访问上游刷新 |
| `call.host.key_facts(query)` | `host.data.keys.get` | `ClientKeyFactsQuery { client_key_id }`:读取当前 Key 的启用状态及显式分组 ID,不返回密钥 |
类型在 `call::data`。控制参数为 `{}`,查询和结果使用二进制 JSON;事实结果固定 `schema_version=1`,认证结果只包含 `client_key_id`。
SDK 解析响应时忽略未知字段,包含账号分页、账号及额度窗口;已知字段按声明校验类型与必填性,账号、Key 与额度查询拒绝未知字段,认证与权限查询忽略未知字段。
插件须通过 `engines.codex-proxy-rs` 限定支持所用接口和字段的宿主版本
`key_facts` 每次读取当前管理数据,返回 `client_key_id`、`enabled`、`group_ids`;不存在的 Key 沿用事实接口的 `rejected` 错误
`group_ids` 表示显式绑定,包含停用分组,不是最终可路由账号集合;空绑定也不代表单账号范围。通过 `account_facts` 关联账号时需完整遍历分页,结果包含停用账号。跨查询关联及同步策略由插件负责,这些调用不构成跨查询事务,管理员修改绑定后应重新检查。
账号仅返回 `account_id`、`provider_id`、`name`、`email`、`group_ids`、`enabled` 和 `updated_at_ms`,不附带令牌或代理信息。
`name` 和 `email` 来自宿主已保存的账号资料;没有邮箱时 `email=null`,读取不会请求上游个人信息。
`quota_facts` 仅返回观测时间与窗口的 `key`、`window_seconds`、`used_percent`、`reset_at_ms`。
时间均为 UTC Unix 毫秒,比例为百分数;未知值保留 `null`,不能解释为 0。`observed_at_ms=null` 表示没有可用观测时间,
不保证当前缓存新鲜,不提供历史快照或多个查询之间的原子一致性
`quota_details` 保留 Provider 已解释的 `limit_reached`、窗口 `group`、`label`、`limit_id`、`limit_name`、`role`
及点数 `has_credits`、`unlimited`、`balance`;缺失值仍为 `null`,不返回上游原始文档,不发起刷新
`quota_history(QuotaHistoryQuery { account_id, window_key, start_ms, end_ms, cursor })` 按请求完成时间倒序返回
`[start_ms, end_ms)` 内的同桶读数。窗口键与 `quota_details` 相同,区间最长 366 天。每个样本包含
`observed_at_ms`、`used_percent` 和当时观测到的 `reset_at_ms`、`plan_type`,后两项可为 `null`。
首次省略游标;即使 `samples` 为空,只要有 `next_cursor` 就沿用原查询继续。末页的 `baseline` 是起点前最近的同桶读数,
最多向前查一个等长区间。例如查最近 48 小时,基线最多再向前找 48 小时;没有基线时返回 `null`
历史来自保留的已结束请求,不含独立额度刷新。Provider 未提供可解析的同桶观测时没有样本。
缺样不代表零;跨重置或套餐变更不能直接相减。这是观测记录,不是精确消耗账本。
分页不冻结数据,长区间建议在后台读取并复用结果
`verify_client` 使用当前请求设置和原认证计划,包含外部 principal 到 Key 的映射;没有 HTTP 入口时使用当前发布配置。
认证可以调用认证插件,继续扣减父预算并响应取消;验证成功不做推理准入、账号租约、使用记录或计费。
授权原文只作本次认证输入,不进入返回值
`check_access` 与 `host.models.list`、显式 Key 模型执行共用父调用内的身份和冻结权限快照。
账号或模型不在冻结范围内时返回 `allowed=false`,不存在或不可用的 Key 沿用 Core 的身份拒绝。
它们不建立模型执行图,不受模型递归深度或当前实例已入链影响;健康、冷却、额度、租约与实时可用性由实际执行检查。
`upstream_model` 使用上游模型名,省略时只判断账号范围;返回结果不承诺后续请求一定可以执行
```rust,ignore
use gateway_plugin_sdk::call::data::{AccountFactsQuery, QuotaFactsQuery};
let page = call.host.account_facts(AccountFactsQuery {
provider_id: Some("openai".into()), cursor: None, limit: 100,
}).await?;
for account in page.accounts {
let quota = call.host.quota_facts(QuotaFactsQuery { account_id: account.account_id }).await?;
// 插件自行解释样本的新鲜度并计算展示或预测结果。
}
```
`observer` 的 `request_completed` 事件提供请求最终用量、时间和结算事实;该投递有界、不是历史补偿接口。
本接口不提供 SQL、池汇总、健康分、额度预测或历史使用记录查询;插件结果保存在自身 `host.state.*` 中
### 额度观测刷新
- `call.host.quota_facts(query)` / `host.data.quota.get`:读取已有快照,不访问上游
- `call.host.refresh_account_quota(query)` / `host.quota_observations.refresh`:请求 Provider 刷新观测
两个方法均使用 `call::data::QuotaFactsQuery` 和 `QuotaFacts`,控制参数为 `{}`,输入输出在二进制 JSON 中。刷新复用原生 Provider 的凭据、代理、超时及观测落库规则
刷新观测不会消费额度重置券,也不会自动重置任何 Key;Provider 仍可能依据真实上游响应更新账号可用性观测
接口不承诺每次得到不同的周期或样本,也不保证结果对应一个账号重置事件。不存在账号返回 `rejected`;
Provider 不支持刷新(如 OpenAI URL + Key 账号)返回 `invalid_input`,其他失败沿用原生管理错误映射。
刷新受父调用期限和取消约束;结果未知不表示观测未落库。SDK 不自动重复调用,插件应控制刷新频率并处理失败,
不能把失败、空值或旧快照当作额度恢复
### 账号与凭据
账号接口使用 `host.auth.list/get_runtime/get/save`:
- `list` 可用 `provider_id` 过滤并分页,返回不含原始凭据的运行投影
- `get` 的原始凭据只放在二进制载荷中
- `save` 新建时显式提供 Provider,由宿主生成账号 ID;替换时必须提交精确 credential revision
插件可以自行选择其业务需要的账号和 Provider,不需要安装器预先配置允许列表。宿主仍校验账号归属、资格、
凭据版本和并发事务;原始凭据不得进入日志、审计正文或控制元数据
### 自有资源与维护
声明 `maintenance` 并注册 `methods::RECONCILE`,宿主会在实例启用发布、进程恢复及配置变更后调用
`plugin.reconcile`,每轮完成后等待 30 秒补偿。处理器必须幂等;调用可能重复,配置通知会合并,不表示逐条账号事件。
每个实例串行执行,不同实例相互独立;处理预算按[会话声明](../README.md#声明调用预算)生效,返回值不消费,调用失败后等待 5 秒重试。维护失败不回滚已经提交的资源,
下一次对账继续补齐。只读校验、准备候选与 CLI 帮助不会启动维护;停用、替换和宿主关闭时取消旧任务
维护与其他处理器共用以下资源方法:
| SDK 方法 | 参数与行为 |
| --- | --- |
| `call.host.ensure_group(GroupEnsureRequest)` | `resource_key`、`name`、`color`、可选 `description`;首次创建,之后返回已有 `{id,name,enabled}` |
| `call.host.change_group_members(GroupMembersChange)` | `resource_key`、`add`、`remove`;两列表合计最多 200 个账号 ID,不得重复或交叉,返回实际 `added`/`removed` 数量 |
| `call.host.ensure_key(KeyEnsureRequest)` | `resource_key`、`name`、非空 `group_resource_keys`(最多 64 个)、`max_concurrency`、`requests_per_minute`、`daily_limit_usd`、`weekly_limit_usd`;返回 `{id,name,enabled}`,预算零值沿用原生无限制语义 |
资源键使用 1~64 位小写字母、数字、`_`、`.`、`-`,首位为字母或数字,在实例和资源类型内唯一。
归属由宿主签发,插件不能指定其他实例。`ensure` 只在首次创建时使用属性,不覆盖管理员对名称、启用状态或限制的修改;
同名的管理员资源不会被接管,名称冲突会失败。账号已被删除时增量加入会忽略该 ID。
无实际变化时不会写审计或递增配置版本。创建与归属登记、成员变更、实例版本复验均在同一事务完成
插件升级沿用实例资源;停用保留分组和 Key,其原生启用状态保持不变。删除实例解除归属,资源仍由管理员管理;
重新安装为新实例不会接管旧资源。管理员删除自有资源后,仍启用的维护逻辑可在下次对账重新创建。
Key 明文仍通过宿主管理面查看,插件模型调用使用返回的 Key ID
典型处理器先确保分组存在,再通过 `data` 分页查询账号并增量补齐成员,最后确保 Key 存在。
插件可将当前及未来新增账号纳入分组,筛选和同步策略由插件决定
### Client Key 预算
预算接口可查询和修改全部 Client Key 的日/周金额上限、用量与窗口,包括管理员和其他插件创建的 Key
类型位于 `call::key_budgets`;下列预算方法控制参数为 `{}`,输入输出为二进制 JSON:
| SDK 方法 / 回调 | 输入与结果 |
| --- | --- |
| `get_key_budget` / `host.keys.get_budget` | `{client_key_id}`;返回 `KeyBudget`,包含 ID、日/周上限及已用金额、日/周重置时间 |
| `update_key_budget_limits` / `host.keys.update_budget_limits` | `{client_key_id, daily_limit_usd?, weekly_limit_usd?}`;至少指定一项;返回 `{client_key_id}` |
| `reset_key_budget` / `host.keys.reset_budget` | `{client_key_id, period}`;`period` 必填,取 `daily`、`weekly` 或 `all`;返回 `{client_key_id}` |
| `get_key_budget_window` / `host.keys.get_budget_window` | `{client_key_id, period}`;`period` 为 `daily` 或 `weekly`;返回 `{revision, explicit, starts_at_us, ends_at_us, used_usd}` |
| `set_key_budget_window` / `host.keys.set_budget_window` | `{client_key_id, period, expected_revision, window}`;返回 `{revision}` |
`list_keys` / `host.keys.list` 仍可查询非秘密目录,仅返回 `{id,name,enabled}` 和游标,沿用目录的控制参数编码。
上述操作均接受 Key ID,不接受 Key 明文,也不要求先查询目录
金额为非负十进制字符串,沿用原生金额精度;上限 `"0"` 表示不限。`KeyBudget` 的字段为
`daily_limit_usd`、`weekly_limit_usd`、`daily_used_usd`、`weekly_used_usd`、`daily_resets_at_ms`、`weekly_resets_at_ms`;
时间为 UTC Unix 毫秒,原生窗口尚未开启或已过期时返回 `null`;显式窗口到期后仍保留金额与结束时间。
读取不触发准入、开启窗口或清零,停用的 Key 仍可管理
上限更新仅写入提供的日/周金额;省略或 `null` 的项保持不变。它保留已用金额、窗口到期时间、费用历史及其他 Key 配置。
写入复用 Key 行锁,与结算串行;实际变化时实例版本复验、修改、配置 revision 和审计在同一事务提交,并通知原生配置发布。
相同值再次赋值不产生新 revision 或审计;并发更新按事务顺序生效,同一字段由后提交的值覆盖,接口不提供调用去重或比较交换。
将非零上限降低到已用金额及以下会拒绝后续准入,提高限额可恢复准入,在途请求仍按原生规则完成和结算
重置清零所选周期、退出显式模式并清除到期时间,保留额度上限、密钥和历史费用事件;所选窗口下次使用时按原生规则重新开启。
费用按完成时间归属,重置前完成但延迟落盘的费用不会重新扣入已重置周期,重置后完成的在途请求仍正常扣额。
实例版本复验、清零和审计在同一事务提交,推进窗口 revision,不推进配置 revision。每次调用均执行新重置,可能清掉两次调用之间的新消费
SDK 不自动重试。超时或断连不能证明写入未提交;重试上限赋值也可能覆盖期间其他调用的修改。
不存在的 Key 返回 `rejected`;写入事务复验发现实例停用或版本变化时返回 `conflict`,
非法输入返回 `invalid_input`。账号关联、预算分配和重置触发由插件决定,宿主不自动串联上述接口
显式窗口的 `window` 为 `{starts_at_us, ends_at_us}`,两端均为 UTC Unix 微秒,采用左闭右开区间,起点须早于终点。
接管已有窗口时,直接回传 `get_key_budget_window` 返回的微秒值;截断到毫秒可能改变窗口边界。
设置窗口保留金额上限,并从原生费用事件计入区间内已完成请求;待落盘费用由现有准入和结算路径处理。
窗口未开始或已到期时拒绝新请求,错误码为 `key_budget_window_inactive`,即使金额上限为零也不放行;
宿主不按日历推进显式窗口。结算按完成时间归属,迟到费用不会计入其他周期。
`window` 必填;传 `null` 退出显式模式并保留当前边界与消费。起点之前仍拒绝准入,到期后按原生规则继续
业务备份不包含逐请求费用。若新边界需要缺失的费用历史,设置返回 `conflict`,原窗口不变。
相同边界可以沿用已用金额;起点不早于完整费用历史的窗口可正常设置。新周期到来前无需清零
`expected_revision` 来自窗口查询,作为该 Key 的操作标识。日/周控制操作共用窗口 revision,
设置窗口或手动重置时递增,消费和日历滚动不推进。操作参数、窗口与审计在同一事务提交:
- 最近一次提交以相同版本、调用来源与参数重试,返回已提交的 revision,不重复改金额或写审计
- 同一版本换参数、较旧版本或尚不存在的版本均返回 `conflict`
- 只保存最近操作的参数,不保存历史回包;新操作先读取当前窗口版本
账号关联、观测新鲜度与周期判断由插件负责,宿主不推断账号周期,也不维护插件同步进度。
插件在私有状态中保存完整待提交操作,再调用窗口接口;结果未知时保留原参数重试,收到冲突后由插件决定如何处理。
私有状态与预算修改不是同一事务。停用插件不会撤销已设窗口,窗口到期后仍拒绝准入;
可显式释放控制,或通过原生手动重置恢复日历规则
### Key、模型与模型调用
- `host.keys.list`:分页返回 `{id, name, enabled}`
- `host.models.list`:以显式 `client_key_id` 查询该 Key 当前可见的模型目录
- `host.model.execute[_stream]`:交给 Core 的路由、准入、租约、重试、账本和计费链路执行
- `host.model.stream_read/close`:读取或关闭当前父调用创建的有界流
模型请求正文使用独立的二进制载荷,不共用响应缓冲预算。宿主从有效设置
`responses_max_decompressed_body_bytes` 取得原始正文预算 `L`,通过
`call::model::request_payload_limit(L)` 为内部请求预留 JSON 字符串转义和元数据空间
(`2 × L + 64 KiB`,受请求编码的 32 位分段长度约束)。超限返回带 HTTP 413 的
`invalid_input`,不启动模型执行。上游适配器的请求 `GPAQ` 也使用请求预算,响应事件仍受
原有 8 MiB 编码上限、Runtime 缓冲预算及流控窗口限制
HTTP 和 request 中间件使用有效请求设置。attempt、outbound、路由、调度、重试及上游适配器沿用冻结的模型请求预算。
显式 Key 的预检与执行共用父调用内的身份快照,后续发布的配置在新的父调用解析身份时生效
`ModelExecuteRequest.client_key_id` 可显式选择执行 Key,不与触发插件的父请求 Key 求交。省略时继承现有模型父请求身份;没有模型父请求的调用必须提供 Key。所选 Key 的启用状态、模型规则、账号组、并发和预算继续由 Core 执行
嵌套调用与显式 Key 调用继承入口快照中的客户端 IP 和 User-Agent;没有 HTTP 入口的后台调用保持来源未知
模型事件使用 `call::model::ExecutionEvent` 的 `GPE2` 封套,将 canonical 事实、宿主事实和原始 wire 分段编码。`host` 包含费用及定价明细、完整上游观测、会话状态和改写来源;当前 wire 与原始 wire 都保留二进制字节;`WirePayload::WebSocket` 独立保留完整文本消息和可选 JSON 视图,不把未知文本改造成 SSE。读取或回传快照不触发第二次计费、续接提交或发送状态更新。
非流式模型结果通过 `ModelEventBatch` 的 `HME1` 有界二进制批次返回;流式句柄只在创建它的父调用内有效。
发起回调的插件实例在子调用中跳过,Core 在单次执行的子调用图内限制递归深度、总数和并发,避免插件调用自身形成环。
每次模型执行独立计时并建立调用图。父调用结束会取消未完成的执行,连接空闲不消耗后续执行的期限
`host.affinity.lookup` 查询 Provider 已持久化的真实亲和键。命中只是账号偏好,
后续执行仍重新检查当前 Key 规则、账号资格和租约
### 网络
`HostClient::http(request, body)` 返回响应头与 `HostHttpBody`。正文用 `read()` 按需读取,
用 `collect(maximum_bytes)` 有界收集,提前结束用 `close()`;EOF 与重复关闭不再调用宿主。
父调用取消或结束时宿主回收未关闭的流,SDK 不后台预读。取消一次 `read()` 等待后,再次读取会继续同一次操作,不丢弃已经返回的分块。
账号上游使用同一正文对象,使用方式见[受管上游](upstream-adapters.md)
`HostClient::account_http(AccountHttpRequest { account_id, credential_revision, request }, body)` 经 `host.http.account` 使用账号代理并返回 `HostHttpBody`。每次发送要求账号存在、已启用且凭据版本匹配。版本变化时须重新读取凭据。
插件提供请求头与正文,宿主不注入账号认证或申请推理租约。无显式代理时使用部署默认出口,代理不可用时直接失败
`HostClient::proxy_http(ProxyHttpRequest { proxy_id, request }, body)` 经 `host.http.proxy` 使用指定代理,无需绑定账号,返回响应头与 `HostHttpBody`。
宿主每次发送读取代理配置,已发出的请求沿该出口完成。代理不存在、禁用或连接失败时直接报错,历史测试结果不限制发送。插件提供目标请求头与正文,宿主仅处理代理认证
`HostClient::list_proxies(ProxyListRequest { page, page_size, search })` 经 `host.proxies.list` 查询代理目录。
`page` 从 1 开始,`page_size` 为 1–200,`search` 可省略,默认空字符串,最多 256 字节且不能包含控制字符。
返回 `{ items: [{ id, name, enabled }], total, page, page_size }`,包含禁用代理,不返回连接地址、凭据或账号信息。
查询和结果使用二进制 JSON 载荷,控制参数及结果均为 `{}`;目录展示不代替发送时的状态校验
请求和响应 `headers` 使用 `(String, Vec<u8>)`,保留重复头与非 UTF-8 值;响应另有 `http_version`。
读取至 EOF 后通过 `body.trailers()` 取得完整尾部头,读取中只包含已收到的部分。
`collect` 只返回正文,需要尾部头时使用 `read`;底层非流式回复携带 `trailers`,流式回复在 `stream_read` 中交付尾部头
`host.http.do/do_stream` 和流读取/关闭方法提供受管 HTTP。正文使用独立二进制载荷,Host 统一执行代理、超时和背压,不按插件身份限制目标地址段。DNS 由宿主解析,连接保留目标 Host 与 TLS 域名校验;重定向不会自动跟随。
受管 HTTP(包括 `host.http.account`、`host.http.proxy` 和 `host.upstream.http.do[_stream]`)的请求正文按有效设置
`responses_max_decompressed_body_bytes` 检查。HTTP/request 中间件使用有效请求设置;
attempt、outbound、路由、调度、重试和上游适配器使用执行冻结预算,其余调用读取当前发布配置。
超限返回带 HTTP 413 的 `invalid_input` 和 `not_sent`,不向目标发送请求。
注册阶段沿用正在编译的配置预算,首次发布前也可发送非空正文。
非空正文无法取得有效配置时拒绝调用;无正文查询不消耗正文预算。
这里检查实际出站正文,内部模型请求的转义余量不增加出站预算。响应缓冲及流窗口不随请求配置扩大
普通调用使用父调用剩余期限;已建立的受管 HTTP 流或 WebSocket 会话按每次网络操作计时,仍受父资源取消约束
期限耗尽返回 `timeout`,解析、连接或响应读取失败返回 `upstream`。错误 `details.kind` 和 `details.reason` 保留 Host 的故障分类与原因标记,响应正文仍由插件读取;协议故障不应直接展示内部消息
## 请求扩展
### 洋葱中间件
`middleware.version: 6` 的所有挂载使用同一个 `ctx + next` 组合器。清单显式选择处理边界,绑定决定顺序;
不按 URL、消息类型或每个内部步骤增加处理器。仅处理一个边界可直接声明其调用类型;跨边界插件使用 `MiddlewareCall`
在一个处理器内匹配类型化视图,不感兴趣的调用交给 `call.forward().await`
| 挂载 | SDK 视图 | 默认终端 |
| --- | --- | --- |
| `http` | `HttpCall` | 路由匹配、认证、正文解析与既有 HTTP handler |
| `websocket` | `WebSocketCall` | 入站业务消息分派/出站连接写入 |
| `service` | `ServiceCall` / `TypedServiceCall<O>` | 已登记的公开业务服务 |
| `request` | `RequestCall` | 一次逻辑模型请求 |
| `attempt` | `RequestCall` | 本次已选 Provider 和账号的执行 |
| `outbound` | `OutboundCall` | 原样返回准备结果,不发送网络 |
`PluginBuilder::middleware` 与 `MiddlewarePlugin::new` 共用 `MiddlewareInput` / `MiddlewareOutput`。
`next.run(input)` 消费自身,最多执行一次;结果按相反顺序经过外层。重试或独立子请求通过宿主执行服务发起
调用上下文的 `timeout_ms` 限制插件自身处理时间,入站与返回处理合计使用同一预算。
父处理任务真正挂起时释放执行名额,恢复取得授权后继续同一次调用。仅等待 `next` 时暂停处理预算;并行包含普通回调时继续计时,具体规则见[并发与期限](../README.md#并发与期限)。
排队、在途容量与过载行为见 [SDK 并发与期限](../README.md#并发与期限)。
请求总期限、下游操作超时和取消信号独立生效,客户端取消或插件退出会结束等待并回收资源
HTTP 总入口统一包裹原生路由,`dispatch_http` 复用同一路由与组合能力;无需为每个 HTTP 接口登记新的挂载点。
`service` 用于不经过 HTTP 的类型化主动调用,具体公开范围见下节
#### 公开服务
服务合同位于 `call::services`,`Operation` 关联稳定名称、输入和输出类型。
`HostClient::service::<O>(input)` 主动调用服务;`ServiceCall::is::<O>()` 匹配操作,
`into_typed::<O>()` 取得可修改输入、单次 `next`、父调用标识及宿主客户端。
返回 `ServiceResponse::from_result::<O>(result)` 可以改写结果、短路或恢复业务错误;
不感兴趣的操作调用 `forward()`。公开值完整传递,类型校验不承担字段权限控制
`settings` 提供 `Load`、`PreviewPrivacyPolicy`、`Replace`、`ApiKeyExists`、`RegenerateApiKey`、`DeleteApiKey`、
`Pricing`、`PreviewPricingSync`、`Sync`、`Update`、`ClientProfileOptions`、`PreviewClientProfile`。
插件回调和 CLI 经注册表主动调用时统一进入一次 `service` 组合;网关原生设置接口由 HTTP 总入口包裹。
各入口共用同一业务实现,业务方法内部调用不重复进入 `service` 组合。
其他管理接口复用既有 HTTP 路由,不要求按内部方法另建服务目录;既有账号、Key 等资源回调不自动进入 `service` 组合
`Load` 返回完整运行设置与 `config_revision`。`ReplaceRuntimeSettings::from(settings)` 保留该版本并构造更新命令;
`Replace` 接收 `(MutationContext, ReplaceRuntimeSettings)`,通过已有校验、事务、审计和快照发布保存设置。
版本过期返回 `ServiceError { kind: "conflict", message }`。读取结果的普通改写不会持久化,也不会回滚已经提交的事务
`accounts::GetResetCreditAutomation` 接收账号 ID,返回 `ResetCreditAutomationStatus`:开关、全局提前分钟数、
生效的周额度触发值(临期模式为 `None`)、下次发现与使用时间、最近结果;时间为 RFC 3339 字符串,无计划时为 `None`。
`accounts::SetResetCreditAutomation` 接收 `(account_id, enabled)`,返回保存后的同一状态;审计主体与调用标识由宿主提供。
两者复用原生账号校验和自动重置用例,不立即查询或消费上游卡片。使用时机、提前时间与剩余周额度上限通过 `settings::Load` / `Replace` 的
`reset_credit_on_low_weekly_quota`、`reset_credit_lead_minutes` 和可选的 `reset_credit_max_weekly_remaining_percent` 读取和设置,范围见[主动额度重置卡](../../../../../docs/api.md#主动额度重置卡)
```rust,ignore
use gateway_plugin_sdk::call::services::accounts::{GetResetCreditAutomation, SetResetCreditAutomation};
let status = host.service::<GetResetCreditAutomation>(account_id.clone()).await?;
let status = host.service::<SetResetCreditAutomation>((account_id, true)).await?;
```
服务错误保留分类与完整业务文案,子调用继承冻结发布计划及取消信号。
插件显式再次调用服务时继承发起实例链并跳过相同实例,防止无限递归;无 service 绑定时直接分派业务实现,仍保留空计划快照、父子关联和取消信号。
原生业务方法保留类型化调用,不为服务组合增加 JSON 编解码
#### HTTP 入口
`HttpCall.request` 提供 method、URI(含 query)、HTTP version、完整多值 headers、`settings`、`timeout_ms` 和 `HttpBody`。
调用发生在路由匹配之前,管理接口、模型接口和未知路径都可参与。`settings` 是同一请求快照中的宿主运行设置,
插件改写后的设置用于认证、版本检查、正文解压及执行。`timeout_ms` 默认取宿主 HTTP 超时,
插件可改写或用 `None` 清除;终端按有效值执行,不恢复宿主默认值。宿主快照不可用时 `settings` 为 `null`
`POST /v1/chat/completions` 在 HTTP 挂载中保留 Chat 请求与 Chat JSON/SSE 响应视图,
转换为 Responses 发生在内层模型入口。自行按 URI 筛选、改写或分派模型请求的 HTTP 插件,
需要将该路径包含在自身匹配范围内;只匹配 `/v1/responses` 不会覆盖 Chat
`HttpCall.settings_sources` 返回 `config_revision`、宿主 `host` 基线、运行设置的 `overrides`、Key 作用域的 `execution` 与 `http_timeout`。
每条改写记录含 `instance_id`、`order` 和 `value`;来源由宿主记录,修改查询结果不会写入设置。
宿主比较提交前后的值,仅记录实际改变的设置项;同值赋值不新增改写记录。每个顶层设置项整体替换,`false`、`0`、
空映射及合同允许的 `null` 都是值,不进行隐式深合并。改写只属于当前调用,不修改持久设置
`HttpBody::read` 按需读取数据帧或 trailers;`map_frames` 包装上传或响应。透传只搬运句柄,保留原始分块、trailers、
request/response extensions 与连接升级状态。上传转换使用单帧有界管道;下游可在上传完成前返回响应,剩余生产随响应正文驱动,
提前拒绝不要求继续读完整个上传。每次调用最多保留 16 个活动上传管道,写入 EOF、显式关闭或消费端退出即归还名额。
读取、发送和生产都随父调用取消,不启动脱离调用的生产任务
取消一次宿主正文读取的等待不会丢帧,再次读取继续原操作;有未完成读取时转交 `HttpBody`,SDK 按输出背压保留该读取并转发剩余正文。读取量遵守宿主 Credit 窗口,已经在途的较大块会拆分保留
`HttpResponse::new` 创建短路结果。`next` 返回响应后可改写状态、headers 或包装正文;返回响应头不代表流已结束。
`host.middleware.next` 与 `host.http.body_*` 复用当前调用的 HTTP 资源池;已消费的 next 或正文句柄不能再消费一次。
读取 EOF 或转交正文会消费读取句柄;SDK 在 EOF 后继续读取返回 `None`,重复关闭不发起 RPC。
`body.close().await` 只关闭正文,仍可替换正文并返回原响应;响应部件保留到返回响应或调用资源池释放。
插件进程已经启动本次 HTTP 调用后,故障不会自动重放下游;无法启动且绑定为 `delegate` 时才直接委托
`HostClient::dispatch_http(HttpRequest)` 主动调用宿主相对路径,复用相同的路由、HTTP 洋葱链与惰性正文资源,不通过网络回环。
`HttpCall.call_id` 和 `parent_call_id` 表达父子关系,`context.request_id` 保持同一请求关联;子调用沿已冻结的计划运行并跳过所有发起祖先实例,最多嵌套 4 层。
主动管理请求使用宿主签发的插件身份和系统审计,不依赖父请求的管理员 Cookie;模型请求仍需提供用于模型范围与结算的 Key。普通 HTTP 请求头不能声明插件身份。
子调用继承当前配置快照与显式改写,`HttpRequest.settings = null` 表示沿用;提供对象时按设置项比较并替换。
切换 Key 后重新解析目标 Key 的默认画像和限额,父 Key 的默认值不会带入;运行设置改写继续生效,Fast、Key 限额和模型超时的改写只对原 Key 生效。同级调用的修改互不回写
主动 HTTP 分派计入模型父请求的副作用水位,避免下游失败后透明重放子调用。父调用取消会终止等待中的子请求与响应读取;转交正文不因父 RPC End 提前取消。消费完成会释放原正文,提前结束时调用 `body.close().await` 释放正文句柄
#### 自定义 WebSocket 会话
HTTP 中间件可调用 `call.upgrade(protocols, handler).await` 接管当前请求,返回仍经过外层 HTTP 中间件。
`protocols` 按插件给出的顺序与客户端协商子协议;握手不合法或当前请求不支持升级时明确失败。
默认路由不会再执行,路径选择、认证、协议解析及每条消息产生哪些模型调用由插件处理
`handler` 接收 `WebSocketSession`,使用 `receive().await` 读取完整消息,复制 `sender` 后可在接收等待期间独立发送。
在 `select!` 中取消一次 `receive` 等待不会丢弃消息,下一次等待继续同一次接收。
`close(code, reason).await` 发送关闭帧;处理函数返回、失败、插件退出或客户端断开时,宿主回收连接与调用资源。
会话的收发也经过已冻结的 `websocket` 消息组合,主动写入与接收不共享跨等待的独占锁
握手受初始调用期限约束。成功返回响应头后,会话持有同一发布代次及父调用,直至连接或资源终结;
101 正文完成不会取消会话。外层中间件替换响应会丢弃未提交的会话,改变已选择的升级状态码会被判为无效响应。
一个会话可通过捕获 `call.host` 发起多个独立模型执行;模型关联、用量和费用仍归各自执行所有
#### 下游 WebSocket 消息
`WebSocketCall` 提供连接 ID、握手完整 headers、`direction`、原始 `message`、单次 `next`、`sender` 和取消信号。
文本、二进制、Ping、Pong 和 Close 均携带原始正文;消息类型不由宿主预先按第三方协议筛选。
`WebSocketPayload` 按需读取,透传不读取、不复制正文;插件需要完整内容时自行 `collect().await`。
不再使用的句柄通过 `payload.close().await` 释放;读取到 EOF 或转交消息也会消费资源。
取消一次读取等待后可继续读取;未完成的读取须先继续消费或关闭,直接转交该消息会报错,避免静默丢弃在途正文。
单次调用最多保留 16 个未消费的消息正文,达到容量后需先消费或关闭已有句柄
`next.run(message)` 返回可继续修改的 `Option<WebSocketMessage>`;返回 `None` 丢弃当前消息。
`sender.send(message).await` 是当前连接的直接写入能力,等待实际 transport 完成,不递归进入消息中间件。
入站插件在响应进行中仍可处理未知控制消息并主动回写;是否转发到上游及其协议语义由插件决定。
消息正文可改写,实际写入、错误和取消事实由连接 owner 记录,丢弃消息不会记作写入成功
Ping 的自动 Pong 与关闭握手属于底层 WebSocket 协议事实;插件观察消息时,transport 可能已经产生应答。
重写消息不能撤销已经发生的发送。文本必须是 UTF-8,控制帧长度和关闭格式仍遵守 WebSocket 协议。
每条消息组合有独立 RPC 期限;自定义会话持有一个受管流式调用。连接结束会取消仍在处理的消息与发送
#### 上游出站准备
`outbound` 在 Provider 完成请求序列化后、提交发送前执行;无绑定或未命中范围时保留原生请求构造,不进入出站准备链。
`OutboundCall.request` 包含
`head.target`、Provider 已生成的完整 `head.headers` 和二进制 `body`;`target` 为 `Http { method, uri }`
或 `WebSocket { uri }`,不能在准备过程中切换传输类型。HTTP 正文是已经序列化、完成内容编码的实际字节,
插件自行处理压缩与 `Content-Encoding` 等头部的一致性;宿主不解码正文、补回字段或修复请求
内置转发在出站准备前,仅为已识别的互联上游组装 `X-CPR-Route`,向普通模型上游剥离。
插件改写目标或自行实现转发时,负责在互联节点间保留并维护路径,在最终模型上游前移除该头;宿主不在插件返回后重新判断或修复互联链路
`OutboundCall.metadata` 提供真实请求、Client Key、分组、Provider、模型、账号与 attempt 序号。
这些归属由宿主冻结,返回值只有请求;修改 URL、认证头或正文不改变账号租约、凭据版本与计费归属。
宿主不从最终字节重建模型、选号或续接事实;需要改变这些业务含义时,插件应在相应的 request / attempt 阶段保持一致。
头部保留重复项与原始字节,正文不经 JSON 编码。
这些头部是交给 transport 的字段集合;原生 HTTP 客户端 reqwest 会在缺少 `Accept` 时发送 `Accept: */*`,本能力不支持禁用该默认行为。
最终结果仍须符合原生 transport 的可编码格式与目标约束;xAI 的内置 transport 只接受固定官方推理端点,
当前原生 WebSocket 客户端不接受非 ASCII 握手头值,不可表示的值在发送前报错
`next.run(request)` 只进入下层准备链并返回完整请求,不打开连接、不发送消息;外层仍可修改返回值。
所有外层处理结束后,Provider 才把结果交给 transport 发送。插件错误、非法传输值或正文超限在原生发送前结束,
不自动跳过、重放或切换传输;取消、请求截止与回调资源沿用当前 attempt
身份策略可在 `request` / `attempt` 读取原始输入,以真实 Key 与账号标识调用私有状态服务维护映射,
再在 `outbound` 自行改写完整请求中的身份及关联字段。UUID 生成、并发创建、持久化、会话与缓存标识派生均由插件负责;
通用中间件层不解释 installation ID、device ID 等策略字段,也不在插件输出后重新派生业务字段
WebSocket 的 `body` 是准备发送的一条完整 UTF-8 文本消息,`headers` 和 `uri` 是候选 opening。
新响应链按出站改写产生的 URI / 握手头差异分区,精确续接仍使用持有原响应链的连接。
复用连接时不能改写已发生的握手;宿主不为插件主动重连、重放消息或重建续接。
插件需要握手身份与消息内容一致时,应结合实际连接与续接语义选择改写
```rust
use gateway_plugin_sdk::client::{OutboundCall, PluginBuilder};
let plugin = PluginBuilder::from_json(manifest_json)?
.middleware(|call: OutboundCall| async move {
let mut request = call.next.run(call.request).await?;
request.head.headers.retain(|header| header.name != "x-optional");
Ok(request)
})?
.build()?;
```
该处理器的清单声明 `middleware.version: 6` 和 `stages: ["outbound"]`,不需要单独注册网络发送方法。
当前内置 Provider 接入其模型执行所用的 HTTP 与 WebSocket 文本发送边界;OAuth、额度刷新等后台网络不属于模型出站准备
#### 模型请求与 attempt
`RequestCall.request.head` 包含完整 Client Key 与分组归属。request 中间件改写正文后,OpenAI 在进入 attempt 前应用宿主 Fast 策略;
attempt 中间件在此基线上继续改写,终端不再应用 Fast 策略。
request 与 attempt 阶段通过 `append_header` 添加的请求头会进入上游请求,不适合存放插件内部标记或仅供下游读取的信息。
OpenAI 与 xAI 的上游 headers 先由账号和画像生成,插件同名字段覆盖基线,同名多值按插件顺序保留;不存在按认证、Cookie 或会话名称划分的保护列表。
实际账号租约、凭据版本与计费归属仍记录真实选中事实,不随插件修改 header 名称而伪造
request 阶段 `request.head.settings` 是本次调用的有效设置对象,包含 `runtime`、`fast_mode`、`client_limits` 和 `timeout_ms`。
`fast_mode` 使用 `default`、`enabled`、`disabled` 三态,具体档位语义见[账号分组](../../../../../docs/api.md#6-账号分组)。
`runtime` 使用宿主快照的设置字段,画像已合并 Client Key 设置;可以修改映射、画像、调度、位置及计价等执行参数。
SDK 仅在对象改变时提交完整替换,`false`、`0`、空映射和合同允许的 `null` 不表示跳过;不做隐式深合并。
线协议省略 `next.settings` 才表示保留;显式 `null` 仍按完整替换校验,因不符合设置对象合同而拒绝。
多个插件按入站顺序读取前层改写后的值,终端在执行前从同一配置代次重算,改写不发布全局配置。
`timeout_ms` 默认为 `null`,表示不限制模型请求总时长;数值从本次模型请求开始计时,`0` 表示立即到期,
改写不会清零已用时间。HTTP 处理期限与 RPC 操作期限仍各自生效
此视图在客户端认证及初始协议解码之后出现:不会追回已经完成的版本准入或入口解压校验。
Responses 终端重新解码插件正文时读取改写后的正文上限;attempt 阶段的 `settings` 为 `null`,已经完成的准入不能经该入口重做。
更早的改写使用上述 HTTP 请求的 `settings`。`request.head.settings_sources` 使用相同的来源结构,`execution.input` 表示进入当前 Key 作用域时的有效值。
原生 Responses WebSocket 每轮请求读取当前宿主快照,重新认证并解析 Key 策略,同时保留握手阶段的显式改写;已开始的执行保持自己的冻结值
Chat Completions 在 request 与 attempt 挂载中使用规范化的 Responses 请求和响应正文,
`request.head.endpoint` 仍为 `/v1/chat/completions`,`protocol` 仍为 `openai`。
request 改写按 Responses 合同重新解码,响应先经过该合同的复核,再由 API 投影成 Chat 交给外层 HTTP 挂载。
Chat 的下游流模式及 `include_usage` 由 API 持有,request 阶段不能切换已确定的下游流模式。
同一边界的原样保留不要求 Chat 与 Responses 字节相同;需要读写 `messages` 或 `choices` 的插件应使用 HTTP 挂载,
字段范围见 [Chat 合同](../../../../../docs/api.md#chat-completions-请求)
Messages 入站的 `protocol` 为 `anthropic`,端点为 `/v1/messages`;计数使用 `/v1/messages/count_tokens` 与 `count_tokens` 操作
同协议请求保留原生正文,Responses 与 Messages 之间的转换发生在所选上游的执行边界
中间件可读取和改写完整请求、响应 headers、正文与响应帧,也不按字段名称过滤认证、Cookie、会话或连接头。
该能力遵循[完整信任](manifest.md#完整信任)边界;类型、HTTP 格式、大小及资源生命周期仍需符合合同
默认使用 `MiddlewareRequestBody::Preserve` 保持正文;`replace_body(Vec::new())` 明确清空。
Header 修改采用增量 remove/append,保留合法多值。`MiddlewareBody::map_frames` 复用会话的流控和唯一终态
`response.metadata` 提供 Provider、实际模型、账号、上游请求 ID 和账号选择观测。
`response.body.with_facts()?.inspect_frames(...)` 或 `.map_frames(...)` 通过 `frame.facts` 读取完整事件快照;纯事实帧可没有正文。
快照按需读取,未开启读取或未消费正文时不复制事件载荷;来源帧完成后对应句柄失效。
修改快照不会改变宿主确认的原执行事实,响应改写仍通过 headers、正文和受管调用完成
`next` 和模型子调用返回的 `PluginFault` 保留具体消息、发送状态、HTTP 状态及 `details`。
域错误详情包含分类、上游 type / code、重试提示和诊断;Provider 错误还包含请求标识、原始错误、HTTP 响应字节与多值 headers、连接及续接恢复事实。
公开服务的 `ServiceError.details` 保留跨进程错误详情。错误快照供插件读取,宿主继续持有原错误处理重试、发送与账本事实
**不改写就 1:1 保留**:同一网关处理边界上,默认 `next.run(request)` 保留原始正文、未修改的 header 和响应流字节及顺序。
只解析 `request.body` 不会触发替换;SDK 比较完整原始输入,只发送实际修改。
只观察响应可使用 `response.body.inspect_frames(|frame| { /* 读取,不修改 */ })?`,保留来源信封、背压和取消语义。
这一保证比较插件前后的同一边界,Provider 自身的协议适配、两次调用的随机值和网络分段不在比较范围内
`request.declare_capabilities(CapabilityDeclaration { handled, required })` 随单次 `next` 发出,必须同时显式替换正文。
当前仅允许 Responses 或 Messages 生成请求的 request 阶段,HTTP 与 WebSocket 共用规则;不扩展端点允许的协议或流模式。
Responses 与 Messages 的功能声明均按各自协议正文重新提取事实,声明不能改变请求协议
`handled` 只允许列举改写前确实存在、改写后已从实际请求移除的 `tools`、`vision`、`reasoning`、`json_schema`,
插件须负责对应的提示词转换及普通响应、错误、流式响应还原。`required` 为额外上游需求,不能覆盖正文推导出的要求。
重复项、同一项同时出现在两组、空声明、attempt 阶段使用声明均会拒绝。
原始语义中未由插件承担的功能继续约束路由;实际正文重新加入某功能时,该需求仍生效。
原生续接不能由声明豁免,attempt 已取得的账号租约与真实发送事实仍由原 owner 持有
```rust,ignore
use gateway_plugin_sdk::call::middleware::{CapabilityDeclaration, RequestFeature};
// 将 JSON Schema 转为提示词前保留原 schema,响应返回时按它验证并还原。
request.replace_body(convert_schema_to_prompt(&request.body)?);
request.declare_capabilities(CapabilityDeclaration {
handled: vec![RequestFeature::JsonSchema], required: vec![],
});
let response = next.run(request).await?;
restore_and_validate_response(response).await
```
仅实现中间件时也可使用轻量的 `MiddlewarePlugin`;需要与管理或其他方法组合时使用
`PluginBuilder`,两者复用相同的类型化调用与结果合同
用量查询、明细与聚合维护、费用试算使用 `call::services::usage`,输入输出和批量语义见 [用量查询、维护与计价](usage-data.md)
### 扩展的组合边界
请求处理沿 `request middleware → 原生选路与选号 → attempt middleware → 原生上游或 upstream_adapter` 推进,
响应按相反顺序返回;适配器是现有洋葱链的终端,不能再次调用 `next` 或组织换号重试
| 工作 | 组合方式 |
| --- | --- |
| 请求头/正文改写、提前拒绝、响应头处理 | `middleware` 包裹一次 `next.run(request)` |
| 响应逐帧转换、观察 | 返回惰性 `map_frames` / `inspect_frames`,不能在 `next` 返回时就把流视为结束 |
| Provider 已生成请求的最终 URL、头部或字节改写 | `outbound` 返回最终请求,Provider 随后发送 |
| 新上游路径、协议编码、错误及用量解析 | `upstream_adapter` 终端,复用已选账号和原生结算 |
| 账号代理、默认凭据注入、网络发送状态 | 宿主网络外层,插件可覆盖默认请求头,普通 HTTP 与账号 HTTP 共用发送和正文资源实现 |
| 路由、调度、重试决策 | 各自的决策端口,Core 保持最终裁决和预算 |
| RPC Credit、取消、流关闭、WebSocket 续接 | 会话及资源生命周期,不作为可重排的中间件 |
| 终态观察、管理与维护 | 对应的观察/管理/维护入口,不嵌入请求 `next` 链 |
### 模型目录
`model_catalog` 仅支持 v2,在 registration 阶段通过 `model_catalog.register` 一次提交
`ModelCatalogRegistrationV2 { aliases, models }`,不接受请求级 binding。
返回值必须同时包含 `aliases` 和 `models`,没有对应条目时使用空数组。
`aliases` 的每条 `ModelAlias { id, provider, model }` 定义公开 ID、Provider 及直接上游目标,条目正确性由插件负责。
别名条目重复、目标不存在或 Provider 未注册不阻止宿主快照发布。
请求按发布顺序取首个匹配条目,插件别名优先于静态映射,目标直接用于上游选路,不递归展开别名或目标上的静态映射
```rust,ignore
use gateway_plugin_sdk::call::catalog::{ModelAlias, ModelCatalogRegistrationV2};
let plugin = PluginBuilder::from_json(include_bytes!("../plugin.json"))?
.model_catalog(ModelCatalogRegistrationV2 {
aliases: vec![ModelAlias {
id: "team-default".into(), provider: "openai".into(), model: "gpt-target".into(),
}],
models: vec![],
})?
.build()?;
```
有效目录、路由和目标能力随同一个不可变快照发布,`/v1/models`、详情、原生目录和 `host.models.list` 共用该事实及现有 Key/账号模型范围。
目标存在时,别名复用目标的可公开对象;禁用后新请求不再使用该别名,在途请求持有旧代次。
别名仅表达直接映射,动态选择可组合 `model_router`;实际路由仍须通过宿主的权限和能力校验,不提供多目标虚拟模型注册合同
`models` 的每条 `AdaptedModel { id, adapter_id, features, max_output_tokens, presentation }`
声明一个受管适配器提供的公开模型,不要求内置 Provider 的原生目录存在同名条目
- `adapter_id` 必须指向同实例已绑定的 `upstream_adapter`,Provider 与非空账号集合取自该适配器声明
- 适配器及 binding 的模型范围必须覆盖 `id`;带 Key/账号组条件的适配器不能贡献静态目录,不能丢弃这些条件扩大可见范围
- `features` 使用 `RequestFeature`,仅为生成操作声明工具、图片输入、推理或 JSON Schema 支持;没有声明的能力不能借用同名原生模型的支持事实
- `presentation` 是独立通用画像,字段见 `call::catalog::ModelPresentation`;省略的布尔能力为 false,未声明推理档位不补猜
- `presentation.reasoning_summary` 独立声明 `reasoning.summary` 参数支持,默认 false;推理档位不代表摘要能力,只有能够处理该参数的适配器才声明 true,客户端目录相应使用 `auto` 或 `none` 作为摘要默认值
- 同名条目可关联不同账号,但 Provider、能力及画像须一致,账号集合不能重叠,也不能与插件直接别名同名,以免展示与实际选择产生歧义
- 别名与适配模型每实例合计最多 256 条,注册响应载荷最多 64 KiB;目录与适配器随同一代次发布,账号最终资格取当前 Key、分组及账号模型政策的交集
清单须显式声明 `model_catalog.version = 2`,可使用上述 `.model_catalog(...)` 固定目录,
或通过 `PluginBuilder::on(methods::MODEL_CATALOG_REGISTER_V2, handler)` 返回 `TypedReply<ModelCatalogRegistrationV2>`。
Codex 客户端目录保留 Provider 的完整原生对象。对于通用画像,当前账号范围内的同名适配模型使用插件声明的 `presentation`,
包括 xAI 这类由宿主转换的目录。仅由插件提供的可见模型按声明顺序追加到所属 Provider 的条目之后。原生目录读取失败时返回错误。
适配模型的 wire 模型名、协议编解码及摘要由插件负责,宿主只使用公开 ID、能力和账号范围参与现有选号,不生成请求正文或转换历史
### 重试决策
`retry_policy` v2 固定绑定 `retry` 阶段,故障策略只能为 `delegate`。使用 `methods::RETRY_DECISION` 处理 `RetryDecisionRequest`。
输入包含失败分类、必要状态码、发送状态、attempt 序号、Provider/上游模型、剩余路由次数和期限,以及 `allowed_actions`。
不发送账号凭据、请求正文或上游错误转储。路由次数不等同于 Provider 自有传输恢复预算
返回 `RetryDecision::Delegate`、`Stop` 或 `Retry`。Core 仅在允许动作包含 `Retry` 时继续已经选定的恢复路径;
不能指定账号、延迟、目标或提高预算。响应已交付、发送不明确、外部副作用及续接绑定等既有安全门不可绕过。
Core 处理建立响应流前与流中的失败,并在策略返回后再次检查期限、取消和副作用
```rust,ignore
use gateway_plugin_sdk::{client::TypedReply, call::policy::RetryDecision};
let plugin = PluginBuilder::from_json(include_bytes!("../plugin.json"))?
.on(methods::RETRY_DECISION, |call| async move {
let decision = if call.request.upstream_status == Some(429) {
RetryDecision::Stop
} else { RetryDecision::Delegate };
Ok(TypedReply::new(decision))
})?
.build()?;
```
按 binding 顺序、插件 ID、实例 ID 确定委托链,首个非委托决定交给 Core 处理。整条链共享匹配实例中最大的重试阶段预算,并受请求剩余期限约束;单个实例同时受自身声明预算约束。未声明时使用默认的 2 秒,预算规则见 [并发与期限](../README.md#并发与期限)。
退出、超时或无法解码的决定委托后续处理,最终回到宿主决定;额外字段忽略,故障不改写原始上游错误。
middleware 的 `next` 最多调用一次,重试与额外模型执行通过独立调用创建
### 路由、调度与观察
`policy.route_model` 和 `policy.schedule_account` 只提出决定,宿主随后复核 Key 规则、模型能力、账号资格和租约。
`scheduler` 必须声明 `version: 4`。`candidates` 已按 Key 范围、模型权限、账号状态和原生续写绑定收窄,
同时包含暂时繁忙但可以等待的账号;`available` 表示本次可以立即尝试租约,不保证租约一定成功
每个候选的 `session_bound` 表示它是否为 Provider 已查到的本次会话绑定账号。仅匹配缓存偏好不算会话绑定。`role` 表示本轮选号如何使用它:
| `role` | 含义 |
| --- | --- |
| `ordinary` | 普通候选。宽松模式下已有绑定也可以是普通候选 |
| `preferred` | 内置选号优先考虑,允许选择其他账号。xAI 的会话偏好由评分得出,不表示已有持久绑定 |
| `follow_only` | 委托内置选号时只跟随这个绑定账号,插件仍可显式选择其他合格候选 |
| `pinned` | 本次尝试已固定账号,例如原生续接;插件不能改选其他账号 |
关系只标在本轮可见候选上,繁忙不抹去关系,候选中没有绑定标记也不能断定是新会话。角色不授予账号资格,不代表已取得租约
- `Pick { account_id }` 显式选号,只能指定 `available: true` 的候选
- `Delegate` 将完整候选交给宿主现有调度
- `DelegateFiltered { exclude_account_ids }` 排除列出的候选,再委托内置权重、Smart 评分和亲和选择;仅接受本次候选 ID,重复 ID 合并,空列表等同于 `Delegate`
- `Reject` 明确拒绝请求
过滤结果约束本次评估后的亲和重选、容量判断和等待队列。全部候选被排除,或严格跟随的会话账号被排除时,
请求以 `account_policy_filtered` 结束,不回退到被排除账号或伪装成额度耗尽。租约争用、排队唤醒和后续请求重新评估策略,
过滤结果不写入账号状态。插件决定自身阈值、恢复条件和配置含义;宿主只检查合同、候选边界并执行决定。
插件设置使用自己的 `configurationSchema` 或管理页面,不向宿主智能调度弹窗注入字段。
调用失败或响应无法解码时按绑定的失败策略处理。Core 拒绝候选越界等无效调度决定,不自动修正插件业务规则
```json
{"decision":"delegate_filtered","exclude_account_ids":["acct_example"]}
```
`observer` v2 通过 `methods::OBSERVE` 接收 `call::observation::Event`,固定绑定 `observation/observe`。
每条绑定以 `event` 选择 `request_completed` 或 `websocket_response`,可分别配置请求范围;同一实例每种事件至多一条绑定,两类绑定使用相同 `order`。
事件选择只决定是否投递,不裁剪字段
- `Event::RequestCompleted` 包含一次最终请求事实,`terminal` 与 `usage` 始终存在;用量、费用与耗时的缺失值表示宿主没有该事实,不等于零
- `Event::WebSocketResponse` 观察实际上游 WS 事件,原始帧放在 `TypedCall.payload`,元数据放在 `request`;序号在请求内单调递增,有界队列丢弃可能产生间隔
两类事件共用 `observer.observe` 方法及同一处理器。观察计划在请求开始时冻结;完成事件最多派发一次,WebSocket 事件按请求保序;完成通知不等待 WebSocket 观察队列排空。
观察超时、过载或插件失败不改变业务响应,返回值不用于修改帧或重新计价。需要改写响应时使用洋葱中间件
```rust,ignore
use gateway_plugin_sdk::call::observation::Event;
let plugin = PluginBuilder::from_json(include_bytes!("../plugin.json"))?
.on(methods::OBSERVE, |call| async move {
match call.request {
Event::RequestCompleted(request) => record_completion(&request),
Event::WebSocketResponse(response) => record_frame(&response, &call.payload),
}
Ok(TypedReply::new(Empty {}))
})?
.build()?;
```
`Handshake`、`Message`、`Frame` 和 `PluginFault` 的调试输出隐藏配置、载荷与错误正文;插件自己的日志同样不能输出凭据或完整请求
## 状态、日志与迁移
清单 `state[]` 声明命名空间、`schemaVersion`、JSON schema、记录与字节配额。运行时用
`host.state.get/put/delete` 访问;创建要求键不存在,更新和删除必须提供精确版本。状态始终绑定当前
插件实例、制品和 schema;该接口操作插件状态,不代替宿主业务事务
不兼容升级由宿主停用并排空旧会话,再调用 `plugin.state.migrate` 分批迁移到暂存状态。插件逐项返回
keep、replace 或 delete;全部完成后宿主才原子提交新配置与状态,失败时丢弃暂存结果
`host.log` 接收固定事件名、级别和有界字段。宿主脱敏并限制速率;`recorded: true` 只表示已交给有界日志任务。
日志、状态与其他宿主回调都属于当前父调用,父调用结束后不能继续使用其资源
## 管理页面、公开入口与 CLI
`PluginBuilder::management` 同时冻结 `ManagementRegistration` 并绑定 `management.handle`。请求元数据在控制参数,
原始 HTTP 正文在二进制载荷;响应同样分离。`ManagementRequest.headers` 完整保留原始请求头,
`ManagementResponse.headers` 可显式覆盖宿主默认响应头;两者使用 `MiddlewareHeader`,保留重复项与非 UTF-8 值。
宿主只校验 HTTP 语法,不按 Cookie、Authorization 等字段名称裁剪。账号操作通过宿主账号接口执行,
资源由调用参数选择,不在路由注册中固定 Provider
页面运行在隔离 iframe 中,静态资源必须同时出现在清单 `resources` 和管理注册中。标记为公开的资源及一次性
票据回调按注册内容开放;`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
需要跳转到外部页面时,在插件页面的用户点击处理器中调用 `openExternal(url): Promise<void>`。
地址必须是绝对 HTTPS URL,不能包含用户名或密码。宿主展示目标主机名和非默认端口,管理员可打开新标签页、复制链接或取消。
Promise 成功只表示宿主已接受确认请求,不代表链接已打开;无用户操作、地址无效或已有链接待确认时,请求会被拒绝。
切换页面会关闭确认框。插件需要适配缺少此方法的宿主时,先检查 `typeof window.codexProxyPlugin.openExternal === 'function'`
普通模型请求使用标准 `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 候选及其可见模型;该便捷桥用 ID 选择推理身份,不需要页面提供 Key 原文。该请求进入普通 Responses 数据面,
因此当前实例自己的 middleware、router、scheduler 和
observer 也按常规计划执行;它不是插件执行期间的嵌套 `host.model` 回调。正文最多 8 MiB,每页最多 4 个并发模型
请求,总时限 10 分钟;响应以不超过 64 KiB 的单块 pull/ack 传输。页面 30 秒不继续消费响应、调用
`AbortController.abort()` / `ReadableStream.cancel()`,或页面被切换、停用、换版时,宿主都会取消请求。桥不接受
任意 URL、header 或 Key 原文;转交响应状态、浏览器 `Headers` 可读取的完整响应头以及原生 JSON / SSE 正文。
这些页面辅助方法不限制插件进程在统一 HTTP 中间件中读取、改写请求,或通过 `dispatch_http` 调用其他宿主接口
### 命令行
`PluginBuilder::command_line` 冻结命令帮助并绑定执行函数。注册和执行的 JSON 都位于二进制载荷,控制信封为 `{}`。
命令返回待保存账号时,只有退出码为零时宿主才按顺序执行各自独立的 CAS 提交。
模型命令通过 `host.keys.list` 展示非秘密 Key,再显式选择 Key 查询模型和执行,不依赖安装时预绑定
## 数据面入口认证
`frontend_auth.identifier` 返回稳定认证器标识;`frontend_auth.authenticate` 接收敏感的 Authorization 载荷并返回
外部 principal。宿主忽略结果中的额外字段,包括附带的 `client_key_id`,只根据当前入口配置完成映射,并继续检查 Key 的启用状态、模型规则、
账号组、并发和预算。该能力只处理数据面身份,不接管管理端登录