Compare commits

..
39 Commits
Author SHA1 Message Date
ZyyandCodex e7f8b5a354 chore: bump version to 3.53.0
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 17:18:26 +08:00
d62868b692 feat(openai): make the WebSocket fast-path budget configurable (#747)
Co-authored-by: Zyy <zyycn@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 17:10:41 +08:00
0922f3486c fix(responses): return HTTP 400 for early WebSocket request errors (#746)
Co-authored-by: Zyy <zyycn@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 16:59:11 +08:00
ZyyandCodex f4058c1d2e test: align backend coverage with current behavior
Remove obsolete field assertions and the ignored Codex binary TLS comparison. Keep coverage for request validation, compatibility, and local TLS handshakes.

Co-authored-by: Codex <noreply@openai.com>
2026-11-19 15:56:12 +08:00
Zyy 8253fbc497 fix(errors): show specific causes in admin feedback and request records 2026-11-19 15:41:32 +08:00
ZyyandCodex 193e83f9f3 fix(accounts): keep stale connection tests from closing a new stream
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 15:06:20 +08:00
ZyyandCodex a9e8fa8a44 refactor(openai): simplify account selection and session admission
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 15:06:20 +08:00
ZyyandCodex 437322ee4b refactor(core): centralize attempt preparation failure handling
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 15:06:19 +08:00
Zyy 843e1367bd docs: streamline guides and clarify current behavior 2026-11-19 14:49:42 +08:00
ZyyandCodex ab1bf4372c fix(api): apply the CLI version gate to Desktop-hosted TUI clients
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 14:15:35 +08:00
dca9806961 feat(usage): filter request errors by origin and focus the detail table (#743)
* feat(usage): filter request errors by origin and focus the detail table

Co-authored-by: Codex <noreply@openai.com>

* fix(usage): preserve request columns and fill the error table

Keep reasoning effort separate and use the success table's column order. Let the error summary fill the space left by hidden columns and reuse the decoded upstream body when filtering saved errors.

Co-authored-by: Codex <noreply@openai.com>

---------

Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Zyy <zyycn@users.noreply.github.com>
2026-11-19 13:40:05 +08:00
ZyyandCodex 15ed54d452 fix(ui): refine subscription badge colors and table spacing
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 13:08:31 +08:00
ZyyandCodex 050214860e docs(readme): streamline setup and highlight project support and activity
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 12:08:36 +08:00
github-actions[bot] d917f948cf chore(release): update release channels to 3.52.2 2026-11-19 01:40:04 +00:00
ZyyandCodex 3d834c9e93 chore: bump version to 3.52.2
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 09:04:14 +08:00
ZyyandCodex 8d282dcdf9 fix(openai): align Responses transport with Codex CLI 0.170.0
Fragment large text messages before permessage-deflate and keep one send acknowledgement per message. Pin the matching WebSocket forks and Linux OpenSSL bindings, and refresh the bundled CLI release.

Co-authored-by: Codex <noreply@openai.com>
2026-11-19 09:03:38 +08:00
github-actions[bot] 38446e8a0c chore(release): update release channels to 3.52.1 2026-11-18 15:25:11 +00:00
ZyyandCodex 1173f6263d chore: bump version to 3.52.1
Co-authored-by: Codex <noreply@openai.com>
2026-11-18 23:02:55 +08:00
ZyyandCodex f4bed2077f fix(accounts): align Codex plan labels and wrap them in tables
Co-authored-by: Codex <noreply@openai.com>
2026-11-18 22:59:20 +08:00
Zyy 4a8b839780 fix(core): release account leases at upstream stream termination (#742) 2026-11-18 22:34:10 +08:00
ZyyandCodex f02bc80f15 fix(openai): keep frame metadata separate from forwarded headers
Co-authored-by: Codex <noreply@openai.com>
2026-11-18 21:21:37 +08:00
ZyyandCodex 32a95a9702 refactor(openai): forward turn state from the current request
Keep the client responsible for echoing turn state across requests. Scope WebSocket opening state to the first request and retain account isolation when moving a request to another account.

Co-authored-by: Codex <noreply@openai.com>
2026-11-18 20:49:26 +08:00
ZyyandCodex cc80401d5e fix(openai): preserve same-turn routing state from Codex turn metadata
Co-authored-by: Codex <noreply@openai.com>
2026-11-18 19:56:08 +08:00
ZyyandCodex 8cc6b50d85 perf(openai): defer account catalog refreshes for one hour on matching ETags
Co-authored-by: Codex <noreply@openai.com>
2026-11-18 19:19:33 +08:00
github-actions[bot] 83521e82f5 chore(release): update release channels to 3.52.0 2026-11-18 04:54:03 +00:00
ZyyandCodex ba8745a714 chore: bump version to 3.52.0
Co-authored-by: Codex <noreply@openai.com>
2026-11-18 12:33:24 +08:00
84bcd0e1c0 feat(usage): filter request records by account name or email (#735)
Co-authored-by: Zyy <zyycn@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-11-18 11:51:02 +08:00
ZyyandCodex 7459c16a3a docs(deploy): specify minimum PostgreSQL version
Co-authored-by: Codex <noreply@openai.com>
2026-11-18 11:41:32 +08:00
ZyyandCodex 3b4fb390c7 fix(ci): allowlist the unpatched picomatch advisory
Co-authored-by: Codex <noreply@openai.com>
2026-11-18 11:03:02 +08:00
ZyyandCodex bb440a3cbb feat(usage): add GPT-6.2 list prices and distinguish Ultrafast requests
Use regular Ultrafast rates for Astra and Sol. Show a double bolt for Ultrafast requests and remove backgrounds from error origin icons.

Co-authored-by: Codex <noreply@openai.com>
2026-11-18 10:55:09 +08:00
github-actions[bot] 89b6d2256f chore(release): update release channels to 3.51.0 2026-11-17 11:01:29 +00:00
ZyyandCodex ba2afe67d0 chore: bump version to 3.51.0
Co-authored-by: Codex <noreply@openai.com>
2026-11-17 18:43:26 +08:00
ZyyandCodex 976359ad26 fix(openai): explain strict session timeouts for ineligible accounts
Report when the bound account cannot use the requested model while a child waits for its parent to switch accounts. Keep the existing queue timeout code and strict affinity behavior.

Refs: #732

Co-authored-by: Codex <noreply@openai.com>
2026-11-17 17:23:16 +08:00
ZyyandCodex 832858dade feat(plugins): expose historical quota observations by window
Let plugins page through retained account observations and find a prior baseline without reading raw provider documents or refreshing upstream. Reuse provider window identities and the existing completion index, preserving resets and gaps.

Co-authored-by: Codex <noreply@openai.com>
2026-11-17 17:06:55 +08:00
ZyyandCodex 4d4c1e48ce feat(plugins)!: expose account binding and selection roles to schedulers
Scheduler v4 reports session ownership separately from native selection preferences and pins. Only eligible candidates are annotated, and cache preferences do not imply a session binding.

BREAKING CHANGE: scheduler plugins must declare capability version 4 and accept the new candidate fields.

Co-authored-by: Codex <noreply@openai.com>
2026-11-17 16:48:06 +08:00
ZyyandCodex 9f873f5ac2 fix(ui): narrow the key usage model filter
Co-authored-by: Codex <noreply@openai.com>
2026-11-17 14:23:32 +08:00
ZyyandCodex 4bc59f32a1 feat(ui): adopt shared action menus and refine quota settings
Pin UI v0.12.0 and use its keyboard-accessible menus for account, API key and proxy actions. Keep quota validation on submit and align a compact inline warmup switch with each bucket title.

Co-authored-by: Codex <noreply@openai.com>
2026-11-17 12:21:15 +08:00
ZyyandCodex 4c5d2bc97e docs: streamline project skills and clarify review and reply guidance
Co-authored-by: Codex <noreply@openai.com>
2026-11-17 12:21:15 +08:00
github-actions[bot] 5033d9f19a chore(release): update release channels to 3.50.0 2026-11-16 11:59:49 +00:00
231 changed files with 4479 additions and 2829 deletions
+13 -15
View File
@@ -1,6 +1,6 @@
---
name: cpr-dev-guide
description: Codex Proxy RS 开发、修复、排障、代码审查和文档修改入口;页面、样式、文案、接口、调度、数据库及宿主 SDK、Runtime、插件接入均适用;PR、Issue、独立网关插件与发版叠加对应技能
description: Codex Proxy RS 的需求评估、排障、开发、代码审查与文档维护入口
---
# 开发指南
@@ -12,39 +12,37 @@ description: Codex Proxy RS 开发、修复、排障、代码审查和文档修
- 先写读者需要知道的事实或动作。删掉一句不影响理解、判断或操作,就删;标题、正文和通知不重复同一信息
- 保留会改变决定的条件、权限、后果和恢复步骤。错误通知只说已知问题,有明确办法才补一句;后端返回的提示在后端改,前端不重复解释。上游原文、用户内容和诊断事实保持原样
## 核实问题根因与宿主职责
评估功能建议、排障、开发和审查时,先按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实使用者要完成什么、当前行为造成了什么影响。反馈直接给出改法时,先弄清提出这个改法的原因
排查故障时,从症状沿实际调用链回溯,定位行为最早偏离预期的环节,用源码、诊断或对照复现说明触发条件如何导致结果。原因尚未确定时,区分已知事实与假设,指出哪项证据能区分可能原因。确认根因后,在负责该行为的模块修复,用原触发场景验证
涉及 Codex 时,以对应版本的官方源码核实客户端行为,默认透明转发,只做必要适配。建议宿主接管已有决定时,指出需要它介入的网关职责或实际约束。若只是个别部署希望采用不同策略,说明不建议内置的原因。实现可行性不能证明宿主应当承担这项需求
## 先确定领域与必读规范
按用户意图、受影响行为与对象初判,定位后按实际文件复核,不要求用户说出“前端”“后端”或技能名。**所有命中行共同构成本次必读规范,先读完再确定方案、修改或给出审查结论**;跨领域叠加,不能只选最像当前步骤的一行
职责边界决定问题由谁修复;即使代码位于账号、调度或 API 模块,只要影响插件接入或为插件增加处理,也命中插件边界。确定方案时说明相关业务事实的归属及已有实现的复用依据,不能以功能恢复或测试通过替代职责判断
按受影响行为和实际文件执行下表所有命中项。流程引用首次完整读取,长文档按标题定位指定章节
| 领域或操作,行为影响与文件路径满足其一即可 | 确定方案前读取与执行 |
| --- | --- |
| 调整页面、弹窗、表单、按钮、文案、样式或交互;目标在 `frontend/`、`modules/ui/`、插件前端,或是 `.vue` 文件 | [前端流程](references/frontend.md),局部修改同样按影响范围检查组件复用、文案、Token、样式、视觉状态和运行证据 |
| 开发、排查或审查插件接入、宿主 SDK、Runtime、扩展接口或独立网关插件;目标在 `backend/crates/gateway-plugin/`、`modules/plugins/` | 完整读取[插件职责边界](references/plugin-boundaries.md)及所用 [SDK](../../../backend/crates/gateway-plugin/sdk/README.md) 类型与能力合同;宿主维护自身合同、资源与稳定性,插件业务错误在插件侧修复,不在宿主、SDK 或 Runtime 中补偿;独立插件开发、排查、审查另用 [cpr-plugin-dev](../cpr-plugin-dev/SKILL.md) |
| 插件接入、SDK、Runtime、扩展接口或独立网关插件,含账号、调度或 API 中为插件新增的处理;目标在 `backend/crates/gateway-plugin/`、`modules/plugins/` | [插件职责边界](references/plugin-boundaries.md)及所用 [SDK](../../../backend/crates/gateway-plugin/sdk/README.md) 类型与能力合同;独立插件开发、排查或审查同时执行 [cpr-plugin-dev](../cpr-plugin-dev/SKILL.md) |
| 开发、排查或审查服务端接口、路由、调度、账号与用量规则、持久化、后台任务或协议行为;目标是 `backend/` 中的实现、配置、迁移,或 Rust 源码 | [Workspace 边界](../../../docs/architecture.md#3-workspace-边界)的模块与依赖规则、所属模块及[后端自审](../../../docs/architecture.md#后端自审);Rust 使用 `$rust-best-practices` 和下方后端注释要求,宿主 Rust 同时读取 [Rust 模块组织约定](../../../docs/architecture.md#32-rust-模块组织约定) |
| 修改页面接口调用,或开发、排查、审查面向管理端或模型客户端的 HTTP/WS API 合同 | [API](../../../docs/api.md)对应章节;优先复用已有接口,核对调用方 → 服务端解析 → 实际查询或执行,不能只凭前端类型认定参数生效;按实际改动叠加前后端规范 |
| 新增、修改或审查客户端可见错误、失败提示、后台任务状态文案 | 下方[错误文案](#错误文案),并按实际出口核对[错误与诊断三层边界](../../../docs/architecture.md#错误与诊断三层边界) |
| 模块或调用链变更 | [Workspace 边界](../../../docs/architecture.md#3-workspace-边界)及所属模块章节,不通读整份架构 |
| 新增、调整、清理或审查测试 | 下方[测试维护](#测试维护),按当前行为、职责归属与已有覆盖判断保留、合并或删除 |
| 修改部署行为、`deploy/` 配置或数据库迁移 | 按范围读取[部署](../../../deploy/README.md)、[迁移](../../../backend/migrations/README.md)对应章节 |
| 修改或审查文档;实现或审查用法、公开合同、职责、约束或运维操作的变化 | [文档检查](references/documentation.md)及相关章节,尚无文档差异时也检查是否漏更;纯文档任务不默认读取代码开发、页面验收或发布流程 |
| 修改或审查文档;实现或审查用法、公开合同、职责、约束或运维操作的变化 | [文档检查](references/documentation.md),按最终行为核对是否漏更;纯文档任务只补读核实所述事实需要的领域条款 |
| 代码审查,包括 PR 审查 | [审查标准](../../../CONTRIBUTING.md#审查标准),叠加被审查行为所属领域的规范;审查默认只读 |
| PR / Issue / 发版 | 按当前意图选 [PR](../cpr-github-pr/SKILL.md)、[Issue](../cpr-github-issue/SKILL.md)或[发版](../cpr-release/SKILL.md),普通提交不创建 PR |
纯文档任务按文档分支执行;核实文中的合同与职责时读对应领域条款,不因提及代码路径或语言加载实现、构建与页面验收流程
首次命中的流程引用完整读取,并落实其中指定的必读章节;长文档先用 `rg -n '^#{1,4} ' 文件` 定位,分段读取指定章节,避免输出截断。`#章节` 不会自动截取,“按需”仅用于未命中的领域和后续操作资料,不能省略必读规范;读取记录与验证证据的复用按 [任务延续与收尾](../../../AGENTS.md#任务延续与收尾) 执行
## 参考仓库的优先级
开发、排障和代码审查先按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实问题与方案。涉及 Codex 行为时执行其中的官方行为优先约束:对应版本的官方源码优先,以透明转发和最小必要适配为默认方案,先判断偏离是否必要再评价实现
## 执行与收尾
1. 遵守已提供的 [AGENTS.md](../../../AGENTS.md),按其 CodeGraph 约定定位代码;确认工作区、任务范围与已有改动,找到事实归属、同类实现和调用链,补齐上表命中规范及[项目约定](../../../CONTRIBUTING.md#项目约定)对应条目后再修改
2. 以最终差异重新匹配上表,补齐新增领域的规范并检查实际实现,再处理本次引入的职责越界、重复规则、冗余状态与无依据分支;删除或替换功能时一并清理失效的配置、类型、调用、测试与文档,已部署数据和公开合同仍遵守所属迁移及兼容规则;仅审查时报告,不自行修复
3. 按最终行为执行[文档检查](references/documentation.md),核对所属正文及相关概述、示例和引用,在本任务内完成必要同步;不以尚无文档差异跳过检查。内部重构等未改变文档所述事实时无需改文档;常规文档只写当前状态,普通开发不自动修改 `release/notes.md`
3. 在本任务内同步受影响的文档、示例和引用
4. 按变更范围执行[验证](../../../CONTRIBUTING.md#验证)及其停止条件,后端命令见[验证命令](../../../docs/architecture.md#验证命令);复用仍适用的验证证据与用户已确定的验收分工,区分通过、失败、跳过与未执行
5. 交付前按[首要写作要求](#首要写作要求言简意赅)通读本次新增或修改的文字。交代实际结果与验证缺口;前端按[前端流程](references/frontend.md)核对运行证据,后端按上表检查生命周期,不把构建通过当作行为验收
6. 按授权完成提交与交付;提交前按[提交约定](../../../CONTRIBUTING.md#项目约定)准备提交信息与实际共同作者署名,提交后核对实际提交消息,PR 的 AI 披露不能替代提交署名
@@ -7,32 +7,11 @@
- 以当前目标分支及任务内工作区的实现、配置和有效运行证据核实行为;提交记录用于发现待核实的主题,不能直接当作现行事实或按提交顺序组织正文。按 [CodeGraph 约定](../../../../AGENTS.md#codegraph)同步索引后定位,证据不足时报告缺口,不把计划或推测写成已支持能力
- 开发任务按最终行为检查哪些用法、合同、职责、约束或运维操作需要同步,即使尚无 Markdown 差异也要检查;独立文档更新按用户范围核对现行说明,不等到发版时再补普通开发所需的文档
- 沿同一事实查找所属正文及相关概述、示例和引用,重点核对“支持/不支持”等能力声明、默认值、配置模板和命令。概述保留必要摘要并链接详细合同;不能只更新详细章节,留下 README 或示例中的矛盾说明,也不扩展为无关全仓改写
## 写之前
先确定读者、必须说明的当前事实与所属章节,再决定是否需要修改及详略;文档职责与更新条件按上节核对。涉及合同或职责说明时,补读所属架构、API 或 SDK 的对应条款,核实事实;不因文档提及实现而执行无关的开发与构建流程
在所属章节就地替换失效说明,先组织读者现在需要的操作、结果和限制,不从变更摘要改写正文。仅介绍被替代实现、修复动机或修改经过的段落直接删除;删掉“新增”“此前”“不再”等词后仍在回答变更经过的内容,也不保留
## 逐段验收
检查工作区和暂存区中本任务的最终文档差异,并连同受影响章节及相关概述、示例通读,按内容用途处理,不只搜索关键词:
| 段落回答的问题 | 处理 |
| --- | --- |
| 现在如何使用、配置或理解结果 | 保留当前事实与必要边界,放回所属章节 |
| 谁负责状态、事务、资源和失败处理 | 放入所属架构章节,避免在 API 或部署文档复述实现 |
| 这次做了什么、以前怎样、为什么这样修、跑过哪些测试 | 移入 PR、Issue 或任务报告,不以换成现在时的方式留在常规文档 |
| 特定配置或数据状态下如何升级、恢复 | 写明适用条件、操作及限制,删除演变过程 |
| 别处已完整说明的事实 | 合并或改为必要摘要与链接 |
脱离提交日期、Issue 和本次任务背景后,读者仍应能独立理解正文
业务中的请求历史、审计记录、旧数据兼容与回滚操作是当前功能,不能因含“历史”“旧”等词而删除
- 涉及合同或职责时核对所属架构、API 或 SDK 条款,在所属章节就地修订。审计记录、旧数据兼容和回滚仍是现行能力时,保留读者需要的说明
## 交付检查
- 完成上述逐段验收及[行文检查](../../../../CONTRIBUTING.md#层次与行文),发现问题先处理,未完成内容审查不能称文档已检查
- 通读工作区与暂存区中本任务的最终差异、受影响章节及相关概述和示例,按[层次与行文](../../../../CONTRIBUTING.md#层次与行文)逐段验收
- 检查相对链接、章节锚点、表格与命令示例,`git diff --check` 或构建通过不能代替内容审查
- 交付时简述已同步的文档范围;涉及更新条件却未改文档时,说明现有内容为何仍准确或还有什么缺口。仅报告实际核对范围,不把链接检查通过称为事实核实,也不把检查记录写进常规文档
@@ -32,7 +32,8 @@
对照最终差异和实际页面核对适用项,不以读取过规范代替检查:
- **复用与范围**:是否沿用参考页面和基础组件,已有组件能承载时不手写替代控件;共用缺陷按职责修复,修复后清理本次已失效的页面补丁,不顺带重排无关区域或新增重复入口
- **文案与层级**:标点是否合规,标题、状态和帮助是否重复,详细说明与当前决策必需提示的位置是否合适
- **核对位置与对齐**时,结合周围内容查看实际页面或 PR 截图,确认操作归属一眼可辨,对照相邻行列检查边缘、文字基线和组间留白。发现错位时指出具体控件、对齐参照和受影响的状态
- **精简文案**,删去重复说明,压短必要提示,检查自写文案中的句号和分号
- **样式与状态**:是否使用对应 Token 与 utility,局部样式是否符合适用边界,受影响的主题、窄屏及交互状态是否正确
- **查询与动作**:区分首次加载、刷新、分页、单行与批量操作,核对 loading、禁用状态的影响范围;沿用请求层错误处理,不在页面叠加同一错误的提示
- **运行证据**:按界面验证核对截图与实际交互,证据对应当前实现;页面 PR 的可访问图片和 Draft 条件按该节执行
+8 -18
View File
@@ -11,20 +11,18 @@ description: 草拟、创建、补充或回复 GitHub Issue,包括缺陷、功
草拟只准备正文,明确创建或提交才发布;已有授权直接执行,自动命中技能本身不授权远程写入
补充已有 Issue 先读原帖和讨论,按授权更新或追加,不重复新建;无法推断的目标或关键事实才向用户补齐
补充已有 Issue 按授权更新原帖或追加评论
## 按动作读取与核实
目标、授权、事实与脱敏要求适用于草拟、提交和回复;按下列动作读取必需规则与证据,再组织正文。症状反馈可保留未知根因,进入技术排查或方案判断时补齐对应规范
- 新建 Issue 时,读取本仓库的[提交 Issue](../../../CONTRIBUTING.md#提交-issue)及本次匹配的一张表单:[接口问题](../../../.github/ISSUE_TEMPLATE/api-bug-report.yml)、[常规问题](../../../.github/ISSUE_TEMPLATE/general-bug-report.yml)或[功能建议](../../../.github/ISSUE_TEMPLATE/feature-request.yml);协作规则提案可用普通 Issue
- 回复时读取原帖、相关讨论与支撑答复的证据,按下方回复口吻组织内容,不套用新建 Issue 的表单
- 补充或回复时先读原帖和讨论,按 [GitHub 回复口吻](../../../CONTRIBUTING.md#github-回复口吻)决定答复内容和是否追问
- 其他仓库读取它自己的相关规则与实际模板,长文档先定位标题再截取,不预读全部模板或 CONTRIBUTING
- 搜索同场景 open/closed Issues、相关 PR 和发布记录,区分主分支修复与已发布修复,不凭标题判断重复;没有新证据时返回已有链接,用户仍要求新建则按其要求处理
- 新建或判断重复时查找同场景的 open/closed Issues 和相关 PR,按实际场景核对。已有相同反馈且无新证据时返回原链接,用户仍要求新建则按其要求处理。答复修复状态时核对发布记录,区分已合入和已发布
- 需要技术排查、判断实现方案或修改时执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的领域必读,不能仅凭症状建议跨职责补偿;提交症状反馈不以找到根因为前提
- 引用上游行为或提出方案时执行[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据),注明适用版本、来源与缺口
## 正文与证据
## 新建 Issue 的正文
标题说明症状或期望行为,区分发生问题的部署版本、实测结果、预期结果与根因假设
@@ -34,22 +32,14 @@ YAML 表单按 `attributes.label` 和字段顺序组织正文,手工核对必
未知信息如实标明,影响理解或复现的关键事实先补齐,不提交原始 YAML、占位答案或未确认的勾选项
日志和附件仅含定位所需的脱敏片段,不公开凭据、完整配置或请求转储,不擅自修改代理、TUN、证书环境取证
附件须获授权且可访问,本机路径不算附件;labels 和 assignees 仅按模板或用户要求设置,并确认实际存在
labels 和 assignees 仅按模板或用户要求设置,并确认实际存在
Issue 可记录复现、排查和变更经过;涉及常规文档修改时执行[文档检查](../cpr-dev-guide/references/documentation.md)
## 回复口吻
草拟、发布或修改 Issue 回复时,按 [GitHub 回复口吻](../../../CONTRIBUTING.md#github-回复口吻)将核实结果写成面向提问者的交流答复,具体口吻规则集中维护在该节
按平常回帖的口吻写,语气自然、委婉,说清判断和原因,少用铺垫、转折和自我说明;暂不采纳或提出不同意见时说明具体原因
发送或更新前从提问者视角通读:判断和原因是否清楚,建议是否便于尝试,补充材料的用途是否明确。删去不影响理解的客套、重复解释和过程说明;发现生硬时调整整句,不能仅加缓和词,保留已核实的结论
## 发布与收尾
日志和附件只含定位所需的脱敏片段,不公开凭据、完整配置或请求转储,不擅自修改代理、TUN、证书环境取证。附件须获授权且可访问,本机路径不算附件
使用可用连接器或 `gh`,不为提交反馈安装工具、修改仓库配置或启用服务
多行正文通过结构化字段或 UTF-8 文件传递,以下变量须先从已确认的目标与正文赋值:
@@ -58,6 +48,6 @@ Issue 可记录复现、排查和变更经过;涉及常规文档修改时执
gh issue create --repo "$issue_repo" --title "$issue_title" --body-file "$issue_body_file"
```
发布前核对目标、必填内容、脱敏与重复记录,更新时保留无关原文;不擅自评论、重开或关闭重复 Issue
发布前核对目标和脱敏内容,新建时确认必填项,更新时保留无关原文;不擅自评论、重开或关闭重复 Issue
超时或结果不明确时先查询远端再重试,发布后回读确认并返回链接;仅草拟或发布失败时提供正文并注明未提交
@@ -1,6 +1,6 @@
interface:
display_name: "cpr-github-issue"
short_description: "整理、提交或补充 Issue,核对复现、重复反馈与发布范围"
default_prompt: "使用 $cpr-github-issue 按当前请求整理、提交或补充 Issue,核对目标、复现证据、重复记录和脱敏,不将草拟自动变成发布。"
short_description: "草拟、提交或回复 GitHub Issue,处理缺陷反馈和功能建议"
default_prompt: "使用 $cpr-github-issue 按当前请求整理反馈或回复已有 Issue"
policy:
allow_implicit_invocation: true
+3 -10
View File
@@ -17,8 +17,6 @@ description: 准备、创建、更新或审查 GitHub PR,含回复讨论与处
为本仓库拟写或更新 PR 标题时,完整标题使用英文,沿用提交信息的 Conventional Commits 格式,例如 `fix(store): preserve client key ledgers after deletion`
涉及上游行为的判断按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)执行
## 按模式读取
先完成上述范围判断,再按当前动作与差异涉及的领域叠加下表。命中的流程引用完整读取,长文档读取指定章节;只复用已实际读取且仍适用的内容,单纯整理正文或回复不扩展为完整实现审查
@@ -28,22 +26,17 @@ description: 准备、创建、更新或审查 GitHub PR,含回复讨论与处
| 只整理标题或描述 | 当前 PR、最终 diff、实际模板、[AI 披露](../../../CONTRIBUTING.md#ai-使用披露),在授权范围内改文案,不自行修改实现;不读取推送或审查流程 |
| 创建或更新 PR | [创建流程](references/create.md)、[PR 流程](../../../CONTRIBUTING.md#pr-流程)与[规则文件保护](../../../CONTRIBUTING.md#规则文件保护) |
| 审查 PR | [审查流程](references/review.md)、[审查标准](../../../CONTRIBUTING.md#审查标准) |
| 回复讨论或审查意见 | 目标评论、相关上下文与实际处理结果,按下方回复口吻答复;仅回复不加载创建或完整审查流程 |
| 回复讨论或审查意见 | 读取目标评论和相关上下文,按[GitHub 回复口吻](../../../CONTRIBUTING.md#github-回复口吻)答复实际处理结果 |
| 实现自审、审查或修改代码与文档 | 执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的领域必读与对应检查,包括后端、插件、测试和 API 等命中项;只读审查同样执行,不能仅核对 PR 正文与 CI |
| 含前端改动 | [前端流程](../cpr-dev-guide/references/frontend.md),核对适用规范与当前实现的运行证据 |
| 含文档改动 | [文档检查](../cpr-dev-guide/references/documentation.md) |
## 回复口吻
草拟和发布 PR 讨论、审查意见的回复时,执行 [GitHub 回复口吻](../../../CONTRIBUTING.md#github-回复口吻)
## 创建与审查的公共核对
- 按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实触发条件、发生版本与目标分支现状,分别判断问题是否成立、是否属于目标项目职责及方案是否必要
- 核对最新目标分支及同场景 open/closed PR、Issue,按实际行为和测试判断重复,不凭标题下结论,也不擅自关闭他人 PR
- 自审或审查覆盖完整差异与调用链,前端与文档按模式表检查
- 核对[AI 使用披露](../../../CONTRIBUTING.md#ai-使用披露),填写实际工具与模型,不猜型号;必需截图或型号待补时保留 Draft
- 验证结果对应实际 head,区分通过、失败、跳过与未执行;无文档改动时只核对现有说明是否失真
- 自审或审查覆盖完整差异和调用链,按[验证](../../../CONTRIBUTING.md#验证)执行适用检查,确认结果对应当前 head
- 核对[界面验证](../../../CONTRIBUTING.md#界面验证)要求的截图和 [AI 使用披露](../../../CONTRIBUTING.md#ai-使用披露),必需材料待补时保留 Draft
远程操作优先使用可用连接器,`gh` 显式指定 `--repo`,多行正文使用结构化字段或 `--body-file`
@@ -1,6 +1,6 @@
interface:
display_name: "cpr-github-pr"
short_description: "提交、更新与审查 PR,核对问题、自审、页面截图和 AI 模型披露"
default_prompt: "使用 $cpr-github-pr 按当前请求准备、提交、更新或审查 PR,实现自审与审查叠加开发指南的领域规范,核实问题、方案、验证、页面截图和 AI 模型披露。"
short_description: "准备、更新或审查 GitHub PR,回复讨论和审查意见"
default_prompt: "使用 $cpr-github-pr 按当前请求准备、更新、审查 PR 或回复讨论"
policy:
allow_implicit_invocation: true
@@ -6,16 +6,12 @@
不用提交日志拼接正文,也不假定仓库一定有模板。
2. 更新并确认 base/head,查看相对 merge-base 的完整差异和待提交内容;核对仓库的受保护文件与准入规则。
只纳入任务范围的文件和提交;需要整理时用独立功能分支,保留用户其他改动,不擅自改写已发布历史。
3. 已完成的改动也须按入口公共核对复核问题与方案。原问题不成立时不包装成已修复的缺陷,证据不足时保留结论。
实现与自审按 [cpr-dev-guide](../../cpr-dev-guide/SKILL.md)执行,包括适用的后端生命周期和前端检查;需要修正时只修改已授权范围。
4. 查找同一来源仓库、head 和 base 的现有 PR;已存在则复用其链接,不重复创建。
3. 查找同一来源仓库、head 和 base 的现有 PR;已存在则复用其链接,不重复创建。
更新现有标题或正文须在本次整理/更新请求范围内。
5. 按[验证](../../../../CONTRIBUTING.md#验证)执行适用检查,记录对应提交或工作区状态;文档、页面证据与模型披露按入口核对。
6. 将任务范围内的提交推送到正确远端,核对远端 head。标题遵循项目约定,正文先说明问题成立的依据和最终行为,
再给必要的设计取舍、自审结论、验证与遗留事项,按模板附页面截图和 AI 使用情况。涉及上游行为时,按[问题与方案依据](../../../../CONTRIBUTING.md#问题与方案依据)写明官方源码位置、版本、处理方式及本次方案关系。按规模压缩,不强填无关章节。
7. 明确要求草稿或仍有阻塞项时创建或保持 Draft PR,并解释原因;必需截图或 AI 模型披露待补时也不标为可审阅。具备审查条件且未要求草稿时创建普通 PR。
4. 将任务范围内的提交推送到正确远端,核对远端 head。按实际模板写明问题依据、最终行为、自审与验证结果,附上适用的审阅材料
5. 明确要求草稿或仍有阻塞项时创建或保持 Draft PR,并说明原因;具备审查条件且未要求草稿时创建普通 PR。
GitHub Draft 状态与“只写本地草稿正文”不同,后者不创建远程对象。
8. 创建或更新后回读正文与附件,核对链接、base、head、草稿状态、模型披露和最新检查结果。网络超时或结果不确定时先查询远端,再决定是否重试。
6. 创建或更新后回读正文与附件,核对链接、base、head、草稿状态、模型披露和最新检查结果。网络超时或结果不确定时先查询远端,再决定是否重试。
CLI 示例中的变量必须先根据上述检查赋值;`pr_body_file` 是精确写入 UTF-8 正文的临时文件:
@@ -4,20 +4,10 @@
1. 获取 PR 的 base/head SHA、描述、文件差异、已有讨论及 CI 状态。记录实际审查的 head,使用 merge-base 差异。
需要源码上下文时先遵守目标仓库的定位规则;需检出时使用隔离工作区,保留用户当前分支和运行环境。
按实际行为与文件执行 [cpr-dev-guide](../../cpr-dev-guide/SKILL.md)的领域必读,再判断方案与实现;只读审查也核对职责边界与生命周期。
2. 按入口公共核对在目标分支基线核实问题,区分原有问题、环境或配置差异与 PR 新引入的问题,说明主分支已覆盖的部分。
3. 按[问题与方案依据](../../../../CONTRIBUTING.md#问题与方案依据)评估解决方向,涉及上游时说明官方处理方式及本次方案关系;缺少必要性依据的偏离明确指出,不因测试通过就认定方案合理。
4. 按[审查标准](../../../../CONTRIBUTING.md#审查标准)追踪完整调用链,找到共享业务事实、同类实现及已有验证。
对既有特殊分支查清服务的场景,再判断本次改动是否引入或加重问题。
主动检查本次变更新引入或加重的冗余与代码异味,说明具体位置、维护成本或行为影响及最小修复方向;
不能仅因功能可用、CI 通过而略过,也不把个人写法偏好判为缺陷。
5. 前端改动执行[前端流程](../../cpr-dev-guide/references/frontend.md),浏览器可用时检查相关交互;缺少必需截图时要求补齐并列为未具备审阅条件。
6. 核对 CI 与本地证据是否覆盖当前 head;根据风险补充必要验证,不触发无关部署或真实账号业务请求。
文档差异按[文档检查](../../cpr-dev-guide/references/documentation.md)核对最终 diff。
核对 AI 使用与模型披露,缺项明确指出。工具不可用、集成测试跳过或环境不足时具体说明影响范围。
7. 按审查标准用中文输出问题是否成立、方案是否合理及对应依据,再列实现问题与验证缺口;复用建议指出具体已有实现。
没有问题的类别可省略,未发现问题时直接说明并交代覆盖范围。
8. 结束前核对 head 是否变化。发生变化时检查新增差异并更新结论,或明确结论只适用于原 SHA。
2. 对照目标分支区分原有问题、环境差异和本次引入或加重的问题。修改既有特殊分支时,查清它原先服务的场景
3. 根据风险补充必要验证。浏览器可用时实测受影响的交互,避免触发无关部署或真实账号业务请求
4. 用中文说明问题是否成立、方案是否合理,再报告可定位的实现问题与验证缺口。建议复用时指出已有实现;未发现问题时交代实际覆盖范围
5. 结束前复核 head。发生变化时检查新增差异并更新结论,或明确结论只适用于原 SHA
审查本身不修改源码、不发表评论、不提交 GitHub 的批准或请求修改状态。
用户明确要求发布时,先复核当前 head 和重复评论,再通过结构化字段或 `--body-file` 发布对应内容;
+2 -6
View File
@@ -1,17 +1,13 @@
---
name: cpr-plugin-dev
description: 开发、修复、排查、审查或打包 Codex Proxy RS 独立网关插件,含处理器、清单与插件页面;仅改宿主能力时使用 cpr-dev-guide 的插件边界,不适用于 Codex 插件或 Vue 插件
description: Codex Proxy RS 独立网关插件的开发、排障、审查与打包
---
# 网关插件开发
## 先读职责边界
插件在独立项目中通过公开 SDK 实现业务,插件业务错误在插件侧修复;宿主维护自身合同、资源与稳定性,不猜测插件意图、不补造业务数据,不在宿主、SDK 或 Runtime 中增加插件专属补偿
开发、排查和审查先完整读取[插件职责边界](../cpr-dev-guide/references/plugin-boundaries.md),再选择实现步骤;已有处理器修复和页面改动也执行,不以是否新增能力为条件。需要新增宿主能力时,先界定可独立使用的基础接口及其职责;必要的协议保护与资源回收仍由宿主负责
同时执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的领域必读与收尾要求;已实际读取且仍适用的内容复用,不递归重读入口。仅构建、打包或分发已有插件时按对应操作读取,若需诊断或修改行为,再补齐开发分支
开发、排查或审查独立插件时,执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md) 并先读[插件职责边界](../cpr-dev-guide/references/plugin-boundaries.md),包括修改已有处理器或页面。仅构建、打包或分发已有插件时,按下表读取对应步骤
## 范围与合同
@@ -61,6 +61,6 @@ release/publish "$release_version"
工作流附加的安装说明和自动提交列表按其当前配置处理,不用它们替代手写的中文变更说明。
- 回读 `main:release/version.yaml` 的 `published`。正式版参与同一大版本四个普通通道的比较;RC 参与 RC、Beta、Alpha,Beta 参与 Beta、Alpha,Alpha 只参与自身。实验版只推进 `exp["X.Y.Z"]`。有通道推进时应有 `chore(release): update release channels to <version>` 提交;重复执行或较旧版本未推进任何通道时无提交
- 通道表写入失败时,确认该版本已公开、工作流能写入 `main`,再按已有授权执行 `gh workflow run release.yml --ref main -f tag="v$release_version" -f index_only=true`。恢复任务重新校验公开附件、读取并合并当前清单,不重新打包或改 tag
- v3.42.0 在线升级:首个包含新更新器的 3.x 正式版公开并通过校验后,从该次通道提交取出 `release/version.yaml`,将顶层 `version` 设为该正式版,作为同名附件上传到该 Release。回读附件,确认 3.x 稳定通道指向该版本且安装包可用,再手动将已有 `update-index` 正文改为 `{"current":"<该正式版>"}`。此后保留该页与附件,无需再编辑
- 保留 v3.42.0 在线升级使用的 `update-index` 页面和 v3.42.1 的 `version.yaml` 附件
- 返回版本、tag 对应提交、Release/工作流链接及实际结果。失败、仍在构建或缺失产物时明确说明,不能称为发布成功;
Release 和镜像已生成也不表示用户的运行实例已经升级。
+1 -1
View File
@@ -4,7 +4,7 @@
| 任务意图与常见说法 | 必用技能 |
| --- | --- |
| 开发、修复、排障、代码审查、改文档;包括“改弹窗/样式/文案”“修接口/调度/数据库”等省略请求 | [cpr-dev-guide](.agents/skills/cpr-dev-guide/SKILL.md),按实际操作和文件匹配规范,跨前后端同时执行 |
| 需求评估、排障、开发、修复、代码审查、改文档,包括“看下这个 Issue”“改弹窗/样式/文案”“修接口/调度/数据库” | [cpr-dev-guide](.agents/skills/cpr-dev-guide/SKILL.md),按实际操作和文件匹配规范,跨前后端同时执行 |
| 提交/提个 PR、准备或更新 PR、看下 PR、回复 PR 讨论、处理 PR 审查意见 | [cpr-github-pr](.agents/skills/cpr-github-pr/SKILL.md);实现自审、审查或修改同时执行 cpr-dev-guide |
| 提 Issue、反馈到仓库、把问题或建议整理成 Issue、补充或回复 Issue | [cpr-github-issue](.agents/skills/cpr-github-issue/SKILL.md) |
| 写、修或审查独立网关插件,排查插件接入、打包插件 | [cpr-plugin-dev](.agents/skills/cpr-plugin-dev/SKILL.md),同时执行 cpr-dev-guide;仅改宿主能力时由 cpr-dev-guide 加载插件边界 |
+4 -10
View File
@@ -21,17 +21,11 @@
### GitHub 回复口吻
AI 草拟、发布或修改 Issue、PR 讨论及审查意见的回复时,以一起排查问题、讨论方案的口吻交流:
Issue 和 PR 回帖直接回应对方遇到的问题,有不同意见时结合具体场景说明理由。语气自然、委婉,用短句,少用句号。说明个人判断或行动时用“我”,确需提问时称呼一次“佬”
- 围绕问题、事实和结论展开,能自然省略主语时省略;需要说明个人判断或行动归属时用“我”,避免反复以“我”起句或强调自己,不用“我们”“本助手”代称自己
- 普通回复直接回应问题,不加问候语或称呼;向对方提问时称呼“佬”,同一条回复不重复称呼
- 先接住对方想完成的事和遇到的困难,再给出核实结果与建议;回复让对方感到问题被理解、有下一步可做,避免一上来归类、纠正或划定责任
- 给出操作建议时说明它能帮助判断什么,措辞自然、委婉,不靠堆叠缓和词修饰命令
- 回应已有能力、暂不支持或未采纳的建议时,结合场景说明可用入口或具体原因,有可行替代办法时一并说明,再交代必要边界;避免只回复“已有功能”“重复问题”“不在范围内”等结论
- 需要补充材料或配合操作时,先利用已有信息,只询问仍缺少的部分,说明用途和最小范围;例如“佬,方便再观察几次吗?如果还出现,可以附一下对应请求的诊断包,便于对照终态用量”
- 澄清误解或提出不同意见时,从观察和依据说起,照顾对方的使用环境与理解路径,避免责备、反问或居高临下的判断;已确认的事实保持明确,尚未确认的原因保留余地
- 使用自然短句,简单回复用短段,并列信息较多时再分点;少用句号,避免客服套话、机械模板和空泛保证
- 排查、复现、修改和验证的完成状态与实际一致;未采纳的意见说明依据,未确认、待处理或未验证的内容如实交代,说清结论、限制和下一步
- 用法问题给出操作入口,功能取舍或关闭 Issue 说明与该场景相关的原因,有可行替代办法时再提。问题已答清即可结束
- 排障先看原帖、已有材料和自己能核实的实现或发布记录。回复只附有助于理解结论或采取行动的排查信息,如相关版本、复现结果或脱敏片段。区分推测和实测
- 只有缺失信息会改变判断或处理方式,且只能由对方提供时才追问。说清需要哪一项、用来区分什么情况
## 问题与方案依据
+28 -83
View File
@@ -12,7 +12,7 @@
[![GHCR](https://img.shields.io/badge/GHCR-codex--proxy--rs-2496ED?logo=docker&logoColor=white&style=flat-square)](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
[快速预览](#快速预览) · [快速开始](#快速开始) · [客户端接入](#客户端接入) · [文档](#文档) · [社区](#社区) · [许可证](#许可证)
[快速预览](#快速预览) · [快速开始](#快速开始) · [文档](#文档) · [社区](#社区) · [贡献者](#贡献者) · [Star History](#star-history) · [支持项目](#支持项目) · [许可证](#许可证)
</div>
@@ -21,105 +21,28 @@
## 快速预览
无需部署即可体验管理端的系统概览、账号分组、代理管理与用量统计:
| 登录信息 | 默认值 |
| --- | --- |
| 地址 | <https://codex-proxy-rs.ainz.cc> |
| 登录身份 | 管理员 |
| 账号 | `admin@cpr.local` |
| 密码 | `039c18de2aeac46d23ead7766bb07bbbe3747233c66a128e` |
预览服务运行已发布版本,展示的账号、代理与使用记录均为模拟数据,每天北京时间 `00:00` 自动生成当天数据
这是公开共享的功能预览环境,不提供真实模型调用;请勿导入真实账号、密钥或其他敏感信息
## 快速开始
使用 Docker Compose 部署版本固定的发布镜像,同时启动 PostgreSQL 和 Redis
以下命令适用于 Linux amd64/arm64,需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL
macOS 从[发行页](https://github.com/zyycn/codex-proxy-rs/releases)下载对应的归档:Intel 机型选 `darwin_amd64`,Apple Silicon 机型选 `darwin_arm64`。
Windows x64 / ARM64 的安装步骤见 [Windows 二进制部署](deploy/README.md#windows-二进制部署)
已有部署请先看 [升级说明](deploy/README.md#镜像升级与源码构建),不要覆盖原配置
### 一键安装
请确保当前用户能访问 Docker,并可通过 `sudo` 或 root 设置目录权限
在已安装 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL 的 Linux amd64/arm64 主机上运行
```bash
curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/install.sh -o install.sh && bash install.sh
```
[安装脚本](deploy/install.sh) 默认安装到当前目录下的 `codex-proxy-rs/`,下载同一正式 Release 的部署文件,
自动生成密码、设置目录权限并启动服务
完成后保存显示的访问地址和管理员密码,再[登录管理端](#登录管理端)并[添加账号与客户端密钥](#添加账号与客户端密钥)
可在执行 `bash install.sh` 时传入环境变量:
| 变量 | 用途 | 默认值 |
| --- | --- | --- |
| `INSTALL_DIR` | 安装目录,建议使用绝对路径 | 当前目录下的 `codex-proxy-rs/` |
| `CPR_RELEASE_TAG` | 指定发布标签 | 最新正式版本 |
| `ADMIN_PASSWORD` | 管理员初始密码,至少 12 位,不能包含 `$`,不能使用常见弱口令 | 随机生成 |
例如,自定义安装目录:
```bash
INSTALL_DIR="$HOME/services/codex-proxy-rs" bash install.sh
```
重复运行时请使用同一安装目录,检测到 `deploy/config.yaml` 后,脚本保留现有配置和部署文件,
忽略传入的管理员密码,也不执行版本升级
### 手动安装
自行下载部署文件、配置密码和启动服务的完整步骤见 [部署文档](deploy/README.md#手动安装)
### 登录管理端
部署完成后,打开 `http://127.0.0.1:8080`,使用 `admin@cpr.local` 和管理员密码登录
API Key 持有者可在登录页切换身份,查看自己的用量与额度,并通过「密钥配置」复制 Codex 配置或导入 CC Switch
默认地址只能在服务器本机访问,从其他设备使用时,需要配置
[HTTPS 反向代理](deploy/README.md#公网访问)
### 添加账号与客户端密钥
1. 在「账号」中添加账号,完成授权或导入
2. 按需建立账号分组,再创建客户端密钥并选择可用分组,**不选分组表示可使用全部账号**
3. [连接客户端](#客户端接入)
## 客户端接入
**Codex CLI / 桌面端**:在「使用密钥」中按操作系统复制配置,合并配置后重启 Codex;也可通过「导入到」把服务连接与密钥添加到 CC Switch
完整步骤、生图配置与排障见[客户端配置](deploy/README.md#客户端配置)
**其他 API 客户端**:API Key 填写管理端创建的客户端密钥。按客户端自动追加的请求路径填写 Base URL;远程接入时将本机地址换成服务器的 HTTPS 地址
| 客户端自动追加的路径 | Base URL(本机部署) |
| --- | --- |
| OpenAI Responses:`/responses`;Chat Completions:`/chat/completions` | `http://127.0.0.1:8080/v1` |
| Anthropic Messages:`/v1/messages` | `http://127.0.0.1:8080` |
查询该密钥可见的模型目录:
```bash
curl http://127.0.0.1:8080/v1/models \
-H 'Authorization: Bearer <client-api-key>'
```
[安装脚本选项](deploy/README.md#安装脚本选项) · [macOS 发行包](https://github.com/zyycn/codex-proxy-rs/releases) · [Windows 安装](deploy/README.md#windows-二进制部署) · [已有部署升级](deploy/README.md#镜像升级与源码构建)
## 文档
| 任务 | 文档 |
| 主题 | 文档 |
| --- | --- |
| 部署与使用 | [部署、备份与恢复](deploy/README.md) · [客户端接入与生图](deploy/README.md#客户端配置) |
| 接口集成 | [API 参考](docs/api.md) · [模型定价](docs/api.md#模型定价) |
| 部署与使用 | [部署、备份与恢复](deploy/README.md) · [客户端接入](deploy/README.md#客户端配置) |
| 接口集成 | [API 参考](docs/api.md) · [模型目录](docs/api.md#模型目录) · [模型定价](docs/api.md#模型定价) |
| 使用插件 | [安装、配置与使用](docs/plugins.md) |
| 开发插件 | [SDK 与合同](backend/crates/gateway-plugin/sdk/README.md) · [打包工具](backend/apps/plugin-cli/README.md) · [官方示例](https://github.com/zyycn/codex-proxy-plugins/blob/main/README.md) |
| 开发共用组件 | [组件库说明](https://github.com/zyycn/codex-proxy-ui/blob/main/README.md) · [组件参考](https://github.com/zyycn/codex-proxy-ui/blob/main/playground/components/index.md) · [Playground](https://zyycn.github.io/codex-proxy-ui/) |
@@ -132,6 +55,28 @@ curl http://127.0.0.1:8080/v1/models \
感谢 [LINUX DO](https://linux.do) 社区提供开放、友善的技术交流平台
## 贡献者
[<img src="https://contrib.rocks/image?repo=zyycn/codex-proxy-rs&amp;columns=10" alt="查看 GitHub 贡献者列表" width="480">](https://github.com/zyycn/codex-proxy-rs/graphs/contributors)
## Star History
<a href="https://simrepo.dera.page/#zyycn/codex-proxy-rs&amp;Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://simrepo.dera.page/svg?repos=zyycn/codex-proxy-rs&amp;type=Date&amp;theme=dark">
<img src="https://simrepo.dera.page/svg?repos=zyycn/codex-proxy-rs&amp;type=Date" alt="Codex Proxy RS 的 GitHub Star 增长趋势" width="560">
</picture>
</a>
## 支持项目
如果 Codex Proxy RS 帮助到你了,欢迎请我喝杯咖啡 ☕
[![Support me on Ko-fi](docs/donations/ko-fi.svg)](https://ko-fi.com/zyycn)
[<img src="docs/donations/wechat-tips.png" alt="WeChat appreciation code" width="138">](docs/donations/wechat-tips.png)&nbsp;
[<img src="docs/donations/alipay.png" alt="Alipay QR code" width="138">](docs/donations/alipay.png)
## 许可证
本项目基于 [Apache License 2.0](LICENSE) 开源
+6 -6
View File
@@ -3006,9 +3006,9 @@ checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
[[package]]
name = "openssl"
version = "0.10.80"
version = "0.10.82"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a45fa2aa886c42762255da344f0a0d313e254066c46aad76f300c3d3da62d967"
checksum = "4de8111e94a56adca7ebfe6c365b6d42f99deb69b74b6becacd4204e2f193aa2"
dependencies = [
"bitflags",
"cfg-if",
@@ -3052,9 +3052,9 @@ dependencies = [
[[package]]
name = "openssl-sys"
version = "0.9.116"
version = "0.9.118"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f28a22dc7140cda5f096e5e7724a6962ca81a7f8bfd2979f9b18c11af56318c4"
checksum = "19c413d6ec9ebaf5e1c829d355cb3e9f783778d700f135be0921d52fce3c60ae"
dependencies = [
"cc",
"libc",
@@ -4797,7 +4797,7 @@ dependencies = [
[[package]]
name = "tokio-tungstenite"
version = "0.28.0"
source = "git+https://github.com/openai-oss-forks/tokio-tungstenite?rev=0e5b2d73aa18dd9f0a50ee9ff199d5aef7594186#0e5b2d73aa18dd9f0a50ee9ff199d5aef7594186"
source = "git+https://github.com/openai-oss-forks/tokio-tungstenite?rev=7447c427513cfe685f236e1ac0513c4ea3dd9c0b#7447c427513cfe685f236e1ac0513c4ea3dd9c0b"
dependencies = [
"futures-util",
"log",
@@ -5006,7 +5006,7 @@ checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
[[package]]
name = "tungstenite"
version = "0.27.0"
source = "git+https://github.com/openai-oss-forks/tungstenite-rs?rev=4fffad30fe373adbdcffab9545e9e9bf4f2fc19f#4fffad30fe373adbdcffab9545e9e9bf4f2fc19f"
source = "git+https://github.com/openai-oss-forks/tungstenite-rs?rev=bc589d684755a8c02da0fc7e58d0861cbfc306f1#bc589d684755a8c02da0fc7e58d0861cbfc306f1"
dependencies = [
"bytes",
"data-encoding",
+8 -13
View File
@@ -1,7 +1,6 @@
# Codex Proxy Plugin CLI
`cpr-plugin` 校验并规范化作者清单、收集声明的资源,生成可安装归档及 SHA-256 校验文件。
输出合同与 [SDK 版本](../../crates/gateway-plugin/sdk/README.md)一致
`cpr-plugin` 按 [SDK 合同](../../crates/gateway-plugin/sdk/README.md)校验清单,将插件可执行文件与声明的资源打包,并输出 SHA-256 校验文件
## 安装
@@ -11,7 +10,7 @@
cargo +1.99.1 install --locked --path backend/apps/plugin-cli --root /path/to/local-tools
```
将 `/path/to/local-tools/bin` 加入 `PATH`,或使用可执行文件的完整路径;工具链与宿主 [验证命令](../../../docs/architecture.md#验证命令)一致
将 `/path/to/local-tools/bin` 加入 `PATH`,或使用可执行文件的完整路径
## 打包
@@ -26,24 +25,20 @@ cpr-plugin package \
--output-dir /path/to/output
```
`--resource-map web=web/dist` 将包内 `web/` 前缀映射到作者清单所在目录下的 `web/dist/`。
可重复传入不同前缀,源目录必须位于项目内;没有对应资源时省略该参数,未使用的映射会被拒绝。
未映射的资源按清单中的相对路径读取,只收集 `resources` 声明的文件
资源文件须在 `resources` 中声明,默认从清单所在目录按相对路径读取。
`--resource-map web=web/dist` 从项目内的 `web/dist/` 读取包内 `web/` 资源。可为不同前缀重复传参,未匹配任何资源的映射会报错
输出为 `<插件 ID>-<版本>-<目标 triple>.tar.gz` 及同名 `.tar.gz.sha256`;归档根目录直接包含 `plugin.json`、可执行文件和声明资源。
输出为 `<插件 ID>-<版本>-<目标 triple>.tar.gz` 及对应的 `.tar.gz.sha256`。归档根目录包含 `plugin.json`、可执行文件和声明资源。
输入清单及生成后的清单均不得超过 64 KiB,压缩包上限为 32 MiB,展开归档上限为 128 MiB
作者清单不填写 `package`;字段省略规则、能力版本和挂载阶段见 [SDK 扩展项声明](../../crates/gateway-plugin/sdk/docs/manifest.md#扩展项简写)。
CLI 生成规范化后的 `plugin.json`,补入协议版本、目标平台和文件摘要。打包成功只证明输入符合包合同,实际启动与能力仍需在目标宿主验证
作者清单须省略 `package`。CLI 将协议版本、目标平台和文件摘要写入 `plugin.json`。可省略的声明字段见 [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`,可通过[子模块](../../../docs/development.md#源码联调)检出;本工具不负责源码构建、上传或启用插件
打包后在目标宿主验证启动和插件功能。完整示例见插件[子模块](../../../docs/development.md#源码联调)的 `examples/workbench`
### 图标资源
在作者清单的 `icon` 中指定图标,并在 `resources` 中登记对应路径与 MIME 类型,配置方式见
[SDK 插件图标](../../crates/gateway-plugin/sdk/docs/manifest.md#插件图标)。图标与其他声明资源一样参与打包和摘要计算,
无需额外命令参数;工具保留文件原始内容,宿主安装时验证图标内容与资源限制
按 [SDK 插件图标](../../crates/gateway-plugin/sdk/docs/manifest.md#插件图标)填写 `icon` 和 `resources`。CLI 自动打包原文件并计算摘要,宿主在安装时校验
## 开发
@@ -14,15 +14,25 @@ use super::{PageSize, Revision, observability::DecimalAmount};
pub fn validate_group_fields(
name: &str,
description: Option<&str>,
) -> Result<(), super::AdminModelError> {
if name.trim() != name
|| name.is_empty()
|| name.chars().count() > 100
|| name.chars().any(char::is_control)
|| description
.is_some_and(|value| value.len() > 4096 || value.chars().any(char::is_control))
{
return Err(super::AdminModelError::InvalidAccountGroupFields);
) -> Result<(), super::AdminError> {
if name.trim().is_empty() {
return Err(super::AdminError::invalid("请输入账号组名称"));
}
if name.chars().count() > 100 {
return Err(super::AdminError::invalid("账号组名称最多 100 个字符"));
}
if name.trim() != name || name.chars().any(char::is_control) {
return Err(super::AdminError::invalid(
"账号组名称不能包含首尾空白或控制字符",
));
}
if let Some(description) = description {
if description.len() > 4096 {
return Err(super::AdminError::invalid("账号组描述最多 4096 字节"));
}
if description.chars().any(char::is_control) {
return Err(super::AdminError::invalid("账号组描述不能包含控制字符"));
}
}
Ok(())
}
@@ -23,6 +23,7 @@ pub mod provider_credentials;
pub mod proxies;
pub mod quota_forecast;
pub mod quota_forecast_sampling;
pub mod quota_history;
pub mod reset_credit_automation;
pub mod retention;
pub mod settings;
@@ -235,8 +236,6 @@ pub enum AdminModelError {
InvalidPageSize(u16),
#[error("observability page size {0} is outside 1..=100")]
InvalidObservabilityPageSize(u16),
#[error("account group name or description is invalid")]
InvalidAccountGroupFields,
#[error("client key group IDs are duplicated or exceed 1000 entries")]
InvalidClientKeyGroups,
#[error("client key page size must be inside 1..=65535")]
@@ -158,7 +158,7 @@ impl OtherRequestOutcome {
#[derive(Debug, Clone, Default, PartialEq, Eq, Hash)]
pub struct UsageFilter {
pub client_api_key_name: Option<String>,
pub provider_account_name: Option<String>,
pub provider_account_search: Option<String>,
pub client_api_key_ref: Option<String>,
pub request_id: Option<String>,
pub provider_account_ref: Option<String>,
@@ -180,7 +180,7 @@ pub struct UsageFilter {
pub enum UsageRecordStatus {
#[default]
Success,
Error,
Error(Option<UsageErrorOrigin>),
All,
}
@@ -814,6 +814,17 @@ pub enum UsageErrorOrigin {
Unknown,
}
/// 来源规则所依赖的已保存事实,供内存投影与持久层分页查询共同解释
#[derive(Clone, Copy)]
pub enum UsageErrorEvidence {
ProviderErrorCode,
UpstreamStatusAtLeast(u16),
SavedUpstreamErrorOrClose,
ErrorKind(&'static [&'static str]),
Continuation(&'static [&'static str]),
ConnectionExit(&'static [&'static str]),
}
impl UsageErrorOrigin {
#[must_use]
pub const fn as_str(self) -> &'static str {
@@ -0,0 +1,87 @@
//! 单个额度桶的历史观测;原始文档只在宿主内交给 Provider 解释
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use super::{observability::TimeRange, provider_credentials::ProviderDocument};
#[derive(Debug, Clone)]
pub struct QuotaHistoryQuery {
pub window_key: String,
pub range: TimeRange,
pub cursor: Option<QuotaHistoryCursor>,
}
impl QuotaHistoryQuery {
/// 起点基线最多回看一个查询区间
pub fn scan_start(&self) -> DateTime<Utc> {
self.range
.start
.checked_sub_signed(self.range.end - self.range.start)
.unwrap_or(DateTime::<Utc>::MIN_UTC)
}
}
/// 完成时间可能相同,继续读取时保留数据库精度和请求 ID
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct QuotaHistoryCursor {
pub completed_at: DateTime<Utc>,
pub id: String,
}
pub struct QuotaDocumentPage {
pub documents: Vec<(DateTime<Utc>, ProviderDocument)>,
pub next_cursor: Option<QuotaHistoryCursor>,
}
#[derive(Debug, Clone, PartialEq)]
pub struct QuotaReading {
pub plan_type: Option<String>,
pub used_percent: f64,
pub reset_at: Option<DateTime<Utc>>,
}
pub type QuotaHistoryParser = fn(&ProviderDocument, &str) -> Option<QuotaReading>;
pub struct QuotaHistoryPoint {
pub observed_at: DateTime<Utc>,
pub reading: QuotaReading,
}
#[derive(Default)]
pub struct QuotaHistoryPage {
pub samples: Vec<QuotaHistoryPoint>,
pub baseline: Option<QuotaHistoryPoint>,
pub next_cursor: Option<QuotaHistoryCursor>,
}
impl QuotaHistoryPage {
pub fn from_documents(
page: QuotaDocumentPage,
query: &QuotaHistoryQuery,
parse: QuotaHistoryParser,
) -> Self {
let mut result = Self {
next_cursor: page.next_cursor,
..Self::default()
};
for (observed_at, document) in page.documents {
let Some(reading) = parse(&document, &query.window_key) else {
continue;
};
let point = QuotaHistoryPoint {
observed_at,
reading,
};
if observed_at < query.range.start {
// 倒序扫描遇到的第一个同桶读数就是最近基线,无需再向前翻页
result.baseline = Some(point);
result.next_cursor = None;
break;
}
result.samples.push(point);
}
result
}
}
@@ -34,6 +34,12 @@ pub trait PluginAccountAccess: Send + Sync {
Err(AdminError::unavailable("插件额度事实查询暂不可用"))
}
async fn quota_history(
&self,
account: &ProviderAccountId,
query: crate::model::quota_history::QuotaHistoryQuery,
) -> Result<crate::model::quota_history::QuotaHistoryPage, AdminError>;
/// 通过 Provider 原生管理路径刷新额度;不向插件暴露凭据或执行额度重置
async fn refresh_quota(
&self,
@@ -349,6 +349,11 @@ pub trait ProviderAdmin: Send + Sync {
Ok(None)
}
/// 历史文档由 Provider 按稳定窗口键解释,不支持的 Provider 不扫描请求记录
fn quota_history_parser(&self) -> Option<crate::model::quota_history::QuotaHistoryParser> {
None
}
/// 历史观测的协议字段仅由具体 Provider 解释;不支持时保留累计估算
fn quota_forecast_observation(
&self,
@@ -180,6 +180,16 @@ pub trait AccountStore:
windows: &[AccountUsageWindowQuery],
) -> AdminStoreResult<Vec<AccountUsageWindowResult>>;
/// 按完成时间倒序读取一页保留的请求观测,不按本地计费结果筛选
async fn quota_documents(
&self,
account: &gateway_core::account::ProviderAccountId,
provider: &gateway_core::routing::ProviderKind,
created_at: DateTime<Utc>,
range: TimeRange,
before: Option<&crate::model::quota_history::QuotaHistoryCursor>,
) -> AdminStoreResult<crate::model::quota_history::QuotaDocumentPage>;
/// 从同一数据库语句取得截止快照的累计用量和有界历史观测
async fn load_quota_forecast_history(
&self,
@@ -470,6 +480,7 @@ pub trait AccountGroupStore: Send + Sync {
context: &MutationContext,
) -> AdminStoreResult<AccountGroupMutation>;
/// 仍有 API Key 引用分组时返回 Conflict
async fn delete_account_group(
&self,
command: DeleteAccountGroup,
@@ -24,7 +24,7 @@ use crate::{
NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
},
},
ports::store::{AccountGroupStore, AccountRuntimeStore},
ports::store::{AccountGroupStore, AccountRuntimeStore, AdminStoreErrorKind},
};
use super::{map_store_error, publish_committed};
@@ -159,8 +159,7 @@ impl AccountGroupService for DefaultAccountGroupService {
crate::model::account_groups::validate_group_fields(
&command.name,
command.description.as_deref(),
)
.map_err(|_| AdminError::invalid("账号组请求不合法"))?;
)?;
let id = AccountGroupId::new(format!("grp_{}", Uuid::now_v7().simple()))
.map_err(|_| AdminError::internal("创建账号组 ID 失败"))?;
self.publish(
@@ -189,8 +188,7 @@ impl AccountGroupService for DefaultAccountGroupService {
crate::model::account_groups::validate_group_fields(
&command.name,
command.description.as_deref(),
)
.map_err(|_| AdminError::invalid("账号组请求不合法"))?;
)?;
self.publish(self.store.update_account_group(command, context).await)
.await
}
@@ -209,8 +207,12 @@ impl AccountGroupService for DefaultAccountGroupService {
context: &MutationContext,
command: DeleteAccountGroup,
) -> Result<AccountGroupMutation, AdminError> {
self.publish(self.store.delete_account_group(command, context).await)
.await
match self.store.delete_account_group(command, context).await {
Err(error) if error.kind() == AdminStoreErrorKind::Conflict => {
Err(AdminError::conflict("分组仍绑定 API Key,请先解除绑定").with_source(error))
}
result => self.publish(result).await,
}
}
}
@@ -314,7 +314,6 @@ impl ClientKeyService for DefaultClientKeyService {
fn map_client_key_write_error(error: AdminStoreError) -> AdminError {
match error.kind() {
AdminStoreErrorKind::DuplicateName => AdminError::conflict("名称已存在"),
AdminStoreErrorKind::Conflict => AdminError::conflict("API Key 已存在,请使用其他密钥"),
_ => map_store_error(error, "client API key"),
}
@@ -4,20 +4,15 @@ use crate::model::{AdminError, AdminErrorKind};
use crate::ports::store::{AdminStoreError, AdminStoreErrorKind};
pub(super) fn map_store_error(error: AdminStoreError, resource: &'static str) -> AdminError {
let kind = match error.kind() {
AdminStoreErrorKind::Invalid => AdminErrorKind::Invalid,
AdminStoreErrorKind::NotFound => AdminErrorKind::NotFound,
AdminStoreErrorKind::StaleRevision
| AdminStoreErrorKind::DuplicateName
| AdminStoreErrorKind::Conflict => AdminErrorKind::Conflict,
AdminStoreErrorKind::Unavailable => AdminErrorKind::Unavailable,
};
let message = match kind {
AdminErrorKind::Invalid => "请求参数不合法",
AdminErrorKind::NotFound => "请求的资源不存在",
AdminErrorKind::Conflict => "当前资源状态冲突,请刷新后重试",
AdminErrorKind::Unavailable => "依赖服务暂不可用",
_ => "服务内部错误",
let (kind, message) = match error.kind() {
AdminStoreErrorKind::Invalid => (AdminErrorKind::Invalid, "请求参数不合法"),
AdminStoreErrorKind::NotFound => (AdminErrorKind::NotFound, "请求的资源不存在"),
AdminStoreErrorKind::StaleRevision => {
(AdminErrorKind::Conflict, "数据已更新,请刷新后再操作")
}
AdminStoreErrorKind::DuplicateName => (AdminErrorKind::Conflict, "名称已存在"),
AdminStoreErrorKind::Conflict => (AdminErrorKind::Conflict, "当前资源状态不允许此操作"),
AdminStoreErrorKind::Unavailable => (AdminErrorKind::Unavailable, "存储服务暂不可用"),
};
AdminError::new(kind, message).with_source(OperationFailure {
operation: resource,
@@ -49,9 +44,8 @@ pub(super) fn map_provider_error(
ProviderAdminErrorKind::Conflict => "服务商资源状态冲突,请刷新后重试",
ProviderAdminErrorKind::BadGateway => "上游服务请求失败",
ProviderAdminErrorKind::Ambiguous => "上游执行结果未知,请刷新状态后再决定是否重试",
ProviderAdminErrorKind::Unavailable | ProviderAdminErrorKind::CredentialRefreshRequired => {
"服务商暂不可用"
}
ProviderAdminErrorKind::Unavailable => "服务商暂不可用",
ProviderAdminErrorKind::CredentialRefreshRequired => "账号凭据需要刷新",
ProviderAdminErrorKind::Internal => "服务内部错误",
};
AdminError::new(kind, error.public_message().unwrap_or(message)).with_source(OperationFailure {
@@ -225,7 +225,7 @@ impl KeyUsageService for DefaultKeyUsageService {
.list_usage_records(UsageQuery {
status: match query.kind {
KeyUsageRecordKind::Success => UsageRecordStatus::Success,
KeyUsageRecordKind::Error => UsageRecordStatus::Error,
KeyUsageRecordKind::Error => UsageRecordStatus::Error(None),
KeyUsageRecordKind::All => UsageRecordStatus::All,
},
range: query.usage.range,
@@ -1,6 +1,8 @@
//! 从已保存的错误事实投影管理端来源,不参与执行错误分类或重试
use crate::model::observability::{UsageErrorOrigin, UsageListRecord, UsageRecord};
use crate::model::observability::{
UsageErrorEvidence, UsageErrorOrigin, UsageListRecord, UsageRecord,
};
impl UsageListRecord {
#[must_use]
@@ -47,107 +49,124 @@ fn error_origin(
continuation_reason: Option<&str>,
connection_exit_reason: Option<&str>,
) -> UsageErrorOrigin {
if has_upstream_error
|| upstream_code.is_some_and(|code| !code.is_empty())
|| websocket_close_code.is_some()
|| upstream_status_code.is_some_and(|status| status >= 400)
|| matches!(
continuation_reason,
Some("upstream_rejected" | "quota_exhausted")
)
|| matches!(
error_kind,
// 这里匹配内部 errorKind;message_too_big 只由收到的上游 close 1009 产生
Some("permission_denied" | "message_too_big" | "upstream_capacity_unavailable")
)
{
return UsageErrorOrigin::Upstream;
}
if matches!(
continuation_reason,
Some(
"scope_unavailable"
| "pool_unavailable"
| "fresh_connection_required"
| "connection_busy"
| "latest_response_mismatch"
| "reused_connection_lost"
| "transport_payload_too_large"
)
) || matches!(
error_kind,
Some(
"process_interrupted"
| "process_terminated"
| "internal_error"
| "model_not_found"
| "no_available_provider"
| "no_eligible_account"
| "account_capacity_unavailable"
| "middleware_capacity_unavailable"
| "concurrency_queue_full"
| "concurrency_queue_timeout"
| "provider_infrastructure_unavailable"
| "session_policy_restricted"
| "request_policy_denied"
| "policy_denied"
| "budget_exhausted"
)
) || matches!(
connection_exit_reason,
Some(
"command_channel_closed"
| "local_close"
| "message_receiver_closed"
| "client_cancelled"
| "downstream_send_failed"
| "downstream_connection_closed"
| "downstream_rebound"
| "pool_shutdown"
| "max_age_expired"
| "idle_timeout_expired"
| "proxy_capacity_evicted"
| "search_activation_required"
)
) {
return UsageErrorOrigin::Proxy;
}
if matches!(
connection_exit_reason,
Some(
"upstream_close"
| "normal_close"
| "unexpected_binary_event"
| "incomplete_response"
| "failed_response"
)
) {
return UsageErrorOrigin::Upstream;
}
if error_kind == Some("transport")
|| matches!(
connection_exit_reason,
Some(
"eof"
| "unexpected_eof"
| "transport_error"
| "connection_reset"
| "connection_aborted"
| "broken_pipe"
| "tcp_reset"
| "reset_without_closing_handshake"
| "transport_timeout"
| "outbound_transport_error"
| "receive_idle_timeout"
| "pong_timeout"
| "ping_write_timeout"
| "pong_write_timeout"
)
)
{
return UsageErrorOrigin::Connection;
}
// invalid_request、protocol、rate_limited 等分类同时用于本地和上游失败
// 发送状态与笼统的连接退出摘要也不能替代缺失的来源事实
UsageErrorOrigin::Unknown
use UsageErrorEvidence::*;
UsageErrorOrigin::RULES
.iter()
.find(|(evidence, _)| match evidence {
ProviderErrorCode => upstream_code.is_some_and(|code| !code.is_empty()),
UpstreamStatusAtLeast(min) => upstream_status_code.is_some_and(|status| status >= *min),
SavedUpstreamErrorOrClose => has_upstream_error || websocket_close_code.is_some(),
ErrorKind(values) => error_kind.is_some_and(|value| values.contains(&value)),
Continuation(values) => {
continuation_reason.is_some_and(|value| values.contains(&value))
}
ConnectionExit(values) => {
connection_exit_reason.is_some_and(|value| values.contains(&value))
}
})
.map_or(UsageErrorOrigin::Unknown, |(_, origin)| *origin)
}
impl UsageErrorOrigin {
/// 第一条命中的规则决定来源;含义不唯一的分类在缺少其他证据时保留 unknown
pub const RULES: &'static [(UsageErrorEvidence, Self)] = {
use UsageErrorEvidence::*;
&[
(ProviderErrorCode, Self::Upstream),
(UpstreamStatusAtLeast(400), Self::Upstream),
(
Continuation(&["upstream_rejected", "quota_exhausted"]),
Self::Upstream,
),
// message_too_big 只由收到的上游 close 1009 产生
(
ErrorKind(&[
"permission_denied",
"message_too_big",
"upstream_capacity_unavailable",
]),
Self::Upstream,
),
(SavedUpstreamErrorOrClose, Self::Upstream),
(
Continuation(&[
"scope_unavailable",
"pool_unavailable",
"fresh_connection_required",
"connection_busy",
"latest_response_mismatch",
"reused_connection_lost",
"transport_payload_too_large",
]),
Self::Proxy,
),
(
ErrorKind(&[
"process_interrupted",
"process_terminated",
"internal_error",
"model_not_found",
"no_available_provider",
"no_eligible_account",
"account_capacity_unavailable",
"middleware_capacity_unavailable",
"concurrency_queue_full",
"concurrency_queue_timeout",
"provider_infrastructure_unavailable",
"session_policy_restricted",
"request_policy_denied",
"policy_denied",
"budget_exhausted",
]),
Self::Proxy,
),
(
ConnectionExit(&[
"command_channel_closed",
"local_close",
"message_receiver_closed",
"client_cancelled",
"downstream_send_failed",
"downstream_connection_closed",
"downstream_rebound",
"pool_shutdown",
"max_age_expired",
"idle_timeout_expired",
"proxy_capacity_evicted",
"search_activation_required",
]),
Self::Proxy,
),
(
ConnectionExit(&[
"upstream_close",
"normal_close",
"unexpected_binary_event",
"incomplete_response",
"failed_response",
]),
Self::Upstream,
),
(ErrorKind(&["transport"]), Self::Connection),
(
ConnectionExit(&[
"eof",
"unexpected_eof",
"transport_error",
"connection_reset",
"connection_aborted",
"broken_pipe",
"tcp_reset",
"reset_without_closing_handshake",
"transport_timeout",
"outbound_transport_error",
"receive_idle_timeout",
"pong_timeout",
"ping_write_timeout",
"pong_write_timeout",
]),
Self::Connection,
),
]
};
}
@@ -126,6 +126,46 @@ impl PluginAccountAccess for DefaultPluginAccountAccess {
self.quota(account_id, false).await
}
async fn quota_history(
&self,
account_id: &ProviderAccountId,
query: crate::model::quota_history::QuotaHistoryQuery,
) -> Result<crate::model::quota_history::QuotaHistoryPage, AdminError> {
use crate::model::{observability::TimeRange, quota_history::QuotaHistoryPage};
let account = self
.accounts
.load_account_record(account_id)
.await
.map_err(|error| map_store_error(error, "plugin quota history"))?
.ok_or_else(|| AdminError::not_found("账号不存在"))?;
let Some(parse) = self
.provider(&account.provider_kind)?
.quota_history_parser()
else {
return Ok(QuotaHistoryPage::default());
};
let start = query.scan_start().max(account.created_at);
if start >= query.range.end {
return Ok(QuotaHistoryPage::default());
}
let page = self
.accounts
.quota_documents(
account_id,
&account.provider_kind,
account.created_at,
TimeRange {
start,
end: query.range.end,
},
query.cursor.as_ref(),
)
.await
.map_err(|error| map_store_error(error, "plugin quota history"))?;
Ok(QuotaHistoryPage::from_documents(page, &query, parse))
}
async fn refresh_quota(
&self,
account_id: &ProviderAccountId,
@@ -845,6 +845,17 @@ impl AccountStore for FakeAccountStore {
.clone())
}
async fn quota_documents(
&self,
_: &gateway_core::account::ProviderAccountId,
_: &gateway_core::routing::ProviderKind,
_: chrono::DateTime<chrono::Utc>,
_: gateway_admin::model::observability::TimeRange,
_: Option<&gateway_admin::model::quota_history::QuotaHistoryCursor>,
) -> AdminStoreResult<gateway_admin::model::quota_history::QuotaDocumentPage> {
unreachable!("测试不读取历史额度文档")
}
async fn load_quota_forecast_history(
&self,
window: &AccountUsageWindowQuery,
@@ -546,6 +546,17 @@ impl AccountStore for UnavailableStore {
Err(unavailable("account quota window usage"))
}
async fn quota_documents(
&self,
_: &gateway_core::account::ProviderAccountId,
_: &gateway_core::routing::ProviderKind,
_: chrono::DateTime<chrono::Utc>,
_: gateway_admin::model::observability::TimeRange,
_: Option<&gateway_admin::model::quota_history::QuotaHistoryCursor>,
) -> AdminStoreResult<gateway_admin::model::quota_history::QuotaDocumentPage> {
unreachable!("测试不读取历史额度文档")
}
async fn load_quota_forecast_history(
&self,
_: &AccountUsageWindowQuery,
@@ -60,7 +60,7 @@ async fn explicit_service_calls_freeze_empty_plan_and_cancel_before_entering_ter
)
.await
.unwrap();
// 内部 pricing 不再单独进入插件链;显式调用只解析一次发布集合
// 每次显式调价只解析一次插件发布集合
assert_eq!(resolutions.load(Ordering::SeqCst), expected);
}
store.updated.lock().unwrap().take();
@@ -51,7 +51,6 @@ impl From<gateway_admin::model::account_groups::AccountGroupRef> for AccountGrou
}
const DEFAULT_PAGE_SIZE: u32 = 50;
const MAX_PAGE_SIZE: u32 = 200;
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
@@ -66,7 +65,7 @@ impl ListAccountGroupsQuery {
fn into_command(self) -> Result<AccountGroupListQuery, WireValidationError> {
let page = self.page.unwrap_or(1);
let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
if page == 0 || page_size == 0 || page_size > MAX_PAGE_SIZE {
if page == 0 {
return Err(WireValidationError::new("page"));
}
let search = self
@@ -507,11 +506,16 @@ fn group_color(value: &str) -> Result<AccountGroupColor, AdminError> {
fn validate_group_fields(name: &str, description: Option<&str>) -> Result<(), AdminError> {
gateway_admin::model::account_groups::validate_group_fields(name, description)
.map_err(|_| AdminError::bad_request("账号组请求不合法"))
.map_err(map_admin_service_error)
}
fn map_wire_error(_: WireValidationError) -> AdminError {
AdminError::bad_request("账号组查询参数不合法")
fn map_wire_error(error: WireValidationError) -> AdminError {
match error.field() {
"page" => AdminError::bad_request("页码须大于 0"),
"pageSize" => AdminError::bad_request(format!("每页数量须为 1 至 {}", PageSize::MAX)),
"search" => AdminError::bad_request("搜索内容最多 256 字节,不能包含控制字符"),
field => AdminError::bad_request(format!("{field} 字段不合法")),
}
}
fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
@@ -1092,7 +1092,7 @@ fn map_wire_error(error: WireValidationError) -> AdminError {
"search" => "搜索内容过长或包含控制字符",
"sortBy" => "排序字段不受支持",
"sortDirection" => "排序方向必须为 asc(升序)或 desc(降序)",
_ => "API Key 请求参数不合法",
field => return AdminError::bad_request(format!("{field} 字段不合法")),
};
AdminError::bad_request(message)
}
@@ -1410,7 +1410,14 @@ pub(crate) fn map_wire_error(error: WireValidationError) -> AdminError {
"dimension" => "诊断维度不合法",
"id" => "用量记录 ID 不能为空",
"cursor" => "观测数据游标不合法",
_ => "观测查询参数不合法",
"currentPage" => "页码须大于 0",
"pageSize" => {
return AdminError::bad_request(format!("每页数量须为 1 至 {}", DomainPageSize::MAX));
}
"status" => "请求状态须为 success、error 或 all",
"errorOrigin" => "错误来源须为 proxy、upstream、connection 或 unknown",
"errorOriginStatus" => "仅错误请求支持按错误来源筛选",
field => return AdminError::bad_request(format!("{field} 字段不合法")),
};
AdminError::bad_request(message)
}
@@ -32,8 +32,9 @@ impl DashboardQuery {
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct UsageQuery {
pub client_api_key_name: Option<String>,
pub account_name: Option<String>,
pub account_search: Option<String>,
pub status: Option<String>,
pub error_origin: Option<String>,
pub current_page: Option<u32>,
pub page_size: Option<u16>,
pub provider: Option<String>,
@@ -339,7 +340,7 @@ pub(crate) fn dashboard_today_range(
pub(crate) fn usage_filter(query: &UsageQuery) -> domain::UsageFilter {
domain::UsageFilter {
client_api_key_name: non_empty(query.client_api_key_name.clone()),
provider_account_name: non_empty(query.account_name.clone()),
provider_account_search: non_empty(query.account_search.clone()),
provider_kind: non_empty(query.provider.clone()),
model_contains: non_empty(query.model.clone()),
..Default::default()
@@ -354,11 +355,21 @@ pub(crate) fn usage_command(
let page_size_value =
DomainPageSize::new(page_size).map_err(|_| WireValidationError::new("pageSize"))?;
Ok(domain::UsageQuery {
status: match query.status.as_deref() {
None | Some("success") => domain::UsageRecordStatus::Success,
Some("error") => domain::UsageRecordStatus::Error,
Some("all") => domain::UsageRecordStatus::All,
Some(_) => return Err(WireValidationError::new("status")),
status: match (query.status.as_deref(), query.error_origin.as_deref()) {
(None | Some("success"), None) => domain::UsageRecordStatus::Success,
(Some("all"), None) => domain::UsageRecordStatus::All,
(Some("error"), origin) => domain::UsageRecordStatus::Error(match origin {
None => None,
Some("proxy") => Some(domain::UsageErrorOrigin::Proxy),
Some("upstream") => Some(domain::UsageErrorOrigin::Upstream),
Some("connection") => Some(domain::UsageErrorOrigin::Connection),
Some("unknown") => Some(domain::UsageErrorOrigin::Unknown),
Some(_) => return Err(WireValidationError::new("errorOrigin")),
}),
(None | Some("success" | "all"), Some(_)) => {
return Err(WireValidationError::new("errorOriginStatus"));
}
(Some(_), _) => return Err(WireValidationError::new("status")),
},
range: usage_range(
query.start_time.as_deref(),
+2 -2
View File
@@ -215,12 +215,12 @@ const METHOD_NOT_ALLOWED: AdminErrorSpec = AdminErrorSpec::new(
const TOO_MANY_LOGIN_ATTEMPTS: AdminErrorSpec = AdminErrorSpec::new(
StatusCode::TOO_MANY_REQUESTS,
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,
+45 -45
View File
@@ -178,7 +178,7 @@ pub(crate) fn client_access_error_response(error: ClientAccessError) -> Response
response
}
/// Desktop 优先于内嵌 CLI/Core;未知客户端及未提供应用版本的手机远程客户端返回 `None`
/// 识别 Desktop 应用或 CLI/Core;未知客户端及未提供应用版本的手机远程客户端返回 `None`
#[must_use]
pub fn identify_codex_client(headers: &HeaderMap) -> Option<IdentifiedCodexClient> {
const MAXIMUM_HEADER_LENGTH: usize = 4096;
@@ -196,25 +196,35 @@ pub fn identify_codex_client(headers: &HeaderMap) -> Option<IdentifiedCodexClien
"codex_mcp_server",
];
let originator = bounded_ascii_header(headers, "originator", MAXIMUM_HEADER_LENGTH);
let user_agent = bounded_ascii_header(headers, "user-agent", MAXIMUM_HEADER_LENGTH);
let is_desktop = originator.is_some_and(|value| value.eq_ignore_ascii_case("Codex Desktop"))
let ascii_header = |name: &'static str| headers.get(name).and_then(|value| value.to_str().ok());
let raw_user_agent = ascii_header("user-agent");
// HeaderValue::to_str 只接受 ASCII,可以按字节截取搜索范围
let user_agent = raw_user_agent.map(|ua| &ua[..ua.len().min(MAXIMUM_HEADER_LENGTH)]);
let is_desktop = ascii_header("originator")
.is_some_and(|value| value.eq_ignore_ascii_case("Codex Desktop"))
|| user_agent.is_some_and(|value| contains_ascii_case_insensitive(value, "Codex Desktop"));
if is_desktop {
let explicit_version = bounded_ascii_header(headers, "version", MAXIMUM_HEADER_LENGTH);
let version_header = headers.get("version");
let user_agent_version = user_agent.and_then(desktop_version_from_user_agent);
// 手机远程初始化会覆盖进程级 UA 后缀,保留的 Desktop/Core 前缀不代表应用版本
// 仅缺失版本信息时免于门禁;已提供的版本即使非法,也继续按 Desktop 校验
if !headers.contains_key("version")
&& user_agent_version.is_none()
&& headers
.get("user-agent")
.is_some_and(|value| value.as_bytes().len() <= MAXIMUM_HEADER_LENGTH)
&& user_agent.is_some_and(has_chatgpt_remote_user_agent_suffix)
if user_agent_version.is_none()
&& let Some(ua) = raw_user_agent.filter(|ua| ua.len() <= MAXIMUM_HEADER_LENGTH)
&& let Some(client) = user_agent_client_name(ua)
{
return None;
// 共享 App Server 可保留 Desktop 进程名,TUI 请求的 version 头也可能重复 Core 版本
if client.eq_ignore_ascii_case("codex-tui")
&& let Some(core) = desktop_core_version(ua)
&& version_header.is_none_or(|value| value.as_bytes() == core.as_bytes())
{
return Some(IdentifiedCodexClient {
kind: CodexClientKind::Cli,
version: CodexClientVersion::parse(core).ok(),
});
}
if version_header.is_none() && is_chatgpt_remote_client(client) {
return None;
}
}
let version = match explicit_version {
let version = match version_header.and_then(|value| value.to_str().ok()) {
Some(value) => CodexClientVersion::parse(value).ok(),
None => user_agent_version.and_then(|value| CodexClientVersion::parse(value).ok()),
};
@@ -244,18 +254,6 @@ pub fn identify_codex_client(headers: &HeaderMap) -> Option<IdentifiedCodexClien
None
}
fn bounded_ascii_header<'a>(
headers: &'a HeaderMap,
name: &'static str,
maximum_length: usize,
) -> Option<&'a str> {
let value = headers.get(name)?.to_str().ok()?;
if !value.is_ascii() {
return None;
}
Some(&value[..value.len().min(maximum_length)])
}
fn desktop_version_from_user_agent(user_agent: &str) -> Option<&str> {
let marker = "Codex Desktop;";
let start = find_ascii_case_insensitive(user_agent, marker)? + marker.len();
@@ -266,27 +264,29 @@ fn desktop_version_from_user_agent(user_agent: &str) -> Option<&str> {
.next()
}
fn has_chatgpt_remote_user_agent_suffix(user_agent: &str) -> bool {
let Some((_, suffix)) = user_agent
.strip_suffix(')')
.and_then(|value| value.rsplit_once(" ("))
else {
return false;
};
let Some((name, version)) = suffix.split_once("; ") else {
return false;
};
let Some(platform) = name
.strip_prefix("codex_chatgpt_")
.and_then(|value| value.strip_suffix("_remote"))
else {
return false;
};
[platform, version].into_iter().all(|value| {
fn desktop_core_version(user_agent: &str) -> Option<&str> {
let (product, rest) = user_agent.split_once('/')?;
let (version, _) = rest.split_once(' ')?;
product
.eq_ignore_ascii_case("Codex Desktop")
.then_some(version)
}
fn user_agent_client_name(user_agent: &str) -> Option<&str> {
let (_, suffix) = user_agent.strip_suffix(')')?.rsplit_once(" (")?;
let (name, version) = suffix.split_once("; ")?;
let valid_token = |value: &str| {
!value.is_empty()
&& !value.contains(['(', ')', ';'])
&& !value.bytes().any(|byte| byte.is_ascii_whitespace())
})
};
(valid_token(name) && valid_token(version)).then_some(name)
}
fn is_chatgpt_remote_client(name: &str) -> bool {
name.strip_prefix("codex_chatgpt_")
.and_then(|value| value.strip_suffix("_remote"))
.is_some_and(|platform| !platform.is_empty())
}
fn contains_ascii_case_insensitive(haystack: &str, needle: &str) -> bool {
@@ -19,7 +19,6 @@ use crate::openai::generation::{
};
const OPENAI_SUBAGENT_KEY: &str = "x-openai-subagent";
const CODEX_TURN_METADATA_KEY: &str = "x-codex-turn-metadata";
const PASSTHROUGH_HEADERS_CONTEXT_KEY: &str = "opaque_request_headers";
const DOWNSTREAM_WEBSOCKET_CONNECTION_ID_CONTEXT_KEY: &str = "downstream_websocket_connection_id";
@@ -36,9 +35,7 @@ pub(super) enum RequestDecodeSource {
pub struct OpenAiRequestHeaders {
turn_state: Option<String>,
turn_metadata: Option<String>,
beta_features: Option<String>,
version: Option<String>,
include_timing_metrics: Option<String>,
codex_window_id: Option<String>,
parent_thread_id: Option<String>,
downstream_websocket_connection_id: Option<String>,
@@ -62,9 +59,7 @@ impl OpenAiRequestHeaders {
Self {
turn_state: header_string(headers, "x-codex-turn-state"),
turn_metadata: header_string(headers, "x-codex-turn-metadata"),
beta_features: header_string(headers, "x-codex-beta-features"),
version: header_string(headers, "version"),
include_timing_metrics: header_string(headers, "x-responsesapi-include-timing-metrics"),
codex_window_id: header_string(headers, "x-codex-window-id"),
parent_thread_id: header_string(headers, "x-codex-parent-thread-id"),
downstream_websocket_connection_id: None,
@@ -120,22 +115,18 @@ impl OpenAiRequestHeaders {
fn protocol_context(
&self,
use_websocket: Option<bool>,
frame_turn_metadata: Option<&String>,
source: RequestDecodeSource,
) -> Map<String, Value> {
let mut context = Map::new();
insert_protocol_context(&mut context, "turn_state", self.turn_state.as_ref());
insert_protocol_context(
&mut context,
"turn_metadata",
frame_turn_metadata.or(self.turn_metadata.as_ref()),
);
insert_protocol_context(&mut context, "beta_features", self.beta_features.as_ref());
insert_protocol_context(&mut context, "turn_metadata", self.turn_metadata.as_ref());
if matches!(source, RequestDecodeSource::WebSocketFrame) {
context.insert(
gateway_protocol::openai::WEBSOCKET_FRAME_CONTEXT_KEY.to_owned(),
Value::Bool(true),
);
}
insert_protocol_context(&mut context, "version", self.version.as_ref());
insert_protocol_context(
&mut context,
"include_timing_metrics",
self.include_timing_metrics.as_ref(),
);
insert_protocol_context(
&mut context,
"codex_window_id",
@@ -338,11 +329,7 @@ pub(super) fn decode_request_object(
.unwrap_or(ContinuationIntent::None);
request_headers.apply_subagent(&mut object);
let frame_turn_metadata = match source {
RequestDecodeSource::Http => None,
RequestDecodeSource::WebSocketFrame => frame_turn_metadata(&object),
};
let protocol_context = request_headers.protocol_context(use_websocket, frame_turn_metadata);
let protocol_context = request_headers.protocol_context(use_websocket, source);
let semantics =
gateway_protocol::openai::codex_responses_request_semantics(&object, &protocol_context);
@@ -381,16 +368,6 @@ pub(super) fn decode_request_object(
})
}
fn frame_turn_metadata(body: &Map<String, Value>) -> Option<&String> {
body.get("client_metadata")
.and_then(Value::as_object)
.and_then(|metadata| metadata.get(CODEX_TURN_METADATA_KEY))
.and_then(|value| match value {
Value::String(value) if !value.trim().is_empty() => Some(value),
_ => None,
})
}
fn inject_subagent_metadata(body: &mut Map<String, Value>, subagent: &str) {
let metadata = body
.entry("client_metadata".to_owned())
@@ -74,13 +74,11 @@ pub(crate) async fn responses_websocket(
&headers,
connect_info.map(|Extension(ConnectInfo(address))| address),
);
let request_headers = OpenAiRequestHeaders::from_headers(&headers);
ResponsesWebSocketAdapter::new(service).upgrade_with_client_context(
websocket,
client,
client_ip,
user_agent,
request_headers,
headers,
middleware.map(|Extension(plan)| plan),
lifetime.map(|Extension(lifetime)| lifetime),
@@ -107,7 +105,6 @@ impl ResponsesWebSocketAdapter {
client: AuthenticatedClient,
client_ip: Option<IpAddr>,
user_agent: Option<String>,
request_headers: OpenAiRequestHeaders,
raw_headers: HeaderMap,
middleware: Option<FrozenMiddlewarePlan>,
lifetime: Option<Arc<crate::middleware::CallLifetime>>,
@@ -130,7 +127,6 @@ impl ResponsesWebSocketAdapter {
connection_id,
client_ip,
user_agent,
request_headers,
raw_headers,
lifecycle: self.service.lifecycle(),
connection_guard,
@@ -150,7 +146,6 @@ struct ResponsesWebSocketSession {
connection_id: String,
client_ip: Option<IpAddr>,
user_agent: Option<String>,
request_headers: OpenAiRequestHeaders,
raw_headers: HeaderMap,
lifecycle: Arc<dyn ConnectionLifecycle>,
connection_guard: Box<dyn ConnectionGuard>,
@@ -164,8 +159,7 @@ async fn serve_responses_websocket(socket: Socket, session: ResponsesWebSocketSe
connection_id,
client_ip,
user_agent,
request_headers,
raw_headers,
mut raw_headers,
lifecycle,
connection_guard,
middleware,
@@ -178,8 +172,6 @@ async fn serve_responses_websocket(socket: Socket, session: ResponsesWebSocketSe
let cancellation = lifecycle.cancellation().child_token();
let _connection_cancellation =
crate::middleware::websocket::CancelOnDrop(Some(cancellation.clone()));
let request_headers =
request_headers.with_downstream_websocket_connection_id(connection_id.clone());
// 帧中间件可能改写终态,此时不能据原始响应关闭下游连接
let reconnect_for_replay = !middleware
.as_ref()
@@ -241,31 +233,32 @@ async fn serve_responses_websocket(socket: Socket, session: ResponsesWebSocketSe
continue;
}
request_count = request_count.saturating_add(1);
// 初步解码只保留路由事实,避免整份正文跨越准入等待和响应交付
let model_hint = match decode_response_create_with_context(&payload, &request_headers) {
Ok(decoded) => Some(decoded.metadata().requested_model().to_owned()),
Err(error) => {
trace_rejected_request(
&correlation_id,
connection.id(),
&payload,
"decode",
&error.to_string(),
);
if send_protocol_error(
&mut connection,
StatusCode::BAD_REQUEST,
error.protocol_body(),
&correlation_id,
)
.await
== ForwardOutcome::Disconnect
{
break;
// 初步解码只取帧中的模型,实际执行使用该帧当前生效的请求头
let model_hint =
match decode_response_create_with_context(&payload, &OpenAiRequestHeaders::default()) {
Ok(decoded) => Some(decoded.metadata().requested_model().to_owned()),
Err(error) => {
trace_rejected_request(
&correlation_id,
connection.id(),
&payload,
"decode",
&error.to_string(),
);
if send_protocol_error(
&mut connection,
StatusCode::BAD_REQUEST,
error.protocol_body(),
&correlation_id,
)
.await
== ForwardOutcome::Disconnect
{
break;
}
continue;
}
continue;
}
};
};
// deadline 与 Text 可能同时就绪;在任何上游执行开始前再次封住该竞争窗口
if connection.is_expired() {
trace_rejected_request(
@@ -336,6 +329,9 @@ async fn serve_responses_websocket(socket: Socket, session: ResponsesWebSocketSe
headers: encode_headers(&raw_headers),
body: Bytes::from(payload),
};
// 握手的轮次头只属于首次执行,复用连接时由各 response.create 携带本轮数据
raw_headers.remove("x-codex-turn-state");
raw_headers.remove("x-codex-turn-metadata");
let service_for_terminal = service.clone();
let replay_for_terminal = replay.clone();
let connection_id_for_terminal = connection.id().to_owned();
@@ -19,8 +19,8 @@ use super::{
use crate::ApiState;
// 公开协议路径由 API 层统一定义;Core 使用操作类型,不根据这些路径分派业务
pub(super) const RESPONSES_PATH: &str = "/v1/responses";
// Core 使用操作类型,不根据这些协议路径分派业务
pub(super) use gateway_protocol::openai::RESPONSES_PATH;
pub(super) const MESSAGES_PATH: &str = "/v1/messages";
pub(super) const MESSAGE_TOKENS_PATH: &str = "/v1/messages/count_tokens";
pub(super) const CHAT_COMPLETIONS_PATH: &str = "/v1/chat/completions";
@@ -215,7 +215,7 @@ async fn mutation_route_should_reject_unknown_json_fields() {
"name": "Unknown field",
"description": null,
"color": "#2563EBFF",
"providerKind": "openai"
"unknownField": true
})),
true,
)
@@ -232,7 +232,7 @@ async fn create_route_should_reject_six_digit_color_without_alpha() {
Method::POST,
"/api/admin/account-groups/create",
Some(json!({
"name": "Opaque legacy color",
"name": "Color without alpha",
"description": null,
"color": "#2563EB"
})),
@@ -341,7 +341,7 @@ async fn account_quota_refresh_time_uses_server_clock_and_deployment_timezone()
));
let future = now + Duration::days(1);
let future_display = zone.local(future).format("%Y-%m-%d %H:%M:%S").to_string();
for (observed_at, expected, legacy) in [
for (observed_at, expected, display) in [
(None, json!(null), "—"),
(Some(now), json!({ "kind": "just_now" }), "刚刚"),
(
@@ -389,7 +389,7 @@ async fn account_quota_refresh_time_uses_server_clock_and_deployment_timezone()
let value: serde_json::Value = serde_json::from_slice(&body).unwrap();
let quota = &value["data"]["items"][0]["quota"];
assert_eq!(quota["refreshedAtRelative"], expected);
assert_eq!(quota["refreshedAtDisplay"], legacy);
assert_eq!(quota["refreshedAtDisplay"], display);
let refreshed_at = quota["refreshedAt"]
.as_str()
.map(|value| DateTime::parse_from_rfc3339(value).unwrap().to_utc());
@@ -610,7 +610,7 @@ fn xai_profile_override_distinguishes_omission_from_explicit_inheritance() {
}
#[test]
fn generic_profile_overrides_accept_native_providers_and_reject_legacy_conflicts() {
fn profile_overrides_accept_matching_native_values_and_reject_conflicts_and_unknown_providers() {
let profile = json!({"preset":"desktop"});
let xai = json!({"preset":"managed"});
let request: CreateClientKeyRequest = serde_json::from_value(json!({
@@ -676,7 +676,7 @@ fn generic_profile_overrides_accept_native_providers_and_reject_legacy_conflicts
}
#[test]
fn generic_profile_override_clear_rejects_conflicting_legacy_update() {
fn clearing_an_xai_profile_override_conflicts_with_an_explicit_xai_value() {
let request: UpdateClientKeyRequest = serde_json::from_value(json!({
"id":"key_profile",
"name":"profile",
@@ -513,6 +513,12 @@ mod provider {
(Kind::Unsupported, 400, 40001, "该服务商不支持此操作"),
(Kind::BadGateway, 502, 50201, "上游服务请求失败"),
(Kind::Unavailable, 503, 50301, "服务商暂不可用"),
(
Kind::CredentialRefreshRequired,
503,
50301,
"账号凭据需要刷新",
),
(
Kind::Ambiguous,
502,
@@ -1300,6 +1300,17 @@ impl AccountStore for UnusedStore {
Err(unavailable("account quota window usage"))
}
async fn quota_documents(
&self,
_: &gateway_core::account::ProviderAccountId,
_: &gateway_core::routing::ProviderKind,
_: chrono::DateTime<chrono::Utc>,
_: gateway_admin::model::observability::TimeRange,
_: Option<&gateway_admin::model::quota_history::QuotaHistoryCursor>,
) -> AdminStoreResult<gateway_admin::model::quota_history::QuotaDocumentPage> {
unreachable!("测试不读取历史额度文档")
}
async fn load_quota_forecast_history(
&self,
_: &AccountUsageWindowQuery,
@@ -917,7 +917,7 @@ pub(super) fn usage_record_with_account(
}
#[tokio::test]
async fn usage_route_should_forward_name_and_model_contains_filters() {
async fn usage_route_should_forward_record_text_filters() {
use axum::{
body::Body,
http::{Request, StatusCode, header},
@@ -933,7 +933,7 @@ async fn usage_route_should_forward_name_and_model_contains_filters() {
.with_state(fixture.state())
.oneshot(
Request::builder()
.uri("/api/admin/usage/records?model=%20coding%20&clientApiKeyName=%20Key%20%25%20&accountName=%20Account%20Name%20")
.uri("/api/admin/usage/records?model=%20coding%20&clientApiKeyName=%20Key%20%25%20&accountSearch=%20alice%40%20")
.header(header::COOKIE, "cpr_session=valid-session")
.header("x-request-id", "req_usage_other_outcome")
.body(Body::empty())
@@ -947,10 +947,7 @@ async fn usage_route_should_forward_name_and_model_contains_filters() {
let filter = &observations.records.last().expect("usage query").filter;
assert_eq!(filter.client_api_key_name.as_deref(), Some("Key %"));
assert_eq!(filter.model_contains.as_deref(), Some("coding"));
assert_eq!(
filter.provider_account_name.as_deref(),
Some("Account Name")
);
assert_eq!(filter.provider_account_search.as_deref(), Some("alice@"));
assert!(filter.client_api_key_ref.is_none());
assert!(filter.provider_account_ref.is_none());
}
@@ -1729,6 +1726,8 @@ async fn observability_queries_reject_group_filters_and_analytics_search() {
"routingGroupRefs=group-a",
),
("/api/admin/usage/records/summary", "search=request-prefix"),
("/api/admin/usage/records/summary", "errorOrigin=proxy"),
("/api/admin/usage/insights/overview", "errorOrigin=proxy"),
(
"/api/admin/usage/insights/overview",
"search=request-prefix",
@@ -1823,27 +1822,50 @@ pub(super) fn ops_error_record() -> gateway_admin::model::observability::OpsErro
}
#[tokio::test]
async fn usage_status_query_accepts_three_modes_and_rejects_unknown_values() {
async fn usage_record_query_accepts_error_sources_only_for_error_status() {
use crate::admin::{AdminTestFixture, AdminTestState};
use axum::{
body::{Body, to_bytes},
http::{Request, StatusCode, header},
};
use gateway_admin::model::observability::{UsageErrorOrigin, UsageRecordStatus};
use gateway_api::admin::observability;
use tower::ServiceExt as _;
let fixture = AdminTestFixture::new().await;
fixture.auth.insert_session("valid-session");
for (status, expected) in [
("success", StatusCode::OK),
("error", StatusCode::OK),
("all", StatusCode::OK),
("failed", StatusCode::BAD_REQUEST),
for (query, expected) in [
("", Some(UsageRecordStatus::Success)),
("status=success", Some(UsageRecordStatus::Success)),
("status=error", Some(UsageRecordStatus::Error(None))),
("status=all", Some(UsageRecordStatus::All)),
(
"status=error&errorOrigin=proxy",
Some(UsageRecordStatus::Error(Some(UsageErrorOrigin::Proxy))),
),
(
"status=error&errorOrigin=upstream",
Some(UsageRecordStatus::Error(Some(UsageErrorOrigin::Upstream))),
),
(
"status=error&errorOrigin=connection",
Some(UsageRecordStatus::Error(Some(UsageErrorOrigin::Connection))),
),
(
"status=error&errorOrigin=unknown",
Some(UsageRecordStatus::Error(Some(UsageErrorOrigin::Unknown))),
),
("status=failed", None),
("errorOrigin=proxy", None),
("status=success&errorOrigin=proxy", None),
("status=all&errorOrigin=unknown", None),
("status=error&errorOrigin=other", None),
("status=error&errorOrigin=", None),
] {
let response = observability::router::<AdminTestState>()
.with_state(fixture.state())
.oneshot(
Request::builder()
.uri(format!("/api/admin/usage/records?status={status}"))
.uri(format!("/api/admin/usage/records?{query}"))
.header(header::COOKIE, "cpr_session=valid-session")
.header("x-request-id", "usage_status_fixture")
.body(Body::empty())
@@ -1855,17 +1877,15 @@ async fn usage_status_query_accepts_three_modes_and_rejects_unknown_values() {
let body = to_bytes(response.into_body(), 1024 * 1024).await.unwrap();
assert_eq!(
actual,
expected,
"{status}: {}",
if expected.is_some() {
StatusCode::OK
} else {
StatusCode::BAD_REQUEST
},
"{query}: {}",
String::from_utf8_lossy(&body)
);
if expected == StatusCode::OK {
use gateway_admin::model::observability::UsageRecordStatus;
let status_value = match status {
"success" => UsageRecordStatus::Success,
"error" => UsageRecordStatus::Error,
_ => UsageRecordStatus::All,
};
if let Some(status_value) = expected {
assert_eq!(
fixture
.observations
@@ -2062,7 +2082,7 @@ async fn dashboard_relative_time_preserves_server_anchor_boundaries_and_deployme
("Asia/Kathmandu", "2026-06-15 05:45:01"),
("America/New_York", "2026-06-14 20:00:01"),
] {
for (elapsed_ms, expected, legacy) in [
for (elapsed_ms, expected, display) in [
(None, json!(null), "—"),
(
Some(-1_000),
@@ -2177,7 +2197,7 @@ async fn dashboard_relative_time_preserves_server_anchor_boundaries_and_deployme
account["lastUsedRelative"], expected,
"{zone}: {elapsed_ms:?}"
);
assert_eq!(account["lastUsed"], legacy, "{zone}: {elapsed_ms:?}");
assert_eq!(account["lastUsed"], display, "{zone}: {elapsed_ms:?}");
assert_eq!(account["lastUsedAt"], json!(last_used_at));
}
}
@@ -431,7 +431,7 @@ fn settings_request_accepts_unlimited_default_account_concurrency() {
}
#[test]
fn settings_request_validates_cron_and_allows_disabled_empty_schedule() {
fn warmup_cron_is_required_and_may_be_empty_only_when_disabled() {
for (enabled, cron, valid) in [
(false, "", true),
(true, "", false),
@@ -461,10 +461,9 @@ fn settings_request_validates_cron_and_allows_disabled_empty_schedule() {
let request: UpdateRuntimeSettingsRequest = serde_json::from_value(oversized).unwrap();
assert_eq!(request.validate().unwrap_err().field(), "accountWarmupCron");
let mut legacy = update_body();
legacy.as_object_mut().unwrap().remove("accountWarmupCron");
legacy["accountWarmupScheduleTime"] = json!("08:00");
assert!(serde_json::from_value::<UpdateRuntimeSettingsRequest>(legacy).is_err());
let mut missing = update_body();
missing.as_object_mut().unwrap().remove("accountWarmupCron");
assert!(serde_json::from_value::<UpdateRuntimeSettingsRequest>(missing).is_err());
}
#[test]
@@ -705,8 +704,6 @@ async fn admin_auth_should_accept_a_configured_request_id_header_name() {
let fixture = AdminTestFixture::new().await;
fixture.auth.insert_session("valid-session");
// 部署把 api.request_id_header 改名后,注入的 header 不再叫 x-request-id;
// 管理请求仍须拿到请求上下文,而不是退化为 500
let custom = HeaderName::from_static("x-trace-id");
let app = app(fixture.state()).layer(SetRequestIdLayer::new(custom, MakeRequestUuid));
let unlabelled = Request::builder()
@@ -919,7 +916,7 @@ fn global_profile_can_be_omitted_but_cannot_be_cleared() {
}
#[tokio::test]
async fn generic_global_profiles_decode_native_providers_and_reject_legacy_conflicts() {
async fn global_profiles_decode_native_providers_and_reject_conflicting_openai_settings() {
let mut body = update_body();
body["providerRequestProfiles"] = json!({
"openai":{"preset":"desktop"},
@@ -198,7 +198,7 @@ mod response {
response_json(generic).await,
json!({
"code": 42902,
"message": "请求过于频繁,请稍后重试",
"message": "请求过于频繁",
"data": null
})
);
@@ -212,7 +212,7 @@ mod response {
response_json(login).await,
json!({
"code": 42901,
"message": "登录尝试过多,请稍后重试",
"message": "登录尝试过多",
"data": null
})
);
@@ -345,7 +345,7 @@ async fn records_keep_pagination_and_hide_admin_and_upstream_data() {
assert_eq!(data.records.len(), 3);
for (query, status) in data.records.iter().zip([
UsageRecordStatus::Success,
UsageRecordStatus::Error,
UsageRecordStatus::Error(None),
UsageRecordStatus::All,
]) {
assert_eq!(query.status, status);
+60 -13
View File
@@ -228,6 +228,46 @@ fn desktop_headers_should_take_precedence_over_embedded_cli_marker() {
);
}
#[test]
fn desktop_hosted_tui_should_use_core_unless_a_desktop_version_is_supplied() {
for (core, version_header, kind, version) in [
("0.170.0", None, CodexClientKind::Cli, Some("0.170.0")),
(
"0.170.0",
Some("0.170.0"),
CodexClientKind::Cli,
Some("0.170.0"),
),
("invalid", None, CodexClientKind::Cli, None),
(
"0.170.0",
Some("26.1023.51421"),
CodexClientKind::Desktop,
Some("26.1023.51421"),
),
("0.170.0", Some("invalid"), CodexClientKind::Desktop, None),
] {
let mut headers = HeaderMap::new();
headers.insert("originator", HeaderValue::from_static("Codex Desktop"));
headers.insert(
"user-agent",
HeaderValue::from_str(&format!(
"Codex Desktop/{core} (Ubuntu 26.4.0; aarch64) xterm-256color (codex-tui; 0.169.0)"
))
.unwrap(),
);
if let Some(value) = version_header {
headers.insert("version", HeaderValue::from_static(value));
}
let client = identify_codex_client(&headers).unwrap();
assert_eq!(client.kind(), kind);
assert_eq!(
client.version().map(ToString::to_string).as_deref(),
version
);
}
}
#[test]
fn official_core_clients_should_use_the_core_version_instead_of_the_app_suffix() {
for product in [
@@ -322,7 +362,7 @@ fn chatgpt_remote_desktop_without_app_version_should_not_use_a_version_gate() {
}
#[test]
fn chatgpt_remote_marker_should_require_a_complete_exact_client_suffix() {
fn desktop_should_require_a_complete_exact_client_suffix() {
for suffix in [
"(codex_chatgpt_android_remote_extra; dev)",
"(unofficial_codex_chatgpt_ios_remote; dev)",
@@ -340,6 +380,9 @@ fn chatgpt_remote_marker_should_require_a_complete_exact_client_suffix() {
"(Codex Desktop; ) (codex_chatgpt_android_remote; dev)",
"(Codex Desktop; invalid) (codex_chatgpt_ios_remote; dev)",
"(Codex Desktop)",
"(codex-tui-custom; 0.169.0)",
"(codex-tui; 0.169.0) trailing",
"(codex-tui; )",
] {
let mut headers = HeaderMap::new();
headers.insert(
@@ -395,19 +438,23 @@ fn chatgpt_remote_marker_should_not_override_an_existing_desktop_version_suffix(
}
#[test]
fn chatgpt_remote_suffix_created_by_header_truncation_should_not_skip_the_gate() {
let suffix = " (codex_chatgpt_android_remote; dev)";
let mut user_agent = "Codex Desktop/0.154.0-alpha.6.2 ".to_owned();
user_agent.push_str(&"x".repeat(4096 - user_agent.len() - suffix.len()));
user_agent.push_str(suffix);
user_agent.push_str(" (another_client; dev)");
let mut headers = HeaderMap::new();
headers.insert("user-agent", HeaderValue::from_str(&user_agent).unwrap());
fn truncated_client_suffix_should_not_change_the_desktop_gate() {
for suffix in [
" (codex_chatgpt_android_remote; dev)",
" (codex-tui; 0.169.0)",
] {
let mut user_agent = "Codex Desktop/0.154.0-alpha.6.2 ".to_owned();
user_agent.push_str(&"x".repeat(4096 - user_agent.len() - suffix.len()));
user_agent.push_str(suffix);
user_agent.push_str(" (another_client; dev)");
let mut headers = HeaderMap::new();
headers.insert("user-agent", HeaderValue::from_str(&user_agent).unwrap());
let client =
identify_codex_client(&headers).expect("incomplete headers still require a version");
assert_eq!(client.kind(), CodexClientKind::Desktop);
assert!(client.version().is_none());
let client =
identify_codex_client(&headers).expect("incomplete headers still require a version");
assert_eq!(client.kind(), CodexClientKind::Desktop);
assert!(client.version().is_none());
}
}
#[tokio::test]
@@ -743,7 +743,7 @@ async fn request_context_should_resolve_forwarded_precedence_and_peer_fallback()
operation_kind: OperationKind::Generate,
input: Some(json!("hello")),
client_metadata: None,
// 客户端 User-Agent 仅用于本地展示,不再透传给上游指纹上下文
// 客户端 User-Agent 仅用于本地展示
protocol_context: Some(json!({"opaque_request_headers": [
["cf-connecting-ip", STANDARD.encode(b"198.51.100.1")],
["x-real-ip", STANDARD.encode(b"198.51.100.2")],
@@ -1378,27 +1378,40 @@ async fn streaming_error_after_initial_keepalive_should_be_a_terminal_sse_failur
}
#[tokio::test(start_paused = true)]
async fn streaming_late_upstream_error_should_preserve_extended_error_fields() {
async fn streaming_bad_request_preserves_extended_error_fields_before_and_after_keepalive() {
let mut error = json!({
"type": "invalid_request_error", "code": "misalignment_policy_violation",
"message": "synthetic policy error", "misalignment": {"category": "synthetic"},
"extension": {"opaque": true}
});
let failure = ProviderError::new(ProviderErrorKind::InvalidRequest, UpstreamSendState::Sent)
.with_client_visible_upstream_response(
ClientVisibleUpstreamResponse::new(
400,
Some(b"application/json".to_vec()),
Bytes::from(json!({"error": error}).to_string()),
let failure = || {
ProviderError::new(ProviderErrorKind::InvalidRequest, UpstreamSendState::Sent)
.with_client_visible_upstream_response(
ClientVisibleUpstreamResponse::new(
400,
Some(b"application/json".to_vec()),
Bytes::from(json!({"error": error}).to_string()),
)
.with_headers(headers(&[("retry-after", "7")])),
)
.with_headers(headers(&[("retry-after", "7")])),
);
error["headers"] = json!({"retry-after": "7"});
};
let immediate = FakeSession::streaming(
Arc::new(Trace::default()),
vec![NextStep::Error(EngineError::Provider(failure()))],
);
let response = stream_execution_response(Box::new(immediate), None).await;
assert_eq!(response.status(), StatusCode::BAD_REQUEST);
assert_eq!(response.headers()[CONTENT_TYPE], "application/json");
let bytes = to_bytes(response.into_body(), usize::MAX).await.unwrap();
assert_eq!(
serde_json::from_slice::<Value>(&bytes).unwrap(),
json!({"error": error})
);
let session = FakeSession::streaming(
Arc::new(Trace::default()),
vec![NextStep::DelayedError(
Duration::from_secs(30),
EngineError::Provider(failure),
EngineError::Provider(failure()),
)],
);
let response = stream_execution_response(Box::new(session), None).await;
@@ -1410,6 +1423,7 @@ async fn streaming_late_upstream_error_should_preserve_extended_error_fields() {
.find(|event| event.event.as_deref() == Some("response.failed"))
.unwrap();
let payload: Value = serde_json::from_str(&failed.data).unwrap();
error["headers"] = json!({"retry-after": "7"});
assert_eq!(payload["response"]["error"], error);
assert!(bytes.ends_with(b"data: [DONE]\n\n"));
}
@@ -2954,20 +2968,21 @@ struct SessionExecution {
#[tokio::test]
async fn official_core_clients_should_be_version_checked_before_starting_responses() {
let admin = crate::admin::AdminTestFixture::new().await.services;
for product in [
"codex-tui",
"codex_exec",
"codex_vscode",
"codex_sdk_ts",
"codex_python_sdk",
for (product, client) in [
("codex-tui", "codex-tui"),
("codex_exec", "codex_exec"),
("codex_vscode", "codex_vscode"),
("codex_sdk_ts", "codex_sdk_ts"),
("codex_python_sdk", "codex_python_sdk"),
("Codex Desktop", "codex-tui"),
] {
for (version, allowed) in [("0.158.0", false), ("0.162.0", true)] {
for (version, allowed) in [("0.168.0", false), ("0.170.0", true)] {
let trace = Arc::new(Trace::default());
let execution = Arc::new(SessionExecution {
client: authenticated_client_with_min_versions(
"sk_version_test",
None,
Some("0.162.0"),
Some("26.1023.51421"),
Some("0.170.0"),
),
session: Mutex::new(Some(Box::new(FakeSession::streaming(
Arc::clone(&trace),
@@ -2985,7 +3000,7 @@ async fn official_core_clients_should_be_version_checked_before_starting_respons
let request = Request::post("/v1/responses")
.header(AUTHORIZATION, "Bearer sk_version_test")
.header("user-agent", format!(
"{product}/{version} (Mac OS 26.6.2; arm64) Apple_Terminal ({product}; 0.165.0)"
"{product}/{version} (Ubuntu 26.4.0; aarch64) xterm-256color ({client}; 0.169.0)"
))
.body(Body::from(json!({"model": "model-a", "input": "synthetic", "stream": true}).to_string()))
.unwrap();
@@ -3006,8 +3021,9 @@ async fn official_core_clients_should_be_version_checked_before_starting_respons
assert_eq!(status, StatusCode::BAD_REQUEST, "{product}/{version}");
let value: Value = serde_json::from_slice(&body).unwrap();
assert_eq!(value["error"]["code"], "client_version_too_old");
assert_eq!(value["error"]["client"], "codex_cli");
assert_eq!(value["error"]["current_version"], version);
assert_eq!(value["error"]["min_version"], "0.162.0");
assert_eq!(value["error"]["min_version"], "0.170.0");
assert!(execution.session.lock().unwrap().is_some());
}
}
@@ -492,7 +492,7 @@ fn decoder_should_strip_http_transport_but_leave_source_headers_for_provider() {
HeaderValue::from_static(r#"{"scheme":"https"}"#),
);
headers.insert("accept-encoding", HeaderValue::from_static("br, gzip"));
// 正文未压缩;入口现在消费 Content-Encoding,但仍不得向上游透传
// identity 与未压缩的正文匹配,Content-Encoding 由入口消费
headers.insert("content-encoding", HeaderValue::from_static("identity"));
headers.insert("x-openai-future-mode", HeaderValue::from_static("keep"));
@@ -358,7 +358,7 @@ async fn rewrite_upgrade_and_control_active_response_keep_http_context_until_con
);
let (trace, mut socket, server) =
start_active_response_with(Some(frozen), "/custom/websocket", "codex-tui/0.166.0").await;
// 升级后的默认会话仍持有入口上下文;101 正文结束不再提前取消它
// 101 响应完成后,WebSocket 会话继续持有入口上下文
assert!(
!plan
.http_cancellation
@@ -255,7 +255,7 @@ impl Stream for TestSocket {
fn poll_next(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Option<Self::Item>> {
let event = self.incoming.poll_recv(context);
// 模拟 Axum transport 的自动 Pong;pump 不再重复实现协议层应答
// 模拟 Axum 传输层收到 Ping 时自动回复 Pong
if let Poll::Ready(Some(Ok(Message::Ping(payload)))) = &event {
self.written
.send(Message::Pong(payload.clone()))
@@ -45,6 +45,14 @@ impl Drop for TestServer {
async fn connect(
trace: Arc<AtomicFailureTrace>,
response_headers: Vec<ProviderResponseHeader>,
) -> (TestSocket, TestServer) {
connect_with_headers(trace, response_headers, axum::http::HeaderMap::new()).await
}
async fn connect_with_headers(
trace: Arc<AtomicFailureTrace>,
response_headers: Vec<ProviderResponseHeader>,
opening_headers: axum::http::HeaderMap,
) -> (TestSocket, TestServer) {
let execution = Arc::new(AtomicFailureExecution {
client: authenticated_client("sk_ws_atomic"),
@@ -66,6 +74,7 @@ async fn connect(
request
.headers_mut()
.insert(AUTHORIZATION, "Bearer sk_ws_atomic".parse().unwrap());
request.headers_mut().extend(opening_headers);
let (socket, response) = connect_async(request).await.expect("upgrade WebSocket");
assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
(socket, server)
@@ -518,13 +527,32 @@ async fn errors_on_a_reused_connection_keep_their_own_upstream_ids() {
initial_errors: Mutex::new(VecDeque::from(errors)),
..AtomicFailureTrace::default()
});
let (mut socket, _server) = connect(trace, Vec::new()).await;
let mut opening = axum::http::HeaderMap::new();
opening.insert(
"x-codex-turn-state",
axum::http::HeaderValue::from_static("opening"),
);
opening.insert(
"x-codex-turn-metadata",
axum::http::HeaderValue::from_static(r#"{"request_kind":"turn"}"#),
);
let (mut socket, _server) = connect_with_headers(Arc::clone(&trace), Vec::new(), opening).await;
for request_id in ["req_first", "req_second"] {
send_request(&mut socket).await;
let error = next_error(&mut socket).await;
assert_eq!(error["headers"]["x-request-id"], request_id);
assert_eq!(error["headers"]["x-gateway-request-id"], "req_ws_atomic");
}
assert_eq!(
*trace.request_turn_headers.lock().unwrap(),
[
[
Some("opening".to_owned()),
Some(r#"{"request_kind":"turn"}"#.to_owned())
],
[None, None]
]
);
assert_no_duplicate_failure(&mut socket).await;
socket.close(None).await.unwrap();
}
@@ -168,21 +168,31 @@ fn response_create_should_preserve_compaction_trigger_for_openai() {
#[test]
fn response_create_should_prefer_frame_turn_metadata_over_opening_headers() {
let frame = r#"{"request_kind":"turn","tool_namespaces_info":{"workspace":{}}}"#;
let opening = r#"{"request_kind":"compaction"}"#;
let decoded = decode_response_create_with_turn_header(
json!({
"type": "response.create",
"model": "smart-code",
"input": "hello",
"client_metadata": {
"x-codex-turn-metadata": r#"{"request_kind":"turn"}"#
"x-codex-turn-metadata": frame
}
}),
r#"{"request_kind":"compaction"}"#,
opening,
);
let Operation::Generate(request) = decoded.operation() else {
panic!("Responses must map to Generate");
};
assert_eq!(
request.protocol_payload().context()["turn_metadata"],
opening
);
assert_eq!(
request.protocol_payload().body()["client_metadata"]["x-codex-turn-metadata"],
frame
);
let semantics = codex_responses_request_semantics(
request.protocol_payload().body(),
request.protocol_payload().context(),
@@ -308,6 +318,7 @@ struct AtomicFailureTrace {
committed: AtomicBool,
finalized: AtomicBool,
downstream_websocket_connection_ids: Mutex<Vec<String>>,
request_turn_headers: Mutex<Vec<[Option<String>; 2]>>,
initial_errors: Mutex<std::collections::VecDeque<EngineError>>,
first_batch: Mutex<Option<CoordinatedEvent>>,
session_drops: Arc<AtomicUsize>,
@@ -437,6 +448,11 @@ impl ExecutionService for AtomicFailureExecution {
.get("downstream_websocket_connection_id")
.and_then(Value::as_str)
{
let context = generate.protocol_payload().context();
self.trace.request_turn_headers.lock().unwrap().push(
["turn_state", "turn_metadata"]
.map(|key| context.get(key).and_then(Value::as_str).map(str::to_owned)),
);
self.trace
.downstream_websocket_connection_ids
.lock()
@@ -1211,12 +1227,16 @@ fn upgrade_request(authorization: &str) -> Request<Body> {
#[tokio::test]
async fn official_core_version_gate_should_run_before_websocket_upgrade() {
let app = api_router(ModelsExecution::with_cli_min("0.162.0")).await;
let app = api_router(ModelsExecution::with_cli_min("0.170.0")).await;
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
for version in ["0.158.0", "0.162.0"] {
for (product, version) in [
("codex-tui", "0.158.0"),
("Codex Desktop", "0.168.0"),
("Codex Desktop", "0.170.0"),
] {
let mut request = format!("ws://{address}/v1/responses")
.into_client_request()
.unwrap();
@@ -1227,12 +1247,12 @@ async fn official_core_version_gate_should_run_before_websocket_upgrade() {
request.headers_mut().insert(
"user-agent",
HeaderValue::from_str(&format!(
"codex-tui/{version} (Mac OS 26.6.2; arm64) Apple_Terminal (codex-tui; 0.165.0)"
"{product}/{version} (Ubuntu 26.4.0; aarch64) xterm-256color (codex-tui; 0.169.0)"
))
.unwrap(),
);
let result = connect_async(request).await;
if version == "0.162.0" {
if version == "0.170.0" {
let (mut socket, response) = result.expect("current Core upgrades successfully");
assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
socket.close(None).await.unwrap();
@@ -1245,8 +1265,9 @@ async fn official_core_version_gate_should_run_before_websocket_upgrade() {
assert_eq!(response.status(), StatusCode::BAD_REQUEST);
let value: Value = serde_json::from_slice(response.body().as_deref().unwrap()).unwrap();
assert_eq!(value["error"]["code"], "client_version_too_old");
assert_eq!(value["error"]["current_version"], "0.158.0");
assert_eq!(value["error"]["min_version"], "0.162.0");
assert_eq!(value["error"]["client"], "codex_cli");
assert_eq!(value["error"]["current_version"], version);
assert_eq!(value["error"]["min_version"], "0.170.0");
}
}
server.abort();
@@ -37,7 +37,7 @@ use crate::event::{
use crate::lifecycle::{CancellationToken, Deadline, LeaseGuard};
use crate::metering::Decimal;
use crate::operation::{Operation, ProviderSessionState};
use crate::routing::RoutingPlan;
use crate::routing::{ProviderCandidate, RoutingPlan};
use futures::future::{BoxFuture, Fuse};
use futures::{FutureExt, StreamExt, pin_mut, select_biased};
use futures_timer::Delay;
@@ -1239,142 +1239,11 @@ where
}
ProviderBoundary::Result(result) => match *result {
Ok(stream) => stream,
Err(mut error) => {
attempt_trace.record_provider_failure(&error);
if self.continuation_attempt == ContinuationAttempt::RotateForClientReplay
&& error.continuation_recovery_disposition()
== Some(ContinuationRecoveryDisposition::ClientReplayRequired)
&& let Some(original) = self.last_retryable_failure.take()
{
// 迁移只改变客户端恢复指令;失败分类、发送事实与运维正文仍属于原请求
error = original.with_client_recovery_from(error);
self.last_retryable_failure_events.clear();
}
let connection_fallback = self.connection_rotation.is_some()
&& self
.last_retryable_failure
.as_ref()
.and_then(ProviderError::unreachable_proxy)
.is_none()
&& !self.connection_budget.exhausted()
&& !error.retry_is_prohibited()
&& error.send_state() == UpstreamSendState::NotSent
&& matches!(
error.kind(),
ProviderErrorKind::NoEligibleAccount
| ProviderErrorKind::AccountCapacityUnavailable
| ProviderErrorKind::QuotaExhausted
| ProviderErrorKind::ConcurrencyQueueFull
| ProviderErrorKind::ConcurrencyQueueTimeout
);
let continuation_retry = !error.retry_is_prohibited()
&& self.prepare_unavailable_native_continuation_replay(&error);
let candidate_retry = !error.retry_is_prohibited() && !connection_fallback && !continuation_retry
&& matches!(
error.kind(),
ProviderErrorKind::AccountCapacityUnavailable
| ProviderErrorKind::NoEligibleAccount
| ProviderErrorKind::QuotaExhausted
| ProviderErrorKind::ProviderInfrastructureUnavailable
| ProviderErrorKind::ConcurrencyQueueFull
| ProviderErrorKind::ConcurrencyQueueTimeout
)
&& error.send_state() == UpstreamSendState::NotSent
&& self.current_send_state() == UpstreamSendState::NotSent
&& matches!(
self.continuation_attempt,
ContinuationAttempt::None | ContinuationAttempt::ReplayAny
)
// 跨 Provider 候选推进必然换号(账号行按 Provider 隔离),
// 预算耗尽后不再推进,交回容量类失败的原有终态语义。
&& self.has_account_rotation_budget()
&& self.advance_provider_candidate();
let retryable = self
.apply_retry_policy(super::policy::RetryFacts {
attempt_index: next_attempt,
provider: candidate.provider().clone(),
model: candidate
.upstream_model()
.map(|model| model.as_str().to_owned()),
error_kind: error.kind(),
upstream_status: error.upstream_status(),
send_state: error.send_state(),
remaining_routing_attempts: self
.plan
.max_attempts()
.get()
.saturating_sub(self.routing_attempts),
remaining_deadline: Duration::ZERO,
retry_allowed: connection_fallback
|| continuation_retry
|| candidate_retry,
})
.await?;
attempt_trace.record("retry.decided", json!({
"phase": "prepare", "retryable": retryable,
"continuationRetry": continuation_retry, "candidateRetry": candidate_retry,
"connectionFallback": connection_fallback,
"retryProhibited": error.retry_is_prohibited(),
"sendState": error.send_state().as_str(),
"requestSendState": self.current_send_state().as_str(),
"continuation": format!("{:?}", self.continuation_attempt),
"accountRotations": self.account_rotations,
"maxAccountRotations": self.plan.account_selection_policy().max_account_rotations(),
"remainingRoutingAttempts": self.plan.max_attempts().get().saturating_sub(self.routing_attempts),
}));
if retryable {
if connection_fallback {
let recovery = self
.connection_rotation
.take()
.expect("pending connection rotation");
self.excluded_accounts.remove(&recovery.account);
self.pending_retry = Some(recovery);
} else if candidate_retry {
// 原账号只属于原 Provider,跨候选后不能拿旧钉选作恢复兜底
self.connection_rotation = None;
}
return Ok(Some(PullOutcome::AttemptDiscarded));
}
if matches!(
error.kind(),
ProviderErrorKind::AccountCapacityUnavailable
| ProviderErrorKind::NoEligibleAccount
| ProviderErrorKind::SessionPolicyRestricted
| ProviderErrorKind::QuotaExhausted
| ProviderErrorKind::ConcurrencyQueueFull
| ProviderErrorKind::ConcurrencyQueueTimeout
) && let Some(last_failure) = self.last_retryable_failure.take()
{
let send_state = self.current_send_state();
let mut events = std::mem::take(&mut self.last_retryable_failure_events);
if !events.is_empty() {
self.observe_atomic_terminal_events(&mut events);
self.budget_attempt_already_counted = true;
return Ok(Some(PullOutcome::TerminalFailure {
events,
error: last_failure,
send_state,
}));
}
self.finish_provider_error(&last_failure).await?;
return Err(provider_engine_error(last_failure));
}
if !(matches!(
error.kind(),
ProviderErrorKind::AccountCapacityUnavailable
| ProviderErrorKind::NoEligibleAccount
| ProviderErrorKind::SessionPolicyRestricted
| ProviderErrorKind::QuotaExhausted
| ProviderErrorKind::ProviderInfrastructureUnavailable
| ProviderErrorKind::ConcurrencyQueueFull
| ProviderErrorKind::ConcurrencyQueueTimeout
) && error.send_state() == UpstreamSendState::NotSent)
{
self.record_provider_failure(candidate.provider().clone());
}
self.finish_provider_error(&error).await?;
return Err(provider_engine_error(error));
Err(error) => {
return self
.handle_prepare_failure(error, &candidate, next_attempt, &attempt_trace)
.await
.map(Some);
}
},
};
@@ -1560,6 +1429,131 @@ where
Ok(None)
}
async fn handle_prepare_failure(
&mut self,
mut error: ProviderError,
candidate: &ProviderCandidate,
next_attempt: NonZeroU32,
attempt_trace: &TraceContext,
) -> Result<PullOutcome, EngineError> {
attempt_trace.record_provider_failure(&error);
if self.continuation_attempt == ContinuationAttempt::RotateForClientReplay
&& error.continuation_recovery_disposition()
== Some(ContinuationRecoveryDisposition::ClientReplayRequired)
&& let Some(original) = self.last_retryable_failure.take()
{
// 迁移只改变客户端恢复指令;失败分类、发送事实与运维正文仍属于原请求
error = original.with_client_recovery_from(error);
self.last_retryable_failure_events.clear();
}
let kind = error.kind();
let account_unavailable = matches!(
kind,
ProviderErrorKind::NoEligibleAccount
| ProviderErrorKind::AccountCapacityUnavailable
| ProviderErrorKind::QuotaExhausted
| ProviderErrorKind::ConcurrencyQueueFull
| ProviderErrorKind::ConcurrencyQueueTimeout
);
let infrastructure_unavailable =
kind == ProviderErrorKind::ProviderInfrastructureUnavailable;
let selection_failed =
account_unavailable || kind == ProviderErrorKind::SessionPolicyRestricted;
let not_sent = error.send_state() == UpstreamSendState::NotSent;
let retry_allowed = !error.retry_is_prohibited();
let connection_fallback = self.connection_rotation.is_some()
&& self
.last_retryable_failure
.as_ref()
.and_then(ProviderError::unreachable_proxy)
.is_none()
&& !self.connection_budget.exhausted()
&& retry_allowed
&& not_sent
&& account_unavailable;
let continuation_retry =
retry_allowed && self.prepare_unavailable_native_continuation_replay(&error);
let candidate_retry = retry_allowed
&& !connection_fallback
&& !continuation_retry
&& (account_unavailable || infrastructure_unavailable)
&& not_sent
&& self.current_send_state() == UpstreamSendState::NotSent
&& matches!(
self.continuation_attempt,
ContinuationAttempt::None | ContinuationAttempt::ReplayAny
)
// 跨 Provider 候选推进必然换号(账号行按 Provider 隔离),
// 预算耗尽后不再推进,交回容量类失败的原有终态语义
&& self.has_account_rotation_budget()
&& self.advance_provider_candidate();
let retryable = self
.apply_retry_policy(super::policy::RetryFacts {
attempt_index: next_attempt,
provider: candidate.provider().clone(),
model: candidate
.upstream_model()
.map(|model| model.as_str().to_owned()),
error_kind: kind,
upstream_status: error.upstream_status(),
send_state: error.send_state(),
remaining_routing_attempts: self
.plan
.max_attempts()
.get()
.saturating_sub(self.routing_attempts),
remaining_deadline: Duration::ZERO,
retry_allowed: connection_fallback || continuation_retry || candidate_retry,
})
.await?;
attempt_trace.record("retry.decided", json!({
"phase": "prepare", "retryable": retryable,
"continuationRetry": continuation_retry, "candidateRetry": candidate_retry,
"connectionFallback": connection_fallback,
"retryProhibited": error.retry_is_prohibited(),
"sendState": error.send_state().as_str(),
"requestSendState": self.current_send_state().as_str(),
"continuation": format!("{:?}", self.continuation_attempt),
"accountRotations": self.account_rotations,
"maxAccountRotations": self.plan.account_selection_policy().max_account_rotations(),
"remainingRoutingAttempts": self.plan.max_attempts().get().saturating_sub(self.routing_attempts),
}));
if retryable {
if connection_fallback {
let recovery = self
.connection_rotation
.take()
.expect("pending connection rotation");
self.excluded_accounts.remove(&recovery.account);
self.pending_retry = Some(recovery);
} else if candidate_retry {
// 原账号只属于原 Provider,跨候选后不能拿旧钉选作恢复兜底
self.connection_rotation = None;
}
return Ok(PullOutcome::AttemptDiscarded);
}
if selection_failed && let Some(last_failure) = self.last_retryable_failure.take() {
let send_state = self.current_send_state();
let mut events = std::mem::take(&mut self.last_retryable_failure_events);
if !events.is_empty() {
self.observe_atomic_terminal_events(&mut events);
self.budget_attempt_already_counted = true;
return Ok(PullOutcome::TerminalFailure {
events,
error: last_failure,
send_state,
});
}
self.finish_provider_error(&last_failure).await?;
return Err(provider_engine_error(last_failure));
}
if !(not_sent && (selection_failed || infrastructure_unavailable)) {
self.record_provider_failure(candidate.provider().clone());
}
self.finish_provider_error(&error).await?;
Err(provider_engine_error(error))
}
fn advance_provider_candidate(&mut self) -> bool {
let Some(next) = self.candidate_index.checked_add(1) else {
return false;
@@ -1947,7 +1941,7 @@ where
let store = Arc::clone(self.engine.store());
let request_id = self.request_id.clone();
let persisted = self.request_persisted;
// 错误、账号 lease 与决策 future 都跨 next_event 的取消保留
// 错误、尝试记录与决策 future 都跨 next_event 的取消保留
// 在持久化及策略回调完成前,不能再次拉流或建立新的 attempt
self.current = Some(current);
self.pending_stream_failure = Some(PendingStreamFailure {
@@ -2063,7 +2057,11 @@ where
.pending_terminal_failure
.as_ref()
.ok_or(EngineError::NoActiveAttempt)?;
if pending.events.is_empty() {
// 在保活提交前冻结 HTTP 错误,否则必须交付原流内事件
if pending.events.is_empty()
|| (pending.error.client_visible_upstream_response().is_some()
&& self.response_commit.finish())
{
return Err(provider_engine_error(
self.finalize_pending_terminal_failure().await?,
));
@@ -2440,6 +2438,9 @@ where
}
async fn finish_interruption(&mut self, error: &EngineError) -> Result<(), EngineError> {
if let Some(current) = self.current.as_mut() {
current.stream.abort();
}
// 结算 I/O 可能继续等待,先冻结交付事实以保持终态与实际 HTTP 状态一致
self.response_commit.finish();
let (outcome, gateway_error) = match error {
@@ -42,9 +42,12 @@ impl ResponseCommit {
self.committed_at().is_some()
}
pub(crate) fn finish(&self) {
// 执行已结束且未提交时保留原 HTTP 错误,不能因外层插件迟迟返回再改成 200
let _ = self.first.set(TransportState::Finished);
/// 冻结交付状态,返回是否仍可发送独立的 HTTP 错误响应
pub(crate) fn finish(&self) -> bool {
matches!(
self.first.get_or_init(|| TransportState::Finished),
TransportState::Finished
)
}
#[must_use]
+14 -1
View File
@@ -643,6 +643,11 @@ impl AttemptContext {
self.request.client_transport
}
#[must_use]
pub fn endpoint(&self) -> &str {
self.request.endpoint()
}
/// 原生响应可交付可替换前导事件;中间件可能改变其输出语义
#[must_use]
pub fn allows_replayable_prelude(&self) -> bool {
@@ -982,11 +987,19 @@ impl AttemptContext {
model: Option<&str>,
candidates: &'a [AccountCandidate],
context: &mut AccountSelectionContext,
ownership: policy::AccountScheduleOwnership<'_>,
) -> Result<Option<AccountSelection<'a>>, policy::AccountPolicyError> {
match self.request.request_policy() {
Some(policy) => {
policy
.select_account(self.attempt_index, provider, model, candidates, context)
.select_account(
self.attempt_index,
provider,
model,
candidates,
context,
ownership,
)
.await
}
None => Ok(crate::account::AccountSelector.select(candidates, context)),
@@ -115,10 +115,29 @@ pub enum ModelRouteDecision {
Reject,
}
/// Provider 在本轮选号中已解析的归属,仅用于向插件投影候选关系
#[derive(Debug, Default, Clone, Copy)]
pub struct AccountScheduleOwnership<'a> {
pub bound_account: Option<&'a ProviderAccountId>,
pub follow_only: bool,
pub pinned_account: Option<&'a ProviderAccountId>,
}
/// 本轮内置选号如何对待这个候选;显式选号仍受宿主资格和固定归属约束
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AccountScheduleRole {
Ordinary,
Preferred,
FollowOnly,
Pinned,
}
/// 账号调度插件可见的单个候选事实,不包含凭据或账号资料
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AccountScheduleCandidate {
account_id: ProviderAccountId,
session_bound: bool,
role: AccountScheduleRole,
available: bool,
weight: u16,
in_flight: u32,
@@ -131,6 +150,16 @@ pub struct AccountScheduleCandidate {
}
impl AccountScheduleCandidate {
#[must_use]
pub const fn session_bound(&self) -> bool {
self.session_bound
}
#[must_use]
pub const fn role(&self) -> AccountScheduleRole {
self.role
}
#[must_use]
pub const fn available(&self) -> bool {
self.available
@@ -469,6 +498,7 @@ impl RequestPolicyContext {
model: Option<&str>,
candidates: &'a [AccountCandidate],
context: &mut AccountSelectionContext,
ownership: AccountScheduleOwnership<'_>,
) -> Result<Option<AccountSelection<'a>>, AccountPolicyError> {
let eligible = AccountSelector.policy_candidates(candidates, context);
if eligible.is_empty() {
@@ -476,19 +506,33 @@ impl RequestPolicyContext {
}
let projected = eligible
.iter()
.map(|candidate| AccountScheduleCandidate {
account_id: candidate.account.id().clone(),
available: AccountSelector
.scheduling_blocker(candidate, context)
.is_none(),
weight: candidate.account.weight().get(),
in_flight: candidate.signals.in_flight,
maximum_concurrency: context.concurrency_limit(candidate).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,
.map(|candidate| {
let id = Some(candidate.account.id());
let session_bound = ownership.bound_account == id;
AccountScheduleCandidate {
session_bound,
role: if ownership.pinned_account == id {
AccountScheduleRole::Pinned
} else if session_bound && ownership.follow_only {
AccountScheduleRole::FollowOnly
} else if context.preferred_account.as_ref() == id {
AccountScheduleRole::Preferred
} else {
AccountScheduleRole::Ordinary
},
account_id: candidate.account.id().clone(),
available: AccountSelector
.scheduling_blocker(candidate, context)
.is_none(),
weight: candidate.account.weight().get(),
in_flight: candidate.signals.in_flight,
maximum_concurrency: context.concurrency_limit(candidate).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
@@ -250,8 +250,7 @@ const MAX_NATIVE_RESPONSE_EVENTS_PER_INPUT: usize = 64;
/// 这样 Coordinator 可以先持久化 attempt,再越过发送屏障
pub struct ProviderStream {
metadata: ProviderCallMetadata,
events: EventStream,
_lease: Box<dyn ResourceLease>,
source: Option<ProviderStreamSource>,
native_response_translator: Option<Box<dyn NativeResponseTranslator>>,
account_feedback: Option<ProviderStreamAccountFeedback>,
account_protection: Option<super::account_protection::AttemptProtection>,
@@ -259,7 +258,12 @@ pub struct ProviderStream {
Option<futures::future::BoxFuture<'static, Option<Result<ProviderEvent, ProviderError>>>>,
validator: Result<EventSequenceValidator, EventSequenceError>,
strict_canonical_seen: bool,
terminated: bool,
}
// 事件流内部也可能持有同一租约,结束读取时须一并丢弃
struct ProviderStreamSource {
events: EventStream,
_lease: Box<dyn ResourceLease>,
}
struct ProviderStreamAccountFeedback {
@@ -360,18 +364,25 @@ impl ProviderStream {
{
Self {
metadata,
events: Box::pin(events),
_lease: Box::new(lease),
source: Some(ProviderStreamSource {
events: Box::pin(events),
_lease: Box::new(lease),
}),
native_response_translator: None,
account_feedback: None,
account_protection: None,
protection_feedback: None,
validator: Ok(EventSequenceValidator::new()),
strict_canonical_seen: false,
terminated: false,
}
}
pub(super) fn abort(&mut self) {
self.source.take();
self.account_protection.take();
self.protection_feedback.take();
}
/// 在第一次发送前捕获反馈栅栏,诊断调用由协调器排除
#[must_use]
pub async fn with_account_error_protection(
@@ -425,6 +436,15 @@ impl ProviderStream {
/// source/target 格式不一致、单事件展开越界、终态被丢弃或 Provider 转换失败时
/// 返回错误
pub fn translate_native_response(
&mut self,
event: ProviderEvent,
terminal: bool,
) -> Result<Vec<ProviderEvent>, ProviderError> {
self.translate_event(event, terminal)
.inspect_err(|_| self.abort())
}
fn translate_event(
&mut self,
mut event: ProviderEvent,
terminal: bool,
@@ -979,8 +999,12 @@ impl Stream for ProviderStream {
};
}
let result = this.poll_event(context);
let upstream_finished = matches!(&result, Poll::Ready(Some(Err(_)) | None));
if upstream_finished {
this.source.take();
}
// 客户端可在成功终态后停止拉取,不能依赖之后的 EOF 才清除保护证据
let protection_terminal = matches!(&result, Poll::Ready(Some(Err(_)) | None))
let protection_terminal = upstream_finished
|| (matches!(&result, Poll::Ready(Some(Ok(_))))
&& this
.account_protection
@@ -1003,14 +1027,14 @@ impl ProviderStream {
context: &mut Context<'_>,
) -> Poll<Option<Result<ProviderEvent, ProviderError>>> {
let this = self;
if this.terminated {
let Some(source) = this.source.as_mut() else {
return Poll::Ready(None);
}
};
if let Some(feedback) = this.account_feedback.as_mut() {
feedback.start();
}
match this.events.as_mut().poll_next(context) {
match source.events.as_mut().poll_next(context) {
Poll::Pending => Poll::Pending,
Poll::Ready(Some(Ok(event))) => {
// 纯 wire 流的 facts 仍只是旁路观测;一旦交付 canonical-only
@@ -1025,7 +1049,6 @@ impl ProviderStream {
}
}
if this.strict_canonical_seen && this.validator.is_err() {
this.terminated = true;
let error =
ProviderError::new(ProviderErrorKind::Protocol, UpstreamSendState::Sent);
if let Some(feedback) = this.account_feedback.as_mut() {
@@ -1042,14 +1065,12 @@ impl ProviderStream {
Poll::Ready(Some(Ok(event)))
}
Poll::Ready(Some(Err(error))) => {
this.terminated = true;
if let Some(feedback) = this.account_feedback.as_mut() {
feedback.report_failure(&error);
}
Poll::Ready(Some(Err(error)))
}
Poll::Ready(None) => {
this.terminated = true;
let validation = if this.strict_canonical_seen {
this.validator
.as_ref()
+3 -3
View File
@@ -425,7 +425,7 @@ impl ProviderConnectionObservation {
/// 只供当前客户端请求使用的 HTTP 失败响应
///
/// 通常保留原始上游响应;Provider 也可为明确的恢复流程准备客户端投影
/// Provider 可透传上游 HTTP 响应,也可按客户端协议构造错误正文
/// 投影不能覆盖 [`ProviderError`] 中用于诊断和记账的真实上游事实
///
/// 该值不属于稳定诊断事实,不能进入日志或持久化
@@ -833,7 +833,7 @@ impl ProviderError {
self
}
/// 附加仅可返回给当前请求方的原始上游 HTTP 失败响应
/// 附加仅可返回给当前请求方的 HTTP 失败响应
#[must_use]
pub fn with_client_visible_upstream_response(
mut self,
@@ -1018,7 +1018,7 @@ impl ProviderError {
self.client_visible_upstream_error.as_deref()
}
/// 返回只供当前协议响应使用的原始上游 HTTP 失败响应
/// 返回仅供当前请求方使用的 HTTP 失败响应
#[must_use]
pub fn client_visible_upstream_response(&self) -> Option<&ClientVisibleUpstreamResponse> {
self.client_visible_upstream_response.as_deref()
@@ -143,10 +143,10 @@ fn zero_or_absent_window_weights_disable_reset_scores_and_tolerance() {
}]
.into(),
);
let legacy = json!({"loadWeight":0,"quotaWeight":0,"healthWeight":0,"latencyWeight":0,"resetWeight":10,"queueWeight":0});
let mut disabled = legacy.clone();
let omitted = json!({"loadWeight":0,"quotaWeight":0,"healthWeight":0,"latencyWeight":0,"resetWeight":10,"queueWeight":0});
let mut disabled = omitted.clone();
disabled["resetWindowWeights"] = json!({"fiveHour":0,"weekly":0,"monthly":0});
for wire in [legacy, disabled] {
for wire in [omitted, disabled] {
let config: SmartSchedulingConfig = serde_json::from_value(wire).unwrap();
context.policy = context.policy.with_smart_scheduling(config);
let trace = gateway_core::diagnostics::TraceContext::new("req_zero_windows");
@@ -299,14 +299,17 @@ fn complete_success_is_reported_once_but_unfinished_drop_is_not_success() {
Ok(gateway_core::event::GatewayEvent::Started(response.clone()).into()),
Ok(gateway_core::event::GatewayEvent::Completed(response).into()),
]);
let mut completed = ProviderStream::new(metadata(), events, ())
let released = Arc::new(AtomicUsize::new(0));
let mut completed = ProviderStream::new(metadata(), events, Lease(released.clone()))
.with_account_error_protection(store.clone(), Arc::new(policy().compile()), 5)
.await;
assert!(completed.next().await.unwrap().is_ok());
assert_eq!(store.successes.load(Ordering::SeqCst), 0);
assert!(completed.next().await.unwrap().is_ok());
assert_eq!(store.successes.load(Ordering::SeqCst), 1);
assert_eq!(released.load(Ordering::SeqCst), 0);
assert!(completed.next().await.is_none());
assert_eq!(released.load(Ordering::SeqCst), 1);
assert!(completed.next().await.is_none());
assert_eq!(store.successes.load(Ordering::SeqCst), 1);
});
@@ -351,27 +354,27 @@ fn stalled_begin_and_feedback_are_bounded_and_preserve_original_failure() {
}
#[test]
fn cancelling_pending_feedback_releases_lease_and_does_not_report_success() {
fn failed_stream_releases_lease_while_protection_feedback_is_pending() {
futures::executor::block_on(async {
let store = Arc::new(Feedback {
stalled_feedback: true,
..Feedback::default()
});
let released = Arc::new(AtomicUsize::new(0));
let mut stream = ProviderStream::new(
metadata(),
stream::iter([Err(failure("invalid_prompt"))]),
Lease(released.clone()),
)
.with_account_error_protection(store.clone(), Arc::new(policy().compile()), 5)
.await;
let lease = Arc::new(Lease(released.clone()));
let events = stream::unfold(Arc::clone(&lease), |lease| async move {
Some((Err(failure("invalid_prompt")), lease))
});
let mut stream = ProviderStream::new(metadata(), events, lease)
.with_account_error_protection(store.clone(), Arc::new(policy().compile()), 5)
.await;
assert!(
timeout(Duration::from_millis(10), stream.next())
.await
.is_err()
);
drop(stream);
assert_eq!(released.load(Ordering::SeqCst), 1);
drop(stream);
assert_eq!(store.successes.load(Ordering::SeqCst), 0);
});
}
@@ -898,7 +898,7 @@ impl Provider for ScriptedProvider {
futures::stream::iter(items.into_iter().map(canonical_provider_event))
.chain(futures::stream::pending()),
),
(),
TrackedLease(Arc::clone(&self.released_leases)),
))
}
Script::ObservedStream { account_id, items } => {
@@ -3402,7 +3402,16 @@ fn recovered_credential_retries_the_same_account_exactly_once() {
CancellationToken::new(),
))
.expect("start execution");
block_on(session.collect_uncommitted()).expect("recovered account succeeds");
let (release, gate) = oneshot::channel();
*store.intermediate_gate.lock().unwrap() = Some(gate);
block_on(async {
let mut collect = Box::pin(session.collect_uncommitted());
assert!(futures::poll!(collect.as_mut()).is_pending());
assert_eq!(provider.contexts.lock().unwrap().len(), 1);
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 1);
release.send(()).unwrap();
collect.await.expect("recovered account succeeds");
});
block_on(session.commit_downstream(Some(200))).expect("commit response");
let contexts = provider.contexts.lock().expect("contexts lock");
@@ -5408,7 +5417,7 @@ fn delivered_prelude_allows_retry_without_control_until_non_replayable_delivery(
fn cancellation_before_pending_delivery_commit_reaches_terminal_state() {
let operation = generate_operation();
let route_plan = plan(&operation);
let (coordinator, store, _) = coordinator(vec![Script::Stream {
let (coordinator, store, provider) = coordinator(vec![Script::Stream {
account_id: "acct_first",
items: complete_stream(None),
}]);
@@ -5429,7 +5438,15 @@ fn cancellation_before_pending_delivery_commit_reaches_terminal_state() {
CommitRequirement::CommitBeforeDelivery
);
block_on(session.cancel_and_finalize()).expect("cancel finalization");
let (release, gate) = oneshot::channel();
*store.send_gate.lock().unwrap() = Some(gate);
block_on(async {
let mut cancel = Box::pin(session.cancel_and_finalize());
assert!(futures::poll!(cancel.as_mut()).is_pending());
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 1);
release.send(()).unwrap();
cancel.await.expect("cancel finalization");
});
assert!(session.is_finalized());
let state = store.state.lock().expect("store lock");
@@ -5946,7 +5963,7 @@ fn interrupted_stream_failure_preserves_the_original_attempt_and_retry_decision(
let mut resumed = Box::pin(session.next_event());
assert!(futures::poll!(resumed.as_mut()).is_pending());
assert_eq!(provider.contexts.lock().unwrap().len(), 1);
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 0);
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 1);
release
.send(())
.expect("the original write still owns its receiver");
@@ -6144,6 +6161,7 @@ fn charged_terminal_write_resumes_without_replacing_success_failure_or_send_fact
assert!(futures::poll!(collect.as_mut()).is_pending());
} else {
session.collect_uncommitted().await.unwrap();
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 1);
let mut commit = Box::pin(session.commit_downstream(Some(200)));
assert!(futures::poll!(commit.as_mut()).is_pending());
}
@@ -6187,7 +6205,7 @@ fn charged_terminal_write_resumes_without_replacing_success_failure_or_send_fact
fn deadline_after_commit_is_persisted_as_incomplete() {
let operation = generate_operation();
let route_plan = plan(&operation);
let (coordinator, store, _) = coordinator(vec![Script::HangingStream {
let (coordinator, store, provider) = coordinator(vec![Script::HangingStream {
account_id: "acct_first",
items: vec![Ok(GatewayEvent::Started(ResponseMeta::new(
"response-1",
@@ -6215,6 +6233,7 @@ fn deadline_after_commit_is_persisted_as_incomplete() {
let error = block_on(session.next_event()).expect_err("deadline elapses mid-stream");
assert!(matches!(error, EngineError::Deadline));
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 1);
let state = store.state.lock().expect("store lock");
assert_eq!(state.finalizations[0].outcome, ExecutionOutcome::Incomplete);
assert!(state.finalizations[0].committed);
@@ -6491,8 +6510,6 @@ fn connection_recovery_rotates_only_after_retrying_the_first_account() {
assert_eq!(context.transport(), AttemptTransport::Fallback);
}
assert_eq!(store.state.lock().unwrap().intermediate_failures, 2);
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 2);
drop(session);
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 3);
}
@@ -6556,8 +6573,6 @@ fn connection_recovery_keeps_one_account_and_http_transport_until_success() {
let state = store.state.lock().unwrap();
assert_eq!(state.intermediate_failures, 3);
assert_eq!(state.finalizations[0].outcome, ExecutionOutcome::Succeeded);
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 3);
drop(session);
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 4);
},
)));
@@ -6654,8 +6669,6 @@ fn connection_recovery_does_not_delay_existing_account_rotation() {
let state = store.state.lock().unwrap();
assert_eq!(state.intermediate_failures, 2);
assert_eq!(state.finalizations[0].outcome, ExecutionOutcome::Succeeded);
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 2);
drop(session);
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 3);
}
@@ -6749,8 +6762,6 @@ fn connection_recovery_exhaustion_preserves_transport_failure() {
store.state.lock().unwrap().finalizations[0].attempt_count,
4
);
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 3);
drop(session);
assert_eq!(provider.released_leases.load(Ordering::SeqCst), 4);
}
@@ -7425,6 +7436,80 @@ fn transport_keepalive_preserves_pre_output_recovery_and_first_business_commit()
assert!(state.finalizations[0].committed);
}
#[test]
fn atomic_http_failure_uses_wire_only_after_downstream_data_or_keepalive() {
for (prelude, keepalive) in [(false, false), (true, false), (false, true)] {
let operation = generate_operation();
let route_plan = plan(&operation);
let detail = json!({"code":"invalid_value", "message":"Invalid input."});
let wire = json!({"type":"error","status":400,"error":detail});
let mut items = Vec::new();
if prelude {
items.push(Ok(ProviderEvent::canonical(GatewayEvent::Started(
ResponseMeta::new("response-1", "gpt-5"),
))
.with_replayable_prelude()));
}
items.push(Err(ProviderError::new(
ProviderErrorKind::InvalidRequest,
UpstreamSendState::Sent,
)
.with_status(400)
.with_client_visible_upstream_response(ClientVisibleUpstreamResponse::new(
400,
Some(b"application/json".to_vec()),
Bytes::from(json!({"error":detail}).to_string()),
))
.with_atomic_client_events(vec![ProviderEvent::wire(
ProtocolWireEvent::json("openai", Some("error".into()), wire.clone()).unwrap(),
)])));
let (coordinator, store, _) = coordinator(vec![Script::ObservedStream {
account_id: "acct_first",
items,
}]);
let mut session = block_on(coordinator.start(
model_request(&operation, SystemTime::now() + Duration::from_secs(30)),
operation,
route_plan,
None,
None,
CancellationToken::new(),
))
.unwrap();
let transport = session.response_commit();
if prelude {
block_on(session.next_event()).unwrap().unwrap();
block_on(session.commit_downstream(Some(200))).unwrap();
}
if keepalive {
assert!(transport.record(Some(200)));
}
if prelude || keepalive {
let batch = block_on(session.next_event()).unwrap().unwrap();
let events = batch.into_provider_events();
assert_eq!(events.len(), 1);
assert_eq!(events[0].wire_event().unwrap().data(), &wire);
if keepalive {
block_on(session.commit_downstream(Some(200))).unwrap();
}
}
let EngineError::Provider(error) = block_on(session.next_event()).unwrap_err() else {
panic!("expected the upstream bad request");
};
assert_eq!(
error.client_visible_upstream_response().unwrap().status(),
400
);
assert!(session.is_finalized());
assert_eq!(transport.record(Some(200)), prelude || keepalive);
let state = store.state.lock().unwrap();
assert_eq!(state.attempts.len(), 1);
assert_eq!(state.finalizations.len(), 1);
assert_eq!(state.finalizations[0].committed, prelude || keepalive);
assert_eq!(state.finalizations[0].upstream_status_code, Some(400));
}
}
#[test]
fn transport_keepalive_records_late_failure_as_incomplete_http_200() {
let operation = generate_operation();
@@ -1955,6 +1955,7 @@ impl NativeResponseTranslator for FailingNativeResponseTranslator {
struct FailingNativeResponseProvider {
calls: Arc<AtomicUsize>,
lease: Arc<()>,
}
#[async_trait]
@@ -2010,7 +2011,7 @@ impl Provider for FailingNativeResponseProvider {
GatewayEvent::Completed(response),
)),
]),
(),
Arc::clone(&self.lease),
)
.with_native_response_translator(FailingNativeResponseTranslator::default()))
}
@@ -2020,8 +2021,10 @@ impl Provider for FailingNativeResponseProvider {
fn native_response_failure_after_downstream_commit_is_not_replayed() {
block_on(async {
let calls = Arc::new(AtomicUsize::new(0));
let lease = Arc::new(());
let provider_index = ProviderRegistry::new([Arc::new(FailingNativeResponseProvider {
calls: Arc::clone(&calls),
lease: Arc::clone(&lease),
}) as Arc<dyn Provider>])
.unwrap();
let generation = super::extensions::reference("native-response-failure");
@@ -2054,6 +2057,7 @@ fn native_response_failure_after_downstream_commit_is_not_replayed() {
}));
started.session.commit_downstream(Some(200)).await.unwrap();
let active_refs = Arc::strong_count(&lease);
let error = started.session.next_event().await.unwrap_err();
assert!(matches!(
error,
@@ -2061,6 +2065,7 @@ fn native_response_failure_after_downstream_commit_is_not_replayed() {
if error.kind() == ProviderErrorKind::Protocol
&& error.send_state() == UpstreamSendState::Sent
));
assert_eq!(Arc::strong_count(&lease), active_refs - 1);
assert_eq!(calls.load(Ordering::SeqCst), 1);
started.session.detach_finalize().await;
});
@@ -2352,6 +2357,7 @@ impl Provider for PolicySelectingProvider {
.map(UpstreamModelId::as_str),
&candidates,
&mut selection,
Default::default(),
)
.await
{
@@ -131,6 +131,7 @@ fn scheduler_can_override_soft_affinity_and_reports_the_override() {
Some("demo-model"),
&candidates,
&mut context(),
Default::default(),
)
.await
.unwrap()
@@ -156,6 +157,7 @@ fn delegated_scheduler_keeps_builtin_affinity() {
None,
&candidates,
&mut context(),
Default::default(),
)
.await
.unwrap()
@@ -195,6 +197,7 @@ fn explicit_plugin_choices_override_native_soft_affinity() {
None,
&candidates,
&mut selection_context,
Default::default(),
)
.await
.unwrap()
@@ -226,6 +229,7 @@ fn scheduler_cannot_select_outside_the_hard_bound_candidate_pool() {
None,
&candidates,
&mut context,
Default::default(),
)
.await;
assert!(matches!(result, Err(AccountPolicyError::Fault)));
@@ -257,6 +261,7 @@ fn filtered_delegation_preserves_native_weights_and_affinity_on_remaining_accoun
None,
&candidates,
&mut context,
Default::default(),
)
.await
.unwrap()
@@ -298,7 +303,8 @@ fn filtered_delegation_covers_busy_candidates_and_does_not_persist_between_selec
&ProviderKind::new("openai").unwrap(),
None,
&candidates,
&mut selection
&mut selection,
Default::default(),
)
.await
.unwrap()
@@ -316,6 +322,7 @@ fn filtered_delegation_covers_busy_candidates_and_does_not_persist_between_selec
None,
&candidates,
&mut context(),
Default::default(),
)
.await
.unwrap()
@@ -344,6 +351,7 @@ fn filtering_all_candidates_is_terminal_even_when_the_only_candidate_is_busy_or_
None,
&candidates,
&mut context,
Default::default(),
)
.await;
assert!(matches!(result, Err(AccountPolicyError::Filtered)));
@@ -368,6 +376,7 @@ fn filtering_ids_outside_the_host_candidate_pool_is_a_policy_fault() {
None,
&candidates,
&mut context,
Default::default(),
)
.await;
assert!(matches!(result, Err(AccountPolicyError::Fault)));
@@ -386,6 +395,7 @@ fn empty_filter_preserves_native_affinity_and_busy_candidates_cannot_be_picked()
None,
&candidates,
&mut context(),
Default::default(),
)
.await
.unwrap()
@@ -400,6 +410,7 @@ fn empty_filter_preserves_native_affinity_and_busy_candidates_cannot_be_picked()
None,
&candidates,
&mut context,
Default::default(),
)
.await;
assert!(matches!(result, Err(AccountPolicyError::Fault)));
@@ -69,7 +69,7 @@ fn privacy_rule_requires_steps_and_rejects_unknown_fields() {
missing_steps.as_object_mut().unwrap().remove("steps");
assert!(serde_json::from_value::<PrivacyRule>(missing_steps).is_err());
let mut unknown_rule_field = value.clone();
unknown_rule_field["scope"] = serde_json::json!("request_body");
unknown_rule_field["unexpected"] = serde_json::json!(true);
assert!(serde_json::from_value::<PrivacyRule>(unknown_rule_field).is_err());
let mut unknown_step_field = value;
unknown_step_field["steps"][0]["unexpected"] = serde_json::json!(true);
@@ -139,7 +139,7 @@ fn blocked_file_output_keeps_http_and_streaming_responsive_and_reserves_errors()
);
let (release, released) = std::sync::mpsc::channel();
let reader = std::thread::spawn(move || {
// 超时只用于让旧的同步实现能退出测试,接口必须在解除阻塞之前完成
// 请求必须在读端放行前完成,超时让写入阻塞时的测试也能退出
let _ = released.recv_timeout(Duration::from_secs(3));
let mut body = String::new();
fs::File::open(fifo)
@@ -327,7 +327,6 @@ async fn managed_http_enforces_the_callers_body_limit_before_sending() {
.mount(&server)
.await;
let client = HttpClient::new().unwrap();
// 覆盖旧固定上限之外的正文,并验证同一个客户端逐次使用调用方的预算
let maximum = 17 * 1024 * 1024;
for (size, limit, accepted) in [
(maximum, maximum, true),
@@ -24,9 +24,9 @@ async fn invalid_update_state_should_keep_raw_details_out_of_public_error() {
}
#[tokio::test]
async fn update_status_should_reconcile_manual_deployment_without_reusing_legacy_success() {
async fn manual_deployment_reports_the_running_version_and_preserves_the_last_operation() {
let fixture = Fixture::new();
fs::write(fixture.state(), r#"{"previousVersion":"3.14.0","currentVersion":"3.14.1","operation":{"operationId":"legacy","kind":"update","status":"succeeded","targetVersion":"3.14.1"}}"#).expect("legacy state");
fs::write(fixture.state(), r#"{"previousVersion":"3.14.0","currentVersion":"3.14.1","operation":{"operationId":"completed-update","kind":"update","status":"succeeded","targetVersion":"3.14.1"}}"#).expect("completed update state");
let mut config = fixture.config("https://api.github.com/repos");
config.version = "3.15.0".to_owned();
config.deployment_mode = "docker".to_owned();
@@ -4,7 +4,7 @@
"protocol_versions": [7],
"capabilities": [
{ "capability": "frontend_authentication", "versions": [2] },
{ "capability": "scheduler", "versions": [3] },
{ "capability": "scheduler", "versions": [4] },
{ "capability": "model_router", "versions": [2] },
{ "capability": "model_catalog", "versions": [2] },
{ "capability": "retry_policy", "versions": [2] },
@@ -7,8 +7,8 @@ use futures::future::BoxFuture;
use gateway_core::{
account::ProviderAccountId,
engine::policy::{
AccountScheduleDecision, AccountScheduleInput, ModelRouteDecision, ModelRouteInput,
RequestPolicyFault, RequestPolicyPlan,
AccountScheduleDecision, AccountScheduleInput, AccountScheduleRole, ModelRouteDecision,
ModelRouteInput, RequestPolicyFault, RequestPolicyPlan,
},
identity::ProviderKind,
operation::{Operation, ProviderHttpHeader},
@@ -20,6 +20,7 @@ use gateway_plugin_sdk::{
AccountScheduleCandidate as WireAccountScheduleCandidate,
AccountScheduleDecision as WireAccountScheduleDecision,
AccountScheduleRequest as WireAccountScheduleRequest,
AccountScheduleRole as WireAccountScheduleRole,
ModelRouteDecision as WireModelRouteDecision, ModelRouteRequest, PolicyHeader,
},
};
@@ -183,6 +184,13 @@ async fn schedule_with_entry(
.iter()
.map(|candidate| WireAccountScheduleCandidate {
account_id: candidate.account_id().as_str().to_owned(),
session_bound: candidate.session_bound(),
role: match candidate.role() {
AccountScheduleRole::Ordinary => WireAccountScheduleRole::Ordinary,
AccountScheduleRole::Preferred => WireAccountScheduleRole::Preferred,
AccountScheduleRole::FollowOnly => WireAccountScheduleRole::FollowOnly,
AccountScheduleRole::Pinned => WireAccountScheduleRole::Pinned,
},
available: candidate.available(),
weight: candidate.weight(),
in_flight: candidate.in_flight(),
@@ -98,6 +98,7 @@ impl PluginData {
next_cursor: page.next_cursor.map(|id| id.as_str().to_owned()),
})
}
data::QUOTA_HISTORY => return self.quota_history(payload).await,
data::QUOTA_GET | data::QUOTA_REFRESH | data::QUOTA_DETAILS => {
let accounts = self.accounts.upgrade().map_err(map_admin_error)?;
let query: data::QuotaFactsQuery =
@@ -162,4 +163,67 @@ impl PluginData {
payload,
})
}
async fn quota_history(&self, payload: &[u8]) -> Result<RpcReply, PluginFault> {
use gateway_admin::model::{
observability::TimeRange,
quota_history::{QuotaHistoryPoint, QuotaHistoryQuery},
};
let wire: data::QuotaHistoryQuery =
serde_json::from_slice(payload).map_err(|_| invalid())?;
let id = ProviderAccountId::new(wire.account_id).map_err(|_| invalid())?;
let time = |ms| chrono::DateTime::from_timestamp_millis(ms).ok_or_else(invalid);
let range =
TimeRange::new(time(wire.start_ms)?, time(wire.end_ms)?).map_err(|_| invalid())?;
if wire.start_ms < 0
|| wire.window_key.is_empty()
|| wire.window_key.len() > 256
|| wire.window_key.chars().any(char::is_control)
{
return Err(invalid());
}
let query = QuotaHistoryQuery {
window_key: wire.window_key,
range,
cursor: wire
.cursor
.as_deref()
.map(serde_json::from_str)
.transpose()
.map_err(|_| invalid())?,
};
if query.cursor.as_ref().is_some_and(|c| {
c.completed_at >= range.end
|| c.completed_at < query.scan_start()
|| c.id.is_empty()
|| c.id.contains('\0')
}) {
return Err(invalid());
}
let page = self
.accounts
.upgrade()
.map_err(map_admin_error)?
.quota_history(&id, query)
.await
.map_err(map_admin_error)?;
let sample = |p: QuotaHistoryPoint| data::QuotaHistorySample {
observed_at_ms: p.observed_at.timestamp_millis(),
used_percent: p.reading.used_percent,
reset_at_ms: p.reading.reset_at.map(|at| at.timestamp_millis()),
plan_type: p.reading.plan_type,
};
super::admin::encode(&data::QuotaHistoryPage {
schema_version: 1,
samples: page.samples.into_iter().map(sample).collect(),
baseline: page.baseline.map(sample),
next_cursor: page
.next_cursor
.as_ref()
.map(serde_json::to_string)
.transpose()
.map_err(|_| invalid())?,
})
}
}
@@ -216,6 +216,7 @@ impl CallbackHandler for PluginCallbacks {
| gateway_plugin_sdk::call::data::KEYS_GET
| gateway_plugin_sdk::call::data::QUOTA_GET
| gateway_plugin_sdk::call::data::QUOTA_REFRESH
| gateway_plugin_sdk::call::data::QUOTA_HISTORY
| gateway_plugin_sdk::call::data::QUOTA_DETAILS
) {
return data.call(&method, params, &payload).await;
@@ -15,6 +15,17 @@ struct BudgetAccountAccess {
#[async_trait::async_trait]
impl gateway_admin::ports::plugin_accounts::PluginAccountAccess for BudgetAccountAccess {
async fn quota_history(
&self,
_: &gateway_core::account::ProviderAccountId,
_: gateway_admin::model::quota_history::QuotaHistoryQuery,
) -> Result<
gateway_admin::model::quota_history::QuotaHistoryPage,
gateway_admin::model::AdminError,
> {
unreachable!("账号提交不读取额度历史")
}
async fn list(
&self,
_: gateway_admin::model::provider_credentials::PluginAccountListQuery,
@@ -75,6 +75,30 @@ fn account() -> AccountRecord {
#[async_trait]
impl PluginAccountAccess for Facts {
async fn quota_history(
&self,
id: &ProviderAccountId,
query: gateway_admin::model::quota_history::QuotaHistoryQuery,
) -> Result<gateway_admin::model::quota_history::QuotaHistoryPage, AdminError> {
use gateway_admin::model::quota_history::{
QuotaHistoryPage, QuotaHistoryPoint, QuotaReading,
};
assert_eq!(id.as_str(), "acct_facts");
assert_eq!(query.window_key, "weekly");
assert!(query.cursor.is_none());
Ok(QuotaHistoryPage {
samples: vec![QuotaHistoryPoint {
observed_at: query.range.start,
reading: QuotaReading {
plan_type: None,
used_percent: 12.5,
reset_at: None,
},
}],
..Default::default()
})
}
async fn refresh_quota(
&self,
account: &ProviderAccountId,
@@ -201,6 +225,9 @@ async fn management_facts_validate_queries_without_permission_declarations() {
{"method":"host.data.accounts.list","query":{"provider_id":"openai","cursor":"acct_before","limit":1}},
{"method":"host.data.quota.get","query":{"account_id":"acct_facts"}},
{"method":"host.data.quota.details","query":{"account_id":"acct_facts"}},
{"method":"host.data.quota.history","query":{"account_id":"acct_facts","window_key":"weekly","start_ms":1000,"end_ms":2000}},
{"method":"host.data.quota.history","query":{"account_id":"acct_facts","window_key":"weekly","start_ms":2000,"end_ms":1000}},
{"method":"host.data.quota.history","query":{"account_id":"acct_facts","window_key":"weekly","start_ms":1000,"end_ms":2000,"cursor":"invalid"}},
{"method":"host.data.accounts.list","query":{"limit":0}},
{"method":"host.data.accounts.list","query":{"limit":65535}},
{"method":"host.data.quota.get","query":{"account_id":"acct_facts","sql":"SELECT secret"}}
@@ -269,7 +296,12 @@ async fn management_facts_validate_queries_without_permission_declarations() {
Some("123456789.123456789")
);
assert!(!result[2].to_string().contains("provider-internal-fixture"));
for invalid in &result.as_array().unwrap()[3..] {
let history: gateway_plugin_sdk::call::data::QuotaHistoryPage =
serde_json::from_value(result[3].clone()).unwrap();
assert_eq!(history.samples[0].used_percent, 12.5);
assert_eq!(history.samples[0].observed_at_ms, 1000);
assert_eq!(history.samples[0].reset_at_ms, None);
for invalid in &result.as_array().unwrap()[4..] {
assert_eq!(invalid["error"], "invalid_input");
}
@@ -682,6 +682,7 @@ async fn scheduler_cannot_pick_outside_the_host_projected_priority_tier() {
Some("upstream-a"),
&candidates,
&mut selection,
Default::default(),
)
.await
.unwrap()
@@ -306,6 +306,7 @@ async fn data_plane_http_callbacks_keep_the_frozen_body_budget_across_publicatio
None,
&[candidate("acct_high", 100)],
&mut selection_context(),
Default::default(),
)
.await
.unwrap();
@@ -1,7 +1,7 @@
//! 验证真实插件进程的候选过滤、繁忙投影与非法决定边界
use super::*;
use gateway_core::engine::policy::AccountPolicyError;
use gateway_core::engine::policy::{AccountPolicyError, AccountScheduleOwnership};
#[tokio::test]
async fn scheduler_filter_contract_covers_busy_candidates_and_rejects_out_of_scope_ids() {
@@ -44,6 +44,10 @@ async fn scheduler_filter_contract_covers_busy_candidates_and_rejects_out_of_sco
None,
&candidates,
&mut selection,
AccountScheduleOwnership {
bound_account: Some(candidates[0].account.id()),
..Default::default()
},
)
.await;
match expected {
@@ -60,8 +64,13 @@ async fn scheduler_filter_contract_covers_busy_candidates_and_rejects_out_of_sco
request["request"]["candidates"].as_array().unwrap().len(),
2
);
assert_eq!(request["request"]["candidates"][0]["available"], false);
assert_eq!(request["request"]["candidates"][1]["available"], true);
let candidates = &request["request"]["candidates"];
assert_eq!(candidates[0]["available"], false);
assert_eq!(candidates[0]["session_bound"], true);
assert_eq!(candidates[0]["role"], "preferred");
assert_eq!(candidates[1]["available"], true);
assert_eq!(candidates[1]["session_bound"], false);
assert_eq!(candidates[1]["role"], "ordinary");
drop(policy);
drop(generation);
super::super::wait_until_empty(cache.path()).await;
@@ -107,6 +107,7 @@ async fn callbacks_are_dispatched_in_every_stage_without_permission_declarations
"host.data.accounts.list",
"host.data.keys.get",
"host.data.quota.get",
"host.data.quota.history",
"host.groups.ensure",
"host.groups.change_members",
"host.keys.ensure",
@@ -645,7 +645,7 @@ async fn concurrent_calls_keep_their_wire_ids_monotonic() {
}
ready.wait().await;
entered.await;
// 旧实现会在 begin 前分配后续 ID;等其他线程进入该窗口后再释放首调用
// 暂停首个 begin,给其他并发调用留出竞争发送顺序的时间
tokio::time::sleep(Duration::from_millis(20)).await;
callbacks.release();
for call in calls {
@@ -542,8 +542,6 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
);
if let Some(expected) = configuration.get("expected_fast_source") {
let sources = &call.request.head.settings_sources["execution"];
assert!(sources.get("disable_fast").is_none());
assert!(sources["input"].get("disable_fast").is_none());
assert_eq!(sources["input"]["fast_mode"], "default");
assert_eq!(&sources["fast_mode"], expected);
}
+10 -25
View File
@@ -1,15 +1,9 @@
# Gateway Plugin SDK
用于编写 Codex Proxy 插件的 Rust 合同与可选会话辅助。插件只依赖本包,不依赖宿主 Core、Admin、Store 或 Host。
SDK 包版本为 `0.1.0`,独立于网关版本,处于实验阶段。能力是否可用取决于宿主支持、清单声明与实际注册
Rust 插件只需依赖 `gateway-plugin-sdk`。SDK `0.1.0` 处于实验阶段,独立于网关发版。清单、进程协议和能力分别版本化,插件可用能力取决于宿主支持、清单声明与实际注册
清单、进程协议和各项能力分别版本化,当前版本与声明规则统一见[插件清单](docs/manifest.md)
开发顺序:编写[清单](docs/manifest.md) → 实现[能力处理器](docs/capabilities.md) → 用 [CLI](../../../apps/plugin-cli/README.md)
打包 → [安装、配置与启用](../../../../docs/plugins.md)。完整可运行示例位于独立仓库
`codex-proxy-plugins` 的 `examples/workbench`
使用 AI 协作开发时,可调用仓库技能 [`$cpr-plugin-dev`](../../../../.agents/skills/cpr-plugin-dev/SKILL.md),按任务定位合同、示例和验证入口
编写[清单](docs/manifest.md) → 实现[处理器](docs/capabilities.md) → 用 [CLI 打包](../../../apps/plugin-cli/README.md) → [安装并启用](../../../../docs/plugins.md)。
完整示例见 `codex-proxy-plugins/examples/workbench`,AI 协作入口见 [cpr-plugin-dev](../../../../.agents/skills/cpr-plugin-dev/SKILL.md)
## 模块与依赖
@@ -23,17 +17,13 @@ SDK 包版本为 `0.1.0`,独立于网关版本,处于实验阶段。能力
| `call::upstream_adapter` | 内置 OpenAI / xAI 的[受管上游适配器](docs/upstream-adapters.md)注册、执行、出站与续接合同 |
| `call::policy` | 模型路由、账号调度与重试决策合同 |
| `call::catalog` | 固定 Provider 的直接别名与适配模型注册合同,见[模型目录](docs/capabilities.md#模型目录) |
| `call::data` | 最小账号事实与已有额度观测的只读合同 |
| `call::data` | 账号事实、当前额度与历史额度观测 |
| `call::observation` | 请求完成、用量、费用与实际上游 WebSocket 响应事件的统一观察合同 |
| `call::host` | 账号、私有状态、受管 HTTP、模型、亲和、日志及调用内流的宿主回调合同 |
| `call::management` | 管理 API、页面与资源声明、公开回调,以及 CLI 命令与待保存账号 |
| `client` | 通过 `io` feature 开启的 `PluginBuilder`、会话、中间件与异步帧收发 |
`call/` 按业务能力组织数据,`message.rs` 定义消息与帧。已有请求链的请求/响应改写、协议转换和思考参数映射使用
`call::middleware`;需要指定业务上游并解析结果时使用 `call::upstream_adapter`,作为洋葱链终端复用宿主账号与结算。
下游 WebSocket 改写使用 `websocket` 中间件;上游发送前的请求准备使用 `outbound` 中间件,响应观察接口保留只读合同
插件使用的导入路径例如:
`message.rs` 定义消息与帧。改写现有请求、响应或推理参数使用 `call::middleware`,其中 `websocket` 处理下游消息,`outbound` 处理上游发送前的请求。响应观察只读。需要自行选择业务上游并解析响应时使用 `call::upstream_adapter`
```rust
use gateway_plugin_sdk::{Frame, Message, PluginFault};
@@ -42,10 +32,8 @@ use gateway_plugin_sdk::call::{host::ModelEventBatch, model::ExecutionEvent};
use gateway_plugin_sdk::client::{read_frame, write_frame};
```
默认 feature 不引入异步运行时。`io` 除帧编解码外,还提供 `PluginBuilder`、
`PluginSession::accept/run` 和 `PluginHandler`。组合插件从作者清单建立类型化方法,SDK 自动生成
`plugin.register`;作者不需要复制贡献项或手写方法名、阶段和敏感载荷编解码。
会话管理握手、有界并发、父调用关联、回调、流信用、取消、排空与关闭,容量与计时见[并发与期限](#并发与期限)
默认 feature 不引入异步运行时。`io` 提供帧编解码、`PluginBuilder`、`PluginSession::accept/run` 和 `PluginHandler`。
[类型化构建器](docs/capabilities.md#类型化作者入口)按清单注册处理器。会话管理握手、并发、父调用关联、回调、流信用、取消、排空与关闭,容量与计时见[并发与期限](#并发与期限)
`HostClient::scan_usage_records` 与 `query_usage_statistics` 提供用量明细扫描和完整分组统计,按批读取与关闭见[用量查询](docs/usage-data.md#完整扫描与分组统计)
@@ -149,9 +137,8 @@ session.run(handler).await?;
### 帧与会话
`CallContext.timeout_ms` 限定初始处理期限。宿主对由流或连接 owner 管理的调用设置 `resource_stream`:
首个流式结果成功返回后,正文、会话及关联回调由资源取消与终态回收,不再沿用初始期限。
普通调用继续使用原期限;资源模式仍保留并发容量、Credit、父调用关联及取消约束
普通调用受 `CallContext.timeout_ms` 限制。对标记为 `resource_stream` 的调用,初始期限只到首个流式结果成功返回。
其后的正文、会话及回调由资源终态或取消回收,仍受并发容量、Credit 和父调用约束
协议 v7 的帧头由大端 `u32` 元数据长度和大端 `u64` 载荷长度组成,随后依次传输 JSON 元数据和二进制载荷。
元数据保留 64 KiB 上限;正文总量不由插件传输层额外限制。传输内部以 256 KiB 为单次 I/O 块,
@@ -210,6 +197,4 @@ RUST_MIN_STACK=16777216 cargo +1.99.1 test --manifest-path backend/Cargo.toml -p
RUST_MIN_STACK=16777216 RUSTDOCFLAGS='-D warnings' cargo +1.99.1 doc --manifest-path backend/Cargo.toml -p gateway-plugin-sdk --all-features --no-deps --locked
```
源码中的类型和字段是当前合同;宿主接入、目录边界、内置 Provider 与 Runtime 集成验证见
[系统架构](../../../../docs/architecture.md#31-插件扩展)。
单元测试与文档构建不代替目标平台上的安装、配置及实际能力验证
宿主集成见[系统架构](../../../../docs/architecture.md#31-插件扩展)。插件还须在目标平台验证安装、配置和实际功能
@@ -27,22 +27,15 @@ let plugin = PluginBuilder::from_json(include_bytes!("../plugin.json"))?
session.run(plugin).await?;
```
`PluginBuilder::from_json` 与 `cpr-plugin package` 使用同一个作者清单规范化入口。构建器负责:
- 自动响应 `plugin.register`,注册内容直接来自规范化后的清单
- 按方法合同解码控制参数和二进制载荷,并在进入业务处理器前检查调用阶段
- 保留 `TypedCall` 中的调用上下文、宿主客户端和取消信号
- 按方法合同编码 `TypedReply`,流式结果继续复用有界 `ResponseStream`
- 在 `build()` 时核对能力与必需处理器,避免清单与分派表漂移
`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`,构建器也会要求该处理器存在
类型化合同故意区分三种数据:普通控制元数据、可能敏感的 JSON 二进制载荷、原始字节。
例如 CLI 参数、账号凭据和状态迁移批次使用二进制 JSON,管理 HTTP 正文保持原始字节。
错误地把敏感载荷放进控制参数会在业务处理器运行前被拒绝
控制参数只放普通元数据。CLI 参数、账号凭据和状态迁移批次使用二进制 JSON,管理 HTTP 正文使用原始字节。敏感载荷放进控制参数会在分派前被拒绝
## 请求上下文
@@ -89,6 +82,7 @@ Provider 固定为宿主内置的 OpenAI 与 xAI。宿主开放以下 11 类扩
| `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,不返回密钥 |
@@ -108,6 +102,16 @@ SDK 解析响应时忽略未知字段,包含账号分页、账号及额度窗
`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 入口时使用当前发布配置。
认证可以调用认证插件,继续扣减父预算并响应取消;验证成功不做推理准入、账号租约、使用记录或计费。
授权原文只作本次认证输入,不进入返回值
@@ -241,9 +245,7 @@ SDK 不自动重试。超时或断连不能证明写入未提交;重试上限
### Key、模型与模型调用
模型调用方法:
- `host.keys.list`:只返回 `{id, name, enabled}`,不返回 Key 明文、前缀或隐藏 scope
- `host.keys.list`:分页返回 `{id, name, enabled}`
- `host.models.list`:以显式 `client_key_id` 查询该 Key 当前可见的模型目录
- `host.model.execute[_stream]`:交给 Core 的路由、准入、租约、重试、账本和计费链路执行
- `host.model.stream_read/close`:读取或关闭当前父调用创建的有界流
@@ -255,9 +257,8 @@ SDK 不自动重试。超时或断连不能证明写入未提交;重试上限
`invalid_input`,不启动模型执行。上游适配器的请求 `GPAQ` 也使用请求预算,响应事件仍受
原有 8 MiB 编码上限、Runtime 缓冲预算及流控窗口限制
HTTP 和 request 中间件中的模型回调沿用有效请求设置;attempt、outbound、路由、调度、重试和上游适配器
沿用该次模型请求冻结的正文预算。显式 Key 模型调用的预检与执行使用同一身份快照,
同一父调用内复用 Key 时不受后续配置发布影响;父调用结束后重新解析身份才读取新配置,无需重新启用插件
HTTP 和 request 中间件使用有效请求设置。attempt、outbound、路由、调度、重试及上游适配器沿用冻结的模型请求预算。
显式 Key 的预检与执行共用父调用内的身份快照,后续发布的配置在新的父调用解析身份时生效
`ModelExecuteRequest.client_key_id` 可显式选择执行 Key,不与触发插件的父请求 Key 求交。省略时继承现有模型父请求身份;没有模型父请求的调用必须提供 Key。所选 Key 的启用状态、模型规则、账号组、并发和预算继续由 Core 执行
嵌套调用与显式 Key 调用继承入口快照中的客户端 IP 和 User-Agent;没有 HTTP 入口的后台调用保持来源未知
@@ -265,7 +266,7 @@ HTTP 和 request 中间件中的模型回调沿用有效请求设置;attempt
模型事件使用 `call::model::ExecutionEvent` 的 `GPE2` 封套,将 canonical 事实、宿主事实和原始 wire 分段编码。`host` 包含费用及定价明细、完整上游观测、会话状态和改写来源;当前 wire 与原始 wire 都保留二进制字节;`WirePayload::WebSocket` 独立保留完整文本消息和可选 JSON 视图,不把未知文本改造成 SSE。读取或回传快照不触发第二次计费、续接提交或发送状态更新。
非流式模型结果通过 `ModelEventBatch` 的 `HME1` 有界二进制批次返回;流式句柄只在创建它的父调用内有效。
发起回调的插件实例在子调用中跳过,Core 在单次执行的子调用图内限制递归深度、总数和并发,避免插件调用自身形成环。
显式 Key 的身份快照随父调用保留,每个模型执行独立计时并建立调用图;父调用结束会取消尚未完成的执行,连接空闲不消耗后续执行的期限
每次模型执行独立计时并建立调用图。父调用结束会取消未完成的执行,连接空闲不消耗后续执行的期限
`host.affinity.lookup` 查询 Provider 已持久化的真实亲和键。命中只是账号偏好,
后续执行仍重新检查当前 Key 规则、账号资格和租约
@@ -277,16 +278,11 @@ HTTP 和 request 中间件中的模型回调沿用有效请求设置;attempt
父调用取消或结束时宿主回收未关闭的流,SDK 不后台预读。取消一次 `read()` 等待后,再次读取会继续同一次操作,不丢弃已经返回的分块。
账号上游使用同一正文对象,使用方式见[受管上游](upstream-adapters.md)
`HostClient::account_http(AccountHttpRequest { account_id, credential_revision, request }, body)` 使用指定账号的当前代理配置,
经 `host.http.account` 返回同一 `HostHttpBody`。每次发送核对账号存在、启用和凭据版本,版本变化须由插件重新读取后决定下一步。
请求 headers 与正文完全由插件提供;宿主不注入账号认证、不申请推理租约。无显式代理时使用部署默认出口,代理不可用时直接失败,不回退直连。
这项能力与上游适配器的账号推理 HTTP 分开,适用于插件自行构造的账号网络请求
`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`,不要求账号存在或绑定代理,也不校验账号凭据版本。
代理不存在、禁用或连接失败时返回错误,不回退直连;未测试或历史测试失败不阻止实际请求。
每次发送重新读取代理,已发出的请求沿该次解析的出口完成,不锁定整个插件业务流程的代理配置。
目标请求的 headers 与正文由插件提供,宿主不注入账号认证;代理连接所需认证由宿主处理
`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 字节且不能包含控制字符。
@@ -376,7 +372,7 @@ let status = host.service::<SetResetCreditAutomation>((account_id, true)).await?
`HttpCall.request` 提供 method、URI(含 query)、HTTP version、完整多值 headers、`settings`、`timeout_ms` 和 `HttpBody`。
调用发生在路由匹配之前,管理接口、模型接口和未知路径都可参与。`settings` 是同一请求快照中的宿主运行设置,
插件改写后用于后续认证、版本检查、正文解压及执行;不新增设置业务的中间件入口。`timeout_ms` 使用宿主 HTTP 超时基线,
插件改写后的设置用于认证、版本检查、正文解压及执行。`timeout_ms` 默认取宿主 HTTP 超时,
插件可改写或用 `None` 清除;终端按有效值执行,不恢复宿主默认值。宿主快照不可用时 `settings` 为 `null`
`POST /v1/chat/completions` 在 HTTP 挂载中保留 Chat 请求与 Chat JSON/SSE 响应视图,
@@ -653,9 +649,20 @@ middleware 的 `next` 最多调用一次,重试与额外模型执行通过独
### 路由、调度与观察
`policy.route_model` 和 `policy.schedule_account` 只提出决定,宿主随后复核 Key 规则、模型能力、账号资格和租约。
`scheduler` 必须声明 `version: 3`。`candidates` 已按 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`
@@ -734,7 +741,7 @@ keep、replace 或 delete;全部完成后宿主才原子提交新配置与状
需要跳转到外部页面时,在插件页面的用户点击处理器中调用 `openExternal(url): Promise<void>`。
地址必须是绝对 HTTPS URL,不能包含用户名或密码。宿主展示目标主机名和非默认端口,管理员可打开新标签页、复制链接或取消。
Promise 成功只表示宿主已接受确认请求,不代表链接已打开;无用户操作、地址无效或已有链接待确认时,请求会被拒绝。
切换页面会关闭确认框。兼容较早的 v2 宿主时,先检查 `typeof window.codexProxyPlugin.openExternal === 'function'`
切换页面会关闭确认框。插件需要适配缺少此方法的宿主时,先检查 `typeof window.codexProxyPlugin.openExternal === 'function'`
普通模型请求使用标准 `Response` 接口:
@@ -2,8 +2,7 @@
[返回 SDK](../README.md) · [能力与回调](capabilities.md)
`Manifest` 对应包内 `plugin.json`。作者源清单由 `Manifest::from_author_slice` 读取,CLI 打包也调用同一入口;
因此本地构建器、生成的安装清单和运行注册共享一份规范化结果
`Manifest` 对应包内的 `plugin.json`。本地构建器与打包 CLI 都通过 `Manifest::from_author_slice` 校验并规范化作者清单
| 字段 | 规则 |
| --- | --- |
@@ -14,11 +13,10 @@
| `configurationSchema` / `secretFields` | 普通设置的 schema / 单独保存的敏感字段 |
| `main` / `resources` | 包内可执行文件 / 资源路径与 MIME 类型 |
| `state` | [私有状态](capabilities.md#状态日志与迁移)的命名空间、schema 与配额 |
| `package` | CLI 生成的协议版本、单一目标平台与文件摘要,不需作者手写 |
| `package` | 作者清单须省略。CLI 填入协议版本、目标平台与文件摘要 |
作者清单不能包含 `package`。使用 `Manifest::from_author_slice()` 校验并规范化;直接反序列化的 `Manifest`
不会执行作者清单的 ID 与固定阶段推导,声明的可选字段仍使用其默认值。打包后,`main` 和所有资源都必须进入 `package.files`,
宿主校验包结构、目标平台与文件完整性,宿主范围和能力版本另行进行兼容检查。运行模式为 `trustedProcess`,信任边界见[完整信任](#完整信任)
直接反序列化 `Manifest` 只应用可选字段默认值。需要推导 ID 和固定阶段时使用作者清单入口。
打包后,`package.files` 须包含 `main` 与所有资源
宿主实际开放的合同由 [plugin-host-compatibility.json](../../runtime/plugin-host-compatibility.json)
声明,SDK 的 `Capability::contract_versions()` 只表示 SDK 能描述的行为版本,不能代替宿主支持检查
@@ -32,13 +30,9 @@
`capabilities` 使用扩展能力标识;Provider、模型和账号 ID 不属于这个集合
清单不接受 `permissions` 字段;插件按[完整信任](#完整信任)运行
CLI 按 SDK 合同校验声明。安装包清单拒绝未知字段,并校验必需字段、类型与版本。进程通信见 [RPC 合同](../README.md#通信边界),已安装元数据的读取见[制品与发布](../../../../../docs/architecture.md#制品配置与发布)
RPC v7 的帧布局、编码与会话生命周期见[通信边界](../README.md#通信边界)。插件使用 SDK 构建,并由 CLI 生成包含协议版本的安装包
安装包清单校验与已安装元数据读取是两个边界:清单拒绝未知字段,并检查必需字段、类型和版本;
数据库元数据的读取规则见[制品与发布](../../../../../docs/architecture.md#制品配置与发布),不改变清单或 RPC 合同。
`engines.codex-proxy-rs` 声明插件所需的宿主范围。范围或已声明能力版本不匹配时不自动启动,管理员确认风险后可尝试本次启动;确认不跨宿主重启保留。包结构、清单格式、平台与 RPC 封装校验失败阻止加载,不能通过风险确认绕过。CLI 严格校验作者声明是否符合 SDK 支持的合同
宿主版本超出 `engines.codex-proxy-rs` 范围或能力版本不匹配时,管理员可确认风险并尝试启动,确认仅对本次启动有效。包结构、文件完整性、清单格式、平台或 RPC 校验失败时无法加载
## 接口弃用
@@ -54,7 +48,7 @@ RPC v7 的帧布局、编码与会话生命周期见[通信边界](../README.md#
| 能力 | 当前版本 |
| --- | --- |
| `middleware` | `6` |
| `scheduler` | `3` |
| `scheduler` | `4` |
| `upstream_adapter` | `5` |
| `frontend_authentication`、`model_router`、`retry_policy`、`observer`、`management` | `2` |
| `model_catalog` | `2` |
@@ -98,15 +92,11 @@ capability 固定并由工具生成:
安装并启用插件意味着信任其全部代码和行为。插件与宿主使用相同的系统身份,可以访问数据、凭据和网络;安全由安装者承担,宿主不提供插件安全沙箱
清单只声明处理器、配置和资源。宿主回调不需要权限声明,也不按调用阶段授予访问域;类型校验、期限、取消、实例 revision、事务及流资源生命周期仍然生效
运行模式为 `trustedProcess`。清单不接受 `permissions`,宿主回调无需声明权限。类型、期限、取消、实例 revision、事务与流资源约束均生效
## 插件图标
`icon` 指定管理端展示的插件图标。值可以是一个包内文件路径,也可以是包含 `light`、`dark` 两个路径的对象。
使用单个路径时,浅色和深色主题共用同一张图;使用主题对象时,管理端按当前主题选择,两项都必须填写。
不填写 `icon` 时显示通用图标。图标路径不是远程 URL,也不接受内置图标名称
在 `plugin.json` 中同时设置 `icon` 和对应的 `resources` 项。以下是单图标配置片段:
`icon` 可填包内路径(两种主题共用),或同时含 `light`、`dark` 路径的对象。每个文件均须在 `resources` 登记。省略 `icon` 时显示通用图标
```json
{
@@ -151,6 +141,4 @@ capability 固定并由工具生成:
- 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
[插件 CLI](../../../../apps/plugin-cli/README.md) 打包图标,宿主在安装时校验内容。管理端通过[图标接口](../../../../../docs/api.md#图标读取)以图片展示 SVG
@@ -2,9 +2,8 @@
[返回 SDK](../README.md) · [清单声明](manifest.md#扩展项简写) · [能力与回调](capabilities.md)
`upstream_adapter` v5 是现有生成请求洋葱链的终端,只挂到内置 `openai` / `xai`,不替换独立图像或压缩端点。
插件定义 Base URL、业务路径、请求编码和响应解析;宿主继续持有身份、ACL、选号、租约、凭据、代理、重试和账本。
普通请求或响应加工使用 [middleware](capabilities.md#洋葱中间件)
`upstream_adapter` v5 处理内置 `openai` / `xai` 的生成请求,独立图像和压缩端点使用原生实现。
插件负责 Base URL、路径、请求编码和响应解析。宿主负责身份、ACL、选号、租约、凭据、代理、重试和账本。仅需加工请求或响应时使用[中间件](capabilities.md#洋葱中间件)
## 声明与绑定
@@ -26,18 +25,13 @@
| `models` | 公开请求模型的精确匹配,空集合沿用绑定范围 |
| `account_ids` | 上游账号 ID 范围,必填;空数组匹配所有账号 |
实例绑定沿用 Key、账号组、Provider、模型范围,只允许一次 `upstream` 绑定和 `reject` 故障策略。
多个声明命中时按发布顺序选择首个适配器,插件负责声明的业务含义。适配器未命中时仍使用原生上游,
已命中但不可用时拒绝请求。安装、配置、启停和升级使用已有插件管理
实例只允许一个 `upstream` 绑定,故障策略为 `reject`。Key、账号组、Provider 和模型限定请求范围,插件注册的 `account_ids` 只能进一步收窄账号范围
账号范围只收窄绑定,不能扩大 Key、分组或模型权限。宿主先排除适配器不可用或认证类型不兼容的账号,
再沿用原调度、亲和和租约;取得账号后从同一发布代次解析适配器。不同账号可以为同一公开模型选择不同适配器,
未匹配账号保持原生执行,重叠声明仍按发布顺序取首个匹配。
前置账号范围已匹配的可用适配器不受后置兜底声明故障影响。
xAI 原生编码不支持的请求仍可选择匹配的适配器账号;原生账号会在取得租约前被排除
同一模型可按账号使用不同适配器。每个账号按发布顺序取首个匹配声明,后续声明的故障不影响已匹配的适配器。未匹配时使用原生上游,命中但不可用时拒绝执行
账号范围由插件注册结果提供,不改变管理端 binding 中 `accountGroupIds` 的请求作用域语义。
停用或卸载实例会移除其绑定;维护时须先停用依赖该适配器的账号并排空请求,账号范围不提供永久依赖约束。
取得租约前,宿主排除适配器不可用或认证不兼容的账号。xAI 原生编码不支持请求时,仅排除原生账号,匹配的适配器账号仍可使用。宿主按亲和与调度策略取得租约后,从同一发布代次解析适配器
停用或卸载实例会移除绑定。维护前先停用依赖该适配器的账号并排空请求
能力、清单、进程 RPC 和宿主兼容声明分别校验各自版本,见[清单](manifest.md)。
Provider、业务协议和传输名称不能写入宿主兼容清单的 capability / RPC 版本位置
@@ -65,9 +59,8 @@ while let Some(bytes) = body.read().await? {
}
```
正文与普通 `HostClient::http` 共用 `read`、`collect(maximum_bytes)` 和 `close`;每次读取至多 64 KiB,
不后台预读,不向作者暴露流 ID。提前关闭及收集超限会释放正文,父调用结束或取消时宿主兜底回收。
JSON 可有界收集,SSE 应增量解析,不能把读取块当成完整事件。HTTP 版本、字节头及 trailers 的读取见[网络](capabilities.md#网络)
正文每次 `read` 至多 64 KiB,SDK 按需读取并管理流 ID。JSON 可用 `collect(maximum_bytes)`,SSE 须跨读取块增量解析。
显式 `close`、收集超限或父调用结束、取消时释放正文。HTTP 版本、字节头及 trailers 见[网络](capabilities.md#网络)
WebSocket 使用 `call.host.upstream_websocket(request).await?`,返回
`UpstreamWebSocketUpgrade::Connected { http_version, headers, connection }` 或 `Rejected { status, http_version, headers, body, trailers }`。
@@ -102,9 +95,7 @@ let (message, ()) = tokio::try_join!(
观测事件和该次 HTTP 的读流、关流不单独阻断;HTTP200 流内报错、WebSocket 拒绝及其他状态码不适用。
Core 仍复核续接归属、外部副作用、交付与重试预算;这不保证一定换号,也不证明完整信任插件绕过宿主执行的操作可重放
初始 RPC 回复受插件处理预算约束,默认上限为 120 秒;持续接收与解析应放在返回的流中。
初始流式回复后,流的寿命遵循模型请求期限与取消,受管 HTTP 正文每次读取单独计时。
持续有数据的流不会因初始 RPC 预算耗尽而结束,单次读取超时、客户端取消和流结束仍会回收资源
初始 RPC 回复默认限时 120 秒。持续接收与解析应放在返回的流中,遵循模型请求期限。受管 HTTP 正文每次读取单独计时,读取超时、客户端取消或流结束时回收资源
用量提交标准 `Usage`,费用由内置 Provider 按已冻结的上游模型与价格计算,响应回显模型不切换计价。
`observation.service_tier` 记录上游回显的最新档位,允许上游在完成时确定实际值;OpenAI 计价沿用请求策略,回显档位仅作观测。
@@ -15,7 +15,7 @@
| `WriteAggregates` | `usage.aggregates.write` | 按聚合键批量覆盖或删除统计贡献 |
| `EvaluatePricing` | `pricing.evaluate` | 根据当前价目或指定价格试算,逐项返回 `estimated` 或 `not_estimable` |
明细列表只列请求记录,聚合贡献参与统计但不生成请求明细。完整分组与全局总量使用下方统计读取,趋势使用既有统计查询
请求列表只含明细。全局与分组统计包含聚合贡献,趋势由统计查询提供
## 完整扫描与分组统计
@@ -93,21 +93,21 @@ async fn read_statistics(
## 聚合维护
`UsageAggregateKey` 由 `bucket_start_ms`、`dimensions` 和调用方的 `key` 共同构成。相同完整键的 `put` 覆盖旧值,重复提交相同内容不会累计;改变时间、维度或 `key` 会形成另一个目标,需要移动时由调用方删除旧键
`UsageAggregateKey` 由 `bucket_start_ms`、`dimensions` 和调用方的 `key` 组成。`put` 按完整键覆盖,重复提交不会累加。移动记录须写入新键并删除旧键
`dimensions` 支持 Provider、模型、账号、Key、操作和传输类型。`counts` 的键由 `UsageMetric` 定义,包括请求次数、各终态次数、已完成次数和各项 Token;`costs` 按币种保存十进制金额。计数与费用允许负值,供调用方表达统计修正
聚合按 `bucket_start_ms` 这个归属时间纳入 `[start_ms, end_ms)` 查询及趋势时间桶,宿主不自动摊分。导入日汇总时,调用方选择该日的归属时间;需要小时分布时,调用方自行提供小时数据
贡献按 `bucket_start_ms` 计入查询区间与趋势时间桶。日汇总不会自动摊到各小时,需要小时分布时须写入小时数据
查询只按实际提供的维度匹配,缺少的维度不会自动补全。未提供某个维度的贡献参与总量,完整分组读取使用独立未归属分组表达,其他维度查询只计入实际提供该维度的贡献。请求 ID、响应 ID、状态码、请求结果及文字搜索等明细筛选不包含聚合贡献,聚合也不生成延迟样本、尝试次数或请求列表页数。原生统计的无符号计数与非负金额若因贡献合计超出表示范围,查询返回错误,由调用方修正输入
贡献计入原生总量、趋势、维度统计和账号用量,维度匹配与越界处理见[分组与覆盖](#分组与覆盖)。按请求或响应 ID、状态码、请求结果或文字筛选时排除贡献。贡献不产生延迟样本、尝试次数或请求列表页数
聚合贡献参与原生总量、趋势、维度统计和账号用量,统计重建保留这些数据。贡献由调用方删除,不随请求历史保留任务清理;明细沿用请求历史保留策略
统计重建保留贡献,须由写入方删除。请求历史保留策略只清理明细
## 费用试算与写回
`EvaluatePricing` 使用 Provider 的原生单请求 Token 计价公式,支持当前价目和调用方指定的价格覆盖。OpenAI 与 xAI 提供此能力;不支持的 Provider、缺少必要 Token、图像用量或无法确定的价目返回 `not_estimable`
`EvaluatePricing` 按 OpenAI 或 xAI 的单请求公式,用当前价目或指定价格试算 Token 费用。须提供输入、输出、缓存读取、缓存写入和图像 Token,纯文本的图像 Token 填零。Provider 不支持、用量不全或价格未知时返回 `not_estimable`
试算输入需要明确输入、输出、缓存读取、缓存写入以及图像 Token;纯文本用量的图像 Token 填零。结果只包含 Token 费用,不自动处理图像、工具或其他附加费用,也不写入历史
试算不含图像、工具等附加费用,也不写入请求记录
调用方可查询明细、选择目标、逐条试算,再通过 `WriteRecords::Update` 写回费用。补全缺失时只处理 `unavailable`;全部覆盖时自行选择整个范围。日汇总若缺少逐请求分布,长上下文档位和逐请求舍入可能无法复现,计算方法由调用方决定
@@ -121,4 +121,4 @@ async fn read_statistics(
- 存储操作共享宿主观测连接与执行预算,超时、锁等待或取消会结束该次执行并释放资源
- 错误类型包括 `invalid_input`、`not_found`、`conflict`、`capacity_exceeded`、`unavailable`,分批读取还区分 `cancelled` 与 `timeout`
响应丢失时,调用方按稳定 ID 或聚合键查询、重试覆盖。宿主不保存任务、来源登记、幂等回执、调整历史或撤销计划;调用方负责来源映射、业务去重、重试策略、并发写入协调和恢复。服务输入不能指定审计主体,宿主从当前调用身份生成普通变更审计
响应丢失时,按稳定 ID 或聚合键查询后重试覆盖。调用方负责来源映射、去重、并发写入、进度、调整记录和恢复。宿主按当前调用身份记录变更审计,不提供幂等回执
@@ -5,6 +5,7 @@ use serde::{Deserialize, Serialize};
pub const ACCOUNTS_LIST: &str = "host.data.accounts.list";
pub const QUOTA_REFRESH: &str = "host.quota_observations.refresh";
pub const QUOTA_HISTORY: &str = "host.data.quota.history";
pub const QUOTA_GET: &str = "host.data.quota.get";
pub const KEYS_GET: &str = "host.data.keys.get";
pub const CLIENT_VERIFY: &str = "host.client.verify";
@@ -93,6 +94,35 @@ pub struct QuotaFactsQuery {
pub account_id: String,
}
/// UTC 毫秒半开区间;续页沿用原查询并原样传回游标
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct QuotaHistoryQuery {
pub account_id: String,
pub window_key: String,
pub start_ms: i64,
pub end_ms: i64,
pub cursor: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuotaHistorySample {
pub plan_type: Option<String>,
pub observed_at_ms: i64,
pub used_percent: f64,
pub reset_at_ms: Option<i64>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuotaHistoryPage {
pub schema_version: u32,
/// 请求完成时间倒序;空页也可能需要继续
pub samples: Vec<QuotaHistorySample>,
/// 最后一页才可能包含起点前的最近同桶观测
pub baseline: Option<QuotaHistorySample>,
pub next_cursor: Option<String>,
}
/// Provider 已有快照的必要投影;空观测时间表示没有可用样本,不代表额度为零
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuotaFacts {
@@ -72,11 +72,23 @@ pub enum ModelRouteDecision {
Reject,
}
/// 宿主在本轮调度中赋予候选的角色,与实时容量和已有会话绑定分开
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AccountScheduleRole {
Ordinary,
Preferred,
FollowOnly,
Pinned,
}
/// 候选账号的即时调度指标;凭据和账号资料通过宿主账号接口读取
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AccountScheduleCandidate {
pub account_id: String,
pub session_bound: bool,
pub role: AccountScheduleRole,
/// false 表示仅可等待,仍可被过滤,但不能作为本轮 Pick 的结果
pub available: bool,
pub weight: u16,
@@ -33,7 +33,7 @@ impl Capability {
| Self::RetryPolicy
| Self::Observer
| Self::Management => &[2],
Self::Scheduler => &[3],
Self::Scheduler => &[4],
Self::UpstreamAdapter => &[5],
Self::CommandLine | Self::Maintenance => &[1],
}
@@ -75,6 +75,17 @@ impl HostClient {
payload_call(self, data::QUOTA_GET, query).await
}
/// 按账号、额度桶和时间范围读取已保留的观测,不刷新上游
///
/// # Errors
/// 账号不存在、查询无效或宿主读取失败时返回错误
pub async fn quota_history(
&self,
query: data::QuotaHistoryQuery,
) -> Result<data::QuotaHistoryPage, PluginFault> {
payload_call(self, data::QUOTA_HISTORY, query).await
}
/// 读取已有额度窗口标签、触顶与点数事实,不触发刷新或补算
///
/// # Errors
@@ -1,8 +1,8 @@
//! 验证插件路由和账号调度决策的类型合同与附加字段透传边界
use gateway_plugin_sdk::call::policy::{
AccountScheduleCandidate, AccountScheduleDecision, AccountScheduleRequest, ModelRouteDecision,
ModelRouteRequest, PolicyHeader,
AccountScheduleCandidate, AccountScheduleDecision, AccountScheduleRequest, AccountScheduleRole,
ModelRouteDecision, ModelRouteRequest, PolicyHeader,
};
use serde_json::json;
@@ -49,6 +49,8 @@ fn route_and_scheduler_decisions_ignore_unused_fields() {
model: Some("gpt-5".into()),
candidates: vec![AccountScheduleCandidate {
account_id: "acct_candidate".into(),
session_bound: true,
role: AccountScheduleRole::Preferred,
available: true,
weight: 10,
in_flight: 1,
@@ -136,7 +136,7 @@ fn capability_contract_versions_are_checked_independently_of_rpc_version() {
(Capability::Middleware, Stage::Request, 6, true),
(Capability::Management, Stage::Management, 2, false),
(Capability::UpstreamAdapter, Stage::Upstream, 5, true),
(Capability::Scheduler, Stage::Scheduling, 3, false),
(Capability::Scheduler, Stage::Scheduling, 4, false),
(Capability::ModelCatalog, Stage::Registration, 2, false),
] {
for mut manifest in [source_manifest(), packaged_manifest()] {
@@ -286,7 +286,7 @@ fn contribution_ids_are_owned_unique_and_stage_bounded() {
Capability::Scheduler,
ContributionDeclaration {
id: "9acme.request-tags.scheduler".into(),
version: 3,
version: 4,
stages: vec![Stage::Scheduling],
input_formats: Vec::new(),
output_formats: Vec::new(),
@@ -6,6 +6,38 @@ const MULTI_AGENT_MODE_OPEN_TAG: &str = "<multi_agent_mode>";
const MULTI_AGENT_MODE_CLOSE_TAG: &str = "</multi_agent_mode>";
const PROACTIVE_MULTI_AGENT_MODE_PREFIX: &str = "Proactive multi-agent delegation is active.";
/// 标记实际入站的 Responses WS 帧,独立于出站传输偏好
pub const WEBSOCKET_FRAME_CONTEXT_KEY: &str = "websocket_frame";
/// 当前帧携带的完整元数据仅用于解释正文,握手或 HTTP 头保留各自的出站值
#[must_use]
pub fn observed_turn_metadata<'a>(
body: &'a Map<String, Value>,
header: Option<&'a str>,
websocket_frame: bool,
) -> Option<&'a str> {
if websocket_frame && let Some(frame) = client_metadata_string(body, "x-codex-turn-metadata") {
return Some(frame);
}
header
}
/// HTTP 请求使用本次请求头,WS 帧使用本次正文或首次握手头
#[must_use]
pub fn context_turn_metadata<'a>(
body: &'a Map<String, Value>,
context: &'a Map<String, Value>,
) -> Option<&'a str> {
observed_turn_metadata(
body,
context.get("turn_metadata").and_then(Value::as_str),
context
.get(WEBSOCKET_FRAME_CONTEXT_KEY)
.and_then(Value::as_bool)
== Some(true),
)
}
/// 各 Codex 端点共用的显式根会话身份
/// 连接边界的 session_id 优先,
/// 正文及官方 metadata 只做回退;不从 turn、window 或请求内容猜测归属
@@ -24,9 +56,7 @@ pub fn codex_account_session_id(
client_metadata_string(body, "session_id")
.map(str::to_owned)
.or_else(|| request_turn_metadata(body).and_then(turn_metadata_session_id))
.or_else(|| {
non_empty_string(context.get("turn_metadata")).and_then(turn_metadata_session_id)
})
.or_else(|| context_turn_metadata(body, context).and_then(turn_metadata_session_id))
.or_else(|| non_empty_string(body.get("session_id")).map(str::to_owned))
.or_else(|| codex_session_id(body, context))
}
@@ -40,9 +70,7 @@ pub fn codex_account_thread_id(
client_metadata_string(body, "thread_id")
.map(str::to_owned)
.or_else(|| request_turn_metadata(body).and_then(turn_metadata_thread_id))
.or_else(|| {
non_empty_string(context.get("turn_metadata")).and_then(turn_metadata_thread_id)
})
.or_else(|| context_turn_metadata(body, context).and_then(turn_metadata_thread_id))
.or_else(|| codex_thread_id(body, context))
}
@@ -64,7 +92,7 @@ pub fn codex_turn_id(body: &Map<String, Value>, context: &Map<String, Value>) ->
client_metadata_string(body, "turn_id")
.map(str::to_owned)
.or_else(|| request_turn_metadata(body).and_then(turn_metadata_turn_id))
.or_else(|| non_empty_string(context.get("turn_metadata")).and_then(turn_metadata_turn_id))
.or_else(|| context_turn_metadata(body, context).and_then(turn_metadata_turn_id))
.or_else(|| codex_identity_field(body, context, "turn_id"))
}
@@ -90,7 +118,8 @@ fn codex_identity_field(
.or_else(|| client_metadata_string(body, field))
.map(str::to_owned)
.or_else(|| {
let metadata = non_empty_string(context.get("turn_metadata"))
let metadata = context_turn_metadata(body, context)
.filter(|value| !value.trim().is_empty())
.or_else(|| request_turn_metadata(body))?;
let metadata: Value = serde_json::from_str(metadata).ok()?;
non_empty_string(metadata.get(field)).map(str::to_owned)
@@ -127,7 +156,7 @@ pub fn codex_responses_request_semantics(
) -> CodexResponsesRequestSemantics {
codex_responses_request_semantics_with_turn_metadata(
body,
context.get("turn_metadata").and_then(Value::as_str),
context_turn_metadata(body, context),
None,
)
}
@@ -3,6 +3,9 @@
/// OpenAI 线协议载荷与事件的协议标识
pub const OPENAI_PROTOCOL: &str = "openai";
/// 原生 Responses 客户端入口
pub const RESPONSES_PATH: &str = "/v1/responses";
/// Codex Responses Lite 的 HTTP 请求头
pub const X_OPENAI_INTERNAL_CODEX_RESPONSES_LITE_HEADER: &str =
"x-openai-internal-codex-responses-lite";
@@ -21,9 +24,10 @@ mod headers;
pub mod sse;
pub use codex::{
CodexResponsesRequestSemantics, codex_account_session_id, codex_account_thread_id,
codex_responses_request_semantics, codex_responses_request_semantics_with_turn_metadata,
codex_session_id, codex_thread_id, codex_turn_id, turn_metadata_session_id,
CodexResponsesRequestSemantics, WEBSOCKET_FRAME_CONTEXT_KEY, codex_account_session_id,
codex_account_thread_id, codex_responses_request_semantics,
codex_responses_request_semantics_with_turn_metadata, codex_session_id, codex_thread_id,
codex_turn_id, context_turn_metadata, observed_turn_metadata, turn_metadata_session_id,
turn_metadata_thread_id, turn_metadata_turn_id,
};
pub use headers::{
@@ -32,7 +32,7 @@ pub fn request_observation(
OPENAI_PROTOCOL => {
let semantics = codex_responses_request_semantics_with_turn_metadata(
body,
context.get("turn_metadata").and_then(Value::as_str),
crate::openai::context_turn_metadata(body, context),
previous_reasoning_effort_override,
);
RequestObservation {
@@ -454,7 +454,10 @@ impl AccountGroupStore for PgAccountGroupRepository {
.await
.map_err(|source| unavailable("check account group delete conflict", source))?;
if exists {
Err(conflict(command.id.as_str()))
Err(conflict(
command.id.as_str(),
ConflictKind::InvalidTransition,
))
} else {
Err(not_found_store(command.id.as_str()))
}
@@ -681,11 +684,15 @@ fn require_one(rows: u64, id: &str) -> StoreResult<()> {
}
fn map_group_write_error(error: sqlx::Error, id: &str) -> StoreError {
if error
.as_database_error()
.is_some_and(|database| database.is_unique_violation())
if let Some(database) = error.as_database_error()
&& database.is_unique_violation()
{
conflict(id)
let kind = if database.constraint() == Some("account_groups_name_uq") {
ConflictKind::DuplicateName
} else {
ConflictKind::InvalidTransition
};
conflict(id, kind)
} else {
unavailable("write account group", error)
}
@@ -703,12 +710,12 @@ fn not_found_store(id: &str) -> StoreError {
}
}
fn conflict(id: &str) -> StoreError {
fn conflict(id: &str, kind: ConflictKind) -> StoreError {
StoreError::Conflict {
source: None,
entity: ENTITY,
id: id.to_owned(),
kind: ConflictKind::InvalidTransition,
kind,
}
}
@@ -36,10 +36,8 @@ impl AnalyticsSnapshot<'_> {
|| filter.attempt_index.is_some()
|| filter.status_code.is_some()
|| filter.outcome.is_some()
|| filter.search.is_some()
|| filter.model_contains.is_some()
|| filter.client_api_key_name.is_some()
|| filter.provider_account_name.is_some()
|| filter.needs_observation_text()
|| matches!(
dimension,
Some(DiagnosticDimension::Failure | DiagnosticDimension::Status)

Some files were not shown because too many files have changed in this diff Show More