chore(release): v3.31.2

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

.agents/skills/cpr-dev-guide/SKILL.md

@@ -1,49 +1,57 @@
 ---
 name: cpr-dev-guide
-description: Codex Proxy RS 仓库的开发、修复、排障、代码审查和文档修改入口；PR、Issue、插件创作与发版按任务另用对应技能
+description: Codex Proxy RS 开发、修复、排障、代码审查和文档修改入口；页面、样式、文案、接口、调度、数据库及宿主 SDK、Runtime、插件接入均适用；PR、Issue、独立网关插件与发版叠加对应技能
 ---
 
 # 开发指南
 
-## 加载边界
+## 先确定领域与必读规范
 
-- 遵守已提供的 [AGENTS.md](../../../AGENTS.md)，上下文已有的规则不重复读取
-- 下表是条件导航，不是必读清单，只加载当前任务命中的技能与章节，进入新阶段再补读
-- 文档链接带 `#章节` 不代表读取工具会自动截取内容，先用 `rg -n '^#{1,4} ' 文件` 找边界，再按范围读取；常规定位不整份加载 CONTRIBUTING、架构、API、主题或全部 references，确需全文审查时再展开
-- 每次补读先明确要解决的未知项，已有资料足够就继续工作；文档提及 Rust、Vue、插件或发布，不等于要加载对应开发流程
+按用户意图、受影响行为与对象初判，定位后按实际文件复核，不要求用户说出“前端”“后端”或技能名。**所有命中行共同构成本次必读规范，先读完再确定方案、修改或给出审查结论**；跨领域叠加，不能只选最像当前步骤的一行
 
-## 按任务读取
+职责边界决定问题由谁修复；即使代码位于账号、调度或 API 模块，只要影响插件接入或为插件增加处理，也命中插件边界。确定方案时说明相关业务事实的归属及已有实现的复用依据，不能以功能恢复或测试通过替代职责判断
 
-| 当前任务 | 必读的相关部分 |
+| 领域或操作，行为影响与文件路径满足其一即可 | 确定方案前读取与执行 |
 | --- | --- |
-| 开发、排障、代码审查 | [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，需要定位代码时按 AGENTS 的 CodeGraph 约定执行 |
+| 调整页面、弹窗、表单、按钮、文案、样式或交互；目标在 `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) |
+| 开发、排查或审查服务端接口、路由、调度、账号与用量规则、持久化、后台任务或协议行为；目标是 `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)对应章节；优先复用已有接口，核对调用方 → 服务端解析 → 实际查询或执行，不能只凭前端类型认定参数生效；按实际改动叠加前后端规范 |
 | 模块或调用链变更 | [Workspace 边界](../../../docs/architecture.md#3-workspace-边界)及所属模块章节，不通读整份架构 |
-| Rust 开发或审查 | `$rust-best-practices`、所属模块、[后端自审](../../../docs/architecture.md#后端自审)，验证时读[命令](../../../docs/architecture.md#验证命令) |
-| 页面开发 | `$frontend-design`、[文案与信息层级](../../../docs/theme.md#界面文案与信息层级)、[界面验证](../../../CONTRIBUTING.md#界面验证)；修改已有页面前留存截图，主题算法仅在涉及时读取 |
-| 接口、部署或迁移 | 分别定位 [API](../../../docs/api.md)、[部署](../../../deploy/README.md)、[迁移](../../../backend/migrations/README.md)的对应章节 |
-| SDK、Runtime、宿主扩展或独立插件 | [插件职责边界](references/plugin-boundaries.md)；只有创作、排查独立网关插件时使用 [cpr-plugin-dev](../cpr-plugin-dev/SKILL.md) |
+| 新增、调整、清理或审查测试 | 下方[测试维护](#测试维护)，按当前行为、职责归属与已有覆盖判断保留、合并或删除 |
+| 修改部署行为、`deploy/` 配置或数据库迁移 | 按范围读取[部署](../../../deploy/README.md)、[迁移](../../../backend/migrations/README.md)对应章节 |
 | 修改或审查文档 | [文档检查](references/documentation.md)及目标章节，不默认读取代码开发、页面验收或发布流程 |
-| 普通代码审查 | [审查标准](../../../CONTRIBUTING.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} ' 文件` 定位，读取指定章节的完整内容。`#章节` 不会自动截取，“按需”仅用于未命中的领域和后续操作资料，不能省略必读规范；已有内容只在当前上下文可用且仍适用时复用，不循环重读技能
+
 ## 参考仓库的优先级
 
-- 涉及 Codex 行为、协议或兼容性时，以官方 [openai/codex](https://github.com/openai/codex) 对应版本的源码与调用链为第一手资料，先查官方实现
-- 优先使用用户提供或本机已有的官方仓库，核对来源、版本或提交；资料不足时再查官方对应版本的源码、测试与文档
-- 三方仓库只能提供排查线索或实现参考，不能代替官方行为依据；与官方不一致时回到官方源码核实，不直接照搬三方结论
-- 结论注明适用版本或提交，区分官方事实、三方参考与本项目推断；官方证据不足时保留不确定性
+开发、排障和代码审查先按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实问题与方案。涉及 Codex 行为时执行其中的官方行为优先约束：对应版本的官方源码优先，以透明转发和最小必要适配为默认方案，先判断偏离是否必要再评价实现
 
 ## 执行与收尾
 
-1. 确认工作区、任务范围与已有改动，先定位事实归属、同类实现和调用链，再修改；编码前只读[项目约定](../../../CONTRIBUTING.md#项目约定)的对应条目
-2. 自审完整差异，处理本次引入的职责越界、重复规则、冗余状态与无依据分支；仅审查时报告，不自行修复
-3. 按变更范围读取[验证](../../../CONTRIBUTING.md#验证)，区分通过、失败、跳过与未执行；提交时补读[提交约定](../../../CONTRIBUTING.md#项目约定)
-4. 交付说明实际结果与验证缺口；页面证据和后端生命周期检查按上表执行，不把构建通过当作行为验收
+1. 遵守已提供的 [AGENTS.md](../../../AGENTS.md)，按其 CodeGraph 约定定位代码；确认工作区、任务范围与已有改动，找到事实归属、同类实现和调用链，补齐上表命中规范及[项目约定](../../../CONTRIBUTING.md#项目约定)对应条目后再修改
+2. 以最终差异重新匹配上表，补齐新增领域的规范并检查实际实现，再处理本次引入的职责越界、重复规则、冗余状态与无依据分支；删除或替换功能时一并清理失效的配置、类型、调用、测试与文档，已部署数据和公开合同仍遵守所属迁移及兼容规则；仅审查时报告，不自行修复
+3. 常规文档只写当前状态；有文档差异时执行[文档检查](references/documentation.md)，没有时只确认现有说明是否失真，普通开发不自动修改 `release/notes.md`
+4. 按变更范围执行[验证](../../../CONTRIBUTING.md#验证)及其停止条件，后端命令见[验证命令](../../../docs/architecture.md#验证命令)；沿用本轮有效证据与用户已确定的验收分工，区分通过、失败、跳过与未执行；提交时补读[提交约定](../../../CONTRIBUTING.md#项目约定)
+5. 交付实际结果与验证缺口；前端按[前端流程](references/frontend.md)核对最终差异和运行证据，后端按上表检查生命周期，不把构建通过当作行为验收
 
-## 文档硬约束
+## 测试维护
 
-**常规文档只描述当前状态，不写变更历史**，这项检查适用于每次开发收尾，不限于专门的文档任务
+- 测试随当前功能维护，名称、夹具和断言描述当前输入、行为与结果；功能变更时优先更新所属模块的现有用例，不为每次改动叠加一组记录变更经过的测试
+- 清理只证明旧字段、旧路由或旧实现已经消失的用例与附带断言；未知字段校验使用合法请求基线加无业务含义的未知字段，避免因缺少必填项等其他错误而误通过
+- 同一层对同一行为的重复覆盖合并为清晰的场景矩阵，复用相邻测试夹具；跨层测试确有不同职责或失败路径时保留，不为统一而扩大测试辅助抽象
+- 断言可观察的行为与业务不变量，避免复述结构体赋值、罗列表列或字段清单、匹配 SQL 文本与源码布局；项目明确要求的架构边界检查继续维护
+- 当前协议兼容、数据读取兼容、安全边界、并发和资源生命周期仍需覆盖，不按 `old`、`legacy` 等名称机械删除，也不能用改名代替无效用例清理
+- 不在仓库中新增或保留迁移 SQL 专项测试，包括迁移文本、schema 演变与指定版本升级用例；需要验证迁移执行、数据保留或回滚时，在临时目录编写一次性验证并使用隔离数据库，测试通过即可，临时脚本不纳入维护测试集
+- 持久化功能测试使用当前完整 schema，验证现行读写、事务与数据约束；插件运行时状态迁移等业务能力按当前功能测试，不归为迁移 SQL 专项测试
 
-- 动笔前确定读者、所属章节与必须说明的当前事实，没有必要就不改文档
-- 有文档差异时执行[文档检查](references/documentation.md)，逐段决定保留、改写、删除或移入任务报告，未完成内容审查不能称文档已检查
-- 没有文档差异时只确认现有说明是否失真；普通开发不自动修改 `release/notes.md`
+## 后端注释
+
+- 每个 Rust 文件顶层使用简短的中文 `//!` 注释说明文件职责，覆盖生产源码、测试与构建脚本；测试文件说明测试范围或辅助用途，生成文件同步维护生成器
+- 注释不使用中文或英文句号，多句说明按语义分行；保留 URL、版本号、标识符和代码示例中有语义的点号
+- 文件说明聚焦当前功能与职责边界，局部注释解释原因和约束，避免复述代码或记录修改经过

.agents/skills/cpr-dev-guide/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "cpr-dev-guide"
-  short_description: "仓库开发、修复、排查、代码审查与文档修改的流程入口"
-  default_prompt: "使用 $cpr-dev-guide 按当前任务定位问题与现有实现，完成已授权的开发或审查，并自审、验证和报告结果。"
+  short_description: "开发、排障与审查入口，按行为影响匹配领域边界并验证实现"
+  default_prompt: "使用 $cpr-dev-guide 按请求、行为影响和实际文件匹配领域必读规范，读完职责边界再确定方案，完成已授权的开发或审查、自审与验证。"
 policy:
   allow_implicit_invocation: true

.agents/skills/cpr-dev-guide/references/documentation.md

@@ -1,16 +1,10 @@
 # 文档检查
 
-仅在准备修改文档或最终差异含文档时读取，职责与行文依据是 [文档职责与更新条件](../../../../CONTRIBUTING.md#文档职责与更新条件)，只读该节
+修改或审查文档时完整读取本流程，并读取 [文档职责与更新条件](../../../../CONTRIBUTING.md#文档职责与更新条件)的完整章节，覆盖内容归属与层次行文
 
 ## 写之前
 
-先明确这段内容服务谁、解决哪个当前使用或维护问题、属于哪个现有章节，再决定详略
-
-接口保留调用合同，架构保留职责与不变量，部署保留操作与排障；同一事实只在所属位置完整说明，其他位置链接
-
-常规文档在原章节修订，不追加本次变更小节，不为了“同步文档”补写修复总结
-
-内部重构、实现经过、前后对比、验证结果应留在 PR、Issue 或任务报告
+先确定读者、必须说明的当前事实与所属章节，再决定是否需要修改及详略；文档职责与更新条件按上节核对。涉及合同或职责说明时，补读所属架构、API 或 SDK 的对应条款，核实事实；不因文档提及实现而执行无关的开发与构建流程
 
 ## 逐段验收
 
@@ -30,9 +24,8 @@
 
 ## 交付检查
 
-- 检查新段落的必要性、归属、重复与当前状态表达，发现变更叙述先改完再交付
-- 标题、短列表、表格和独立短段通常不加句号，长段按主题拆分，命令与字段保持准确
+- 完成上述逐段验收及[行文检查](../../../../CONTRIBUTING.md#层次与行文)，发现问题先处理，未完成内容审查不能称文档已检查
 - 检查相对链接、章节锚点、表格与命令示例，`git diff --check` 或构建通过不能代替内容审查
 - 报告实际覆盖和缺口即可，不把检查记录写进常规文档
 
-只有明确的发布说明任务才进入 `cpr-release`，`release/notes.md` 用于该次发行，不向 README、API、架构或部署文档复制版本变化列表
+只有明确的发布说明任务才进入 `cpr-release`；发布说明与常规文档的边界按[内容归属](../../../../CONTRIBUTING.md#内容归属)执行

.agents/skills/cpr-dev-guide/references/frontend.md

@@ -0,0 +1,34 @@
+# 前端开发与审查
+
+适用于页面、组件、弹窗、表单及局部文案和样式修改，不以是否创建 PR 为触发条件；仅审查时核对和报告，不自行修改
+
+## 领域必读
+
+确定页面方案或审查结论前，读取[前端职责](../../../../docs/architecture.md#34-前端模块职责)、[文案与信息层级](../../../../docs/theme.md#界面文案与信息层级)和[界面验证](../../../../CONTRIBUTING.md#界面验证)的完整章节；只改文案或局部样式也执行。明确本次用户操作、原页面、最接近的同类实现及可复用基础组件，沿用既有设计与请求层，按本轮验收分工留存所需截图
+
+## 按改动补齐规范
+
+用户要求看效果或自行验收时，按[源码联调](../../../../docs/development.md#源码联调)提供当前工作区的可访问预览与页面入口，确认热更新和依赖来源；需要模拟数据时用于实际页面并标明，不把静态稿、旧构建或仅有本机文件路径当作可用预览
+
+按改动补读，不把“未修改主题算法”当作跳过页面样式规范的理由：
+
+| 改动 | 规范入口 |
+| --- | --- |
+| Vue 组件、逻辑、请求或状态 | 使用 `$vue-best-practices`，读取[项目约定](../../../../CONTRIBUTING.md#项目约定)的前端条目；请求与接口合同同时执行开发入口的 API 分支 |
+| 颜色、间距、字体、边框、阴影、局部 CSS 或交互样式 | [通用颜色消费](../../../../docs/theme.md#通用颜色消费)、[样式与命名约定](../../../../docs/theme.md#样式与命名约定)，核对无边常态及 Hover、Focus 等视觉状态 |
+| 主题算法、编辑器或共用组件视觉行为 | 所改主题章节及[扩大验证范围](../../../../docs/theme.md#验证) |
+| 明确指定设计技能，或建立、重塑视觉方向 | 使用指定技能或 `$frontend-design`，设计取舍仍以项目主题、用户任务和已有页面为依据 |
+
+普通维护和新增业务页面沿用现有设计；设计技能中的配色、字体、布局探索不覆盖项目规范，主题算法只在涉及时读取
+
+## 交付前
+
+对照最终差异和实际页面逐项核对，不以读取过规范代替检查：
+
+- **复用与范围**：是否沿用参考页面和基础组件，已有组件能承载时不手写替代控件；共用缺陷按职责修复，修复后清理本次已失效的页面补丁，不顺带重排无关区域或新增重复入口
+- **文案与层级**：标点是否合规，标题、状态和帮助是否重复，详细说明与当前决策必需提示的位置是否合适
+- **样式与状态**：是否使用对应 Token 与 utility，局部样式是否符合适用边界，受影响的主题、窄屏及交互状态是否正确
+- **查询与动作**：区分首次加载、刷新、分页、单行与批量操作，核对 loading、禁用状态的影响范围；沿用请求层错误处理，不在页面叠加同一错误的提示
+- **运行证据**：按界面验证核对截图与实际交互，证据对应当前实现；页面 PR 的可访问图片和 Draft 条件按该节执行
+
+交付简述所复用的页面或组件、实际验证范围及缺口；环境不足时如实说明，不能仅凭构建、源码或截图推断未验证的行为

.agents/skills/cpr-dev-guide/references/plugin-boundaries.md

@@ -1,11 +1,15 @@
 # 插件职责边界
 
-仅在开发或审查 SDK、Runtime、宿主扩展接口及独立网关插件时读取
-先看[插件扩展](../../../../docs/architecture.md#31-插件扩展)中的职责与执行边界，不通读整份架构
+开发、排查或审查插件接入、SDK、Runtime、宿主扩展接口及独立网关插件时完整读取，不以文件位于插件目录或正在选择能力为条件
+确定方案前读取[职责与源码入口](../../../../docs/architecture.md#职责与源码入口)、[发布与执行边界](../../../../docs/architecture.md#发布与执行边界)及[信任与资源边界](../../../../docs/architecture.md#信任与资源边界)，明确问题归属、必要宿主保护与插件责任
 
-**宿主可以暴露底层能力，不能替插件完成业务**
+**宿主提供可组合能力，守住自身合同、资源与稳定性；插件业务正确性和兼容修复由插件负责**
 
 - 宿主提供可独立组合的受控原生能力，负责授权、资源隔离、事务与审计，复用已有服务与状态归属
 - 插件自身的触发条件、跨资源关联、策略和流程编排由插件实现，不能把某个使用场景做成宿主专属流程、状态或补偿逻辑
-- 发现能力缺口时，界定可独立使用的基础接口，说明输入输出、权限、事务、失败及重复调用语义，不夹带插件私有数据模型或工作流
-- 自审调用链、合同、测试与文档中的业务判断、自动串联和专属状态，仅换成通用名称不算解除耦合
+- 插件行为不可预测，只保留宿主安全解码、权限、资源限制及一致性所需的检查，不为插件业务正确性增加语义校验、未知字段拒绝或重复检查；失败按已有调用、会话、实例边界及能力策略拒绝、隔离和回收，不把单次业务错误扩大为全局停用
+- 不靠猜测插件意图、补造业务字段、修正业务结果、重放操作或增加插件专属兼容分支让错误插件继续工作；问题归插件时在插件侧修复，不把补偿搬进宿主 SDK 或 Runtime
+- 通用协议与会话辅助、公开合同规定的默认值和失败恢复仍按既有合同执行，不能因拒绝业务兜底而删掉必要的宿主保护；故障隔离按[信任与资源边界](../../../../docs/architecture.md#信任与资源边界)评估，不假定完整信任的插件具有安全沙箱
+- 开放已有能力时复用宿主服务与数据模型，不为插件的导入、修正、重算等编排新增表、字段、账本或任务系统；确有宿主能力缺口时，界定可独立使用的基础接口及输入输出、权限、事务、失败和重复调用语义，不夹带插件私有模型与工作流
+- 新增防御、兼容、重试、缓存或状态前，说明要保护的宿主不变量、触发依据和最小处理范围；仅为迁就某个插件或猜测未来行为时不加入宿主
+- 自审调用链、合同、测试与文档中的业务判断、自动串联和专属状态，仅换成通用名称不算解除耦合；验证失败与取消后的资源释放、状态一致性和其他调用受影响范围，不以插件恢复成功代替宿主边界验证

.agents/skills/cpr-github-issue/SKILL.md

@@ -13,14 +13,16 @@ description: 草拟、创建、补充或回复 GitHub 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 时，读取本仓库的[提交 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 的表单
 - 其他仓库读取它自己的相关规则与实际模板，长文档先定位标题再截取，不预读全部模板或 CONTRIBUTING
 - 搜索同场景 open/closed Issues、相关 PR 和发布记录，区分主分支修复与已发布修复，不凭标题判断重复；没有新证据时返回已有链接，用户仍要求新建则按其要求处理
-- 仅当需要额外排查或修改时使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，提交症状反馈不以找到根因为前提
-- 引用上游行为或提出方案时读取[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，涉及 Codex 时按[参考仓库优先级](../cpr-dev-guide/SKILL.md#参考仓库的优先级)先查官方 Codex 源码，三方仓库仅作参考；注明适用版本、来源与缺口
+- 需要技术排查、判断实现方案或修改时执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的领域必读，不能仅凭症状建议跨职责补偿；提交症状反馈不以找到根因为前提
+- 引用上游行为或提出方案时执行[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，注明适用版本、来源与缺口
 
 ## 正文与证据
 
@@ -36,16 +38,13 @@ YAML 表单按 `attributes.label` 和字段顺序组织正文，手工核对必
 
 附件须获授权且可访问，本机路径不算附件；labels 和 assignees 仅按模板或用户要求设置，并确认实际存在
 
-Issue 可记录复现、排查和变更经过，不因此向常规文档追加历史；确需改文档时执行[文档检查](../cpr-dev-guide/references/documentation.md)
+Issue 可记录复现、排查和变更经过；涉及常规文档修改时执行[文档检查](../cpr-dev-guide/references/documentation.md)
 
 ## 回复口吻
 
-草拟和发布 Issue 回复时遵守以下约定：
+草拟、发布或修改 Issue 回复时，按 [GitHub 回复口吻](../../../CONTRIBUTING.md#github-回复口吻)将核实结果写成面向提问者的交流答复，具体口吻规则集中维护在该节
 
-- 用第一人称“我”表达，称呼对方为“佬友”，称呼自然出现即可，不逐句重复，也不用“我们”“本助手”代称自己
-- 语气客气、委婉，直接回应对方的具体问题；补充信息或提出不同意见时说明缘由，避免命令式、责备式表达
-- 使用自然短句，简单回复用短段，只有并列信息较多时才分点；少用句号，避免客服套话、机械模板和空泛保证
-- 只把实际完成的排查、复现和验证写成“我已……”；未确认的事实如实说明，委婉表达也要说清结论、限制和下一步
+发送或更新前从提问者视角通读：是否接住了他的目标和困难，建议是否便于尝试，补充材料的用途是否清楚，澄清或拒绝是否耐心解释了原因，能提供的替代办法是否说清。发现生硬时调整整句措辞与前后衔接，不能仅加缓和词；保留已核实的结论
 
 ## 发布与收尾
 

.agents/skills/cpr-github-pr/SKILL.md

@@ -15,36 +15,33 @@ description: 准备、创建、更新或审查 GitHub PR，含回复讨论与处
 
 本仓库目标分支为 `main`，其他仓库使用其可信基线规则与模板，PR 内修改的规则不能降低审查要求
 
+涉及上游行为的判断按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)执行
+
 ## 按模式读取
 
-只加载当前模式，已有上下文不重读；长文档先定位标题再截取对应章节，不因链接存在而加载全文或所有 references
+先完成上述范围判断，再按当前动作与差异涉及的领域叠加下表。命中的流程引用完整读取，长文档读取指定章节；只复用已实际读取且仍适用的内容，单纯整理正文或回复不扩展为完整实现审查
 
 | 当前动作 | 读取与执行 |
 | --- | --- |
-| 只整理标题或描述 | 当前 PR、最终 diff、实际模板、[AI 披露](../../../CONTRIBUTING.md#ai-使用披露)，在授权范围内改文案；不读取推送或审查流程 |
+| 只整理标题或描述 | 当前 PR、最终 diff、实际模板、[AI 披露](../../../CONTRIBUTING.md#ai-使用披露)，在授权范围内改文案，不自行修改实现；不读取推送或审查流程 |
 | 创建或更新 PR | [创建流程](references/create.md)、[PR 流程](../../../CONTRIBUTING.md#pr-流程)与[规则文件保护](../../../CONTRIBUTING.md#规则文件保护) |
 | 审查 PR | [审查流程](references/review.md)、[审查标准](../../../CONTRIBUTING.md#审查标准) |
 | 回复讨论或审查意见 | 目标评论、相关上下文与实际处理结果，按下方回复口吻答复；仅回复不加载创建或完整审查流程 |
-| 需要修改代码或文档 | 使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的对应分支，完成自审与验证 |
-| 含页面改动 | [界面验证](../../../CONTRIBUTING.md#界面验证)，必需截图须可访问且对应当前实现 |
-| 含文档改动 | [文档检查](../cpr-dev-guide/references/documentation.md)，常规文档只说明当前状态，变更经过留在 PR |
+| 实现自审、审查或修改代码与文档 | 执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的领域必读与对应检查，包括后端、插件、测试和 API 等命中项；只读审查同样执行，不能仅核对 PR 正文与 CI |
+| 含前端改动 | [前端流程](../cpr-dev-guide/references/frontend.md)，核对适用规范与当前实现的运行证据 |
+| 含文档改动 | [文档检查](../cpr-dev-guide/references/documentation.md) |
 
 ## 回复口吻
 
-草拟和发布 PR 讨论、审查意见的回复时遵守以下约定：
-
-- 用第一人称“我”表达，称呼对方为“佬友”，称呼自然出现即可，不逐句重复，也不用“我们”“本助手”代称自己
-- 语气客气、委婉，直接回应对方的具体问题；补充信息或提出不同意见时说明缘由，避免命令式、责备式表达
-- 使用自然短句，简单回复用短段，只有并列信息较多时才分点；少用句号，避免客服套话、机械模板和空泛保证
-- 只把实际完成的修改和验证写成“我已……”；未采纳的意见说明依据，待处理或未验证的内容如实交代，委婉表达也要说清结论和下一步
+草拟和发布 PR 讨论、审查意见的回复时，执行 [GitHub 回复口吻](../../../CONTRIBUTING.md#github-回复口吻)
 
 ## 创建与审查的公共核对
 
-- 按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实触发条件、发生版本与目标分支现状；涉及 Codex 时按[参考仓库优先级](../cpr-dev-guide/SKILL.md#参考仓库的优先级)先查官方 Codex 源码，三方仓库仅作参考
+- 按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实触发条件、发生版本与目标分支现状，分别判断问题是否成立、是否属于目标项目职责及方案是否必要
 - 核对最新目标分支及同场景 open/closed PR、Issue，按实际行为和测试判断重复，不凭标题下结论，也不擅自关闭他人 PR
-- 自审或审查覆盖完整差异与调用链，文档逐段检查必要性、职责、重复和当前状态表达，构建与链接检查不能代替内容判断
+- 自审或审查覆盖完整差异与调用链，前端与文档按模式表检查
 - 核对[AI 使用披露](../../../CONTRIBUTING.md#ai-使用披露)，填写实际工具与模型，不猜型号；必需截图或型号待补时保留 Draft
-- 验证结果对应实际 head，区分通过、失败、跳过与未执行；无文档改动时只检查现有说明是否失真
+- 验证结果对应实际 head，区分通过、失败、跳过与未执行；无文档改动时只核对现有说明是否失真
 
 远程操作优先使用可用连接器，`gh` 显式指定 `--repo`，多行正文使用结构化字段或 `--body-file`
 

.agents/skills/cpr-github-pr/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "cpr-github-pr"
   short_description: "提交、更新与审查 PR，核对问题、自审、页面截图和 AI 模型披露"
-  default_prompt: "使用 $cpr-github-pr 按当前请求准备、提交、更新或审查 PR，核实问题与方案，检查自审、验证、页面截图和 AI 模型披露。"
+  default_prompt: "使用 $cpr-github-pr 按当前请求准备、提交、更新或审查 PR，实现自审与审查叠加开发指南的领域规范，核实问题、方案、验证、页面截图和 AI 模型披露。"
 policy:
   allow_implicit_invocation: true

.agents/skills/cpr-github-pr/references/create.md

@@ -6,19 +6,13 @@
    不用提交日志拼接正文，也不假定仓库一定有模板。
 2. 更新并确认 base/head，查看相对 merge-base 的完整差异和待提交内容；核对仓库的受保护文件与准入规则。
    只纳入任务范围的文件和提交；需要整理时用独立功能分支，保留用户其他改动，不擅自改写已发布历史。
-3. 按入口的公共核对，在目标分支基线核实问题，追踪官方与本项目的相关调用链，先确定解决方向再实现。
-   若改动已完成，也要据此复核问题与方案；需要修正时只修改已授权的范围。仅整理标题或正文时报告差异与缺口，
-   不自行修改实现。原问题不成立时不将它包装成已修复的缺陷；证据不足时明确保留结论。
-   按 `cpr-dev-guide` 完成实现自审；后端按 [后端自审](../../../../docs/architecture.md#后端自审) 核对归属、状态、失败出口与副作用，
-   页面先复用已有设计并检查文案密度。处理本次引入的冗余与越界问题，功能可用和检查通过不能替代可维护性自查。
+3. 已完成的改动也须按入口公共核对复核问题与方案。原问题不成立时不包装成已修复的缺陷，证据不足时保留结论。
+   实现与自审按 [cpr-dev-guide](../../cpr-dev-guide/SKILL.md)执行，包括适用的后端生命周期和前端检查；需要修正时只修改已授权范围。
 4. 查找同一来源仓库、head 和 base 的现有 PR；已存在则复用其链接，不重复创建。
    更新现有标题或正文须在本次整理/更新请求范围内。
-5. 按[验证](../../../../CONTRIBUTING.md#验证)执行适用检查。记录实际验证的提交或工作区状态，区分通过、失败、跳过和未执行。
-   有文档差异时按[文档检查](../../cpr-dev-guide/references/documentation.md)检查最终 diff；没有文档差异时，核对行为变化是否使现有说明失真。
-   页面改动按入口链接的界面验证要求补齐截图与实际交互证据，核对模型披露是否完整。
+5. 按[验证](../../../../CONTRIBUTING.md#验证)执行适用检查，记录对应提交或工作区状态；文档、页面证据与模型披露按入口核对。
 6. 将任务范围内的提交推送到正确远端，核对远端 head。标题遵循项目约定，正文先说明问题成立的依据和最终行为，
-   再给必要的设计取舍、自审结论、验证与遗留事项，按模板附页面截图和 AI 使用情况。涉及官方行为时，写明官方源码位置与版本或提交、官方处理方式、
-   本次实现与它的关系及必要的偏离原因；区分源码推断和实际复现，不用检查通过替代方案论证。按规模压缩，不强填无关章节。
+   再给必要的设计取舍、自审结论、验证与遗留事项，按模板附页面截图和 AI 使用情况。涉及上游行为时，按[问题与方案依据](../../../../CONTRIBUTING.md#问题与方案依据)写明官方源码位置、版本、处理方式及本次方案关系。按规模压缩，不强填无关章节。
 7. 明确要求草稿或仍有阻塞项时创建或保持 Draft PR，并解释原因；必需截图或 AI 模型披露待补时也不标为可审阅。具备审查条件且未要求草稿时创建普通 PR。
    GitHub Draft 状态与“只写本地草稿正文”不同，后者不创建远程对象。
 8. 创建或更新后回读正文与附件，核对链接、base、head、草稿状态、模型披露和最新检查结果。网络超时或结果不确定时先查询远端，再决定是否重试。
@@ -32,4 +26,4 @@ gh pr create --repo "$pr_repo" --base "$pr_base" --head "$pr_head" \
 
 按需添加 `--draft`。不要用 `gh pr create --dry-run` 做只读预览，它仍可能推送 Git 变更。
 多行正文通过文件或连接器的结构化字段传递，不把未转义正文拼进 shell 命令。
-创建完成返回链接、目标分支和验证摘要；不要称为已合并或已获维护者批准。
+创建完成返回链接、目标分支和验证摘要，不称为已合并。

.agents/skills/cpr-github-pr/references/review.md

@@ -4,28 +4,19 @@
 
 1. 获取 PR 的 base/head SHA、描述、文件差异、已有讨论及 CI 状态。记录实际审查的 head，使用 merge-base 差异。
    需要源码上下文时先遵守目标仓库的定位规则；需检出时使用隔离工作区，保留用户当前分支和运行环境。
-2. 先核实 PR 要解决的问题是否成立：提取触发场景、预期行为和声称的原因，在目标分支基线检查实际行为。
-   按入口的公共核对收集一手证据，区分原有问题、环境或配置差异与 PR 新引入的问题，说明主分支已覆盖的部分。
-3. 从官方方案评估解决方向：说明官方如何处理同一场景，检查 PR 是否遵循其协议语义和职责归属、
-   是否复用已有能力或正确传递官方合同；核对偏离官方方案的理由与运行证据。
-   审查 OpenAI 官方上游与 Codex 的对接时，默认官方返回与 Codex 兼容、直接对接正常，重点检查本项目是否误解、
-   改写或破坏官方合同。不得仅凭自行构造的异常上游数据揣测官方不兼容，也不据此报告缺陷、提出改进建议，
-   或要求增加防御分支与测试。讨论特定版本或场景的对接例外须有真实响应或实际复现证据，并区分代理链路与官方直连。
-4. 按贡献文档的审查维度追踪完整调用链，找到共享业务事实、同类实现及已有验证。
+   按实际行为与文件执行 [cpr-dev-guide](../../cpr-dev-guide/SKILL.md)的领域必读，再判断方案与实现；只读审查也核对职责边界与生命周期。
+2. 按入口公共核对在目标分支基线核实问题，区分原有问题、环境或配置差异与 PR 新引入的问题，说明主分支已覆盖的部分。
+3. 按[问题与方案依据](../../../../CONTRIBUTING.md#问题与方案依据)评估解决方向，涉及上游时说明官方处理方式及本次方案关系；缺少必要性依据的偏离明确指出，不因测试通过就认定方案合理。
+4. 按[审查标准](../../../../CONTRIBUTING.md#审查标准)追踪完整调用链，找到共享业务事实、同类实现及已有验证。
    对既有特殊分支查清服务的场景，再判断本次改动是否引入或加重问题。
    主动检查本次变更新引入或加重的冗余与代码异味，说明具体位置、维护成本或行为影响及最小修复方向；
    不能仅因功能可用、CI 通过而略过，也不把个人写法偏好判为缺陷。
-5. UI 改动同时对照原页面、主题、共用组件和同类页面，核对结构变化的必要性、文案是否重复及帮助是否适合收进 Popover。
-   按页面类型检查必需截图是否齐全、可访问且对应待审实现；缺少必需截图时要求补齐并列为未具备审阅条件。
-   浏览器可用时检查相关交互；未运行的检查列为验证缺口，不从截图或源码推断所有状态都正确。
+5. 前端改动执行[前端流程](../../cpr-dev-guide/references/frontend.md)，浏览器可用时检查相关交互；缺少必需截图时要求补齐并列为未具备审阅条件。
 6. 核对 CI 与本地证据是否覆盖当前 head；根据风险补充必要验证，不触发无关部署或真实账号业务请求。
-   有文档差异时按[文档检查](../../cpr-dev-guide/references/documentation.md)检查最终 diff，不能把构建或链接检查通过当作文档内容已经合格。
+   文档差异按[文档检查](../../cpr-dev-guide/references/documentation.md)核对最终 diff。
    核对 AI 使用与模型披露，缺项明确指出。工具不可用、集成测试跳过或环境不足时具体说明影响范围。
-7. 按 [审查标准](../../../../CONTRIBUTING.md#审查标准) 用中文先回答原问题是否成立、解决方向是否合理，
-   再列出实现问题与验证缺口，结论附具体依据。
-   实现问题区分必须修复项、可选建议和验证缺口；没有的类别可省略。
-   每个问题给变更中的文件位置、触发条件或规范依据、影响和最小修复方向。
-   复用建议指出具体已有实现，不把个人偏好写成缺陷；未发现问题时直接说明并交代覆盖范围。
+7. 按审查标准用中文输出问题是否成立、方案是否合理及对应依据，再列实现问题与验证缺口；复用建议指出具体已有实现。
+   没有问题的类别可省略，未发现问题时直接说明并交代覆盖范围。
 8. 结束前核对 head 是否变化。发生变化时检查新增差异并更新结论，或明确结论只适用于原 SHA。
 
 审查本身不修改源码、不发表评论、不提交 GitHub 的批准或请求修改状态。

.agents/skills/cpr-plugin-dev/SKILL.md

@@ -1,39 +1,43 @@
 ---
 name: cpr-plugin-dev
-description: 开发、排查或打包 Codex Proxy RS 独立网关插件；仅改宿主 Runtime、安装器或管理端时使用 cpr-dev-guide，不适用于 Codex 插件或 Vue 插件
+description: 开发、修复、排查、审查或打包 Codex Proxy RS 独立网关插件，含处理器、清单与插件页面；仅改宿主能力时使用 cpr-dev-guide 的插件边界，不适用于 Codex 插件或 Vue 插件
 ---
 
 # 网关插件开发
 
-插件在独立项目中通过公开 SDK 实现业务，不向宿主业务模块添加专属流程
+## 先读职责边界
 
-同时使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的对应任务分支，已加载则复用，不递归重读
+插件在独立项目中通过公开 SDK 实现业务，插件业务错误在插件侧修复；宿主维护自身合同、资源与稳定性，不猜测插件意图、不补造业务数据，不在宿主、SDK 或 Runtime 中增加插件专属补偿
+
+开发、排查和审查先完整读取[插件职责边界](../cpr-dev-guide/references/plugin-boundaries.md)，再选择实现步骤；已有处理器修复和页面改动也执行，不以是否新增能力为条件。需要新增宿主能力时，先界定可独立使用的基础接口及其职责；必要的协议保护与资源回收仍由宿主负责
+
+同时执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的领域必读与收尾要求；已实际读取且仍适用的内容复用，不递归重读入口。仅构建、打包或分发已有插件时按对应操作读取，若需诊断或修改行为，再补齐开发分支
 
 ## 范围与合同
 
 - 确认用途、工程位置、目标宿主版本与平台，沿用已有工程；位置无法推断时只补齐该信息，不把插件源码塞进宿主 workspace
 - 核对运行宿主、[SDK 版本](../../../backend/crates/gateway-plugin/sdk/Cargo.toml)、[宿主支持清单](../../../backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json)及所用 CLI，清单、进程和能力版本分别判断
-- `contributes` 是能力，`permissions` 是访问域，`bindings` 是挂载与匹配范围；安装成功不等于功能生效，`trustedProcess` 也不是操作系统沙箱
-- 涉及 Codex 时按[参考仓库优先级](../cpr-dev-guide/SKILL.md#参考仓库的优先级)先查官方 Codex 源码，三方仓库仅作参考；宿主能力以目标版本的 SDK 为准
+- `contributes` 声明处理器，`bindings` 选择挂载与匹配范围；安装成功不等于功能生效。当前清单拒绝 `permissions`，安装者完整信任插件，`trustedProcess` 不提供操作系统沙箱或访问域隔离，见[完整信任](../../../backend/crates/gateway-plugin/sdk/docs/manifest.md#完整信任)
+- Codex 兼容性适配按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)执行，不因位于插件中扩大改写或补偿范围；业务改写限于用户授权，宿主能力以目标 SDK 为准
 
 ## 按当前步骤读取
 
-只读取命中行与链接的指定章节，长文档先列标题再截取；不预读全部 SDK、示例、前端和打包资料
+完成上述适用边界后，按当前步骤读取下表；同时涉及多项时叠加。命中的实现或页面参考完整读取，长文档读取指定章节，示例、前端和打包资料在对应步骤加载
 
 | 当前工作 | 入口 |
 | --- | --- |
-| 选择能力或确认能力缺口 | [能力与方法](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#能力与方法)、所需能力章节、[插件职责边界](../cpr-dev-guide/references/plugin-boundaries.md) |
-| 清单与 Rust 处理器 | [实现参考](references/implementation.md)、所用 SDK 类型；只有修改清单字段时读[清单](../../../backend/crates/gateway-plugin/sdk/docs/manifest.md)对应章节 |
-| 创建或修改页面 | [页面参考](references/frontend.md)，不需要页面的插件不创建前端 |
+| 选择、使用或审查能力 | [能力与方法](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#能力与方法)及所用能力章节，不以已有调用能编译代替合同核对 |
+| 开发、排查或审查清单与 Rust 处理器 | [实现参考](references/implementation.md)、所用 SDK 类型；涉及清单字段时读[清单](../../../backend/crates/gateway-plugin/sdk/docs/manifest.md)对应章节 |
+| 创建、修改或审查页面 | [页面参考](references/frontend.md)，不需要页面的插件不创建前端 |
 | 准备工程或联调依赖 | [工程与依赖](references/development.md#工程与依赖)，需要示例时再读[复用示例](references/development.md#复用示例) |
 | 构建或打包 | [构建与打包](references/development.md#构建与打包) |
 | 实际验收 | [验证与交付](references/development.md#验证与交付)，按实现范围验证 |
 | 分发插件 | [发布与安装来源](references/development.md#发布与安装来源)，不自动进入宿主发版流程 |
-| 修改插件文档 | [文档检查](../cpr-dev-guide/references/documentation.md)，只写当前用法、合同和限制，不附修复过程 |
+| 修改插件文档 | [文档检查](../cpr-dev-guide/references/documentation.md) |
 
 ## 交付
 
-说明源码与产物位置、兼容范围、能力与权限、实际验证及缺口，只报告真正生成的安装包或完成的业务验证
+说明源码与产物位置、兼容范围、能力与绑定、实际验证及缺口，只报告真正生成的安装包或完成的业务验证
 
 修改源码不默认授权在目标实例安装启用、调用真实上游或发布，沿用用户当前授权判断后续动作
 

.agents/skills/cpr-plugin-dev/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "cpr-plugin-dev"
-  short_description: "网关插件开发、接入排障、SDK 实现、页面与打包验证"
-  default_prompt: "使用 $cpr-plugin-dev 按当前请求开发、排查或打包 Codex Proxy RS 网关插件，复用公开 SDK 与已有页面并验证实际行为。"
+  short_description: "独立网关插件开发、排障与审查，先核对宿主边界再实现和验证"
+  default_prompt: "使用 $cpr-plugin-dev 按当前请求开发、排查、审查或打包独立网关插件，先读取适用职责边界，插件业务错误在插件侧修复，再按步骤读取实现与验证资料。"
 policy:
   allow_implicit_invocation: true

.agents/skills/cpr-plugin-dev/references/development.md

@@ -13,7 +13,7 @@
 | [codex-proxy-ui](https://github.com/zyycn/codex-proxy-ui) | 可选的 Vue UI 库、组件文档与 playground |
 
 先检查用户给定工程、`modules/plugins` 子模块或同级仓库是否存在，读取实际仓库约定及当前步骤所需的 README 章节、依赖与锁文件，不预读无关前端配置
-只需中间件时不复制示例的管理 API、页面和相关权限；CLI 等能力从 SDK 对应合同起步，不给示例添加无关能力。
+只需中间件时不复制示例的管理 API 和页面；CLI 等能力从 SDK 对应合同起步，不给示例添加无关能力
 
 本仓库子模块联调使用[开发文档](../../../../docs/development.md#源码联调)中的 source 模式和本地 SDK 验证入口，不改写正式依赖或锁文件
 其他工程按其自身联调配置临时使用包级链接或 override，路径须真实可解析，不从业务源码跨仓 `import .../src/...`
@@ -37,7 +37,7 @@
 | 包内静态资源构建 | `examples/workbench/frontend/vite.config.ts` |
 
 若派生新插件，同时修改包名、二进制名、插件身份、扩展项 ID、注册描述和构建目标，不只改展示名称。
-保留当前项目确实需要的依赖、资源和权限；不要把示例中的全请求范围直接用到共享环境。
+保留当前项目确实需要的依赖、资源和能力声明；不要把示例中的全请求范围直接用到共享环境
 
 ## 构建与打包
 
@@ -58,7 +58,7 @@ cargo build --manifest-path /path/to/plugin/Cargo.toml --release --locked --targ
 需要从目标宿主源码构建工具时，在主仓根目录运行以下命令，把 `--help` 换成实际参数即可，不必全局安装：
 
 ```bash
-cargo run --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked -- package --help
+cargo +1.99.1 run --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked -- package --help
 ```
 
 直接打包的示意命令：
@@ -92,7 +92,7 @@ cpr-plugin package \
 
 ## 验证与交付
 
-按[插件使用](../../../../docs/plugins.md)验证“安装包 → 查看权限并安装 → 自动准备默认配置 → 实际使用”；只在缺少业务必填值时补配置，不添加授权或资源选择向导。
+按[插件使用](../../../../docs/plugins.md)验证“校验安装包 → 确认来源并接受完整信任 → 自动准备默认配置 → 实际使用”；只在缺少业务必填值时补配置，不添加权限或资源选择向导
 只有获得目标环境操作授权才安装和启用；不把修改源码的授权扩展到生产实例或真实凭据操作。
 需要 API 自动化时查[插件管理 API](../../../../docs/api.md#12-插件管理)，不要依据记忆拼路由。
 
@@ -100,7 +100,8 @@ cpr-plugin package \
 
 | 实现范围 | 应验证的行为 |
 | --- | --- |
-| 中间件 | 匹配／不匹配范围、授权不足、下游错误与取消；支持流式时检查多帧、终态和断开；若涉及续链，使用真实目标客户端检查 HTTP/SSE、WS 及后续轮次 |
+| 中间件 | 匹配／不匹配范围、单次 `next`、未改写字节保留、下游错误与取消；支持流式时检查多帧、终态和断开；若涉及续链，使用真实目标客户端检查 HTTP/SSE、WS 及后续轮次 |
+| 上游适配器 | 绑定匹配、账号认证与代理、HTTP/SSE 或 WS 事件解析、发送状态、用量和终态；支持续接时核对 Key、账号、凭据版本与代次隔离，失败不能透明重放已发送操作 |
 | 模型路由／调度 | 真实入口能命中规则，未匹配请求保持原有行为；使用官方客户端正常携带的业务头和会话别名，确认投影不会拒绝合法请求，也不暴露身份字段 |
 | 生命周期／用量／WS 观察 | 完成一次实际模型请求并核对对应事件；WS 观察需确认实际上游采用 WS，HTTP 请求成功不能证明 WS 观察生效 |
 | 管理页面 | 从宿主打开，标题／副标题、明暗主题、加载与错误状态；管理桥请求成功；停用或版本切换后旧入口失效 |
@@ -111,5 +112,5 @@ cpr-plugin package \
 外部示例测试若依赖未提供的仓库或制品，应记录为未执行；当前示例可用于实际能力联调，但不能把被忽略的测试计为通过。
 临时账号、Key 或配置只在明确的测试范围内创建，记录并清理自己创建的对象，不输出密钥、原始请求或插件 secret。
 
-交付简述：源码与产物位置、兼容范围、所需能力／权限／绑定、执行过的命令及结果、尚未验证的场景。
+交付简述：源码与产物位置、兼容范围、所需能力与绑定、执行过的命令及结果、尚未验证的场景
 只有确实生成了产物才报告“已打包”，只有目标环境业务验证成功才报告“已生效”；提交、推送与发布按用户授权另行执行。

.agents/skills/cpr-plugin-dev/references/frontend.md

@@ -1,8 +1,7 @@
 # 插件页面
 
-仅在创建或修改插件页面时读取，同时使用[开发入口](../../cpr-dev-guide/SKILL.md)的页面分支
+创建、修改或审查插件页面时完整读取，先完成[插件入口](../SKILL.md#先读职责边界)的边界判断并执行[前端流程](../../cpr-dev-guide/references/frontend.md)，再核对以下插件特有合同
 
-- 沿用已有插件页面与 [管理端主题](../../../../docs/theme.md#界面文案与信息层级) 的设计和文案层级，详细帮助使用现有 Popover；页面 PR 按 [界面验证](../../../../CONTRIBUTING.md#界面验证) 提供实际截图
 - 优先参考独立示例仓库的 `examples/workbench/frontend/src/api/`：业务路由放在 `modules/`，`request.ts` 封装公开宿主桥；按需使用 `@codex-proxy/ui` 包出口，不跨仓导入宿主或 UI 的内部源码
 - Vue 页面保留 SFC，逻辑、脚本和配置使用 TypeScript；只实现业务内容，标题和副标题由 `ManagementPage` 交给宿主显示
 - 隔离页面通过 `window.codexProxyPlugin.request` 调用已注册管理路由；`models.responses` 通过普通请求链交付 JSON/SSE，支持取消且不暴露 Key 明文。不直接 `fetch` 宿主、不读取管理 Cookie 或借用宿主 Vue 实例

.agents/skills/cpr-plugin-dev/references/implementation.md

@@ -1,12 +1,12 @@
 # 清单与处理器实现
 
-仅在编写或排查插件清单、Rust 处理器时读取，涉及 Rust 时使用[开发入口](../../cpr-dev-guide/SKILL.md)的 Rust 分支
-选择能力时只读 SDK 的[能力与方法](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#能力与方法)及所需能力章节
+开发、排查或审查插件清单、Rust 处理器时完整读取，先完成[插件入口](../SKILL.md#先读职责边界)的边界判断，涉及 Rust 时执行[开发入口](../../cpr-dev-guide/SKILL.md)的 Rust 分支
+使用能力前读取 SDK 的[能力与方法](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#能力与方法)及所用能力章节，已有实现的修复与审查也核对合同
 
 ## 清单与处理器
 
 - `publisher` 与机器短名 `name` 派生插件 ID，`displayName` 用于展示；复制示例后同时调整扩展项 ID 与注册结果
-- `contributes` 每种能力最多一项，普通贡献项可省略派生 ID、能力版本和固定阶段；中间件阶段仍需显式选择。自定义完整扩展项 ID 属于自己的插件命名空间，运行注册与规范化清单一致
+- `contributes` 每种能力最多一项，派生 ID 和固定阶段可省略；能力版本与中间件阶段按[扩展项简写](../../../../backend/crates/gateway-plugin/sdk/docs/manifest.md#扩展项简写)声明。自定义完整扩展项 ID 属于自己的插件命名空间，运行注册与规范化清单一致
 - 作者清单用 `Manifest::from_author_slice` 规范化，不手写 `package`、固定阶段或重复注册；CLI 生成平台、协议与资源摘要，版本范围不能使用全版本通配
 - 安装后宿主会按 `configurationSchema` 准备默认配置，配置完整即可启用；默认绑定的空范围不限制请求。需要业务参数时声明真实必填项，通过 `secretFields` 声明敏感字段，不依赖用户再走一遍自建安装向导
 - Rust 插件只依赖公开 `gateway-plugin-sdk`；需要异步会话辅助时开启 `io`，使用 `PluginSession` 管理握手、回调关联、流控、取消和关闭
@@ -16,9 +16,10 @@
 ## 中间件与宿主服务
 
 - `request` 包裹整个逻辑请求，`attempt` 在每次选定账号的尝试中执行；根据作用范围选择，避免重试时重复副作用
-- `next` 只能消费一次。使用 SDK 的正文保留与流式映射能力，不自行拼一套 SSE／取消／流控机制；请求、响应及策略处理使用 `requests` 域
+- `next` 只能消费一次。使用 SDK 的正文保留与流式映射能力，不自行拼一套 SSE／取消／流控机制；HTTP、WebSocket、服务和模型请求按各自的类型化视图处理
 - 持久化状态使用已声明命名空间的 `host.state.*`，账号读写使用 `host.auth.*`，不直接访问宿主数据库。见[账号与凭据](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#账号与凭据)和[状态、日志与迁移](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#状态日志与迁移)
-- 权限从目标 SDK 的[访问域](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#访问域)选择，不在技能中维护枚举副本；日志和自身状态无需授权项，安装器不配置 Key／账号白名单，资源选择属于插件业务
+- 按[完整信任](../../../../backend/crates/gateway-plugin/sdk/docs/manifest.md#完整信任)使用宿主回调，不添加权限或访问域声明；资源选择属于插件业务，父调用、期限、取消、实例 revision 与事务校验仍须满足
 - 模型、网络和亲和查询使用当前父调用的受管回调。管理／CLI 等独立入口调用模型时传明确的 Key ID；请求处理阶段继承父身份。见[Key、模型与模型调用](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#key模型与模型调用)
-- SDK 操作名不是管理员 HTTP 路由，不能据此拼接口地址；宿主身份、账单事实和调用授权也不能由插件覆盖
+- SDK 操作名不是管理员 HTTP 路由，不能据此拼接口地址；主动调用 HTTP 使用 `dispatch_http`，类型化服务使用 `HostClient::service`，实际执行与账单事实仍由宿主持有
 - 路由与调度只读取宿主投影的请求事实，身份头可能被隐藏；使用已有会话和亲和合同，不依赖原始认证头或根据缓存键补造客户端身份
+- 需要自定义上游编码、路径与响应解析时使用[受管上游适配器](../../../../backend/crates/gateway-plugin/sdk/docs/upstream-adapters.md)，它是已选号后的终端，不调用 `next` 或自行组织换号重试；普通请求和响应加工仍使用中间件

.agents/skills/cpr-release/SKILL.md

@@ -15,24 +15,25 @@ description: Codex Proxy RS 的版本规划、发布说明、正式或预发行
 
 其他仓库使用其发布入口与规则，不套用本仓库路径；规则已在上下文中时不重复读取
 
+## 必须保持的边界
+
+- Codex 兼容性变化按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核对已有依据与验证范围，缺少依据列为发行风险，不以 CI 通过代替
+- `release/publish` 会提交、打 tag、推送并触发工作流，没有只读预演模式，不能用于探测或演练
+- 同名版本、超时或中断先查本地与远端状态，不删已发布 tag、不移动 tag、不强推掩盖冲突
+- 预发行不得覆盖 GitHub Latest 或镜像 `latest`，完成后回读核对
+- `release/notes.md` 只承载当前发行的说明；常规文档修改另按开发入口执行[文档检查](../cpr-dev-guide/references/documentation.md)
+- 交付版本、提交、Release／工作流链接与实际结果，未完成构建或缺失产物时不称发布成功
+
 ## 按任务读取
 
-只读当前阶段和指定章节，先定位标题再截取，不预读整份 CONTRIBUTING、工作流或所有参考文件；实际发布前仍须核对发布入口的完整副作用
+先落实上述范围与边界，再读取当前阶段的完整指定章节；实际发布包含准备与验收，不能只读执行命令。阶段变化时补齐读取，准备文案不加载执行流程，实际发布前须核对发布入口的完整副作用
 
 | 任务 | 读取范围 |
 | --- | --- |
 | 推荐版本号 | [基线与版本](references/preparation.md#基线与版本) |
 | 编写或翻译发布说明 | [基线与版本](references/preparation.md#基线与版本)、[发布说明](references/preparation.md#发布说明) |
 | 检查发行条件 | [发行准备检查](references/preparation.md#发行准备检查) |
-| 实际发布 | 完成准备，再读[通道核对](references/operations.md#发行通道核对)和[执行发版](references/operations.md#执行发版) |
+| 实际发布 | 先完成[基线与版本](references/preparation.md#基线与版本)、[发布说明](references/preparation.md#发布说明)、[发行准备检查](references/preparation.md#发行准备检查)，再执行[通道核对](references/operations.md#发行通道核对)、[执行发版](references/operations.md#执行发版)与[恢复与验收](references/operations.md#恢复与验收) |
 | 失败恢复或验收 | [恢复与验收](references/operations.md#恢复与验收)，先确定已完成步骤，不直接重跑入口 |
-| 实验版 | 在对应阶段补读[实验流程](references/experimental.md)的版本、文案或验收章节 |
+| 实验版 | 在对应阶段补读[实验流程](references/experimental.md)；实际发布必须覆盖分支与版本、发布能力、文案和执行与验收 |
 | 修复代码、工作流或常规文档 | 使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，有 PR 任务再使用 [cpr-github-pr](../cpr-github-pr/SKILL.md) |
-
-## 必须保持的边界
-
-- `release/publish` 会提交、打 tag、推送并触发工作流，没有只读预演模式，不能用于探测或演练
-- 同名版本、超时或中断先查本地与远端状态，不删已发布 tag、不移动 tag、不强推掩盖冲突
-- 预发行不得覆盖 GitHub Latest 或镜像 `latest`，完成后回读核对
-- `release/notes.md` 只承载当前发行的说明，常规文档只写当前状态，不追加版本历史；其变更执行[文档检查](../cpr-dev-guide/references/documentation.md)
-- 交付版本、提交、Release／工作流链接与实际结果，未完成构建或缺失产物时不称发布成功

.agents/skills/cpr-release/references/operations.md

@@ -20,7 +20,7 @@
 
 调用入口前重新核对当前脚本的副作用、目标版本和待推送提交，保留无关工作区内容，不自动清理或暂存用户文件。
 先编辑 `release/notes.md`，保留为未提交改动（已暂存或未暂存均可）；其他已跟踪文件的改动应先单独提交。
-脚本会更新 `release/version.yaml`，将它与最终工作区中的发布说明一起提交为 `chore(release): vX.Y.Z`。
+脚本会更新 `release/version.yaml`，按[接口弃用规则](../../../../backend/crates/gateway-plugin/sdk/docs/manifest.md#接口弃用)校验并维护 `plugin-api-deprecations.json`，将这些差异与最终工作区中的发布说明一起提交为 `chore(release): vX.Y.Z`。
 不要提前单独提交说明或把版本文件改成目标版本；脚本要求说明相对 HEAD 有改动，并自行更新版本号。
 本任务需要的提交按[项目约定](../../../../CONTRIBUTING.md#项目约定)保留英文 Conventional Commits 与相应署名。
 
@@ -30,7 +30,7 @@
 release/publish "$release_version"
 ```
 
-该命令会创建包含版本号和发布说明的单次提交与 annotated tag，原子推送分支和 tag，再从长期分支手动触发 `release.yml`。
+该命令会创建上述版本提交与 annotated tag，原子推送分支和 tag，再从长期分支手动触发 `release.yml`。
 它没有只读预演模式；不能为了检查或演练而执行。发布工作流读取 tag 中的说明，修改 tag 之后的本地文件不会改变该次构建。
 
 只调整已发布页面的标题或正文时，编辑对应 GitHub Release 的 `name` 或 `body` 并回读核对；

.agents/skills/cpr-release/references/preparation.md

@@ -19,7 +19,7 @@
 - 只翻译已有准确说明时保持事实与范围，不混入其他变更
 - 常规文档仍只描述当前状态；必要修订执行[文档检查](../../cpr-dev-guide/references/documentation.md)，不复制发布说明中的版本变化列表
 
-实际发布由 `release/publish` 提交说明与版本文件，准备说明时不要提前单独提交或把版本文件改成目标版本
+实际发布由 `release/publish` 提交说明、版本文件及[插件接口弃用清单](../../../../backend/crates/gateway-plugin/sdk/docs/manifest.md#接口弃用)的必要更新，准备说明时不要提前单独提交或把版本文件改成目标版本
 用户只要求准备时保留本地改动，纯说明修改无需重建前后端
 
 ## 发行准备检查

.github/actions/build-frontend/action.yml

@@ -12,10 +12,15 @@ runs:
       with:
         package_json_file: frontend/package.json
 
+    - name: Read build toolchains
+      id: toolchains
+      shell: bash
+      run: ruby .github/scripts/toolchains.rb >> "$GITHUB_OUTPUT"
+
     - name: Setup Node
-      uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
       with:
-        node-version: 24
+        node-version: ${{ steps.toolchains.outputs.node }}
         cache: pnpm
         cache-dependency-path: frontend/pnpm-lock.yaml
 
@@ -33,7 +38,7 @@ runs:
 
     - name: Upload frontend artifact
       if: inputs.upload-artifact == 'true'
-      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+      uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
       with:
         name: frontend-dist
         path: frontend/dist

.github/actions/cargo-cache/cargo-cache.sh

@@ -42,8 +42,11 @@ else
   mkdir -p "$(dirname "$directory")"
   temporary="$(mktemp -d "${directory}.XXXXXX")"
   trap 'rm -rf "$temporary"' EXIT
-  mkdir "$temporary/context"
-  "${command[@]}" --output "type=local,dest=$temporary/snapshot" "$temporary/context"
+  mkdir "$temporary"/{context,snapshot}
+  # tar 流避开 local exporter 的逐文件同步阻塞，直接解包以免额外落盘整份归档。
+  # https://github.com/moby/buildkit/issues/2950
+  "${command[@]}" --output type=tar,dest=- "$temporary/context" \
+    | tar -xf - -C "$temporary/snapshot"
   if usable "$temporary/snapshot"; then
     rm -rf "$directory"
     mv "$temporary/snapshot" "$directory"

.github/actions/verify-container/action.yml

@@ -117,8 +117,9 @@ runs:
         compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
           -f deploy/compose.yaml)
         "${compose[@]}" up -d --no-build --wait postgres redis
+        # 基础设施使用 UTC，业务展示和调度时区由应用配置独立控制。
         test "$("${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
-          psql -At -U codex_proxy -d codex_proxy -c "SHOW TimeZone;" | tr -d '\r')" = Asia/Shanghai
+          psql -At -U codex_proxy -d codex_proxy -c "SHOW TimeZone;" | tr -d '\r')" = UTC
         "${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
           psql -v ON_ERROR_STOP=1 -U codex_proxy -d codex_proxy -c \
           "CREATE TABLE cpr_ci_persistence_probe (value text PRIMARY KEY); INSERT INTO cpr_ci_persistence_probe VALUES ('persisted');"
@@ -148,11 +149,26 @@ runs:
         test "$status" = 204
         test "$("${compose[@]}" exec -T codex-proxy-rs id -u | tr -d '\r')" = 10001
         test "$("${compose[@]}" exec -T codex-proxy-rs id -g | tr -d '\r')" = 10001
-        test "$("${compose[@]}" exec -T codex-proxy-rs date +%z | tr -d '\r')" = +0800
-        test "$("${compose[@]}" exec -T codex-proxy-rs cat /etc/timezone | tr -d '\r')" = Asia/Shanghai
+        test "$("${compose[@]}" exec -T codex-proxy-rs date +%z | tr -d '\r')" = +0000
+        test "$("${compose[@]}" exec -T codex-proxy-rs cat /etc/timezone | tr -d '\r')" = UTC
         "${compose[@]}" exec -T codex-proxy-rs sh -c \
           'touch /app/.runtime/data/.ci-write /app/.runtime/logs/.ci-write && rm /app/.runtime/data/.ci-write /app/.runtime/logs/.ci-write'
 
+    - name: Verify application restart after installer permissions
+      shell: bash
+      run: |
+        set -euo pipefail
+        compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
+          -f deploy/compose.yaml)
+        "${compose[@]}" stop --timeout 30 codex-proxy-rs
+        # 使用安装器原函数，验证已有备份暂存目录与日志不会因所有权变更而阻止启动
+        (
+          export INSTALL_DIR="$PWD"
+          source deploy/install.sh
+          fix_runtime_permissions
+        )
+        "${compose[@]}" up -d --no-build --wait codex-proxy-rs
+
     - name: Verify clean logs and graceful shutdown
       shell: bash
       run: |
@@ -226,7 +242,7 @@ runs:
 
     - name: Upload container diagnostics
       if: always()
-      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+      uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
       with:
         name: ${{ inputs.artifact-name }}
         path: ${{ runner.temp }}/codex-proxy-rs-diagnostics

.github/dependabot.yml

@@ -52,7 +52,7 @@ updates:
           - patch
 
   - package-ecosystem: npm
-    directory: /
+    directory: /frontend
     labels: []
     schedule:
       interval: weekly

.github/scripts/package-release.rb

@@ -0,0 +1,79 @@
+require 'digest'
+require 'fileutils'
+require 'json'
+
+# 归档与镜像消费相同二进制和封口清单，不在打包时重新解释插件分发策略
+module ReleasePackage
+  APP_NAME = 'codex-proxy-rs'
+  MANIFEST = 'dist/plugin-release-assets/plugin-release-manifest.json'
+
+  def self.install_manifest(directory)
+    manifest = JSON.parse(File.read(MANIFEST))
+    unless manifest['schema_version'] == 1 && manifest['sealed'] == true && manifest['plugins'] == []
+      raise 'Expected a sealed host manifest without bundled plugins'
+    end
+    FileUtils.mkdir_p(directory)
+    destination = File.join(directory, File.basename(MANIFEST))
+    FileUtils.cp(MANIFEST, destination)
+    File.chmod(0o444, destination)
+    File.chmod(0o555, directory)
+  end
+
+  def self.archives
+    platforms = JSON.parse(ENV.fetch('PLATFORM_MATRIX')).fetch('include')
+    release_dir = 'dist/release'
+    FileUtils.rm_rf(release_dir)
+    FileUtils.mkdir_p(release_dir)
+    # 上一次打包生成的只读清单目录需要先恢复写权限
+    FileUtils.chmod_R('u+w', 'package') if File.directory?('package')
+    FileUtils.rm_rf('package')
+    config = 'deploy/config.example.yaml'
+    FileUtils.cp(config, release_dir)
+    compose = File.read('deploy/compose.yaml')
+    image = "#{ENV.fetch('REGISTRY')}/#{ENV.fetch('IMAGE_NAME')}"
+    default_image = "${CPR_IMAGE:-#{image}:latest}"
+    raise 'Expected exactly one default application image in deploy/compose.yaml' unless compose.scan(default_image).length == 1
+    File.write("#{release_dir}/compose.yaml", compose.sub(default_image, "${CPR_IMAGE:-#{image}:#{ENV.fetch('DOCKER_VERSION')}}"))
+    FileUtils.cp(MANIFEST, release_dir)
+
+    platforms.each do |platform|
+      raise "Unsupported archive format: #{platform['archive']}" unless platform['archive'] == 'tar.gz'
+      name = "#{platform.fetch('os')}-#{platform.fetch('arch')}"
+      binary = platform.fetch('binary')
+      root = "package/#{name}/#{APP_NAME}"
+      FileUtils.mkdir_p(["#{root}/web/dist", "#{root}/deploy"])
+      FileUtils.cp("dist/binaries/#{APP_NAME}-#{name}/#{binary}", "#{root}/#{binary}")
+      File.chmod(0o755, "#{root}/#{binary}")
+      FileUtils.cp_r('dist/frontend/.', "#{root}/web/dist")
+      FileUtils.cp(config, "#{root}/deploy")
+      install_manifest("#{root}/plugins/official")
+      archive = "#{release_dir}/#{APP_NAME}_#{ENV.fetch('VERSION')}_#{platform['os']}_#{platform['arch']}.tar.gz"
+      raise "Failed to create #{archive}" unless system('tar', '-czf', archive, '-C', File.dirname(root), APP_NAME)
+    end
+
+    checksums = Dir.glob("#{release_dir}/*").sort.map { |path| "#{Digest::SHA256.file(path).hexdigest}  #{File.basename(path)}\n" }
+    File.write("#{release_dir}/checksums.txt", checksums.join)
+  end
+
+  def self.image
+    platform = "#{ENV.fetch('MATRIX_OS')}-#{ENV.fetch('MATRIX_ARCH')}"
+    target = "dist/docker/#{platform}"
+    FileUtils.mkdir_p(target)
+    FileUtils.cp("dist/docker-artifacts/#{APP_NAME}-#{platform}/#{ENV.fetch('MATRIX_BINARY')}", "#{target}/#{APP_NAME}")
+    File.chmod(0o755, "#{target}/#{APP_NAME}")
+    install_manifest("#{target}/plugins/official")
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    case ARGV
+    when ['archives'] then ReleasePackage.archives
+    when ['image'] then ReleasePackage.image
+    else raise 'usage: package-release.rb archives|image'
+    end
+  rescue StandardError => error
+    warn "error: #{error.message}"
+    exit 1
+  end
+end

.github/scripts/publish-release.rb

@@ -0,0 +1,84 @@
+require_relative 'release-metadata'
+
+# 构建和验证可以并行；调用方必须在仓库级发布锁内执行本脚本
+module ReleasePublication
+  def self.run(*command)
+    output, error, status = Open3.capture3(*command)
+    raise "#{command.first} failed: #{error.strip}" unless status.success?
+    output.strip
+  end
+
+  def self.latest_release(repository)
+    output, error, status = Open3.capture3('gh', 'api', '--include', "repos/#{repository}/releases/latest")
+    code = output.lines.first.to_s.split[1]
+    return nil if code == '404'
+    raise "Cannot read latest GitHub release: #{error.strip}" unless status.success? && code == '200'
+    JSON.parse(output.split(/\r?\n\r?\n/, 2).fetch(1)).fetch('tag_name')
+  end
+
+  def self.latest_image(image)
+    ref = "#{image}:latest"
+    output, error, status = Open3.capture3('docker', 'buildx', 'imagetools', 'inspect', ref, '--format', '{{json .Image}}')
+    # 只把明确的缺失标签当作首次发布，鉴权和网络错误必须终止提升
+    return nil if !status.success? && error.include?("#{ref}: not found")
+    raise "Cannot read latest image: #{error.strip}" unless status.success?
+    versions = JSON.parse(output).values.map do |config|
+      config.fetch('config').fetch('Labels').fetch('org.opencontainers.image.version')
+    end.uniq
+    raise 'Latest image must have one consistent version across platforms' unless versions.length == 1
+    versions.first
+  end
+
+  def self.can_promote?(version, current_versions)
+    return false if ReleaseMetadata.prerelease?(version)
+    current_versions.compact.all? do |current|
+      raise "Latest points to a prerelease: #{current}" if ReleaseMetadata.prerelease?(current)
+      comparison = ReleaseMetadata.sort_key(version) <=> ReleaseMetadata.sort_key(current)
+      # 构建元数据不决定版本先后；同优先级只允许相同版本重试
+      comparison.positive? || (comparison.zero? && ReleaseMetadata.version(current) == version)
+    end
+  end
+
+  def self.tag(image, digest, name)
+    ref = "#{image}:#{name}"
+    run('docker', 'buildx', 'imagetools', 'create', '-t', ref, "#{image}@#{digest}")
+    actual = run('docker', 'buildx', 'imagetools', 'inspect', ref, '--format', '{{.Manifest.Digest}}')
+    raise "Promoted image digest changed: #{ref}" unless actual == digest
+  end
+
+  def self.publish(version:, image:, digest:, repository:, release_id:)
+    version = ReleaseMetadata.version(version)
+    raise 'Invalid image digest' unless digest.match?(/\Asha256:[a-f0-9]{64}\z/)
+    raise 'Invalid GitHub release ID' unless release_id.match?(/\A\d+\z/)
+    endpoint = "repos/#{repository}/releases/#{release_id}"
+
+    # 附件上传及镜像证明、签名已完成，再公开版本入口；失败可从本 job 重跑
+    tag(image, digest, version.tr('+', '-'))
+    run('gh', 'api', '--method', 'PATCH', endpoint, '-F', 'draft=false', '-f', 'make_latest=false')
+    return if ReleaseMetadata.prerelease?(version)
+
+    current_versions = [latest_release(repository), latest_image(image)]
+    unless can_promote?(version, current_versions)
+      puts "Published #{version}; latest remains at #{current_versions.compact.join(', ')}"
+      return
+    end
+
+    # 两个服务不能原子更新；同时检查两侧版本，让失败重试可以补齐而旧版不能回退
+    tag(image, digest, 'latest')
+    run('gh', 'api', '--method', 'PATCH', endpoint, '-f', 'make_latest=true')
+    puts "Published #{version} and promoted latest"
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    ReleasePublication.publish(
+      version: ENV.fetch('VERSION'), image: "#{ENV.fetch('REGISTRY')}/#{ENV.fetch('IMAGE_NAME')}",
+      digest: ENV.fetch('DIGEST'), repository: ENV.fetch('GITHUB_REPOSITORY'),
+      release_id: ENV.fetch('RELEASE_ID')
+    )
+  rescue StandardError => error
+    warn "error: #{error.message}"
+    exit 1
+  end
+end

.github/scripts/release-metadata.rb

@@ -0,0 +1,129 @@
+require 'fileutils'
+require 'json'
+require 'open3'
+require 'rubygems'
+require 'time'
+require 'yaml'
+
+# 本地入口与发行工作流共用版本、说明和平台合同
+module ReleaseMetadata
+  APP_NAME = 'codex-proxy-rs'
+  SEMVER = /\A(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:alpha|beta|rc|exp)\.[1-9]\d*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?\z/
+
+  def self.version(raw)
+    value = raw.delete_prefix('v')
+    raise "Invalid release version: #{raw}" unless value.match?(SEMVER)
+    value
+  end
+
+  def self.prerelease?(value)
+    version(value).split('+', 2).first.include?('-')
+  end
+
+  def self.sort_key(value)
+    Gem::Version.new(version(value).split('+', 2).first)
+  end
+
+  def self.validate_notes(value)
+    tag = "v#{version(value)}"
+    lines = File.readlines('release/notes.md')
+    unless lines.first&.strip == "# #{tag}" && !lines.drop(1).join.strip.empty?
+      raise "release/notes.md: expected non-empty notes starting with '# #{tag}'"
+    end
+  end
+
+  def self.git(*arguments)
+    output, status = Open3.capture2('git', *arguments)
+    raise "git #{arguments.join(' ')} failed" unless status.success?
+    output.strip
+  end
+
+  def self.platforms
+    entries = YAML.load_file('release/platforms.yaml').fetch('platforms')
+    raise 'release/platforms.yaml: platforms must be a non-empty array' unless entries.is_a?(Array) && !entries.empty?
+    seen = {}
+    entries.each do |entry|
+      raise 'Invalid release platform' unless entry.is_a?(Hash)
+      %w[os arch runner target binary archive].each do |key|
+        raise "Invalid platform #{key}" unless entry[key].is_a?(String) && !entry[key].strip.empty?
+      end
+      key = "#{entry['os']}-#{entry['arch']}"
+      raise "Duplicate release platform: #{key}" if seen[key]
+      seen[key] = true
+      raise "Unsupported archive: #{entry['archive']}" unless entry['archive'] == 'tar.gz'
+      if entry['docker'] == true
+        platform = entry['dockerPlatform']
+        raise "Missing Docker platform: #{key}" unless platform.is_a?(String) && !platform.strip.empty?
+        entry['dockerPlatform'] = platform.strip
+      end
+      entry['artifact'] = "#{APP_NAME}-#{key}"
+    end
+    raise 'At least one Docker platform is required' unless entries.any? { |entry| entry['docker'] == true }
+    entries
+  end
+
+  def self.outputs(tag)
+    value = version(YAML.load_file('release/version.yaml').fetch('version'))
+    raise "Release tag #{tag} does not match v#{value}" unless tag == "v#{value}"
+    validate_notes(value)
+    entries = platforms
+    docker, native = entries.partition { |entry| entry['docker'] == true }
+    previous = git('tag', '--list', 'v*', '--merged', 'HEAD').lines.map(&:strip).filter_map do |candidate|
+      next unless candidate.delete_prefix('v').match?(SEMVER)
+      key = sort_key(candidate)
+      [key, candidate] if key < sort_key(value)
+    end.max_by(&:first)&.last
+    {
+      'tag' => tag,
+      'version' => value,
+      'docker_version' => value.tr('+', '-'),
+      'build_time' => Time.now.utc.iso8601,
+      'git_sha' => git('rev-parse', 'HEAD'),
+      'platform_matrix' => JSON.generate('include' => entries),
+      'docker_matrix' => JSON.generate('include' => docker),
+      'non_docker_matrix' => JSON.generate('include' => native),
+      'docker_platforms' => docker.map { |entry| entry['dockerPlatform'] }.join(','),
+      'previous_tag' => previous,
+      'prerelease' => prerelease?(value),
+      'build_type' => value.split('+', 2).first.include?('-exp.') ? 'experimental' : 'release'
+    }
+  end
+
+  def self.seal_manifest(metadata)
+    path = 'backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json'
+    host = JSON.parse(File.read(path))
+    raise "Invalid plugin host compatibility declaration: #{path}" unless host['schema_version'] == 2
+    manifest = {
+      'schema_version' => 1,
+      'sealed' => true,
+      'gateway_version' => metadata.fetch('version'),
+      'gateway_git_sha' => metadata.fetch('git_sha'),
+      'plugin_host' => host,
+      'plugins' => []
+    }
+    FileUtils.mkdir_p('dist/plugin-release-assets')
+    File.write('dist/plugin-release-assets/plugin-release-manifest.json', JSON.pretty_generate(manifest) + "\n")
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    command, value = ARGV
+    raise 'usage: release-metadata.rb validate VERSION | outputs TAG' unless ARGV.length == 2
+    case command
+    when 'validate'
+      value = ReleaseMetadata.version(value)
+      ReleaseMetadata.validate_notes(value)
+      puts value
+    when 'outputs'
+      metadata = ReleaseMetadata.outputs(value)
+      ReleaseMetadata.seal_manifest(metadata)
+      metadata.each { |key, entry| puts "#{key}=#{entry}" }
+    else
+      raise "Unknown command: #{command}"
+    end
+  rescue StandardError => error
+    warn "error: #{error.message}"
+    exit 1
+  end
+end

.github/scripts/toolchains.rb

@@ -0,0 +1,27 @@
+# 从构建声明读取 CI 工具链，阻止 Docker 与本地 Rust 版本漂移
+module BuildToolchains
+  def self.read(root = '.')
+    declaration = File.read(File.join(root, 'backend/rust-toolchain.toml'))
+    rust = declaration[/^\s*channel\s*=\s*["'](\d+\.\d+(?:\.\d+)?)["']\s*(?:#.*)?$/, 1]
+    raise 'Expected a pinned Rust channel in backend/rust-toolchain.toml' unless rust
+    dockerfile = File.read(File.join(root, 'deploy/Dockerfile'))
+    image = lambda do |stage, name|
+      match = dockerfile.match(/^FROM (#{name}:([^\s@]+)@sha256:[a-f0-9]{64}) AS #{stage}$/)
+      raise "Missing pinned #{stage} image" unless match
+      [match[1], match[2].split('-', 2).first]
+    end
+    rust_image, image_rust = image.call('backend-builder', 'rust')
+    _, node = image.call('frontend-builder', 'node')
+    raise "Rust toolchain #{rust} differs from Docker builder #{image_rust}" unless rust == image_rust
+    { 'rust' => rust, 'rust_image' => rust_image, 'node' => node }
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    BuildToolchains.read.each { |key, value| puts "#{key}=#{value}" }
+  rescue StandardError => error
+    warn "error: #{error.message}"
+    exit 1
+  end
+end

.github/workflows/_container.yml

@@ -14,7 +14,7 @@ permissions:
 
 jobs:
   container:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 45
     env:
       CPR_IMAGE: codex-proxy-rs:ci-${{ inputs.ref }}

.github/workflows/_quality.yml

@@ -24,17 +24,17 @@ permissions:
 jobs:
   backend:
     if: inputs.run_backend
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 30
     env:
       CARGO_TERM_COLOR: always
-      # Rust 1.97 编译 AWS SDK 调试信息需要更大的 codegen 线程栈。
+      # 编译 AWS SDK 调试信息需要更大的 codegen 线程栈
       RUST_MIN_STACK: 16777216
       CPR_TEST_DATABASE_URL: postgres://codex_proxy:codex_proxy@127.0.0.1:5432/codex_proxy
       CPR_TEST_REDIS_URL: redis://127.0.0.1:6379
     services:
       postgres:
-        image: postgres:18-bookworm@sha256:d9c83446333daec3f0588cc709adb80c26090b7f9f0f7ec8d43c243385d79818
+        image: postgres:18-bookworm@sha256:bbf83594798e144bff365a9c191c5d779f181fb3135902064ab8ff11918020fc
         env:
           POSTGRES_DB: codex_proxy
           POSTGRES_USER: codex_proxy
@@ -48,7 +48,7 @@ jobs:
           --health-timeout 5s
           --health-retries 10
       redis:
-        image: redis:8-alpine@sha256:9d317178eceac8454a2284a9e6df2466b93c745529947f0cd42a0fa9609d7005
+        image: redis:8-alpine@sha256:0bf6577d7774e592b29d093e3ac9390eb91e13d72c21e506afce736de5e0eeb0
         ports:
           - 6379:6379
         options: >-
@@ -97,9 +97,14 @@ jobs:
             fi
           fi
 
+      - name: Read build toolchains
+        id: toolchains
+        run: ruby .github/scripts/toolchains.rb >> "$GITHUB_OUTPUT"
+
       - name: Setup Rust
-        uses: dtolnay/rust-toolchain@1a3a6d54512beeaffd394f8d516ca16f2c506a20 # 1.97
+        uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
         with:
+          toolchain: ${{ steps.toolchains.outputs.rust }}
           components: rustfmt,clippy
 
       - name: Cache Rust
@@ -117,7 +122,7 @@ jobs:
         run: cargo clippy --all-targets --all-features --locked -- -D warnings
 
       - name: Setup nextest
-        uses: taiki-e/install-action@4cef1412cce204788f482e778a0b9187f9626a29 # v2.87.21
+        uses: taiki-e/install-action@8cca0918f8471c33515202b73f56ab27f2bed283 # v2.87.29
         with:
           tool: cargo-nextest@0.9.143
           fallback: none
@@ -151,6 +156,20 @@ jobs:
             echo "CPR_TEST_REDIS_URL=redis://:${redis_password}@127.0.0.1:6379"
           } >> "$GITHUB_ENV"
 
+      - name: Expose matching PostgreSQL backup and restore tools
+        shell: bash
+        env:
+          CPR_TEST_POSTGRES_CONTAINER: ${{ job.services.postgres.id }}
+        run: |
+          set -euo pipefail
+          client_dir="$RUNNER_TEMP/pg-client"
+          mkdir -p "$client_dir"
+          for tool in pg_dump psql; do
+            printf '#!/bin/sh\nexec docker exec -i --env PGPASSWORD "%s" %s "$@"\n' "$CPR_TEST_POSTGRES_CONTAINER" "$tool" > "$client_dir/$tool"
+            chmod +x "$client_dir/$tool"
+          done
+          echo "$client_dir" >> "$GITHUB_PATH"
+
       - name: Rust tests
         working-directory: backend
         run: |
@@ -180,7 +199,7 @@ jobs:
 
   frontend:
     if: inputs.run_frontend
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 15
     env:
       CI: 'true'
@@ -194,7 +213,7 @@ jobs:
         uses: ./.github/actions/build-frontend
 
   workflow-lint:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 5
     steps:
       - name: Checkout
@@ -202,6 +221,10 @@ jobs:
         with:
           ref: ${{ inputs.ref }}
 
+      # GitHub 已支持 queue: max，actionlint 尚未支持该字段
+      # https://github.com/rhysd/actionlint/issues/657
+      # GitHub 已提供 ubuntu-26.04，actionlint 尚未收录该标签
+      # https://github.com/actions/runner-images#available-images
       - name: Lint GitHub Actions workflows
         run: >-
           docker run --rm
@@ -209,6 +232,8 @@ jobs:
           --workdir /repo
           rhysd/actionlint:1.7.7@sha256:887a259a5a534f3c4f36cb02dca341673c6089431057242cdc931e9f133147e9
           -color
+          -ignore '^unexpected key "queue" for "concurrency" section\. expected one of "cancel-in-progress", "group"$'
+          -ignore '^label "ubuntu-26\.04" is unknown\.'
           .github/workflows/*.yml
 
       - name: Check workflow script syntax
@@ -216,3 +241,6 @@ jobs:
           bash -n release/publish
           shopt -s globstar nullglob
           for script in .github/**/*.sh; do bash -n "$script"; done
+          for script in .github/scripts/*.rb; do ruby -c "$script"; done
+          ruby .github/scripts/toolchains.rb
+          ruby -c backend/crates/gateway-plugin/runtime/plugin-api-lifecycle.rb

.github/workflows/ci.yml

@@ -20,8 +20,11 @@ concurrency:
 
 jobs:
   changes:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: read
     outputs:
       backend: ${{ steps.filter.outputs.backend }}
       frontend: ${{ steps.filter.outputs.frontend }}
@@ -42,18 +45,26 @@ jobs:
           predicate-quantifier: some-with-excludes
           filters: |
             backend:
+              - '.github/scripts/toolchains.rb'
+              - 'deploy/Dockerfile'
               - 'backend/**'
               - 'release/version.yaml'
               - '.github/workflows/ci.yml'
               - '.github/workflows/_quality.yml'
               - '!**/*.md'
             frontend:
+              - '.github/scripts/toolchains.rb'
+              - 'backend/rust-toolchain.toml'
+              - 'deploy/Dockerfile'
               - 'frontend/**'
               - '.github/actions/build-frontend/**'
               - '.github/workflows/ci.yml'
               - '.github/workflows/_quality.yml'
               - '!**/*.md'
             source:
+              - '.github/scripts/toolchains.rb'
+              - 'backend/rust-toolchain.toml'
+              - 'deploy/Dockerfile'
               - '.gitmodules'
               - 'modules/ui'
               - 'modules/plugins'
@@ -94,7 +105,7 @@ jobs:
   source-development:
     needs: changes
     if: needs.changes.outputs.source == 'true'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 20
     steps:
       - name: Checkout with development modules
@@ -106,22 +117,18 @@ jobs:
         uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
         with:
           package_json_file: frontend/package.json
+      - name: Read build toolchains
+        id: toolchains
+        run: ruby .github/scripts/toolchains.rb >> "$GITHUB_OUTPUT"
+
       - name: Setup Node
-        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
-          node-version: 24
+          node-version: ${{ steps.toolchains.outputs.node }}
       - name: Setup Rust
-        uses: dtolnay/rust-toolchain@1a3a6d54512beeaffd394f8d516ca16f2c506a20 # 1.97
-      - name: Check dependency pins
-        run: |
-          ui_revision="$(git -C modules/ui rev-parse HEAD)"
-          for lockfile in frontend/pnpm-lock.yaml modules/plugins/examples/workbench/frontend/pnpm-lock.yaml; do
-            locked_revision="$(sed -nE 's@.*codeload.github.com/zyycn/codex-proxy-ui/tar.gz/([a-f0-9]{40}).*@\1@p' "$lockfile" | sort -u)"
-            if [ "$locked_revision" != "$ui_revision" ]; then
-              echo "::error file=$lockfile::UI dependency must match modules/ui ($ui_revision)"
-              exit 1
-            fi
-          done
+        uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
+        with:
+          toolchain: ${{ steps.toolchains.outputs.rust }}
       - name: Install development dependencies
         run: |
           pnpm --dir modules/ui install --frozen-lockfile

.github/workflows/release.yml

@@ -21,7 +21,7 @@ env:
 
 jobs:
   release-info:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 10
     outputs:
       tag: ${{ steps.version.outputs.tag }}
@@ -36,6 +36,8 @@ jobs:
       previous_tag: ${{ steps.version.outputs.previous_tag }}
       prerelease: ${{ steps.version.outputs.prerelease }}
       build_type: ${{ steps.version.outputs.build_type }}
+      rust: ${{ steps.toolchains.outputs.rust }}
+      rust_image: ${{ steps.toolchains.outputs.rust_image }}
 
     steps:
       - name: Checkout
@@ -44,156 +46,18 @@ jobs:
           ref: ${{ inputs.tag }}
           fetch-depth: 0
 
-      - name: Read release metadata
+      - name: Read release metadata and seal plugin manifest
         id: version
-        shell: bash
         env:
           RELEASE_TAG: ${{ inputs.tag }}
-        run: |
-          ruby <<'RUBY' >> "$GITHUB_OUTPUT"
-          require "json"
-          require "open3"
-          require "rubygems"
-          require "time"
-          require "yaml"
+        run: ruby .github/scripts/release-metadata.rb outputs "$RELEASE_TAG" >> "$GITHUB_OUTPUT"
 
-          APP_NAME = "codex-proxy-rs"
-          SEMVER = /\A(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:alpha|beta|rc|exp)\.[1-9]\d*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?\z/
-
-          def fail(message)
-            warn(message)
-            exit(1)
-          end
-
-          def require_string(data, key, path)
-            value = data[key]
-            fail("#{path}: #{key} must be a non-empty string") unless value.is_a?(String) && !value.strip.empty?
-            value.strip
-          end
-
-          def version_sort_key(version)
-            Gem::Version.new(version.split("+", 2).first)
-          rescue ArgumentError
-            nil
-          end
-
-          version_path = "release/version.yaml"
-          platforms_path = "release/platforms.yaml"
-          version_data = YAML.load_file(version_path)
-          platforms_data = YAML.load_file(platforms_path)
-
-          version = require_string(version_data, "version", version_path).delete_prefix("v")
-          tag_prefix = "v"
-          expected_tag = "#{tag_prefix}#{version}"
-          release_tag = ENV.fetch("RELEASE_TAG")
-          fail("Release tag #{release_tag} does not match #{version_path} tag #{expected_tag}") unless release_tag == expected_tag
-          fail("#{version_path}: version #{version} is not a valid semver") unless version.match?(SEMVER)
-
-          notes_path = "release/notes.md"
-          fail("#{notes_path}: release notes are required") unless File.file?(notes_path)
-          notes = File.readlines(notes_path)
-          unless notes.first&.strip == "# #{release_tag}" && !notes.drop(1).join.strip.empty?
-            fail("#{notes_path}: expected non-empty notes starting with '# #{release_tag}'")
-          end
-
-          platforms = platforms_data["platforms"]
-          fail("#{platforms_path}: platforms must be a non-empty array") unless platforms.is_a?(Array) && !platforms.empty?
-
-          required_platform_keys = %w[os arch runner target binary archive]
-          seen_platforms = {}
-          docker_platform_jobs = []
-          non_docker_platform_jobs = []
-          docker_platforms = []
-          platforms.each_with_index do |platform, index|
-            fail("#{platforms_path}: platforms[#{index}] must be a table") unless platform.is_a?(Hash)
-            required_platform_keys.each do |key|
-              require_string(platform, key, "#{platforms_path}: platforms[#{index}]")
-            end
-            archive = platform["archive"]
-            fail("#{platforms_path}: platforms[#{index}].archive must be tar.gz") unless archive == "tar.gz"
-            platform_key = "#{platform["os"]}-#{platform["arch"]}"
-            fail("#{platforms_path}: duplicate platform #{platform_key}") if seen_platforms[platform_key]
-            seen_platforms[platform_key] = true
-            platform["artifact"] = "#{APP_NAME}-#{platform_key}"
-            if platform["docker"] == true
-              docker_platform = require_string(platform, "dockerPlatform", "#{platforms_path}: platforms[#{index}]")
-              platform["dockerPlatform"] = docker_platform
-              docker_platform_jobs << platform
-              docker_platforms << docker_platform
-            else
-              non_docker_platform_jobs << platform
-            end
-          end
-
-          fail("#{platforms_path}: at least one platform must set docker = true") if docker_platforms.empty?
-
-          git_sha, status = Open3.capture2("git", "rev-parse", "HEAD")
-          fail("failed to resolve git sha") unless status.success?
-          matrix = JSON.generate({ "include" => platforms })
-          docker_matrix = JSON.generate({ "include" => docker_platform_jobs })
-          non_docker_matrix = JSON.generate({ "include" => non_docker_platform_jobs })
-          current_sort_key = version_sort_key(version)
-          tags, status = Open3.capture2("git", "tag", "--list", "#{tag_prefix}*", "--merged", "HEAD")
-          fail("failed to list git tags") unless status.success?
-          previous_tag = tags
-            .lines
-            .map(&:strip)
-            .reject(&:empty?)
-            .reject { |tag| tag == release_tag }
-            .filter_map do |tag|
-              tag_version = tag.delete_prefix(tag_prefix)
-              next unless tag_version.match?(SEMVER)
-              sort_key = version_sort_key(tag_version)
-              next unless sort_key && current_sort_key && sort_key < current_sort_key
-              [sort_key, tag]
-            end
-            .max_by(&:first)
-            &.last
-
-          puts "tag=#{release_tag}"
-          puts "version=#{version}"
-          # Docker tags forbid "+", so semver build metadata maps to "-" in image tags.
-          puts "docker_version=#{version.tr("+", "-")}"
-          puts "build_time=#{Time.now.utc.iso8601}"
-          puts "git_sha=#{git_sha.strip}"
-          puts "platform_matrix=#{matrix}"
-          puts "docker_matrix=#{docker_matrix}"
-          puts "non_docker_matrix=#{non_docker_matrix}"
-          puts "docker_platforms=#{docker_platforms.join(",")}"
-          puts "previous_tag=#{previous_tag}"
-          puts "prerelease=#{version.split("+", 2).first.include?("-")}"
-          puts "build_type=#{version.split("+", 2).first.include?("-exp.") ? "experimental" : "release"}"
-          RUBY
-
-      - name: Seal plugin release manifest
-        env:
-          VERSION: ${{ steps.version.outputs.version }}
-          GIT_SHA: ${{ steps.version.outputs.git_sha }}
-        run: |
-          ruby <<'RUBY'
-          require "fileutils"
-          require "json"
-
-          host_path = "backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json"
-          host = JSON.parse(File.read(host_path))
-          abort "Invalid plugin host compatibility declaration: #{host_path}" unless host["schema_version"] == 2
-          # 保留旧更新器可解析的传输格式，实际支持范围仍取自当前宿主合同。
-          host = host.merge("schema_version" => 1, "permissions" => [])
-          # 清单只依赖版本与兼容声明，平台归档和镜像消费同一份封口结果。
-          manifest = {
-            "schema_version" => 1,
-            "sealed" => true,
-            "gateway_version" => ENV.fetch("VERSION"),
-            "gateway_git_sha" => ENV.fetch("GIT_SHA"),
-            "plugin_host" => host,
-            "plugins" => [],
-          }
-          FileUtils.mkdir_p("dist/plugin-release-assets")
-          File.write("dist/plugin-release-assets/plugin-release-manifest.json", JSON.pretty_generate(manifest) + "\n")
-          RUBY
+      - name: Read build toolchains
+        id: toolchains
+        run: ruby .github/scripts/toolchains.rb >> "$GITHUB_OUTPUT"
 
       - name: Upload sealed plugin assets
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: plugin-release-assets
           path: dist/plugin-release-assets
@@ -209,7 +73,7 @@ jobs:
 
   frontend:
     needs: release-info
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 15
     env:
       CI: 'true'
@@ -247,7 +111,7 @@ jobs:
             ~/.cargo/git
             backend/target
           # 按目标、工具链和依赖保存，不为每个发行提交复制整个 target
-          key: cargo-v3-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml', '.github/workflows/release.yml') }}
+          key: cargo-v3-${{ runner.os }}-${{ matrix.target }}-${{ needs.release-info.outputs.rust_image }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}
           restore-keys: |
             cargo-v3-${{ runner.os }}-${{ matrix.target }}-
 
@@ -267,18 +131,19 @@ jobs:
             -v "$HOME/.cargo:/cargo" \
             -v "$PWD/..:/workspace" \
             -w /workspace/backend \
-            rust:1.97-bookworm@sha256:77fac8b98f9f46062bb680b6d25d5bcaabfc400143952ebc572e924bcbedc3fa \
+            "${RUST_IMAGE}" \
             cargo build --release --locked --target "${{ matrix.target }}" --bin codex-proxy-rs
           cp "target/${{ matrix.target }}/release/${{ matrix.binary }}" "../dist/binaries/${{ matrix.os }}-${{ matrix.arch }}/${{ matrix.binary }}"
         working-directory: backend
         env:
+          RUST_IMAGE: ${{ needs.release-info.outputs.rust_image }}
           CPR_VERSION: ${{ needs.release-info.outputs.version }}
           CPR_GIT_SHA: ${{ needs.release-info.outputs.git_sha }}
           CPR_BUILD_TIME: ${{ needs.release-info.outputs.build_time }}
           CPR_BUILD_TYPE: ${{ needs.release-info.outputs.build_type }}
 
       - name: Upload binary artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: codex-proxy-rs-${{ matrix.os }}-${{ matrix.arch }}
           path: dist/binaries/${{ matrix.os }}-${{ matrix.arch }}/
@@ -301,8 +166,9 @@ jobs:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
       - name: Setup Rust
-        uses: dtolnay/rust-toolchain@1a3a6d54512beeaffd394f8d516ca16f2c506a20 # 1.97
+        uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
         with:
+          toolchain: ${{ needs.release-info.outputs.rust }}
           targets: ${{ matrix.target }}
 
       - name: Cache Cargo
@@ -312,7 +178,7 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             backend/target
-          key: cargo-v3-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml', '.github/workflows/release.yml') }}
+          key: cargo-v3-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}
           restore-keys: |
             cargo-v3-${{ runner.os }}-${{ matrix.target }}-
 
@@ -330,7 +196,7 @@ jobs:
           CPR_BUILD_TYPE: ${{ needs.release-info.outputs.build_type }}
 
       - name: Upload binary artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: codex-proxy-rs-${{ matrix.os }}-${{ matrix.arch }}
           path: dist/binaries/${{ matrix.os }}-${{ matrix.arch }}/
@@ -339,7 +205,7 @@ jobs:
 
   package-assets:
     needs: [release-info, frontend, build-docker-binary, build-binary]
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 20
     permissions:
       contents: read
@@ -353,19 +219,19 @@ jobs:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
       - name: Download frontend artifact
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: frontend-dist
           path: dist/frontend
 
       - name: Download binary artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           pattern: codex-proxy-rs-*
           path: dist/binaries
 
       - name: Download sealed plugin assets
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: plugin-release-assets
           path: dist/plugin-release-assets
@@ -375,101 +241,8 @@ jobs:
         env:
           VERSION: ${{ needs.release-info.outputs.version }}
           DOCKER_VERSION: ${{ needs.release-info.outputs.docker_version }}
-        run: |
-          set -euo pipefail
-          ruby <<'RUBY' > release-platforms.json
-          require "json"
-          require "yaml"
-
-          print JSON.generate(YAML.load_file("release/platforms.yaml"))
-          RUBY
-          python3 - <<'PY'
-          import hashlib
-          import json
-          import os
-          import pathlib
-          import shutil
-          import tarfile
-
-          APP_NAME = "codex-proxy-rs"
-
-          def sha256(path: pathlib.Path) -> str:
-              digest = hashlib.sha256()
-              with path.open("rb") as file:
-                  for chunk in iter(lambda: file.read(1024 * 1024), b""):
-                      digest.update(chunk)
-              return digest.hexdigest()
-
-          version = os.environ["VERSION"]
-          platforms = json.loads(pathlib.Path("release-platforms.json").read_text())["platforms"]
-          frontend_dir = pathlib.Path("dist/frontend")
-          binary_artifacts_dir = pathlib.Path("dist/binaries")
-          release_dir = pathlib.Path("dist/release")
-          package_dir = pathlib.Path("package")
-
-          shutil.rmtree(release_dir, ignore_errors=True)
-          release_dir.mkdir(parents=True)
-          config_template = pathlib.Path("deploy/config.example.yaml")
-          shutil.copy2(config_template, release_dir / config_template.name)
-          compose = pathlib.Path("deploy/compose.yaml").read_text()
-          image = f"{os.environ['REGISTRY']}/{os.environ['IMAGE_NAME']}"
-          default_image = "${CPR_IMAGE:-" + image + ":latest}"
-          if compose.count(default_image) != 1:
-              raise SystemExit("Expected exactly one default application image in deploy/compose.yaml")
-          # 发布附件固定镜像版本，防止后续 pull 与随包配置模板脱节。
-          versioned_image = "${CPR_IMAGE:-" + f"{image}:{os.environ['DOCKER_VERSION']}" + "}"
-          compose = compose.replace(default_image, versioned_image)
-          (release_dir / "compose.yaml").write_text(compose)
-          assets = [release_dir / config_template.name, release_dir / "compose.yaml"]
-          shutil.rmtree(package_dir, ignore_errors=True)
-          release_packages = []
-
-          for platform in platforms:
-              platform_name = f"{platform['os']}-{platform['arch']}"
-              artifact_name = f"{APP_NAME}-{platform_name}"
-              binary_src = binary_artifacts_dir / artifact_name / platform["binary"]
-              if not binary_src.is_file():
-                  raise SystemExit(f"Missing binary artifact: {binary_src}")
-
-              package_root = package_dir / platform_name / APP_NAME
-              web_dist = package_root / "web" / "dist"
-              web_dist.mkdir(parents=True)
-
-              binary_dest = package_root / platform["binary"]
-              shutil.copy2(binary_src, binary_dest)
-              binary_dest.chmod(0o755)
-              shutil.copytree(frontend_dir, web_dist, dirs_exist_ok=True)
-              deploy_dir = package_root / "deploy"
-              deploy_dir.mkdir()
-              shutil.copy2(config_template, deploy_dir / config_template.name)
-
-              archive_name = f"{APP_NAME}_{version}_{platform['os']}_{platform['arch']}.{platform['archive']}"
-              archive_path = release_dir / archive_name
-              if platform["archive"] != "tar.gz":
-                  raise SystemExit(f"Unsupported archive format: {platform['archive']}")
-              release_packages.append((platform, package_root, archive_path))
-
-          plugin_manifest_path = release_dir / "plugin-release-manifest.json"
-          shutil.copy2("dist/plugin-release-assets/plugin-release-manifest.json", plugin_manifest_path)
-          assets.append(plugin_manifest_path)
-
-          # 保留运行时清单目录合同，宿主包不再携带教学示例。
-          for platform, package_root, archive_path in release_packages:
-              official_dir = package_root / "plugins" / "official"
-              official_dir.mkdir(parents=True)
-              bundled_manifest = official_dir / plugin_manifest_path.name
-              shutil.copy2(plugin_manifest_path, bundled_manifest)
-              bundled_manifest.chmod(0o444)
-              official_dir.chmod(0o555)
-              with tarfile.open(archive_path, "w:gz") as archive:
-                  archive.add(package_root, arcname=APP_NAME)
-              assets.append(archive_path)
-
-          checksum_path = release_dir / "checksums.txt"
-          with checksum_path.open("w", encoding="utf-8") as file:
-              for asset in assets:
-                  file.write(f"{sha256(asset)}  {asset.name}\n")
-          PY
+          PLATFORM_MATRIX: ${{ needs.release-info.outputs.platform_matrix }}
+        run: ruby .github/scripts/package-release.rb archives
 
       - name: Generate release asset provenance
         uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
@@ -477,7 +250,7 @@ jobs:
           subject-path: dist/release/*
 
       - name: Upload release assets
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: release-assets
           path: dist/release
@@ -510,19 +283,19 @@ jobs:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
       - name: Download frontend artifact
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: frontend-dist
           path: dist/docker/web/dist
 
       - name: Download Docker binary artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: codex-proxy-rs-${{ matrix.os }}-${{ matrix.arch }}
           path: dist/docker-artifacts/codex-proxy-rs-${{ matrix.os }}-${{ matrix.arch }}
 
       - name: Download sealed plugin assets
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: plugin-release-assets
           path: dist/plugin-release-assets
@@ -533,56 +306,7 @@ jobs:
           MATRIX_OS: ${{ matrix.os }}
           MATRIX_ARCH: ${{ matrix.arch }}
           MATRIX_BINARY: ${{ matrix.binary }}
-        run: |
-          set -euo pipefail
-          python3 - <<'PY'
-          import json
-          import shutil
-          import os
-          import pathlib
-
-          app_name = "codex-proxy-rs"
-          platform_name = f"{os.environ['MATRIX_OS']}-{os.environ['MATRIX_ARCH']}"
-          binary_src = pathlib.Path("dist/docker-artifacts") / f"{app_name}-{platform_name}" / os.environ["MATRIX_BINARY"]
-          if not binary_src.is_file():
-              raise SystemExit(f"Missing Docker binary artifact: {binary_src}")
-
-          target_dir = pathlib.Path("dist/docker") / platform_name
-          target_dir.mkdir(parents=True, exist_ok=True)
-          binary_dest = target_dir / app_name
-          shutil.copy2(binary_src, binary_dest)
-          binary_dest.chmod(0o755)
-
-          release_dir = pathlib.Path("dist/plugin-release-assets")
-          manifest_path = release_dir / "plugin-release-manifest.json"
-          manifest = json.loads(manifest_path.read_text())
-          if manifest.get("schema_version") != 1 or manifest.get("sealed") is not True:
-              raise SystemExit("Invalid sealed plugin release manifest")
-          official_dir = target_dir / "plugins" / "official"
-          official_dir.mkdir(parents=True)
-          bundled_manifest = official_dir / manifest_path.name
-          shutil.copy2(manifest_path, bundled_manifest)
-          bundled_manifest.chmod(0o444)
-          selected = 0
-          for plugin in manifest.get("plugins", []):
-              artifacts = [
-                  artifact for artifact in plugin.get("artifacts", [])
-                  if artifact.get("release_os") == os.environ["MATRIX_OS"]
-                  and artifact.get("release_architecture") == os.environ["MATRIX_ARCH"]
-              ]
-              if len(artifacts) != 1:
-                  raise SystemExit(f"Official plugin platform selection is not unique: {plugin.get('id')}")
-              archive = release_dir / artifacts[0]["archive"]
-              if not archive.is_file():
-                  raise SystemExit(f"Missing official plugin archive: {archive.name}")
-              bundled_archive = official_dir / archive.name
-              shutil.copy2(archive, bundled_archive)
-              bundled_archive.chmod(0o444)
-              selected += 1
-          if selected != len(manifest.get("plugins", [])):
-              raise SystemExit("Official plugin release bundle is incomplete")
-          official_dir.chmod(0o555)
-          PY
+        run: ruby .github/scripts/package-release.rb image
 
       - name: Setup Docker Buildx
         uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
@@ -638,7 +362,7 @@ jobs:
           printf '%s\n' "$IMAGE_DIGEST" > "dist/digests/linux-${IMAGE_ARCH}.txt"
 
       - name: Upload verified image digest
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: image-digest-${{ matrix.os }}-${{ matrix.arch }}
           path: dist/digests/*.txt
@@ -646,9 +370,12 @@ jobs:
           retention-days: 1
 
   publish:
+    concurrency:
+      group: release-publication
+      queue: max
     # 产物准备可与测试重叠，版本标签和 GitHub Release 必须等全部质量与镜像验证通过
     needs: [release-info, quality, package-assets, build-docker-image]
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 20
     permissions:
       contents: write
@@ -663,13 +390,13 @@ jobs:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
       - name: Download release assets
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: release-assets
           path: dist/release
 
       - name: Download verified image digests
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           pattern: image-digest-*
           path: dist/digests
@@ -688,14 +415,12 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Create app image manifest
+      - name: Assemble candidate image manifest
         id: manifest
         shell: bash
         env:
-          DOCKER_VERSION: ${{ needs.release-info.outputs.docker_version }}
           GIT_SHA: ${{ needs.release-info.outputs.git_sha }}
           DOCKER_PLATFORMS: ${{ needs.release-info.outputs.docker_platforms }}
-          PRERELEASE: ${{ needs.release-info.outputs.prerelease }}
         run: |
           set -euo pipefail
 
@@ -719,16 +444,10 @@ jobs:
             exit 1
           fi
 
-          target_args=(
-            -t "${image}:${DOCKER_VERSION}"
-            -t "${image}:sha-${GIT_SHA}"
-          )
-          if [ "$PRERELEASE" != true ]; then
-            target_args+=(-t "${image}:latest")
-          fi
-          docker buildx imagetools create "${target_args[@]}" "${sources[@]}"
+          candidate="${image}:sha-${GIT_SHA}"
+          docker buildx imagetools create -t "$candidate" "${sources[@]}"
 
-          inspect_output="$(docker buildx imagetools inspect "${image}:${DOCKER_VERSION}")"
+          inspect_output="$(docker buildx imagetools inspect "$candidate")"
           platform_list="$(awk '$1 == "Platform:" { print $2 }' <<< "${inspect_output}")"
           for platform in "${platforms[@]}"; do
             if ! grep -Eq "^${platform}(/|$)" <<< "${platform_list}"; then
@@ -738,7 +457,7 @@ jobs:
             fi
           done
 
-          digest="$(docker buildx imagetools inspect "${image}:${DOCKER_VERSION}" --format '{{ .Manifest.Digest }}')"
+          digest="$(docker buildx imagetools inspect "$candidate" --format '{{ .Manifest.Digest }}')"
           if [ -z "${digest}" ]; then
             echo "missing image digest"
             exit 1
@@ -752,31 +471,10 @@ jobs:
           subject-digest: ${{ steps.manifest.outputs.digest }}
           push-to-registry: true
 
-      - name: Sign app image
-        shell: bash
+      - name: Sign app image digest
         env:
           DIGEST: ${{ steps.manifest.outputs.digest }}
-          DOCKER_VERSION: ${{ needs.release-info.outputs.docker_version }}
-          GIT_SHA: ${{ needs.release-info.outputs.git_sha }}
-          PRERELEASE: ${{ needs.release-info.outputs.prerelease }}
-        run: |
-          set -euo pipefail
-          if [ -z "${DIGEST}" ]; then
-            echo "missing image digest"
-            exit 1
-          fi
-
-          image="${REGISTRY}/${IMAGE_NAME}"
-          tags=("${image}:${DOCKER_VERSION}" "${image}:sha-${GIT_SHA}")
-          if [ "$PRERELEASE" != true ]; then
-            tags+=("${image}:latest")
-          fi
-          images=()
-          for tag in "${tags[@]}"; do
-            images+=("${tag}@${DIGEST}")
-          done
-
-          cosign sign --yes "${images[@]}"
+        run: cosign sign --yes "${REGISTRY}/${IMAGE_NAME}@${DIGEST}"
 
       - name: Prepare release notes
         shell: bash
@@ -805,25 +503,33 @@ jobs:
             - [GitHub 仓库](https://github.com/${{ github.repository }})
             - [部署指南](https://github.com/${{ github.repository }}/blob/${{ needs.release-info.outputs.tag }}/deploy/README.md)
         run: |
-          python3 <<'PY'
-          import os
-          from pathlib import Path
+          ruby <<'RUBY'
+          notes = File.readlines('release/notes.md').drop(1).join.strip
+          installation = ENV.fetch('INSTALLATION_NOTES').strip
+          output = File.join(ENV.fetch('RUNNER_TEMP'), 'release-notes.md')
+          File.write(output, "#{notes}\n\n#{installation}\n")
+          RUBY
 
-          notes = "\n".join(Path("release/notes.md").read_text().splitlines()[1:]).strip()
-          installation = os.environ["INSTALLATION_NOTES"].strip()
-          output = Path(os.environ["RUNNER_TEMP"]) / "release-notes.md"
-          output.write_text(f"{notes}\n\n{installation}\n")
-          PY
-
-      - name: Publish GitHub Release
+      - name: Upload GitHub Release assets
+        id: release
         uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
         with:
           tag_name: ${{ needs.release-info.outputs.tag }}
           generate_release_notes: true
           previous_tag: ${{ needs.release-info.outputs.previous_tag }}
           prerelease: ${{ needs.release-info.outputs.prerelease == 'true' }}
-          make_latest: ${{ needs.release-info.outputs.prerelease == 'true' && 'false' || 'true' }}
+          # action 保留已公开 Release 的状态，新 Release 上传完成后仍保持草稿
+          draft: true
+          make_latest: 'false'
           body_path: ${{ runner.temp }}/release-notes.md
           fail_on_unmatched_files: true
           files: |
             dist/release/*
+
+      - name: Publish version and advance latest
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.release-info.outputs.version }}
+          DIGEST: ${{ steps.manifest.outputs.digest }}
+          RELEASE_ID: ${{ steps.release.outputs.id }}
+        run: ruby .github/scripts/publish-release.rb

.github/workflows/rules.yml

@@ -18,7 +18,7 @@ concurrency:
 
 jobs:
   guard:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 5
     steps:
       # 只查询 PR 元数据，禁止检出或执行贡献分支中的代码。
@@ -33,14 +33,23 @@ jobs:
               ...params,
               per_page: 100,
             });
+            // 按 PR 作者识别官方机器人，维护者重开或编辑 PR 时仍使用同一判断
+            const isDependabot = pr.user.login === 'dependabot[bot]'
+              && pr.user.type === 'Bot'
+              && pr.head.repo?.full_name === `${owner}/${repo}`;
+            const isDependencyUpdate = file => isDependabot
+              && file.status === 'modified'
+              && (/^\.github\/workflows\/[^/]+\.ya?ml$/.test(file.filename)
+                || /^\.github\/actions\/.+\/(?:action\.ya?ml|Dockerfile)$/.test(file.filename));
             const isProtectedRule = path => typeof path === 'string'
               && (path === 'AGENTS.md' || path.endsWith('/AGENTS.md')
                 || path === 'CONTRIBUTING.md'
                 || path === '.agents/skills' || path.startsWith('.agents/skills/')
                 || path === '.github' || path.startsWith('.github/'));
 
-            // 同时检查重命名前后的路径，避免通过移走规则文件绕过检查。
-            if (!files.some(file => isProtectedRule(file.filename) || isProtectedRule(file.previous_filename))) {
+            // 依赖更新只豁免已有文件的修改，重命名前后的受保护路径仍参与检查
+            if (!files.some(file => !isDependencyUpdate(file)
+              && (isProtectedRule(file.filename) || isProtectedRule(file.previous_filename)))) {
               core.info('No protected contribution rule changes detected.');
               return;
             }
@@ -56,7 +65,7 @@ jobs:
             const marker = '<!-- agents-md-guard -->';
             const body = [
               marker,
-              '佬友，我看到这个 PR 涉及受保护的协作规则文件，按仓库约定需要先关闭',
+              '我看到这个 PR 涉及受保护的协作规则文件，按仓库约定需要先关闭',
               '',
               '保护范围包括根目录或子目录的 `AGENTS.md`、根目录的 `CONTRIBUTING.md`，以及 `.agents/skills/` 和 `.github/` 中的所有文件，涵盖新增、修改、删除和重命名',
               '',

.github/workflows/security.yml

@@ -19,7 +19,7 @@ concurrency:
 
 jobs:
   backend-security:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 20
     steps:
       - name: Checkout
@@ -28,7 +28,7 @@ jobs:
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
       - name: Install cargo-audit
-        uses: taiki-e/install-action@4cef1412cce204788f482e778a0b9187f9626a29 # v2.87.21
+        uses: taiki-e/install-action@8cca0918f8471c33515202b73f56ab27f2bed283 # v2.87.29
         with:
           tool: cargo-audit@0.22.2
           fallback: none
@@ -38,7 +38,7 @@ jobs:
           cargo-audit audit --file backend/Cargo.lock
 
   frontend-security:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 15
     steps:
       - name: Checkout
@@ -51,10 +51,14 @@ jobs:
         with:
           package_json_file: frontend/package.json
 
+      - name: Read build toolchains
+        id: toolchains
+        run: ruby .github/scripts/toolchains.rb >> "$GITHUB_OUTPUT"
+
       - name: Setup Node
-        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
-          node-version: 24
+          node-version: ${{ steps.toolchains.outputs.node }}
           cache: pnpm
           cache-dependency-path: frontend/pnpm-lock.yaml
 

AGENTS.md

@@ -4,19 +4,21 @@
 
 | 任务意图与常见说法 | 必用技能 |
 | --- | --- |
-| 开发、实现、修复、排查报错、审查问题或代码、修改文档 | [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 |
+| 开发、修复、排障、代码审查、改文档；包括“改弹窗／样式／文案”“修接口／调度／数据库”等省略请求 | [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-plugin-dev](.agents/skills/cpr-plugin-dev/SKILL.md)，同时执行 cpr-dev-guide；仅改宿主能力时由 cpr-dev-guide 加载插件边界 |
 | 发版、准备版本、发布 beta／实验版、整理发布说明、打发行 tag | [cpr-release](.agents/skills/cpr-release/SKILL.md) |
 
 结合上下文识别“提交吧”“看看这个问题”等省略说法：普通 Git 提交不自动变成 PR，代码排查不自动变成 Issue；审查与发版准备不代表获准远程写入
 
-只加载当前任务命中的技能、模式和文档章节，复用已有上下文，进入新阶段再补读；链接是按需入口，不是全文或全部参考文件的必读清单
+先完整读取命中技能的 `SKILL.md`，再读取其领域必读规范，之后按当前步骤补充实现、命令和示例。技能名称、描述或入口摘要不能代替正文与必读引用；引用中明确要求“先读”“必须读取”或“执行”的规范也要落实，其他资料按需读取
+
+按用户意图、行为影响和实际文件共同匹配，跨领域叠加；确定方案或给出审查结论前完成对应领域必读，不能因改动小、路径未落在该模块或自认为熟悉而跳过。只复用当前上下文中已实际读取且仍适用的内容；输出截断、上下文压缩后缺失的必要内容须补读，范围或阶段变化时重新匹配
 
 执行所选流程中的问题核实、自审、验证与交付要求，协作流程和审查标准见 [CONTRIBUTING.md](CONTRIBUTING.md)
 
-Issue 和 PR 回复分别按对应技能的[Issue 回复口吻](.agents/skills/cpr-github-issue/SKILL.md#回复口吻)与[PR 回复口吻](.agents/skills/cpr-github-pr/SKILL.md#回复口吻)执行
+Issue 和 PR 回复统一按 [GitHub 回复口吻](CONTRIBUTING.md#github-回复口吻)执行
 
 模块职责以 [系统架构](docs/architecture.md) 为准，界面约定以 [管理端主题](docs/theme.md) 为准；
 没有明确约定时保持与相邻实现一致，不把单次页面反馈扩展成全仓规则
@@ -34,10 +36,10 @@ If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is
 
 ## 工作方式
 
-- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题；涉及 Codex 行为、协议或兼容性时，按[参考仓库优先级](.agents/skills/cpr-dev-guide/SKILL.md#参考仓库的优先级)以官方 Codex 仓库对应版本源码为第一手资料，三方仓库仅作参考
+- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题及方案必要性；涉及 Codex 行为、协议或兼容性时，以官方对应版本源码为第一手资料，三方仓库仅作参考
 - 先定位变更所属模块、同类实现和上下游调用关系，再选择最小合理改动。复用已有能力，也避免为尚不存在的需求增加抽象。
 - 提交前自审最终差异，先处理本次引入的职责混淆、重复规则、冗余状态和无依据的兼容分支；后端按 [后端自审](docs/architecture.md#后端自审) 追踪状态与资源生命周期，不能把自审留给 CI 或 PR 审查者。
-- 页面变更先复用已有页面设计与组件，不因个人偏好重排页面或另建交互。文案取舍遵循 [界面文案与信息层级](docs/theme.md#界面文案与信息层级)，页面 PR 必须提供 [实际截图](CONTRIBUTING.md#界面验证)。
+- 前端开发与审查执行[前端流程](.agents/skills/cpr-dev-guide/references/frontend.md)，先复用已有页面设计与组件，不因个人偏好重排页面或另建交互；页面 PR 必须提供 [实际截图](CONTRIBUTING.md#界面验证)。
 - 代码注释使用中文，解释原因与边界；提交信息使用英文，沿用历史中的 Conventional Commits 格式。
 - 常规文档只描述当前状态，不记录变更历史；按[文档职责与更新条件](CONTRIBUTING.md#文档职责与更新条件)在所属章节就地修订，分清层次与详略，短段和列表少用句号，交付前逐段检查必要性、归属、重复与当前状态表达
 - 按变更范围执行验证，记录命令、结果和缺口。跳过的测试不算通过；界面与集成行为需要对应运行证据，构建通过不能替代实际验收。

CONTRIBUTING.md

@@ -19,15 +19,35 @@
 
 日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议说明使用场景、当前不便和期望行为；协作规则调整可直接提交普通 Issue，说明原因和建议方案
 
+### GitHub 回复口吻
+
+AI 草拟、发布或修改 Issue、PR 讨论及审查意见的回复时，以一起排查问题、讨论方案的口吻交流：
+
+- 围绕问题、事实和结论展开，能自然省略主语时省略；需要说明个人判断或行动归属时用“我”，避免反复以“我”起句或强调自己，不用“我们”“本助手”代称自己
+- 普通回复直接回应问题，不加问候语或称呼；向对方提问时称呼“佬”，同一条回复不重复称呼
+- 先接住对方想完成的事和遇到的困难，再给出核实结果与建议；回复让对方感到问题被理解、有下一步可做，避免一上来归类、纠正或划定责任
+- 建议用商量的口吻，说明尝试某个操作能帮助判断什么，给对方留出选择空间；“可以试试”“方便的话”等表达随语境使用，整句仍需自然，不靠堆叠缓和词修饰命令
+- 回应已有能力、暂不支持或未采纳的建议时，结合场景说明可用入口或具体原因，有可行替代办法时一并说明，再交代必要边界；避免只回复“已有功能”“重复问题”“不在范围内”等结论
+- 需要补充材料或配合操作时，先利用已有信息，只询问仍缺少的部分，说明用途和最小范围；例如“佬，方便再观察几次吗？如果还出现，可以附一下对应请求的诊断包，便于对照终态用量”
+- 澄清误解或提出不同意见时，从观察和依据说起，照顾对方的使用环境与理解路径，避免责备、反问或居高临下的判断；已确认的事实保持明确，尚未确认的原因保留余地
+- 使用自然短句，简单回复用短段，并列信息较多时再分点；少用句号，避免客服套话、机械模板和空泛保证
+- 排查、复现、修改和验证的完成状态与实际一致；未采纳的意见说明依据，未确认、待处理或未验证的内容如实交代，说清结论、限制和下一步
+
 ## 问题与方案依据
 
 开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题
 
-涉及上游协议、客户端行为或兼容性时，以对应版本的官方源码为首要资料。优先读取用户提供或本机已有的官方源码，核对仓库来源、版本或提交；本地资料不足时查官方仓库的对应版本源码，再结合官方测试、文档、发布说明和运行证据。第三方资料只作线索或补充。引用具体文件、符号或行号，对外引用优先使用固定提交的源码链接；源码不可得或版本不匹配时说明证据缺口，不把最新实现当成当前部署行为。无上游依赖的内部变更，以本项目代码、合同和运行证据为依据
+涉及上游协议、客户端行为或兼容性时，遵守以下依据与行为约束；无上游依赖的内部变更以本项目代码、合同和运行证据为依据
 
-官方已有同一场景的处理方式时，优先沿用其协议语义、职责归属和解决路径，检查是否只需复用已有能力或正确传递官方合同。新增覆盖配置、补偿逻辑或采用第三方兼容方案，应说明官方路径为何不足；偏离官方方案需有本项目的实际约束和验证依据，不机械照搬源码，也不默认接受已有提案
+- **资料来源**：以对应版本的官方源码与调用链为首要资料，Codex 对照 [openai/codex](https://github.com/openai/codex)。先查用户提供或本机已有的仓库，核对来源、版本或提交；不足时再查官方对应版本源码，结合测试、文档、发布说明和运行证据。三方资料只作线索或实现参考，不能替代官方依据
+- **证据表达**：引用具体文件、符号或行号，对外优先使用固定提交的源码链接；注明适用版本，区分官方事实、三方参考与本项目推断。源码不可得或版本不匹配时报告缺口，不把最新实现当作部署行为，也不把自定义策略写成官方要求
+- **默认方案**：Codex 兼容性优先保持官方行为，以透明转发和最小必要适配为默认方案。沿用官方协议语义、职责归属和解决路径，优先复用已有能力或正确传递合同，不额外解释请求意图、扩展工具权限或改变续接语义
+- **问题核实**：对照官方与 CPR 的实际请求、响应及状态生命周期，检查本项目是否误解、改写、遗漏或破坏合同；分别说明源码推断、代理链路复现与官方直连结果。真实上游报错不自动等于 CPR 缺陷
+- **审查官方对接**：审查 OpenAI 官方上游与 Codex 的对接时，默认二者兼容、直接对接正常。不得仅凭自行构造的异常上游数据揣测官方不兼容，据此报告缺陷、提出改进建议或要求防御分支与测试；特定版本或场景的例外须有真实响应或实际复现证据
+- **偏离依据**：新增覆盖配置、补偿逻辑或三方兼容方案前，说明官方路径为何不足、本项目实际约束、最小改动、行为代价及验证。补偿后成功、测试通过或三方采用同一做法不能单独证明必要性；依据不足时保持现有合同并报告缺口，不先加分支再倒推理由。用户明确要求的行为变更限定在授权范围内
+- **网关职责**：调度、隔离和资源管理按网关职责评估，不机械照搬单客户端实现，不因官方客户端没有同类池策略就判错，也不任意改变客户端可观察行为。新增默认限制或回收阈值须有容量依据，并验证续接、重试与延迟影响
 
-反馈 Issue 时区分观察到的症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。能说明问题的反馈可以先提交，不要求报告者先找到官方源码或证明根因；引用官方行为或提出实现方案时，按上述原则注明依据与缺口
+反馈 Issue 时区分症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。症状反馈不以找到官方源码或证明根因为前提；引用上游行为或提出方案时注明上述依据与缺口
 
 ## PR 流程
 
@@ -69,7 +89,9 @@ PR 不接受以下协作规则文件的新增、修改、删除或重命名：
 - `.agents/skills/` 中的所有文件，包括技能入口、引用文档、配置和脚本
 - `.github/` 中的所有文件，包括工作流、Actions、Issue／PR 模板和依赖更新配置
 
-调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；[规则保护工作流](.github/workflows/rules.yml) 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查
+官方 `dependabot[bot]` 从本仓库分支发起的依赖更新可修改 `.github/workflows/` 中已有的 YAML 工作流，以及 `.github/actions/` 下已有的 `action.yml`、`action.yaml` 和 `Dockerfile`，继续执行正常审查与 CI；其他受保护文件以及新增、删除、重命名不在例外范围内
+
+除此之外，调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；[规则保护工作流](.github/workflows/rules.yml) 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查
 
 源码变更遵守现有架构边界与迁移冻结规则，由对应 CI 检查执行；不额外设立整块业务目录的 PR 禁改清单。构建、测试和安全扫描复用现有工作流
 
@@ -127,6 +149,9 @@ PR 不接受以下协作规则文件的新增、修改、删除或重命名：
 | [插件使用](docs/plugins.md) | 如何安装、授权、配置和使用插件 | 管理员操作与影响，不展开 SDK 调用或宿主事务实现 |
 | [插件 SDK](backend/crates/gateway-plugin/sdk/README.md) / [CLI](backend/apps/plugin-cli/README.md) | 如何编写和打包插件 | 作者合同、权限边界、示例与打包验证 |
 | [数据库迁移](backend/migrations/README.md) | 如何维护 schema 和准备测试库 | 冻结规则、升级约束和测试环境，不罗列迁移历史 |
+| [共用组件](modules/ui/README.md)及其组件参考 | 如何安装、使用和开发独立 UI 库 | 组件公开 API、主题能力与库内开发；宿主页面约定归管理端主题，跨仓库联调归开发文档 |
+| [官方插件示例](modules/plugins/README.md)及其示例说明 | 如何构建、使用和维护示例插件 | 示例自身的功能、配置与验证；通用协议归 SDK，宿主安装操作归插件使用文档 |
+| [AGENTS.md](AGENTS.md) 与[项目技能](.agents/skills/cpr-dev-guide/SKILL.md) | AI 如何选择并执行任务流程 | 任务匹配、执行步骤和规范入口，不另建模块合同、版本表或协作标准 |
 | 本文 | 如何协作、审查和交付 | 流程、判断标准与验证要求，任务入口由 [开发技能](.agents/skills/cpr-dev-guide/SKILL.md) 串联 |
 
 - 同一事实只在所属文档完整说明，其他位置按读者任务保留必要摘要和链接
@@ -147,7 +172,7 @@ PR 不接受以下协作规则文件的新增、修改、删除或重命名：
 
 ## 界面验证
 
-AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方案以本项目的用户任务、[管理端主题](docs/theme.md) 和已有页面为依据，优先延续原页面的布局、信息层级与交互；设计技能不构成重做页面的理由
+AI 进行前端开发或审查时，执行[前端流程](.agents/skills/cpr-dev-guide/references/frontend.md)，覆盖页面、组件、弹窗、表单及局部文案和样式。用户指定设计技能时使用该技能；未指定时，只有任务明确需要建立或重塑视觉方向才使用 `$frontend-design`。新增页面也优先沿用 [管理端主题](docs/theme.md) 和已有设计，设计技能不构成重做页面的理由
 
 开发前查找原页面、同类页面及 `modules/ui/src/components` 中的基础组件，明确参考实现和可复用部分，再确定最小改动。只有原设计不能满足本次操作或存在具体问题时才调整结构，并在 PR 中说明原因；不顺带换风格、重排无关区域或增加重复的模式入口。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题
 
@@ -163,11 +188,17 @@ AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方
 
 截图用于视觉审阅，保存、切换、错误恢复和键盘操作等行为仍需实际验证并记录覆盖范围，不能仅凭静态图片推断交互正确
 
+当前用户明确接管或确认本轮视觉验收时，沿用约定分工和结果；明确免除本次截图时，该项不再阻塞交付或要求 Draft。报告区分用户确认、AI 实测和未验证，其他验证仍执行；后续修改只复核受影响部分
+
 涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 HTTP/HTTPS、localhost/实际部署地址与浏览器版本，记录实际覆盖的条件；本地预览正常不能替代部署环境中的交互验收
 
 ## 验证
 
-选择与变更相关的检查，纯文档修改无需重建前后端。行为修复补充能覆盖触发条件和结果的测试，不增加仅复述实现的断言
+按变更风险明确要验证的行为与通过条件，优先复用现有检查；缺少有效回归覆盖时补充行为测试，不为表名、字段清单或 SQL 文本形状单独保留测试，也不增加仅复述实现的断言。纯文档修改无需重建前后端
+
+必要验证通过且没有新改动、失败或未解疑点后停止扩围与重复运行。真实账号验证满足约定场景后即收尾，不无目的重复请求；用户限定验证范围或次数时按其要求执行，未覆盖项如实列出
+
+临时预览、模拟数据、诊断脚本与压测产物放在 `.runtime/` 或系统临时目录，使用后按需清理；只有持续维护的工具和回归测试进入源码目录，不把一次性验收产物混进 `src/`、`examples/` 或正式提交
 
 | 范围 | 现有检查 | 仍需提供的证据 |
 | --- | --- | --- |

README.md

@@ -21,7 +21,7 @@
 
 ## 快速预览
 
-无需部署，打开 [快速预览服务](https://codex-proxy-rs.ainz.cc) 即可体验管理端的系统概览、账号分组、代理管理与用量统计
+无需部署即可体验管理端的系统概览、账号分组、代理管理与用量统计：
 
 | 登录信息 | 默认值 |
 | --- | --- |
@@ -53,8 +53,7 @@ curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/in
 [安装脚本](deploy/install.sh) 默认安装到当前目录下的 `codex-proxy-rs/`，下载同一正式 Release 的部署文件，
 自动生成密码、设置目录权限并启动服务
 
-完成后会显示访问地址和管理员密码，请保存密码，再按下方步骤
-[添加账号与客户端密钥](#添加账号与客户端密钥)
+完成后保存显示的访问地址和管理员密码，再[登录管理端](#登录管理端)并[添加账号与客户端密钥](#添加账号与客户端密钥)
 
 可在执行 `bash install.sh` 时传入环境变量：
 
@@ -81,7 +80,7 @@ INSTALL_DIR="$HOME/services/codex-proxy-rs" bash install.sh
 
 部署完成后，打开 `http://127.0.0.1:8080`，使用 `admin@cpr.local` 和管理员密码登录
 
-API Key 持有者可在登录页切换身份，查看自己的用量与额度，并通过「密钥配置」复制 Codex 配置或导入 CCSwitch
+API Key 持有者可在登录页切换身份，查看自己的用量与额度，并通过「密钥配置」复制 Codex 配置或导入 CC Switch
 
 默认地址只能在服务器本机访问，从其他设备使用时，需要配置
 [HTTPS 反向代理](deploy/README.md#公网访问)
@@ -94,7 +93,7 @@ API Key 持有者可在登录页切换身份，查看自己的用量与额度，
 
 ## 客户端接入
 
-**Codex CLI / 桌面端**：在「使用密钥」中按操作系统复制配置，或通过 CCSwitch 导入，合并配置后重启 Codex
+**Codex CLI / 桌面端**：在「使用密钥」中按操作系统复制配置，合并配置后重启 Codex；也可通过「导入到」把服务连接与密钥添加到 CC Switch
 
 完整步骤、生图配置与排障见[客户端配置](deploy/README.md#客户端配置)
 
@@ -119,7 +118,8 @@ curl http://127.0.0.1:8080/v1/models \
 | 部署与使用 | [部署、备份与恢复](deploy/README.md) · [客户端接入与生图](deploy/README.md#客户端配置) |
 | 接口集成 | [API 参考](docs/api.md) · [模型定价](docs/api.md#模型定价) |
 | 使用插件 | [安装、配置与使用](docs/plugins.md) |
-| 开发插件 | [SDK 与合同](backend/crates/gateway-plugin/sdk/README.md) · [打包工具](backend/apps/plugin-cli/README.md) |
+| 开发插件 | [SDK 与合同](backend/crates/gateway-plugin/sdk/README.md) · [打包工具](backend/apps/plugin-cli/README.md) · [官方示例](modules/plugins/README.md) |
+| 开发共用组件 | [组件库说明](modules/ui/README.md) · [组件参考](modules/ui/playground/components/index.md) |
 | 开发宿主 | [开发与源码联调](docs/development.md) · [系统架构](docs/architecture.md) · [管理端主题](docs/theme.md) · [数据库迁移](backend/migrations/README.md) |
 | 参与协作 | [贡献、审查与验证](CONTRIBUTING.md) |
 

backend/Cargo.lock

@@ -31,6 +31,12 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "allocation-counter"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "beb9e990c0a33699f1984d85a6abead615ccc72dd8130bf3e15dcabe2ca149c9"
+
 [[package]]
 name = "allocator-api2"
 version = "0.2.21"
@@ -139,6 +145,18 @@ dependencies = [
  "serde_json",
 ]
 
+[[package]]
+name = "async-compression"
+version = "0.4.50"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee19bd99b43e3691acbad4e840420a4881cea6c0b66a208125a824f8fd53f5a1"
+dependencies = [
+ "compression-codecs",
+ "compression-core",
+ "pin-project-lite",
+ "tokio",
+]
+
 [[package]]
 name = "async-lock"
 version = "3.4.2"
@@ -180,7 +198,7 @@ checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.9",
 ]
 
 [[package]]
@@ -268,9 +286,9 @@ dependencies = [
 
 [[package]]
 name = "aws-sdk-s3"
-version = "1.149.0"
+version = "1.152.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d48257fb0eb1907a02a965ff7d1b910770a6de2c59a2d03461678df989c5cdcd"
+checksum = "004d5acbd6850ab58789a43822e0a2ef23927a46b012c17f8fa51253103db9f8"
 dependencies = [
  "arc-swap",
  "aws-credential-types",
@@ -297,7 +315,7 @@ dependencies = [
  "lru",
  "percent-encoding",
  "regex-lite",
- "sha2 0.11.0",
+ "sha2",
  "tracing",
  "url",
 ]
@@ -319,7 +337,7 @@ dependencies = [
  "hmac",
  "http",
  "percent-encoding",
- "sha2 0.11.0",
+ "sha2",
  "time",
  "tracing",
 ]
@@ -352,7 +370,7 @@ dependencies = [
  "md-5",
  "pin-project-lite",
  "sha1 0.11.0",
- "sha2 0.11.0",
+ "sha2",
  "tracing",
 ]
 
@@ -369,9 +387,9 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-http"
-version = "0.64.0"
+version = "0.64.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "37843d9add67c3aff5856f409c6dc315d3cdff60f9c0cb5b670dab1e9920306d"
+checksum = "639b4d8f8555f24a9be649811c3eb0b4d4616f4d61daf0c32e28873bc1ea9af1"
 dependencies = [
  "aws-smithy-eventstream",
  "aws-smithy-runtime-api",
@@ -391,9 +409,9 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-http-client"
-version = "1.4.2"
+version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7bd25384a4e437aa8d8f339afad4b69e786b936a7cb10db668a7aaf66717b1a8"
+checksum = "51c89cc3f1f281d659a67a519a1b5c6d445b5ce09fa7e5aee40c2c2707e9509d"
 dependencies = [
  "aws-smithy-async",
  "aws-smithy-runtime-api",
@@ -435,9 +453,9 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-runtime"
-version = "1.15.0"
+version = "1.16.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "591e0024cdf2a8de8711860f7e1d5cfbca26b800ce13793a9aa2f4f5918e6d95"
+checksum = "d6e302ac1d88b99652489df31abdec6ac42a2ab2ac3982ad0ac49f64dfaf28ba"
 dependencies = [
  "aws-smithy-async",
  "aws-smithy-http",
@@ -459,9 +477,9 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-runtime-api"
-version = "1.18.0"
+version = "1.19.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9bb0deb40a69de59f7809251cfe1ab16de135f42c49d222d1202b4d0ce19720f"
+checksum = "c0730c16f91124c6a2abb4932c77e299288b3dd9f967ea2e9ec48cc6731e87a4"
 dependencies = [
  "aws-smithy-async",
  "aws-smithy-runtime-api-macros",
@@ -567,6 +585,7 @@ dependencies = [
  "matchit",
  "memchr",
  "mime",
+ "multer",
  "percent-encoding",
  "pin-project-lite",
  "serde_core",
@@ -772,9 +791,9 @@ checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
 
 [[package]]
 name = "chacha20"
-version = "0.10.1"
+version = "0.10.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d524456ba66e72eb8b115ff89e01e497f8e6d11d78b70b1aa13c0fbd97540a81"
+checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06"
 dependencies = [
  "cfg-if",
  "cpufeatures 0.3.0",
@@ -837,7 +856,7 @@ dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.9",
 ]
 
 [[package]]
@@ -870,7 +889,7 @@ dependencies = [
  "gateway-plugin-sdk",
  "hex",
  "serde_json",
- "sha2 0.11.0",
+ "sha2",
  "tar",
  "tempfile",
  "thiserror",
@@ -891,7 +910,7 @@ dependencies = [
  "provider-xai",
  "serde",
  "serde_json",
- "syn 3.0.6",
+ "syn 3.0.9",
  "tempfile",
  "thiserror",
  "tokio",
@@ -925,10 +944,27 @@ dependencies = [
 ]
 
 [[package]]
-name = "config"
-version = "0.15.26"
+name = "compression-codecs"
+version = "0.4.45"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "790374c727a4cb20877dd2cc99ce7011cbe03b0b8df083acccd37df0d161304d"
+checksum = "98fc98460ba0ad5317075d3632b8dfc45d0be8c4a49347c2a38272019717614a"
+dependencies = [
+ "compression-core",
+ "flate2",
+ "memchr",
+]
+
+[[package]]
+name = "compression-core"
+version = "0.4.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e8ccc4ea9f6acc32d102c0f6d471d11d913ad15f20c04de743374861fa1d414"
+
+[[package]]
+name = "config"
+version = "0.15.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38e9fbc53afcec54441422f1c596cd054655b32e70e1cbac956651b7b175a404"
 dependencies = [
  "pathdiff",
  "serde_core",
@@ -1093,9 +1129,9 @@ checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
 
 [[package]]
 name = "crypto-bigint"
-version = "0.7.5"
+version = "0.7.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1a52aa3fcda4e6302a9f48734f234d35d4721b96f8fe07d073f07ce9df4f0271"
+checksum = "6bb08299a6046833a879ace115697f12fd2bd6c8d3e93c909ffc9e0738e7cae0"
 dependencies = [
  "cpubits",
  "ctutils",
@@ -1153,9 +1189,9 @@ dependencies = [
 
 [[package]]
 name = "ctutils"
-version = "0.4.2"
+version = "0.4.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7d5515a3834141de9eafb9717ad39eea8247b5674e6066c404e8c4b365d2a29e"
+checksum = "38d28fb6aa7dd680b3ffd1a3e64e115c177bdba63c0ae7f9cd48129ff05c4fa0"
 dependencies = [
  "cmov",
  "subtle",
@@ -1621,7 +1657,7 @@ checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.9",
 ]
 
 [[package]]
@@ -1674,6 +1710,7 @@ dependencies = [
  "gateway-core",
  "heck",
  "hex",
+ "hkdf",
  "prettyplease",
  "quote",
  "rand_core 0.6.4",
@@ -1681,9 +1718,9 @@ dependencies = [
  "semver",
  "serde",
  "serde_json",
- "sha2 0.11.0",
+ "sha2",
  "subtle",
- "syn 2.0.119",
+ "syn 3.0.9",
  "tempfile",
  "thiserror",
  "tokio",
@@ -1709,10 +1746,11 @@ dependencies = [
  "http",
  "http-body",
  "http-body-util",
+ "regex",
  "secrecy",
  "serde",
  "serde_json",
- "sha2 0.11.0",
+ "sha2",
  "thiserror",
  "tokio",
  "tokio-tungstenite 0.29.0",
@@ -1721,6 +1759,7 @@ dependencies = [
  "tracing",
  "url",
  "uuid",
+ "zip",
  "zstd",
 ]
 
@@ -1728,19 +1767,21 @@ dependencies = [
 name = "gateway-core"
 version = "0.1.0"
 dependencies = [
+ "allocation-counter",
  "async-trait",
  "base64 0.23.1",
  "bytes",
+ "chrono",
  "chrono-tz",
+ "event-listener",
  "futures",
  "futures-timer",
  "http",
- "http-body",
  "http-body-util",
  "semver",
  "serde",
  "serde_json",
- "sha2 0.11.0",
+ "sha2",
  "thiserror",
  "tracing",
  "url",
@@ -1779,7 +1820,8 @@ dependencies = [
  "serde",
  "serde_ignored",
  "serde_json",
- "sha2 0.11.0",
+ "serde_path_to_error",
+ "sha2",
  "tar",
  "tempfile",
  "thiserror",
@@ -1820,7 +1862,7 @@ dependencies = [
  "semver",
  "serde",
  "serde_json",
- "sha2 0.11.0",
+ "sha2",
  "sqlx",
  "tar",
  "tempfile",
@@ -1837,6 +1879,7 @@ dependencies = [
 name = "gateway-plugin-sdk"
 version = "0.1.0"
 dependencies = [
+ "base64 0.23.1",
  "semver",
  "serde",
  "serde_json",
@@ -1848,6 +1891,8 @@ dependencies = [
 name = "gateway-protocol"
 version = "0.0.0"
 dependencies = [
+ "http",
+ "httpdate",
  "memchr",
  "serde",
  "serde_json",
@@ -1859,6 +1904,7 @@ dependencies = [
 name = "gateway-store"
 version = "0.1.0"
 dependencies = [
+ "async-compression",
  "async-stream",
  "async-trait",
  "aws-credential-types",
@@ -1871,11 +1917,12 @@ dependencies = [
  "gateway-admin",
  "gateway-core",
  "hex",
+ "percent-encoding",
  "redis",
  "secrecy",
  "serde",
  "serde_json",
- "sha2 0.11.0",
+ "sha2",
  "sqlx",
  "tempfile",
  "thiserror",
@@ -1968,9 +2015,9 @@ dependencies = [
 
 [[package]]
 name = "h2"
-version = "0.4.16"
+version = "0.4.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a9f37a958b41b3b19ee2707c06439c0e9e547e847223eb791ecb0cb821c65e27"
+checksum = "7d29020232d6aa3fb1daca64c1127cf662cf97f254ae16c18c05b8ab635fc118"
 dependencies = [
  "atomic-waker",
  "bytes",
@@ -2098,9 +2145,9 @@ dependencies = [
 
 [[package]]
 name = "http-body"
-version = "1.0.1"
+version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1efedce1fb8e6913f23e0c92de8e62cd5b772a67e7b3946df930a62566c93184"
+checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c"
 dependencies = [
  "bytes",
  "http",
@@ -2206,8 +2253,9 @@ dependencies = [
 
 [[package]]
 name = "hyper-util"
-version = "0.1.20"
-source = "git+https://github.com/hyperium/hyper-util?rev=191b1acf0a6b18e807e4abf5a6d4a7c47979ecd6#191b1acf0a6b18e807e4abf5a6d4a7c47979ecd6"
+version = "0.1.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddc03d96684f9226b8a787cdb71488417b53ab5ea8fdb1dac946cb9431cc8bff"
 dependencies = [
  "base64 0.23.1",
  "bytes",
@@ -2215,6 +2263,7 @@ dependencies = [
  "futures-util",
  "http",
  "http-body",
+ "httparse",
  "hyper",
  "ipnet",
  "libc",
@@ -2434,9 +2483,9 @@ dependencies = [
 
 [[package]]
 name = "jsonschema"
-version = "0.57.0"
+version = "0.58.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "71160ed5f6dbe36a2d6be79f4ca03ee09a99d2866f340faed49458913449aefa"
+checksum = "f622c574a29fb3034a0a90645afee194dfedc75fc124228801b6e77041075bd1"
 dependencies = [
  "ahash",
  "bytecount",
@@ -2462,18 +2511,18 @@ dependencies = [
 
 [[package]]
 name = "jsonschema-regex"
-version = "0.57.0"
+version = "0.58.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48d2120d8466ffcdc1b3be4b88ff0e9191bf5b6b09b1b1af1eef9aff8f465ea3"
+checksum = "a968fffd387b2ab005bf00c1851f5d26e90df05b6f7ad609ed0d620033cca5e7"
 dependencies = [
  "regex-syntax",
 ]
 
 [[package]]
 name = "jsonschema-value"
-version = "0.57.0"
+version = "0.58.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3fbfa40a42415369d940b3848f3ce08099f1f1ac04d73e8580f4d652617c4f44"
+checksum = "39b7670345e5ce87371339d13705dbb9276b7e3e934bbe1efa2c6734a1f65a96"
 dependencies = [
  "ahash",
  "bytecount",
@@ -2513,6 +2562,15 @@ version = "0.2.186"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
+[[package]]
+name = "libredox"
+version = "0.1.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61ff90caf6077a803a240f62fdbe88645a890bbca49ef8174c3cb0404362171d"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "libsqlite3-sys"
 version = "0.37.0"
@@ -2687,6 +2745,23 @@ dependencies = [
  "pxfm",
 ]
 
+[[package]]
+name = "multer"
+version = "3.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83e87776546dc87511aa5ee218730c92b666d7264ab6ed41f9d215af9cd5224b"
+dependencies = [
+ "bytes",
+ "encoding_rs",
+ "futures-util",
+ "http",
+ "httparse",
+ "memchr",
+ "mime",
+ "spin 0.9.9",
+ "version_check",
+]
+
 [[package]]
 name = "native-tls"
 version = "0.2.14"
@@ -2710,6 +2785,18 @@ version = "1.0.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086"
 
+[[package]]
+name = "nix"
+version = "0.31.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
+dependencies = [
+ "bitflags",
+ "cfg-if",
+ "cfg_aliases",
+ "libc",
+]
+
 [[package]]
 name = "nu-ansi-term"
 version = "0.50.3"
@@ -2813,6 +2900,24 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "objc2-core-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "objc2-system-configuration"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7216bd11cbda54ccabcab84d523dc93b858ec75ecfb3a7d89513fa22464da396"
+dependencies = [
+ "objc2-core-foundation",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -2901,7 +3006,7 @@ dependencies = [
  "elliptic-curve",
  "primefield",
  "primeorder",
- "sha2 0.11.0",
+ "sha2",
 ]
 
 [[package]]
@@ -3161,12 +3266,12 @@ checksum = "925383efa346730478fb4838dbe9137d2a47675ad789c546d150a6e1dd4ab31c"
 
 [[package]]
 name = "prettyplease"
-version = "0.2.37"
+version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
+checksum = "2bfe0f4c752e450fc2faf62654f1c134747922825d5b04ca717b8874f41a40c0"
 dependencies = [
  "proc-macro2",
- "syn 2.0.119",
+ "syn 3.0.9",
 ]
 
 [[package]]
@@ -3209,6 +3314,7 @@ dependencies = [
 name = "provider-openai"
 version = "0.0.0"
 dependencies = [
+ "allocation-counter",
  "async-stream",
  "async-trait",
  "aws-lc-rs",
@@ -3224,6 +3330,7 @@ dependencies = [
  "gateway-core",
  "gateway-protocol",
  "getrandom 0.4.3",
+ "h2",
  "hex",
  "hyper",
  "hyper-rustls",
@@ -3231,6 +3338,7 @@ dependencies = [
  "native-tls",
  "openssl",
  "openssl-sys",
+ "regex",
  "reqwest",
  "roxmltree",
  "rustls",
@@ -3240,7 +3348,7 @@ dependencies = [
  "semver",
  "serde",
  "serde_json",
- "sha2 0.11.0",
+ "sha2",
  "subtle",
  "tar",
  "tempfile",
@@ -3282,7 +3390,7 @@ dependencies = [
  "semver",
  "serde",
  "serde_json",
- "sha2 0.11.0",
+ "sha2",
  "thiserror",
  "tokio",
  "tracing",
@@ -3342,9 +3450,9 @@ dependencies = [
 
 [[package]]
 name = "quinn-proto"
-version = "0.11.16"
+version = "0.11.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2f4bfc015262b9df63c8845072ce59068853ff5872180c2ce2f13038b970e560"
+checksum = "a9746dbde176634f4f2f1faf2404e30a31b2bc1e9cafb5329c95d8177a18c9fc"
 dependencies = [
  "bytes",
  "getrandom 0.4.3",
@@ -3378,9 +3486,9 @@ dependencies = [
 
 [[package]]
 name = "quote"
-version = "1.0.46"
+version = "1.0.47"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
 dependencies = [
  "proc-macro2",
 ]
@@ -3523,14 +3631,14 @@ checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.9",
 ]
 
 [[package]]
 name = "referencing"
-version = "0.57.0"
+version = "0.58.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b06f6798be4fed305e74df8b1fb90cf59c6b8cc17aa3febeb1830c0c6b627b3e"
+checksum = "558f3855529c0a7e78a48e409fa653456e55f1b167eab4109c16a255b7727e3f"
 dependencies = [
  "ahash",
  "fluent-uri",
@@ -3545,9 +3653,9 @@ dependencies = [
 
 [[package]]
 name = "regex"
-version = "1.13.0"
+version = "1.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2a0e75113e14dc5acb068cd0786884f214f1312650a3d36d269f5c4f3cdee8a2"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -3690,9 +3798,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.45"
+version = "0.23.46"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
+checksum = "48e13bd8c0e9365c43cfa5c9e8f9ad49d3c8444926c9aac819e0e4dc503c8fdf"
 dependencies = [
  "aws-lc-rs",
  "log",
@@ -3728,9 +3836,9 @@ dependencies = [
 
 [[package]]
 name = "rustls-webpki"
-version = "0.103.15"
+version = "0.103.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f3c3cf1d8b1e7d4927e2d154c3fcb02979afb9939629c62cd9048d4f07b60ac2"
+checksum = "4443b1b6d39d7c663139942cc4558262562d2c84123bb6282ef177009ca8b281"
 dependencies = [
  "aws-lc-rs",
  "ring",
@@ -3896,7 +4004,7 @@ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.9",
 ]
 
 [[package]]
@@ -3911,10 +4019,11 @@ dependencies = [
 
 [[package]]
 name = "serde_json"
-version = "1.0.151"
+version = "1.0.154"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
 dependencies = [
+ "foldhash",
  "indexmap",
  "itoa",
  "memchr",
@@ -3995,20 +4104,9 @@ checksum = "bbfa15b3dddfee50a0fff136974b3e1bde555604ba463834a7eb7deb6417705d"
 
 [[package]]
 name = "sha2"
-version = "0.10.9"
+version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
-dependencies = [
- "cfg-if",
- "cpufeatures 0.2.17",
- "digest 0.10.7",
-]
-
-[[package]]
-name = "sha2"
-version = "0.11.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "446ba717509524cb3f22f17ecc096f10f4822d76ab5c0b9822c5f9c284e825f4"
+checksum = "47d7069beb7d6ac7b9acd1039986e73443f24234f41074da099d6f994ac9ad19"
 dependencies = [
  "cfg-if",
  "cpufeatures 0.3.0",
@@ -4124,8 +4222,7 @@ dependencies = [
 [[package]]
 name = "sqlx"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "378620ccc25c62c89d8be1c819e76a88d59bdcc3304733330788948e619bfd71"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
  "sqlx-core",
  "sqlx-macros",
@@ -4137,8 +4234,7 @@ dependencies = [
 [[package]]
 name = "sqlx-core"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "05b44e85bf579a8eeb4ceaa77a3a523baf2bf0e9bac7e40f405d537b5d2d5ccb"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
  "base64 0.22.1",
  "bytes",
@@ -4161,7 +4257,7 @@ dependencies = [
  "rustls",
  "serde",
  "serde_json",
- "sha2 0.10.9",
+ "sha2",
  "smallvec",
  "thiserror",
  "tokio",
@@ -4175,8 +4271,7 @@ dependencies = [
 [[package]]
 name = "sqlx-macros"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bd2b84f2bc39a5705ef27ec785a11c934a41bbd4a24941e257927cddc26b60bf"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -4188,8 +4283,7 @@ dependencies = [
 [[package]]
 name = "sqlx-macros-core"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fb8d96de5fdc85a5c4ec813432b523ec637e80ba98f046555f75f7908ddac7c3"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
  "cfg-if",
  "dotenvy",
@@ -4200,7 +4294,7 @@ dependencies = [
  "quote",
  "serde",
  "serde_json",
- "sha2 0.10.9",
+ "sha2",
  "sqlx-core",
  "sqlx-mysql",
  "sqlx-postgres",
@@ -4214,8 +4308,7 @@ dependencies = [
 [[package]]
 name = "sqlx-mysql"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "90b8020fe17c5f2c245bfa2505d7ef59c5604839527c740266ad2214acebea27"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
  "bitflags",
  "byteorder",
@@ -4232,7 +4325,7 @@ dependencies = [
  "percent-encoding",
  "serde",
  "sha1 0.11.0",
- "sha2 0.11.0",
+ "sha2",
  "sqlx-core",
  "thiserror",
  "tracing",
@@ -4242,8 +4335,7 @@ dependencies = [
 [[package]]
 name = "sqlx-postgres"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "87a2bdd6e83f6b3ea525ca9fee568030508b58355a43d0b2c1674d5f79dcd65e"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
  "atoi",
  "base64 0.22.1",
@@ -4266,7 +4358,7 @@ dependencies = [
  "rand 0.10.2",
  "serde",
  "serde_json",
- "sha2 0.11.0",
+ "sha2",
  "smallvec",
  "sqlx-core",
  "stringprep",
@@ -4279,8 +4371,7 @@ dependencies = [
 [[package]]
 name = "sqlx-sqlite"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "488e99c397a62007e4229aec669a179816339afc6d2620ca6fa420dbee2e982c"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
  "atoi",
  "chrono",
@@ -4395,9 +4486,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "3.0.6"
+version = "3.0.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -4495,7 +4586,7 @@ checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.9",
 ]
 
 [[package]]
@@ -4564,9 +4655,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.52.3"
+version = "1.53.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
+checksum = "ce3335fa71841cda333a58d7615b03901380ecf09d59b3296d21f8bbac0dde4e"
 dependencies = [
  "bytes",
  "libc",
@@ -4649,9 +4740,9 @@ dependencies = [
 
 [[package]]
 name = "tokio-util"
-version = "0.7.19"
+version = "0.7.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
+checksum = "e464cf451ba96ebfc6f9b6542f17ee8b8956e33f1e40d9690624e59d7a7f8a4b"
 dependencies = [
  "bytes",
  "futures-core",
@@ -4701,6 +4792,7 @@ version = "0.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "08a05a66a4fdd61cbbe0a1d755ffe0ca6aba159dd4820936a0ff8a8278245b9c"
 dependencies = [
+ "async-compression",
  "bitflags",
  "bytes",
  "futures-core",
@@ -4965,9 +5057,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
 [[package]]
 name = "uuid"
-version = "1.26.1"
+version = "1.28.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2ef6dac1e96601b4fb3acccccff2139741fcb757cb9a36089bf5be91cfb285ce"
+checksum = "7cc1186384beb7dd8eedea376413fd654937285ea6c9cfbb928dc3043ea4b606"
 dependencies = [
  "getrandom 0.4.3",
  "js-sys",
@@ -5134,9 +5226,9 @@ dependencies = [
 
 [[package]]
 name = "webpki-roots"
-version = "1.0.5"
+version = "1.0.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "12bed680863276c63889429bfd6cab3b99943659923822de1c8a39c49e4d722c"
+checksum = "1c1c8e20c8a38fc7d65abfe74eb7280e4aa667e8eec8bc84996d2874810748d9"
 dependencies = [
  "rustls-pki-types",
 ]
@@ -5152,6 +5244,12 @@ name = "whoami"
 version = "2.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "998767ef88740d1f5b0682a9c53c24431453923962269c2db68ee43788c5a40d"
+dependencies = [
+ "libc",
+ "libredox",
+ "objc2-system-configuration",
+ "web-sys",
+]
 
 [[package]]
 name = "winapi"
@@ -5376,13 +5474,14 @@ checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
 
 [[package]]
 name = "wnaf"
-version = "0.14.0"
+version = "0.14.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ab12e7090f27e2ffd9322651492942d50c2926094af30601e1964337db39daf1"
+checksum = "795ca18b3fdb5e62bf982199278341ddcf7ebf7d32e25e212ad05d496e95f6fa"
 dependencies = [
  "ff",
  "group",
  "hybrid-array",
+ "primefield",
 ]
 
 [[package]]
@@ -5499,9 +5598,9 @@ dependencies = [
 
 [[package]]
 name = "zeroize"
-version = "1.9.0"
+version = "1.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+checksum = "e13084392c5e4bc371903e2935a5eaeed24905a7511356b883835e18a78f6879"
 dependencies = [
  "zeroize_derive",
 ]
@@ -5552,14 +5651,15 @@ dependencies = [
 
 [[package]]
 name = "zip"
-version = "8.6.0"
+version = "9.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2d04a6b5381502aa6087c94c669499eb1602eb9c5e8198e534de571f7154809b"
+checksum = "a954114b47a54df49f83d2722814e86b23d4bb1b54a1b90fb7d92b41619ddc22"
 dependencies = [
  "crc32fast",
  "flate2",
  "indexmap",
  "memchr",
+ "nix",
  "typed-path",
 ]
 

backend/Cargo.toml

@@ -20,7 +20,7 @@ version = "0.0.0"
 edition = "2024"
 license = "Apache-2.0"
 publish = false
-rust-version = "1.97"
+rust-version = "1.99.1"
 
 [workspace.lints.rust]
 warnings = "deny"
@@ -43,7 +43,7 @@ opt-level = 2
 [profile.dev.package.blake2]
 opt-level = 2
 
-[profile.dev.package."sha2@0.11.0"]
+[profile.dev.package."sha2@0.11.1"]
 opt-level = 2
 
 [profile.dev.package."miniz_oxide@0.9.1"]
@@ -57,5 +57,5 @@ codegen-units = 1
 panic = "abort"
 
 [patch.crates-io]
-# Upstream SOCKS IPv6 fix; remove once a release includes hyperium/hyper-util#302.
-hyper-util = { git = "https://github.com/hyperium/hyper-util", rev = "191b1acf0a6b18e807e4abf5a6d4a7c47979ecd6" }
+# 固定上游 BEGIN 取消回滚修复，避免未结束事务复用；见 transact-rs/sqlx#4394
+sqlx = { git = "https://github.com/transact-rs/sqlx", rev = "f1e94ec34dd5f11ad6488a3a8ac7988439a3f757" }

backend/apps/gateway/src/bootstrap.rs

@@ -1,459 +0,0 @@
-//! 网关唯一组合根：加载包级配置并连接各 Bundle。
-
-use gateway_core::engine::provider::{ProviderRegistry, RegistryError};
-use gateway_host::{ConfigError, HostConfig, LoadableConfig};
-use serde::Deserialize;
-
-const CONFIG_SCHEMA_VERSION: u32 = 1;
-
-/// 顶层配置只组合各包拥有的配置段，不解释任何业务字段。
-/// 各启动配置忽略未知字段，允许升级时保留旧配置；已知字段仍按类型和业务约束校验。
-#[derive(Debug, Deserialize)]
-pub struct GatewayConfig {
-    schema_version: u32,
-    host: HostConfig,
-    store: gateway_store::StoreConfig,
-    admin: gateway_admin::AdminConfig,
-    #[serde(default)]
-    client: gateway_admin::ClientConfig,
-    api: gateway_api::ApiConfig,
-    #[serde(default)]
-    openai: provider_openai::OpenAiConfig,
-}
-
-impl LoadableConfig for GatewayConfig {
-    const EXTERNAL_SECTIONS: &'static [&'static str] = &["services"];
-
-    fn resolve_and_validate(&mut self, source_dir: &std::path::Path) -> Result<(), ConfigError> {
-        if self.schema_version != CONFIG_SCHEMA_VERSION {
-            return Err(ConfigError::InvalidField("schema_version"));
-        }
-        self.api
-            .resolve_and_validate(source_dir)
-            .map_err(|_| ConfigError::InvalidField("api"))?;
-        self.host
-            .resolve_and_validate(source_dir, &self.api.asset_directory)?;
-        let runtime_data_dir = self.host.runtime_data_dir().to_path_buf();
-        self.store
-            .resolve_and_validate(&runtime_data_dir)
-            .map_err(|_| ConfigError::InvalidField("store"))?;
-        self.admin
-            .resolve_and_validate(source_dir)
-            .map_err(|_| ConfigError::InvalidField("admin"))?;
-        self.client
-            .resolve_and_validate(source_dir)
-            .map_err(|_| ConfigError::InvalidField("client"))?;
-        self.openai
-            .resolve_and_validate(&runtime_data_dir)
-            .map_err(|_| ConfigError::InvalidField("openai"))?;
-        Ok(())
-    }
-}
-
-/// 按冻结顺序初始化全部 Bundle，并把进程阻塞权交给 Host。
-pub async fn run() -> Result<(), BootstrapError> {
-    launch(None).await.map(|_| ())
-}
-
-/// 这里只接收插件命名空间内的参数，不转交宿主配置或其他启动 secret。
-pub struct PluginCommand {
-    pub instance_id: Option<String>,
-    pub name: Option<String>,
-    pub arguments: Vec<String>,
-}
-
-impl PluginCommand {
-    fn is_help(&self) -> bool {
-        self.name.is_none()
-            || self
-                .arguments
-                .iter()
-                .any(|value| matches!(value.as_str(), "--help" | "-h"))
-    }
-}
-
-pub async fn plugin_command(
-    command: PluginCommand,
-) -> Result<gateway_plugin_runtime::PluginCommandOutput, BootstrapError> {
-    launch(Some(command)).await
-}
-
-async fn launch(
-    command: Option<PluginCommand>,
-) -> Result<gateway_plugin_runtime::PluginCommandOutput, BootstrapError> {
-    macro_rules! or_shutdown {
-        ($runtime:expr, $result:expr) => {
-            match $result {
-                Ok(value) => value,
-                Err(error) => {
-                    $runtime.shutdown().await;
-                    return Err(error.into());
-                }
-            }
-        };
-    }
-
-    let config = gateway_host::load_config::<GatewayConfig>()?;
-    let GatewayConfig {
-        schema_version: _,
-        host,
-        store,
-        admin,
-        client,
-        api,
-        openai,
-    } = config;
-
-    let plugin_cache = host.runtime_data_dir().join("plugins");
-    let host = if command.is_some() {
-        gateway_host::initialize_command_line(host).await?
-    } else {
-        gateway_host::initialize(host).await?
-    };
-    host.report_startup_ready("Host");
-    let help = command.as_ref().is_some_and(PluginCommand::is_help);
-    let mut store = if help {
-        gateway_store::initialize_read_only(store).await?
-    } else if command.is_some() {
-        gateway_store::initialize_command_line(store).await?
-    } else {
-        gateway_store::initialize(store).await?
-    };
-    host.report_startup_ready("Store");
-    let version = host
-        .system_operations()
-        .version()
-        .await
-        .map_err(|_| ConfigError::InvalidField("host.version"))?
-        .version;
-    let plugin_http = std::sync::Arc::new(gateway_host::outbound::HttpClient::new()?);
-    if let Some(command) = command.as_ref().filter(|_| help) {
-        let runtime = prepare_plugins(&store, plugin_cache, &version, plugin_http.clone())?;
-        let commands = or_shutdown!(runtime, runtime.prepare_command_line().await);
-        let stdout = commands.help(command.instance_id.as_deref(), command.name.as_deref());
-        commands.shutdown().await;
-        runtime.shutdown().await;
-        return Ok(gateway_plugin_runtime::PluginCommandOutput {
-            stdout: stdout?,
-            stderr: String::new(),
-            exit_code: 0,
-            saved_accounts: 0,
-        });
-    }
-    let provider_ports = store.provider_ports();
-    let mut openai = provider_openai::initialize(openai, provider_ports.clone()).await?;
-    host.report_startup_ready("OpenAI Provider");
-    let mut xai = provider_xai::initialize(provider_ports).await?;
-    host.report_startup_ready("xAI Provider");
-    let providers = ProviderRegistry::new([openai.core_provider(), xai.core_provider()])?;
-    let plugin_runtime = prepare_plugins(&store, plugin_cache, &version, plugin_http.clone())?;
-    let admin_providers = gateway_admin::ports::provider::ProviderAdminRegistry::new([
-        openai.admin_provider(),
-        xai.admin_provider(),
-    ])
-    .map_err(|_| gateway_admin::model::AdminError::invalid("Provider 管理身份冲突"))?;
-    if let Some(command) = command {
-        let instance_id = or_shutdown!(
-            plugin_runtime,
-            command
-                .instance_id
-                .as_deref()
-                .ok_or_else(|| gateway_admin::model::AdminError::invalid("插件实例 ID 缺失"))
-        );
-        let name = or_shutdown!(
-            plugin_runtime,
-            command
-                .name
-                .as_deref()
-                .ok_or_else(|| gateway_admin::model::AdminError::invalid("插件命令名缺失"))
-        );
-        let core = gateway_core::prepare_command_plane(
-            store.core_ports(),
-            providers.clone(),
-            Some(plugin_runtime.clone()),
-            Some(plugin_runtime.observer_registry()),
-            Some(plugin_runtime.policy_registry()),
-            Some(plugin_runtime.middleware_registry()),
-        );
-        let accounts = gateway_admin::initialize_plugin_accounts(
-            admin_providers.clone(),
-            store.admin_ports().accounts(),
-            core.snapshot_control(),
-        );
-        or_shutdown!(plugin_runtime, plugin_runtime.bind_account_ports(&accounts));
-        let keys = gateway_admin::initialize_plugin_client_keys(
-            admin_providers.clone(),
-            store.admin_ports().client_keys(),
-            core.snapshot_control(),
-        );
-        or_shutdown!(plugin_runtime, plugin_runtime.bind_client_key_ports(&keys));
-        let plugin_resources = gateway_admin::initialize_plugin_resources(
-            store.admin_ports().plugin_resources(),
-            core.snapshot_control(),
-        );
-        or_shutdown!(
-            plugin_runtime,
-            plugin_runtime.bind_resource_ports(&plugin_resources)
-        );
-        let core = or_shutdown!(plugin_runtime, core.activate().await);
-        let nested_models = core.nested_model_execution_port();
-        let affinity_lookup = core.affinity_lookup_port();
-        or_shutdown!(
-            plugin_runtime,
-            plugin_runtime.bind_model_ports(&nested_models, &affinity_lookup)
-        );
-        let settings = gateway_admin::initialize_settings(
-            store.admin_ports().settings(),
-            core.snapshot_control(),
-            admin_providers,
-            std::sync::Arc::new(gateway_host::pricing::ModelsDevPricing),
-        );
-        let mut services = gateway_admin::service::Registry::new({
-            let snapshots = core.snapshots();
-            let middleware = plugin_runtime.middleware_registry();
-            std::sync::Arc::new(move || {
-                let snapshot = snapshots.snapshot_for_diagnostics()?;
-                middleware.resolve(snapshot.extensions()?)
-            })
-        });
-        or_shutdown!(plugin_runtime, services.register_settings(&settings));
-        let services = std::sync::Arc::new(services);
-        or_shutdown!(plugin_runtime, plugin_runtime.bind_services(&services));
-        let commands = or_shutdown!(plugin_runtime, plugin_runtime.prepare_command_line().await);
-        or_shutdown!(plugin_runtime, store.start_command_line_writes());
-        let result = commands
-            .execute_cancellable(instance_id, name, &command.arguments, &host.cancellation())
-            .await;
-        commands.shutdown().await;
-        plugin_runtime.shutdown().await;
-        store.shutdown_command_line_writes().await?;
-        return Ok(result?);
-    }
-    let core = gateway_core::prepare(
-        store.core_ports(),
-        providers,
-        Some(plugin_runtime.clone()),
-        Some(plugin_runtime.observer_registry()),
-        Some(plugin_runtime.policy_registry()),
-        Some(plugin_runtime.middleware_registry()),
-        Some(plugin_runtime.frontend_authentication_registry()),
-    );
-    let plugin_accounts = gateway_admin::initialize_plugin_accounts(
-        admin_providers.clone(),
-        store.admin_ports().accounts(),
-        core.snapshot_control(),
-    );
-    or_shutdown!(
-        plugin_runtime,
-        plugin_runtime.bind_account_ports(&plugin_accounts)
-    );
-    let plugin_keys = gateway_admin::initialize_plugin_client_keys(
-        admin_providers.clone(),
-        store.admin_ports().client_keys(),
-        core.snapshot_control(),
-    );
-    or_shutdown!(
-        plugin_runtime,
-        plugin_runtime.bind_client_key_ports(&plugin_keys)
-    );
-    let plugin_resources = gateway_admin::initialize_plugin_resources(
-        store.admin_ports().plugin_resources(),
-        core.snapshot_control(),
-    );
-    or_shutdown!(
-        plugin_runtime,
-        plugin_runtime.bind_resource_ports(&plugin_resources)
-    );
-    let mut core = or_shutdown!(plugin_runtime, core.activate().await);
-    let nested_models = core.nested_model_execution_port();
-    let affinity_lookup = core.affinity_lookup_port();
-    or_shutdown!(
-        plugin_runtime,
-        plugin_runtime.bind_model_ports(&nested_models, &affinity_lookup)
-    );
-    host.report_startup_ready("Core");
-    let host_version = or_shutdown!(
-        plugin_runtime,
-        version
-            .trim_start_matches('v')
-            .parse()
-            .map_err(|_| ConfigError::InvalidField("host.version"))
-    );
-    let plugin_inspector = std::sync::Arc::new(gateway_plugin_runtime::PackageInspector::new(
-        gateway_plugin_runtime::PackageLimits::default(),
-        host_version,
-    ));
-    let plugin_distribution = std::sync::Arc::new(or_shutdown!(
-        plugin_runtime,
-        gateway_host::plugin_distribution::HttpPluginDistribution::new(plugin_http)
-    ));
-    let mut admin = or_shutdown!(
-        plugin_runtime,
-        gateway_admin::initialize_with_plugin_accounts(
-            admin,
-            client,
-            store.admin_ports(),
-            gateway_admin::AdminRuntimePorts {
-                service_middleware: {
-                    let snapshots = core.snapshots();
-                    let middleware = plugin_runtime.middleware_registry();
-                    std::sync::Arc::new(move || {
-                        let snapshot = snapshots.snapshot_for_diagnostics()?;
-                        middleware.resolve(snapshot.extensions()?)
-                    })
-                },
-                providers: admin_providers,
-                plugin_preparation: plugin_runtime.clone(),
-                plugin_management: plugin_runtime.clone(),
-                published_snapshot: core.snapshots(),
-                plugin_inspector,
-                plugin_distribution,
-                pricing_source: std::sync::Arc::new(gateway_host::pricing::ModelsDevPricing),
-                snapshot: core.snapshot_control(),
-                account_probe: core.account_probe(),
-                proxy_probe: host.proxy_probe(provider_openai::build_reqwest_client_with_custom_ca),
-                client_distribution: host.client_distribution_resolver(),
-                system: host.system_operations(),
-                client_key_verifier: core.client_key_verifier(),
-            },
-            plugin_accounts,
-        )
-        .await
-    );
-    let official_files = host.official_plugin_release_files();
-    let official_identity = host.official_plugin_release_identity();
-    let official_import = or_shutdown!(
-        plugin_runtime,
-        admin
-            .services()
-            .plugins()
-            .import_official_release(
-                official_files.as_ref(),
-                &official_identity,
-                &gateway_admin::model::MutationContext {
-                    actor: gateway_admin::model::MutationActor::System,
-                    request_id: "startup-official-plugin-import".to_owned(),
-                },
-            )
-            .await
-    );
-    if official_import.artifacts > 0 {
-        host.report_startup_ready("Official plugins");
-    }
-    host.report_startup_ready("Admin");
-
-    let mut probes = store.health_probes();
-    probes.extend(core.health_probes());
-    probes.push(host.logging_health_probe());
-    let api = or_shutdown!(
-        plugin_runtime,
-        gateway_api::initialize(
-            api,
-            core.execution_service(),
-            admin.services(),
-            probes,
-            host.worker_health(),
-            host.connection_lifecycle(),
-        )
-    )
-    .with_middleware({
-        let snapshots = core.snapshots();
-        let middleware = plugin_runtime.middleware_registry();
-        move |snapshot| {
-            if let Some(snapshot) = snapshot {
-                return middleware.resolve(snapshot.extensions()?);
-            }
-            // 数据面未就绪时，管理与诊断路由仍可使用发布候选中的插件。
-            let diagnostic = snapshots.snapshot_for_diagnostics()?;
-            middleware.resolve(diagnostic.extensions()?)
-        }
-    });
-    let http_dispatcher = api.dispatcher();
-    or_shutdown!(plugin_runtime, plugin_runtime.bind_http(&http_dispatcher));
-    host.report_startup_ready("API");
-
-    or_shutdown!(
-        plugin_runtime,
-        plugin_runtime.bind_services(&admin.services().public_services())
-    );
-
-    let mut plan = store.take_worker_contributions();
-    plan.push(gateway_host::retention::worker(store.retention())?);
-    plan.extend(core.take_worker_contributions());
-    plan.extend(openai.take_worker_contributions());
-    plan.extend(xai.take_worker_contributions());
-    plan.extend(admin.take_worker_contributions());
-    plan.push(plugin_runtime.maintenance_worker(core.snapshots())?);
-    or_shutdown!(
-        plugin_runtime,
-        host.start_workers(plan, store.worker_leader_lease())
-    );
-    host.report_startup_ready("Workers");
-    let served = host.serve(api.router()).await;
-    plugin_runtime.shutdown().await;
-    served?;
-    Ok(gateway_plugin_runtime::PluginCommandOutput {
-        stdout: String::new(),
-        stderr: String::new(),
-        exit_code: 0,
-        saved_accounts: 0,
-    })
-}
-
-fn prepare_plugins(
-    store: &gateway_store::StoreBundle,
-    plugin_cache: std::path::PathBuf,
-    version: &str,
-    http: std::sync::Arc<gateway_host::outbound::HttpClient>,
-) -> Result<std::sync::Arc<gateway_plugin_runtime::PluginRuntime>, BootstrapError> {
-    Ok(std::sync::Arc::new(
-        gateway_plugin_runtime::PluginRuntime::new(
-            store.admin_ports().plugins(),
-            store.admin_ports().plugin_state(),
-            gateway_plugin_runtime::PluginRuntimeConfig {
-                cache_directory: plugin_cache,
-                host_version: version
-                    .trim_start_matches('v')
-                    .parse()
-                    .map_err(|_| ConfigError::InvalidField("host.version"))?,
-                package_limits: gateway_plugin_runtime::PackageLimits::default(),
-                rpc_limits: gateway_plugin_runtime::RpcLimits::default(),
-                restart_circuit: Default::default(),
-            },
-            http,
-            std::sync::Arc::new(gateway_host::process::ProcessSupervisor::default()),
-        )
-        .with_oauth_pending(store.provider_ports().oauth_pending()),
-    ))
-}
-
-/// 组合根只保留包级错误分类，不展开内部实现或敏感配置。
-#[derive(Debug, thiserror::Error)]
-pub enum BootstrapError {
-    #[error(transparent)]
-    Worker(#[from] gateway_core::task::WorkerDefinitionError),
-    #[error(transparent)]
-    PluginCommand(#[from] gateway_plugin_runtime::PluginCommandError),
-    #[error(transparent)]
-    Config(#[from] gateway_host::ConfigError),
-    #[error(transparent)]
-    Host(#[from] gateway_host::HostError),
-    #[error(transparent)]
-    Outbound(#[from] gateway_host::outbound::HttpError),
-    #[error(transparent)]
-    Store(#[from] gateway_store::StoreError),
-    #[error(transparent)]
-    CommandStoreDrain(#[from] gateway_store::CommandStoreDrainError),
-    #[error(transparent)]
-    OpenAi(#[from] provider_openai::OpenAiInitializeError),
-    #[error(transparent)]
-    Xai(#[from] provider_xai::XaiInitializeError),
-    #[error(transparent)]
-    Registry(#[from] RegistryError),
-    #[error(transparent)]
-    Core(#[from] gateway_core::CoreError),
-    #[error(transparent)]
-    Admin(#[from] gateway_admin::model::AdminError),
-    #[error(transparent)]
-    Api(#[from] gateway_api::ApiError),
-}

backend/apps/gateway/src/bootstrap/command.rs

@@ -0,0 +1,155 @@
+//! 插件帮助只读启动；命令仅组装命令平面和必要写泵
+
+use super::{
+    BootstrapError, GatewayConfig,
+    plugins::{ManagementPorts, or_shutdown, prepare_plugins, service_middleware},
+    startup::{Environment, Mode, Providers},
+};
+
+/// 这里只接收插件命名空间内的参数，不转交宿主配置或其他启动 secret
+pub struct PluginCommand {
+    pub instance_id: Option<String>,
+    pub name: Option<String>,
+    pub arguments: Vec<String>,
+}
+
+impl PluginCommand {
+    fn is_help(&self) -> bool {
+        self.name.is_none()
+            || self
+                .arguments
+                .iter()
+                .any(|value| matches!(value.as_str(), "--help" | "-h"))
+    }
+}
+
+pub async fn plugin_command(
+    command: PluginCommand,
+) -> Result<gateway_plugin_runtime::PluginCommandOutput, BootstrapError> {
+    let config = gateway_host::load_config::<GatewayConfig>()?;
+    if command.is_help() {
+        let environment = Environment::initialize(config.host, config.store, Mode::Help).await?;
+        help(command, environment).await
+    } else {
+        let environment = Environment::initialize(config.host, config.store, Mode::Command).await?;
+        let providers = Providers::initialize(config.openai, &environment).await?;
+        execute(command, environment, providers).await
+    }
+}
+
+async fn help(
+    command: PluginCommand,
+    environment: Environment,
+) -> Result<gateway_plugin_runtime::PluginCommandOutput, BootstrapError> {
+    let runtime = prepare_plugins(
+        &environment.store,
+        environment.plugin_cache,
+        &environment.version,
+        environment.plugin_http,
+    )?;
+    let commands = or_shutdown!(runtime, runtime.prepare_command_line().await);
+    let stdout = commands.help(command.instance_id.as_deref(), command.name.as_deref());
+    commands.shutdown().await;
+    runtime.shutdown().await;
+    Ok(gateway_plugin_runtime::PluginCommandOutput {
+        stdout: stdout?,
+        stderr: String::new(),
+        exit_code: 0,
+        saved_accounts: 0,
+    })
+}
+
+async fn execute(
+    command: PluginCommand,
+    environment: Environment,
+    providers: Providers,
+) -> Result<gateway_plugin_runtime::PluginCommandOutput, BootstrapError> {
+    let Environment {
+        host,
+        mut store,
+        timezone,
+        plugin_cache,
+        version,
+        plugin_http,
+        ..
+    } = environment;
+    let plugin_runtime = prepare_plugins(&store, plugin_cache, &version, plugin_http)?;
+    let instance_id = or_shutdown!(
+        plugin_runtime,
+        command
+            .instance_id
+            .as_deref()
+            .ok_or_else(|| gateway_admin::model::AdminError::invalid("插件实例 ID 缺失"))
+    );
+    let name = or_shutdown!(
+        plugin_runtime,
+        command
+            .name
+            .as_deref()
+            .ok_or_else(|| gateway_admin::model::AdminError::invalid("插件命令名缺失"))
+    );
+    let core = gateway_core::prepare_command_plane(
+        store.core_ports(),
+        providers.core,
+        Some(plugin_runtime.clone()),
+        Some(plugin_runtime.observer_registry()),
+        Some(plugin_runtime.policy_registry()),
+        Some(plugin_runtime.execution_registry()),
+    );
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_snapshots(&core.snapshots())
+    );
+    let management = ManagementPorts::new(&store, providers.admin.clone(), core.snapshot_control());
+    or_shutdown!(plugin_runtime, management.bind(&plugin_runtime));
+    let core = or_shutdown!(plugin_runtime, core.activate().await);
+    let nested_models = core.nested_model_execution_port();
+    let affinity_lookup = core.affinity_lookup_port();
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_model_ports(&nested_models, &affinity_lookup)
+    );
+    let settings = gateway_admin::initialize_settings(
+        store.admin_ports().settings(),
+        core.snapshot_control(),
+        providers.admin.clone(),
+        std::sync::Arc::new(gateway_host::pricing::ModelsDevPricing),
+    );
+    let mut services = gateway_admin::public_service::Registry::new(service_middleware(
+        core.snapshots(),
+        &plugin_runtime,
+    ));
+    or_shutdown!(plugin_runtime, services.register_settings(&settings));
+    let accounts = gateway_admin::initialize_accounts(
+        store.admin_ports().accounts(),
+        store.admin_ports().account_runtime(),
+        store.admin_ports().settings(),
+        timezone,
+        providers.admin.clone(),
+        core.snapshot_control(),
+        core.account_probe(),
+    );
+    or_shutdown!(plugin_runtime, services.register_accounts(&accounts));
+    let usage_data = gateway_admin::initialize_usage_data(
+        store.admin_ports().usage_data(),
+        store.admin_ports().settings(),
+        providers.admin,
+    );
+    or_shutdown!(plugin_runtime, services.register_usage_data(&usage_data));
+    let services = std::sync::Arc::new(services);
+    or_shutdown!(plugin_runtime, plugin_runtime.bind_services(&services));
+    let commands = or_shutdown!(plugin_runtime, plugin_runtime.prepare_command_line().await);
+    let result = async {
+        store.start_command_line_writes()?;
+        Ok::<_, BootstrapError>(
+            commands
+                .execute_cancellable(instance_id, name, &command.arguments, &host.cancellation())
+                .await?,
+        )
+    }
+    .await;
+    commands.shutdown().await;
+    plugin_runtime.shutdown().await;
+    store.shutdown_command_line_writes().await?;
+    result
+}

backend/apps/gateway/src/bootstrap/config.rs

@@ -0,0 +1,50 @@
+//! 网关顶层配置的加载、路径解析与跨模块参数校验
+
+use gateway_host::{ConfigError, HostConfig, LoadableConfig};
+use serde::Deserialize;
+
+const CONFIG_SCHEMA_VERSION: u32 = 1;
+
+/// 顶层配置只组合各包拥有的配置段，不解释任何业务字段
+/// 各启动配置忽略未知字段，允许升级时保留旧配置；已知字段仍按类型和业务约束校验
+#[derive(Debug, Deserialize)]
+pub struct GatewayConfig {
+    schema_version: u32,
+    pub(super) host: HostConfig,
+    pub(super) store: gateway_store::StoreConfig,
+    pub(super) admin: gateway_admin::AdminConfig,
+    #[serde(default)]
+    pub(super) client: gateway_admin::ClientConfig,
+    pub(super) api: gateway_api::ApiConfig,
+    #[serde(default)]
+    pub(super) openai: provider_openai::OpenAiConfig,
+}
+
+impl LoadableConfig for GatewayConfig {
+    const EXTERNAL_SECTIONS: &'static [&'static str] = &["services"];
+
+    fn resolve_and_validate(&mut self, source_dir: &std::path::Path) -> Result<(), ConfigError> {
+        if self.schema_version != CONFIG_SCHEMA_VERSION {
+            return Err(ConfigError::InvalidField("schema_version"));
+        }
+        self.api
+            .resolve_and_validate(source_dir)
+            .map_err(|_| ConfigError::InvalidField("api"))?;
+        self.host
+            .resolve_and_validate(source_dir, &self.api.asset_directory)?;
+        let runtime_data_dir = self.host.runtime_data_dir().to_path_buf();
+        self.store
+            .resolve_and_validate(&runtime_data_dir)
+            .map_err(|_| ConfigError::InvalidField("store"))?;
+        self.admin
+            .resolve_and_validate(source_dir)
+            .map_err(|_| ConfigError::InvalidField("admin"))?;
+        self.client
+            .resolve_and_validate(source_dir)
+            .map_err(|_| ConfigError::InvalidField("client"))?;
+        self.openai
+            .resolve_and_validate(&runtime_data_dir)
+            .map_err(|_| ConfigError::InvalidField("openai"))?;
+        Ok(())
+    }
+}

backend/apps/gateway/src/bootstrap/mod.rs

@@ -0,0 +1,42 @@
+//! 网关唯一组合根：按启动模式连接各 Bundle
+
+mod command;
+mod config;
+mod plugins;
+mod server;
+mod startup;
+
+pub use command::{PluginCommand, plugin_command};
+pub use config::GatewayConfig;
+pub use server::run;
+
+/// 组合根只保留包级错误分类，不展开内部实现或敏感配置
+#[derive(Debug, thiserror::Error)]
+pub enum BootstrapError {
+    #[error(transparent)]
+    Worker(#[from] gateway_core::task::WorkerDefinitionError),
+    #[error(transparent)]
+    PluginCommand(#[from] gateway_plugin_runtime::PluginCommandError),
+    #[error(transparent)]
+    Config(#[from] gateway_host::ConfigError),
+    #[error(transparent)]
+    Host(#[from] gateway_host::HostError),
+    #[error(transparent)]
+    Outbound(#[from] gateway_host::outbound::HttpError),
+    #[error(transparent)]
+    Store(#[from] gateway_store::StoreError),
+    #[error(transparent)]
+    CommandStoreDrain(#[from] gateway_store::CommandStoreDrainError),
+    #[error(transparent)]
+    OpenAi(#[from] provider_openai::OpenAiInitializeError),
+    #[error(transparent)]
+    Xai(#[from] provider_xai::XaiInitializeError),
+    #[error(transparent)]
+    Registry(#[from] gateway_core::engine::provider::RegistryError),
+    #[error(transparent)]
+    Core(#[from] gateway_core::CoreError),
+    #[error(transparent)]
+    Admin(#[from] gateway_admin::model::AdminError),
+    #[error(transparent)]
+    Api(#[from] gateway_api::ApiError),
+}

backend/apps/gateway/src/bootstrap/plugins.rs

@@ -0,0 +1,108 @@
+//! 插件 Runtime 的组装与回调资源持有；服务和命令模式复用同一组管理端口
+
+use std::sync::Arc;
+
+use gateway_admin::{
+    model::AdminError,
+    ports::{
+        plugin_accounts::PluginAccountAccess, plugin_client_keys::PluginClientKeyAccess,
+        plugin_resources::PluginResourceAccess, provider::ProviderAdminRegistry,
+    },
+};
+use gateway_core::runtime::{RuntimeSnapshotHandle, SnapshotControl};
+use gateway_host::ConfigError;
+use gateway_plugin_runtime::PluginRuntime;
+
+use super::BootstrapError;
+
+// 必须在调用方仍持有 Core 和回调资源时异步关闭，不能先退出该作用域再清理
+macro_rules! or_shutdown {
+    ($runtime:expr, $result:expr) => {
+        match $result {
+            Ok(value) => value,
+            Err(error) => {
+                $runtime.shutdown().await;
+                return Err(error.into());
+            }
+        }
+    };
+}
+
+pub(super) use or_shutdown;
+
+pub(super) struct ManagementPorts {
+    // Runtime 保存 Weak；组合根持有这些 Arc，直到插件全部关闭
+    pub(super) accounts: Arc<dyn PluginAccountAccess>,
+    keys: Arc<dyn PluginClientKeyAccess>,
+    resources: Arc<dyn PluginResourceAccess>,
+}
+
+impl ManagementPorts {
+    pub(super) fn new(
+        store: &gateway_store::StoreBundle,
+        providers: ProviderAdminRegistry,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        let ports = store.admin_ports();
+        Self {
+            accounts: gateway_admin::initialize_plugin_accounts(
+                providers.clone(),
+                ports.accounts(),
+                snapshot.clone(),
+            ),
+            keys: gateway_admin::initialize_plugin_client_keys(
+                providers,
+                ports.client_keys(),
+                snapshot.clone(),
+            ),
+            resources: gateway_admin::initialize_plugin_resources(
+                ports.plugin_resources(),
+                snapshot,
+            ),
+        }
+    }
+
+    pub(super) fn bind(&self, runtime: &PluginRuntime) -> Result<(), AdminError> {
+        runtime.bind_account_ports(&self.accounts)?;
+        runtime.bind_client_key_ports(&self.keys)?;
+        runtime.bind_resource_ports(&self.resources)
+    }
+}
+
+pub(super) fn service_middleware(
+    snapshots: RuntimeSnapshotHandle,
+    runtime: &PluginRuntime,
+) -> gateway_admin::public_service::PlanSource {
+    let middleware = runtime.execution_registry();
+    Arc::new(move || {
+        let snapshot = snapshots.snapshot_for_diagnostics()?;
+        middleware.middleware(snapshot.extensions()?)
+    })
+}
+
+pub(super) fn prepare_plugins(
+    store: &gateway_store::StoreBundle,
+    plugin_cache: std::path::PathBuf,
+    version: &str,
+    http: Arc<gateway_host::outbound::HttpClient>,
+) -> Result<Arc<gateway_plugin_runtime::PluginRuntime>, BootstrapError> {
+    Ok(Arc::new(
+        gateway_plugin_runtime::PluginRuntime::new(
+            store.admin_ports().plugins(),
+            store.admin_ports().plugin_state(),
+            gateway_plugin_runtime::PluginRuntimeConfig {
+                cache_directory: plugin_cache,
+                host_version: version
+                    .trim_start_matches('v')
+                    .parse()
+                    .map_err(|_| ConfigError::InvalidField("host.version"))?,
+                package_limits: gateway_plugin_runtime::PackageLimits::default(),
+                rpc_limits: gateway_plugin_runtime::RpcLimits::default(),
+                restart_circuit: Default::default(),
+            },
+            http,
+            Arc::new(gateway_host::process::ProcessSupervisor::default()),
+        )
+        .with_oauth_pending(store.provider_ports().oauth_pending()),
+    ))
+}

backend/apps/gateway/src/bootstrap/server.rs

@@ -0,0 +1,176 @@
+//! 服务模式完成全部组装后交给 Host 监听，并在停止监听与 Worker 收尾后关闭插件
+
+use gateway_host::ConfigError;
+
+use super::{
+    BootstrapError, GatewayConfig,
+    plugins::{ManagementPorts, or_shutdown, prepare_plugins, service_middleware},
+    startup::{Environment, Mode, Providers},
+};
+
+/// 按冻结顺序初始化全部 Bundle，并把进程阻塞权交给 Host
+pub async fn run() -> Result<(), BootstrapError> {
+    let config = gateway_host::load_config::<GatewayConfig>()?;
+    let environment = Environment::initialize(config.host, config.store, Mode::Server).await?;
+    let mut providers = Providers::initialize(config.openai, &environment).await?;
+    let Environment {
+        host,
+        mut store,
+        timezone,
+        plugin_cache,
+        version,
+        plugin_http,
+    } = environment;
+    let plugin_runtime = prepare_plugins(&store, plugin_cache, &version, plugin_http.clone())?;
+    let core = gateway_core::prepare(
+        store.core_ports(),
+        providers.core,
+        Some(plugin_runtime.clone()),
+        Some(plugin_runtime.observer_registry()),
+        Some(plugin_runtime.policy_registry()),
+        Some(plugin_runtime.execution_registry()),
+        Some(plugin_runtime.frontend_authentication_registry()),
+    );
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_snapshots(&core.snapshots())
+    );
+    let management = ManagementPorts::new(&store, providers.admin.clone(), core.snapshot_control());
+    or_shutdown!(plugin_runtime, management.bind(&plugin_runtime));
+    let mut core = or_shutdown!(plugin_runtime, core.activate().await);
+    let nested_models = core.nested_model_execution_port();
+    let affinity_lookup = core.affinity_lookup_port();
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_model_ports(&nested_models, &affinity_lookup)
+    );
+    host.report_startup_ready("Core");
+    let host_version = or_shutdown!(
+        plugin_runtime,
+        version
+            .trim_start_matches('v')
+            .parse()
+            .map_err(|_| ConfigError::InvalidField("host.version"))
+    );
+    let plugin_inspector = std::sync::Arc::new(gateway_plugin_runtime::PackageInspector::new(
+        gateway_plugin_runtime::PackageLimits::default(),
+        host_version,
+    ));
+    let plugin_distribution = std::sync::Arc::new(or_shutdown!(
+        plugin_runtime,
+        gateway_host::plugin_distribution::HttpPluginDistribution::new(plugin_http)
+    ));
+    let analytics_worker = or_shutdown!(
+        plugin_runtime,
+        store.request_analytics_worker(std::sync::Arc::new(
+            gateway_admin::ProviderUsageBillingProjector::new(providers.admin.clone()),
+        ))
+    );
+    let mut admin = or_shutdown!(
+        plugin_runtime,
+        gateway_admin::initialize_with_plugin_accounts(
+            config.admin,
+            config.client,
+            store.admin_ports(),
+            gateway_admin::AdminRuntimePorts {
+                timezone,
+                service_middleware: service_middleware(core.snapshots(), &plugin_runtime),
+                providers: providers.admin,
+                plugin_preparation: plugin_runtime.clone(),
+                plugin_management: plugin_runtime.clone(),
+                published_snapshot: core.snapshots(),
+                plugin_inspector,
+                plugin_distribution,
+                pricing_source: std::sync::Arc::new(gateway_host::pricing::ModelsDevPricing),
+                snapshot: core.snapshot_control(),
+                account_probe: core.account_probe(),
+                proxy_probe: host.proxy_probe(provider_openai::build_reqwest_client_with_custom_ca),
+                client_distribution: host.client_distribution_resolver(),
+                system: host.system_operations(),
+                client_key_verifier: core.client_key_verifier(),
+            },
+            management.accounts.clone(),
+        )
+        .await
+    );
+    let official_files = host.official_plugin_release_files();
+    let official_identity = host.official_plugin_release_identity();
+    let official_import = or_shutdown!(
+        plugin_runtime,
+        admin
+            .services()
+            .plugins()
+            .import_official_release(
+                official_files.as_ref(),
+                &official_identity,
+                &gateway_admin::model::MutationContext {
+                    actor: gateway_admin::model::MutationActor::System,
+                    request_id: "startup-official-plugin-import".to_owned(),
+                },
+            )
+            .await
+    );
+    if official_import.artifacts > 0 {
+        host.report_startup_ready("Official plugins");
+    }
+    host.report_startup_ready("Admin");
+
+    let mut probes = store.health_probes();
+    probes.extend(core.health_probes());
+    probes.push(host.logging_health_probe());
+    let api = or_shutdown!(
+        plugin_runtime,
+        gateway_api::initialize(
+            config.api,
+            core.execution_service(),
+            admin.services(),
+            probes,
+            host.worker_health(),
+            host.connection_lifecycle(),
+            store.diagnostics(),
+        )
+    )
+    .with_middleware({
+        let snapshots = core.snapshots();
+        let middleware = plugin_runtime.execution_registry();
+        move |snapshot| {
+            if let Some(snapshot) = snapshot {
+                return middleware.middleware(snapshot.extensions()?);
+            }
+            // 数据面未就绪时，管理与诊断路由仍可使用发布候选中的插件
+            let diagnostic = snapshots.snapshot_for_diagnostics()?;
+            middleware.middleware(diagnostic.extensions()?)
+        }
+    });
+    let http_dispatcher = api.dispatcher();
+    or_shutdown!(plugin_runtime, plugin_runtime.bind_http(&http_dispatcher));
+    host.report_startup_ready("API");
+
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_services(&admin.services().public_services())
+    );
+
+    let mut plan = store.take_worker_contributions();
+    plan.push(analytics_worker);
+    plan.push(or_shutdown!(
+        plugin_runtime,
+        gateway_host::retention::worker(store.retention())
+    ));
+    plan.extend(core.take_worker_contributions());
+    plan.extend(providers.openai.take_worker_contributions());
+    plan.extend(providers.xai.take_worker_contributions());
+    plan.extend(admin.take_worker_contributions());
+    plan.push(or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.maintenance_worker(core.snapshots())
+    ));
+    or_shutdown!(
+        plugin_runtime,
+        host.start_workers(plan, store.worker_leader_lease(), store.diagnostics())
+    );
+    host.report_startup_ready("Workers");
+    let served = host.serve(api.router()).await;
+    plugin_runtime.shutdown().await;
+    Ok(served?)
+}

backend/apps/gateway/src/bootstrap/startup.rs

@@ -0,0 +1,94 @@
+//! 启动模式共享的基础设施与 Provider 组装，不启动 HTTP 或 Worker
+
+use std::{path::PathBuf, sync::Arc};
+
+use gateway_admin::ports::provider::ProviderAdminRegistry;
+use gateway_core::{engine::provider::ProviderRegistry, time::DeploymentTimeZone};
+use gateway_host::{ConfigError, HostBundle, HostConfig, outbound::HttpClient};
+use gateway_store::{StoreBundle, StoreConfig};
+
+use super::BootstrapError;
+
+pub(super) enum Mode {
+    Server,
+    Command,
+    Help,
+}
+
+pub(super) struct Environment {
+    pub(super) host: HostBundle,
+    pub(super) store: StoreBundle,
+    pub(super) timezone: DeploymentTimeZone,
+    pub(super) plugin_cache: PathBuf,
+    pub(super) version: String,
+    pub(super) plugin_http: Arc<HttpClient>,
+}
+
+impl Environment {
+    pub(super) async fn initialize(
+        host: HostConfig,
+        store: StoreConfig,
+        mode: Mode,
+    ) -> Result<Self, BootstrapError> {
+        let timezone = host.timezone;
+        let store = store.with_timezone(timezone);
+        let plugin_cache = host.runtime_data_dir().join("plugins");
+        let host = match mode {
+            Mode::Server => gateway_host::initialize(host).await?,
+            Mode::Command | Mode::Help => gateway_host::initialize_command_line(host).await?,
+        };
+        host.report_startup_ready("Host");
+        let store = match mode {
+            Mode::Server => gateway_store::initialize(store).await?,
+            Mode::Command => gateway_store::initialize_command_line(store).await?,
+            Mode::Help => gateway_store::initialize_read_only(store).await?,
+        };
+        host.report_startup_ready("Store");
+        let version = host
+            .system_operations()
+            .version()
+            .await
+            .map_err(|_| ConfigError::InvalidField("host.version"))?
+            .version;
+        let plugin_http = Arc::new(HttpClient::new()?);
+        Ok(Self {
+            host,
+            store,
+            timezone,
+            plugin_cache,
+            version,
+            plugin_http,
+        })
+    }
+}
+
+pub(super) struct Providers {
+    pub(super) openai: provider_openai::ProviderBundle,
+    pub(super) xai: provider_xai::ProviderBundle,
+    pub(super) core: ProviderRegistry,
+    pub(super) admin: ProviderAdminRegistry,
+}
+
+impl Providers {
+    pub(super) async fn initialize(
+        config: provider_openai::OpenAiConfig,
+        environment: &Environment,
+    ) -> Result<Self, BootstrapError> {
+        let ports = environment.store.provider_ports();
+        let openai =
+            provider_openai::initialize(config.with_timezone(environment.timezone), ports.clone())
+                .await?;
+        environment.host.report_startup_ready("OpenAI Provider");
+        let xai = provider_xai::initialize(ports).await?;
+        environment.host.report_startup_ready("xAI Provider");
+        let core = ProviderRegistry::new([openai.core_provider(), xai.core_provider()])?;
+        let admin = ProviderAdminRegistry::new([openai.admin_provider(), xai.admin_provider()])
+            .map_err(|_| gateway_admin::model::AdminError::invalid("Provider 管理身份冲突"))?;
+        Ok(Self {
+            openai,
+            xai,
+            core,
+            admin,
+        })
+    }
+}

backend/apps/gateway/src/lib.rs

@@ -1,3 +1,3 @@
-//! 网关进程组装根。
+//! 网关进程组装根
 
 pub mod bootstrap;

backend/apps/gateway/src/main.rs

@@ -1,3 +1,5 @@
+//! 网关命令行入口，选择启动模式并创建异步运行时
+
 use std::{
     env,
     error::Error,

backend/apps/gateway/tests/architecture.rs

@@ -1,14 +1,15 @@
-//! docs/architecture.md 依赖 DAG 与生产源码纪律的 workspace 级机器校验。
+//! docs/architecture.md 依赖 DAG 与生产源码纪律的 workspace 级机器校验
 
 use std::{
     collections::{BTreeMap, BTreeSet},
     fs,
     path::{Path, PathBuf},
+    sync::OnceLock,
 };
 
 use syn::{Item, visit::Visit};
 
-/// workspace 成员冻结清单;新增 crate 必须同步扩展本文件的依赖规则。
+/// workspace 成员冻结清单;新增 crate 必须同步扩展本文件的依赖规则
 pub(super) const WORKSPACE_MEMBERS: &[&str] = &[
     "apps/gateway",
     "apps/plugin-cli",
@@ -26,22 +27,24 @@ pub(super) const WORKSPACE_MEMBERS: &[&str] = &[
 
 #[test]
 fn workspace_member_list_matches_the_frozen_dag_scope() {
-    let manifest =
-        fs::read_to_string(backend_root().join("Cargo.toml")).expect("read workspace manifest");
-    for member in WORKSPACE_MEMBERS {
-        assert!(
-            manifest.contains(&format!("\"{member}\"")),
-            "workspace must include {member}"
-        );
-    }
-    let member_count = manifest
-        .lines()
-        .map(str::trim)
-        .filter(|line| line.starts_with("\"apps/") || line.starts_with("\"crates/"))
-        .count();
+    let metadata = cargo_metadata_json();
+    let root = backend_root();
+    let actual: BTreeSet<_> = metadata["packages"]
+        .as_array()
+        .expect("Cargo packages")
+        .iter()
+        .map(|package| {
+            Path::new(package["manifest_path"].as_str().expect("package manifest"))
+                .parent()
+                .expect("package directory")
+                .strip_prefix(&root)
+                .expect("workspace member path")
+                .to_path_buf()
+        })
+        .collect();
     assert_eq!(
-        member_count,
-        WORKSPACE_MEMBERS.len(),
+        actual,
+        WORKSPACE_MEMBERS.iter().map(PathBuf::from).collect(),
         "new workspace members must extend the dependency DAG rules"
     );
 }
@@ -79,18 +82,25 @@ fn core_value_owners_do_not_depend_on_execution_or_routing() {
             path if path.starts_with("policy/") => {
                 Some(&["account", "identity", "policy", "validation"])
             }
-            "settings/values.rs" | "settings/compiled.rs" => {
-                Some(&["account", "concurrency", "identity", "metering", "policy"])
-            }
+            path if path.starts_with("settings/") => Some(&[
+                "account",
+                "concurrency",
+                "identity",
+                "metering",
+                "policy",
+                "settings",
+            ]),
             path if path.starts_with("account/") => Some(&["account", "identity", "validation"]),
             _ => None,
         };
         let Some(allowed) = allowed else { continue };
         let source = fs::read_to_string(root.join(&relative)).expect("read core source");
         let syntax = syn::parse_file(&source).expect("parse core source");
-        let mut references = CrateReferences::default();
+        let mut references = CrateReferences::in_module(&relative);
         references.visit_file(&syntax);
-        for dependency in references.0 {
+        // 相对路径中的 self 指向当前 owner，不是跨 owner 依赖
+        references.owners.remove(&references.module_path[0]);
+        for dependency in references.owners {
             assert!(
                 allowed.contains(&dependency.as_str()),
                 "{} must not depend on crate::{dependency}",
@@ -100,49 +110,155 @@ fn core_value_owners_do_not_depend_on_execution_or_routing() {
     }
 }
 
+#[test]
+fn core_owner_paths_form_a_dag() {
+    let root = backend_root().join("crates/gateway-core/src");
+    let mut graph = BTreeMap::<String, BTreeSet<String>>::new();
+    for relative in super::rust_files(&root) {
+        if relative == Path::new("lib.rs") {
+            continue;
+        }
+        let mut references = CrateReferences::in_module(&relative);
+        let owner = references.module_path[0].clone();
+        let source = fs::read_to_string(root.join(&relative)).expect("read core source");
+        references.visit_file(&syn::parse_file(&source).expect("parse core source"));
+        references.owners.remove(&owner);
+        graph.entry(owner).or_default().extend(references.owners);
+    }
+    for owner in graph.keys() {
+        let mut pending = graph[owner].iter().cloned().collect::<Vec<_>>();
+        let mut visited = BTreeSet::new();
+        while let Some(dependency) = pending.pop() {
+            assert_ne!(
+                &dependency, owner,
+                "Core owner dependency cycle reaches {owner}"
+            );
+            if visited.insert(dependency.clone())
+                && let Some(next) = graph.get(&dependency)
+            {
+                pending.extend(next.iter().cloned());
+            }
+        }
+    }
+}
+
+#[test]
+fn core_reference_scan_resolves_groups_reexports_and_relative_paths() {
+    let syntax = syn::parse_file(
+        r#"
+        pub use crate::{engine::AttemptContext, settings::SettingsValues as Values};
+        use super::super::runtime as publication;
+        use self::compiled::Value;
+        // crate::ignored::Comment
+        const EXAMPLE: &str = "crate::ignored::Literal";
+        "#,
+    )
+    .expect("parse reference fixture");
+    let mut references = CrateReferences::in_module(Path::new("routing/snapshot.rs"));
+    references.visit_file(&syntax);
+    assert_eq!(
+        references.owners,
+        BTreeSet::from([
+            "engine".to_owned(),
+            "settings".to_owned(),
+            "runtime".to_owned(),
+            "routing".to_owned(),
+        ])
+    );
+}
+
 #[derive(Default)]
-struct CrateReferences(BTreeSet<String>);
+struct CrateReferences {
+    owners: BTreeSet<String>,
+    module_path: Vec<String>,
+}
 
 impl<'ast> Visit<'ast> for CrateReferences {
     fn visit_path(&mut self, path: &'ast syn::Path) {
-        let mut segments = path.segments.iter();
-        if segments
-            .next()
-            .is_some_and(|segment| segment.ident == "crate")
-            && let Some(owner) = segments.next()
-        {
-            self.0.insert(owner.ident.to_string());
-        }
+        self.record(
+            &path
+                .segments
+                .iter()
+                .map(|part| part.ident.to_string())
+                .collect::<Vec<_>>(),
+        );
         syn::visit::visit_path(self, path);
     }
 
     fn visit_item_use(&mut self, item: &'ast syn::ItemUse) {
-        self.use_tree(&item.tree, false);
+        self.use_tree(&item.tree, &mut Vec::new());
     }
 }
 
 impl CrateReferences {
-    fn use_tree(&mut self, tree: &syn::UseTree, crate_root: bool) {
+    fn in_module(relative: &Path) -> Self {
+        let mut module = relative
+            .with_extension("")
+            .components()
+            .map(|part| {
+                part.as_os_str()
+                    .to_str()
+                    .expect("UTF-8 module path")
+                    .to_owned()
+            })
+            .collect::<Vec<_>>();
+        if module.last().is_some_and(|part| part == "mod") {
+            module.pop();
+        }
+        Self {
+            owners: BTreeSet::new(),
+            module_path: module,
+        }
+    }
+
+    fn record(&mut self, path: &[String]) {
+        let Some(first) = path.first() else { return };
+        let owner = if first == "crate" {
+            path.get(1).cloned()
+        } else if first == "self" || first == "super" {
+            let mut module = self.module_path.clone();
+            let mut rest = path;
+            while rest
+                .first()
+                .is_some_and(|part| part == "super" || part == "self")
+            {
+                if rest[0] == "super" {
+                    module.pop();
+                }
+                rest = &rest[1..];
+            }
+            module.first().or_else(|| rest.first()).cloned()
+        } else {
+            None
+        };
+        if let Some(owner) = owner {
+            self.owners.insert(owner);
+        }
+    }
+
+    fn use_tree(&mut self, tree: &syn::UseTree, prefix: &mut Vec<String>) {
         match tree {
-            syn::UseTree::Path(path) if crate_root => {
-                self.0.insert(path.ident.to_string());
+            syn::UseTree::Path(path) => {
+                prefix.push(path.ident.to_string());
+                self.use_tree(&path.tree, prefix);
+                prefix.pop();
             }
-            syn::UseTree::Name(name) if crate_root => {
-                self.0.insert(name.ident.to_string());
+            syn::UseTree::Name(name) => {
+                prefix.push(name.ident.to_string());
+                self.record(prefix);
+                prefix.pop();
             }
-            syn::UseTree::Rename(rename) if crate_root => {
-                self.0.insert(rename.ident.to_string());
+            syn::UseTree::Rename(rename) => {
+                prefix.push(rename.ident.to_string());
+                self.record(prefix);
+                prefix.pop();
             }
-            syn::UseTree::Path(path) => self.use_tree(&path.tree, path.ident == "crate"),
             syn::UseTree::Group(group) => {
                 for item in &group.items {
-                    self.use_tree(item, crate_root);
+                    self.use_tree(item, prefix);
                 }
             }
-            syn::UseTree::Glob(_) if crate_root => {
-                self.0.insert("*".to_owned());
-            }
-            _ => {}
+            syn::UseTree::Glob(_) => self.record(prefix),
         }
     }
 }
@@ -178,7 +294,7 @@ fn gateway_admin_stays_free_of_infrastructure_dependencies() {
     );
 }
 
-/// workspace 包名到冻结成员路径的映射。
+/// workspace 包名到冻结成员路径的映射
 const PACKAGE_TO_MEMBER: &[(&str, &str)] = &[
     ("codex-proxy-rs", "apps/gateway"),
     ("codex-proxy-plugin-cli", "apps/plugin-cli"),
@@ -194,7 +310,7 @@ const PACKAGE_TO_MEMBER: &[(&str, &str)] = &[
     ("provider-xai", "crates/providers/xai"),
 ];
 
-/// SDK 与 Adapter/provider 根门面的稳定合同模块；任何增减都必须同步完成边界审计。
+/// SDK 与 Adapter/provider 根门面的稳定合同模块；任何增减都必须同步完成边界审计
 const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
     ("crates/gateway-plugin/sdk", &["call", "client"]),
     ("crates/gateway-plugin/runtime", &[]),
@@ -221,16 +337,16 @@ const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
         "crates/providers/openai",
         &["config", "credential", "transport"],
     ),
-    ("crates/providers/xai", &["credential", "transport"]),
+    ("crates/providers/xai", &["transport"]),
 ];
 
-/// 不对应单一生产模块、而是校验 crate/workspace 整体契约的根级测试场景。
+/// 不对应单一生产模块、而是校验 crate/workspace 整体契约的根级测试场景
 const ROOT_TEST_SCENARIOS: &[(&str, &[&str])] = &[
     ("apps/gateway", &["architecture"]),
     ("crates/gateway-api", &["architecture"]),
 ];
 
-/// 冻结的 workspace 内部运行时依赖边；新增/删除任何边都必须同步本表。
+/// 冻结的 workspace 内部运行时依赖边；新增/删除任何边都必须同步本表
 const ALLOWED_INTERNAL_EDGES: &[(&str, &str)] = &[
     ("codex-proxy-plugin-cli", "gateway-plugin-sdk"),
     ("codex-proxy-rs", "gateway-admin"),
@@ -265,7 +381,7 @@ const ALLOWED_INTERNAL_EDGES: &[(&str, &str)] = &[
 #[test]
 fn workspace_internal_dependency_edges_match_frozen_dag() {
     let metadata = cargo_metadata_json();
-    let actual = workspace_runtime_dependency_edges(&metadata);
+    let actual = workspace_runtime_dependency_edges(metadata);
     let mut expected: Vec<(String, String)> = ALLOWED_INTERNAL_EDGES
         .iter()
         .map(|(from, to)| ((*from).to_owned(), (*to).to_owned()))
@@ -361,24 +477,6 @@ fn adapter_public_module_surfaces_match_allowlist() {
     }
 }
 
-#[test]
-fn production_sources_do_not_host_tests() {
-    for member in WORKSPACE_MEMBERS {
-        let src = backend_root().join(member).join("src");
-        let sources = super::rust_files(&src);
-        assert!(!sources.is_empty(), "{member} has no production sources");
-        for relative in sources {
-            let path = src.join(relative);
-            let source = fs::read_to_string(&path).expect("read production source");
-            assert!(
-                !source.contains("#[cfg(test)]"),
-                "{} hosts tests in production src",
-                path.display()
-            );
-        }
-    }
-}
-
 #[test]
 fn workspace_modules_follow_conventional_file_layout() {
     let targets = test_source_roots();
@@ -475,7 +573,7 @@ fn integration_tests_mirror_production_module_tree() {
     }
 }
 
-/// Rust 子进程 fixture 是 Cargo 的独立 crate 根，不能要求它由测试模块再次声明。
+/// Rust 子进程 fixture 是 Cargo 的独立 crate 根，不能要求它由测试模块再次声明
 fn test_source_roots() -> BTreeMap<PathBuf, Vec<String>> {
     let metadata = cargo_metadata_json();
     let mut roots = BTreeMap::<PathBuf, Vec<String>>::new();
@@ -529,7 +627,7 @@ fn root_test_scenario_allowed(member: &str, module: &Path) -> bool {
 
 fn assert_module_tree(root: &Path, crate_roots: &[&str]) {
     let files = super::rust_files(root);
-    // 同一父模块的所有子文件复用一次语法解析，计数仍保留重复声明检查。
+    // 同一父模块的所有子文件复用一次语法解析，计数仍保留重复声明检查
     let mut declarations = BTreeMap::<PathBuf, BTreeMap<String, usize>>::new();
     for relative in &files {
         if crate_roots
@@ -635,40 +733,46 @@ pub(super) fn backend_root() -> PathBuf {
         .expect("backend workspace root")
 }
 
-fn cargo_metadata_json() -> serde_json::Value {
-    let output = std::process::Command::new("cargo")
-        .args(["metadata", "--format-version", "1", "--no-deps"])
-        .current_dir(backend_root())
-        .output()
-        .expect("run cargo metadata");
-    assert!(
-        output.status.success(),
-        "cargo metadata failed: {}",
-        String::from_utf8_lossy(&output.stderr)
-    );
-    serde_json::from_slice(&output.stdout).expect("parse cargo metadata")
+fn cargo_metadata_json() -> &'static serde_json::Value {
+    static METADATA: OnceLock<serde_json::Value> = OnceLock::new();
+    METADATA.get_or_init(|| {
+        let output = std::process::Command::new("cargo")
+            .args(["metadata", "--format-version", "1", "--no-deps", "--locked"])
+            .current_dir(backend_root())
+            .output()
+            .expect("run cargo metadata");
+        assert!(
+            output.status.success(),
+            "cargo metadata failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+        serde_json::from_slice(&output.stdout).expect("parse cargo metadata")
+    })
 }
 
-/// 提取成员 `[dependencies]` 段内声明的依赖名;段落以下一个 `[` 表头结束。
+/// 复用 Cargo 解析后的实际包名，覆盖重命名依赖与平台条件，排除测试和构建依赖
 fn dependency_names(member: &str) -> Vec<String> {
-    let manifest = fs::read_to_string(backend_root().join(member).join("Cargo.toml"))
-        .expect("read member manifest");
-    let mut in_dependencies = false;
-    let mut names = Vec::new();
-    for line in manifest.lines() {
-        let line = line.trim();
-        if line.starts_with('[') {
-            in_dependencies = line == "[dependencies]";
-            continue;
-        }
-        if !in_dependencies || line.is_empty() || line.starts_with('#') {
-            continue;
-        }
-        if let Some((name, _)) = line.split_once('=') {
-            names.push(name.trim().to_owned());
-        }
-    }
-    names
+    let manifest = backend_root().join(member).join("Cargo.toml");
+    let package = cargo_metadata_json()["packages"]
+        .as_array()
+        .expect("Cargo packages")
+        .iter()
+        .find(|package| {
+            Path::new(package["manifest_path"].as_str().expect("package manifest")) == manifest
+        })
+        .expect("workspace member");
+    package["dependencies"]
+        .as_array()
+        .expect("package dependencies")
+        .iter()
+        .filter(|dependency| dependency["kind"].is_null())
+        .map(|dependency| {
+            dependency["name"]
+                .as_str()
+                .expect("dependency name")
+                .to_owned()
+        })
+        .collect()
 }
 
 fn assert_no_dependency(member: &str, forbidden: &[&str]) {

backend/apps/gateway/tests/bootstrap/command.rs

@@ -0,0 +1,51 @@
+//! 验证网关基础命令无需加载配置，并拒绝非法或多余参数
+
+use std::{fs, process::Command};
+
+#[test]
+fn basic_cli_options_do_not_load_configuration_and_reject_unexpected_arguments() {
+    let directory = tempfile::tempdir().unwrap();
+    fs::create_dir(directory.path().join("deploy")).unwrap();
+    fs::write(directory.path().join("deploy/config.yaml"), "invalid: [").unwrap();
+    for flag in ["--help", "-h", "help", "--version", "-V"] {
+        let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
+            .arg(flag)
+            .current_dir(directory.path())
+            .env_clear()
+            .output()
+            .unwrap();
+        assert!(output.status.success(), "{flag}");
+        assert!(!output.stdout.is_empty());
+        assert!(output.stderr.is_empty());
+    }
+    for args in [
+        vec!["unknown"],
+        vec!["--help", "extra"],
+        vec!["serve", "extra"],
+    ] {
+        let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
+            .args(args)
+            .current_dir(directory.path())
+            .env_clear()
+            .output()
+            .unwrap();
+        assert!(!output.status.success());
+        assert!(output.stdout.is_empty());
+        assert!(!String::from_utf8_lossy(&output.stderr).contains("configuration"));
+    }
+}
+
+#[cfg(unix)]
+#[test]
+fn non_utf8_command_is_not_interpreted_as_serve() {
+    use std::os::unix::ffi::OsStringExt as _;
+
+    let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
+        .arg(std::ffi::OsString::from_vec(vec![0xff]))
+        .env_clear()
+        .output()
+        .unwrap();
+    assert!(!output.status.success());
+    assert!(output.stdout.is_empty());
+    assert!(String::from_utf8_lossy(&output.stderr).contains("command must be UTF-8"));
+}

backend/apps/gateway/tests/bootstrap/config.rs

@@ -1,207 +1,16 @@
+//! 验证顶层配置加载、路径解析、显式覆盖与敏感字段脱敏
+
 use std::{fs, process::Command};
 
 use codex_proxy_rs::bootstrap::GatewayConfig;
 use gateway_host::LoadableConfig;
 
-const CONFIG_EXAMPLE: &str = include_str!("../../../../deploy/config.example.yaml");
+const CONFIG_EXAMPLE: &str = include_str!("../../../../../deploy/config.example.yaml");
 const POSTGRES_PASSWORD: &str = "111111111111111111111111111111111111111111111111";
 const REDIS_PASSWORD: &str = "222222222222222222222222222222222222222222222222";
 const ADMIN_PASSWORD: &str = "test-admin-password";
 const TOPOLOGY_CHILD_ENV: &str = "CPR_TEST_TOPOLOGY_CHILD";
 
-#[test]
-fn basic_cli_options_do_not_load_configuration_and_reject_unexpected_arguments() {
-    let directory = tempfile::tempdir().unwrap();
-    fs::create_dir(directory.path().join("deploy")).unwrap();
-    fs::write(directory.path().join("deploy/config.yaml"), "invalid: [").unwrap();
-    for flag in ["--help", "-h", "help", "--version", "-V"] {
-        let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
-            .arg(flag)
-            .current_dir(directory.path())
-            .env_clear()
-            .output()
-            .unwrap();
-        assert!(output.status.success(), "{flag}");
-        assert!(!output.stdout.is_empty());
-        assert!(output.stderr.is_empty());
-    }
-    for args in [
-        vec!["unknown"],
-        vec!["--help", "extra"],
-        vec!["serve", "extra"],
-    ] {
-        let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
-            .args(args)
-            .current_dir(directory.path())
-            .env_clear()
-            .output()
-            .unwrap();
-        assert!(!output.status.success());
-        assert!(output.stdout.is_empty());
-        assert!(!String::from_utf8_lossy(&output.stderr).contains("configuration"));
-    }
-}
-
-#[cfg(unix)]
-#[test]
-fn non_utf8_command_is_not_interpreted_as_serve() {
-    use std::os::unix::ffi::OsStringExt as _;
-
-    let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
-        .arg(std::ffi::OsString::from_vec(vec![0xff]))
-        .env_clear()
-        .output()
-        .unwrap();
-    assert!(!output.status.success());
-    assert!(output.stdout.is_empty());
-    assert!(String::from_utf8_lossy(&output.stderr).contains("command must be UTF-8"));
-}
-
-#[tokio::test]
-async fn proxy_probe_should_use_provider_custom_ca_for_https_proxies() {
-    use gateway_admin::ports::proxy::ProxyProbe;
-    use gateway_core::account::OutboundProxy;
-    use gateway_host::proxy_probe::HttpProxyProbe;
-    use std::{sync::Arc, time::Duration};
-    use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
-    use tokio_rustls::{
-        TlsAcceptor,
-        rustls::{
-            ServerConfig,
-            pki_types::{CertificateDer, PrivateKeyDer, pem::PemObject as _},
-        },
-    };
-
-    const CHILD_ENV: &str = "CPR_TEST_PROXY_TLS_DIRECTORY";
-    let Ok(directory) = std::env::var(CHILD_ENV) else {
-        let directory = tempfile::tempdir().unwrap();
-        generate_proxy_test_certificates(directory.path());
-        // 使用子进程隔离环境变量，避免并行测试读取到临时 CA 配置。
-        for ca_env in ["CODEX_CA_CERTIFICATE", "SSL_CERT_FILE"] {
-            let mut child = Command::new(std::env::current_exe().unwrap());
-            child
-                .args([
-                    "--exact",
-                    "bootstrap::proxy_probe_should_use_provider_custom_ca_for_https_proxies",
-                    "--nocapture",
-                ])
-                .env(CHILD_ENV, directory.path())
-                .env_remove("CODEX_CA_CERTIFICATE")
-                .env_remove("SSL_CERT_FILE")
-                .env(ca_env, directory.path().join("ca.pem"));
-            if ca_env == "CODEX_CA_CERTIFICATE" {
-                child.env(
-                    "SSL_CERT_FILE",
-                    directory.path().join("missing-fallback.pem"),
-                );
-            }
-            let output = child.output().unwrap();
-            assert!(
-                output.status.success(),
-                "{ca_env}: {}\n{}",
-                String::from_utf8_lossy(&output.stdout),
-                String::from_utf8_lossy(&output.stderr)
-            );
-        }
-        return;
-    };
-    provider_openai::ensure_rustls_provider();
-    let directory = std::path::Path::new(&directory);
-    let certificate = CertificateDer::from_pem_file(directory.join("server.pem")).unwrap();
-    let key = PrivateKeyDer::from_pem_file(directory.join("server.key")).unwrap();
-    let acceptor = TlsAcceptor::from(Arc::new(
-        ServerConfig::builder()
-            .with_no_client_auth()
-            .with_single_cert(vec![certificate], key)
-            .unwrap(),
-    ));
-    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
-    let proxy =
-        OutboundProxy::parse(&format!("https://{}", listener.local_addr().unwrap())).unwrap();
-    let server = tokio::spawn(async move {
-        let (socket, _) = listener.accept().await.unwrap();
-        let mut stream = acceptor.accept(socket).await.unwrap();
-        let mut request = Vec::new();
-        while !request.ends_with(b"\r\n\r\n") {
-            assert!(request.len() < 8192);
-            request.push(stream.read_u8().await.unwrap());
-        }
-        assert!(request.starts_with(b"GET http://unresolvable.invalid/ip "));
-        let body = "{\"ip\":\"203.0.113.8\"}";
-        stream.write_all(format!("HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", body.len()).as_bytes()).await.unwrap();
-        stream.shutdown().await.unwrap();
-    });
-    let probe = HttpProxyProbe::new("http://unresolvable.invalid/ip")
-        .with_client_builder(provider_openai::build_reqwest_client_with_custom_ca);
-    let result = probe.test(&proxy, false).await;
-    assert!(result.success, "{}", result.message);
-    assert_eq!(result.exit_ip.unwrap().to_string(), "203.0.113.8");
-    tokio::time::timeout(Duration::from_secs(5), server)
-        .await
-        .unwrap()
-        .unwrap();
-}
-
-fn generate_proxy_test_certificates(directory: &std::path::Path) {
-    let openssl = |args: &[&str]| {
-        let output = Command::new("openssl")
-            .args(args)
-            .current_dir(directory)
-            .output()
-            .unwrap();
-        assert!(
-            output.status.success(),
-            "{}",
-            String::from_utf8_lossy(&output.stderr)
-        );
-    };
-    openssl(&[
-        "req",
-        "-x509",
-        "-newkey",
-        "rsa:2048",
-        "-nodes",
-        "-keyout",
-        "ca.key",
-        "-out",
-        "ca.pem",
-        "-days",
-        "1",
-        "-subj",
-        "/CN=Proxy Test CA",
-    ]);
-    openssl(&[
-        "req",
-        "-newkey",
-        "rsa:2048",
-        "-nodes",
-        "-keyout",
-        "server.key",
-        "-out",
-        "server.csr",
-        "-subj",
-        "/CN=localhost",
-    ]);
-    fs::write(directory.join("extensions"), "subjectAltName=IP:127.0.0.1\nbasicConstraints=critical,CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n").unwrap();
-    openssl(&[
-        "x509",
-        "-req",
-        "-in",
-        "server.csr",
-        "-CA",
-        "ca.pem",
-        "-CAkey",
-        "ca.key",
-        "-CAcreateserial",
-        "-out",
-        "server.pem",
-        "-days",
-        "1",
-        "-extfile",
-        "extensions",
-    ]);
-}
-
 #[test]
 fn config_loader_should_load_complete_terminal_example() {
     parse_config(&valid_config()).expect("terminal config example");
@@ -220,7 +29,7 @@ fn config_loader_should_resolve_paths_relative_to_config_file() {
 fn config_loader_should_share_resolved_assets_with_system_update() {
     const CHILD_ENV: &str = "CPR_TEST_UPDATE_ASSETS_CHILD";
     let Ok(case) = std::env::var(CHILD_ENV) else {
-        // 使用子进程覆盖无环境变量、Docker 路径和相对路径，避免污染并行测试。
+        // 使用子进程覆盖无环境变量、Docker 路径和相对路径，避免污染并行测试
         for (case, web_dist) in [
             ("binary", None),
             ("docker", Some("/app/web/dist")),
@@ -230,7 +39,7 @@ fn config_loader_should_share_resolved_assets_with_system_update() {
             child
                 .args([
                     "--exact",
-                    "bootstrap::config_loader_should_share_resolved_assets_with_system_update",
+                    "bootstrap::config::config_loader_should_share_resolved_assets_with_system_update",
                 ])
                 .env(CHILD_ENV, case)
                 .env_remove("CPR_WEB_DIST_DIR");
@@ -267,11 +76,6 @@ fn config_loader_should_reject_missing_runtime_data_dir() {
     assert!(parse_config(&config).is_err());
 }
 
-#[test]
-fn config_loader_should_inject_connection_passwords_into_urls() {
-    parse_config(&valid_config()).expect("Store validates password injection into both URLs");
-}
-
 #[test]
 fn config_loader_should_apply_only_explicit_topology_overrides() {
     let invalid = valid_config()
@@ -292,7 +96,7 @@ fn config_loader_should_apply_only_explicit_topology_overrides() {
     let status = Command::new(std::env::current_exe().expect("current test executable"))
         .args([
             "--exact",
-            "bootstrap::config_loader_should_apply_only_explicit_topology_overrides",
+            "bootstrap::config::config_loader_should_apply_only_explicit_topology_overrides",
         ])
         .env(TOPOLOGY_CHILD_ENV, "1")
         .env("CPR_SERVER_HOST", "127.0.0.1")
@@ -302,8 +106,11 @@ fn config_loader_should_apply_only_explicit_topology_overrides() {
             "postgres://codex_proxy@127.0.0.1:5432/codex_proxy",
         )
         .env("CPR_REDIS_URL", "redis://127.0.0.1:6379/")
-        .env("CPR_DATABASE_PASSWORD", POSTGRES_PASSWORD)
-        .env("CPR_REDIS_PASSWORD", REDIS_PASSWORD)
+        .env(
+            "CPR_DATABASE_PASSWORD",
+            "RdsTest9!abcdefGhRdsTest9!abcdefGh",
+        )
+        .env("CPR_REDIS_PASSWORD", "ManagedRedis9!abcdefGh")
         .status()
         .expect("run isolated environment override test");
     assert!(status.success());
@@ -348,14 +155,6 @@ fn config_loader_should_ignore_unknown_fields_in_configuration_sections() {
     }
 }
 
-#[test]
-fn config_loader_should_ignore_removed_tls_and_fingerprint_sections() {
-    let mut document = valid_config_document();
-    document["openai"]["tls"] = serde_json::json!({});
-    document["openai"]["fingerprint"] = serde_json::json!({"browser": "removed"});
-    parse_config(&document.to_string()).expect("removed provider settings are ignored");
-}
-
 #[test]
 fn config_loader_should_reject_invalid_known_fields_alongside_unknown_fields() {
     for port in [serde_json::json!(0), serde_json::json!("not-a-port")] {
@@ -374,16 +173,32 @@ fn config_loader_should_report_startup_configuration_diagnostics() {
         gateway_host::load_config::<GatewayConfig>().expect("startup configuration");
         return;
     }
-    for case in ["normal", "unused", "missing"] {
+    for case in [
+        "normal",
+        "unused",
+        "missing",
+        "timezoneEmpty",
+        "timezoneInvalid",
+        "timezoneNull",
+        "timezoneType",
+    ] {
         let mut document = valid_config_document();
         if case == "unused" {
-            document["openai"]["wire_profile"]["location"] = serde_json::json!(UNUSED_SECRET);
+            document["openai"]["unused_setting"] = serde_json::json!(UNUSED_SECRET);
         } else if case == "missing" {
             document["host"]["listen"]
                 .as_object_mut()
                 .unwrap()
                 .remove("port");
         }
+        if case.starts_with("timezone") {
+            document["host"]["timezone"] = match case {
+                "timezoneEmpty" => serde_json::json!(""),
+                "timezoneInvalid" => serde_json::json!(UNUSED_SECRET),
+                "timezoneNull" => serde_json::json!(null),
+                _ => serde_json::json!(8),
+            };
+        }
         let directory = tempfile::tempdir().unwrap();
         fs::create_dir(directory.path().join("deploy")).unwrap();
         fs::write(
@@ -394,7 +209,7 @@ fn config_loader_should_report_startup_configuration_diagnostics() {
         let output = Command::new(std::env::current_exe().unwrap())
             .args([
                 "--exact",
-                "bootstrap::config_loader_should_report_startup_configuration_diagnostics",
+                "bootstrap::config::config_loader_should_report_startup_configuration_diagnostics",
                 "--nocapture",
             ])
             .env(CHILD_ENV, "1")
@@ -404,15 +219,18 @@ fn config_loader_should_report_startup_configuration_diagnostics() {
         let stderr = String::from_utf8_lossy(&output.stderr);
         assert_eq!(
             output.status.success(),
-            case != "missing",
+            case != "missing" && !case.starts_with("timezone"),
             "{case}: {stderr}"
         );
         match case {
             "unused" => assert!(
-                stderr.contains("openai.wire_profile") && stderr.contains("已忽略"),
+                stderr.contains("openai.unused_setting") && stderr.contains("已忽略"),
                 "{stderr}"
             ),
             "missing" => assert!(stderr.contains("host.listen.port"), "{stderr}"),
+            case if case.starts_with("timezone") => {
+                assert!(stderr.contains("host.timezone"), "{stderr}")
+            }
             _ => assert!(!stderr.contains("警告"), "{stderr}"),
         }
         assert!(!stderr.contains(UNUSED_SECRET), "{stderr}");
@@ -430,19 +248,7 @@ fn config_loader_should_allow_missing_provider_configuration() {
     let mut document = valid_config_document();
     document.as_object_mut().unwrap().remove("openai");
     document.as_object_mut().unwrap().remove("xai");
-    parse_config(&document.to_string()).expect("provider defaults require no YAML identity");
-}
-
-#[test]
-fn config_loader_should_ignore_removed_provider_identity_sections() {
-    let mut document = valid_config_document();
-    document["openai"]["wire_profile"] = serde_json::json!({"codex_version":"legacy-invalid"});
-    document["xai"] = serde_json::json!({"wire_profile": {"client_identifier": "legacy-client"}});
-    let (config, _directory) =
-        parse_config(&document.to_string()).expect("removed identities ignored");
-    let debug = format!("{config:?}");
-    assert!(!debug.contains("legacy-invalid"));
-    assert!(!debug.contains("legacy-client"));
+    parse_config(&document.to_string()).expect("providers use defaults when omitted");
 }
 
 #[test]
@@ -459,13 +265,53 @@ fn config_loader_should_reject_embedded_database_password() {
 }
 
 #[test]
-fn config_loader_should_reject_non_hex_postgres_password() {
-    assert_rejected(valid_config().replace(POSTGRES_PASSWORD, &"g".repeat(48)));
+fn config_loader_should_accept_managed_store_passwords() {
+    for password in [
+        "RdsTest9!abcdefGh".to_owned(),
+        "RdsTest9!abcdefGhRdsTest9!abcdefGh".to_owned(),
+        POSTGRES_PASSWORD.to_owned(),
+        "x".repeat(128),
+        "Managed@:/?#%&+Password9!".to_owned(),
+        "数据库密码".repeat(4),
+    ] {
+        for field in ["database", "redis"] {
+            let mut document = valid_config_document();
+            document["store"][field]["password"] = serde_json::json!(password);
+            let (config, _directory) =
+                parse_config(&document.to_string()).expect("managed store password");
+            assert!(!format!("{config:?}").contains(&password));
+        }
+    }
 }
 
 #[test]
-fn config_loader_should_reject_wrong_length_redis_password() {
-    assert_rejected(valid_config().replace(REDIS_PASSWORD, "1234"));
+fn config_loader_should_reject_invalid_store_passwords() {
+    for password in [
+        String::new(),
+        "x".repeat(15),
+        "x".repeat(129),
+        " ".repeat(32),
+        "\u{3000}".repeat(6),
+        "数据库密码".repeat(9),
+        "RdsTest9!abcdefGh\u{0000}".to_owned(),
+        "RdsTest9!abcdefGh\n".to_owned(),
+        "RdsTest9!abcdefGh\t".to_owned(),
+        "RdsTest9!abcdefGh\u{007f}".to_owned(),
+    ] {
+        for field in ["database", "redis"] {
+            let mut document = valid_config_document();
+            document["store"][field]["password"] = serde_json::json!(password);
+            assert_rejected(document.to_string());
+        }
+    }
+}
+
+#[test]
+fn config_loader_should_reject_embedded_redis_password() {
+    assert_rejected(valid_config().replace(
+        "redis://127.0.0.1:6379/",
+        "redis://default:embedded@127.0.0.1:6379/",
+    ));
 }
 
 #[test]
@@ -553,7 +399,7 @@ fn valid_config() -> String {
 }
 
 fn valid_config_document() -> serde_json::Value {
-    // 按字段修改样例，避免注释或排版变化让测试输入悄悄失效；JSON 仍可由 YAML 文件入口加载。
+    // 按字段修改样例，避免注释或排版变化让测试输入悄悄失效；JSON 仍可由 YAML 文件入口加载
     config::Config::builder()
         .add_source(config::File::from_str(
             &valid_config(),
@@ -580,3 +426,18 @@ fn parse_config(config: &str) -> Result<(GatewayConfig, tempfile::TempDir), Stri
         .map_err(|error| error.to_string())?;
     Ok((config, directory))
 }
+
+#[test]
+fn deployment_timezone_defaults_and_valid_override_are_loaded() {
+    let mut document = valid_config_document();
+    document["host"].as_object_mut().unwrap().remove("timezone");
+    let (_config, _directory) = parse_config(&document.to_string()).unwrap();
+    let host: gateway_host::config::HostConfig =
+        serde_json::from_value(document["host"].clone()).unwrap();
+    assert_eq!(host.timezone.name(), "Asia/Shanghai");
+    document["host"]["timezone"] = serde_json::json!("Asia/Kathmandu");
+    let (_config, _directory) = parse_config(&document.to_string()).unwrap();
+    let host: gateway_host::config::HostConfig =
+        serde_json::from_value(document["host"].clone()).unwrap();
+    assert_eq!(host.timezone.name(), "Asia/Kathmandu");
+}

backend/apps/gateway/tests/bootstrap/mod.rs

@@ -0,0 +1,5 @@
+//! 网关启动配置、命令行与服务组装的测试入口
+
+mod command;
+mod config;
+mod server;

backend/apps/gateway/tests/bootstrap/server.rs

@@ -0,0 +1,148 @@
+//! 验证服务组装为 HTTPS 代理探测传递自定义 CA
+
+use std::{fs, process::Command};
+
+#[tokio::test]
+async fn proxy_probe_should_use_provider_custom_ca_for_https_proxies() {
+    use gateway_admin::ports::proxy::ProxyProbe;
+    use gateway_core::account::OutboundProxy;
+    use gateway_host::proxy_probe::HttpProxyProbe;
+    use std::{sync::Arc, time::Duration};
+    use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
+    use tokio_rustls::{
+        TlsAcceptor,
+        rustls::{
+            ServerConfig,
+            pki_types::{CertificateDer, PrivateKeyDer, pem::PemObject as _},
+        },
+    };
+
+    const CHILD_ENV: &str = "CPR_TEST_PROXY_TLS_DIRECTORY";
+    let Ok(directory) = std::env::var(CHILD_ENV) else {
+        let directory = tempfile::tempdir().unwrap();
+        generate_proxy_test_certificates(directory.path());
+        // 使用子进程隔离环境变量，避免并行测试读取到临时 CA 配置
+        for ca_env in ["CODEX_CA_CERTIFICATE", "SSL_CERT_FILE"] {
+            let mut child = Command::new(std::env::current_exe().unwrap());
+            child
+                .args([
+                    "--exact",
+                    "bootstrap::server::proxy_probe_should_use_provider_custom_ca_for_https_proxies",
+                    "--nocapture",
+                ])
+                .env(CHILD_ENV, directory.path())
+                .env_remove("CODEX_CA_CERTIFICATE")
+                .env_remove("SSL_CERT_FILE")
+                .env(ca_env, directory.path().join("ca.pem"));
+            if ca_env == "CODEX_CA_CERTIFICATE" {
+                child.env(
+                    "SSL_CERT_FILE",
+                    directory.path().join("missing-fallback.pem"),
+                );
+            }
+            let output = child.output().unwrap();
+            assert!(
+                output.status.success(),
+                "{ca_env}: {}\n{}",
+                String::from_utf8_lossy(&output.stdout),
+                String::from_utf8_lossy(&output.stderr)
+            );
+        }
+        return;
+    };
+    provider_openai::ensure_rustls_provider();
+    let directory = std::path::Path::new(&directory);
+    let certificate = CertificateDer::from_pem_file(directory.join("server.pem")).unwrap();
+    let key = PrivateKeyDer::from_pem_file(directory.join("server.key")).unwrap();
+    let acceptor = TlsAcceptor::from(Arc::new(
+        ServerConfig::builder()
+            .with_no_client_auth()
+            .with_single_cert(vec![certificate], key)
+            .unwrap(),
+    ));
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let proxy =
+        OutboundProxy::parse(&format!("https://{}", listener.local_addr().unwrap())).unwrap();
+    let server = tokio::spawn(async move {
+        let (socket, _) = listener.accept().await.unwrap();
+        let mut stream = acceptor.accept(socket).await.unwrap();
+        let mut request = Vec::new();
+        while !request.ends_with(b"\r\n\r\n") {
+            assert!(request.len() < 8192);
+            request.push(stream.read_u8().await.unwrap());
+        }
+        assert!(request.starts_with(b"GET http://unresolvable.invalid/ip "));
+        let body = "{\"ip\":\"203.0.113.8\"}";
+        stream.write_all(format!("HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", body.len()).as_bytes()).await.unwrap();
+        stream.shutdown().await.unwrap();
+    });
+    let probe = HttpProxyProbe::new("http://unresolvable.invalid/ip")
+        .with_client_builder(provider_openai::build_reqwest_client_with_custom_ca);
+    let result = probe.test(Some(&proxy), false).await;
+    assert!(result.success, "{}", result.message);
+    assert_eq!(result.exit_ip.unwrap().to_string(), "203.0.113.8");
+    tokio::time::timeout(Duration::from_secs(5), server)
+        .await
+        .unwrap()
+        .unwrap();
+}
+
+fn generate_proxy_test_certificates(directory: &std::path::Path) {
+    let openssl = |args: &[&str]| {
+        let output = Command::new("openssl")
+            .args(args)
+            .current_dir(directory)
+            .output()
+            .unwrap();
+        assert!(
+            output.status.success(),
+            "{}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    };
+    openssl(&[
+        "req",
+        "-x509",
+        "-newkey",
+        "rsa:2048",
+        "-nodes",
+        "-keyout",
+        "ca.key",
+        "-out",
+        "ca.pem",
+        "-days",
+        "1",
+        "-subj",
+        "/CN=Proxy Test CA",
+    ]);
+    openssl(&[
+        "req",
+        "-newkey",
+        "rsa:2048",
+        "-nodes",
+        "-keyout",
+        "server.key",
+        "-out",
+        "server.csr",
+        "-subj",
+        "/CN=localhost",
+    ]);
+    fs::write(directory.join("extensions"), "subjectAltName=IP:127.0.0.1\nbasicConstraints=critical,CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n").unwrap();
+    openssl(&[
+        "x509",
+        "-req",
+        "-in",
+        "server.csr",
+        "-CA",
+        "ca.pem",
+        "-CAkey",
+        "ca.key",
+        "-CAcreateserial",
+        "-out",
+        "server.pem",
+        "-days",
+        "1",
+        "-extfile",
+        "extensions",
+    ]);
+}

backend/apps/gateway/tests/main.rs

@@ -1,8 +1,10 @@
+//! 网关组合根测试入口，检查源码模块纪律与冻结的文件边界
+
 mod architecture;
 mod bootstrap;
 
-// 组合根是否混入业务策略由代码审查判断，行数和标识符/注释关键词不能证明职责越界。
-// 依赖 DAG、公开模块面和模块镜像继续由 architecture 检查，源码纪律由下方测试维护。
+// 组合根是否混入业务策略由代码审查判断，行数和标识符/注释关键词不能证明职责越界
+// 依赖 DAG、公开模块面和模块镜像继续由 architecture 检查，源码纪律由下方测试维护
 
 use std::{
     collections::BTreeSet,
@@ -18,7 +20,12 @@ fn app_tree_matches_frozen_terminal_manifest() {
     assert_eq!(
         rust_files(&root.join("src")),
         BTreeSet::from([
-            PathBuf::from("bootstrap.rs"),
+            PathBuf::from("bootstrap/command.rs"),
+            PathBuf::from("bootstrap/config.rs"),
+            PathBuf::from("bootstrap/mod.rs"),
+            PathBuf::from("bootstrap/plugins.rs"),
+            PathBuf::from("bootstrap/server.rs"),
+            PathBuf::from("bootstrap/startup.rs"),
             PathBuf::from("lib.rs"),
             PathBuf::from("main.rs"),
         ]),
@@ -27,7 +34,10 @@ fn app_tree_matches_frozen_terminal_manifest() {
         rust_files(&root.join("tests")),
         BTreeSet::from([
             PathBuf::from("architecture.rs"),
-            PathBuf::from("bootstrap.rs"),
+            PathBuf::from("bootstrap/command.rs"),
+            PathBuf::from("bootstrap/config.rs"),
+            PathBuf::from("bootstrap/mod.rs"),
+            PathBuf::from("bootstrap/server.rs"),
             PathBuf::from("main.rs"),
         ]),
     );
@@ -49,9 +59,16 @@ fn cargo_library_root_is_conventional_lib() {
 fn workspace_production_files_have_no_hidden_modules_or_test_hooks() {
     for member in architecture::WORKSPACE_MEMBERS {
         let root = architecture::backend_root().join(member).join("src");
-        for relative in rust_files(&root) {
+        let sources = rust_files(&root);
+        assert!(!sources.is_empty(), "{member} has no production sources");
+        for relative in sources {
             let path = root.join(relative);
             let source = fs::read_to_string(&path).expect("read production source");
+            assert!(
+                !source.contains("#[cfg(test)]"),
+                "{} hosts tests in production src",
+                path.display()
+            );
             assert!(
                 !source.contains("include!("),
                 "{} uses include!",

backend/apps/plugin-cli/README.md

@@ -8,10 +8,10 @@
 从仓库根目录安装到本地工具目录：
 
 ```bash
-cargo install --locked --path backend/apps/plugin-cli --root /path/to/local-tools
+cargo +1.99.1 install --locked --path backend/apps/plugin-cli --root /path/to/local-tools
 ```
 
-将 `/path/to/local-tools/bin` 加入 `PATH`，或使用可执行文件的完整路径
+将 `/path/to/local-tools/bin` 加入 `PATH`，或使用可执行文件的完整路径；工具链与宿主 [验证命令](../../../docs/architecture.md#验证命令)一致
 
 ## 打包
 
@@ -26,13 +26,15 @@ cpr-plugin package \
   --output-dir /path/to/output
 ```
 
-资源映射相对于作者清单所在目录解析。输出包括完整插件 ID、版本和目标 triple 命名的 `.tar.gz` 及 `.sha256`；归档根目录直接包含 `plugin.json`、可执行文件和已声明资源，不包含开发依赖
+`--resource-map web=web/dist` 将包内 `web/` 前缀映射到作者清单所在目录下的 `web/dist/`。
+可重复传入不同前缀，源目录必须位于项目内；没有对应资源时省略该参数，未使用的映射会被拒绝。
+未映射的资源按清单中的相对路径读取，只收集 `resources` 声明的文件
 
-作者清单可省略普通贡献项的 `id`、`version` 和固定阶段；`middleware` 必须显式声明版本 `3`，
-并从 `http`、`websocket`、`service`、`request`、`attempt` 中选择挂载阶段。
-CLI 与 SDK 的 `Manifest::from_author_slice`、`PluginBuilder::from_json` 共用规范化入口；归档中的
-`plugin.json` 写入补全后的贡献项字段，不保留另一份作者声明。
-完整规则见 [SDK 清单](../../crates/gateway-plugin/sdk/docs/manifest.md)
+输出为 `<插件 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`，补入协议版本、目标平台和文件摘要。打包成功只证明输入符合包合同，实际启动与能力仍需在目标宿主验证
 
 支持 `x86_64-unknown-linux-gnu`、`aarch64-unknown-linux-gnu` 和 `aarch64-apple-darwin`。
 完整开发示例在独立仓库 `codex-proxy-plugins` 的 `examples/workbench`，可通过[子模块](../../../docs/development.md#源码联调)检出；本工具不负责源码构建、上传或启用插件
@@ -48,6 +50,6 @@ CLI 与 SDK 的 `Manifest::from_author_slice`、`PluginBuilder::from_json` 共
 Rust 包名为 `codex-proxy-plugin-cli`，位于宿主的 `backend` workspace，共享工具链、锁文件和检查规则；内部仅依赖 `gateway-plugin-sdk`
 
 ```bash
-cargo run --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli -- package --help
-RUST_MIN_STACK=16777216 cargo +1.97.0 test --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked
+cargo +1.99.1 run --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked -- package --help
+RUST_MIN_STACK=16777216 cargo +1.99.1 test --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked
 ```

backend/apps/plugin-cli/src/main.rs

@@ -1,3 +1,5 @@
+//! 插件打包命令行，校验输入资源并生成带摘要的平台归档
+
 use std::{
     collections::{BTreeMap, BTreeSet},
     fs::{self, File, OpenOptions},

backend/apps/plugin-cli/tests/main.rs

@@ -1,3 +1,5 @@
+//! 插件打包命令行的参数、归档校验与输出行为测试
+
 use std::{
     collections::BTreeMap,
     fs::{self, File},
@@ -128,7 +130,7 @@ fn rejects_duplicate_resource_prefixes() {
 }
 
 #[test]
-fn packages_only_generated_resources_with_v3_metadata() {
+fn packages_only_generated_resources_with_current_metadata() {
     assert_packaged_resources("assets/icon.png", "image/png", b"png");
 }
 
@@ -248,8 +250,8 @@ fn source_manifest() -> &'static [u8] {
       "main":"bin/plugin",
       "runtime":"trustedProcess",
       "contributes":{
-        "middleware":{"version":3,"stages":["request"],"inputFormats":["openai"],"outputFormats":["openai"]},
-        "management":{}
+        "middleware":{"version":6,"stages":["request"],"inputFormats":["openai"],"outputFormats":["openai"]},
+        "management":{"version":2}
       },
 
       "icon":"assets/icon.png",

backend/crates/gateway-admin/Cargo.toml

@@ -21,6 +21,7 @@ futures = "0.3.32"
 gateway-core = { path = "../gateway-core" }
 heck = "0.5.0"
 hex = "0.4.3"
+hkdf = "0.13.0"
 rand_core = { version = "0.6.4", features = ["getrandom"] }
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
@@ -30,15 +31,15 @@ sha2 = "0.11"
 subtle = "2.6.1"
 thiserror = "2.0.18"
 tracing = "0.1.44"
-uuid = { version = "1.23.3", features = ["v7"] }
+uuid = { version = "1.23.3", features = ["v4", "v7"] }
 cron = "0.17"
 chrono-tz = "0.10"
 tokio = { version = "1.52", features = ["rt", "time", "macros", "sync"] }
 
 [dev-dependencies]
-prettyplease = "0.2"
+prettyplease = "0.3"
 quote = "1"
-syn = { version = "2", features = ["full", "visit-mut"] }
+syn = { version = "3", features = ["full", "visit-mut"] }
 tempfile = "3"
 tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt", "test-util"] }
 

backend/crates/gateway-admin/src/backup/mod.rs

@@ -1,4 +1,4 @@
-//! 备份纯策略与 Worker 任务。
+//! 备份纯策略与 Worker 任务
 
 pub mod policy;
 pub mod task;

backend/crates/gateway-admin/src/backup/policy.rs

@@ -1,6 +1,6 @@
-//! 备份纯策略：Cron 推进与保留候选。
+//! 备份纯策略：Cron 推进与保留候选
 //!
-//! 本模块不持有任何端口或对象，是 `BackupService` 与 `BackupTask` 共用的纯函数集。
+//! 本模块不持有任何端口或对象，是 `BackupService` 与 `BackupTask` 共用的纯函数集
 
 use std::str::FromStr;
 
@@ -10,10 +10,11 @@ use cron::Schedule;
 
 use crate::model::backup::{BackupError, BackupRecord, BackupStatus, code};
 
-/// 向历史回溯的最大范围（分钟）。覆盖 Feb 29 + 特定星期等罕见组合的最长间隔。
+/// 向历史回溯的最大范围（分钟）
+/// 覆盖 Feb 29 + 特定星期等罕见组合的最长间隔
 const MAX_BACKDATE_MINUTES: i64 = 40 * 366 * 24 * 60;
 
-/// 已解析并校验的备份计划。
+/// 已解析并校验的备份计划
 #[derive(Debug, Clone)]
 pub struct BackupSchedule {
     schedule: Schedule,
@@ -21,43 +22,44 @@ pub struct BackupSchedule {
 }
 
 impl BackupSchedule {
-    /// 解析并校验 5 段 Cron 与 IANA 时区。
+    /// 按部署时区解析并校验 5 段 Cron
     ///
     /// # Errors
     ///
-    /// Cron 非法或时区不是 IANA 名称时返回 [`BackupError`]。
-    pub fn parse(cron_expression: &str, schedule_timezone: &str) -> Result<Self, BackupError> {
+    /// Cron 非法时返回 [`BackupError`]
+    pub fn parse(
+        cron_expression: &str,
+        timezone: gateway_core::time::DeploymentTimeZone,
+    ) -> Result<Self, BackupError> {
         let expression = format!("0 {cron_expression}");
         let schedule = Schedule::from_str(&expression).map_err(|_| {
             BackupError::new(code::INVALID_CRON, "Cron 表达式必须是 5 段格式".to_owned())
         })?;
-        let timezone = schedule_timezone.parse::<Tz>().map_err(|_| {
-            BackupError::new(code::INVALID_TIMEZONE, "时区必须是 IANA 名称".to_owned())
-        })?;
-        Ok(Self { schedule, timezone })
+        Ok(Self {
+            schedule,
+            timezone: timezone.iana(),
+        })
     }
 
-    /// 返回最接近 `at`（含 `at` 所在分钟）的最近一次触发时间。
+    /// 返回最接近 `at`（含 `at` 所在分钟）的最近一次触发时间
     ///
     /// 若过去 `MAX_BACKDATE_MINUTES` 内没有任何触发（极罕见的稀疏计划或超长停机），
-    /// 返回 `None`，调用方不应为历史点补任务。
+    /// 返回 `None`，调用方不应为历史点补任务
     #[must_use]
     pub fn last_firing_at_or_before(&self, at: DateTime<Utc>) -> Option<DateTime<Utc>> {
         let high_min = at.timestamp().div_euclid(60);
         let low_min = high_min.saturating_sub(MAX_BACKDATE_MINUTES);
 
-        // 检查窗口内是否存在触发；不存在则直接返回 None。
+        // 检查窗口内是否存在触发；不存在则直接返回 None
         let low_instant = instant(low_min, self.timezone)?;
         if self
-            .schedule
-            .after(&low_instant)
-            .next()
+            .next_after(low_instant.to_utc())
             .is_none_or(|firing| firing.timestamp() > high_min * 60 + 59)
         {
             return None;
         }
 
-        // 二分查找最小的 u（分钟）使 after(u) > high；prev = after(u - 1 分钟)。
+        // 二分查找最小的 u（分钟）使 after(u) > high；prev = after(u - 1 分钟)
         let mut lo = low_min;
         let mut hi = high_min;
         while lo < hi {
@@ -76,54 +78,56 @@ impl BackupSchedule {
             .and_then(|firing| Utc.timestamp_opt(firing * 60, 0).single())
     }
 
-    /// 返回第一个严格晚于 `at` 的触发时间。
+    /// 返回第一个严格晚于 `at` 的触发时间
     #[must_use]
     pub fn next_after(&self, at: DateTime<Utc>) -> Option<DateTime<Utc>> {
-        let local = at.with_timezone(&self.timezone);
-        self.schedule
-            .after(&local)
-            .next()
-            .map(|firing| firing.with_timezone(&Utc))
+        let local = at.with_timezone(&self.timezone).naive_local().and_utc();
+        self.schedule.after(&local).find_map(|firing| {
+            let instant = self
+                .timezone
+                .from_local_datetime(&firing.naive_utc())
+                .earliest()?
+                .to_utc();
+            (instant > at).then_some(instant)
+        })
     }
 
-    /// `after(u 分钟)` 返回的第一个触发时间（分钟索引），用于二分搜索。
+    /// `after(u 分钟)` 返回的第一个触发时间（分钟索引），用于二分搜索
     fn firing_after(&self, minute_index: i64) -> Option<i64> {
-        let instant = instant(minute_index, self.timezone)?;
-        self.schedule
-            .after(&instant)
-            .next()
+        let instant = instant(minute_index, self.timezone)?.to_utc();
+        self.next_after(instant)
             .map(|firing| firing.timestamp().div_euclid(60))
     }
 }
 
-/// 构造指定分钟索引（UTC epoch 分钟）在目标时区下的 `DateTime`。
+/// 构造指定分钟索引（UTC epoch 分钟）在目标时区下的 `DateTime`
 fn instant(minute_index: i64, timezone: Tz) -> Option<DateTime<Tz>> {
     timezone.timestamp_opt(minute_index * 60, 0).single()
 }
 
-/// 一条记录被纳入删除流程的原因。
+/// 一条记录被纳入删除流程的原因
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum RetentionReason {
-    /// 超过 `retention_days`。
+    /// 超过 `retention_days`
     Days,
-    /// 超过 `retention_count`。
+    /// 超过 `retention_count`
     Count,
 }
 
-/// 保留决策。
+/// 保留决策
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct RetentionDecision {
     pub record_id: String,
     pub reason: RetentionReason,
 }
 
-/// 从按完成时间倒序的 completed 计划备份中决定纳入删除流程的记录。
+/// 从按完成时间倒序的 completed 计划备份中决定纳入删除流程的记录
 ///
 /// 自动保留规则：
-/// - `retentionDays = 0` 时不按天数清理；`retentionCount = 0` 时不按份数清理。
-/// - 自动计划备份满足任一启用阈值即可进入删除。
-/// - 无论阈值如何，至少保留最近一个成功的计划备份（倒序下标 0）。
-/// - 手动备份不进入本规则；手工/计划记录各自的 `expires_at` 由到期扫描处理。
+/// - `retentionDays = 0` 时不按天数清理；`retentionCount = 0` 时不按份数清理
+/// - 自动计划备份满足任一启用阈值即可进入删除
+/// - 无论阈值如何，至少保留最近一个成功的计划备份（倒序下标 0）
+/// - 手动备份不进入本规则；手工/计划记录各自的 `expires_at` 由到期扫描处理
 #[must_use]
 pub fn decide_retention(
     retention_days: u32,
@@ -136,7 +140,7 @@ pub fn decide_retention(
         if record.status != BackupStatus::Completed {
             continue;
         }
-        // 最近一个成功的计划备份永远保留。
+        // 最近一个成功的计划备份永远保留
         if index == 0 {
             continue;
         }

backend/crates/gateway-admin/src/backup/task.rs

@@ -1,7 +1,8 @@
-//! Backup Worker 贡献：单个可取消 `DaemonTask` 承担调度、执行、删除收敛与保留清理。
+//! Backup Worker 贡献：单个可取消 `DaemonTask` 承担调度、执行、删除收敛与保留清理
 //!
-//! 当前部署边界是单副本，因此不需要 Redis lease、fencing token 或 heartbeat。长时间
-//! `pg_dump` 与上传由本 Daemon 自身持有；Host 只负责 panic 后重启、健康与关闭。
+//! 当前部署边界是单副本，因此不需要 Redis lease、fencing token 或 heartbeat
+//! 长时间
+//! `pg_dump` 与上传由本 Daemon 自身持有；Host 只负责 panic 后重启、健康与关闭
 
 use std::sync::Arc;
 use std::time::Duration;
@@ -10,7 +11,7 @@ use chrono::{DateTime, Utc};
 use futures::future::BoxFuture;
 use gateway_core::{
     lifecycle::CancellationToken,
-    task::{DaemonTask, WorkerTaskError},
+    task::{DaemonTask, WorkerDaemonContext, WorkerTaskError},
 };
 use tracing::{info, warn};
 
@@ -27,30 +28,31 @@ use crate::{
 
 impl From<BackupError> for WorkerTaskError {
     fn from(error: BackupError) -> Self {
-        WorkerTaskError::safe(error.message())
+        WorkerTaskError::safe(error.message()).with_source(error)
     }
 }
 
 use super::policy::{BackupSchedule, decide_retention};
 
-/// 循环间隔：管理员修改 Cron 后该时长内生效；无工作时可取消等待。
+/// 循环间隔：管理员修改 Cron 后该时长内生效；无工作时可取消等待
 const BACKUP_LOOP_INTERVAL: Duration = Duration::from_secs(30);
-/// 每个循环最多执行的保留删除数量。
+/// 每个循环最多执行的保留删除数量
 const RETENTION_BATCH_SIZE: usize = 10;
-/// 保留扫描一次读取的 completed 计划备份上限。
+/// 保留扫描一次读取的 completed 计划备份上限
 const RETENTION_SCAN_LIMIT: u32 = 1000;
-/// 每个循环最多完成的待删除记录数量。
+/// 每个循环最多完成的待删除记录数量
 const PENDING_DELETION_BATCH: u32 = 20;
 
-/// 备份 Daemon 任务。
+/// 备份 Daemon 任务
 pub struct BackupTask {
+    timezone: gateway_core::time::DeploymentTimeZone,
     repository: Arc<dyn BackupRepository>,
     dump: Arc<dyn DatabaseDumpPort>,
     object_store: Arc<dyn BackupObjectStorePort>,
 }
 
 impl BackupTask {
-    /// 组合仓储、导出器与对象存储适配器。
+    /// 组合仓储、导出器与对象存储适配器
     #[must_use]
     pub fn new(
         repository: Arc<dyn BackupRepository>,
@@ -58,26 +60,35 @@ impl BackupTask {
         object_store: Arc<dyn BackupObjectStorePort>,
     ) -> Self {
         Self {
+            timezone: Default::default(),
             repository,
             dump,
             object_store,
         }
     }
+
+    #[must_use]
+    pub fn with_timezone(mut self, timezone: gateway_core::time::DeploymentTimeZone) -> Self {
+        self.timezone = timezone;
+        self
+    }
 }
 
 impl DaemonTask for BackupTask {
-    fn run(&self, cancellation: CancellationToken) -> BoxFuture<'_, Result<(), WorkerTaskError>> {
-        Box::pin(async move { self.run_daemon(cancellation).await })
+    fn run(&self, context: WorkerDaemonContext) -> BoxFuture<'_, Result<(), WorkerTaskError>> {
+        Box::pin(async move { self.run_daemon(context).await })
     }
 }
 
 impl BackupTask {
-    async fn run_daemon(&self, cancellation: CancellationToken) -> Result<(), WorkerTaskError> {
+    async fn run_daemon(&self, context: WorkerDaemonContext) -> Result<(), WorkerTaskError> {
+        let cancellation = context.cancellation();
         loop {
             if cancellation.is_cancelled() {
                 return Ok(());
             }
-            self.run_cycle(&cancellation).await?;
+            self.run_cycle(cancellation).await?;
+            context.succeeded();
 
             tokio::select! {
                 _ = cancellation.cancelled() => return Ok(()),
@@ -86,13 +97,13 @@ impl BackupTask {
         }
     }
 
-    /// 执行一个周期：推进计划、恢复中间态、删除收敛、领取执行一个任务、保留清理。
+    /// 执行一个周期：推进计划、恢复中间态、删除收敛、领取执行一个任务、保留清理
     ///
-    /// 对外暴露以便集成测试逐周期驱动；daemon 循环内部复用。
+    /// 对外暴露以便集成测试逐周期驱动；daemon 循环内部复用
     ///
     /// # Errors
     ///
-    /// 仓储或基础设施不可用、任务执行失败时返回 [`WorkerTaskError`]。
+    /// 仓储或基础设施不可用、任务执行失败时返回 [`WorkerTaskError`]
     pub async fn run_cycle(&self, cancellation: &CancellationToken) -> Result<(), WorkerTaskError> {
         if cancellation.is_cancelled() {
             return Ok(());
@@ -105,29 +116,52 @@ impl BackupTask {
         Ok(())
     }
 
-    /// 推进到期计划并幂等插入 scheduled 任务。
+    /// 推进到期计划并幂等插入 scheduled 任务
     async fn advance_schedule(&self, now: DateTime<Utc>) -> Result<(), WorkerTaskError> {
         let settings = self.repository.load_settings().await.map_err(repo_error)?;
         if !settings.schedule_enabled {
             return Ok(());
         }
         let cron = settings.cron_expression.as_deref().unwrap_or_default();
-        let timezone = settings.schedule_timezone.as_deref().unwrap_or_default();
-        if cron.is_empty() || timezone.is_empty() {
+        let timezone = self.timezone.name();
+        if cron.is_empty() {
             return Ok(());
         }
-        let schedule = BackupSchedule::parse(cron, timezone)
-            .map_err(|_| WorkerTaskError::safe("backup schedule is invalid"))?;
+        let schedule = BackupSchedule::parse(cron, self.timezone).map_err(|source| {
+            WorkerTaskError::safe("backup schedule is invalid").with_source(source)
+        })?;
 
+        if settings.schedule_timezone.as_deref() != Some(timezone) {
+            // 时区切换只初始化未来游标，不把旧时区计划当作应补跑任务
+            if let Some(next_run_at) = schedule.next_after(now) {
+                self.repository
+                    .advance_schedule_cursor(
+                        next_run_at,
+                        cron,
+                        settings.schedule_timezone.as_deref(),
+                        settings.next_run_at,
+                        timezone,
+                    )
+                    .await
+                    .map_err(repo_error)?;
+            }
+            return Ok(());
+        }
         let due = match settings.next_run_at {
             Some(next_run_at) if next_run_at <= now => true,
             Some(_) => false,
             None => {
-                // 刚启用计划但尚无游标：直接初始化。
+                // 刚启用计划但尚无游标：直接初始化
                 if let Some(next_run_at) = schedule.next_after(now) {
                     let _ = self
                         .repository
-                        .advance_schedule_cursor(next_run_at, cron, timezone)
+                        .advance_schedule_cursor(
+                            next_run_at,
+                            cron,
+                            Some(timezone),
+                            settings.next_run_at,
+                            timezone,
+                        )
                         .await
                         .map_err(repo_error)?;
                 }
@@ -141,11 +175,17 @@ impl BackupTask {
         let scheduled_at = match schedule.last_firing_at_or_before(now) {
             Some(scheduled_at) => scheduled_at,
             None => {
-                // 无法从计划推导最近到期时间：推进游标避免反复触发。
+                // 无法从计划推导最近到期时间：推进游标避免反复触发
                 if let Some(next_run_at) = schedule.next_after(now) {
                     let _ = self
                         .repository
-                        .advance_schedule_cursor(next_run_at, cron, timezone)
+                        .advance_schedule_cursor(
+                            next_run_at,
+                            cron,
+                            Some(timezone),
+                            settings.next_run_at,
+                            timezone,
+                        )
                         .await
                         .map_err(repo_error)?;
                 }
@@ -168,25 +208,24 @@ impl BackupTask {
         .map_err(infra_error)?;
         let inserted = self
             .repository
-            .insert_scheduled_record(seed)
+            .insert_scheduled_record(
+                seed,
+                schedule.next_after(now),
+                cron,
+                timezone,
+                settings.next_run_at,
+            )
             .await
             .map_err(repo_error)?;
         if inserted {
             info!(scheduled_at = %scheduled_at, "计划备份任务已创建");
         } else {
-            warn!(scheduled_at = %scheduled_at, "计划时间点冲突，跳过并推进游标");
-        }
-        if let Some(next_run_at) = schedule.next_after(now) {
-            let _ = self
-                .repository
-                .advance_schedule_cursor(next_run_at, cron, timezone)
-                .await
-                .map_err(repo_error)?;
+            warn!(scheduled_at = %scheduled_at, "计划已变化或存在冲突，本轮未创建任务");
         }
         Ok(())
     }
 
-    /// 恢复中间状态（dumping/uploading/deleting）。
+    /// 恢复中间状态（dumping/uploading/deleting）
     async fn recover_intermediate(
         &self,
         cancellation: &CancellationToken,
@@ -206,7 +245,7 @@ impl BackupTask {
         Ok(())
     }
 
-    /// dumping：有完整暂存则继续上传，否则清理暂存并标记失败。
+    /// dumping：有完整暂存则继续上传，否则清理暂存并标记失败
     async fn recover_dumping(
         &self,
         record: &BackupRecord,
@@ -244,7 +283,6 @@ impl BackupTask {
                 .await?;
             }
             None => {
-                let _ = self.dump.cleanup_staging(&record.id).await;
                 self.fail_task(record, code::PG_DUMP_FAILED, "导出进程中断，暂存归档不完整")
                     .await?;
             }
@@ -252,7 +290,7 @@ impl BackupTask {
         Ok(())
     }
 
-    /// uploading：远端匹配则补记完成，有完整暂存则重试上传，否则失败。
+    /// uploading：远端匹配则补记完成，有完整暂存则重试上传，否则失败
     async fn recover_uploading(
         &self,
         record: &BackupRecord,
@@ -270,7 +308,8 @@ impl BackupTask {
             && record.sha256.as_deref() == Some(remote.sha256.as_str())
         {
             let now = Utc::now();
-            self.repository
+            if self
+                .repository
                 .transition_status(
                     &record.id,
                     status_transition(BackupStatus::Uploading, BackupStatus::Completed)?,
@@ -278,7 +317,11 @@ impl BackupTask {
                     now,
                 )
                 .await
-                .map_err(repo_error)?;
+                .map_err(repo_error)?
+                .is_some()
+            {
+                self.cleanup_staging(&record.id).await;
+            }
             return Ok(());
         }
         match self.dump.inspect_staging(&record.id).await? {
@@ -304,7 +347,7 @@ impl BackupTask {
         }
     }
 
-    /// 完成待删除记录（deleting → DeleteObject → 硬删除）。
+    /// 完成待删除记录（deleting → DeleteObject → 硬删除）
     async fn finish_pending_deletions(&self) -> Result<(), WorkerTaskError> {
         let settings = self.repository.load_settings().await.map_err(repo_error)?;
         let Some(config) = BackupStorageConfig::from_settings(&settings) else {
@@ -331,7 +374,7 @@ impl BackupTask {
         Ok(())
     }
 
-    /// 领取一个 queued 任务并执行导出、上传与远端校验。
+    /// 领取一个 queued 任务并执行导出、上传与远端校验
     async fn process_next_task(
         &self,
         cancellation: &CancellationToken,
@@ -356,7 +399,7 @@ impl BackupTask {
         Ok(())
     }
 
-    /// 执行单个任务；内部处理全部状态迁移。
+    /// 执行单个任务；内部处理全部状态迁移
     async fn execute_task(
         &self,
         record: &BackupRecord,
@@ -390,7 +433,7 @@ impl BackupTask {
             }
         };
 
-        // dumping → uploading，持久化 size/sha256。
+        // dumping → uploading，持久化 size/sha256
         let update = StatusTransitionUpdate {
             size_bytes: Some(artifact.size_bytes),
             sha256: Some(artifact.sha256.clone()),
@@ -418,12 +461,10 @@ impl BackupTask {
             now,
             cancellation,
         )
-        .await?;
-        let _ = self.dump.cleanup_staging(&record.id).await;
-        Ok(())
+        .await
     }
 
-    /// 上传 + 远端校验，内部完成终态迁移。
+    /// 上传 + 远端校验，内部完成终态迁移
     async fn upload_and_verify(
         &self,
         record: &BackupRecord,
@@ -452,11 +493,13 @@ impl BackupTask {
             )
             .await
         {
-            let _ = store.delete_object(&config, &record.object_key).await;
-            self.fail_task(
+            self.fail_uploaded_task(
                 record,
-                error.code(),
-                format!("上传到对象存储失败：{}", error.message()),
+                &config,
+                BackupError::new(
+                    error.code(),
+                    format!("上传到对象存储失败：{}", error.message()),
+                ),
             )
             .await?;
             return Ok(());
@@ -481,6 +524,7 @@ impl BackupTask {
                         size_bytes,
                         "备份完成"
                     );
+                    self.cleanup_staging(&record.id).await;
                 }
             }
             Ok(Some(remote)) => {
@@ -493,16 +537,19 @@ impl BackupTask {
                     sha256_matches,
                     "备份远端对象校验不一致"
                 );
-                let _ = store.delete_object(&config, &record.object_key).await;
-                self.fail_task(
+                self.fail_uploaded_task(
                     record,
-                    code::REMOTE_VERIFICATION_FAILED,
-                    match (size_matches, sha256_matches) {
-                        (false, true) => "远端对象大小不一致",
-                        (true, false) => "远端对象 sha256 校验值不一致",
-                        (false, false) => "远端对象大小和 sha256 校验值均不一致",
-                        (true, true) => "远端对象校验状态异常",
-                    },
+                    &config,
+                    BackupError::new(
+                        code::REMOTE_VERIFICATION_FAILED,
+                        match (size_matches, sha256_matches) {
+                            (false, true) => "远端对象大小不一致",
+                            (true, false) => "远端对象 sha256 校验值不一致",
+                            (false, false) => "远端对象大小和 sha256 校验值均不一致",
+                            (true, true) => "远端对象校验状态异常",
+                        }
+                        .to_owned(),
+                    ),
                 )
                 .await?;
             }
@@ -516,11 +563,13 @@ impl BackupTask {
                 .await?;
             }
             Err(error) => {
-                let _ = store.delete_object(&config, &record.object_key).await;
-                self.fail_task(
+                self.fail_uploaded_task(
                     record,
-                    error.code(),
-                    format!("远端对象校验失败：{}", error.message()),
+                    &config,
+                    BackupError::new(
+                        error.code(),
+                        format!("远端对象校验失败：{}", error.message()),
+                    ),
                 )
                 .await?;
             }
@@ -528,7 +577,25 @@ impl BackupTask {
         Ok(())
     }
 
-    /// 把活跃任务写入失败终态并清理暂存。
+    /// 清理失败并入原终态，后续清理沿用备份记录的到期策略
+    async fn fail_uploaded_task(
+        &self,
+        record: &BackupRecord,
+        config: &BackupStorageConfig,
+        mut error: BackupError,
+    ) -> Result<(), WorkerTaskError> {
+        if let Err(cleanup) = self
+            .object_store
+            .delete_object(config, &record.object_key)
+            .await
+        {
+            error =
+                error.with_cleanup_failure("DeleteObject", &cleanup, record.expires_at.is_some());
+        }
+        self.fail_task(record, error.code(), error.message()).await
+    }
+
+    /// 把活跃任务写入失败终态并清理暂存
     async fn fail_task(
         &self,
         record: &BackupRecord,
@@ -559,15 +626,21 @@ impl BackupTask {
             )
             .await
             .map_err(repo_error)?;
-        let _ = self.dump.cleanup_staging(&record.id).await;
+        self.cleanup_staging(&record.id).await;
         Ok(())
     }
 
-    /// 执行一小批到期保留清理：先处理 `expires_at` 已到期的记录，再按天数/份数清理计划备份。
+    async fn cleanup_staging(&self, backup_id: &str) {
+        if let Err(error) = self.dump.cleanup_staging(backup_id).await {
+            warn!(backup_id, error = %error, "清理备份暂存失败");
+        }
+    }
+
+    /// 执行一小批到期保留清理：先处理 `expires_at` 已到期的记录，再按天数/份数清理计划备份
     async fn run_retention_batch(&self, now: DateTime<Utc>) -> Result<(), WorkerTaskError> {
         let settings = self.repository.load_settings().await.map_err(repo_error)?;
 
-        // 1. expires_at 已到期的记录（手动或计划）无条件进入删除。
+        // 1. expires_at 已到期的记录（手动或计划）无条件进入删除
         let expired = self
             .repository
             .list_expired_records(RETENTION_BATCH_SIZE as u32)
@@ -576,7 +649,7 @@ impl BackupTask {
         for record in expired {
             let Some(record) = self
                 .repository
-                .transition_to_deleting(&record.id, now)
+                .transition_to_deleting(&record.id, now, None)
                 .await
                 .map_err(repo_error)?
             else {
@@ -585,7 +658,7 @@ impl BackupTask {
             self.finalize_deletion(&record).await?;
         }
 
-        // 2. 计划备份按 retentionDays / retentionCount 清理。
+        // 2. 计划备份按 retentionDays / retentionCount 清理
         let records = self
             .repository
             .list_scheduled_completed_desc(RETENTION_SCAN_LIMIT)
@@ -600,7 +673,7 @@ impl BackupTask {
         for decision in decisions.into_iter().take(RETENTION_BATCH_SIZE) {
             let Some(record) = self
                 .repository
-                .transition_to_deleting(&decision.record_id, now)
+                .transition_to_deleting(&decision.record_id, now, None)
                 .await
                 .map_err(repo_error)?
             else {
@@ -611,7 +684,7 @@ impl BackupTask {
         Ok(())
     }
 
-    /// 对已进入 deleting 的记录执行对象删除并硬删除记录行。
+    /// 对已进入 deleting 的记录执行对象删除并硬删除记录行
     async fn finalize_deletion(&self, record: &BackupRecord) -> Result<(), WorkerTaskError> {
         let settings = self.repository.load_settings().await.map_err(repo_error)?;
         let Some(config) = BackupStorageConfig::from_settings(&settings) else {
@@ -635,6 +708,10 @@ impl BackupTask {
 fn classify_dump_error(error: BackupError) -> (&'static str, &'static str) {
     match error.code() {
         code::CANCELLED => (code::CANCELLED, "备份已取消"),
+        code::ANALYTICS_NOT_READY => (
+            code::ANALYTICS_NOT_READY,
+            "用量统计正在重建，请在统计就绪后重试备份",
+        ),
         code::STAGING_SPACE_EXHAUSTED => (code::STAGING_SPACE_EXHAUSTED, "暂存磁盘空间不足"),
         _ => (code::PG_DUMP_FAILED, "数据库导出失败"),
     }
@@ -649,9 +726,9 @@ fn status_transition(
 }
 
 fn repo_error(error: crate::ports::store::AdminStoreError) -> WorkerTaskError {
-    WorkerTaskError::safe(format!("backup store failed: {error}"))
+    WorkerTaskError::safe("backup store failed").with_source(error)
 }
 
 fn infra_error(error: BackupError) -> WorkerTaskError {
-    WorkerTaskError::safe(error.message())
+    WorkerTaskError::safe(error.message()).with_source(error)
 }

backend/crates/gateway-admin/src/freeze_recovery.rs

@@ -1,8 +1,9 @@
-//! 容量熔断冻结的恢复编排：到期探测、失败顺延与自适应并发下调。
+//! 容量熔断冻结的恢复编排：到期探测、失败顺延与自适应并发下调
 //!
 //! 冻结事实保存在可丢失的 Redis 冷却中，本服务只组合 Admin 端口：
 //! 观测（`AccountRuntimeStore`）、探测（`AccountsService`）与写回
-//! （原子降低并发 / 按冻结代次结束探测）。旧观测不会覆盖管理员操作。
+//! （原子降低并发 / 按冻结代次结束探测）
+//! 旧观测不会覆盖管理员操作
 
 use std::collections::BTreeMap;
 use std::sync::Arc;
@@ -22,21 +23,21 @@ use crate::model::{MutationActor, MutationContext};
 use crate::ports::store::{AccountRuntimeStore, AccountStore, SettingsStore};
 use crate::use_case::accounts::AccountsService;
 
-/// 自适应并发下调保留系数：下调到观测在途峰值的 80%。
+/// 自适应并发下调保留系数：下调到观测在途峰值的 80%
 const ADAPTIVE_CONCURRENCY_FACTOR: f64 = 0.8;
-/// 自适应并发下限：过低的并发让账号几乎不可用，宁可保持冻结。
+/// 自适应并发下限：过低的并发让账号几乎不可用，宁可保持冻结
 const ADAPTIVE_CONCURRENCY_FLOOR: u32 = 2;
-/// worker 周期；冷却观测与探测都依赖该节奏。
+/// worker 周期；冷却观测与探测都依赖该节奏
 pub const FREEZE_RECOVERY_INTERVAL: Duration = Duration::from_secs(30);
 pub const FREEZE_RECOVERY_WORKER_OWNER: &str = "account-freeze-recovery";
 pub const WORKER_INITIAL_BACKOFF: Duration = Duration::from_secs(1);
 pub const WORKER_MAXIMUM_BACKOFF: Duration = Duration::from_secs(60);
 pub const WORKER_LEASE_TTL: Duration = Duration::from_secs(15 * 60);
 pub const WORKER_LEASE_RENEWAL: Duration = Duration::from_secs(5 * 60);
-/// 系统审计上下文的固定请求 ID；账号并发更新审计由此溯源到自动冻结编排。
+/// 系统审计上下文的固定请求 ID；账号并发更新审计由此溯源到自动冻结编排
 const SYSTEM_REQUEST_ID: &str = "account-freeze-recovery";
 
-/// 冻结恢复所需的管理端口组合。
+/// 冻结恢复所需的管理端口组合
 #[derive(Clone)]
 pub struct FreezeRecoveryDeps {
     pub accounts: Arc<dyn AccountsService>,
@@ -61,17 +62,17 @@ impl FreezeRecoveryTask {
         }
     }
 
-    /// 读取冻结策略；读取或校验失败跳过本轮，不能把未知配置当作允许解冻。
+    /// 读取冻结策略；读取或校验失败跳过本轮，不能把未知配置当作允许解冻
     async fn freeze_policy(&self) -> Option<gateway_core::provider_ports::ProviderFreezePolicy> {
         let settings = self.deps.settings.load_runtime_settings().await.ok()?;
         gateway_core::provider_ports::ProviderFreezePolicy::try_new(
-            settings.account_auto_freeze_enabled,
-            settings.account_auto_freeze_threshold,
-            settings.account_auto_freeze_window_seconds,
-            settings.account_auto_freeze_duration_seconds,
-            settings.account_auto_freeze_probe_enabled,
-            settings.account_auto_freeze_probe_model,
-            settings.account_auto_freeze_adaptive_concurrency,
+            settings.values.account_auto_freeze_enabled,
+            settings.values.account_auto_freeze_threshold,
+            settings.values.account_auto_freeze_window_seconds,
+            settings.values.account_auto_freeze_duration_seconds,
+            settings.values.account_auto_freeze_probe_enabled,
+            settings.values.account_auto_freeze_probe_model,
+            settings.values.account_auto_freeze_adaptive_concurrency,
         )
         .ok()
     }
@@ -95,7 +96,7 @@ impl FreezeRecoveryTask {
     }
 
     /// 对冻结中的账号执行自适应并发下调：目标为观测在途峰值的 80%（下限 2），
-    /// 只降不升；未观测到峰值证据的账号保持现状。
+    /// 只降不升；未观测到峰值证据的账号保持现状
     async fn adapt_concurrency_limits(
         &self,
         freezes: &BTreeMap<String, AccountFreeze>,
@@ -146,7 +147,7 @@ impl FreezeRecoveryTask {
             .ok()
     }
 
-    /// 到达探测时间后才恢复；关闭自动冻结或探测时，已有冻结仍等待原冷却结束。
+    /// 到达探测时间后才恢复；关闭自动冻结或探测时，已有冻结仍等待原冷却结束
     async fn recover_due_freezes(
         &self,
         freezes: &BTreeMap<String, AccountFreeze>,
@@ -179,14 +180,14 @@ impl FreezeRecoveryTask {
             return;
         };
         if !item.account.enabled {
-            // 停用账号没有自动恢复意义；解冻交给管理员手动恢复。
+            // 停用账号没有自动恢复意义；解冻交给管理员手动恢复
             return;
         }
         let Ok(account) = ProviderAccountId::new(account_id.to_owned()) else {
             return;
         };
         let Some(model) = self.resolve_probe_model(&account, policy).await else {
-            // 没有可用探测模型时按失败处理，顺延冻结等待下一轮。
+            // 没有可用探测模型时按失败处理，顺延冻结等待下一轮
             self.postpone(&account, freeze, policy).await;
             return;
         };
@@ -218,7 +219,7 @@ impl FreezeRecoveryTask {
         }
     }
 
-    /// 探测失败只顺延本次仍存在的冻结，旧探测不能重新冻结已手动恢复的账号。
+    /// 探测失败只顺延本次仍存在的冻结，旧探测不能重新冻结已手动恢复的账号
     async fn postpone(
         &self,
         account: &ProviderAccountId,
@@ -281,7 +282,7 @@ impl ScheduledTask for FreezeRecoveryTask {
     }
 }
 
-/// 自适应目标并发：观测峰值 × 0.8 向下取整，下限 2；无证据（峰值为 0）不调整。
+/// 自适应目标并发：观测峰值 × 0.8 向下取整，下限 2；无证据（峰值为 0）不调整
 fn adaptive_target(peak_in_flight: u32) -> Option<u32> {
     if peak_in_flight == 0 {
         return None;
@@ -290,7 +291,7 @@ fn adaptive_target(peak_in_flight: u32) -> Option<u32> {
     Some(scaled.max(ADAPTIVE_CONCURRENCY_FLOOR))
 }
 
-/// 消耗连接测试事件流并返回是否以 `Completed` 终止。
+/// 消耗连接测试事件流并返回是否以 `Completed` 终止
 async fn drain_probe(mut events: crate::model::accounts::AccountConnectionTestEventStream) -> bool {
     let mut completed = false;
     while let Some(event) = events.next().await {

backend/crates/gateway-admin/src/lib.rs

@@ -1,6 +1,6 @@
-//! 管理控制面的语义模型、用例与外部能力端口。
+//! 管理控制面的语义模型、用例与外部能力端口
 //!
-//! 本 crate 不包含 HTTP wire、数据库实现或具体 Provider 实现。
+//! 本 crate 不包含 HTTP wire、数据库实现或具体 Provider 实现
 
 use std::{fmt, path::Path, sync::Arc, time::Duration};
 
@@ -20,7 +20,8 @@ pub mod backup;
 pub mod freeze_recovery;
 pub mod model;
 pub mod ports;
-pub mod service;
+pub mod public_service;
+mod reset_credit_automation;
 mod use_case;
 pub use use_case::plugins::{PluginDistributionPorts, PluginManagementService, PluginsService};
 
@@ -35,10 +36,11 @@ pub use use_case::{
     client_keys::ClientKeyService,
     credentials::{CredentialsService, ProviderCredentials},
     import_tasks::ImportTasksService,
-    observability::ObservabilityService,
+    observability::{ObservabilityService, ProviderUsageBillingProjector},
     proxies::ProxiesService,
     settings::SettingsService,
     system::SystemService,
+    usage_data::UsageDataService,
 };
 
 use model::AdminError;
@@ -70,7 +72,7 @@ const WEAK_ADMIN_PASSWORDS: &[&str] = &[
 const BACKUP_WORKER_OWNER: &str = "backup";
 const DEFAULT_CLIENT_SESSION_TTL_MINUTES: u64 = 24 * 60;
 
-/// 只用于首次幂等创建默认管理员的启动密码。
+/// 只用于首次幂等创建默认管理员的启动密码
 #[derive(Clone, Deserialize)]
 #[serde(transparent)]
 pub struct InitialAdminPassword(SecretString);
@@ -100,15 +102,21 @@ impl fmt::Debug for InitialAdminPassword {
     }
 }
 
-/// 管理控制面的启动配置。
+/// 管理控制面的启动配置
 #[derive(Clone, Deserialize, PartialEq, Eq)]
 pub struct AdminConfig {
     pub session_ttl_minutes: u64,
+    #[serde(default = "default_absolute_session_ttl_minutes")]
+    pub session_absolute_ttl_minutes: u64,
     pub default_username: String,
     pub default_password: InitialAdminPassword,
 }
 
-/// Client 登录域的通用启动配置。
+fn default_absolute_session_ttl_minutes() -> u64 {
+    30 * 24 * 60
+}
+
+/// Client 登录域的通用启动配置
 #[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
 pub struct ClientConfig {
     pub session_ttl_minutes: u64,
@@ -123,11 +131,11 @@ impl Default for ClientConfig {
 }
 
 impl ClientConfig {
-    /// 校验 Client session TTL；当前配置不含相对路径。
+    /// 校验 Client session TTL；当前配置不含相对路径
     ///
     /// # Errors
     ///
-    /// 会话有效期为零或无法安全换算时返回错误。
+    /// 会话有效期为零或无法安全换算时返回错误
     pub fn resolve_and_validate(&mut self, _source_dir: &Path) -> Result<(), AdminConfigError> {
         if self.session_ttl_minutes == 0 || i64::try_from(self.session_ttl_minutes).is_err() {
             return Err(AdminConfigError::InvalidField("client.session_ttl_minutes"));
@@ -137,11 +145,11 @@ impl ClientConfig {
 }
 
 impl AdminConfig {
-    /// 校验 Admin-owned 字段；当前配置不含相对路径。
+    /// 校验 Admin-owned 字段；当前配置不含相对路径
     ///
     /// # Errors
     ///
-    /// 用户名、会话有效期或初始密码不满足安全约束时返回错误。
+    /// 用户名、会话有效期或初始密码不满足安全约束时返回错误
     pub fn resolve_and_validate(&mut self, _source_dir: &Path) -> Result<(), AdminConfigError> {
         if self.default_username.trim().is_empty()
             || self.default_username.chars().any(char::is_control)
@@ -151,6 +159,13 @@ impl AdminConfig {
         if self.session_ttl_minutes == 0 || i64::try_from(self.session_ttl_minutes).is_err() {
             return Err(AdminConfigError::InvalidField("admin.session_ttl_minutes"));
         }
+        if self.session_absolute_ttl_minutes == 0
+            || i64::try_from(self.session_absolute_ttl_minutes).is_err()
+        {
+            return Err(AdminConfigError::InvalidField(
+                "admin.session_absolute_ttl_minutes",
+            ));
+        }
         let password = self.default_password.expose().trim();
         if password.len() < MINIMUM_INITIAL_PASSWORD_BYTES
             || password.contains('$')
@@ -167,13 +182,17 @@ impl fmt::Debug for AdminConfig {
         formatter
             .debug_struct("AdminConfig")
             .field("session_ttl_minutes", &self.session_ttl_minutes)
+            .field(
+                "session_absolute_ttl_minutes",
+                &self.session_absolute_ttl_minutes,
+            )
             .field("default_username", &self.default_username)
             .field("default_password", &"[REDACTED]")
             .finish()
     }
 }
 
-/// Admin-owned 启动配置错误；不回显任何配置值。
+/// Admin-owned 启动配置错误；不回显任何配置值
 #[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
 pub enum AdminConfigError {
     #[error("配置字段 `{0}` 不合法")]
@@ -182,12 +201,13 @@ pub enum AdminConfigError {
     WeakInitialPassword,
 }
 
-/// API 持有的管理资源能力集合。
+/// API 持有的管理资源能力集合
 ///
-/// 字段全部私有；调用方经 accessor 直接调用能力，不需要命名内部 `use_case` 模块。
+/// 字段全部私有；调用方经 accessor 直接调用能力，不需要命名内部 `use_case` 模块
 #[derive(Clone)]
 pub struct AdminServices {
-    public_services: Arc<service::Registry>,
+    timezone: gateway_core::time::DeploymentTimeZone,
+    public_services: Arc<public_service::Registry>,
     plugins: Arc<PluginsService>,
     plugin_management: Arc<PluginManagementService>,
     proxies: Arc<dyn ProxiesService>,
@@ -199,15 +219,22 @@ pub struct AdminServices {
     client_distribution: Arc<dyn ClientDistributionService>,
     observability: Arc<dyn ObservabilityService>,
     settings: Arc<dyn SettingsService>,
+    usage_data: Arc<dyn UsageDataService>,
     system: Arc<dyn SystemService>,
     credentials: Arc<CredentialsService>,
-    plugin_accounts: Arc<dyn PluginAccountAccess>,
+    // Runtime 只持有 Weak，这个强引用保障账号端口与 Admin 服务同寿命
+    _plugin_accounts: Arc<dyn PluginAccountAccess>,
     backups: Arc<dyn BackupService>,
     import_tasks: Arc<dyn ImportTasksService>,
 }
 
 impl AdminServices {
-    pub fn public_services(&self) -> Arc<service::Registry> {
+    #[must_use]
+    pub const fn timezone(&self) -> gateway_core::time::DeploymentTimeZone {
+        self.timezone
+    }
+
+    pub fn public_services(&self) -> Arc<public_service::Registry> {
         self.public_services.clone()
     }
 
@@ -231,12 +258,6 @@ impl AdminServices {
         self.key_usage.as_ref()
     }
 
-    /// 取得账号服务的共享句柄；后台编排（冻结恢复 worker）需要持有 Arc。
-    #[must_use]
-    pub fn accounts_handle(&self) -> Arc<dyn AccountsService> {
-        Arc::clone(&self.accounts)
-    }
-
     #[must_use]
     pub fn proxies(&self) -> &dyn ProxiesService {
         self.proxies.as_ref()
@@ -267,6 +288,11 @@ impl AdminServices {
         self.client_distribution.as_ref()
     }
 
+    #[must_use]
+    pub fn usage_data(&self) -> &dyn UsageDataService {
+        self.usage_data.as_ref()
+    }
+
     #[must_use]
     pub fn observability(&self) -> &dyn ObservabilityService {
         self.observability.as_ref()
@@ -286,19 +312,13 @@ impl AdminServices {
         self.credentials.as_ref()
     }
 
-    /// Runtime 只持有该窄端口的 Weak；AdminBundle 保持实际生命周期。
-    #[must_use]
-    pub fn plugin_accounts_handle(&self) -> Arc<dyn PluginAccountAccess> {
-        Arc::clone(&self.plugin_accounts)
-    }
-
     #[must_use]
     pub fn backups(&self) -> &dyn BackupService {
         self.backups.as_ref()
     }
 }
 
-/// Admin 初始化完成后的封闭能力包。
+/// Admin 初始化完成后的封闭能力包
 pub struct AdminBundle {
     services: AdminServices,
     worker_contributions: Vec<WorkerContribution>,
@@ -310,15 +330,16 @@ impl AdminBundle {
         self.services.clone()
     }
 
-    /// 取出 Admin Worker 贡献；只能调用一次，与其它 Bundle 的贡献一并交给 Host。
+    /// 取出 Admin Worker 贡献；只能调用一次，与其它 Bundle 的贡献一并交给 Host
     pub fn take_worker_contributions(&mut self) -> Vec<WorkerContribution> {
         std::mem::take(&mut self.worker_contributions)
     }
 }
 
-/// 组合根提供给控制面的运行能力；与配置和存储端口分别传入。
+/// 组合根提供给控制面的运行能力；与配置和存储端口分别传入
 pub struct AdminRuntimePorts {
-    pub service_middleware: service::PlanSource,
+    pub timezone: gateway_core::time::DeploymentTimeZone,
+    pub service_middleware: public_service::PlanSource,
     pub plugin_preparation: Arc<dyn ports::plugins::PluginPreparation>,
     pub plugin_management: Arc<dyn ports::plugin_management::PluginManagement>,
     pub published_snapshot: gateway_core::runtime::RuntimeSnapshotHandle,
@@ -334,11 +355,11 @@ pub struct AdminRuntimePorts {
     pub client_key_verifier: Arc<dyn ClientKeyVerifier>,
 }
 
-/// 校验配置、接入已组装的 Provider 注册表并完成默认管理员幂等初始化。
+/// 校验配置、接入已组装的 Provider 注册表并完成默认管理员幂等初始化
 ///
 /// # Errors
 ///
-/// 配置非法或默认管理员初始化失败时返回错误。
+/// 配置非法或默认管理员初始化失败时返回错误
 pub async fn initialize(
     config: AdminConfig,
     client_config: ClientConfig,
@@ -348,7 +369,7 @@ pub async fn initialize(
     initialize_inner(config, client_config, store, runtime, None).await
 }
 
-/// 使用组合根已绑定给 Runtime 的同一账号窄端口，避免为完整 Admin 重建第二实例。
+/// 使用组合根已绑定给 Runtime 的同一账号窄端口，避免为完整 Admin 重建第二实例
 pub async fn initialize_with_plugin_accounts(
     config: AdminConfig,
     client_config: ClientConfig,
@@ -367,6 +388,7 @@ async fn initialize_inner(
     plugin_accounts: Option<Arc<dyn PluginAccountAccess>>,
 ) -> Result<AdminBundle, AdminError> {
     let AdminRuntimePorts {
+        timezone,
         service_middleware,
         plugin_preparation,
         plugin_management,
@@ -391,8 +413,7 @@ async fn initialize_inner(
     let registry = providers;
 
     let auth = Arc::new(DefaultAuthService::new(
-        config.default_username,
-        config.session_ttl_minutes,
+        &config,
         client_config.session_ttl_minutes,
         store.auth(),
         client_key_verifier.clone(),
@@ -400,37 +421,44 @@ async fn initialize_inner(
     auth.ensure_default_admin(config.default_password.expose())
         .await?;
 
-    let accounts = Arc::new(DefaultAccountsService::new(
+    let accounts = initialize_accounts(
         store.accounts(),
         store.account_runtime(),
+        store.settings(),
+        timezone,
         registry.clone(),
         snapshot.clone(),
         probe.clone(),
-    ));
+    );
     let backup_ports = store.backup();
     let backups = Arc::new(DefaultBackupService::new(
         backup_ports.repository(),
         backup_ports.object_store(),
         store.auth(),
         snapshot.clone(),
+        timezone,
     ));
     let backup_task = backup::task::BackupTask::new(
         backup_ports.repository(),
         backup_ports.dump(),
         backup_ports.object_store(),
-    );
+    )
+    .with_timezone(timezone);
     let system_preflight = Arc::new(use_case::plugin_update::PluginSystemUpdatePreflight::new(
         store.plugins(),
         plugin_inspector.clone(),
-        snapshot.clone(),
     ));
     let system = Arc::new(DefaultSystemService::new(system, system_preflight));
+    let observations: Arc<dyn ports::store::ObservabilityStore> = Arc::new(
+        use_case::observability::CachedObservabilityStore::new(store.observability()),
+    );
     let key_usage = Arc::new(use_case::key_usage::DefaultKeyUsageService::new(
         auth.clone(),
         client_key_verifier,
         store.client_keys(),
-        store.observability(),
+        observations.clone(),
         system.clone(),
+        timezone,
     ));
     let credentials = Arc::new(CredentialsService::new(
         registry.clone(),
@@ -449,9 +477,13 @@ async fn initialize_inner(
         registry.clone(),
         pricing_source,
     );
-    let mut public_services = service::Registry::new(service_middleware);
+    let usage_data = initialize_usage_data(store.usage_data(), store.settings(), registry.clone());
+    let mut public_services = public_service::Registry::new(service_middleware);
     public_services.register_settings(&settings)?;
+    public_services.register_accounts(&accounts)?;
+    public_services.register_usage_data(&usage_data)?;
     let services = AdminServices {
+        timezone,
         public_services: Arc::new(public_services),
         plugin_management: Arc::new(PluginManagementService::new(
             plugin_management,
@@ -488,15 +520,18 @@ async fn initialize_inner(
         )),
         client_distribution: Arc::new(DefaultClientDistributionService::new(client_distribution)),
         observability: Arc::new(DefaultObservabilityService::new(
-            store.observability(),
+            observations.clone(),
             store.accounts(),
             store.settings(),
             registry.clone(),
+            timezone,
+            system.clone(),
         )),
         settings,
+        usage_data,
         system,
         credentials,
-        plugin_accounts,
+        _plugin_accounts: plugin_accounts,
         import_tasks,
         backups,
     };
@@ -522,13 +557,40 @@ async fn initialize_inner(
     .map_err(|_| AdminError::internal("导入 Worker 注册信息不合法"))?;
     worker_contributions.push(WorkerContribution::Registration(registration));
     worker_contributions.extend(freeze_recovery_worker_contribution(freeze_recovery)?);
+    let id = WorkerId::try_new(WorkerKind::ResetCreditAutomation, "admin")
+        .map_err(|_| AdminError::internal("重置卡 Worker ID 不合法"))?;
+    let schedule = WorkerSchedule::try_new(
+        Duration::from_secs(5),
+        Duration::from_secs(5),
+        Duration::from_secs(60),
+        Duration::from_secs(90),
+        Duration::from_secs(30),
+    )
+    .map_err(|_| AdminError::internal("重置卡 Worker 调度配置不合法"))?;
+    let lease = WorkerLeaseRequest::try_new(id.clone(), Duration::from_secs(90))
+        .map_err(|_| AdminError::internal("重置卡 Worker 租约配置不合法"))?;
+    worker_contributions.push(WorkerContribution::Registration(
+        WorkerRegistration::try_new(
+            id,
+            WorkerRunnable::Scheduled {
+                schedule,
+                lease: Some(lease),
+                task: Box::new(reset_credit_automation::ResetCreditAutomationTask {
+                    accounts,
+                    store: store.accounts(),
+                    settings: store.settings(),
+                }),
+            },
+        )
+        .map_err(|_| AdminError::internal("重置卡 Worker 注册失败"))?,
+    ));
     Ok(AdminBundle {
         services,
         worker_contributions,
     })
 }
 
-/// CLI 只组合账号用例，不初始化管理员、管理服务或后台任务；写入仍复用同一事务与审计。
+/// CLI 只组合账号用例，不初始化管理员、管理服务或后台任务；写入仍复用同一事务与审计
 pub fn initialize_plugin_accounts(
     providers: ports::provider::ProviderAdminRegistry,
     accounts: Arc<dyn ports::store::AccountStore>,
@@ -539,7 +601,7 @@ pub fn initialize_plugin_accounts(
     ))
 }
 
-/// 为 Runtime 创建非秘密 Client Key 目录与预算重置的窄端口。
+/// 为 Runtime 创建非秘密 Client Key 目录与预算重置的窄端口
 #[must_use]
 pub fn initialize_plugin_client_keys(
     providers: ports::provider::ProviderAdminRegistry,
@@ -551,7 +613,7 @@ pub fn initialize_plugin_client_keys(
     Arc::new(use_case::plugin_client_keys::DefaultPluginClientKeyAccess::new(service))
 }
 
-/// 为 Runtime 组合实例自有资源写入；权限和归属在同一存储事务复核。
+/// 为 Runtime 组合实例自有资源写入；权限和归属在同一存储事务复核
 #[must_use]
 pub fn initialize_plugin_resources(
     store: Arc<dyn ports::plugin_resources::PluginResourceStore>,
@@ -560,7 +622,7 @@ pub fn initialize_plugin_resources(
     Arc::new(use_case::plugin_resources::DefaultPluginResourceAccess { store, snapshot })
 }
 
-/// Backup Worker 注册：单个可取消 Daemon，owner 固定为 `backup`。
+/// Backup Worker 注册：单个可取消 Daemon，owner 固定为 `backup`
 fn backup_worker_contribution(
     task: backup::task::BackupTask,
 ) -> Result<Vec<WorkerContribution>, AdminError> {
@@ -579,7 +641,7 @@ fn backup_worker_contribution(
     Ok(vec![WorkerContribution::Registration(registration)])
 }
 
-/// 冻结恢复 Worker 注册：按固定周期扫描活跃冻结，owner 固定。
+/// 冻结恢复 Worker 注册：按固定周期扫描活跃冻结，owner 固定
 fn freeze_recovery_worker_contribution(
     task: freeze_recovery::FreezeRecoveryTask,
 ) -> Result<Vec<WorkerContribution>, AdminError> {
@@ -610,7 +672,29 @@ fn freeze_recovery_worker_contribution(
     Ok(vec![WorkerContribution::Registration(registration)])
 }
 
-/// 设置服务不依赖 Web 管理会话，CLI 与服务器通过同一用例执行事务和发布。
+/// 服务端与 CLI 复用账号用例，不随命令启动后台调度
+#[must_use]
+pub fn initialize_accounts(
+    accounts: Arc<dyn ports::store::AccountStore>,
+    account_runtime: Arc<dyn ports::store::AccountRuntimeStore>,
+    settings: Arc<dyn ports::store::SettingsStore>,
+    timezone: gateway_core::time::DeploymentTimeZone,
+    providers: ProviderAdminRegistry,
+    snapshot: Arc<dyn SnapshotControl>,
+    probe: Arc<dyn AccountProbe>,
+) -> Arc<dyn AccountsService> {
+    Arc::new(DefaultAccountsService::new(
+        accounts,
+        account_runtime,
+        settings,
+        timezone,
+        providers,
+        snapshot,
+        probe,
+    ))
+}
+
+/// 设置服务不依赖 Web 管理会话，CLI 与服务器通过同一用例执行事务和发布
 pub fn initialize_settings(
     store: Arc<dyn ports::store::SettingsStore>,
     snapshot: Arc<dyn SnapshotControl>,
@@ -624,3 +708,15 @@ pub fn initialize_settings(
         pricing_source,
     ))
 }
+
+/// HTTP、插件及 CLI 共用的用量领域用例，宿主提供已验证的调用主体
+#[must_use]
+pub fn initialize_usage_data(
+    store: Arc<dyn ports::usage_data::UsageDataStore>,
+    settings: Arc<dyn ports::store::SettingsStore>,
+    providers: ProviderAdminRegistry,
+) -> Arc<dyn UsageDataService> {
+    Arc::new(use_case::usage_data::DefaultUsageDataService::new(
+        store, settings, providers,
+    ))
+}

backend/crates/gateway-admin/src/model/account_groups.rs

@@ -1,13 +1,33 @@
-//! Provider-neutral account group commands and projections.
+//! 跨 Provider 账号分组的管理命令与查询投影
 
 use std::collections::BTreeMap;
 
 use chrono::{DateTime, Utc};
-use gateway_core::{account::AccountStatusFacts, routing::AccountGroupId};
+use gateway_core::{
+    account::{AccountStatusFacts, FastMode},
+    routing::AccountGroupId,
+};
 
 use super::{PageSize, Revision, observability::DecimalAmount};
 
-/// Canonical `#RRGGBBAA` color persisted with an account group.
+/// 名称与描述的共同约束，HTTP、用例和存储边界只映射错误
+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);
+    }
+    Ok(())
+}
+
+/// 账号分组持久化使用的标准 `#RRGGBBAA` 颜色
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupColor(String);
 
@@ -26,7 +46,7 @@ impl AccountGroupColor {
     }
 }
 
-/// Group member availability at the current observation time.
+/// 当前观测时刻的分组成员可用性
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AccountGroupAccountSummary {
     pub available: u64,
@@ -34,23 +54,23 @@ pub struct AccountGroupAccountSummary {
     pub total: u64,
 }
 
-/// Group scheduling slots derived from available accounts and runtime leases.
+/// 根据可用账号与运行时租约计算的分组调度槽位
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AccountGroupCapacity {
     pub used_slots: Option<u64>,
-    /// `None` 表示可用账号中存在不限制并发的账号。
+    /// `None` 表示可用账号中存在不限制并发的账号
     pub total_slots: Option<u64>,
 }
 
-/// Successful, downstream-committed USD request costs for group accounts.
+/// 分组账号成功且已向下游交付的请求美元费用
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupUsage {
     pub today_usd: DecimalAmount,
-    /// 当前 usage retention 窗口内、按请求发生时 routing group 快照归属的累计成本。
+    /// 当前 usage retention 窗口内、当前组成员实际完成请求的累计成本
     pub retained_total_usd: DecimalAmount,
 }
 
-/// 当前页账号组 membership 对应的持久账号事实；运行态在 Admin query service 合并。
+/// 当前页账号组 membership 对应的持久账号事实；运行态在 Admin query service 合并
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupMemberFact {
     pub group_id: AccountGroupId,
@@ -59,7 +79,7 @@ pub struct AccountGroupMemberFact {
     pub total_slots: Option<u64>,
 }
 
-/// Lightweight group reference embedded in account and client-key views.
+/// 账号与 Client Key 视图内嵌的轻量分组引用
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupRef {
     pub id: AccountGroupId,
@@ -68,7 +88,7 @@ pub struct AccountGroupRef {
     pub enabled: bool,
 }
 
-/// Account group list query.
+/// 账号分组列表查询
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupListQuery {
     pub page: u32,
@@ -77,10 +97,11 @@ pub struct AccountGroupListQuery {
     pub enabled: Option<bool>,
 }
 
-/// Complete account group summary.
+/// 完整账号分组摘要
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupRecord {
-    pub disable_fast: bool,
+    pub allow_image_generation: bool,
+    pub fast_mode: FastMode,
     pub id: AccountGroupId,
     pub name: String,
     pub description: Option<String>,
@@ -96,7 +117,7 @@ pub struct AccountGroupRecord {
     pub updated_at: DateTime<Utc>,
 }
 
-/// Paginated account groups.
+/// 账号分组分页结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupPage {
     pub config_revision: Revision,
@@ -106,49 +127,62 @@ pub struct AccountGroupPage {
     pub page_size: u16,
 }
 
-/// Create an account group.
+/// 分组选择器使用的轻量分页结果
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupOptionsPage {
+    pub config_revision: Revision,
+    pub items: Vec<AccountGroupRef>,
+    pub total: u64,
+    pub page: u32,
+    pub page_size: u16,
+}
+
+/// 创建账号分组
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CreateAccountGroup {
-    pub disable_fast: bool,
+    pub allow_image_generation: bool,
+    pub fast_mode: FastMode,
     pub name: String,
     pub description: Option<String>,
     pub color: AccountGroupColor,
 }
 
-/// Store-ready create command with a generated stable ID.
+/// 已生成稳定标识、可直接提交存储的创建命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct NewAccountGroup {
-    pub disable_fast: bool,
+    pub allow_image_generation: bool,
+    pub fast_mode: FastMode,
     pub id: AccountGroupId,
     pub name: String,
     pub description: Option<String>,
     pub color: AccountGroupColor,
 }
 
-/// Update an account group's descriptive fields.
+/// 更新账号分组的描述字段
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UpdateAccountGroup {
-    pub disable_fast: Option<bool>,
+    pub allow_image_generation: Option<bool>,
+    pub fast_mode: Option<FastMode>,
     pub id: AccountGroupId,
     pub name: String,
     pub description: Option<String>,
     pub color: AccountGroupColor,
 }
 
-/// Enable or disable an account group.
+/// 启用或停用账号分组
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SetAccountGroupEnabled {
     pub id: AccountGroupId,
     pub enabled: bool,
 }
 
-/// Delete an account group that is not referenced by a client key.
+/// 删除未被 Client Key 引用的账号分组
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DeleteAccountGroup {
     pub id: AccountGroupId,
 }
 
-/// Result of any account-group mutation.
+/// 账号分组变更结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupMutation {
     pub config_revision: Revision,

backend/crates/gateway-admin/src/model/accounts.rs

@@ -1,4 +1,4 @@
-//! 多 Provider 账号目录与连接测试的公共事实。
+//! 多 Provider 账号目录与连接测试的公共事实
 
 use std::{collections::BTreeMap, pin::Pin};
 
@@ -18,7 +18,7 @@ pub use gateway_core::account::{
     QuotaState, resolve_account_status,
 };
 
-/// 账号可用的管理操作。
+/// 账号可用的管理操作
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct ProviderAccountCapabilities {
     pub quota: bool,
@@ -30,7 +30,7 @@ pub struct ProviderAccountCapabilities {
     pub consume_reset_credit: bool,
 }
 
-/// 导入时统一应用的账号备注、调度与分组设置；缺省时保留原有导入语义。
+/// 导入时统一应用的账号备注、调度与分组设置；缺省时保留原有导入语义
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountImportSettings {
     pub notes: Option<String>,
@@ -41,7 +41,7 @@ pub struct AccountImportSettings {
     pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
 }
 
-/// 账号列表排序字段。
+/// 账号列表排序字段
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AccountSortField {
     Email,
@@ -52,21 +52,21 @@ pub enum AccountSortField {
     ExpiresAt,
 }
 
-/// 账号列表排序方向。
+/// 账号列表排序方向
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SortDirection {
     Asc,
     Desc,
 }
 
-/// 一组完整的账号排序规则。
+/// 一组完整的账号排序规则
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AccountSort {
     pub field: AccountSortField,
     pub direction: SortDirection,
 }
 
-/// 账号列表的存储查询条件。
+/// 账号列表的存储查询条件
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountListQuery {
     pub page: u32,
@@ -78,15 +78,15 @@ pub struct AccountListQuery {
     pub sort: Option<AccountSort>,
 }
 
-/// Admin query service 从运行态存储取得的当前账号冷却快照。
+/// Admin query service 从运行态存储取得的当前账号冷却快照
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct AccountRuntimeSnapshot {
     pub cooldown: BTreeMap<String, gateway_core::account::AccountCooldown>,
-    /// `None` 表示实时 lease 存储不可用；`Some` 中未出现的账号当前使用量为零。
+    /// `None` 表示实时 lease 存储不可用；`Some` 中未出现的账号当前使用量为零
     pub in_flight: Option<BTreeMap<String, u64>>,
 }
 
-/// 恢复任务读取的冻结快照；generation 将异步结果绑定到本次冻结。
+/// 恢复任务读取的冻结快照；generation 将异步结果绑定到本次冻结
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountFreeze {
     pub credential_revision: Revision,
@@ -95,14 +95,14 @@ pub struct AccountFreeze {
     pub requires_probe: bool,
 }
 
-/// Optional account membership filter.
+/// 可选的账号分组成员筛选条件
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AccountGroupFilter {
     Group(gateway_core::routing::AccountGroupId),
     Ungrouped,
 }
 
-/// 账号公共存储投影；Provider 专属字段不进入此结构。
+/// 账号公共存储投影；Provider 专属字段不进入此结构
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountRecord {
     pub id: String,
@@ -123,7 +123,9 @@ pub struct AccountRecord {
     pub concurrency_limit: Option<AccountConcurrencyLimit>,
     pub weight: AccountWeight,
     pub model_access: gateway_core::account::AccountModelAccess,
+    pub outbound_proxy_id: Option<String>,
     pub outbound_proxy: Option<gateway_core::account::OutboundProxy>,
+    pub outbound_proxy_enabled: bool,
     pub credential_state: CredentialState,
     pub credential_observed_at: DateTime<Utc>,
     pub quota: QuotaState,
@@ -133,42 +135,22 @@ pub struct AccountRecord {
     pub updated_at: DateTime<Utc>,
 }
 
-/// 单一货币的账号成本聚合。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct AccountCost {
-    pub currency: String,
-    pub amount: super::observability::DecimalAmount,
+impl AccountRecord {
+    /// 配置保留绑定，执行请求时禁用代理按直连处理
+    #[must_use]
+    pub fn effective_outbound_proxy(&self) -> Option<&gateway_core::account::OutboundProxy> {
+        self.outbound_proxy
+            .as_ref()
+            .filter(|_| self.outbound_proxy_enabled)
+    }
 }
 
-/// 账号在一个模型上的历史用量。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct AccountModelUsage {
-    pub model: String,
-    pub request_count: u64,
-    pub success_count: u64,
-    pub input_tokens: Option<u64>,
-    pub output_tokens: Option<u64>,
-    pub cached_tokens: Option<u64>,
-    pub cache_write_tokens: Option<u64>,
-    pub reasoning_tokens: Option<u64>,
-    pub image_input_tokens: Option<u64>,
-    pub image_output_tokens: Option<u64>,
-    pub image_request_count: u64,
-    pub image_request_failed_count: u64,
-    pub total_tokens: Option<u64>,
-    pub cost_coverage: super::observability::CostCoverage,
-    pub costs: Vec<AccountCost>,
-    pub last_used_at: DateTime<Utc>,
-}
+pub use super::observability::{
+    AccountModelUsage, AccountPoolMetrics as AccountSummary, AccountRequestBucket,
+    CurrencyCost as AccountCost,
+};
 
-/// 账号在一个小时窗口内的请求数。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct AccountRequestBucket {
-    pub bucket_start: DateTime<Utc>,
-    pub request_count: u64,
-}
-
-/// 账号历史用量聚合。
+/// 账号历史用量聚合
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUsage {
     pub account_id: String,
@@ -176,9 +158,9 @@ pub struct AccountUsage {
     pub success_count: u64,
     pub input_tokens: Option<u64>,
     pub output_tokens: Option<u64>,
-    pub cached_tokens: Option<u64>,
-    pub cache_write_tokens: Option<u64>,
-    pub reasoning_tokens: Option<u64>,
+    pub cached_input_tokens: Option<u64>,
+    pub cache_write_input_tokens: Option<u64>,
+    pub reasoning_output_tokens: Option<u64>,
     pub image_input_tokens: Option<u64>,
     pub image_output_tokens: Option<u64>,
     pub image_request_count: u64,
@@ -191,9 +173,9 @@ pub struct AccountUsage {
     pub models: Vec<AccountModelUsage>,
 }
 
-/// 某个账号在调用方指定时间窗口内的本地用量查询。
+/// 某个账号在调用方指定时间窗口内的本地用量查询
 ///
-/// `key` 只用于把聚合结果关联回调用方的窗口，不承载 Provider 私有语义。
+/// `key` 只用于把聚合结果关联回调用方的窗口，不承载 Provider 私有语义
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUsageWindowQuery {
     pub account_id: String,
@@ -201,7 +183,7 @@ pub struct AccountUsageWindowQuery {
     pub range: TimeRange,
 }
 
-/// 一个账号时间窗口用量查询的结果。
+/// 一个账号时间窗口用量查询的结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUsageWindowResult {
     pub account_id: String,
@@ -209,7 +191,7 @@ pub struct AccountUsageWindowResult {
     pub usage: AccountUsage,
 }
 
-/// 账号列表页所需的完整存储事实。
+/// 账号列表页所需的完整存储事实
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountPage {
     pub config_revision: Revision,
@@ -218,7 +200,7 @@ pub struct AccountPage {
     pub summary: AccountSummary,
 }
 
-/// 同一状态快照下的账号事实与唯一状态投影。
+/// 同一状态快照下的账号事实与唯一状态投影
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountPageItem {
     pub account: AccountRecord,
@@ -226,33 +208,20 @@ pub struct AccountPageItem {
     pub capacity: AccountCapacity,
 }
 
-/// 网关配置的账号并发上限与查询时的占用，不包含排队请求或上游隐藏限制。
+/// 网关配置的账号并发上限与查询时的占用，不包含排队请求或上游隐藏限制
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AccountCapacity {
-    /// 实时租约读取失败时为 `None`，不能当作空闲。
+    /// 实时租约读取失败时为 `None`，不能当作空闲
     pub used_slots: Option<u64>,
-    /// 应用账号覆盖或全局默认值后的上限；`None` 表示不限。
+    /// 应用账号覆盖或全局默认值后的上限；`None` 表示不限
     pub total_slots: Option<u64>,
 }
 
-/// 统一账号目录的全局状态计数，不受当前筛选和分页影响。
-///
-/// 计数与 [`AccountStatus`] 一一对应，由 store 按派生状态聚合。
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct AccountSummary {
-    pub total: u64,
-    pub normal: u64,
-    pub quota_exhausted: u64,
-    pub rate_limited: u64,
-    pub disabled: u64,
-    pub error: u64,
-}
-
-/// 账号可编辑事实的一次性替换命令。
+/// 账号可编辑事实的一次性替换命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UpdateAccount {
     pub account_id: String,
-    /// 缺省保留备注；空字符串清空备注。
+    /// 缺省保留备注；空字符串清空备注
     pub notes: Option<String>,
     pub enabled: bool,
     pub concurrency_limit: Option<AccountConcurrencyLimit>,
@@ -262,14 +231,14 @@ pub struct UpdateAccount {
     pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }
 
-/// 账号更新结果。
+/// 账号更新结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUpdateResult {
     pub config_revision: Revision,
     pub account_id: gateway_core::account::ProviderAccountId,
 }
 
-/// 仅修改显式字段的批量账号设置命令。
+/// 仅修改显式字段的批量账号设置命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BatchUpdateAccounts {
     pub account_ids: Vec<String>,
@@ -281,20 +250,20 @@ pub struct BatchUpdateAccounts {
     pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }
 
-/// 批量账号更新结果。
+/// 批量账号更新结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountsUpdateResult {
     pub config_revision: Revision,
     pub account_ids: Vec<gateway_core::account::ProviderAccountId>,
 }
 
-/// 账号批量删除命令。
+/// 账号批量删除命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DeleteAccounts {
     pub account_ids: Vec<String>,
 }
 
-/// 账号连接测试的语义事件。
+/// 账号连接测试的语义事件
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AccountConnectionTestEvent {
     Started {
@@ -323,6 +292,27 @@ pub enum AccountConnectionTestEvent {
     },
 }
 
-/// 每次连接测试独占的有限事件流。
+/// 每次连接测试独占的有限事件流
 pub type AccountConnectionTestEventStream =
     Pin<Box<dyn Stream<Item = AccountConnectionTestEvent> + Send + 'static>>;
+
+/// 单个账号普通并发池的实时租约明细，不关联请求历史
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountConcurrencyEntry {
+    pub lease_id: String,
+    pub request_id: Option<String>,
+    pub client_key_id: Option<String>,
+    pub client_key_name: Option<String>,
+    pub model: Option<String>,
+    pub client_ip: Option<String>,
+    pub started_at: Option<DateTime<Utc>>,
+    pub acquired_at: Option<DateTime<Utc>>,
+}
+
+/// 同一次 Redis 读取中的当前占用数和分页明细
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountConcurrencyPage {
+    pub entries: Vec<AccountConcurrencyEntry>,
+    pub total: u64,
+    pub observed_at: DateTime<Utc>,
+}

backend/crates/gateway-admin/src/model/analytics.rs

@@ -0,0 +1,65 @@
+//! 统计投影的新鲜度、覆盖范围与预计算费用合同
+
+use chrono::{DateTime, Utc};
+
+use super::observability::{DecimalAmount, RequestMetricPoint, UsageOverview};
+
+/// 数据可见性状态，不以缺失投影冒充零统计
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum AnalyticsState {
+    Ready,
+    #[default]
+    Building,
+    Lagging,
+    Stale,
+}
+
+impl AnalyticsState {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Ready => "ready",
+            Self::Building => "building",
+            Self::Lagging => "lagging",
+            Self::Stale => "stale",
+        }
+    }
+}
+
+/// 与统计结果在同一读取快照内取得的覆盖和版本事实
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct AnalyticsMetadata {
+    pub coverage_start: Option<DateTime<Utc>>,
+    pub coverage_end: Option<DateTime<Utc>>,
+    pub generated_at: DateTime<Utc>,
+    pub lag_seconds: u64,
+    pub state: AnalyticsState,
+    pub percentiles_approximate: bool,
+    pub schema_version: u32,
+    pub histogram_version: u32,
+    /// 派生数据版本供缓存判断失效，不作为源事务提交顺序
+    pub generation: u64,
+}
+
+/// 单次请求经 Provider 费用合同确认后可累加的 USD 情景金额
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct UsageBillingProjection {
+    pub standard_amount: Option<DecimalAmount>,
+    pub no_cache_amount: Option<DecimalAmount>,
+}
+
+/// 时间桶内的情景费用，未知金额不改写为零
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UsageProjectedCostPoint {
+    pub bucket_start: DateTime<Utc>,
+    pub standard_amount: Option<DecimalAmount>,
+    pub no_cache_amount: Option<DecimalAmount>,
+}
+
+/// 同一数据库快照内的完整洞察输入
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UsageInsightsObservation {
+    pub overview: UsageOverview,
+    pub trend: Vec<RequestMetricPoint>,
+    pub costs: Vec<UsageProjectedCostPoint>,
+}

backend/crates/gateway-admin/src/model/audit.rs

@@ -1,4 +1,4 @@
-//! 管理写入的审计分类；适配器只能补充事务实际写入的字段与实体标识。
+//! 管理写入的审计分类；适配器只能补充事务实际写入的字段与实体标识
 
 use super::{
     MutationActor, MutationContext,
@@ -19,6 +19,10 @@ pub enum MutationAuditOperation {
     ProviderAccountUpdate,
     BackupStorageUpdate,
     BackupScheduleUpdate,
+    BackupCreate,
+    BackupDelete,
+    BackupConnectionTest,
+    BackupDownloadUrl,
     ProviderAccountAdaptConcurrency,
     ProviderAccountRecover,
     ProviderAccountBatchUpdate,
@@ -76,6 +80,10 @@ impl MutationAuditOperation {
             Self::ProviderAccountUpdate => ("update", "provider_account"),
             Self::BackupStorageUpdate => ("backup.s3_config_updated", "backup_settings"),
             Self::BackupScheduleUpdate => ("backup.schedule_updated", "backup_settings"),
+            Self::BackupCreate => ("backup.created", "backup"),
+            Self::BackupDelete => ("backup.delete_requested", "backup"),
+            Self::BackupConnectionTest => ("backup.s3_connection_tested", "backup_settings"),
+            Self::BackupDownloadUrl => ("backup.download_url_created", "backup"),
             Self::ProviderAccountAdaptConcurrency => ("adapt_concurrency", "provider_account"),
             Self::ProviderAccountRecover => ("recover", "provider_account"),
             Self::ProviderAccountBatchUpdate => ("batch_update", "provider_account"),
@@ -112,7 +120,7 @@ impl MutationAuditOperation {
     }
 }
 
-/// 分类与稳定实体标识共同组成审计意图，字段差异由同一提交事务补齐。
+/// 分类与稳定实体标识共同组成审计意图，字段差异由同一提交事务补齐
 #[derive(Debug, Clone, Copy)]
 pub struct MutationAuditIntent<'a> {
     pub operation: MutationAuditOperation,

backend/crates/gateway-admin/src/model/auth.rs

@@ -1,30 +1,30 @@
-//! 控制面认证、统一会话和管理员安全审计事实。
+//! 控制面认证、统一会话和管理员安全审计事实
 
 use chrono::{DateTime, Utc};
 use gateway_core::{engine::execution::ClientAuthenticationError, policy::ClientApiKeyId};
 
 use super::{MutationActor, MutationContext, Revision};
 
-/// 会话审计使用的稳定管理员标识。
+/// 会话审计使用的稳定管理员标识
 #[must_use]
 pub fn admin_session_actor_ref(admin_user_id: &str) -> String {
     format!("admin:{admin_user_id}")
 }
 
-/// 已认证的管理主体。
+/// 已认证的管理主体
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AdminPrincipal {
     Session {
         admin_user_id: String,
     },
     ApiKey,
-    /// 安装者完整信任的插件；身份仅由内部 HTTP 分派端口签发。
+    /// 安装者完整信任的插件；身份仅由内部 HTTP 分派端口签发
     Plugin {
         instance_id: String,
     },
 }
 
-/// 传给管理用例的安全请求上下文。
+/// 传给管理用例的安全请求上下文
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AdminRequestContext {
     pub principal: AdminPrincipal,
@@ -48,7 +48,7 @@ impl AdminRequestContext {
     }
 }
 
-/// 登录方式只决定凭据验证流程，不能直接授予会话权限。
+/// 登录方式只决定凭据验证流程，不能直接授予会话权限
 #[derive(Clone, PartialEq, Eq)]
 pub enum LoginCommand {
     Admin {
@@ -76,24 +76,29 @@ impl std::fmt::Debug for LoginCommand {
     }
 }
 
-/// 登录成功后返回的会话事实。
+/// 登录或刷新后仅向当前浏览器交付的会话凭据
 #[derive(Clone, PartialEq, Eq)]
-pub struct LoginResult {
+pub struct SessionGrant {
     pub session_id: String,
+    pub refresh_token: Option<String>,
     pub session: AuthSession,
 }
 
-impl std::fmt::Debug for LoginResult {
+impl std::fmt::Debug for SessionGrant {
     fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         formatter
-            .debug_struct("LoginResult")
+            .debug_struct("SessionGrant")
             .field("session_id", &"[REDACTED]")
+            .field(
+                "refresh_token",
+                &self.refresh_token.as_ref().map(|_| "[REDACTED]"),
+            )
             .field("session", &self.session)
             .finish()
     }
 }
 
-/// 登录状态机可被 API 精确映射的失败类型。
+/// 登录状态机可被 API 精确映射的失败类型
 #[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
 pub enum LoginError {
     #[error("invalid login credentials")]
@@ -114,7 +119,7 @@ impl From<ClientAuthenticationError> for LoginError {
     }
 }
 
-/// 服务端已验证的身份绑定，不保存密码或原始 API Key。
+/// 服务端已验证的身份绑定，不保存密码或原始 API Key
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum SessionSubject {
     Admin {
@@ -126,7 +131,7 @@ pub enum SessionSubject {
     },
 }
 
-/// 仅已登录管理员可以修改自己的密码。
+/// 仅已登录管理员可以修改自己的密码
 pub struct ChangePassword {
     pub current_password: String,
     pub new_password: String,
@@ -138,14 +143,44 @@ impl std::fmt::Debug for ChangePassword {
     }
 }
 
-/// 两种登录方式共用的固定有效期会话。
+/// 访问有效期与逻辑会话；没有续期凭据的会话保持固定期限
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AuthSession {
     pub subject: SessionSubject,
     pub expires_at: DateTime<Utc>,
+    pub absolute_expires_at: Option<DateTime<Utc>>,
+    pub renewal: Option<SessionRenewal>,
 }
 
-/// 安全审计事件类型。
+/// 长效登录的凭据摘要与续期窗口；访问到期不删除整段登录
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct SessionRenewal {
+    pub expires_at: DateTime<Utc>,
+    pub access_digest: [u8; 32],
+    pub refresh_digest: [u8; 32],
+    pub previous: Option<SessionRefreshReplay>,
+}
+
+/// 仅保存上一代摘要及派生盐；响应丢失时须持有上一代凭据才能重建同一响应
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct SessionRefreshReplay {
+    pub digest: [u8; 32],
+    pub salt: [u8; 32],
+    pub expires_at: DateTime<Utc>,
+}
+
+impl AuthSession {
+    #[must_use]
+    pub fn retained_until(&self) -> DateTime<Utc> {
+        self.renewal
+            .as_ref()
+            .map_or(self.expires_at, |renewal| renewal.expires_at)
+    }
+}
+
+/// 安全审计事件类型
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AuditActorKind {
     AdminSession,
@@ -154,7 +189,7 @@ pub enum AuditActorKind {
     Anonymous,
 }
 
-/// 管理写操作留下的最小审计事实。
+/// 管理写操作留下的最小审计事实
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AdminAuditEvent {
     pub id: String,

backend/crates/gateway-admin/src/model/backup/code.rs

@@ -1,34 +1,35 @@
-//! 备份领域的稳定错误码。
+//! 备份领域的稳定错误码
 
-/// 配置或参数非法。
+/// 配置或参数非法
 pub const INVALID_CONFIG: &str = "backup.invalid_config";
-/// Cron 表达式非法。
+/// Cron 表达式非法
 pub const INVALID_CRON: &str = "backup.invalid_cron";
-/// IANA 时区非法。
-pub const INVALID_TIMEZONE: &str = "backup.invalid_timezone";
-/// 记录不存在。
+/// IANA 时区非法
+/// 记录不存在
 pub const RECORD_NOT_FOUND: &str = "backup.record_not_found";
-/// 已存在活跃任务，拒绝创建。
+/// 已存在活跃任务，拒绝创建
 pub const ACTIVE_TASK_CONFLICT: &str = "backup.active_task_conflict";
-/// 记录状态与期望不符，无法迁移。
+/// 记录状态与期望不符，无法迁移
 pub const STATE_CONFLICT: &str = "backup.state_conflict";
-/// 已有记录时禁止切换存储目标。
+/// 已有记录时禁止切换存储目标
 pub const STORAGE_IDENTITY_LOCKED: &str = "backup.storage_identity_locked";
-/// `pg_dump` 非零退出或失败。
+/// `pg_dump` 非零退出或失败
 pub const PG_DUMP_FAILED: &str = "backup.pg_dump_failed";
-/// 暂存磁盘空间不足。
+/// 用量汇总尚未完整发布
+pub const ANALYTICS_NOT_READY: &str = "backup.analytics_not_ready";
+/// 暂存磁盘空间不足
 pub const STAGING_SPACE_EXHAUSTED: &str = "backup.staging_space_exhausted";
-/// S3 认证失败。
+/// S3 认证失败
 pub const S3_AUTH_FAILED: &str = "backup.s3_auth_failed";
-/// S3 权限拒绝。
+/// S3 权限拒绝
 pub const S3_PERMISSION_DENIED: &str = "backup.s3_permission_denied";
-/// S3 上传失败。
+/// S3 上传失败
 pub const S3_UPLOAD_FAILED: &str = "backup.s3_upload_failed";
-/// 远端对象校验失败。
+/// 远端对象校验失败
 pub const REMOTE_VERIFICATION_FAILED: &str = "backup.remote_verification_failed";
-/// 任务被取消。
+/// 任务被取消
 pub const CANCELLED: &str = "backup.cancelled";
-/// 仓储或对象存储暂不可用。
+/// 仓储或对象存储暂不可用
 pub const STORE_UNAVAILABLE: &str = "backup.store_unavailable";
-/// 上游 S3 服务返回无效或失败响应。
+/// 上游 S3 服务返回无效或失败响应
 pub const UPSTREAM_FAILURE: &str = "backup.upstream_failure";

backend/crates/gateway-admin/src/model/backup/mod.rs

@@ -1,8 +1,10 @@
-//! S3 备份领域模型、状态机与稳定错误。
+//! S3 备份领域模型、状态机与稳定错误
 //!
-//! 领域类型只携带事实，不承载基础设施细节。Secret 使用 [`secrecy::SecretString`]，
-//! 全流程不实现 `Serialize`，避免被错误地写入 wire 或日志。管理员身份等审计事实
-//! 只存在于 `admin_audit_events`，本模型不重复保存。
+//! 领域类型只携带事实，不承载基础设施细节
+//! Secret 使用 [`secrecy::SecretString`]，
+//! 全流程不实现 `Serialize`，避免被错误地写入 wire 或日志
+//! 管理员身份等审计事实
+//! 只存在于 `admin_audit_events`，本模型不重复保存
 
 use std::fmt;
 
@@ -12,7 +14,7 @@ use uuid::Uuid;
 
 use super::PageSize;
 
-/// 备份触发来源。
+/// 备份触发来源
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum BackupTriggerKind {
     Manual,
@@ -20,7 +22,7 @@ pub enum BackupTriggerKind {
 }
 
 impl BackupTriggerKind {
-    /// 稳定持久化值。
+    /// 稳定持久化值
     #[must_use]
     pub const fn as_str(self) -> &'static str {
         match self {
@@ -29,7 +31,7 @@ impl BackupTriggerKind {
         }
     }
 
-    /// 解析持久化值。
+    /// 解析持久化值
     #[must_use]
     pub fn parse(value: &str) -> Option<Self> {
         match value {
@@ -46,11 +48,11 @@ impl fmt::Display for BackupTriggerKind {
     }
 }
 
-/// 备份任务状态机（六状态）。
+/// 备份任务状态机（六状态）
 ///
 /// 迁移 `backup_records_lifecycle_ck` 与字段空值语义共同定义合法持久化行；
-/// [`Self::allows_transition_to`] 只约束领域内的显式状态迁移，两层都必须满足。
-/// 删除成功后记录行被硬删除，因此不存在 `deleted` 终态。
+/// [`Self::allows_transition_to`] 只约束领域内的显式状态迁移，两层都必须满足
+/// 删除成功后记录行被硬删除，因此不存在 `deleted` 终态
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum BackupStatus {
     Queued,
@@ -62,7 +64,7 @@ pub enum BackupStatus {
 }
 
 impl BackupStatus {
-    /// 稳定持久化值。
+    /// 稳定持久化值
     #[must_use]
     pub const fn as_str(self) -> &'static str {
         match self {
@@ -75,7 +77,7 @@ impl BackupStatus {
         }
     }
 
-    /// 解析持久化值。
+    /// 解析持久化值
     #[must_use]
     pub fn parse(value: &str) -> Option<Self> {
         match value {
@@ -89,19 +91,19 @@ impl BackupStatus {
         }
     }
 
-    /// 该状态是否消耗全局活跃名额。
+    /// 该状态是否消耗全局活跃名额
     #[must_use]
     pub const fn is_active(self) -> bool {
         matches!(self, Self::Queued | Self::Dumping | Self::Uploading)
     }
 
-    /// 该状态是否允许进入删除流程。
+    /// 该状态是否允许进入删除流程
     #[must_use]
     pub const fn can_be_deleted(self) -> bool {
         matches!(self, Self::Completed | Self::Failed)
     }
 
-    /// 领域内允许的显式迁移。
+    /// 领域内允许的显式迁移
     #[must_use]
     pub fn allows_transition_to(self, target: BackupStatus) -> bool {
         matches!(
@@ -124,7 +126,7 @@ impl fmt::Display for BackupStatus {
     }
 }
 
-/// 已通过领域状态机校验的显式迁移。
+/// 已通过领域状态机校验的显式迁移
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct BackupStatusTransition {
     from: BackupStatus,
@@ -132,26 +134,26 @@ pub struct BackupStatusTransition {
 }
 
 impl BackupStatusTransition {
-    /// 校验并构造显式迁移；非法状态边返回 `None`。
+    /// 校验并构造显式迁移；非法状态边返回 `None`
     #[must_use]
     pub fn try_new(from: BackupStatus, to: BackupStatus) -> Option<Self> {
         from.allows_transition_to(to).then_some(Self { from, to })
     }
 
-    /// 迁移要求的当前状态。
+    /// 迁移要求的当前状态
     #[must_use]
     pub const fn from(self) -> BackupStatus {
         self.from
     }
 
-    /// 迁移完成后的目标状态。
+    /// 迁移完成后的目标状态
     #[must_use]
     pub const fn to(self) -> BackupStatus {
         self.to
     }
 }
 
-/// S3 存储配置更新命令；`secret_access_key` 为 `None` 表示保留旧值。
+/// S3 存储配置更新命令；`secret_access_key` 为 `None` 表示保留旧值
 #[derive(Clone)]
 pub struct UpdateBackupStorageCommand {
     pub endpoint: String,
@@ -178,19 +180,18 @@ impl fmt::Debug for UpdateBackupStorageCommand {
     }
 }
 
-/// 调度配置更新命令。
+/// 调度配置更新命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UpdateBackupScheduleCommand {
     pub schedule_enabled: bool,
     pub cron_expression: String,
-    pub schedule_timezone: String,
     pub retention_days: u32,
     pub retention_count: u32,
 }
 
-/// 完整保存的备份设置（含 Secret）。
+/// 完整保存的备份设置（含 Secret）
 ///
-/// 只从仓储读取；不实现 `Serialize`，防止 Secret 进入 wire 或日志。
+/// 只从仓储读取；不实现 `Serialize`，防止 Secret 进入 wire 或日志
 #[derive(Clone)]
 pub struct BackupSettings {
     pub storage_revision: u64,
@@ -203,6 +204,7 @@ pub struct BackupSettings {
     pub force_path_style: bool,
     pub schedule_enabled: bool,
     pub cron_expression: Option<String>,
+    /// 记录持久化游标采用的时区，由服务端维护，不是独立部署设置
     pub schedule_timezone: Option<String>,
     pub retention_days: u32,
     pub retention_count: u32,
@@ -236,7 +238,7 @@ impl fmt::Debug for BackupSettings {
 }
 
 impl BackupSettings {
-    /// S3 存储配置是否完整（bucket/region/密钥/前缀齐全）。
+    /// S3 存储配置是否完整（bucket/region/密钥/前缀齐全）
     #[must_use]
     pub fn storage_configured(&self) -> bool {
         self.endpoint.is_some()
@@ -247,14 +249,14 @@ impl BackupSettings {
             && self.prefix.is_some()
     }
 
-    /// 探测是否已对当前 revision 成功；`last_verified_at` 非空即表示当前配置已通过探针。
+    /// 探测是否已对当前 revision 成功；`last_verified_at` 非空即表示当前配置已通过探针
     #[must_use]
     pub fn storage_verified(&self) -> bool {
         self.last_verified_at.is_some()
     }
 }
 
-/// 已经校验并可用于对象存储操作的存储配置快照。
+/// 已经校验并可用于对象存储操作的存储配置快照
 #[derive(Clone)]
 pub struct BackupStorageConfig {
     pub storage_revision: u64,
@@ -284,7 +286,7 @@ impl fmt::Debug for BackupStorageConfig {
 }
 
 impl BackupStorageConfig {
-    /// 从完整设置推导对象存储配置；设置不完整时返回 `None`。
+    /// 从完整设置推导对象存储配置；设置不完整时返回 `None`
     #[must_use]
     pub fn from_settings(settings: &BackupSettings) -> Option<Self> {
         Some(Self {
@@ -300,7 +302,7 @@ impl BackupStorageConfig {
     }
 }
 
-/// 一条备份记录。
+/// 一条备份记录
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BackupRecord {
     pub id: String,
@@ -315,13 +317,13 @@ pub struct BackupRecord {
     pub error_message: Option<String>,
     pub started_at: Option<DateTime<Utc>>,
     pub completed_at: Option<DateTime<Utc>>,
-    /// 创建时确定的过期时间；手工和计划备份均可设置，到期自动清理。
+    /// 创建时确定的过期时间；手工和计划备份均可设置，到期自动清理
     pub expires_at: Option<DateTime<Utc>>,
     pub created_at: DateTime<Utc>,
     pub updated_at: DateTime<Utc>,
 }
 
-/// 备份记录分页查询。
+/// 备份记录分页查询
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BackupRecordListQuery {
     pub page: u32,
@@ -330,7 +332,7 @@ pub struct BackupRecordListQuery {
     pub trigger: Option<BackupTriggerKind>,
 }
 
-/// 备份记录分页结果。
+/// 备份记录分页结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BackupRecordPage {
     pub items: Vec<BackupRecord>,
@@ -340,7 +342,7 @@ pub struct BackupRecordPage {
 }
 
 impl BackupRecordPage {
-    /// 计算总页数；空集合视为一页。
+    /// 计算总页数；空集合视为一页
     #[must_use]
     pub fn total_pages(&self) -> u32 {
         let size = u64::from(self.page_size.get());
@@ -352,7 +354,7 @@ impl BackupRecordPage {
     }
 }
 
-/// 创建备份任务的持久化数据；id 与对象 key 由领域生成。
+/// 创建备份任务的持久化数据；id 与对象 key 由领域生成
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BackupRecordSeed {
     pub id: String,
@@ -362,7 +364,7 @@ pub struct BackupRecordSeed {
     pub expires_at: Option<DateTime<Utc>>,
 }
 
-/// 连接测试结果；只携带稳定阶段与脱敏消息。
+/// 连接测试结果；只携带稳定阶段与脱敏消息
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ConnectionTestResult {
     pub ok: bool,
@@ -371,7 +373,7 @@ pub struct ConnectionTestResult {
     pub message: String,
 }
 
-/// 对象存储探测阶段。
+/// 对象存储探测阶段
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ConnectionTestStage {
     PutObject,
@@ -381,7 +383,7 @@ pub enum ConnectionTestStage {
 }
 
 impl ConnectionTestStage {
-    /// 稳定 wire 值。
+    /// 稳定 wire 值
     #[must_use]
     pub const fn as_str(self) -> &'static str {
         match self {
@@ -393,10 +395,10 @@ impl ConnectionTestStage {
     }
 }
 
-/// 上传到对象存储并期望远端校验的归档 metadata。
+/// 上传到对象存储并期望远端校验的归档 metadata
 ///
 /// `size_bytes` 在上传时不写入 metadata，但 `HeadObject` 会返回远端大小，
-/// 用于与本地归档校验一致。
+/// 用于与本地归档校验一致
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BackupObjectMetadata {
     pub backup_id: String,
@@ -406,7 +408,7 @@ pub struct BackupObjectMetadata {
 }
 
 impl BackupObjectMetadata {
-    /// 构造上传 metadata。
+    /// 构造上传 metadata
     #[must_use]
     pub const fn new(
         backup_id: String,
@@ -423,7 +425,7 @@ impl BackupObjectMetadata {
     }
 }
 
-/// 短时下载地址结果。
+/// 短时下载地址结果
 #[derive(Clone, PartialEq, Eq)]
 pub struct DownloadUrlResult {
     pub url: String,
@@ -442,10 +444,11 @@ impl fmt::Debug for DownloadUrlResult {
     }
 }
 
-/// 备份基础设施错误：只携带稳定错误码与脱敏消息。
+/// 备份基础设施错误：只携带稳定错误码与脱敏消息
 ///
 /// 该类型不构成第二套 kind 枚举；`gateway-admin` 边界统一映射为既有
-/// `AdminErrorKind`。稳定 `error_code` 同时用于任务记录、日志与 UI。
+/// `AdminErrorKind`
+/// 稳定 `error_code` 同时用于任务记录、日志与 UI
 #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
 #[error("{message}")]
 pub struct BackupError {
@@ -454,32 +457,52 @@ pub struct BackupError {
 }
 
 impl BackupError {
-    /// 构造基础设施错误。
+    /// 构造基础设施错误
     #[must_use]
     pub const fn new(code: &'static str, message: String) -> Self {
         Self { code, message }
     }
 
-    /// 稳定错误码，例如 `backup.s3_auth_failed`。
+    /// 稳定错误码，例如 `backup.s3_auth_failed`
     #[must_use]
     pub const fn code(&self) -> &'static str {
         self.code
     }
 
-    /// 脱敏后的可操作消息。
+    /// 脱敏后的可操作消息
     #[must_use]
     pub fn message(&self) -> &str {
         &self.message
     }
+
+    /// 清理失败附加到原始终态，不覆盖上传失败或主动取消的分类
+    #[must_use]
+    pub fn with_cleanup_failure(
+        mut self,
+        stage: &'static str,
+        error: &Self,
+        retry_on_expiration: bool,
+    ) -> Self {
+        let recovery = if retry_on_expiration {
+            "等待备份到期清理"
+        } else {
+            "未安排自动重试"
+        };
+        self.message.push_str(&format!(
+            "；清理阶段 {stage} 失败（{}），{recovery}",
+            error.code()
+        ));
+        self
+    }
 }
 
-/// 构造稳定错误码常量。
+/// 构造稳定错误码常量
 pub mod code;
 
-/// 构建对象 key：`{prefix}/YYYY/MM/DD/codex-proxy-rs_{UTC seconds}_{backup id}.dump`。
+/// 构建对象 key：`{prefix}/YYYY/MM/DD/codex-proxy-rs_{UTC seconds}_{backup id}.sql.gz`
 ///
 /// 规范化规则：prefix 不得为空、不得以前导 `/` 开头、不得包含 `..`、反斜杠或控制字符；
-/// 输出统一使用 `/` 分隔且不含空段。
+/// 输出统一使用 `/` 分隔且不含空段
 pub fn build_object_key(
     prefix: &str,
     backup_id: &str,
@@ -487,7 +510,7 @@ pub fn build_object_key(
 ) -> Result<String, BackupError> {
     let prefix = normalize_prefix(prefix)?;
     Ok(format!(
-        "{prefix}/{}/{:02}/{:02}/codex-proxy-rs_{}_{}.dump",
+        "{prefix}/{}/{:02}/{:02}/codex-proxy-rs_{}_{}.sql.gz",
         at.format("%Y"),
         at.format("%m"),
         at.format("%d"),
@@ -496,22 +519,22 @@ pub fn build_object_key(
     ))
 }
 
-/// 下载文件名：`codex-proxy-rs_{短 id}.dump`，与对象 key 的文件名一致。
+/// 下载文件名：`codex-proxy-rs_{短 id}.sql.gz`，与对象 key 的文件名一致
 #[must_use]
 pub fn build_download_file_name(backup_id: &str) -> String {
-    format!("codex-proxy-rs_{}.dump", short_backup_id(backup_id))
+    format!("codex-proxy-rs_{}.sql.gz", short_backup_id(backup_id))
 }
 
-/// 截取备份 id 的可读短标识：去掉 `backup_` 前缀，最多保留 8 位 hex。
+/// 截取备份 id 的可读短标识：去掉 `backup_` 前缀，最多保留 8 位 hex
 #[must_use]
 fn short_backup_id(backup_id: &str) -> String {
     let hex = backup_id.strip_prefix("backup_").unwrap_or(backup_id);
     hex.get(..8).unwrap_or(hex).to_owned()
 }
 
-/// 规范化并校验对象 prefix。
+/// 规范化并校验对象 prefix
 ///
-/// 返回去掉尾部 `/` 的规范 prefix；空串、前导 `/`、`..` 段、反斜杠和控制字符均拒绝。
+/// 返回去掉尾部 `/` 的规范 prefix；空串、前导 `/`、`..` 段、反斜杠和控制字符均拒绝
 pub fn normalize_prefix(prefix: &str) -> Result<String, BackupError> {
     if prefix.is_empty() || prefix.starts_with('/') {
         return Err(BackupError::new(
@@ -534,13 +557,13 @@ pub fn normalize_prefix(prefix: &str) -> Result<String, BackupError> {
     Ok(prefix.trim_end_matches('/').to_owned())
 }
 
-/// 生成新的备份记录 id。
+/// 生成新的备份记录 id
 #[must_use]
 pub fn new_backup_id() -> String {
     format!("backup_{}", Uuid::now_v7().simple())
 }
 
-/// 从触发类型与计划时间构造可持久化 seed；id 与对象 key 一次生成保持一致。
+/// 从触发类型与计划时间构造可持久化 seed；id 与对象 key 一次生成保持一致
 pub fn build_backup_seed(
     trigger_kind: BackupTriggerKind,
     scheduled_at: Option<DateTime<Utc>>,

backend/crates/gateway-admin/src/model/client_distribution.rs

@@ -1,8 +1,8 @@
-//! 管理设置页使用的 Codex 客户端下载信息。
+//! 管理设置页使用的 Codex 客户端下载信息
 
 use chrono::{DateTime, Utc};
 
-/// Windows 安装包架构。
+/// Windows 安装包架构
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum ClientArchitecture {
     X64,
@@ -19,7 +19,7 @@ impl ClientArchitecture {
     }
 }
 
-/// 下载地址的可信来源。
+/// 下载地址的可信来源
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ClientDownloadSource {
     MicrosoftStore,
@@ -36,7 +36,7 @@ impl ClientDownloadSource {
     }
 }
 
-/// 一个已经过 Host 校验、可以直接交给浏览器下载的安装包。
+/// 一个已经过 Host 校验、可以直接交给浏览器下载的安装包
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientDownloadPackage {
     pub architecture: ClientArchitecture,
@@ -48,7 +48,7 @@ pub struct ClientDownloadPackage {
     pub expires_at: Option<DateTime<Utc>>,
 }
 
-/// Codex Desktop Windows 下载解析结果。
+/// Codex Desktop Windows 下载解析结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CodexDesktopWindowsDownloads {
     pub resolved_at: DateTime<Utc>,

backend/crates/gateway-admin/src/model/client_keys.rs

@@ -1,4 +1,4 @@
-//! Client API Key 的 Command、Result 与安全秘密类型。
+//! Client API Key 的 Command、Result 与安全秘密类型
 
 use std::{collections::BTreeMap, fmt, num::NonZeroU16};
 
@@ -20,16 +20,30 @@ pub type ProviderRequestProfileOverrides =
 pub type ProviderRequestProfileOverrideUpdates =
     BTreeMap<ProviderKind, Option<gateway_core::account::OpaqueProviderData>>;
 
-/// Client Key 列表保持旧 HTTP 合同允许的完整非零 `u16` 页大小。
+/// Client Key 关联分组的数量与唯一性约束
+pub fn validate_group_ids(group_ids: &[AccountGroupId]) -> Result<(), AdminModelError> {
+    if group_ids.len() > 1000
+        || group_ids
+            .iter()
+            .collect::<std::collections::BTreeSet<_>>()
+            .len()
+            != group_ids.len()
+    {
+        return Err(AdminModelError::InvalidClientKeyGroups);
+    }
+    Ok(())
+}
+
+/// Client Key 列表保持旧 HTTP 合同允许的完整非零 `u16` 页大小
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct ClientKeyPageSize(NonZeroU16);
 
 impl ClientKeyPageSize {
-    /// 创建 1 至 65535 的 Client Key 页大小。
+    /// 创建 1 至 65535 的 Client Key 页大小
     ///
     /// # Errors
     ///
-    /// `value` 为零时返回 [`AdminModelError::InvalidClientKeyPageSize`]。
+    /// `value` 为零时返回 [`AdminModelError::InvalidClientKeyPageSize`]
     pub fn new(value: u16) -> Result<Self, AdminModelError> {
         NonZeroU16::new(value)
             .map(Self)
@@ -42,7 +56,7 @@ impl ClientKeyPageSize {
     }
 }
 
-/// Client Key 列表排序字段。
+/// Client Key 列表排序字段
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ClientKeySortField {
     Name,
@@ -51,21 +65,21 @@ pub enum ClientKeySortField {
     LastUsedAt,
 }
 
-/// Client Key 列表排序方向。
+/// Client Key 列表排序方向
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SortDirection {
     Asc,
     Desc,
 }
 
-/// Client Key 列表排序规则。
+/// Client Key 列表排序规则
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ClientKeySort {
     pub field: ClientKeySortField,
     pub direction: SortDirection,
 }
 
-/// 与排序字段绑定的游标值。
+/// 与排序字段绑定的游标值
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ClientKeyCursorValue {
     Name(String),
@@ -74,7 +88,7 @@ pub enum ClientKeyCursorValue {
     LastUsedAt(Option<DateTime<Utc>>),
 }
 
-/// Client Key 的稳定键集游标。
+/// Client Key 的稳定键集游标
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientKeyCursor {
     pub sort: ClientKeySort,
@@ -82,7 +96,7 @@ pub struct ClientKeyCursor {
     pub id: ClientApiKeyId,
 }
 
-/// Client Key 列表查询。
+/// Client Key 列表查询
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientKeyListQuery {
     pub cursor: Option<ClientKeyCursor>,
@@ -91,7 +105,7 @@ pub struct ClientKeyListQuery {
     pub sort: ClientKeySort,
 }
 
-/// 不含完整明文 Key 的管理投影。
+/// 不含完整明文 Key 的管理投影
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientKeyRecord {
     pub request_profile_overrides: ProviderRequestProfileOverrides,
@@ -109,7 +123,7 @@ pub struct ClientKeyRecord {
     pub updated_at: DateTime<Utc>,
 }
 
-/// Client Key 列表页。
+/// Client Key 列表页
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientKeyPage {
     pub config_revision: Revision,
@@ -118,7 +132,7 @@ pub struct ClientKeyPage {
     pub next_cursor: Option<ClientKeyCursor>,
 }
 
-/// 仅在创建或显式读取密钥配置时返回的明文 Key；Debug 隐去明文。
+/// 仅在创建或显式读取密钥配置时返回的明文 Key；Debug 隐去明文
 #[derive(Clone, PartialEq, Eq)]
 pub struct ClientKeySecret {
     pub record: ClientKeyRecord,
@@ -150,7 +164,7 @@ impl fmt::Debug for ClientKeySecret {
     }
 }
 
-/// API 提交的 Client Key 创建命令。
+/// API 提交的 Client Key 创建命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CreateClientKey {
     pub request_profile_overrides: ProviderRequestProfileOverrides,
@@ -162,7 +176,7 @@ pub struct CreateClientKey {
     pub budget: ClientBudgetLimits,
 }
 
-/// 管理用例生成 ID 与明文后的持久化命令。
+/// 管理用例生成 ID 与明文后的持久化命令
 #[derive(Clone, PartialEq, Eq)]
 pub struct NewClientKey {
     pub request_profile_overrides: ProviderRequestProfileOverrides,
@@ -187,7 +201,7 @@ impl fmt::Debug for NewClientKey {
     }
 }
 
-/// 修改 Client Key 的公开策略字段。
+/// 修改 Client Key 的公开策略字段
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UpdateClientKey {
     pub request_profile_override_updates: ProviderRequestProfileOverrideUpdates,
@@ -200,14 +214,14 @@ pub struct UpdateClientKey {
     pub weekly_limit_usd: Option<gateway_core::metering::Decimal>,
 }
 
-/// 修改 Client Key 启用状态。
+/// 修改 Client Key 启用状态
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SetClientKeyEnabled {
     pub id: ClientApiKeyId,
     pub enabled: bool,
 }
 
-/// 管理员选择的金额重置范围。
+/// 管理员选择的金额重置范围
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ClientKeyBudgetPeriod {
     Daily,
@@ -215,14 +229,14 @@ pub enum ClientKeyBudgetPeriod {
     All,
 }
 
-/// 清零所选窗口已用金额，保留限额、到期时间与历史费用。
+/// 清零所选窗口已用金额，保留限额、到期时间与历史费用
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ResetClientKeyBudget {
     pub id: ClientApiKeyId,
     pub period: ClientKeyBudgetPeriod,
 }
 
-/// 仅更新指定金额上限；省略的周期保持不变，不修改已用金额或窗口。
+/// 仅更新指定金额上限；省略的周期保持不变，不修改已用金额或窗口
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UpdateClientKeyBudgetLimits {
     pub id: ClientApiKeyId,
@@ -230,20 +244,20 @@ pub struct UpdateClientKeyBudgetLimits {
     pub weekly_limit_usd: Option<gateway_core::metering::Decimal>,
 }
 
-/// 预算变更的调用来源；插件身份由 Runtime 给出，不能从插件请求反序列化。
+/// 预算变更的调用来源；插件身份由 Runtime 给出，不能从插件请求反序列化
 #[derive(Debug, Clone)]
 pub enum ClientKeyBudgetMutationOrigin {
     Admin,
     Plugin(PluginResourceOwner),
 }
 
-/// 删除 Client Key。
+/// 删除 Client Key
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DeleteClientKey {
     pub id: ClientApiKeyId,
 }
 
-/// Client Key 创建结果；完整明文仅存在于该一次性结果中。
+/// Client Key 创建结果；完整明文仅存在于该一次性结果中
 pub struct CreatedClientKey {
     pub config_revision: Revision,
     pub secret: ClientKeySecret,
@@ -259,7 +273,7 @@ impl fmt::Debug for CreatedClientKey {
     }
 }
 
-/// Client Key 普通写操作结果。
+/// Client Key 普通写操作结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientKeyMutation {
     pub config_revision: Revision,

backend/crates/gateway-admin/src/model/diagnostics.rs

@@ -0,0 +1,44 @@
+//! 故障诊断导出的目标、已采集证据与缺口
+
+use chrono::{DateTime, Utc};
+
+use super::{
+    observability::{OpsError, UsageDetail},
+    system::SystemVersion,
+};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DiagnosticTarget {
+    Request(String),
+    Operation(String),
+}
+
+impl DiagnosticTarget {
+    #[must_use]
+    pub fn id(&self) -> &str {
+        match self {
+            Self::Request(id) | Self::Operation(id) => id,
+        }
+    }
+}
+
+pub struct DiagnosticGap {
+    pub section: String,
+    pub reason: &'static str,
+}
+
+pub struct DiagnosticRequest {
+    pub request_id: String,
+    pub detail: Option<UsageDetail>,
+    pub errors: Vec<OpsError>,
+}
+
+/// 原始受控详情只能经导出投影脱敏后交付，不参与普通日志或 Debug
+pub struct DiagnosticBundle {
+    pub target: DiagnosticTarget,
+    pub collected_at: DateTime<Utc>,
+    pub environment: Option<SystemVersion>,
+    pub error: Option<OpsError>,
+    pub requests: Vec<DiagnosticRequest>,
+    pub gaps: Vec<DiagnosticGap>,
+}

backend/crates/gateway-admin/src/model/import_tasks.rs

@@ -1,4 +1,4 @@
-//! 进程内账号导入任务；只保存执行所需输入与可公开的结果。
+//! 进程内账号导入任务；只保存执行所需输入与可公开的结果
 
 use chrono::{DateTime, Utc};
 use gateway_core::{account::ProviderAccountId, routing::ProviderKind};
@@ -17,7 +17,7 @@ pub struct ImportTaskInput {
 #[derive(Debug)]
 pub struct SubmitImportTask {
     pub submission_id: Uuid,
-    /// API 对完整输入计算摘要；用于区分丢失响应后的重试与修改后的新提交。
+    /// API 对完整输入计算摘要；用于区分丢失响应后的重试与修改后的新提交
     pub fingerprint: [u8; 32],
     pub context: MutationContext,
     pub items: Vec<ImportTaskInput>,

backend/crates/gateway-admin/src/model/key_usage.rs

@@ -1,10 +1,10 @@
-//! 单页 Key 用量的查询合同；身份范围不由调用方提供。
+//! 单页 Key 用量的查询合同；身份范围不由调用方提供
 
 use super::{
-    PageSize,
     client_keys::ClientKeyRecord,
     observability::{
-        HealthTimeline, OpsErrorPage, RequestMetricPoint, TimeRange, UsageOverview, UsagePage,
+        HealthTimeline, ObservabilityPageSize, RequestMetricPoint, TimeRange, UsageOverview,
+        UsagePage,
     },
 };
 
@@ -18,6 +18,7 @@ pub struct KeyUsageQuery {
 pub enum KeyUsageRecordKind {
     Success,
     Error,
+    All,
 }
 
 #[derive(Debug, Clone)]
@@ -25,7 +26,7 @@ pub struct KeyUsageRecordsQuery {
     pub usage: KeyUsageQuery,
     pub kind: KeyUsageRecordKind,
     pub current_page: u32,
-    pub page_size: PageSize,
+    pub page_size: ObservabilityPageSize,
 }
 
 pub struct KeyUsageOverview {
@@ -35,7 +36,4 @@ pub struct KeyUsageOverview {
     pub health_timeline: HealthTimeline,
 }
 
-pub enum KeyUsageRecords {
-    Success(UsagePage),
-    Error(OpsErrorPage),
-}
+pub type KeyUsageRecords = UsagePage;

backend/crates/gateway-admin/src/model/mod.rs

@@ -1,14 +1,16 @@
-//! 管理控制面使用的 Command、Result 与稳定值对象。
+//! 管理控制面使用的 Command、Result 与稳定值对象
 
 use std::num::{NonZeroU16, NonZeroU64};
 
 pub mod account_groups;
 pub mod accounts;
+pub mod analytics;
 pub mod audit;
 pub mod auth;
 pub mod backup;
 pub mod client_distribution;
 pub mod client_keys;
+pub mod diagnostics;
 pub mod import_tasks;
 pub mod key_usage;
 pub mod observability;
@@ -20,11 +22,13 @@ pub mod provider_credentials;
 pub mod proxies;
 pub mod quota_forecast;
 pub mod quota_forecast_sampling;
+pub mod reset_credit_automation;
 pub mod retention;
 pub mod settings;
 pub mod system;
+pub mod usage_data;
 
-/// 管理用例对外返回的稳定错误分类。
+/// 管理用例对外返回的稳定错误分类
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AdminErrorKind {
     Invalid,
@@ -39,12 +43,31 @@ pub enum AdminErrorKind {
     Internal,
 }
 
-/// 不携带基础设施细节、可安全返回给管理员的管理用例错误。
-#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+impl AdminErrorKind {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Invalid => "invalid",
+            Self::Forbidden => "forbidden",
+            Self::Unauthorized => "unauthorized",
+            Self::NotFound => "not_found",
+            Self::Conflict => "conflict",
+            Self::RateLimited => "rate_limited",
+            Self::BadGateway => "bad_gateway",
+            Self::UpstreamResultUnknown => "upstream_result_unknown",
+            Self::Unavailable => "unavailable",
+            Self::Internal => "internal",
+        }
+    }
+}
+
+/// 管理用例的安全消息与内部原因分离，原始来源不进入响应
+#[derive(Debug, Clone, thiserror::Error)]
 #[error("{message}")]
 pub struct AdminError {
     kind: AdminErrorKind,
     message: String,
+    source: Option<gateway_core::error::ErrorSource>,
 }
 
 impl AdminError {
@@ -53,15 +76,27 @@ impl AdminError {
         Self {
             kind,
             message: message.into(),
+            source: None,
         }
     }
 
+    #[must_use]
+    pub fn with_source(mut self, source: impl Into<gateway_core::error::ErrorSource>) -> Self {
+        self.source = Some(source.into());
+        self
+    }
+
+    #[must_use]
+    pub fn error_details(&self) -> Option<gateway_core::error::ErrorDetails> {
+        gateway_core::error::ErrorDetails::capture(self.source.as_ref(), None, false)
+    }
+
     #[must_use]
     pub const fn kind(&self) -> AdminErrorKind {
         self.kind
     }
 
-    /// 返回已脱敏、可公开给管理员的文案。
+    /// 返回已脱敏、可公开给管理员的文案
     #[must_use]
     pub fn message(&self) -> &str {
         &self.message
@@ -108,7 +143,7 @@ impl AdminError {
     }
 }
 
-/// PostgreSQL 中所有正整数 revision 的管理层表示。
+/// PostgreSQL 中所有正整数 revision 的管理层表示
 #[derive(
     Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize,
 )]
@@ -116,11 +151,11 @@ impl AdminError {
 pub struct Revision(NonZeroU64);
 
 impl Revision {
-    /// 创建正整数 revision。
+    /// 创建正整数 revision
     ///
     /// # Errors
     ///
-    /// `value` 为零时返回 [`AdminModelError::ZeroRevision`]。
+    /// `value` 为零时返回 [`AdminModelError::ZeroRevision`]
     pub fn new(value: u64) -> Result<Self, AdminModelError> {
         NonZeroU64::new(value)
             .map(Self)
@@ -133,18 +168,18 @@ impl Revision {
     }
 }
 
-/// 管理列表统一使用的受限页大小。
+/// 管理列表统一使用的受限页大小
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct PageSize(NonZeroU16);
 
 impl PageSize {
     pub const MAX: u16 = 200;
 
-    /// 创建 1 至 200 的页大小。
+    /// 创建 1 至 200 的页大小
     ///
     /// # Errors
     ///
-    /// `value` 不在有效范围时返回 [`AdminModelError::InvalidPageSize`]。
+    /// `value` 不在有效范围时返回 [`AdminModelError::InvalidPageSize`]
     pub fn new(value: u16) -> Result<Self, AdminModelError> {
         if value > Self::MAX {
             return Err(AdminModelError::InvalidPageSize(value));
@@ -160,7 +195,7 @@ impl PageSize {
     }
 }
 
-/// 可审计管理写操作的发起者。
+/// 可审计管理写操作的发起者
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 #[serde(rename_all = "snake_case", deny_unknown_fields)]
 pub enum MutationActor {
@@ -169,7 +204,7 @@ pub enum MutationActor {
     System,
 }
 
-/// 管理写操作必须携带的审计上下文。
+/// 管理写操作必须携带的审计上下文
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 #[serde(rename_all = "snake_case", deny_unknown_fields)]
 pub struct MutationContext {
@@ -177,13 +212,19 @@ pub struct MutationContext {
     pub request_id: String,
 }
 
-/// 领域值对象构造失败。
+/// 领域值对象构造失败
 #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
 pub enum AdminModelError {
     #[error("revision must be greater than zero")]
     ZeroRevision,
     #[error("page size {0} is outside 1..=200")]
     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")]
     InvalidClientKeyPageSize,
     #[error("request outcome must be 1..=256 bytes without control characters")]

backend/crates/gateway-admin/src/model/plugin_client_keys.rs

@@ -1,11 +1,11 @@
-//! 插件可见的 Client Key 非秘密资源投影。
+//! 插件可见的 Client Key 非秘密资源投影
 
 use gateway_core::policy::ClientApiKeyId;
 use gateway_core::routing::AccountGroupId;
 
 use super::PageSize;
 
-/// 插件可读取的当前 Key 范围，不含密钥或配置秘密。
+/// 插件可读取的当前 Key 范围，不含密钥或配置秘密
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginClientKeyFacts {
     pub id: ClientApiKeyId,
@@ -25,7 +25,7 @@ pub struct PluginClientKeyListQuery {
     pub limit: PageSize,
 }
 
-/// 插件只能发现调用所需的公开身份，不取得 Key 前缀、策略细节或明文。
+/// 插件只能发现调用所需的公开身份，不取得 Key 前缀、策略细节或明文
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginClientKey {
     pub id: ClientApiKeyId,

backend/crates/gateway-admin/src/model/plugin_resources.rs

@@ -1,4 +1,4 @@
-//! 插件资源归属由宿主调用上下文给出，不能由插件参数选择实例或代次。
+//! 插件资源归属由宿主调用上下文给出，不能由插件参数选择实例或代次
 
 use super::Revision;
 
@@ -17,7 +17,7 @@ pub struct ManagedResource {
 }
 
 pub struct ResourceMutation<T> {
-    /// 没有事实变化时不递增配置 revision，也不触发发布。
+    /// 没有事实变化时不递增配置 revision，也不触发发布
     pub revision: Option<Revision>,
     pub value: T,
 }
@@ -34,7 +34,7 @@ pub struct GroupMembersChanged {
     pub removed: u64,
 }
 
-/// 插件 Key 的首次创建设置；分组始终从本实例资源键解析。
+/// 插件 Key 的首次创建设置；分组始终从本实例资源键解析
 pub struct ManagedKeyConfig {
     pub name: String,
     pub limits: gateway_core::policy::RateLimits,

backend/crates/gateway-admin/src/model/plugins/distribution.rs

@@ -1,3 +1,5 @@
+//! 插件分发来源、下载凭据、发行查询与远程安装的数据合同
+
 use std::{fmt, sync::Arc};
 
 use chrono::{DateTime, Utc};
@@ -17,7 +19,7 @@ pub enum PluginUpdateSource {
     Github { repository: String },
 }
 
-/// 检查策略只决定查询目标，任何策略都不会自动安装或切换运行实例。
+/// 检查策略只决定查询目标，任何策略都不会自动安装或切换运行实例
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
 pub enum PluginUpdatePolicy {
@@ -85,7 +87,7 @@ impl fmt::Debug for PluginDistributionEgress {
 #[serde(rename_all = "camelCase")]
 pub struct PluginUpdateCheck {
     pub binding: PluginSourceBinding,
-    /// Release 元数据不是已校验的插件包，不据此声明平台或 SDK 兼容。
+    /// Release 元数据不是已校验的插件包，不据此声明平台或 SDK 兼容
     pub release: PluginRelease,
 }
 
@@ -109,7 +111,7 @@ pub enum DownloadPurpose {
     Artifact,
 }
 
-/// 授权目标以完整 origin 和路径段边界匹配；摘要、名称和列表均不包含 secret。
+/// 授权目标以完整 origin 和路径段边界匹配；摘要、名称和列表均不包含 secret
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct SourceCredentialInfo {
@@ -174,7 +176,7 @@ pub struct PluginRelease {
     pub expires_at: DateTime<Utc>,
 }
 
-/// 下载意图不承载凭据；引用在 Admin 中解析后只交给 Host 的本次调用。
+/// 下载意图不承载凭据；引用在 Admin 中解析后只交给 Host 的本次调用
 #[derive(Debug, Clone, Deserialize)]
 #[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
 pub enum RemotePluginLocation {
@@ -200,7 +202,7 @@ pub struct RemotePluginVerify {
     pub credential_ids: Vec<String>,
     #[serde(default)]
     pub outbound_proxy_id: Option<String>,
-    /// 更新已有插件时锁定身份；首次安装从包内清单读取。
+    /// 更新已有插件时锁定身份；首次安装从包内清单读取
     pub expected_plugin_id: Option<String>,
 }
 
@@ -222,7 +224,7 @@ pub struct DownloadedPlugin {
     pub source: PluginSource,
 }
 
-/// 只读包校验结果，不代表实例配置、授权或私有状态已完成运行时准备。
+/// 只读包校验结果，不代表实例配置、授权或私有状态已完成运行时准备
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct VerifiedPluginArtifact {

backend/crates/gateway-admin/src/model/plugins/instances.rs

@@ -1,3 +1,5 @@
+//! 插件实例配置、能力绑定、运行状态与版本切换的数据合同
+
 use std::collections::BTreeMap;
 
 use secrecy::SecretString;
@@ -20,7 +22,7 @@ pub struct PluginCapabilityBinding {
     pub stage: String,
     pub order: i32,
     pub failure_policy: PluginFailurePolicy,
-    /// 观察绑定选择事件类型；其他能力不设置事件。
+    /// 观察绑定选择事件类型；其他能力不设置事件
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub event: Option<String>,
     #[serde(default)]
@@ -35,7 +37,7 @@ pub struct PluginCapabilityBinding {
     pub identity_bindings: Vec<PluginFrontendIdentityBinding>,
 }
 
-/// 外部 principal 到既有 Client Key 的显式宿主映射。
+/// 外部 principal 到既有 Client Key 的显式宿主映射
 #[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct PluginFrontendIdentityBinding {
@@ -53,7 +55,7 @@ impl std::fmt::Debug for PluginFrontendIdentityBinding {
     }
 }
 
-/// 配置和 secret 分离；Debug 与 Serialize 不得无意展开实例配置。
+/// 配置和 secret 分离；Debug 与 Serialize 不得无意展开实例配置
 #[derive(Clone)]
 pub struct PluginInstance {
     pub id: String,
@@ -78,7 +80,7 @@ pub struct PluginInstanceMutation {
     pub instance: PluginInstance,
 }
 
-/// 控制面展示的单实例运行状态；它描述当前进程观察到的事实，不替代持久启用配置。
+/// 控制面展示的单实例运行状态；它描述当前进程观察到的事实，不替代持久启用配置
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum PluginInstanceRuntimeStatus {
     Disabled,
@@ -91,14 +93,14 @@ pub enum PluginInstanceRuntimeStatus {
     Draining,
 }
 
-/// 已脱敏且可安全返回给管理员的运行失败摘要。
+/// 已脱敏且可安全返回给管理员的运行失败摘要
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginInstanceRuntimeFailure {
     pub code: String,
     pub message: String,
 }
 
-/// 当前发布视图与代次索引的只读诊断。
+/// 当前发布视图与代次索引的只读诊断
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginInstanceRuntime {
     pub status: PluginInstanceRuntimeStatus,
@@ -108,10 +110,24 @@ pub struct PluginInstanceRuntime {
     pub draining_revisions: Vec<u64>,
 }
 
+/// 可继续运行的旧接口提示，与无法启用的兼容性错误分开
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginApiDeprecation {
+    pub capability: String,
+    pub version: u32,
+    pub replacement_version: u32,
+    pub introduced_in: Option<String>,
+    pub remaining_releases: u32,
+    pub migration: String,
+}
+
 pub struct PluginInstanceView {
     pub instance: PluginInstance,
     pub configuration_required: bool,
     pub compatibility_warning: Option<String>,
+    pub load_error: Option<String>,
+    pub api_deprecations: Vec<PluginApiDeprecation>,
     pub running: bool,
     pub published_revision: Option<u64>,
     pub runtime: PluginInstanceRuntime,
@@ -120,18 +136,18 @@ pub struct PluginInstanceView {
 #[derive(Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct ConfigurePluginInstance {
-    /// 创建草稿固定一个 UUID，重试复用同一配置，不能作为编辑已有配置的入口。
+    /// 创建草稿固定一个 UUID，重试复用同一配置，不能作为编辑已有配置的入口
     pub creation_id: Option<String>,
-    /// 编辑时检查用户看到的配置版本，避免覆盖另一窗口已经保存的内容。
+    /// 编辑时检查用户看到的配置版本，避免覆盖另一窗口已经保存的内容
     pub expected_revision: Option<u64>,
-    /// 管理员确认停用的同插件配置，与当前配置在同一事务中切换。
+    /// 管理员确认停用的同插件配置，与当前配置在同一事务中切换
     #[serde(default)]
     pub replace_instances: Vec<PluginInstanceReplacement>,
     pub name: String,
     pub artifact_sha256: String,
     pub enabled: bool,
     pub configuration: serde_json::Value,
-    /// 缺省保留旧值；显式空对象清除全部 secret。
+    /// 缺省保留旧值；显式空对象清除全部 secret
     pub secrets: Option<BTreeMap<String, SecretString>>,
     pub bindings: Vec<PluginCapabilityBinding>,
 }
@@ -143,7 +159,7 @@ pub struct PluginInstanceReplacement {
     pub expected_revision: u64,
 }
 
-/// 恢复已安装旧版本的配置快照，并重新通过目标版本校验。
+/// 恢复已安装旧版本的配置快照，并重新通过目标版本校验
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct RollbackPluginInstance {
@@ -159,7 +175,7 @@ pub struct PluginRollbackTarget {
     pub platforms: Vec<String>,
 }
 
-/// 静态候选不启动插件；实际回滚仍须复验配置、平台和私有状态兼容性。
+/// 静态候选不启动插件；实际回滚仍须复验配置、平台和私有状态兼容性
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PluginRollbackPlan {
@@ -168,7 +184,7 @@ pub struct PluginRollbackPlan {
     pub targets: Vec<PluginRollbackTarget>,
 }
 
-/// 版本配置快照只用于服务端恢复，敏感值不实现 Debug 或 Serialize。
+/// 版本配置快照只用于服务端恢复，敏感值不实现 Debug 或 Serialize
 #[derive(Clone)]
 pub struct PluginVersionConfiguration {
     pub configuration: serde_json::Value,
@@ -176,7 +192,7 @@ pub struct PluginVersionConfiguration {
     pub bindings: Vec<PluginCapabilityBinding>,
 }
 
-/// 切换版本的只读草稿，不包含密钥值，也不会启动插件或写入配置。
+/// 切换版本的只读草稿，不包含密钥值，也不会启动插件或写入配置
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PluginVersionPlan {

backend/crates/gateway-admin/src/model/plugins/management.rs

@@ -1,8 +1,10 @@
+//! 插件管理页面、静态资源、请求与授权回调的数据合同
+
 use std::sync::Arc;
 
 use serde::{Deserialize, Serialize};
 
-/// 页面和业务调用绑定同一实例版本；制品摘要单独作为不可变资源身份。
+/// 页面和业务调用绑定同一实例版本；制品摘要单独作为不可变资源身份
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct PluginManagementTarget {
@@ -37,7 +39,7 @@ pub struct StartPluginManagementCallback {
     pub ttl_seconds: u32,
 }
 
-/// state 是短期一次性秘密，只交给发起登录的管理员，不进入 Debug 或日志。
+/// state 是短期一次性秘密，只交给发起登录的管理员，不进入 Debug 或日志
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PluginManagementCallbackTicket {
@@ -72,8 +74,9 @@ pub struct PluginManagementResource {
     pub public: bool,
 }
 
-/// 原始正文可能含业务数据，不能派生内容型 Debug 或写入诊断日志。
+/// 原始正文可能含业务数据，不能派生内容型 Debug 或写入诊断日志
 pub struct PluginManagementRequest {
+    pub request_context: Option<std::sync::Arc<gateway_core::engine::extensions::RequestContext>>,
     pub method: String,
     pub path: String,
     pub query: String,

backend/crates/gateway-admin/src/model/plugins/mod.rs

@@ -1,3 +1,5 @@
+//! 插件制品元数据、宿主兼容性与管理领域模型的公共入口
+
 use std::{
     collections::{BTreeMap, BTreeSet},
     sync::Arc,
@@ -13,7 +15,7 @@ pub mod management;
 pub mod official;
 pub mod state;
 
-/// 一个宿主发行版明确承诺支持的插件能力版本。
+/// 一个宿主发行版明确承诺支持的插件能力版本
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct PluginHostCapability {
@@ -21,7 +23,7 @@ pub struct PluginHostCapability {
     pub versions: Vec<u32>,
 }
 
-/// 随宿主发行物封口的插件合同；Runtime 与发布清单共用这一份声明。
+/// 随宿主发行物封口的插件合同；Runtime 与发布清单共用这一份声明
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct PluginHostCompatibility {
@@ -32,7 +34,7 @@ pub struct PluginHostCompatibility {
 }
 
 impl PluginHostCompatibility {
-    /// 拒绝空集合、重复项和不受控标识，避免发行清单把“未知”解释为通配。
+    /// 拒绝空集合、重复项和不受控标识，避免发行清单把“未知”解释为通配
     #[must_use]
     pub fn is_valid(&self) -> bool {
         if self.schema_version != 2
@@ -101,7 +103,7 @@ fn valid_plugin_segment(value: &str) -> bool {
             .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
 }
 
-/// 已安装包对目标宿主的静态要求；不包含包体、配置或 secret。
+/// 已安装包对目标宿主的静态要求；不包含包体、配置或 secret
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginCompatibilityRequirements {
     pub host_version: String,
@@ -110,7 +112,7 @@ pub struct PluginCompatibilityRequirements {
     pub capabilities: Vec<(String, u32)>,
 }
 
-/// 一次下载使用的非敏感出站代理身份；地址与认证由受管代理记录持有。
+/// 一次下载使用的非敏感出站代理身份；地址与认证由受管代理记录持有
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct PluginSourceEgress {
@@ -118,7 +120,7 @@ pub struct PluginSourceEgress {
     pub revision: u64,
 }
 
-/// 安装来源只保存公开定位信息，下载凭据和出站代理通过独立记录引用。
+/// 安装来源只保存公开定位信息，下载凭据和出站代理通过独立记录引用
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
 pub enum PluginSource {
@@ -164,7 +166,7 @@ impl PluginSource {
     }
 }
 
-/// 管理端保留的单项贡献声明；map key 是能力标识，`id` 是实例绑定引用的扩展项身份。
+/// 管理端保留的单项贡献声明；map key 是能力标识，`id` 是实例绑定引用的扩展项身份
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PluginContribution {
@@ -178,7 +180,7 @@ pub struct PluginContribution {
     pub output_formats: Vec<String>,
 }
 
-/// 制品清单中的展示图标；路径只用于选择已校验的包资源。
+/// 制品清单中的展示图标；路径只用于选择已校验的包资源
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(untagged)]
 pub enum PluginArtifactIcon {
@@ -198,15 +200,15 @@ pub enum PluginIconTheme {
     Dark,
 }
 
-/// 从不可变制品中读取的已校验图标字节。
+/// 从不可变制品中读取的已校验图标字节
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginArtifactIconResource {
     pub content_type: String,
     pub body: Vec<u8>,
 }
 
-/// 已校验制品的持久化投影；读取时忽略未知字段，可选字段缺省沿用清单语义。
-/// 身份与执行所需事实仍为必填，包清单及协议版本由 Runtime 独立校验。
+/// 已校验制品的持久化投影；读取时忽略未知字段，可选字段缺省沿用清单语义
+/// 身份与执行所需事实仍为必填，包清单及协议版本由 Runtime 独立校验
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PluginArtifactMetadata {
@@ -235,7 +237,7 @@ fn empty_configuration_schema() -> serde_json::Value {
     serde_json::json!({})
 }
 
-/// 由包检查端口产生的不可变制品；不派生 Debug，包内可能含敏感用户数据。
+/// 由包检查端口产生的不可变制品；不派生 Debug，包内可能含敏感用户数据
 #[derive(Clone)]
 pub struct InspectedPluginArtifact {
     pub metadata: PluginArtifactMetadata,

backend/crates/gateway-admin/src/model/plugins/official.rs

@@ -1,13 +1,15 @@
+//! 官方插件发行身份与导入命令
+
 use super::super::Revision;
 
-/// 编译进宿主二进制的发行身份；不能由运行时配置或插件清单覆盖。
+/// 编译进宿主二进制的发行身份；不能由运行时配置或插件清单覆盖
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct OfficialPluginReleaseIdentity {
     pub gateway_version: String,
     pub gateway_git_sha: String,
 }
 
-/// 启动时导入官方制品的结果；导入只持久化制品，不创建或启用实例。
+/// 启动时导入官方制品的结果；导入只持久化制品，不创建或启用实例
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct OfficialPluginImport {
     pub artifacts: usize,

backend/crates/gateway-admin/src/model/plugins/state.rs

@@ -1,10 +1,12 @@
-use std::{collections::BTreeMap, fmt};
+//! 插件私有状态的归属、代次隔离与迁移数据合同
+
+use std::{collections::BTreeMap, fmt, sync::Arc};
 
 use serde::{Deserialize, Serialize};
 
 use crate::model::Revision;
 
-/// 已由 Runtime 校验的命名空间 schema 与配额事实。
+/// 已由 Runtime 校验的命名空间 schema 与配额事实
 #[derive(Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PluginStateSchema {
@@ -42,7 +44,7 @@ pub struct PluginStateConfiguration {
     pub namespaces: Vec<PluginStateSchema>,
 }
 
-/// 与实例保存同事务提交的状态配置；transition 只引用已完成的 staging 数据。
+/// 与实例保存同事务提交的状态配置；transition 只引用已完成的 staging 数据
 #[derive(Clone, Default)]
 pub struct PluginStateCommit {
     pub configuration: PluginStateConfiguration,
@@ -57,7 +59,8 @@ pub struct PluginStateOwnerRequest {
     pub configuration: PluginStateConfiguration,
 }
 
-/// Store 签发的实例私有状态 fence。插件协议中从不传输这些字段。
+/// Store 签发的实例私有状态 fence
+/// 插件协议中从不传输这些字段
 #[derive(Clone)]
 pub struct PluginStateOwner {
     instance_id: String,
@@ -136,7 +139,7 @@ impl PluginStateNamespaceOwner {
     }
 }
 
-/// 私有值可能含插件自己的敏感状态，故意不实现 `Debug`。
+/// 私有值可能含插件自己的敏感状态，故意不实现 `Debug`
 #[derive(Clone)]
 pub struct PluginStateRecord {
     pub key: String,
@@ -149,7 +152,7 @@ pub struct PutPluginState {
     pub namespace: String,
     pub key: String,
     pub value: serde_json::Value,
-    /// `None` 是 create-only；已有记录必须提交精确版本。
+    /// `None` 是 create-only；已有记录必须提交精确版本
     pub expected_version: Option<u64>,
 }
 
@@ -170,6 +173,8 @@ pub struct PluginStateTransition {
     pub instance_id: String,
     pub artifact_sha256: String,
     pub namespaces: Vec<PluginStateMigrationNamespace>,
+    /// Store 持有的迁移所有权；最后一个调用持有者释放后允许回收遗留 staging
+    pub guard: Arc<dyn Send + Sync>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -188,7 +193,7 @@ pub struct ApplyPluginStateMigration {
     pub transition_id: String,
     pub namespace: String,
     pub cursor: Option<String>,
-    /// Runtime 刚读取的有序源键；Store 会在写入前重新读取并逐项比对。
+    /// Runtime 刚读取的有序源键；Store 会在写入前重新读取并逐项比对
     pub expected_keys: Vec<String>,
     pub changes: Vec<PluginStateMigrationChange>,
 }

backend/crates/gateway-admin/src/model/pricing.rs

@@ -1,4 +1,4 @@
-//! 全局模型定价的管理合同。
+//! 全局模型定价的管理合同
 
 use gateway_core::metering::{ModelPriceOverride, PricingOverrides};
 use std::collections::{BTreeMap, BTreeSet};

backend/crates/gateway-admin/src/model/provider_credentials.rs

@@ -1,4 +1,4 @@
-//! Provider 管理能力交换的中立 Command 与 Result。
+//! Provider 管理能力交换的中立 Command 与 Result
 
 use std::{fmt, pin::Pin};
 
@@ -22,7 +22,7 @@ use super::{
     },
 };
 
-/// Provider-owned JSON；公共层只搬运且 Debug 不输出值。
+/// Provider-owned JSON；公共层只搬运且 Debug 不输出值
 #[derive(Clone, PartialEq)]
 pub struct ProviderDocument(OpaqueProviderData);
 
@@ -32,7 +32,7 @@ impl ProviderDocument {
         Self(data)
     }
 
-    /// 仅具体 Provider 可以解释内部字段。
+    /// 仅具体 Provider 可以解释内部字段
     #[must_use]
     pub const fn expose_to_provider(&self) -> &OpaqueProviderData {
         &self.0
@@ -50,14 +50,14 @@ impl fmt::Debug for ProviderDocument {
     }
 }
 
-/// Provider credential 详情。
+/// Provider credential 详情
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialDetails {
     pub config_revision: Revision,
     pub credential: AccountRecord,
 }
 
-/// Provider 正式文档批量导入命令。
+/// Provider 正式文档批量导入命令
 pub struct ImportCredentials {
     pub outbound_proxy_id: Option<String>,
     pub settings: Option<AccountImportSettings>,
@@ -75,14 +75,14 @@ impl fmt::Debug for ImportCredentials {
     }
 }
 
-/// 批量导入提交结果。
+/// 批量导入提交结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialImportResult {
     pub config_revision: Revision,
     pub credential_ids: Vec<ProviderAccountId>,
 }
 
-/// Provider 解析导入文档时只接收不透明文档，不接触 revision 或审计上下文。
+/// Provider 解析导入文档时只接收不透明文档，不接触 revision 或审计上下文
 pub struct PrepareCredentialImport {
     pub default_outbound_proxy: Option<gateway_core::account::OutboundProxy>,
     pub document: ProviderDocument,
@@ -97,7 +97,7 @@ impl fmt::Debug for PrepareCredentialImport {
     }
 }
 
-/// Provider 已验证、可由 Store 原子创建的一份 credential。
+/// Provider 已验证、可由 Store 原子创建的一份 credential
 #[derive(Debug, Clone, PartialEq)]
 pub struct PreparedCredentialCreate {
     pub model_access: Option<gateway_core::account::AccountModelAccess>,
@@ -119,14 +119,14 @@ pub struct PreparedCredentialCreate {
     pub credential_observed_at: DateTime<Utc>,
 }
 
-/// Provider 对一份导入文档的完整验证结果。
+/// Provider 对一份导入文档的完整验证结果
 #[derive(Debug, Clone, PartialEq)]
 pub struct PreparedCredentialImport {
     pub provider_kind: ProviderKind,
     pub credentials: Vec<PreparedCredentialCreate>,
 }
 
-/// Admin 交给 Store 的导入事务命令。
+/// Admin 交给 Store 的导入事务命令
 #[derive(Debug, Clone, PartialEq)]
 pub struct CredentialImportCommit {
     pub outbound_proxy: Option<super::proxies::ImportProxyBinding>,
@@ -134,7 +134,7 @@ pub struct CredentialImportCommit {
     pub prepared: PreparedCredentialImport,
 }
 
-/// OAuth pending owner 的中立身份；不编码具体 Provider 的 Redis key 或 JSON。
+/// OAuth pending owner 的中立身份；不编码具体 Provider 的 Redis key 或 JSON
 #[derive(Clone, PartialEq, Eq)]
 pub enum AuthorizationOwner {
     AdminSession { admin_user_id: String },
@@ -148,7 +148,7 @@ impl fmt::Debug for AuthorizationOwner {
     }
 }
 
-/// Provider 写入 pending payload 与 Redis owner binding 所需的全部中立字段。
+/// Provider 写入 pending payload 与 Redis owner binding 所需的全部中立字段
 #[derive(Clone, PartialEq, Eq)]
 pub struct AuthorizationOwnerBinding {
     owner: AuthorizationOwner,
@@ -193,17 +193,17 @@ impl fmt::Debug for AuthorizationOwnerBinding {
     }
 }
 
-/// OAuth 完成时应创建新账号还是 CAS 更新既有 credential。
+/// OAuth 完成时应创建新账号还是 CAS 更新既有 credential
 ///
 /// 重新授权只绑定稳定的账号身份：credential revision 由服务端在临近写入时读取，
-/// 长流程期间的后台刷新不得让恢复操作失效。
+/// 长流程期间的后台刷新不得让恢复操作失效
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AuthorizationMutationTarget {
     Create { name: String },
     Reauthorize { account_id: ProviderAccountId },
 }
 
-/// 必须完整进入 Provider opaque pending payload、并在 complete 后原样恢复的事务信封。
+/// 必须完整进入 Provider opaque pending payload、并在 complete 后原样恢复的事务信封
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PendingAuthorizationMutation {
     provider_kind: ProviderKind,
@@ -269,7 +269,7 @@ impl PendingAuthorizationMutation {
 }
 
 impl PendingAuthorizationMutation {
-    /// 编码 v1 中立事务字段；版本号的位置和 Provider 私有外层文档由 adapter 保持。
+    /// 编码 v1 中立事务字段；版本号的位置和 Provider 私有外层文档由 adapter 保持
     #[must_use]
     pub fn to_storage_v1(&self) -> Map<String, Value> {
         let target = match &self.target {
@@ -311,11 +311,11 @@ impl PendingAuthorizationMutation {
         document
     }
 
-    /// 恢复 adapter 已确认版本为 v1 的中立事务字段。
+    /// 恢复 adapter 已确认版本为 v1 的中立事务字段
     ///
     /// # Errors
     ///
-    /// 文档字段、Provider kind 或账号身份非法时返回错误，不携带原始 pending 内容。
+    /// 文档字段、Provider kind 或账号身份非法时返回错误，不携带原始 pending 内容
     pub fn from_storage_v1(value: Value) -> Result<Self, AdminError> {
         let invalid = || AdminError::invalid("invalid pending authorization mutation");
         let document: StoredAuthorizationMutationV1 =
@@ -385,7 +385,7 @@ enum StoredAuthorizationOwnerV1 {
     System,
 }
 
-/// Provider 授权请求。
+/// Provider 授权请求
 #[derive(Debug, Clone, PartialEq)]
 pub struct StartAuthorization {
     pub context: MutationContext,
@@ -394,7 +394,7 @@ pub struct StartAuthorization {
     pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }
 
-/// OAuth 流程启动结果。
+/// OAuth 流程启动结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AuthorizationStarted {
     pub flow_id: String,
@@ -402,35 +402,37 @@ pub struct AuthorizationStarted {
     pub expires_at: DateTime<Utc>,
 }
 
-/// refresh/rotate/reauthorize 的 lease 或 completion 生命周期。
+/// refresh/rotate/reauthorize 的 lease 或 completion 生命周期
 ///
-/// 该 guard 不可 Clone。Admin 只能在 Store CAS 与审计事务成功后调用 `finish`；失败路径直接
-/// drop，使 Provider 可以释放 lease 或执行补偿。
+/// 该 guard 不可 Clone
+/// Admin 只能在 Store CAS 与审计事务成功后调用 `finish`；失败路径直接
+/// drop，使 Provider 可以释放 lease 或执行补偿
 pub trait CredentialCommitGuard: Send + 'static {
     fn finish(self: Box<Self>);
 }
 
-/// OAuth pending claim 在 Store 事务结果确定后执行的显式结算动作。
+/// OAuth pending claim 在 Store 事务结果确定后执行的显式结算动作
 ///
 /// OAuth provider 必须在 credential 准备阶段持有 claim：Store 提交成功后消费 flow，提交或
-/// 校验失败后释放 flow。异步结算不能依赖 `Drop`，否则请求提前返回会让同一授权流无谓地
-/// 进入短暂的不可重试状态。
+/// 校验失败后释放 flow
+/// 异步结算不能依赖 `Drop`，否则请求提前返回会让同一授权流无谓地
+/// 进入短暂的不可重试状态
 #[async_trait]
 pub trait AuthorizationCommitGuard: Send + 'static {
-    /// Store 已提交 OAuth credential 后消费对应的一次性 flow。
+    /// Store 已提交 OAuth credential 后消费对应的一次性 flow
     async fn commit(self: Box<Self>) -> Result<(), AdminError>;
 
-    /// Store 未提交 OAuth credential 时释放 claim，允许同一 flow 重试。
+    /// Store 未提交 OAuth credential 时释放 claim，允许同一 flow 重试
     async fn abort(self: Box<Self>) -> Result<(), AdminError>;
 }
 
-/// OAuth complete 后由 Provider 返回的准备结果；Store 仍是唯一提交者。
+/// OAuth complete 后由 Provider 返回的准备结果；Store 仍是唯一提交者
 pub enum PreparedAuthorizationCredential {
     Create(Box<PreparedCredentialCreate>),
     Reauthorize(Box<PreparedCredentialRotation>),
 }
 
-/// Provider 从 opaque pending payload 恢复的信封与已验证 credential 必须一起返回。
+/// Provider 从 opaque pending payload 恢复的信封与已验证 credential 必须一起返回
 pub struct PreparedAuthorizationCommit {
     pub pending: PendingAuthorizationMutation,
     pub credential: PreparedAuthorizationCredential,
@@ -447,14 +449,14 @@ impl fmt::Debug for PreparedAuthorizationCommit {
     }
 }
 
-/// Store 可持久化的 OAuth credential facts，不携带 Provider guard。
+/// Store 可持久化的 OAuth credential facts，不携带 Provider guard
 #[derive(Debug, Clone, PartialEq)]
 pub enum AuthorizationCredentialCommit {
     Create(Box<PreparedCredentialCreate>),
     Reauthorize(Box<PreparedCredentialRotationFacts>),
 }
 
-/// Admin 交给 Store 的 OAuth 原子事务命令。
+/// Admin 交给 Store 的 OAuth 原子事务命令
 #[derive(Debug, Clone, PartialEq)]
 pub struct AuthorizationCommit {
     pub key: AuthorizationReceiptKey,
@@ -463,7 +465,7 @@ pub struct AuthorizationCommit {
     pub credential: AuthorizationCredentialCommit,
 }
 
-/// 回执以 Provider、授权流和管理员身份绑定；不持久化原始 flow 或回调材料。
+/// 回执以 Provider、授权流和管理员身份绑定；不持久化原始 flow 或回调材料
 #[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct AuthorizationReceiptKey {
     provider_kind: ProviderKind,
@@ -531,10 +533,10 @@ pub struct AuthorizationCommitResult {
     pub newly_committed: bool,
 }
 
-/// OAuth 准备结果拆解后的 Store 命令与两个结算 guard。
+/// OAuth 准备结果拆解后的 Store 命令与两个结算 guard
 ///
 /// Store 成功时先结束 credential guard，再消费 OAuth claim；失败时丢弃 credential guard 并
-/// 释放 OAuth claim，使同一授权流可以重试。
+/// 释放 OAuth claim，使同一授权流可以重试
 pub(crate) struct AuthorizationCommitSettlement {
     pub(crate) command: AuthorizationCommit,
     pub(crate) credential_guard: Option<Box<dyn CredentialCommitGuard>>,
@@ -554,7 +556,7 @@ impl PreparedAuthorizationCommit {
         }
     }
 
-    /// 让 OAuth claim 覆盖准备完成到 Store 事务结算之间的全部窗口。
+    /// 让 OAuth claim 覆盖准备完成到 Store 事务结算之间的全部窗口
     #[must_use]
     pub fn with_authorization_guard(mut self, guard: Box<dyn AuthorizationCommitGuard>) -> Self {
         self.authorization_guard = Some(guard);
@@ -599,7 +601,7 @@ impl PreparedAuthorizationCommit {
     }
 }
 
-/// 完成 Provider OAuth 流程。
+/// 完成 Provider OAuth 流程
 #[derive(Clone, PartialEq, Eq)]
 pub struct CompleteAuthorization {
     pub settings: Option<AccountImportSettings>,
@@ -619,14 +621,14 @@ impl fmt::Debug for CompleteAuthorization {
     }
 }
 
-/// Credential 生命周期写操作。
+/// Credential 生命周期写操作
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialMutation {
     pub context: MutationContext,
     pub account_id: ProviderAccountId,
 }
 
-/// Credential 写入提交结果。
+/// Credential 写入提交结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialMutationResult {
     pub config_revision: Revision,
@@ -634,28 +636,28 @@ pub struct CredentialMutationResult {
     pub credential_revision: Option<Revision>,
 }
 
-/// 同一 Provider 管理范围内的 credential 批量删除。
+/// 同一 Provider 管理范围内的 credential 批量删除
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialDeletion {
     pub context: MutationContext,
     pub account_ids: Vec<ProviderAccountId>,
 }
 
-/// Credential 批量删除提交结果。
+/// Credential 批量删除提交结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialDeletionResult {
     pub config_revision: Revision,
     pub account_ids: Vec<ProviderAccountId>,
 }
 
-/// Provider-owned token 轮换命令。
+/// Provider-owned token 轮换命令
 pub struct RotateCredential {
     pub mutation: CredentialMutation,
     pub provider_material: ProviderDocument,
     pub settings: Option<super::accounts::UpdateAccount>,
 }
 
-/// Provider 校验手工轮换材料时所需的非事务输入。
+/// Provider 校验手工轮换材料时所需的非事务输入
 pub struct PrepareCredentialRotation {
     pub account: AccountRecord,
     pub provider_material: ProviderDocument,
@@ -671,7 +673,7 @@ impl fmt::Debug for PrepareCredentialRotation {
     }
 }
 
-/// Provider 已验证、可由 Store 以 credential revision CAS 原子提交的轮换 facts。
+/// Provider 已验证、可由 Store 以 credential revision CAS 原子提交的轮换 facts
 #[derive(Debug, Clone, PartialEq)]
 pub struct PreparedCredentialRotationFacts {
     pub account_id: ProviderAccountId,
@@ -681,9 +683,9 @@ pub struct PreparedCredentialRotationFacts {
     pub name: String,
     pub email: Option<String>,
     pub plan_type: Option<String>,
-    /// Token 刷新保留提交时的资料，不以准备阶段的副本覆盖新套餐。
+    /// Token 刷新保留提交时的资料，不以准备阶段的副本覆盖新套餐
     pub preserve_profile: bool,
-    /// 连接配置变更保留当前凭据健康状态与错误事实。
+    /// 连接配置变更保留当前凭据健康状态与错误事实
     pub preserve_credential_state: bool,
     pub provider_material: ProviderDocument,
     pub has_refresh_token: bool,
@@ -691,7 +693,7 @@ pub struct PreparedCredentialRotationFacts {
     pub next_refresh_at: Option<DateTime<Utc>>,
 }
 
-/// Provider 返回的轮换准备结果；guard 必须覆盖后续 Store CAS 与审计事务。
+/// Provider 返回的轮换准备结果；guard 必须覆盖后续 Store CAS 与审计事务
 pub struct PreparedCredentialRotation {
     facts: PreparedCredentialRotationFacts,
     guard: Box<dyn CredentialCommitGuard>,
@@ -706,7 +708,7 @@ impl PreparedCredentialRotation {
         Self { facts, guard }
     }
 
-    /// 仅修改连接配置时，不把配置更新视为凭据恢复成功。
+    /// 仅修改连接配置时，不把配置更新视为凭据恢复成功
     #[must_use]
     pub fn preserving_credential_state(mut self) -> Self {
         self.facts.preserve_credential_state = true;
@@ -739,7 +741,7 @@ impl fmt::Debug for PreparedCredentialRotation {
     }
 }
 
-/// Admin 交给 Store 的轮换或 refresh 事务命令。
+/// Admin 交给 Store 的轮换或 refresh 事务命令
 #[derive(Debug, Clone, PartialEq)]
 pub struct CredentialRotationCommit {
     pub prepared: PreparedCredentialRotationFacts,
@@ -757,16 +759,16 @@ impl fmt::Debug for RotateCredential {
     }
 }
 
-/// 通用账号用量能否可靠归属到一个 Provider quota 窗口。
+/// 通用账号用量能否可靠归属到一个 Provider quota 窗口
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum QuotaLocalUsageAttribution {
-    /// 窗口覆盖账号的全部请求，可按账号与时间范围聚合。
+    /// 窗口覆盖账号的全部请求，可按账号与时间范围聚合
     AccountWide,
-    /// 窗口需要 Provider / 模型级归属，通用账号聚合不可用。
+    /// 窗口需要 Provider / 模型级归属，通用账号聚合不可用
     Unavailable,
 }
 
-/// Provider quota bucket 中窗口的官方位置语义。
+/// Provider quota bucket 中窗口的官方位置语义
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ProviderQuotaWindowRole {
     Primary,
@@ -785,7 +787,7 @@ impl ProviderQuotaWindowRole {
     }
 }
 
-/// 一个 Provider quota 窗口的公共投影。
+/// 一个 Provider quota 窗口的公共投影
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderQuotaWindow {
     pub key: String,
@@ -803,14 +805,14 @@ pub struct ProviderQuotaWindow {
     pub provider_data: Option<ProviderDocument>,
 }
 
-/// 账号用量统计周期，按周优先、月次之选择；短期限流窗口不参与统计面板。
+/// 账号用量统计周期，按周优先、月次之选择；短期限流窗口不参与统计面板
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum AccountUsagePeriod {
     Weekly,
     Monthly,
 }
 
-/// Provider 解释 quota 所需的公共请求事实。
+/// Provider 解释 quota 所需的公共请求事实
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderQuotaRequest {
     pub account_id: ProviderAccountId,
@@ -818,20 +820,36 @@ pub struct ProviderQuotaRequest {
     pub rolling_usage: Option<AccountUsage>,
 }
 
-/// Provider 已解析的 quota 结果及其不透明差异字段。
+/// 当前目录页已读取的账号事实；批量投影不触发上游刷新
+#[derive(Debug, Clone, Copy)]
+pub struct ProviderQuotaReadRequest<'a> {
+    pub account: &'a AccountRecord,
+    pub rolling_usage: Option<&'a AccountUsage>,
+}
+
+/// Provider 已解析的 quota 结果及其不透明差异字段
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderQuota {
-    /// 上游额度响应明确提供的套餐，可用于补全账号展示。
+    /// 上游额度响应明确提供的套餐，可用于补全账号展示
     pub plan_type: Option<String>,
     pub observed_at: Option<DateTime<Utc>>,
     pub refresh_token_expires_at: Option<DateTime<Utc>>,
     pub windows: Vec<ProviderQuotaWindow>,
-    /// 展示用快照级触顶事实（顶层或任一窗口触顶）；不参与账号五态派生。
+    pub credits: Option<ProviderQuotaCredits>,
+    /// 展示用快照级触顶事实（顶层或任一窗口触顶）；不参与账号五态派生
     pub limit_reached: bool,
     pub provider_data: Option<ProviderDocument>,
 }
 
-/// 空值和 `unknown` 代表未提供套餐；新的套餐标识仍按明确值保留。
+/// 上游点数余额的展示事实，保留原始十进制文本以避免精度损失
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderQuotaCredits {
+    pub has_credits: bool,
+    pub unlimited: bool,
+    pub balance: Option<String>,
+}
+
+/// 空值和 `unknown` 代表未提供套餐；新的套餐标识仍按明确值保留
 pub(crate) fn explicit_plan_type(value: Option<&str>) -> Option<&str> {
     value.filter(|value| {
         let value = value.trim();
@@ -839,7 +857,7 @@ pub(crate) fn explicit_plan_type(value: Option<&str>) -> Option<&str> {
     })
 }
 
-/// 按需查询的订阅周期，不参与额度或账号可用性判断。
+/// 按需查询的订阅周期，不参与额度或账号可用性判断
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderSubscription {
     pub starts_at: Option<DateTime<Utc>>,
@@ -850,14 +868,14 @@ pub struct ProviderSubscription {
     pub observed_at: DateTime<Utc>,
 }
 
-/// 按需汇聚的个人信息；资料查询失败不丢弃可用的订阅结果。
-#[derive(Debug, Clone, PartialEq)]
+/// 按需汇聚的个人信息；资料查询失败不丢弃可用的订阅结果
+#[derive(Debug, Clone)]
 pub struct AccountPersonalInfo {
     pub profile: Result<ProviderProfileStatistics, AdminError>,
     pub subscription: Option<ProviderSubscription>,
 }
 
-/// Provider 官方个人资料中的累计摘要。
+/// Provider 官方个人资料中的累计摘要
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderProfileStatisticsSummary {
     pub total_text_tokens: Option<u64>,
@@ -867,14 +885,14 @@ pub struct ProviderProfileStatisticsSummary {
     pub longest_streak_days: Option<u64>,
 }
 
-/// Provider 官方个人资料中的单日 Token bucket。
+/// Provider 官方个人资料中的单日 Token bucket
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderProfileDailyUsage {
     pub date: NaiveDate,
     pub tokens: u64,
 }
 
-/// Provider 官方个人资料中的插件或 Skill 调用排行。
+/// Provider 官方个人资料中的插件或 Skill 调用排行
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderProfileInvocation {
     pub invocation_type: String,
@@ -885,7 +903,7 @@ pub struct ProviderProfileInvocation {
     pub usage_count: Option<u64>,
 }
 
-/// Provider 官方个人资料中的活动洞察。
+/// Provider 官方个人资料中的活动洞察
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderProfileActivityInsights {
     pub fast_mode_percent: Option<f64>,
@@ -897,7 +915,7 @@ pub struct ProviderProfileActivityInsights {
     pub invocations: Option<Vec<ProviderProfileInvocation>>,
 }
 
-/// Provider 已解释的官方个人资料统计。
+/// Provider 已解释的官方个人资料统计
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderProfileStatistics {
     pub display_name: Option<String>,
@@ -909,16 +927,16 @@ pub struct ProviderProfileStatistics {
     pub activity_insights: ProviderProfileActivityInsights,
 }
 
-/// Provider 头像正文的中立字节流；公共层不解释 MIME，也不限制总字节数。
+/// Provider 头像正文的中立字节流；公共层不解释 MIME，也不限制总字节数
 pub type ProviderProfileAvatarStream =
     Pin<Box<dyn Stream<Item = Result<Bytes, ProviderProfileAvatarStreamError>> + Send + 'static>>;
 
-/// Provider 头像流在响应开始后的通用失败，不携带上游 URL 或正文。
+/// Provider 头像流在响应开始后的通用失败，不携带上游 URL 或正文
 #[derive(Debug, thiserror::Error)]
 #[error("provider profile avatar stream failed")]
 pub struct ProviderProfileAvatarStreamError;
 
-/// Provider 已校验并打开的官方头像响应。
+/// Provider 已校验并打开的官方头像响应
 pub struct ProviderProfileAvatar {
     pub content_type: Option<String>,
     pub content_length: Option<u64>,
@@ -938,7 +956,7 @@ impl fmt::Debug for ProviderProfileAvatar {
     }
 }
 
-/// Provider 返回的一张安全主动额度重置卡。
+/// Provider 返回的一张安全主动额度重置卡
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderResetCredit {
     pub id: String,
@@ -948,14 +966,14 @@ pub struct ProviderResetCredit {
     pub reset_type: Option<String>,
 }
 
-/// Provider 主动额度重置卡列表。
+/// Provider 主动额度重置卡列表
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderResetCredits {
     pub available_count: u64,
     pub credits: Vec<ProviderResetCredit>,
 }
 
-/// 一次主动额度重置卡消费命令。
+/// 一次主动额度重置卡消费命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ConsumeProviderResetCredit {
     pub account_id: ProviderAccountId,
@@ -963,7 +981,7 @@ pub struct ConsumeProviderResetCredit {
     pub redeem_request_id: Uuid,
 }
 
-/// Provider 返回的主动额度重置卡消费结果。
+/// Provider 返回的主动额度重置卡消费结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderResetCreditResult {
     pub code: String,
@@ -971,17 +989,18 @@ pub struct ProviderResetCreditResult {
 }
 
 impl ProviderQuota {
-    /// 保留账号已有的套餐子类型，仅在缺失时使用上游额度快照补全。
+    /// 保留账号已有的套餐子类型，仅在缺失时使用上游额度快照补全
     pub(crate) fn fill_missing_plan_type(&self, account_plan_type: &mut Option<String>) {
         if explicit_plan_type(account_plan_type.as_deref()).is_none() {
             *account_plan_type = explicit_plan_type(self.plan_type.as_deref()).map(str::to_owned);
         }
     }
 
-    /// 选择账号用量统计的周/月窗口，同时返回展示所需的周期事实。
+    /// 选择账号用量统计的周/月窗口，同时返回展示所需的周期事实
     ///
     /// 只使用边界完整、可归属到整个账号的窗口；周优先于月，同周期保持
-    /// Provider 投影顺序。没有符合条件的窗口时不回退到短期或历史累计。
+    /// Provider 投影顺序
+    /// 没有符合条件的窗口时不回退到短期或历史累计
     #[must_use]
     pub fn usage_window(&self) -> Option<(&ProviderQuotaWindow, AccountUsagePeriod)> {
         self.usage_windows()
@@ -989,7 +1008,7 @@ impl ProviderQuota {
             .min_by_key(|(_, period)| *period)
     }
 
-    /// 统计与预测共用窗口归属规则，避免把模型专属桶或短期限流当作账号容量。
+    /// 统计与预测共用窗口归属规则，避免把模型专属桶或短期限流当作账号容量
     pub(crate) fn usage_windows(
         &self,
     ) -> impl Iterator<Item = (&ProviderQuotaWindow, AccountUsagePeriod)> {
@@ -1011,11 +1030,12 @@ impl ProviderQuota {
         })
     }
 
-    /// 返回 Dashboard 使用的代表性额度比例。
+    /// 返回 Dashboard 使用的代表性额度比例
     ///
     /// 优先使用覆盖账号全部请求的窗口；同一归属范围内再依次使用短周期、周、月
-    /// 和其它窗口，同一优先级取较高的已用比例。这里只解释跨 Provider 共享的窗口
-    /// 语义，绝不读取 Provider 私有 JSON。
+    /// 和其它窗口，同一优先级取较高的已用比例
+    /// 这里只解释跨 Provider 共享的窗口
+    /// 语义，绝不读取 Provider 私有 JSON
     #[must_use]
     pub fn representative_used_percent(&self) -> Option<f64> {
         if self.limit_reached {
@@ -1025,7 +1045,7 @@ impl ProviderQuota {
             .map(|(_, used_percent)| used_percent)
     }
 
-    /// 选择 Dashboard 展示的真实窗口；没有百分比时仍保留 Provider 的滚动窗口语义。
+    /// 选择 Dashboard 展示的真实窗口；没有百分比时仍保留 Provider 的滚动窗口语义
     #[must_use]
     pub fn representative_window(&self) -> Option<&ProviderQuotaWindow> {
         self.representative_used_window()
@@ -1039,10 +1059,10 @@ impl ProviderQuota {
             })
     }
 
-    /// 将已确认的账号级额度耗尽事实投影到展示窗口。
+    /// 将已确认的账号级额度耗尽事实投影到展示窗口
     ///
     /// Provider 已指出具体触顶窗口时只归一化这些窗口；否则归一化 Dashboard
-    /// 同样会选择的代表窗口，避免把多个独立额度窗口全部伪造成已用尽。
+    /// 同样会选择的代表窗口，避免把多个独立额度窗口全部伪造成已用尽
     pub fn apply_limit_reached_display(&mut self) {
         if !self.limit_reached {
             return;
@@ -1122,21 +1142,21 @@ fn is_week_window(seconds: u64) -> bool {
     seconds > 0 && seconds.abs_diff(WEEK_SECONDS) <= WEEK_SECONDS / 20
 }
 
-/// Provider 实时模型目录的一项。
+/// Provider 实时模型目录的一项
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderModel {
     pub id: UpstreamModelId,
     pub name: String,
 }
 
-/// Provider 实时模型目录。
+/// Provider 实时模型目录
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderModels {
     pub models: Vec<ProviderModel>,
     pub observed_at: Option<DateTime<Utc>>,
 }
 
-/// Provider 原生模型目录正文；wire 语义由对应 Provider 拥有，公共层只搬运不解释字段。
+/// Provider 原生模型目录正文；wire 语义由对应 Provider 拥有，公共层只搬运不解释字段
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderModelCatalogDocument {
     pub document: RawJsonPayload,
@@ -1144,7 +1164,7 @@ pub struct ProviderModelCatalogDocument {
     pub observed_at: DateTime<Utc>,
 }
 
-/// 插件账号回调的服务端过滤条件；Provider 缺省时跨全部已注册类型分页。
+/// 插件账号回调的服务端过滤条件；Provider 缺省时跨全部已注册类型分页
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginAccountListQuery {
     pub provider_kind: Option<ProviderKind>,
@@ -1158,7 +1178,7 @@ pub struct PluginAccountPage {
     pub next_cursor: Option<ProviderAccountId>,
 }
 
-/// 原始凭据与当前账号 revision 的同一读取结果。
+/// 原始凭据与当前账号 revision 的同一读取结果
 #[derive(Clone, PartialEq)]
 pub struct PluginAccountCredential {
     pub account: AccountRecord,
@@ -1175,7 +1195,7 @@ impl fmt::Debug for PluginAccountCredential {
     }
 }
 
-/// Runtime 已完成 wire 校验、Admin 仍需绑定当前账号和 revision 的 prepared facts。
+/// Runtime 已完成 wire 校验、Admin 仍需绑定当前账号和 revision 的 prepared facts
 #[derive(Debug, Clone, PartialEq)]
 pub enum PreparedPluginAccountSave {
     Create(PreparedCredentialCreate),
@@ -1192,20 +1212,20 @@ pub struct PluginAccountSaveResult {
     pub credential_revision: Revision,
 }
 
-/// Provider 执行 refresh 时所需的当前公共账号事实。
+/// Provider 执行 refresh 时所需的当前公共账号事实
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PrepareCredentialRefresh {
     pub account: AccountRecord,
 }
 
-/// Provider 敏感导出结果。
+/// Provider 敏感导出结果
 pub struct ProviderExport {
     pub provider_kind: ProviderKind,
     pub account_ids: Vec<ProviderAccountId>,
     pub document: ProviderDocument,
 }
 
-/// Store 为 Provider 导出序列化准备的最小输入；material 对公共层保持不透明。
+/// Store 为 Provider 导出序列化准备的最小输入；material 对公共层保持不透明
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderExportCredentialInput {
     pub account: AccountRecord,
@@ -1223,20 +1243,20 @@ impl fmt::Debug for ProviderExport {
     }
 }
 
-/// 统一账号目录的一行完整结果。
+/// 统一账号目录的一行完整结果
 #[derive(Debug, Clone, PartialEq)]
 pub struct AccountDirectoryItem {
     pub account: AccountRecord,
     pub capacity: super::accounts::AccountCapacity,
     pub capabilities: super::accounts::ProviderAccountCapabilities,
-    /// Provider 提供的套餐展示名称；未识别到套餐时为空。
+    /// Provider 提供的套餐展示名称；未识别到套餐时为空
     pub plan_type_display: Option<String>,
     pub projection: gateway_core::account::AccountStatusProjection,
     pub usage: Option<super::accounts::AccountUsage>,
     pub quota: ProviderQuota,
 }
 
-/// 统一账号目录页。
+/// 统一账号目录页
 #[derive(Debug, Clone, PartialEq)]
 pub struct AccountDirectoryPage {
     pub config_revision: Revision,
@@ -1245,14 +1265,14 @@ pub struct AccountDirectoryPage {
     pub summary: AccountSummary,
 }
 
-/// 凭据刷新提交后的完整账号结果。
+/// 凭据刷新提交后的完整账号结果
 #[derive(Debug, Clone, PartialEq)]
 pub struct AccountRefreshResult {
     pub config_revision: Revision,
     pub account: AccountDirectoryItem,
 }
 
-/// 多 Provider 导出文档集合。
+/// 多 Provider 导出文档集合
 pub struct AccountExportBundle {
     pub exported_at: DateTime<Utc>,
     pub documents: Vec<ProviderExport>,

backend/crates/gateway-admin/src/model/proxies.rs

@@ -1,4 +1,4 @@
-//! 可复用的账号出口配置，以及脱敏后的连通性测试结果。
+//! 可复用的账号出口配置，以及脱敏后的连通性测试结果
 
 use chrono::{DateTime, Utc};
 use gateway_core::account::{OutboundProxy, RequestLocation};
@@ -39,7 +39,7 @@ pub struct ProxyAccountRef {
     pub enabled: bool,
 }
 
-/// 按代理查询关联账号，分页与搜索均在存储层执行。
+/// 按代理查询关联账号，分页与搜索均在存储层执行
 #[derive(Debug, Clone)]
 pub struct ProxyAccountListQuery {
     pub proxy_id: String,
@@ -69,6 +69,7 @@ pub struct ProxyTestResult {
 
 #[derive(Debug, Clone)]
 pub struct ProxyRecord {
+    pub enabled: bool,
     pub auto_location: bool,
     pub detected_location: Option<DetectedProxyLocation>,
     pub location: Option<gateway_core::account::RequestLocation>,
@@ -94,7 +95,7 @@ pub struct ProxyPage {
 #[derive(Debug, Clone)]
 pub struct NewProxy {
     pub auto_location: bool,
-    /// 由管理用例探测，随配置原子保存，不接受 HTTP 调用方提供结果。
+    /// 由管理用例探测，随配置原子保存，不接受 HTTP 调用方提供结果
     pub test: Option<ProxyTestResult>,
     pub location: Option<gateway_core::account::RequestLocation>,
     pub name: String,
@@ -103,9 +104,12 @@ pub struct NewProxy {
 
 #[derive(Debug, Clone)]
 pub struct UpdateProxy {
+    /// 省略保留配置，零值取消限制
+    pub max_websocket_connections: Option<u32>,
+    pub enabled: Option<bool>,
     pub auto_location: Option<bool>,
     pub test: Option<ProxyTestResult>,
-    /// 外层为空保留配置，内层为空恢复全局继承。
+    /// 外层为空保留配置，内层为空恢复全局继承
     pub location: Option<Option<gateway_core::account::RequestLocation>>,
     pub id: String,
     pub revision: Revision,
@@ -119,7 +123,22 @@ pub struct ProxyMutation {
     pub record: ProxyRecord,
 }
 
-/// 检测失败与连通性分开，双栈冲突不得继续应用旧位置。
+pub const MAX_PROXY_BATCH_SIZE: usize = 100;
+
+#[derive(Debug)]
+pub struct TestProxy {
+    pub id: String,
+    pub revision: Revision,
+    pub detect_location: bool,
+}
+
+#[derive(Debug)]
+pub enum ProxyBatchResult<T> {
+    Completed(Result<T, super::AdminError>),
+    Skipped,
+}
+
+/// 检测失败与连通性分开，双栈冲突不得继续应用旧位置
 #[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(tag = "status", rename_all = "camelCase")]
 pub enum ProxyLocationDetection {
@@ -155,7 +174,7 @@ impl ProxyRecord {
         }
     }
 
-    /// 未知出口可暂用上次成功结果，已知出口变化或时区冲突必须撤销旧覆盖。
+    /// 未知出口可暂用上次成功结果，已知出口变化或时区冲突必须撤销旧覆盖
     #[must_use]
     pub fn detected_location_after_test(
         &self,

backend/crates/gateway-admin/src/model/quota_forecast.rs

@@ -1,4 +1,4 @@
-//! 账号额度的只读容量估算，不参与金额结算或账号调度。
+//! 账号额度的只读容量估算，不参与金额结算或账号调度
 
 use chrono::{DateTime, Duration, Utc};
 
@@ -40,9 +40,9 @@ pub struct QuotaForecastSource {
     pub usd: Option<f64>,
 }
 
-/// 为目标周期选择唯一的预测源窗口；缺少同周期窗口时复用最短的可统计窗口。
+/// 为目标周期选择唯一的预测源窗口；缺少同周期窗口时复用最短的可统计窗口
 ///
-/// Admin 的历史查询与最终投影必须共用这里的顺序，避免查询不会进入响应的窗口。
+/// Admin 的历史查询与最终投影必须共用这里的顺序，避免查询不会进入响应的窗口
 pub(crate) fn quota_forecast_source_window(
     quota: &ProviderQuota,
     period: AccountUsagePeriod,
@@ -53,8 +53,8 @@ pub(crate) fn quota_forecast_source_window(
         .or_else(|| quota.usage_windows().min_by_key(|(_, period)| *period))
 }
 
-/// 优先预测真实的对应窗口；缺少对应周期时只给出明确标识的 7/30 天容量折算。
-/// 本地日志不能证明站外消耗或完整留存，因此即使样本充足也不声称官方额度。
+/// 优先预测真实的对应窗口；缺少对应周期时只给出明确标识的 7/30 天容量折算
+/// 本地日志不能证明站外消耗或完整留存，因此即使样本充足也不声称官方额度
 #[must_use]
 pub fn account_quota_forecasts(
     quota: &ProviderQuota,
@@ -178,9 +178,9 @@ impl AccountQuotaForecast {
         };
         self.low_sample = sample.sampled_percent < LOW_SAMPLE_PERCENT
             || (method == QuotaForecastMethod::Incremental && sample.block_count < 2);
-        // 漏记和个别缺失只影响精度，仍按已记录数值估算，不按请求数补齐未知消耗。
-        // 预测是近似展示值；不复用为账单金额，也不把月折算当成自然月或额外余额。
-        // 已发生的用量保持本周期累计，只把近期消耗比例用于尚未使用的额度。
+        // 漏记和个别缺失只影响精度，仍按已记录数值估算，不按请求数补齐未知消耗
+        // 预测是近似展示值；不复用为账单金额，也不把月折算当成自然月或额外余额
+        // 已发生的用量保持本周期累计，只把近期消耗比例用于尚未使用的额度
         let factor = self.target_seconds as f64 / seconds as f64;
         let remaining_factor = (100.0 - percent) / sample.sampled_percent;
         let remaining_tokens = Some(sample.usage.tokens)

backend/crates/gateway-admin/src/model/quota_forecast_sampling.rs

@@ -1,10 +1,10 @@
-//! 预测专用的配对采样；不改变完整交付用量或费用账本的统计口径。
+//! 预测专用的配对采样；不改变完整交付用量或费用账本的统计口径
 
 use chrono::{DateTime, Utc};
 
 use super::provider_credentials::ProviderDocument;
 
-/// 限制带 Provider 文档的历史点数量；累计用量仍覆盖整个查询区间。
+/// 限制带 Provider 文档的历史点数量；累计用量仍覆盖整个查询区间
 pub const MAX_FORECAST_HISTORY_POINTS: usize = 128;
 const MIN_BLOCK_PERCENT: f64 = 5.0;
 const RECENT_BLOCKS: usize = 3;
@@ -15,7 +15,7 @@ pub struct QuotaForecastUsage {
     pub tokens: u64,
     pub input_tokens: u64,
     pub output_tokens: u64,
-    pub cached_tokens: u64,
+    pub cached_input_tokens: u64,
     pub missing_token_count: u64,
     pub known_cost_count: u64,
     pub unavailable_cost_count: u64,
@@ -24,7 +24,7 @@ pub struct QuotaForecastUsage {
 }
 
 impl QuotaForecastUsage {
-    /// 累计计数倒退表示不能配对，不用饱和减法掩盖数据断点。
+    /// 累计计数倒退表示不能配对，不用饱和减法掩盖数据断点
     fn difference(&self, baseline: &Self) -> Option<Self> {
         let usd = self.usd - baseline.usd;
         if !usd.is_finite() || usd < -1e-9 {
@@ -35,7 +35,9 @@ impl QuotaForecastUsage {
             tokens: self.tokens.checked_sub(baseline.tokens)?,
             input_tokens: self.input_tokens.checked_sub(baseline.input_tokens)?,
             output_tokens: self.output_tokens.checked_sub(baseline.output_tokens)?,
-            cached_tokens: self.cached_tokens.checked_sub(baseline.cached_tokens)?,
+            cached_input_tokens: self
+                .cached_input_tokens
+                .checked_sub(baseline.cached_input_tokens)?,
             missing_token_count: self
                 .missing_token_count
                 .checked_sub(baseline.missing_token_count)?,
@@ -68,7 +70,7 @@ pub struct QuotaForecastHistory {
     pub pending_request_count: u64,
 }
 
-/// 具体 Provider 从自己的历史文档解释出的额度事实。
+/// 具体 Provider 从自己的历史文档解释出的额度事实
 #[derive(Debug, Clone, PartialEq)]
 pub struct QuotaForecastObservation {
     pub used_percent: f64,
@@ -101,13 +103,13 @@ pub struct QuotaForecastSample {
     pub observation_count: usize,
     pub pending_request_count: u64,
     pub discontinuous: bool,
-    /// 本周期已记录用量；近期采样仅用于预测剩余量，不能覆盖这份累计值。
+    /// 本周期已记录用量；近期采样仅用于预测剩余量，不能覆盖这份累计值
     pub cycle_usage: QuotaForecastUsage,
     pub usage: QuotaForecastUsage,
 }
 
-/// 对同一额度段的累计点形成至少 5 个百分点的连续块，使用最近三个完整块及尾部。
-/// 不平均逐请求比值；重复百分比不增加块数，5/10 个百分点仅是量化噪声门槛。
+/// 对同一额度段的累计点形成至少 5 个百分点的连续块，使用最近三个完整块及尾部
+/// 不平均逐请求比值；重复百分比不增加块数，5/10 个百分点仅是量化噪声门槛
 #[must_use]
 pub fn select_forecast_sample(
     key: String,
@@ -139,8 +141,8 @@ pub fn select_forecast_sample(
         usage: current.usage.clone(),
     };
     history.push(current);
-    // 重置边界不在查询起点时，从首个新观测重新计数，避免把旧周期累计带入总量。
-    let mut cycle_baseline = interrupted.then(|| &history[0]);
+    // 重置边界不在查询起点时，从首个新观测重新计数，避免把旧周期累计带入总量
+    let cycle_baseline = interrupted.then(|| &history[0]);
     let mut anchors: Vec<&QuotaForecastPoint> = Vec::new();
     let mut high_water: Option<&QuotaForecastPoint> = None;
     for point in &history {
@@ -149,13 +151,13 @@ pub fn select_forecast_sample(
                 continue;
             }
             if point.used_percent < previous.used_percent {
-                // 一个百分点内的回落可能是量化/并发乱序；更大的回落不能跨越。
+                // 一个百分点内的回落可能是量化/并发乱序；更大的回落不能跨越
                 if previous.used_percent - point.used_percent <= 1.0 {
                     continue;
                 }
+                // 同窗口回落不能证明周期重置，只重建采样并保留已记录累计
                 sample.discontinuous = true;
                 anchors.clear();
-                cycle_baseline = Some(point);
             }
         }
         high_water = Some(point);
@@ -198,7 +200,7 @@ pub fn select_forecast_sample(
     sample.sampled_percent = progress;
     sample.block_count = anchors.len() - baseline_index - 1;
     sample.usage = usage;
-    // 断点后的新基线已有足够进度时，只消费新段；旧段从不参与本次估算。
+    // 断点后的新基线已有足够进度时，只消费新段；旧段从不参与本次估算
     sample.discontinuous = false;
     sample
 }

backend/crates/gateway-admin/src/model/reset_credit_automation.rs

@@ -0,0 +1,45 @@
+//! 自动重置卡的持久计划与查询投影，不保存上游凭据或完整卡片
+
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PlannedResetCredit {
+    pub id: String,
+    pub expires_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PendingResetCredit {
+    pub credit: PlannedResetCredit,
+    pub redeem_request_id: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ResetCreditAutomationState {
+    pub next_discovery_at: DateTime<Utc>,
+    pub credits: Vec<PlannedResetCredit>,
+    pub pending: Option<PendingResetCredit>,
+    pub retry_at: Option<DateTime<Utc>>,
+    pub failures: u32,
+    pub last_result: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResetCreditAutomation {
+    pub account_id: String,
+    pub enabled: bool,
+    /// 零表示尚未创建；每次持久状态写入都递增版本
+    pub revision: u64,
+    pub next_run_at: DateTime<Utc>,
+    pub state: ResetCreditAutomationState,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ResetCreditAutomationStatus {
+    pub enabled: bool,
+    pub lead_minutes: u32,
+    pub next_discovery_at: Option<DateTime<Utc>>,
+    pub next_consume_at: Option<DateTime<Utc>>,
+    pub last_result: Option<String>,
+}

backend/crates/gateway-admin/src/model/retention.rs

@@ -1,4 +1,4 @@
-//! 历史数据保留规则；存储实现只接受已校验的窗口。
+//! 历史数据保留规则；存储实现只接受已校验的窗口
 
 use super::AdminError;
 
@@ -17,10 +17,28 @@ pub struct RetentionPolicy {
 }
 
 impl RetentionPolicy {
+    /// 保留期管理与全量设置保存共用的字段约束
+    pub fn validate_values(
+        usage_days: u32,
+        ops_days: u32,
+        audit_days: u32,
+    ) -> Result<(), &'static str> {
+        for (valid, field) in [
+            ((1..=31).contains(&usage_days), "usage_retention_days"),
+            (ops_days > 0, "ops_event_retention_days"),
+            (audit_days > 0, "audit_retention_days"),
+        ] {
+            if !valid {
+                return Err(field);
+            }
+        }
+        Ok(())
+    }
+
     pub fn try_new(usage_days: u32, ops_days: u32, audit_days: u32) -> Result<Self, AdminError> {
-        if usage_days < 31 || ops_days == 0 || audit_days == 0 {
+        if Self::validate_values(usage_days, ops_days, audit_days).is_err() {
             return Err(AdminError::invalid(
-                "请求保留期至少 31 天，事件与审计保留期必须为正数",
+                "请求保留期必须为 1～31 天，事件与审计保留期必须为正数",
             ));
         }
         Ok(Self {

backend/crates/gateway-admin/src/model/settings.rs

@@ -1,4 +1,4 @@
-//! Runtime settings 与明文管理员 API Key 的语义模型。
+//! Runtime settings 与明文管理员 API Key 的语义模型
 
 use std::{collections::BTreeMap, fmt};
 
@@ -8,96 +8,105 @@ use gateway_core::routing::{ProviderKind, PublicModelId, UpstreamModelId};
 
 use super::Revision;
 
-/// 客户端模型到上游模型的全局精确映射。
+/// 客户端模型到上游模型的全局精确映射
 pub type ModelMappings = BTreeMap<PublicModelId, UpstreamModelId>;
 
-/// Provider-owned 请求画像选择；Provider ID 是唯一命名空间。
+/// 全局模型映射的数量与文本约束；调用方保留各自的键值表示
+pub fn validate_model_mappings<'a>(
+    mappings: impl ExactSizeIterator<Item = (&'a str, &'a str)>,
+) -> Result<(), &'static str> {
+    if mappings.len() > 512 {
+        return Err("model_mappings");
+    }
+    for (requested, upstream) in mappings {
+        for value in [requested, upstream] {
+            if value.is_empty()
+                || value.len() > 256
+                || value.bytes().any(|byte| byte.is_ascii_control())
+            {
+                return Err("model_mappings");
+            }
+        }
+    }
+    Ok(())
+}
+
+/// Provider-owned 请求画像选择；Provider ID 是唯一命名空间
 pub type ProviderRequestProfiles =
     BTreeMap<ProviderKind, gateway_core::account::OpaqueProviderData>;
 
-/// Provider-owned 请求画像的部分更新；`None` 只表示显式删除该 Provider 的历史选择。
+/// Provider-owned 请求画像的部分更新；`None` 只表示显式删除该 Provider 的历史选择
 pub type ProviderRequestProfileUpdates =
     BTreeMap<ProviderKind, Option<gateway_core::account::OpaqueProviderData>>;
 
-/// 账号调度策略；由 Core 拥有稳定值与 wire 映射。
+/// 账号调度策略；由 Core 拥有稳定值与 wire 映射
 pub use gateway_core::account::RotationStrategy;
 
-/// 完整运行设置事实。
+/// 运行设置的共同值；版本、Provider 画像更新和数据库秘密由外层类型拥有
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct RuntimeSettingsValues {
+    pub codex_privacy_policy: gateway_core::settings::privacy::CodexPrivacyPolicy,
+    pub request_location_enabled: bool,
+    pub request_location: gateway_core::account::RequestLocation,
+    pub refresh_margin_seconds: u64,
+    pub refresh_concurrency: u32,
+    pub max_concurrent_per_account: u32,
+    pub max_waiting_per_key: u32,
+    pub max_waiting_per_account: u32,
+    pub concurrency_wait_timeout_seconds: u32,
+    pub openai_guardian_reserved_concurrency: u32,
+    pub openai_account_affinity: gateway_core::account::AccountAffinity,
+    pub max_account_rotations: u32,
+    pub openai_session_affinity_ttl_hours: u32,
+    pub responses_max_decompressed_body_bytes: u64,
+    pub smart_scheduling: gateway_core::account::SmartSchedulingConfig,
+    pub min_codex_desktop_version: Option<String>,
+    pub min_codex_cli_version: Option<String>,
+    pub usage_retention_days: u32,
+    pub ops_event_retention_days: u32,
+    pub audit_retention_days: u32,
+    pub account_auto_freeze_enabled: bool,
+    pub account_auto_freeze_threshold: u32,
+    pub account_auto_freeze_window_seconds: u64,
+    pub account_auto_freeze_duration_seconds: u64,
+    pub account_auto_freeze_probe_enabled: bool,
+    pub account_auto_freeze_probe_model: Option<String>,
+    pub account_auto_freeze_adaptive_concurrency: bool,
+    pub account_warmup_enabled: bool,
+    pub account_warmup_schedule_time: String,
+    pub account_warmup_model: Option<String>,
+    pub reset_credit_lead_minutes: u32,
+    pub reset_credit_max_weekly_remaining_percent: Option<u32>,
+}
+
+/// 完整运行设置事实
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct RuntimeSettings {
+    #[serde(flatten)]
+    pub values: RuntimeSettingsValues,
     pub request_profiles: ProviderRequestProfiles,
     pub config_revision: Revision,
-    pub request_location_enabled: bool,
-    pub request_location: gateway_core::account::RequestLocation,
     pub model_mappings: ModelMappings,
-    pub refresh_margin_seconds: u64,
-    pub refresh_concurrency: u32,
-    pub max_concurrent_per_account: u32,
-    pub request_interval_ms: u64,
-    pub max_waiting_per_key: u32,
-    pub max_waiting_per_account: u32,
-    pub concurrency_wait_timeout_seconds: u32,
-    pub responses_max_decompressed_body_bytes: u64,
-    pub smart_scheduling: gateway_core::account::SmartSchedulingConfig,
     pub rotation_strategy: RotationStrategy,
-    pub min_codex_desktop_version: Option<String>,
-    pub min_codex_cli_version: Option<String>,
-    pub usage_retention_days: u32,
-    pub ops_event_retention_days: u32,
-    pub audit_retention_days: u32,
-    pub account_auto_freeze_enabled: bool,
-    pub account_auto_freeze_threshold: u32,
-    pub account_auto_freeze_window_seconds: u64,
-    pub account_auto_freeze_duration_seconds: u64,
-    pub account_auto_freeze_probe_enabled: bool,
-    pub account_auto_freeze_probe_model: Option<String>,
-    pub account_auto_freeze_adaptive_concurrency: bool,
-    pub account_warmup_enabled: bool,
-    pub account_warmup_schedule_time: String,
-    pub account_warmup_model: Option<String>,
     pub updated_at: DateTime<Utc>,
 }
 
-/// 原子替换运行设置的命令。
+/// 原子替换运行设置的命令
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct ReplaceRuntimeSettings {
-    /// 读取设置时的版本；与写入在同一事务内比较，防止覆盖并发更新。
+    #[serde(flatten)]
+    pub values: RuntimeSettingsValues,
+    /// 读取设置时的版本；与写入在同一事务内比较，防止覆盖并发更新
     pub expected_revision: Revision,
-    /// 只覆盖提交的 Provider；未提交项保留当前持久值。
+    /// 只覆盖提交的 Provider；未提交项保留当前持久值
     pub request_profile_updates: ProviderRequestProfileUpdates,
-    pub request_location_enabled: bool,
-    pub request_location: gateway_core::account::RequestLocation,
     pub model_mappings: ModelMappings,
-    pub refresh_margin_seconds: u64,
-    pub refresh_concurrency: u32,
-    pub max_concurrent_per_account: u32,
-    pub request_interval_ms: u64,
-    pub max_waiting_per_key: u32,
-    pub max_waiting_per_account: u32,
-    pub concurrency_wait_timeout_seconds: u32,
-    pub responses_max_decompressed_body_bytes: u64,
-    pub smart_scheduling: gateway_core::account::SmartSchedulingConfig,
     pub rotation_strategy: RotationStrategy,
-    pub min_codex_desktop_version: Option<String>,
-    pub min_codex_cli_version: Option<String>,
-    pub usage_retention_days: u32,
-    pub ops_event_retention_days: u32,
-    pub audit_retention_days: u32,
-    pub account_auto_freeze_enabled: bool,
-    pub account_auto_freeze_threshold: u32,
-    pub account_auto_freeze_window_seconds: u64,
-    pub account_auto_freeze_duration_seconds: u64,
-    pub account_auto_freeze_probe_enabled: bool,
-    pub account_auto_freeze_probe_model: Option<String>,
-    pub account_auto_freeze_adaptive_concurrency: bool,
-    pub account_warmup_enabled: bool,
-    pub account_warmup_schedule_time: String,
-    pub account_warmup_model: Option<String>,
 }
 
-/// 明文管理员 API Key；按产品约束明文落库，但禁止 Debug 泄漏。
+/// 明文管理员 API Key；按产品约束明文落库，但禁止 Debug 泄漏
 #[derive(Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 #[serde(transparent)]
 pub struct AdminApiKey(String);
@@ -113,7 +122,7 @@ impl AdminApiKey {
         &self.0
     }
 
-    /// 仅供显式 regenerate 响应读取一次。
+    /// 仅供显式 regenerate 响应读取一次
     #[must_use]
     pub fn expose_for_response(&self) -> &str {
         &self.0
@@ -126,7 +135,7 @@ impl fmt::Debug for AdminApiKey {
     }
 }
 
-/// 管理员 API Key 更新结果。
+/// 管理员 API Key 更新结果
 #[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct AdminApiKeyMutation {
@@ -134,7 +143,7 @@ pub struct AdminApiKeyMutation {
     pub exists: bool,
 }
 
-/// 新管理员 API Key 的一次性返回结果。
+/// 新管理员 API Key 的一次性返回结果
 #[derive(serde::Serialize, serde::Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct RegeneratedAdminApiKey {
@@ -172,35 +181,68 @@ impl From<RuntimeSettings> for ReplaceRuntimeSettings {
                 .into_iter()
                 .map(|(provider, value)| (provider, Some(value)))
                 .collect(),
-            request_location_enabled: settings.request_location_enabled,
-            request_location: settings.request_location,
+            values: settings.values,
             model_mappings: settings.model_mappings,
-            refresh_margin_seconds: settings.refresh_margin_seconds,
-            refresh_concurrency: settings.refresh_concurrency,
-            max_concurrent_per_account: settings.max_concurrent_per_account,
-            request_interval_ms: settings.request_interval_ms,
-            max_waiting_per_key: settings.max_waiting_per_key,
-            max_waiting_per_account: settings.max_waiting_per_account,
-            concurrency_wait_timeout_seconds: settings.concurrency_wait_timeout_seconds,
-            responses_max_decompressed_body_bytes: settings.responses_max_decompressed_body_bytes,
-            smart_scheduling: settings.smart_scheduling,
             rotation_strategy: settings.rotation_strategy,
-            min_codex_desktop_version: settings.min_codex_desktop_version,
-            min_codex_cli_version: settings.min_codex_cli_version,
-            usage_retention_days: settings.usage_retention_days,
-            ops_event_retention_days: settings.ops_event_retention_days,
-            audit_retention_days: settings.audit_retention_days,
-            account_auto_freeze_enabled: settings.account_auto_freeze_enabled,
-            account_auto_freeze_threshold: settings.account_auto_freeze_threshold,
-            account_auto_freeze_window_seconds: settings.account_auto_freeze_window_seconds,
-            account_auto_freeze_duration_seconds: settings.account_auto_freeze_duration_seconds,
-            account_auto_freeze_probe_enabled: settings.account_auto_freeze_probe_enabled,
-            account_auto_freeze_probe_model: settings.account_auto_freeze_probe_model,
-            account_auto_freeze_adaptive_concurrency: settings
-                .account_auto_freeze_adaptive_concurrency,
-            account_warmup_enabled: settings.account_warmup_enabled,
-            account_warmup_schedule_time: settings.account_warmup_schedule_time,
-            account_warmup_model: settings.account_warmup_model,
         }
     }
 }
+
+impl RuntimeSettingsValues {
+    /// 校验共同事实，返回字段名供边界转换错误；SQL 类型转换仍由 Store 处理
+    pub fn validate(&self) -> Result<(), &'static str> {
+        if !(1..=1440).contains(&self.reset_credit_lead_minutes) {
+            return Err("reset_credit_lead_minutes");
+        }
+        if self
+            .reset_credit_max_weekly_remaining_percent
+            .is_some_and(|percent| percent > 100)
+        {
+            return Err("reset_credit_max_weekly_remaining_percent");
+        }
+        self.request_location
+            .validate()
+            .map_err(|_| "request_location")?;
+        gateway_core::settings::validate_request_limits(
+            self.max_waiting_per_key,
+            self.max_waiting_per_account,
+            self.concurrency_wait_timeout_seconds,
+            self.max_account_rotations,
+            self.openai_session_affinity_ttl_hours,
+        )?;
+        gateway_core::settings::response_body_limit(self.responses_max_decompressed_body_bytes)?;
+        gateway_core::settings::client_min_versions(
+            self.min_codex_desktop_version.as_deref(),
+            self.min_codex_cli_version.as_deref(),
+        )?;
+        for (valid, field) in [
+            (
+                self.refresh_margin_seconds > 0
+                    && i64::try_from(self.refresh_margin_seconds).is_ok(),
+                "refresh_margin_seconds",
+            ),
+            (self.refresh_concurrency > 0, "refresh_concurrency"),
+        ] {
+            if !valid {
+                return Err(field);
+            }
+        }
+        super::retention::RetentionPolicy::validate_values(
+            self.usage_retention_days,
+            self.ops_event_retention_days,
+            self.audit_retention_days,
+        )?;
+        gateway_core::provider_ports::ProviderFreezePolicy::validate_values(
+            self.account_auto_freeze_threshold,
+            self.account_auto_freeze_window_seconds,
+            self.account_auto_freeze_duration_seconds,
+            self.account_auto_freeze_probe_model.as_deref(),
+        )?;
+        gateway_core::provider_ports::ProviderWarmupPolicy::validate_values(
+            self.account_warmup_enabled,
+            &self.account_warmup_schedule_time,
+            self.account_warmup_model.as_deref(),
+        )?;
+        Ok(())
+    }
+}

backend/crates/gateway-admin/src/model/system.rs

@@ -1,9 +1,9 @@
-//! 版本、自更新、回滚与进程重启的 UTC 语义模型。
+//! 版本、自更新、回滚与进程重启的 UTC 语义模型
 
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 
-/// 本次检查或安装选择的更新稳定性范围，具体版本准入由 Host 判定。
+/// 本次检查或安装选择的更新稳定性范围，具体版本准入由 Host 判定
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(rename_all = "lowercase")]
 pub enum SystemUpdateChannel {
@@ -28,7 +28,7 @@ impl SystemUpdateChannel {
     }
 }
 
-/// Host 返回的本次检查通道及当前构建允许选择的范围。
+/// Host 返回的本次检查通道及当前构建允许选择的范围
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SystemUpdatePolicy {
@@ -36,9 +36,9 @@ pub struct SystemUpdatePolicy {
     pub available_channels: Vec<SystemUpdateChannel>,
 }
 
-/// 当前运行版本及更新检查摘要。
+/// 当前运行版本及更新检查摘要
 ///
-/// `deployment_mode_label` 之类的本地化字符串由 API 根据原始枚举值生成。
+/// `deployment_mode_label` 之类的本地化字符串由 API 根据原始枚举值生成
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SystemVersion {
     pub version: String,
@@ -52,9 +52,9 @@ pub struct SystemVersion {
     pub update_warning: Option<String>,
 }
 
-/// 发布源提供的完整更新详情。
+/// 发布源提供的完整更新详情
 ///
-/// 部署模式与构建类型的展示标签归 API；其余字段均为 Host 已确认的原始事实。
+/// 部署模式与构建类型的展示标签归 API；其余字段均为 Host 已确认的原始事实
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SystemUpdateDetail {
     pub policy: SystemUpdatePolicy,
@@ -71,7 +71,7 @@ pub struct SystemUpdateDetail {
     pub warning: Option<String>,
 }
 
-/// 系统操作类型。
+/// 系统操作类型
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SystemOperationKind {
     Update,
@@ -79,7 +79,7 @@ pub enum SystemOperationKind {
     Restart,
 }
 
-/// 系统操作状态。
+/// 系统操作状态
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SystemOperationStatus {
     Idle,
@@ -88,7 +88,7 @@ pub enum SystemOperationStatus {
     Failed,
 }
 
-/// 持久化系统操作的完整状态。
+/// 持久化系统操作的完整状态
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SystemOperationState {
     pub operation_id: Option<String>,
@@ -101,7 +101,7 @@ pub struct SystemOperationState {
     pub finished_at: Option<DateTime<Utc>>,
 }
 
-/// 最近一次系统操作及版本交换状态。
+/// 最近一次系统操作及版本交换状态
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SystemUpdateStatus {
     pub previous_version: Option<String>,
@@ -110,7 +110,7 @@ pub struct SystemUpdateStatus {
     pub operation: SystemOperationState,
 }
 
-/// 自更新日志级别。
+/// 自更新日志级别
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SystemUpdateEventLevel {
     Info,
@@ -119,7 +119,7 @@ pub enum SystemUpdateEventLevel {
     Error,
 }
 
-/// 一条已脱敏的系统更新事件。
+/// 一条已脱敏的系统更新事件
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SystemUpdateEvent {
     pub id: String,
@@ -132,7 +132,7 @@ pub struct SystemUpdateEvent {
     pub occurred_at: DateTime<Utc>,
 }
 
-/// 已受理的异步系统操作；不同 wire shape 由枚举保持为合法状态。
+/// 已受理的异步系统操作；不同 wire shape 由枚举保持为合法状态
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum SystemOperationAccepted {
     Update {
@@ -163,7 +163,7 @@ impl SystemOperationAccepted {
     }
 }
 
-/// 重启前的只读确认快照；目标发行与全局配置版本一起绑定用户确认。
+/// 重启前的只读确认快照；目标发行与全局配置版本一起绑定用户确认
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct SystemRestartPlan {

backend/crates/gateway-admin/src/model/usage_data/actor.rs

@@ -0,0 +1,26 @@
+//! 由宿主传入的可信写入主体，不属于插件请求载荷
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum UsageActor {
+    Admin {
+        subject: String,
+    },
+    Plugin {
+        publisher: String,
+        name: String,
+        instance_id: String,
+    },
+    System,
+}
+
+impl super::UsageRecordChange {
+    #[must_use]
+    pub fn id(&self) -> &str {
+        match self {
+            Self::Put { id, .. } | Self::Update { id, .. } | Self::Delete { id } => id,
+        }
+    }
+}

backend/crates/gateway-admin/src/model/usage_data/aggregate.rs

@@ -0,0 +1,87 @@
+//! 按归属时间和维度维护统计贡献，业务来源与调整历史由调用方保存
+
+use super::{UsageDelta, UsageRecordFilter};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum UsageMetric {
+    RequestCount,
+    SuccessCount,
+    FailureCount,
+    CancelledCount,
+    IncompleteCount,
+    CompletedRequestCount,
+    InputTokens,
+    OutputTokens,
+    CachedInputTokens,
+    CacheWriteInputTokens,
+    ReasoningOutputTokens,
+    ImageInputTokens,
+    ImageOutputTokens,
+    TotalTokens,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsageDimensions {
+    pub provider: Option<String>,
+    pub model: Option<String>,
+    pub account_ref: Option<String>,
+    pub client_key_ref: Option<String>,
+    pub operation: Option<String>,
+    pub transport: Option<String>,
+}
+
+/// 整个键决定覆盖目标；调用方可将来源标识编码进 key，重试相同键不会累计
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsageAggregateKey {
+    pub bucket_start_ms: i64,
+    pub dimensions: UsageDimensions,
+    pub key: String,
+}
+
+/// 值按 bucket_start_ms 归属，不自动摊分；负值用于相对原生统计的修正
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsageAggregate {
+    pub identity: UsageAggregateKey,
+    pub counts: BTreeMap<UsageMetric, UsageDelta>,
+    pub costs: BTreeMap<String, String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum UsageAggregateChange {
+    Put { aggregate: UsageAggregate },
+    Delete { identity: UsageAggregateKey },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct WriteUsageAggregates {
+    pub changes: Vec<UsageAggregateChange>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsageAggregateWriteResult {
+    pub changed: Vec<UsageAggregateKey>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ListUsageAggregates {
+    pub filter: UsageRecordFilter,
+    pub cursor: Option<String>,
+    pub limit: Option<u16>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsageAggregatePage {
+    pub items: Vec<UsageAggregate>,
+    pub next_cursor: Option<String>,
+}

backend/crates/gateway-admin/src/model/usage_data/error.rs

@@ -0,0 +1,44 @@
+//! 用量基础操作的错误分类，不保存失败或重试状态
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum UsageErrorKind {
+    InvalidInput,
+    NotFound,
+    Conflict,
+    CapacityExceeded,
+    Unavailable,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsageDataError {
+    pub kind: UsageErrorKind,
+    pub message: String,
+}
+impl UsageDataError {
+    #[must_use]
+    pub fn new(kind: UsageErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+        }
+    }
+    #[must_use]
+    pub fn invalid(message: impl Into<String>) -> Self {
+        Self::new(UsageErrorKind::InvalidInput, message)
+    }
+    #[must_use]
+    pub fn unavailable(message: impl Into<String>) -> Self {
+        Self::new(UsageErrorKind::Unavailable, message)
+    }
+}
+impl std::fmt::Display for UsageDataError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(&self.message)
+    }
+}
+impl std::error::Error for UsageDataError {}
+pub type UsageDataResult<T> = Result<T, UsageDataError>;

backend/crates/gateway-admin/src/model/usage_data/mod.rs

@@ -0,0 +1,22 @@
+//! 用量明细、聚合维护与纯计价的公开合同
+
+mod value;
+pub use value::*;
+mod record;
+pub use record::*;
+mod query;
+pub use query::*;
+mod pricing;
+pub use pricing::*;
+mod error;
+pub use error::*;
+
+pub const USAGE_DATA_MAX_TARGETS: usize = 500;
+pub const USAGE_DATA_MAX_REQUEST_BYTES: usize = 2 * 1024 * 1024;
+pub const USAGE_DATA_MAX_PAGE_SIZE: u16 = 200;
+
+mod actor;
+pub use actor::*;
+
+mod aggregate;
+pub use aggregate::*;

backend/crates/gateway-admin/src/model/usage_data/pricing.rs

@@ -0,0 +1,62 @@
+//! 纯 Token 计价合同，费用是否采用与额外费用合并由调用方决定
+
+use super::{UsageCost, UsageTokens};
+use gateway_core::metering::ModelPriceOverride;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum UsagePriceSelection {
+    Current,
+    Override { price: Box<ModelPriceOverride> },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsagePricingInput {
+    pub id: String,
+    pub provider: String,
+    pub model: String,
+    pub tokens: UsageTokens,
+    pub service_tier: Option<String>,
+    pub price: UsagePriceSelection,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct EvaluateUsagePricing {
+    pub items: Vec<UsagePricingInput>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsagePricingBreakdown {
+    pub input_amount: String,
+    pub output_amount: String,
+    pub cache_read_amount: String,
+    pub cache_write_amount: String,
+    pub standard_amount: String,
+    pub long_context_billing_applied: bool,
+    pub service_tier: Option<String>,
+    pub custom_multiplier_bps: u32,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "status", rename_all = "snake_case", deny_unknown_fields)]
+pub enum UsagePricingResult {
+    Estimated {
+        id: String,
+        cost: UsageCost,
+        breakdown: UsagePricingBreakdown,
+    },
+    NotEstimable {
+        id: String,
+        reason: String,
+    },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsagePricingEvaluation {
+    pub items: Vec<UsagePricingResult>,
+}

backend/crates/gateway-admin/src/model/usage_data/query.rs

@@ -0,0 +1,36 @@
+//! 请求明细的有界筛选与稳定顺序分页
+
+use super::UsageRecord;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct GetUsageRecord {
+    pub id: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsageRecordFilter {
+    pub start_ms: i64,
+    pub end_ms: i64,
+    pub provider: Option<String>,
+    pub model: Option<String>,
+    pub account_ref: Option<String>,
+    pub client_key_ref: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ListUsageRecords {
+    pub filter: UsageRecordFilter,
+    pub cursor: Option<String>,
+    pub limit: Option<u16>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsageRecordPage {
+    pub items: Vec<UsageRecord>,
+    pub next_cursor: Option<String>,
+}

backend/crates/gateway-admin/src/model/usage_data/record.rs

@@ -0,0 +1,106 @@
+//! 既有请求明细的用量读写合同，不承载插件任务或来源状态
+
+use super::UsageCount;
+use serde::{Deserialize, Serialize};
+
+/// Token 使用宿主口径：缓存包含在输入中，推理包含在输出中，未知值为 null
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsageTokens {
+    pub input_tokens: Option<UsageCount>,
+    pub output_tokens: Option<UsageCount>,
+    pub cached_input_tokens: Option<UsageCount>,
+    pub cache_write_input_tokens: Option<UsageCount>,
+    pub reasoning_output_tokens: Option<UsageCount>,
+    pub image_input_tokens: Option<UsageCount>,
+    pub image_output_tokens: Option<UsageCount>,
+    pub total_tokens: Option<UsageCount>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum UsageCostSource {
+    ProviderReported,
+    Calculated,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum UsageCost {
+    #[default]
+    Unavailable,
+    Known {
+        source: UsageCostSource,
+        amount: String,
+        currency: String,
+    },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum UsageOutcome {
+    Running,
+    Succeeded,
+    Failed,
+    Cancelled,
+    Incomplete,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsageRecordData {
+    pub client_key_ref: String,
+    pub provider: Option<String>,
+    pub account_ref: Option<String>,
+    pub requested_model: Option<String>,
+    pub model: Option<String>,
+    pub protocol: String,
+    pub operation: String,
+    pub endpoint: String,
+    pub client_transport: String,
+    pub service_tier: Option<String>,
+    pub started_at_ms: i64,
+    pub completed_at_ms: Option<i64>,
+    pub outcome: UsageOutcome,
+    pub tokens: UsageTokens,
+    pub cost: UsageCost,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsageRecord {
+    pub id: String,
+    pub data: UsageRecordData,
+    pub billing_snapshot: Option<serde_json::Value>,
+    pub provider_observation: Option<serde_json::Value>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum UsageRecordChange {
+    Put {
+        id: String,
+        data: Box<UsageRecordData>,
+    },
+    /// tokens 替换全部 Token 字段；cost 的 unavailable 明确清空费用
+    Update {
+        id: String,
+        tokens: Option<UsageTokens>,
+        cost: Option<UsageCost>,
+    },
+    Delete {
+        id: String,
+    },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct WriteUsageRecords {
+    pub changes: Vec<UsageRecordChange>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UsageWriteResult {
+    pub changed_ids: Vec<String>,
+}

backend/crates/gateway-admin/src/model/usage_data/value.rs

@@ -0,0 +1,63 @@
+//! 用量计数使用十进制字符串，避免插件前端丢失整数精度
+
+use serde::{Deserialize, Deserializer, Serialize, Serializer, de::Error};
+use std::fmt;
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct UsageCount(pub u64);
+impl UsageCount {
+    pub const ZERO: Self = Self(0);
+    #[must_use]
+    pub const fn get(self) -> u64 {
+        self.0
+    }
+}
+impl From<u64> for UsageCount {
+    fn from(value: u64) -> Self {
+        Self(value)
+    }
+}
+impl fmt::Display for UsageCount {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        self.0.fmt(formatter)
+    }
+}
+impl Serialize for UsageCount {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_str(&self.0.to_string())
+    }
+}
+impl<'de> Deserialize<'de> for UsageCount {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let value = String::deserialize(deserializer)?;
+        if value.is_empty() || !value.bytes().all(|byte| byte.is_ascii_digit()) {
+            return Err(D::Error::custom("count must be an unsigned decimal string"));
+        }
+        value.parse().map(Self).map_err(D::Error::custom)
+    }
+}
+
+/// 有符号统计贡献受 PostgreSQL bigint 范围限制，JSON 使用十进制字符串
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct UsageDelta(pub i64);
+impl UsageDelta {
+    #[must_use]
+    pub const fn get(self) -> i64 {
+        self.0
+    }
+}
+impl Serialize for UsageDelta {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_str(&self.0.to_string())
+    }
+}
+impl<'de> Deserialize<'de> for UsageDelta {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let value = String::deserialize(deserializer)?;
+        let digits = value.strip_prefix('-').unwrap_or(&value);
+        if digits.is_empty() || !digits.bytes().all(|byte| byte.is_ascii_digit()) {
+            return Err(D::Error::custom("delta must be a signed decimal string"));
+        }
+        value.parse().map(Self).map_err(D::Error::custom)
+    }
+}