chore(release): v3.16.0

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

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

@@ -0,0 +1,58 @@
+---
+name: cpr-dev-guide
+description: Codex Proxy RS 仓库开发与问题审查入口。用户要求“开发／实现这个功能”“直接改”“修复一下”“看下报错”“审查这个问题／代码”“自审当前改动”“调整页面”“更新文档”，或继续修改本仓库的 Rust、Vue、协议、存储、部署和 CI 时主动使用，无需点名技能。负责定位、方案、自审与验证；提交或审查 PR 另配合 cpr-github-pr。Use for implementation, debugging, code review and documentation in this repository, not generic advice for unrelated projects.
+---
+
+# 开发指南
+
+先读根目录的 [AGENTS.md](../../../AGENTS.md) 和 [CONTRIBUTING.md](../../../CONTRIBUTING.md)。
+本技能只组织工作入口，架构、协议和视觉规则从下列权威文档读取，不维护第二份副本。
+
+普通问题审查、代码审查与排查由本技能进入贡献文档的审查标准；有 PR 链接、编号或提交 PR 的意图时再加载 `cpr-github-pr`。
+审查请求先报告结论，不因加载开发技能而擅自修复；用户已要求修改时完成实现、自审和验证。
+
+## 按任务读取
+
+| 任务 | 技能与文档入口 |
+| --- | --- |
+| 用户能力、快速开始 | [README](../../../README.md) |
+| 模块职责、调用链、状态归属 | [系统架构](../../../docs/architecture.md) |
+| Rust 开发 | 加载并使用 `$rust-best-practices`，结合 [系统架构](../../../docs/architecture.md) 与 [项目约定](../../../CONTRIBUTING.md#项目约定) |
+| HTTP 路由、请求与响应、导入导出 | [API 文档](../../../docs/api.md) |
+| 开发独立网关插件 | [cpr-plugin-dev](../cpr-plugin-dev/SKILL.md)：公开 SDK、能力选择、示例、打包与验证 |
+| 前端开发、管理端组件、主题 Token、视觉验证 | 按下方「前端任务」加载设计约束，结合 [管理端主题](../../../docs/theme.md) 与 [界面验证](../../../CONTRIBUTING.md#界面验证) |
+| 常规文档更新 | [文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件)：维护当前说明，在原章节就地修订，不记录变更历史 |
+| 部署、客户端配置、备份与恢复 | [部署说明](../../../deploy/README.md) |
+| 数据迁移、冻结清单与本地测试库 | [迁移说明](../../../backend/migrations/README.md) |
+| 验证命令与提交规范 | [贡献与审查](../../../CONTRIBUTING.md) |
+| 创建或审查 PR | [cpr-github-pr](../cpr-github-pr/SKILL.md) |
+| 整理或提交 Issue | [cpr-github-issue](../cpr-github-issue/SKILL.md) |
+| 发布说明、版本规划与发版 | [cpr-release](../cpr-release/SKILL.md) |
+
+## 前端任务
+
+- 加载并使用 `$frontend-design`，先读 [界面文案与信息层级](../../../docs/theme.md#界面文案与信息层级)，将本项目的管理工具风格、现有字体与主题 Token 作为设计约束
+- 开发前对照原页面及该章节的同类参考，确认可复用布局、组件与操作位置；修改已有页面前先留存截图，不为局部需求重做页面
+- 页面保留操作所需的简短信息，重复文案删除，详细帮助按主题约定收进 Popover；关键限制和错误仍就近提示
+- 交付前按该章节复核文案、层级与密度，按 [界面验证](../../../CONTRIBUTING.md#界面验证) 实际操作并保存前后截图；页面 PR 的截图必须可供审查者访问，预览步骤与构建不能替代
+
+## 后端任务
+
+加载并使用 `$rust-best-practices`，先按架构文档定位事实归属与既有调用链，实现后逐项执行 [后端自审](../../../docs/architecture.md#后端自审) 中与本次改动相关的检查。
+交付说明实际复用位置、重要边界的处理与验证缺口，不用“符合最佳实践”或“CI 已通过”代替自审结论。
+
+## 执行顺序
+
+1. 从仓库根目录确认工作区、当前任务范围和相关运行实例；保留已有改动。
+2. 按 `AGENTS.md` 的 CodeGraph 约定定位入口、调用链和职责归属，再阅读相关实现。
+3. 按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 核实触发条件、问题发生版本与目标分支现状，
+   优先依据适用的官方源码确定或评估方案。结合上表读取所需文档，先找可复用的同类实现，再按授权修改或审查所属模块。
+4. 文档和运行结果不一致时，追查当前源码、配置与版本，区分实现缺陷和文档过期；
+   按 [文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件) 判断是否修订，不为每次改动追加文档或发布说明。
+5. 复核相对目标基线的完整差异及上下游：开发时清理本次引入的职责越界、重复逻辑、冗余状态和无依据的分支；仅审查时报告问题与依据。页面与后端分别按上述任务入口执行，不等待 PR 审查代做开发自审。
+6. 交付前按文档职责逐段复核最终文档 diff：新增内容是否回答当前读者的使用或维护问题，是否属于该文档，
+   是否与其他位置重复，脱离本次变更背景能否独立理解。仅解释实现经过、前后对比或验证结果的内容移到
+   任务报告或 PR；仍影响升级、恢复的说明保留适用条件与操作。没有文档差异时，只核对行为变化是否使现有说明失真。
+7. 按 `CONTRIBUTING.md` 验证并报告结果。后端 Cargo 命令从 `backend/` 执行，或显式指定该目录的 manifest。用户要求提交或更新 PR 时，进入 `cpr-github-pr` 流程整理最终证据与正文。
+
+发布任务按 `cpr-release` 技能读取当前版本、发布入口和工作流，发布说明语言遵循 `CONTRIBUTING.md`。

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "cpr-dev-guide"
+  short_description: "仓库开发、修复、排查、代码审查与文档修改的流程入口"
+  default_prompt: "使用 $cpr-dev-guide 按当前任务定位问题与现有实现，完成已授权的开发或审查，并自审、验证和报告结果。"
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,61 @@
+---
+name: cpr-github-issue
+description: 整理、创建和补充 GitHub Issue。用户说“提／开／提交一个 Issue”“报个 bug 到仓库”“反馈给上游”“把问题或功能建议整理成 Issue”“补充这个 Issue”时主动使用；已有 Issue 反馈上下文中的“提交吧”“补上复现”也适用。处理缺陷、功能与协作规则反馈，区分草拟和发布。Use for drafting, filing and updating issues; standalone “审查问题／看下报错／修一下” belongs to cpr-dev-guide, not automatic Issue submission.
+---
+
+# 整理与提交 Issue
+
+本仓库流程见 [贡献与审查](../../../CONTRIBUTING.md)，按场景选择当前的
+[接口问题反馈](../../../.github/ISSUE_TEMPLATE/api-bug-report.yml)、[常规问题反馈](../../../.github/ISSUE_TEMPLATE/general-bug-report.yml)
+或 [功能建议](../../../.github/ISSUE_TEMPLATE/feature-request.yml) 表单。从表单读取字段与必填项，不在技能中复制一份字段清单。
+用户指定其他仓库时，使用该仓库当前的贡献规则与 Issue 模板，不能把这里的表单套过去。
+
+## 确定目标和动作
+
+- 根据用户 URL、仓库上下文和 remote 确认接收 Issue 的仓库。fork 场景核对用户要反馈给自己的 fork 还是上游。
+- “写一份、整理内容、草拟 Issue”只准备正文；明确要求“提交、创建 Issue”才发布。
+  已经授权提交且信息足够时直接完成，不重复索要确认；仅自动选中技能不能授权发布。
+- “有个 bug”“这个报错怎么修”本身是排障语境，不能推断要发 Issue；结合已有反馈任务识别省略的目标和动作。
+- “补充这个 Issue”先读取原帖与已有讨论，按授权更新正文或追加证据，不重复新建；需要排查或修改本仓库时先执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)。
+- 缺少无法推断的目标或关键复现事实时，只问必要信息，并先整理其余已有证据。
+- 使用可用的 GitHub 连接器或 `gh`。不要为提交 Issue 安装新工具、修改仓库配置或启用额外服务。
+
+## 证据与去重
+
+1. 读取目标仓库实际 Issue 模板和配置，区分缺陷、功能建议与协作规则提案。
+   本仓库功能建议有独立表单，协作规则提案允许普通 Issue；其他仓库按其配置选择入口。
+2. 先搜索 open 和 closed Issues，结合关键词、错误信息与触发条件检查重复，而不只比较标题。
+   同时核对相关 PR 与发布记录，关联已有修复及其发布版本；仅主分支已修复时明确尚未发布。
+   同一问题已有记录且没有新增证据时返回已有链接；用户仍明确要求新建时按其要求处理。
+   不因发现重复而擅自评论、重开或关闭已有 Issue。
+3. 从用户描述、当前版本与已有诊断中整理事实：区分实际结果、预期结果、稳定复现条件和未经证实的推测。
+   不把本地开发版本当作发生问题的部署版本；无法复现时如实说明已知条件。
+   引用官方行为或提出实现方案时，按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 注明来源、版本与缺口；
+   不把找到官方源码或证明根因作为提交症状反馈的前提。
+4. 只收集定位所需信息。正文、日志片段和附件去除密钥、Cookie、令牌、代理认证、私人请求内容等敏感信息；
+   不直接附完整配置或请求转储。记录与复现相关的代理、TUN、证书条件，不擅自修改这些环境来收集材料。
+
+## 编写正文
+
+- 标题写具体症状或所需行为，不预先断言尚未证明的根因。语言与目标仓库及用户要求一致。
+- YAML Issue Form 按字段顺序使用 `attributes.label` 作为 Markdown 小标题，填写相应答案。
+  `gh issue create --body-file` 直接提交正文，不会替你完成网页表单校验；手动核对必填字段、选项和必选确认项。
+  不把原始 YAML、占位文字或尚未确认的勾选项当成答案提交。
+- 无法获知的信息明确写未提供或不适用，并说明理由；如果该事实关系到能否理解或复现问题，发布前补齐。
+  功能或规则提案说明当前场景、缺少的能力、建议结果和必要取舍，不强行填写缺陷复现步骤。
+- 附件只使用用户授权发布且实际可访问的地址；本机 `/tmp/...` 路径不能作为 GitHub 附件。
+  没有可用附件时保留操作描述并说明缺口，不声称截图已上传。
+- 使用模板规定或用户要求的 labels、assignees；先确认它们在目标仓库存在，不自行猜测。
+
+## 提交与收尾
+
+把核对后的 UTF-8 正文写入临时文件，或直接传给连接器的结构化字段。CLI 变量先从已确认的目标与正文赋值：
+
+```bash
+gh issue create --repo "$issue_repo" --title "$issue_title" --body-file "$issue_body_file"
+```
+
+发布前快速复核目标、必填内容、脱敏及重复记录；更新已有 Issue 时保留与本次无关的内容，核对目标编号和当前正文。
+网络超时或返回不明确时先查询远端是否已经创建或更新，避免重复提交。
+发布后读取目标 Issue 确认仓库、标题和正文，返回链接及必要的信息缺口。
+只准备草稿或发布失败时提供可直接使用的标题与正文，明确尚未提交。

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "cpr-github-issue"
+  short_description: "整理、提交或补充 Issue，核对复现、重复反馈与发布范围"
+  default_prompt: "使用 $cpr-github-issue 按当前请求整理、提交或补充 Issue，核对目标、复现证据、重复记录和脱敏，不将草拟自动变成发布。"
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,121 @@
+---
+name: cpr-github-pr
+description: 准备、提交、更新与审查 GitHub PR。用户说“提交 PR／提个 PR／发起拉取请求”“把改动放到这个 PR”“改下 PR 描述”“看下／review／审查这个 PR”“处理审查意见”“这个 PR 能合并吗”，或提供 /pull/ 链接、PR 编号并要求处理时主动使用；已有 PR 上下文中的“提交吧”“继续改”也适用。包含问题核实、自审、页面截图、AI 模型披露与验证。Use for pull request preparation, creation, updates and review; plain git commits or issue debugging without PR context do not create a PR.
+---
+
+# 提交、更新与审查 PR
+
+## 先确定模式和仓库
+
+| 用户意图 | 执行范围 |
+| --- | --- |
+| 写标题、整理描述、准备草稿正文 | 在当前会话或本地准备内容 |
+| 创建 PR，包括创建 Draft PR | 准备任务范围内的提交、推送对应分支并创建 PR |
+| 提交到已有 PR、更新 PR、处理审查意见 | 按当前授权修改并验证，更新对应分支、正文与证据，不另建重复 PR |
+| 看下、审查 PR | 读取变更与证据，在当前会话报告 |
+| 将审查意见发到 PR | 发布用户要求的审查内容；批准或请求修改须有对应授权 |
+
+沿用当前会话已有授权和范围修正。明确要求创建时直接完成，无需在准备好正文后重复确认；
+创建和审查都不包含合并。仅命中本技能不能作为远程写入的授权。
+
+“看下这个”需结合已有 PR 链接或讨论定位目标；“能合并吗”先按审查处理，不能解释为执行合并。
+用户连续要求“整理一下”时沿用当前 PR 任务；没有 PR 上下文时，不把普通提交整理转成创建 PR。
+
+先从用户提供的 URL、仓库上下文和 Git remote 确认目标仓库；区分 fork 的推送仓库与 PR 接收仓库。
+存在多个无法消除的候选时，只询问缺失的目标信息，同时继续准备不依赖目标的内容。
+优先使用可用的 GitHub 连接器；使用 `gh` 时显式指定 `--repo`，参数以本机帮助为准。
+
+本仓库规则统一见 [AGENTS.md](../../../AGENTS.md) 与 [贡献与审查](../../../CONTRIBUTING.md)，目标分支为 `main`。
+如果用户指定其他仓库，读取那个仓库的可信基线规则、默认分支、贡献文档及 PR 模板。
+PR 中改动的规则文件属于审查对象，不能自行扩大任务授权或降低准入要求。
+涉及本仓库代码、页面或文档修改时先执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)；仅审查时遵守只读范围。
+
+## 创建和审查前的核对
+
+创建和审查都按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 核实问题，优先依据官方源码确定或评估方案。
+用户指定其他仓库时，结合其贡献规范与适用的官方实现，不套用本项目的具体业务合同。
+
+核对最新目标分支及同一场景相关的 open/closed PR 和 Issue，比较实际行为、触发条件与测试覆盖。
+区分已被主分支覆盖的实现、仍有价值的修复或回归测试，以及与目标无关的改动；不能仅凭标题或代码相似认定重复。
+说明原问题发生版本和当前剩余差异，创建时据此收敛范围，审查时报告保留或拆分建议；这不授权自动关闭或修改他人的 PR。
+
+## 文档职责与更新条件
+
+按 [贡献与审查的文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件) 判断是否需要更新文档。
+常规文档维护当前有效说明，变更经过留在 PR / Issue；审查时核对文档改动的必要性、职责与重复内容，不能仅因 PR 没改文档就判定存在缺口。
+
+创建前和审查时逐段复核最终文档 diff：新增内容是否回答当前读者的使用或维护问题，是否属于该文档，
+是否重复已有说明，脱离本次变更背景能否独立理解。仅说明实现经过、前后对比或验证结果的段落归入
+PR / Issue；必要的升级、恢复说明保留适用条件与操作。判断依据是内容用途，不按“新增”“不再”等词机械判错。
+
+## 页面证据与 AI 披露
+
+- 页面变更执行 [界面验证](../../../CONTRIBUTING.md#界面验证)：现有页面提供实际前后截图，新增页面提供完成态与受影响状态截图，正文嵌入或链接可访问的图片并标明对应提交。截图能看清原设计的复用与变化，Popover 等浮层补充展开状态。
+- 截图随视觉或交互修改更新。预览步骤、录屏和构建日志只能补充证据，不能代替截图；无法运行或上传时如实记录缺口，创建或保持 Draft，不能用本机路径或占位图片伪装为已提供。
+- 按 [AI 使用披露](../../../CONTRIBUTING.md#ai-使用披露) 记录实际使用的工具与模型型号，多个模型分别列出。不能猜测模型、把工具名当型号或漏掉更新阶段使用的模型；未知型号作为待补项。
+
+## 创建或更新 PR
+
+1. 检查工作区、当前分支、远端和近期提交格式。读取实际存在的 PR 模板，按最终变更重写标题与描述。
+   不用提交日志拼接正文，也不假定仓库一定有模板。
+2. 更新并确认 base/head，查看相对 merge-base 的完整差异和待提交内容；核对仓库的受保护文件与准入规则。
+   只纳入任务范围的文件和提交；需要整理时用独立功能分支，保留用户其他改动，不擅自改写已发布历史。
+3. 按上述核对流程，在目标分支基线核实问题，追踪官方与本项目的相关调用链，先确定解决方向再实现。
+   若改动已完成，也要据此复核问题与方案；需要修正时只修改已授权的范围。仅整理标题或正文时报告差异与缺口，
+   不自行修改实现。原问题不成立时不将它包装成已修复的缺陷；证据不足时明确保留结论。
+   按 `cpr-dev-guide` 完成实现自审；后端按 [后端自审](../../../docs/architecture.md#后端自审) 核对归属、状态、失败出口与副作用，
+   页面先复用已有设计并检查文案密度。处理本次引入的冗余与越界问题，功能可用和检查通过不能替代可维护性自查。
+4. 查找同一来源仓库、head 和 base 的现有 PR；已存在则复用其链接，不重复创建。
+   更新现有标题或正文须在本次整理/更新请求范围内。
+5. 按贡献文档执行适用检查。记录实际验证的提交或工作区状态，区分通过、失败、跳过和未执行。
+   按上述文档复核步骤检查最终 diff；没有文档差异时，核对行为变化是否使现有说明失真。
+   页面改动按上述规则补齐截图与实际交互证据，核对模型披露是否完整。
+6. 将任务范围内的提交推送到正确远端，核对远端 head。标题遵循项目约定，正文先说明问题成立的依据和最终行为，
+   再给必要的设计取舍、自审结论、验证与遗留事项，按模板附页面截图和 AI 使用情况。涉及官方行为时，写明官方源码位置与版本或提交、官方处理方式、
+   本次实现与它的关系及必要的偏离原因；区分源码推断和实际复现，不用检查通过替代方案论证。按规模压缩，不强填无关章节。
+7. 明确要求草稿或仍有阻塞项时创建或保持 Draft PR，并解释原因；必需截图或 AI 模型披露待补时也不标为可审阅。具备审查条件且未要求草稿时创建普通 PR。
+   GitHub Draft 状态与“只写本地草稿正文”不同，后者不创建远程对象。
+8. 创建或更新后回读正文与附件，核对链接、base、head、草稿状态、模型披露和最新检查结果。网络超时或结果不确定时先查询远端，再决定是否重试。
+
+CLI 示例中的变量必须先根据上述检查赋值；`pr_body_file` 是精确写入 UTF-8 正文的临时文件：
+
+```bash
+gh pr create --repo "$pr_repo" --base "$pr_base" --head "$pr_head" \
+  --title "$pr_title" --body-file "$pr_body_file"
+```
+
+按需添加 `--draft`。不要用 `gh pr create --dry-run` 做只读预览，它仍可能推送 Git 变更。
+多行正文通过文件或连接器的结构化字段传递，不把未转义正文拼进 shell 命令。
+创建完成返回链接、目标分支和验证摘要；不要称为已合并或已获维护者批准。
+
+## 审查 PR
+
+1. 获取 PR 的 base/head SHA、描述、文件差异、已有讨论及 CI 状态。记录实际审查的 head，使用 merge-base 差异。
+   需要源码上下文时先遵守目标仓库的定位规则；需检出时使用隔离工作区，保留用户当前分支和运行环境。
+2. 先核实 PR 要解决的问题是否成立：提取触发场景、预期行为和声称的原因，在目标分支基线检查实际行为。
+   按上述核对流程收集一手证据，区分原有问题、环境或配置差异与 PR 新引入的问题，说明主分支已覆盖的部分。
+3. 从官方方案评估解决方向：说明官方如何处理同一场景，检查 PR 是否遵循其协议语义和职责归属、
+   是否复用已有能力或正确传递官方合同；核对偏离官方方案的理由与运行证据。
+   审查 OpenAI 官方上游与 Codex 的对接时，默认官方返回与 Codex 兼容、直接对接正常，重点检查本项目是否误解、
+   改写或破坏官方合同。不得仅凭自行构造的异常上游数据揣测官方不兼容，也不据此报告缺陷、提出改进建议，
+   或要求增加防御分支与测试。讨论特定版本或场景的对接例外须有真实响应或实际复现证据，并区分代理链路与官方直连。
+4. 按贡献文档的审查维度追踪完整调用链，找到共享业务事实、同类实现及已有验证。
+   对既有特殊分支查清服务的场景，再判断本次改动是否引入或加重问题。
+   主动检查本次变更新引入或加重的冗余与代码异味，说明具体位置、维护成本或行为影响及最小修复方向；
+   不能仅因功能可用、CI 通过而略过，也不把个人写法偏好判为缺陷。
+5. UI 改动同时对照原页面、主题、共用组件和同类页面，核对结构变化的必要性、文案是否重复及帮助是否适合收进 Popover。
+   按页面类型检查必需截图是否齐全、可访问且对应待审实现；缺少必需截图时要求补齐并列为未具备审阅条件。
+   浏览器可用时检查相关交互；未运行的检查列为验证缺口，不从截图或源码推断所有状态都正确。
+6. 核对 CI 与本地证据是否覆盖当前 head；根据风险补充必要验证，不触发无关部署或真实账号业务请求。
+   按上述文档复核步骤检查最终 diff，不能把构建或链接检查通过当作文档内容已经合格。
+   核对 AI 使用与模型披露，缺项明确指出。工具不可用、集成测试跳过或环境不足时具体说明影响范围。
+7. 按 [审查标准](../../../CONTRIBUTING.md#审查标准) 用中文先回答原问题是否成立、解决方向是否合理，
+   再列出实现问题与验证缺口，结论附具体依据。
+   实现问题区分必须修复项、可选建议和验证缺口；没有的类别可省略。
+   每个问题给变更中的文件位置、触发条件或规范依据、影响和最小修复方向。
+   复用建议指出具体已有实现，不把个人偏好写成缺陷；未发现问题时直接说明并交代覆盖范围。
+8. 结束前核对 head 是否变化。发生变化时检查新增差异并更新结论，或明确结论只适用于原 SHA。
+
+审查本身不修改源码、不发表评论、不提交 GitHub 的批准或请求修改状态。
+用户明确要求发布时，先复核当前 head 和重复评论，再通过结构化字段或 `--body-file` 发布对应内容；
+需要绑定具体提交时使用支持 commit ID 的审查接口。不要在旧提交结论上批准新的 head。

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

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

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

@@ -0,0 +1,85 @@
+---
+name: cpr-plugin-dev
+description: 开发、排查和打包 Codex Proxy RS 网关插件。用户说“写／做一个网关插件”“给插件加能力或页面”“改 plugin.json”“接入公开 SDK”“插件不生效／接入报错”“打包插件”时主动使用，覆盖能力选择、SDK 处理器、管理页面和安装包验证。Use for gateway plugin authoring and debugging; host Runtime/installer changes use cpr-dev-guide, not this workflow, and OpenAI .codex-plugin or Vue plugins are outside its scope.
+---
+
+# cpr-plugin-dev
+
+面向插件作者。插件在独立项目中实现，通过公开 SDK 与宿主通信，不向宿主业务模块添加分支。
+仅修改宿主安装器、Runtime 或管理端时，使用仓库开发指南，不按本技能创建插件工程。
+本仓库开发与排查同时执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，准备、提交或审查插件 PR 时执行 [cpr-github-pr](../cpr-github-pr/SKILL.md)。
+
+## 先建立正确的模型
+
+```text
+选择能力 → 作者清单 + SDK 处理器 → 构建二进制／页面 → cpr-plugin package
+                                                       ↓
+实际业务验证 ← 查看权限并安装、自动准备配置 ← tar.gz + sha256
+```
+
+- `contributes` 声明提供什么，`permissions` 声明访问域；安装接受记录派生授权，`bindings` 只决定功能挂载和请求匹配
+- 安装包、运行配置和已启用功能不是同一件事；安装成功不能代替功能验证
+- `trustedProcess` 与宿主使用相同系统身份，不是操作系统沙箱
+
+## 开始工作
+
+1. 确认插件用途、已有工程／输出目录、目标宿主版本与平台。已有项目沿用其结构；没有指定工程时先确认目录，不把插件源码塞进宿主 workspace
+2. 先读 [SDK 入口](../../../backend/crates/gateway-plugin/sdk/README.md) 和[清单](../../../backend/crates/gateway-plugin/sdk/docs/manifest.md)，再按下表只选本次需要的能力章节
+3. 核对实际运行宿主的版本、目标版本的 [SDK Cargo.toml](../../../backend/crates/gateway-plugin/sdk/Cargo.toml) 与[宿主支持清单](../../../backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json)。同时确认打包 CLI 使用相同作者清单合同；不要只看源码版本或依赖包版本号。清单版本、通信版本、能力版本各自独立
+4. 需要构建、联调或交付时读取 [构建与验证](references/development.md)，先检查实际依赖和脚本，不假设包已公开发布；通过 GitHub 交付时另读其中的[发布与安装来源](references/development.md#发布与安装来源)
+
+本技能相对链接以各文件所在目录解析；主仓根目录是本文件所在目录向上三级。插件工程或同级示例不在磁盘上时，请用户提供位置或使用选定版本的公开资料，不猜开发机绝对路径，也不自动克隆或创建远程仓库。
+
+## 按任务选择能力
+
+| 用户要做什么 | 优先使用 | 需要读取的合同 |
+| --- | --- | --- |
+| 改写请求／响应、处理流式内容、协议转换 | `middleware` | [洋葱中间件](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#洋葱中间件) |
+| 改变模型选择或账号排序 | `model_router` / `scheduler` | [策略类型](../../../backend/crates/gateway-plugin/sdk/src/call/policy/mod.rs)，宿主继续复验范围、资格和租约 |
+| 发布模型别名 | `model_catalog` | [模型目录](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#模型目录)，注册时冻结直接目标，不需要请求绑定 |
+| 读取基础数据制作管理页面 | `management` + `data` 权限 | [基础事实](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#基础事实)，不需要账号凭据授权 |
+| 选择宿主允许的重试动作 | `retry_policy` | [重试决策](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#重试决策)，不能修改预算或自行重复调用 next |
+| 统计成功失败、用量或观察 WS 帧 | `request_lifecycle` / `usage` / `web_socket_observer` | [路由、调度与观察](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#路由调度与观察)，观察不改写业务结果 |
+| 接受外部客户端身份 | `frontend_authentication` | [数据面入口认证](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#数据面入口认证)，映射现有 Client Key，不接管后台登录 |
+| 增加插件页面与管理操作 | `management` | [管理页面、公开入口与 CLI](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#管理页面公开入口与-cli) |
+| 提供终端命令 | `command_line` | [管理页面、公开入口与 CLI](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#管理页面公开入口与-cli) |
+
+只声明实现了的能力。Provider 固定为宿主内置的 OpenAI 与 xAI；插件只能扩展已开放的处理与管理能力。
+网络、账号、模型调用和私有状态属于宿主回调与授权，不重复声明为顶层能力。
+
+## 实现时的关键选择
+
+### 清单与处理器
+
+- `publisher` 与机器短名 `name` 派生插件 ID，`displayName` 用于展示；复制示例后同时调整扩展项 ID 与注册结果
+- `contributes` 每种能力最多一项，普通贡献项可省略派生 ID、能力版本和固定阶段；中间件阶段仍需显式选择。自定义完整扩展项 ID 属于自己的插件命名空间，运行注册与规范化清单一致
+- 作者清单用 `Manifest::from_author_slice` 规范化，不手写 `package`、固定阶段或重复注册；CLI 生成平台、协议与资源摘要，版本范围不能使用全版本通配
+- 安装后宿主会按 `configurationSchema` 准备默认配置，配置完整即可启用；默认绑定的空范围不限制请求。需要业务参数时声明真实必填项，通过 `secretFields` 声明敏感字段，不依赖用户再走一遍自建安装向导
+- Rust 插件只依赖公开 `gateway-plugin-sdk`；需要异步会话辅助时开启 `io`，使用 `PluginSession` 管理握手、回调关联、流控、取消和关闭
+- 优先用 `PluginBuilder::from_json` 组合 `.middleware`、`.management`、`.command_line` 与 `.on(methods::..., handler)`，由构建器生成注册并检查处理器；单一中间件也可用 `MiddlewarePlugin`
+- stdout 是二进制协议通道，不能用 `println!` 输出诊断。使用基础设施 `host.log`，不输出 secret 或完整请求
+
+### 中间件与宿主服务
+
+- `request` 包裹整个逻辑请求，`attempt` 在每次选定账号的尝试中执行；根据作用范围选择，避免重试时重复副作用
+- `next` 只能消费一次。使用 SDK 的正文保留与流式映射能力，不自行拼一套 SSE／取消／流控机制；请求、响应及策略处理使用 `requests` 域
+- 持久化状态使用已声明命名空间的 `host.state.*`，账号读写使用 `host.auth.*`，不直接访问宿主数据库。见[账号与凭据](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#账号与凭据)和[状态、日志与迁移](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#状态日志与迁移)
+- 权限只声明 `network`、`models`、`accounts`、`data`、`requests`、`public_endpoints`；日志和自身状态无需授权项。安装器不配置 Key／账号白名单，资源选择属于插件业务
+- 模型、网络和亲和查询使用当前父调用的受管回调。管理／CLI 等独立入口调用模型时传明确的 Key ID；请求处理阶段继承父身份。见[Key、模型与模型调用](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#key模型与模型调用)
+- SDK 操作名不是管理员 HTTP 路由，不能据此拼接口地址；宿主身份、账单事实和调用授权也不能由插件覆盖
+- 路由与调度只读取宿主投影的请求事实，身份头可能被隐藏；使用已有会话和亲和合同，不依赖原始认证头或根据缓存键补造客户端身份
+
+### 只有需要页面时才创建前端
+
+- 沿用已有插件页面与 [管理端主题](../../../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 实例
+- 管理路由的响应正文由插件业务定义，不默认套用宿主管理 API 的 `{ code, message, data }`；页面与处理器共享实际合同，GET 无正文时不附带 JSON 正文声明
+- `host.model.*` 子请求跳过发起插件，不能用它证明本插件中间件／路由已参与；需要完整请求链的示例使用页面模型桥或真实客户端
+- JS、CSS、图标等资源随包构建和声明；沿用宿主桥的主题同步。Vite 本地预览不等于已安装插件的热更新，宿主验证仍需重新构建、打包和切换版本
+
+## 交付
+
+按[构建与验证](references/development.md#验证与交付)提供源码位置、能力／权限／绑定摘要、实际运行结果及验证缺口。
+开发插件不默认授权安装并启用本机进程、调用真实上游、发布依赖或推送仓库；超出当前授权时交付可安装包及操作步骤。

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "cpr-plugin-dev"
+  short_description: "网关插件开发、接入排障、SDK 实现、页面与打包验证"
+  default_prompt: "使用 $cpr-plugin-dev 按当前请求开发、排查或打包 Codex Proxy RS 网关插件，复用公开 SDK 与已有页面并验证实际行为。"
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,114 @@
+# 构建、联调与验证
+
+仅在准备工程、构建或验证插件时读取。这里给出执行入口，不复制 SDK 协议或安装 API 的字段手册。
+
+## 工程与依赖
+
+| 位置 | 用途 |
+| --- | --- |
+| 主仓 `backend/crates/gateway-plugin/sdk/` | Rust 公开合同、会话辅助与能力文档 |
+| 主仓 `backend/apps/plugin-cli/` | `cpr-plugin package`，只校验与打包，不编译插件源码 |
+| [codex-proxy-plugins](https://github.com/zyycn/codex-proxy-plugins) 的 `examples/workbench/` | 基础能力体验与文本工作流示例，按需选择功能，不整体复制 |
+| [codex-proxy-ui](https://github.com/zyycn/codex-proxy-ui) | 可选的 Vue UI 库、组件文档与 playground |
+
+先检查用户给定工程，或主仓父目录下的同级仓库是否存在；读取实际仓库约定、README、`Cargo.toml`、`package.json` 与锁文件。
+只需中间件时不复制示例的管理 API、页面和相关权限；CLI 等能力从 SDK 对应合同起步，不给示例添加无关能力。
+
+本地源码联调可以使用 Cargo 路径依赖和 pnpm 的包级链接／override；路径必须真实可解析，并记录在消费方依赖配置中。
+这不等于允许从业务源码跨仓 `import .../src/...`，也不能证明第三方能独立安装。
+
+对外交付前核实 UI／SDK 的可用版本和安装来源：仅引用确实存在的发布版本，或包含所需合同的固定 Git commit；
+不要把浮动 `main` 当版本，也不要自动发布依赖以补齐条件。本地 override 尚未移除时，明确说明独立安装缺口。
+所用工具链以目标项目的配置为准，不因本机安装了更新版本而顺手升级。
+
+## 复用示例
+
+找到 `codex-proxy-plugins` 后先读根目录与 `examples/workbench/README.md`。
+该仓库使用 `bash scripts/package` 构建页面、Rust 二进制并打包；前端依赖和工具配置位于示例的 `frontend/`，根目录不维护 Node 工程。执行前核对脚本适用的插件路径和目标平台。
+
+| 任务 | 示例入口 |
+| --- | --- |
+| 身份、声明与资源 | `examples/workbench/plugin.json` |
+| 会话启动与处理器组合 | `examples/workbench/backend/src/main.rs`、`app.rs` |
+| 管理接口 | `examples/workbench/backend/src/management/` |
+| 页面与主题 | `examples/workbench/frontend/src/` |
+| 管理接口调用 | `examples/workbench/frontend/src/api/modules/` |
+| 包内静态资源构建 | `examples/workbench/frontend/vite.config.ts` |
+
+若派生新插件，同时修改包名、二进制名、插件身份、扩展项 ID、注册描述和构建目标，不只改展示名称。
+保留当前项目确实需要的依赖、资源和权限；不要把示例中的全请求范围直接用到共享环境。
+
+## 构建与打包
+
+先运行目标工程已有的测试和构建入口。Rust 检查示意如下，路径、工具链和 target 按实际工程替换：
+
+```bash
+cargo fmt --manifest-path /path/to/plugin/Cargo.toml -- --check
+cargo clippy --manifest-path /path/to/plugin/Cargo.toml --all-targets --all-features --locked -- -D warnings
+cargo test --manifest-path /path/to/plugin/Cargo.toml --locked
+cargo build --manifest-path /path/to/plugin/Cargo.toml --release --locked --target x86_64-unknown-linux-gnu
+```
+
+新工程尚无锁文件时先生成并检查锁文件；不要把缺少锁文件的 `--locked` 失败当作源码问题。
+有页面时另跑该前端项目的检查与生产构建，确认产物路径、资源清单和 MIME 类型相符；无页面的插件无需 Node 项目。
+
+先检查实际调用的 `cpr-plugin` 路径与构建来源。已有工具只有在支持目标作者清单时才复用；
+遇到派生字段被要求手写或支持能力不符时，对照目标 SDK 和 CLI 合同，不通过改写清单迁就过期工具。
+需要从目标宿主源码构建工具时，在主仓根目录运行以下命令，把 `--help` 换成实际参数即可，不必全局安装：
+
+```bash
+cargo run --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked -- package --help
+```
+
+直接打包的示意命令：
+
+```bash
+cpr-plugin package \
+  --manifest /path/to/plugin/plugin.json \
+  --binary /path/to/plugin/target/x86_64-unknown-linux-gnu/release/plugin \
+  --target x86_64-unknown-linux-gnu \
+  --resource-map web=frontend/dist \
+  --output-dir /path/to/plugin/dist
+```
+
+没有 `web` 资源时去掉 `--resource-map`。映射源相对于作者清单目录，而非命令执行目录；资源必须留在插件工程内。
+目标平台指运行宿主的服务器／容器，不是访问管理端的浏览器所在电脑；平台与二进制必须匹配，不能只改 target 参数伪装交叉编译。支持平台以 [CLI 文档](../../../../backend/apps/plugin-cli/README.md)及实际 `--help` 为准。
+
+输出为 `.tar.gz` 与 `.sha256`，不是源码 zip、npm 包或页面目录。归档根目录应有生成后的 `plugin.json`、可执行文件和声明资源。
+安装时以本次输出的包摘要为准，核对包内版本、平台、能力和 `engines` 与实际运行宿主匹配；
+源码已更新不代表 `dist` 中旧包已重建。版本要求未满足时使用兼容宿主或确有依据的兼容声明，不跳过宿主检查。
+本地同版本反复试验与对外发布区分处理；发布新内容使用明确的新版本，不覆盖已发布版本。
+
+## 发布与安装来源
+
+仅在用户要求发布或准备分发时执行；沿用目标插件仓库的发布流程，核对源码提交、包内版本、目标平台与产物摘要。
+
+- GitHub 安装读取 Release 附件，发布时上传实际生成的 `.tar.gz`／`.tgz` 和校验文件；仅推送 tag 或保留 GitHub 自动生成的源码归档，不能提供可安装插件
+- 稳定版应发布为非 Draft、非 Pre-release；需要支持留空标签安装时，再核对最新稳定版查询能返回预期 Release。版本号没有预发行后缀，不代表 GitHub 的发布状态已经是正式版
+- 当前宿主在标签留空时只查询最新稳定版；预发行版安装需要同时指定标签并允许预发行，不把该开关解释成自动发现预发行版
+- 多平台或多插件附件由用户按实际发布内容选择，文件名帮助辨识，包内清单才是平台、版本与兼容范围的依据
+- 发布完成后，从公开下载来源核对附件和摘要，再按已授权的目标环境验证安装；本地包验证不等于远程发行附件已经验证
+
+## 验证与交付
+
+按[插件使用](../../../../docs/plugins.md)验证“安装包 → 查看权限并安装 → 自动准备默认配置 → 实际使用”；只在缺少业务必填值时补配置，不添加授权或资源选择向导。
+只有获得目标环境操作授权才安装和启用；不把修改源码的授权扩展到生产实例或真实凭据操作。
+需要 API 自动化时查[插件管理 API](../../../../docs/api.md#12-插件管理)，不要依据记忆拼路由。
+
+按实际实现选择验证，不为不存在的能力增加测试任务：
+
+| 实现范围 | 应验证的行为 |
+| --- | --- |
+| 中间件 | 匹配／不匹配范围、授权不足、下游错误与取消；支持流式时检查多帧、终态和断开；若涉及续链，使用真实目标客户端检查 HTTP/SSE、WS 及后续轮次 |
+| 模型路由／调度 | 真实入口能命中规则，未匹配请求保持原有行为；使用官方客户端正常携带的业务头和会话别名，确认投影不会拒绝合法请求，也不暴露身份字段 |
+| 生命周期／用量／WS 观察 | 完成一次实际模型请求并核对对应事件；WS 观察需确认实际上游采用 WS，HTTP 请求成功不能证明 WS 观察生效 |
+| 管理页面 | 从宿主打开，标题／副标题、明暗主题、加载与错误状态；管理桥请求成功；停用或版本切换后旧入口失效 |
+| 入口认证／CLI | 对应身份和账号范围、缺少授权、取消与错误；不把帮助输出、注册成功或一次健康探测当完整验收 |
+| 持久状态或升级 | 读写版本冲突、停用再启用后的持久状态、升级兼容性及迁移失败；版本配置恢复与私有状态迁移分别验证，不覆盖并发配置或把回滚版本误当恢复历史数据 |
+
+真实请求按用户选择的客户端、模型和测试预算执行；没有这些能力或授权时列为缺口，不模拟成功。
+外部示例测试若依赖未提供的仓库或制品，应记录为未执行；当前示例可用于实际能力联调，但不能把被忽略的测试计为通过。
+临时账号、Key 或配置只在明确的测试范围内创建，记录并清理自己创建的对象，不输出密钥、原始请求或插件 secret。
+
+交付简述：源码与产物位置、兼容范围、所需能力／权限／绑定、执行过的命令及结果、尚未验证的场景。
+只有确实生成了产物才报告“已打包”，只有目标环境业务验证成功才报告“已生效”；提交、推送与发布按用户授权另行执行。

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

@@ -0,0 +1,110 @@
+---
+name: cpr-release
+description: 准备、执行和排查 Codex Proxy RS 发版。用户说“发个版本／正式发版”“准备 vX.Y.Z”“推荐版本号”“整理更新日志／发布说明”“更新 release/notes.md”“发布 alpha／beta／rc／exp／实验版”“打发行 tag”“重试失败发版”时主动使用；已有发版上下文中的“发布吧”“继续发布”也适用。Use for release planning, notes, publishing and recovery; deployment/restarts and ordinary Git tag cleanup are not release requests.
+---
+
+# 发版
+
+## 识别任务范围
+
+| 用户意图 | 执行范围 |
+| --- | --- |
+| 推荐版本号 | 根据本次变更与已有版本给出建议及理由 |
+| 整理更新日志、写 note、准备发版 | 核对变更、编写说明、检查发布条件；未要求提交时保留本地改动 |
+| 正式发布、发布指定版本、打版本 tag | 在已授权范围内执行对应步骤；仅打 tag 的请求不自动扩展为完整发版 |
+| 发布 alpha、beta、rc | 从 `main` 发布，确定目标正式版本和阶段，核对预发行标记与晋级路径 |
+| 发布实验版、exp 版本 | 从目标实验分支发布，按下方实验版流程确定版本、文案和渠道隔离 |
+| 重试失败的发版 | 核对上次执行状态，从未完成的步骤恢复 |
+
+沿用当前会话明确的版本、范围与授权；用户已授权发布目标版本且条件满足时直接执行，不重复确认。
+“准备好了”“可以发版吗”属于准备或检查，不能解释成正式发布；创建本技能也不触发发版。
+发行版发布与运行实例升级分开判断，“上线”需结合上下文确定用户指哪一种。
+需要修复本仓库代码、工作流或文档时先执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，准备或更新相关 PR 时执行 [cpr-github-pr](../cpr-github-pr/SKILL.md)，不以发版步骤替代开发自审。
+
+稳定版以及面向下一正式版本的 alpha、beta、rc 从 `main` 发布，预发行 tag 使用 `vX.Y.Z-<阶段>.N`。
+发版前读取[版本命名与升级规则](../../../deploy/README.md#版本命名与升级规则)，作为命名、阶段晋级和更新边界的权威约定。
+实验版从对应的 `experimental/<用途>` 分支发布，版本与 tag 采用 `vX.Y.Z-exp.N`，
+展示标题包含分支用途名；先读 [实验版发布](references/experimental.md) 确定标题与编号，再复用本文的准备、执行与验收步骤。
+实验功能是否合入 `main` 是单独的维护决策，发布实验版不包含合并功能的授权。
+
+## 读取当前流程
+
+先读 [AGENTS.md](../../../AGENTS.md) 与 [贡献与审查](../../../CONTRIBUTING.md)，再按任务检查：
+
+| 事实 | 权威入口 |
+| --- | --- |
+| 当前版本 | [release/version.yaml](../../../release/version.yaml) |
+| 本次发布说明及语言约定 | [release/notes.md](../../../release/notes.md)、贡献文档的项目约定 |
+| 版本提交、tag、推送与工作流触发 | [release/publish](../../../release/publish) |
+| 构建、检查、GitHub Release 和镜像发布 | [发布工作流](../../../.github/workflows/release.yml) |
+| 平台与产物清单 | [release/platforms.yaml](../../../release/platforms.yaml) |
+
+命令从仓库根目录执行；每次以当前脚本和工作流为准，不另写发布脚本或绕过已有质量检查。
+用户明确指定其他仓库时先读取其发布流程，不能直接套用这里的路径和命令。
+
+## 发行通道核对
+
+- alpha 是下一正式版本的早期开发阶段，beta 是功能测试阶段，rc 是发布候选，exp 是临时功能实验。
+  预发行采用 `vX.Y.Z-<阶段>.N`，`N` 从 1 开始；正式版不带预发行后缀，不新增未约定的通道名称。
+- 更新候选由本次检查或安装选择的通道决定：Stable 仅正式版，RC 包含正式版，Beta 包含 RC 与正式版，Alpha 包含所有常规阶段。
+  仅接收同一大版本内严格更高的版本，可跟随后续小版本与补丁版本，默认按运行版本推导通道；临时选择不保存、不允许降级。
+  exp 仅接收同基线、同一轮实验的后续编号，不能跨实验线或转入其他阶段；不同实验分支不得共用一个 `X.Y.Z-exp.N` 系列。
+- 核对目标工作流的构建类型：正式版及 alpha、beta、rc 为 `release`，exp 为 `experimental`。
+  所有预发行均标记为 Pre-release，不设置 GitHub Latest、不覆盖镜像 `latest`。
+  发布预发行前记录这两个稳定入口，发布后回读确认未改变。
+- 验收更新器时，核对检查更新与执行更新使用相同规则。只有当前构建支持更新且存在允许的更高目标时
+  才能返回 `hasUpdate=true`；被禁止的目标即使版本领先，也不能出现在更新标记、可用版本或发布说明中。
+  检查失败须单独报告。核对上一发行实际包含的更新能力，不能因新包支持在线更新就宣称旧包也能在线安装它。
+
+## 准备版本与说明
+
+1. 确认发布类型、对应分支、upstream、目标仓库、工作区和完整待推送范围；
+   未提交或未跟踪内容分别核对，不因脚本只检查已跟踪文件就认定所有内容都已纳入发布。
+2. 读取版本文件、已有 tag 和实际发行记录，确认上一发布基线与本次目标提交。
+   根据基线到目标的提交和最终差异归纳变更，剔除回退、重复和未进入发布范围的内容。
+   不能只用当前版本文件或最近几条提交判断“本次更新”。
+3. 使用用户指定或当前会话已确定的目标版本；需要建议时按兼容性、能力新增和修复范围说明理由。
+   目标 tag 必须未被占用；遇到已有同名版本先判断是重试还是新发版，不自动递增版本掩盖冲突。
+4. 按贡献文档维护 `release/notes.md`。正文写中文，保留版本号和必要技术标识；
+   按用户可感知的最终行为归并，不逐条翻译 commit，也不把排查过程或未验证承诺写入说明。
+   可按新增功能、问题修复、体验优化、升级说明组织，省略没有内容的章节。
+5. 替换为本次版本说明，首行与目标 tag 一致且正文非空。升级事项应能追溯到实际迁移、配置或兼容变化；
+   敏感信息脱敏，未合入功能不宣称已发布。已有准确说明仅需翻译时保持其事实和范围。
+6. 按贡献规范检查变更与现有 CI 证据，明确通过、失败、跳过和未执行。
+   涉及数据库迁移时，对照同一大版本的上一正式 Release 及本轮预发行/实验线的已发布版本检查迁移是否保持不变，并验证升级路径；
+   跨大版本按项目部署约定判断，不默认支持在线升级。区分未发布迁移的整理、已执行这些迁移的源码部署实例，
+   以及 CI 实际采用的冻结基线。未发版不代表迁移从未被执行，CI 冻结检查失败也不等于正式版数据库升级失败；
+   按各自证据报告兼容性与检查结果，不因未发版而自动放宽现有冻结规则。
+   只修改说明时无需重建前后端；实际发版仍要跟踪发布工作流针对目标提交的检查与产物。
+
+## 执行发版
+
+调用入口前重新核对当前脚本的副作用、目标版本和待推送提交，保留无关工作区内容，不自动清理或暂存用户文件。
+先编辑 `release/notes.md`，保留为未提交改动（已暂存或未暂存均可）；其他已跟踪文件的改动应先单独提交。
+脚本会更新 `release/version.yaml`，将它与最终工作区中的发布说明一起提交为 `chore(release): vX.Y.Z`。
+不要提前单独提交说明或把版本文件改成目标版本；脚本要求说明相对 HEAD 有改动，并自行更新版本号。
+本任务需要的提交按贡献文档保留英文 Conventional Commits 与相应署名。
+
+在准备完成且用户已授权发布后，将 `release_version` 设为已确定的版本，执行：
+
+```bash
+release/publish "$release_version"
+```
+
+该命令会创建包含版本号和发布说明的单次提交与 annotated tag，原子推送分支和 tag，再从长期分支手动触发 `release.yml`。
+它没有只读预演模式；不能为了检查或演练而执行。发布工作流读取 tag 中的说明，修改 tag 之后的本地文件不会改变该次构建。
+
+只调整已发布页面的标题或正文时，编辑对应 GitHub Release 的 `name` 或 `body` 并回读核对；
+保持已有 tag、源码提交、附件和预发行状态，不重新执行发布入口。
+
+## 恢复与验收
+
+- 脚本中断或网络超时时，先核对本地提交与 tag、远端分支与 tag、对应工作流 run 及 Release，确定已完成到哪一步。
+  若本地已创建版本提交或 tag，不直接重跑入口，也不通过删 tag、回退版本或强推来消除报错。
+- 提交和 tag 已推送但工作流未触发时，核对目标后使用脚本提示的 dispatch 命令补触发；
+  工作流已存在则跟踪或恢复对应 run，避免重复发布。发现 tag 指向不同提交时报告冲突，不移动已发布 tag。
+- 跟踪与本次 tag 对应的 run ID，核对工作流解析的目标提交。触发工作流成功只表示已开始，不能当作发布完成。
+- 发布完成后核对 GitHub Release 的版本、正式版/预发行状态和中文变更正文；对照平台清单与工作流确认归档、校验和及镜像产物。
+  工作流附加的安装说明和自动提交列表按其当前配置处理，不用它们替代手写的中文变更说明。
+- 返回版本、tag 对应提交、Release/工作流链接及实际结果。失败、仍在构建或缺失产物时明确说明，不能称为发布成功；
+  Release 和镜像已生成也不表示用户的运行实例已经升级。

.agents/skills/cpr-release/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "cpr-release"
+  short_description: "版本规划、中文发布说明、正式与预发行发布及失败恢复"
+  default_prompt: "使用 $cpr-release 按当前请求准备版本与中文说明、执行已授权的发版或恢复失败步骤，核对渠道与实际结果。"
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,65 @@
+# 实验版发布
+
+适用于独立于主版本维护、供用户主动选择体验的实验功能。发布入口仍是仓库的 `release/publish`，
+构建复用目标实验分支的 `.github/workflows/release.yml` 与 `release/platforms.yaml`。
+
+## 分支与版本
+
+- 从用户指定或会话已确定的 `experimental/<用途>` 分支发布，核对它的 upstream 和实验功能范围。
+  使用独立 worktree 时保留其他工作区内容；不把实验代码合入 `main`，也不顺带升级运行实例。
+- 版本采用 `vX.Y.Z-exp.N`：`X.Y.Z` 表示本轮采用的正式版基线，`N` 从 1 开始递增。
+  同一基线的 `exp.N` 只代表同一轮实验，不得用于不同实验分支；开始其他实验时使用不同的实际基线，不能仅接续编号。
+  后续只有实际同步了新的正式版基线，才调整 `X.Y.Z`；调整后属于另一实验线，发布说明需交代手动迁移方式。
+- 核对已有 tag、Release 与目标分支源码，先区分重试和新发行。已发布的旧命名版本保留，
+  不为统一名称移动 tag 或替换原有产物。
+- GitHub Release 展示标题采用 `vX.Y.Z-<用途>.M`，`<用途>` 取实验分支名去掉 `experimental/` 前缀后的部分。
+  发布前通过 `gh api` 核对相同正式版基线与用途的已有 Release 标题和旧命名 tag，新发行取已有最大编号加 1，首次从 1 开始。
+  展示编号 `M` 独立于实际 tag 的 `exp.N`，旧命名发行也计入，不能因改用 `exp.N` 而重置；同一发行重试沿用已确定编号。
+  例如已有 `v3.10.0-codex-anti-degradation.1`，下一次 tag 即使是 `v3.10.0-exp.1`，标题也应为 `v3.10.0-codex-anti-degradation.2`。
+- tag 和产物继续使用 `exp.N`：镜像版本去掉 tag 开头的 `v`，安装包沿用项目的版本、系统和架构命名。
+  发布说明首行仍匹配实际 tag；关联 Issue 和试验目的写在正文中。新标题规则不自动改名已有 Release。
+
+## 先核对发布能力
+
+在目标实验分支读取实际工作流，确认以下行为；新实验分支若缺少支持，先在既有流程中补齐并验证：
+
+- `exp.N` 产生 `experimental` 构建类型，所有平台的二进制与镜像使用同一版本和源码提交。
+  应用内更新仅允许同一轮实验，规则见[版本命名与升级规则](../../../../deploy/README.md#版本命名与升级规则)。
+  发版前核对上一实验版是否已包含该更新器；仍禁用在线更新的旧构建需要先手动升级。
+- GitHub Release 标为 Pre-release，且不设为 Latest；Docker 发布版本标签，不覆盖稳定版 `latest`。
+  正式版和 alpha、beta、rc 均不接收实验版更新；环境变量不能改变发行线。
+- 复用正式版平台清单、质量检查、完整安装包与多架构镜像，以及部署文件、校验和和现有产物证明。
+  对照本次清单确认平台，不以“实验版”为由仅发布单架构镜像。
+- 部署说明交代与稳定实例并存的目录、配置、端口和数据库要求；需要 Compose 隔离配置时，
+  核对发布附件确实包含它，不能只在文案中承诺。
+- 实验版正文使用下方完整文案，不再由工作流重复追加安装章节或自动生成混入正式版基线的提交列表。
+- Release 的 `name` 使用上述展示标题。工作流若默认以 tag 为标题，发布成功后用 `gh release edit --title` 设置标题，
+  再通过 `gh api` 回读核对；仅修改 `name`，保留 tag、产物、正文和预发行状态。
+
+## 中文发布说明
+
+在目标分支的 `release/notes.md` 编写，首行为 `# vX.Y.Z-exp.N`。后续内容按实际需要组织：
+
+1. **实验说明**：开头简述正式版基线、验证的问题与适用人群。效果尚未验证时明确说明，
+   不把假设写成已解决的问题，不承诺实验功能一定进入主版本。
+2. **本次变化**：首次发行概括相对正式版基线新增的实验能力，关联 PR；后续发行只列相对上个实验版的变化。
+   同步主分支修复时说明它对实验用户的影响，不复制整份正式版更新记录。
+3. **安装与使用**：给出本版本真实镜像命令、支持平台、部署文件及实验部署文档链接。
+   交代功能是否默认启用和必要配置；保留工作流实际提供的校验与证明说明。
+4. **使用须知**：只写本次适用的已知限制、数据隔离、迁移与回退边界，以及在线更新条件和手动迁移方式。
+5. **反馈与致谢**：链接关联 Issue 或已有反馈入口，感谢实际贡献者。没有相应内容的章节可以省略。
+
+用户要求先审核文案时，先展示完整正文；已批准的同一版本文案无需重复确认。
+正常新发行把说明纳入版本提交并从 tag 构建，不先创建公开空 Release 再回填附件。
+
+## 执行与验收
+
+按主技能准备说明和其他变更后，在实验分支执行 `release/publish <X.Y.Z-exp.N>`。
+入口创建版本提交和 tag，并从该分支 dispatch 发布工作流；不要从 `main` 发布实验代码。
+
+按主技能的「发行通道核对」确认稳定入口未改变，并检查实验线隔离与上一版本的更新能力。
+检查展示标题的分支用途与历史续号、它所对应的实际 tag，以及目标 tag 的源码提交、完整产物、校验和、多架构平台和 Pre-release 标记。
+同基线的 `X.Y.Z-exp.N` 按 SemVer 排序低于正式 `X.Y.Z`；渠道隔离仍以更新器过滤和发布标签规则为准。
+
+失败时按主技能从未完成步骤恢复，不通过换版本号或移动 tag 掩盖失败。
+仅维护已有页面文案时不重新构建；报告实际完成状态、发布链接及验证缺口。

.github/DISCUSSION_TEMPLATE/使用问答.yml

@@ -0,0 +1,33 @@
+body:
+  - type: markdown
+    attributes:
+      value: |
+        欢迎提问。提交前可以搜索已有讨论，并查看[部署文档](https://github.com/zyycn/codex-proxy-rs/blob/main/deploy/README.md)。
+        明确的程序故障请使用 [Issue 模板](https://github.com/zyycn/codex-proxy-rs/issues/new/choose)；不确定是不是 Bug，也可以先在这里交流。
+        请移除密钥、令牌、Cookie、代理认证和私人内容，不要上传完整配置或请求转储。解决后请标记帮助到你的答案。
+
+  - type: textarea
+    id: question
+    attributes:
+      label: 想解决什么问题
+      description: 说明希望完成的任务、当前遇到的困难，标题尽量具体。
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: 版本与部署方式
+      description: 涉及具体实例时，填写完整版本号或提交号，以及 Docker、二进制或源码部署方式。
+
+  - type: textarea
+    id: attempts
+    attributes:
+      label: 已尝试的方法与结果
+      description: 可以附看过的文档、相关讨论、脱敏错误片段或截图；未尝试可留空。
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: 相关环境与补充信息
+      description: 按问题需要补充操作系统、客户端、反向代理或中转链路，无需提供无关信息。

.github/DISCUSSION_TEMPLATE/实验反馈.yml

@@ -0,0 +1,44 @@
+body:
+  - type: markdown
+    attributes:
+      value: |
+        欢迎分享实验版本的使用体验，包括有效、无明显变化或遇到限制的情况。
+        请先查看对应[预发行页面](https://github.com/zyycn/codex-proxy-rs/releases)的部署与数据隔离说明，并搜索已有反馈。
+        明确的程序缺陷请使用 [Issue 模板](https://github.com/zyycn/codex-proxy-rs/issues/new/choose)，在两处互相附链接即可，无需重复粘贴。
+        请移除密钥、令牌、Cookie、代理认证和私人内容，不要上传完整配置或请求转储。
+
+  - type: input
+    id: version
+    attributes:
+      label: 实验版本或提交号
+      description: 填写实际运行的完整版本号或提交号，不要只写 exp 或 latest。
+    validations:
+      required: true
+
+  - type: textarea
+    id: scenario
+    attributes:
+      label: 使用场景与环境
+      description: 说明启用的实验功能、部署方式、客户端及与结果相关的条件，不需要提供账号身份信息。
+    validations:
+      required: true
+
+  - type: textarea
+    id: observation
+    attributes:
+      label: 观察到的效果或限制
+      description: 描述实际现象、出现频率和观察时长；请区分观察结果与原因推测。
+    validations:
+      required: true
+
+  - type: textarea
+    id: comparison
+    attributes:
+      label: 对照与复现信息
+      description: 如已对比启用前后或不同配置，请说明条件和结果；没有对照也可以反馈，无需额外测试。
+
+  - type: textarea
+    id: references
+    attributes:
+      label: 相关链接与补充材料
+      description: 可附已有 Issue、讨论、脱敏日志片段或截图。

.github/DISCUSSION_TEMPLATE/想法讨论.yml

@@ -0,0 +1,29 @@
+body:
+  - type: markdown
+    attributes:
+      value: |
+        这里适合交流尚在探索的想法、方案取舍和使用场景，不要求先给出完整实现。
+        已有明确场景与预期行为时，可以直接提交[功能建议 Issue](https://github.com/zyycn/codex-proxy-rs/issues/new?template=feature-request.yml)，无需先开讨论。
+        请先搜索相关讨论，每个主题围绕一个问题展开。
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: 使用场景与当前不便
+      description: 希望完成什么任务，目前的做法有什么不足？
+    validations:
+      required: true
+
+  - type: textarea
+    id: idea
+    attributes:
+      label: 想法与希望讨论的方向
+      description: 可以说明期望体验、考虑过的替代方法，以及还不确定的地方。
+    validations:
+      required: true
+
+  - type: textarea
+    id: references
+    attributes:
+      label: 参考资料
+      description: 可附相关 Issue、讨论或其他项目的具体行为；示例和截图请先脱敏。

.github/ISSUE_TEMPLATE/api-bug-report.yml

@@ -0,0 +1,174 @@
+name: 接口问题反馈
+description: 客户端调用模型、搜索等 API 时的报错、断流、超时或响应异常
+body:
+  - type: markdown
+    attributes:
+      value: |
+        管理端页面、账号导入或服务部署的问题请选择“常规问题反馈”；新增能力请选择“功能建议”。
+        请提供最小复现信息。请求、日志和截图发布前请移除密钥、令牌、Cookie、代理认证及私人内容。
+
+  - type: textarea
+    id: description
+    attributes:
+      label: 问题描述
+      description: 说明发生了什么、实际结果以及出现的频率；已有正常账号、模型或客户端的对照结果也可说明。
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: 服务版本
+      description: 填写实际运行的完整版本号，不要只写“最新”或 latest；源码运行填写提交号。
+      placeholder: 完整版本号或提交号
+    validations:
+      required: true
+
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: 部署方式
+      options:
+        - Docker Compose
+        - 其他容器部署
+        - 二进制运行
+        - 源码运行
+        - 其他方式（请在环境信息中说明）
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: 环境信息
+      description: 填写服务端与客户端的操作系统及版本；性能或超时问题可补充 CPU、内存和容器资源限制。
+      placeholder: |
+        服务端操作系统与版本：
+        客户端操作系统与版本：
+        相关资源限制（如有）：
+    validations:
+      required: true
+
+  - type: input
+    id: client-name
+    attributes:
+      label: 客户端名称
+      description: 区分 CLI、桌面端、编辑器扩展、SDK 或自编脚本。
+      placeholder: 例如 Codex CLI、Codex Desktop 或某个编辑器扩展
+    validations:
+      required: true
+
+  - type: input
+    id: client-version
+    attributes:
+      label: 客户端版本
+      description: 填写完整版本号；Codex CLI 可填写 codex --version 的输出。无法取得时说明原因。
+      placeholder: 完整版本号或相关 SDK 版本
+    validations:
+      required: true
+
+  - type: input
+    id: client-source
+    attributes:
+      label: 客户端安装来源与启动方式
+      description: 说明安装来源，以及是否通过包装脚本、启动器或第三方修改版运行；不确定时填写已知部分。
+      placeholder: 例如通过 npm 安装 @openai/codex，直接执行 codex
+    validations:
+      required: true
+
+  - type: input
+    id: endpoint
+    attributes:
+      label: 请求方法与端点
+      description: 填写发生异常的请求方法与路径，无需真实域名；不清楚端点时说明客户端当时执行的具体操作。
+      placeholder: 例如 POST /v1/responses、POST /v1/alpha/search 或 WebSocket /v1/responses
+    validations:
+      required: true
+
+  - type: dropdown
+    id: intermediary
+    attributes:
+      label: 是否经过中转或反向代理
+      description: |
+        指客户端到本服务之间的链路。API 中转包括 New API、One API、CCH 等；反向代理或 CDN 包括 Nginx、Caddy、Cloudflare Tunnel 等。
+        如有中转，请在下方填写链路详情；本服务到上游的出站代理请在补充信息中说明。
+      options:
+        - 否，直接连接本服务
+        - 是，仅经过 API 中转服务
+        - 是，仅经过反向代理或 CDN
+        - 是，同时经过 API 中转和反向代理或 CDN
+        - 不确定
+    validations:
+      required: true
+
+  - type: textarea
+    id: request-chain
+    attributes:
+      label: 请求链路
+      description: |
+        按调用顺序填写中间服务的名称与版本，例如：Codex → New API → Nginx → 本服务。不确定时填写已知部分。
+        如果已测试过直连本服务，请说明是否仍能复现；未测试可注明，不要求先完成对照测试。
+      placeholder: |
+        调用顺序与各中间服务版本：
+        是否启用请求参数或请求头改写（如已知）：
+        直连本服务的对照结果（如已测试）：
+
+  - type: textarea
+    id: account-model
+    attributes:
+      label: 平台、账号类型与模型
+      description: 填写与失败请求相关的信息，不要提供账号凭据；不涉及模型或无法确认的信息请注明。
+      placeholder: |
+        平台与认证类型：
+        账号套餐（如相关）：
+        请求模型与映射后的上游模型（如已知）：
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: 复现步骤
+      description: 描述触发问题的操作；无法稳定复现时，说明已知触发条件。
+      placeholder: |
+        1. 使用什么配置或输入
+        2. 执行什么操作
+        3. 出现什么结果
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: 预期行为
+      description: 说明原本期望得到的结果。
+    validations:
+      required: true
+
+  - type: textarea
+    id: request-response
+    attributes:
+      label: 请求、响应与诊断附件
+      description: |
+        提供脱敏后的最小请求、网关实际状态/响应片段和客户端显示，区分上游、中转、网关与客户端的错误来源。
+        可在此直接上传管理端默认诊断包并检查其缺失说明；原始错误与日志片段需另行审阅脱敏，粘贴时请使用 Markdown 代码块。
+        按部署文档的“请求错误排查”检查关联 ID、错误详情与 application 日志，不默认开启完整 dump；无法取得的信息请注明。
+      placeholder: |
+        发生时间与时区：
+        传输（HTTP JSON / SSE / WebSocket）：
+        脱敏后的最小请求：
+        网关关联 ID（x-gateway-request-id；配置的入口头请单独注明）：
+        上游关联 ID（x-request-id / x-oai-request-id，注明来源）：
+        网关实际状态、Content-Type 与响应片段：
+        中转服务的状态与错误（如有）：
+        客户端显示的错误：
+        诊断包或无法取得的信息：
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: 补充信息
+      description: 最近有升级时填写升级前后版本及前后端是否同步更新；网络问题补充出站代理、系统代理、TUN 和自定义证书等相关环境。
+      placeholder: |
+        服务或客户端升级前版本 → 当前版本（如有）：
+        服务前后端是否同步更新（如有升级）：
+        最近的配置变更：
+        其他相关环境：

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 使用问答
+    url: https://github.com/zyycn/codex-proxy-rs/discussions/categories/使用问答
+    about: 安装部署、配置和日常使用求助；明确的 Bug 请选择上方问题反馈模板。
+  - name: 想法与方案讨论
+    url: https://github.com/zyycn/codex-proxy-rs/discussions/categories/想法讨论
+    about: 探索尚未明确的需求与方案；具体功能需求也可以直接提交功能建议。
+  - name: 实验版体验反馈
+    url: https://github.com/zyycn/codex-proxy-rs/discussions/categories/实验反馈
+    about: 分享实验版本的使用效果、适用场景和限制。

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,39 @@
+name: 功能建议
+description: 说明使用场景、当前不便和期望行为，提出新能力或体验改进
+body:
+  - type: markdown
+    attributes:
+      value: |
+        如果已有功能无法正常使用，请选择对应的故障模板。提交前可搜索已有 Issues，相关讨论请附链接。
+        每个 Issue 尽量围绕一个使用场景；截图和示例请移除密钥、令牌、Cookie、代理认证及私人内容。
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: 使用场景与当前不便
+      description: 说明你希望完成什么任务、目前如何操作，以及现有能力有什么不足。
+      placeholder: |
+        希望完成的任务：
+        当前做法与不便：
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: 期望行为
+      description: 描述改进后希望如何使用，最好给出一个具体例子；不要求先设计技术方案。
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: 已尝试的替代方案
+      description: 如果已有配置、操作方式或其他工具能部分满足需求，说明仍缺少什么；未尝试可留空。
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: 补充信息
+      description: 可附当前使用的具体版本、相关 Issue、截图或参考链接；引用其他项目时说明希望借鉴的具体行为。

.github/ISSUE_TEMPLATE/general-bug-report.yml

@@ -0,0 +1,143 @@
+name: 常规问题反馈
+description: 管理端页面、账号导入、安装部署、升级或其他非客户端 API 问题
+body:
+  - type: markdown
+    attributes:
+      value: |
+        客户端调用模型、搜索等 API 的问题请选择“接口问题反馈”；新增能力或体验改进请选择“功能建议”。
+        请提供最小复现信息。请求、日志和截图发布前请移除密钥、令牌、Cookie、代理认证及私人内容。
+
+  - type: dropdown
+    id: issue-type
+    attributes:
+      label: 问题类型
+      options:
+        - 页面或交互异常
+        - 配置或部署异常
+        - 升级异常
+        - 其他问题
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: 问题描述
+      description: 说明发生了什么、实际结果以及出现的频率。
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: 服务版本
+      description: 填写实际运行的完整版本号，不要只写“最新”或 latest；源码运行填写提交号。服务无法启动时填写准备运行的版本。
+      placeholder: 完整版本号或提交号
+    validations:
+      required: true
+
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: 部署方式
+      options:
+        - Docker Compose
+        - 其他容器部署
+        - 二进制运行
+        - 源码运行
+        - 其他方式（请在环境信息中说明）
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: 环境信息
+      description: 填写操作系统与版本，并补充与问题相关的浏览器、访问方式或资源信息。
+      placeholder: |
+        操作系统与版本：
+        浏览器与版本（页面问题）：
+        页面访问方式（HTTP / HTTPS，localhost / IP / 域名，无需真实地址）：
+        CPU 核数与内存、容器资源限制（部署或性能问题）：
+        Docker / Compose 版本（容器部署问题）：
+    validations:
+      required: true
+
+  - type: dropdown
+    id: intermediary
+    attributes:
+      label: 是否经过中转或反向代理
+      description: |
+        指客户端或浏览器到本服务之间的链路。API 中转包括 New API、One API、CCH 等；反向代理或 CDN 包括 Nginx、Caddy、Cloudflare Tunnel 等。
+        如有中转，请在下方填写链路详情；本服务到上游的出站代理请在补充信息中说明。
+      options:
+        - 否，直接连接本服务
+        - 是，仅经过 API 中转服务
+        - 是，仅经过反向代理或 CDN
+        - 是，同时经过 API 中转和反向代理或 CDN
+        - 不确定
+        - 不适用（例如服务尚未启动）
+    validations:
+      required: true
+
+  - type: textarea
+    id: request-chain
+    attributes:
+      label: 请求链路
+      description: |
+        按调用顺序填写中间服务的名称与版本，例如：浏览器 → Cloudflare → Nginx → 本服务。不确定时填写已知部分。
+        如果已测试过直连本服务，请说明是否仍能复现；未测试可注明，不要求先完成对照测试。
+      placeholder: |
+        调用顺序与各中间服务版本：
+        是否启用请求参数或请求头改写（如已知）：
+        直连本服务的对照结果（如已测试）：
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: 复现步骤
+      description: 描述触发问题的操作；批量操作补充数量，升级问题说明升级方式。无法稳定复现时，说明已知触发条件。
+      placeholder: |
+        1. 使用什么配置或输入
+        2. 执行什么操作
+        3. 出现什么结果
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: 预期行为
+      description: 说明原本期望得到的结果。
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: 错误信息与日志
+      description: |
+        提供脱敏后的页面提示、浏览器控制台错误或相关启动、升级日志；如有失败请求，补充状态码与响应片段。
+        可以在此上传诊断包或日志附件；粘贴日志时请使用 Markdown 代码块。不要上传完整配置或请求转储。
+      placeholder: |
+        发生时间与时区：
+        页面提示或终端错误：
+        浏览器控制台 / 服务日志：
+        失败请求的状态码与响应片段（如有）：
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: 截图或录屏
+      description: 页面或交互问题可在此拖入相关截图、录屏，并说明对应的操作。
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: 补充信息
+      description: 最近有升级时填写升级前后版本及前后端是否同步更新；网络问题补充出站代理、系统代理、TUN 和自定义证书等相关环境。
+      placeholder: |
+        升级前版本 → 当前版本（如有）：
+        前后端是否同步更新（如有升级）：
+        最近的配置变更：
+        其他相关环境：

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

@@ -0,0 +1,242 @@
+name: Verify container
+description: Scan and validate a built image with the deployment Compose configuration
+inputs:
+  image:
+    description: Local image tag or immutable registry digest to validate
+    required: true
+  platform:
+    description: Native runner image platform
+    required: true
+  artifact-name:
+    description: Unique diagnostics artifact name within the workflow run
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: Define isolated runtime values
+      shell: bash
+      env:
+        IMAGE: ${{ inputs.image }}
+      run: |
+        set -euo pipefail
+        admin_password="$(openssl rand -hex 24)"
+        postgres_password="$(openssl rand -hex 24)"
+        redis_password="$(openssl rand -hex 24)"
+        echo "::add-mask::$admin_password"
+        echo "::add-mask::$postgres_password"
+        echo "::add-mask::$redis_password"
+        {
+          echo "CPR_IMAGE=$IMAGE"
+          echo "COMPOSE_PROJECT_NAME=cpr-check-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-${RUNNER_ARCH,,}"
+          echo "DIAGNOSTICS_DIR=$RUNNER_TEMP/codex-proxy-rs-diagnostics"
+          echo "CI_ADMIN_PASSWORD=$admin_password"
+          echo "CI_POSTGRES_PASSWORD=$postgres_password"
+          echo "CI_REDIS_PASSWORD=$redis_password"
+        } >> "$GITHUB_ENV"
+
+    - name: Scan container image
+      uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+      env:
+        TRIVY_PLATFORM: ${{ inputs.platform }}
+        TRIVY_QUIET: 'true'
+        TRIVY_SKIP_VERSION_CHECK: 'true'
+      with:
+        image-ref: ${{ inputs.image }}
+        version: v0.72.0
+        format: json
+        output: trivy-results.json
+        severity: HIGH,CRITICAL
+        vuln-type: os,library
+        scanners: vuln
+        ignore-unfixed: true
+        exit-code: '0'
+
+    - name: Generate Trivy SARIF
+      shell: bash
+      run: trivy convert --format sarif --output trivy-results.sarif trivy-results.json
+
+    - name: Upload Trivy SARIF
+      if: >-
+        ${{ always() && hashFiles('trivy-results.sarif') != '' &&
+            (github.event_name != 'pull_request' ||
+             github.event.pull_request.head.repo.full_name == github.repository) }}
+      uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+      with:
+        sarif_file: trivy-results.sarif
+        category: runtime-container-${{ inputs.platform }}
+
+    - name: Enforce Trivy vulnerability gate
+      shell: bash
+      run: trivy convert --format table --severity HIGH,CRITICAL --exit-code 1 trivy-results.json
+
+    - name: Prepare isolated runtime
+      shell: bash
+      run: |
+        set -euo pipefail
+        umask 0077
+        # Bind roots hand off ownership to the image-specific database users.
+        # Sticky directories keep that initialization compatible with user-namespaced runners.
+        install -d -m 1777 .runtime/postgres .runtime/redis
+        mkdir -p "$DIAGNOSTICS_DIR"
+        sudo install -d -m 0770 -o "$(id -u)" -g 10001 \
+          .runtime/data .runtime/logs
+        ruby <<'RUBY'
+        path = "deploy/config.example.yaml"
+        content = File.read(path)
+        replacements = {
+          "password: &postgres_password ''" => "password: &postgres_password '#{ENV.fetch("CI_POSTGRES_PASSWORD")}'",
+          "password: &redis_password ''" => "password: &redis_password '#{ENV.fetch("CI_REDIS_PASSWORD")}'",
+          "default_password: ''" => "default_password: '#{ENV.fetch("CI_ADMIN_PASSWORD")}'",
+        }
+        replacements.each do |placeholder, configured|
+          raise "missing config placeholder: #{placeholder}" unless content.sub!(placeholder, configured)
+        end
+        File.write("deploy/config.yaml", content)
+        RUBY
+        sudo chown "$(id -u):10001" deploy/config.yaml
+        chmod 0640 deploy/config.yaml
+
+    - name: Validate Docker Compose
+      shell: bash
+      run: |
+        set -euo pipefail
+        docker compose --project-name "$COMPOSE_PROJECT_NAME" \
+          -f deploy/compose.yaml config --quiet
+
+    - name: Configure Redis host memory overcommit
+      shell: bash
+      run: |
+        set -euo pipefail
+        sudo sysctl -w vm.overcommit_memory=1
+        test "$(sysctl -n vm.overcommit_memory)" = 1
+
+    - name: Verify PostgreSQL and Redis volume persistence
+      shell: bash
+      run: |
+        set -euo pipefail
+        compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
+          -f deploy/compose.yaml)
+        "${compose[@]}" up -d --no-build --wait postgres redis
+        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
+        "${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');"
+        "${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
+          redis-cli SET cpr:ci:persistence-probe persisted
+        "${compose[@]}" up -d --no-build --wait --force-recreate postgres redis
+        test "$("${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
+          psql -At -U codex_proxy -d codex_proxy -c \
+          "SELECT value FROM cpr_ci_persistence_probe;")" = persisted
+        test "$("${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
+          redis-cli --raw GET cpr:ci:persistence-probe | tr -d '\r')" = persisted
+        "${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
+          psql -v ON_ERROR_STOP=1 -U codex_proxy -d codex_proxy -c \
+          "DROP TABLE cpr_ci_persistence_probe;"
+        "${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
+          redis-cli DEL cpr:ci:persistence-probe
+
+    - name: Start and verify application
+      shell: bash
+      run: |
+        set -euo pipefail
+        compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
+          -f deploy/compose.yaml)
+        "${compose[@]}" up -d --no-build --wait codex-proxy-rs
+        status="$(curl --silent --show-error --output /dev/null --write-out '%{http_code}' \
+          "http://127.0.0.1:8080/healthz")"
+        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
+        "${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 clean logs and graceful shutdown
+      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
+        container_id="$("${compose[@]}" ps -a -q codex-proxy-rs)"
+        test -n "$container_id"
+        test "$(docker inspect --format '{{.State.ExitCode}}' "$container_id")" = 0
+        "${compose[@]}" logs --no-color --timestamps codex-proxy-rs \
+          > "$DIAGNOSTICS_DIR/application.log"
+        "${compose[@]}" logs --no-color --timestamps postgres \
+          > "$DIAGNOSTICS_DIR/postgres.log"
+        "${compose[@]}" logs --no-color --timestamps redis \
+          > "$DIAGNOSTICS_DIR/redis.log"
+        if grep --extended-regexp --ignore-case \
+          '"level"[[:space:]]*:[[:space:]]*"(warn|error|fatal|panic)"|(^|[^[:alnum:]_])panic([^[:alnum:]_]|$)' \
+          "$DIAGNOSTICS_DIR/application.log" \
+          || grep --extended-regexp --ignore-case \
+            '(^|[[:space:]])(warning|error|fatal|panic):' \
+            "$DIAGNOSTICS_DIR/postgres.log" \
+          || grep --extended-regexp --ignore-case \
+            '[0-9]+:[A-Z][[:space:]].*[[:space:]]#[[:space:]]|(^|[|[:space:]])(warning|error|fatal|panic)(:|[[:space:]])' \
+            "$DIAGNOSTICS_DIR/redis.log"; then
+          echo "container logs contain a warning or error severity" >&2
+          exit 1
+        fi
+
+    - name: Collect container diagnostics
+      if: always()
+      shell: bash
+      run: |
+        set +e
+        mkdir -p "$DIAGNOSTICS_DIR"
+        raw_dir="$(mktemp -d)"
+        compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
+          -f deploy/compose.yaml)
+        "${compose[@]}" config > "$raw_dir/compose-config.yaml" 2>&1
+        "${compose[@]}" ps -a > "$raw_dir/compose-ps.txt" 2>&1
+        "${compose[@]}" logs --no-color --timestamps > "$raw_dir/compose.log" 2>&1
+        mapfile -t container_ids < <("${compose[@]}" ps -a -q)
+        if [ "${#container_ids[@]}" -gt 0 ]; then
+          docker inspect "${container_ids[@]}" > "$raw_dir/docker-inspect.json" 2>&1
+        fi
+        RAW_DIR="$raw_dir" OUTPUT_DIR="$DIAGNOSTICS_DIR" ruby <<'RUBY'
+        raw_dir = ENV.fetch("RAW_DIR")
+        output_dir = ENV.fetch("OUTPUT_DIR")
+        secrets = [
+          ENV.fetch("CI_ADMIN_PASSWORD"),
+          ENV.fetch("CI_POSTGRES_PASSWORD"),
+          ENV.fetch("CI_REDIS_PASSWORD"),
+        ]
+        encoded_secrets = secrets.map do |secret|
+          secret.encode("UTF-8").bytes.map do |byte|
+            character = byte.chr
+            character.match?(/[A-Za-z0-9]/) ? character : format("%%%02X", byte)
+          end.join
+        end
+
+        Dir.children(raw_dir).each do |name|
+          content = File.binread(File.join(raw_dir, name))
+          (secrets + encoded_secrets).each do |secret|
+            content = content.gsub(secret, "<redacted>")
+          end
+          File.binwrite(File.join(output_dir, name), content)
+        end
+        RUBY
+        rm -rf "$raw_dir"
+        cp trivy-results.json trivy-results.sarif "$DIAGNOSTICS_DIR/" 2>/dev/null || true
+
+    - name: Upload container diagnostics
+      if: always()
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+      with:
+        name: ${{ inputs.artifact-name }}
+        path: ${{ runner.temp }}/codex-proxy-rs-diagnostics
+        if-no-files-found: warn
+        retention-days: 7
+
+    - name: Remove isolated runtime
+      if: always()
+      shell: bash
+      run: |
+        docker compose --project-name "$COMPOSE_PROJECT_NAME" \
+          -f deploy/compose.yaml down --remove-orphans || true
+        sudo rm -rf "$GITHUB_WORKSPACE/.runtime" "$GITHUB_WORKSPACE/deploy/config.yaml"

.github/dependabot.yml

@@ -1,8 +1,10 @@
 version: 2
 
+# 标签由维护者手动添加，各生态关闭默认打标，避免重新创建旧标签。
 updates:
   - package-ecosystem: github-actions
     directory: /
+    labels: []
     schedule:
       interval: weekly
       day: monday
@@ -16,11 +18,33 @@ updates:
 
   - package-ecosystem: cargo
     directory: /backend
+    labels: []
     schedule:
       interval: weekly
       day: monday
       time: '09:10'
       timezone: Asia/Shanghai
+    # 按官方 Codex 锁文件、协议指纹或已审计 fork 固定；完成对应核对与实测后再手动升级。
+    ignore:
+      - dependency-name: aws-lc-rs
+      - dependency-name: hyper
+      - dependency-name: hyper-rustls
+      - dependency-name: hyper-tls
+      - dependency-name: hyper-util
+      - dependency-name: native-tls
+      - dependency-name: openssl
+      - dependency-name: openssl-src
+      - dependency-name: openssl-sys
+      - dependency-name: reqwest
+      - dependency-name: rustls
+      - dependency-name: rustls-native-certs
+      - dependency-name: rustls-pki-types
+      - dependency-name: tokio
+      - dependency-name: tokio-native-tls
+      - dependency-name: tokio-rustls
+      - dependency-name: tokio-tungstenite
+      - dependency-name: tungstenite
+      - dependency-name: zstd
     groups:
       minor-and-patch:
         update-types:
@@ -28,7 +52,8 @@ updates:
           - patch
 
   - package-ecosystem: npm
-    directory: /frontend
+    directory: /
+    labels: []
     schedule:
       interval: weekly
       day: monday
@@ -44,6 +69,7 @@ updates:
 
   - package-ecosystem: docker
     directory: /deploy
+    labels: []
     schedule:
       interval: weekly
       day: monday

.github/pull_request_template.md

@@ -0,0 +1,20 @@
+## 问题与改动
+
+<!-- 说明触发场景、问题依据和最终行为；涉及上游时注明官方源码版本与位置。 -->
+
+## 自审与验证
+
+<!-- 简述实际执行的检查、结果与缺口，不把跳过写成通过。
+后端说明相关职责归属、复用与边界自审结果；页面说明沿用的设计及必要调整。
+流程见 CONTRIBUTING.md；AI 开发执行 cpr-dev-guide，准备或更新 PR 执行 cpr-github-pr。 -->
+
+## 页面截图
+
+<!-- 无页面变更时删除本节。有页面变更必须嵌入或链接审查者可访问的实际截图：
+现有页面提供前后对比，新增页面提供完成态；补充受影响状态，浮层展示展开状态。
+注明入口、状态和对应提交；预览步骤、录屏、本机路径不能替代截图。截图待补时保留 Draft。 -->
+
+## AI 使用
+
+<!-- 写明未使用 AI；使用时列出工具名称与实际模型型号，多模型分别列出，可补充参与范围。
+不能只填 Codex、ChatGPT 等工具或产品名。型号不可得时如实标为待补，不猜测，补齐前保留 Draft。 -->

.github/workflows/_container.yml

@@ -17,250 +17,61 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 45
     env:
-      COMPOSE_PROJECT_NAME: cpr-ci-${{ github.run_id }}-${{ github.run_attempt }}
       CPR_IMAGE: codex-proxy-rs:ci-${{ inputs.ref }}
       TRIVY_QUIET: 'true'
       TRIVY_SKIP_VERSION_CHECK: 'true'
     steps:
-      - name: Define isolated runtime values
-        shell: bash
-        run: |
-          set -euo pipefail
-          admin_password="$(openssl rand -hex 24)"
-          postgres_password="$(openssl rand -hex 24)"
-          redis_password="$(openssl rand -hex 24)"
-          echo "::add-mask::$admin_password"
-          echo "::add-mask::$postgres_password"
-          echo "::add-mask::$redis_password"
-          {
-            echo "DIAGNOSTICS_DIR=$RUNNER_TEMP/codex-proxy-rs-diagnostics"
-            echo "CI_ADMIN_PASSWORD=$admin_password"
-            echo "CI_POSTGRES_PASSWORD=$postgres_password"
-            echo "CI_REDIS_PASSWORD=$redis_password"
-          } >> "$GITHUB_ENV"
-
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ inputs.ref }}
 
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        id: buildx
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+
+      - name: Cache Cargo mounts
+        id: cargo-cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ runner.temp }}/container-cargo
+          key: container-cargo-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('backend/Cargo.lock', 'backend/**/Cargo.toml', 'deploy/Dockerfile') }}-${{ inputs.ref }}
+          restore-keys: |
+            container-cargo-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('backend/Cargo.lock', 'backend/**/Cargo.toml', 'deploy/Dockerfile') }}-
+            container-cargo-v1-${{ runner.os }}-${{ runner.arch }}-
+
+      # The GHA layer exporter does not persist RUN --mount=type=cache contents.
+      # Extraction runs before actions/cache saves its directories in post steps.
+      - name: Restore Cargo mounts to BuildKit
+        uses: reproducible-containers/buildkit-cache-dance@5422eac04292c961a382e0f584ea0f03ad9da723 # v3.4.0
+        with:
+          builder: ${{ steps.buildx.outputs.name }}
+          scratch-dir: ${{ runner.temp }}/container-cache-dance
+          cache-map: |
+            {
+              "${{ runner.temp }}/container-cargo/registry": "/usr/local/cargo/registry",
+              "${{ runner.temp }}/container-cargo/git": "/usr/local/cargo/git",
+              "${{ runner.temp }}/container-cargo/target": "/app/backend/target"
+            }
+          skip-extraction: ${{ steps.cargo-cache.outputs.cache-hit }}
 
       - name: Build runtime image
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
         with:
           context: .
           file: deploy/Dockerfile
           target: runtime
           load: true
           tags: ${{ env.CPR_IMAGE }}
+          no-cache-filters: |
+            runtime-base
+            runtime
           cache-from: type=gha,scope=runtime-ci
           cache-to: type=gha,mode=max,scope=runtime-ci
 
-      - name: Generate Trivy SARIF
-        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+      - name: Verify runtime image
+        uses: ./.github/actions/verify-container
         with:
-          image-ref: ${{ env.CPR_IMAGE }}
-          version: v0.72.0
-          format: sarif
-          output: trivy-results.sarif
-          severity: HIGH,CRITICAL
-          vuln-type: os,library
-          scanners: vuln
-          ignore-unfixed: true
-          exit-code: '0'
-
-      - name: Upload Trivy SARIF
-        if: >-
-          ${{ hashFiles('trivy-results.sarif') != '' &&
-              (github.event_name != 'pull_request' ||
-               github.event.pull_request.head.repo.full_name == github.repository) }}
-        uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
-        with:
-          sarif_file: trivy-results.sarif
-          category: runtime-container
-
-      - name: Enforce Trivy vulnerability gate
-        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
-        with:
-          image-ref: ${{ env.CPR_IMAGE }}
-          version: v0.72.0
-          format: table
-          severity: HIGH,CRITICAL
-          vuln-type: os,library
-          scanners: vuln
-          ignore-unfixed: true
-          exit-code: '1'
-
-      - name: Prepare isolated runtime
-        shell: bash
-        run: |
-          set -euo pipefail
-          umask 0077
-          # Bind roots hand off ownership to the image-specific database users.
-          # Sticky directories keep that initialization compatible with user-namespaced runners.
-          install -d -m 1777 .runtime/postgres .runtime/redis
-          mkdir -p "$DIAGNOSTICS_DIR"
-          sudo install -d -m 0770 -o "$(id -u)" -g 10001 \
-            .runtime/data .runtime/logs
-          ruby <<'RUBY'
-          path = "deploy/config.example.yaml"
-          content = File.read(path)
-          replacements = {
-            "password: &postgres_password ''" => "password: &postgres_password '#{ENV.fetch("CI_POSTGRES_PASSWORD")}'",
-            "password: &redis_password ''" => "password: &redis_password '#{ENV.fetch("CI_REDIS_PASSWORD")}'",
-            "default_password: ''" => "default_password: '#{ENV.fetch("CI_ADMIN_PASSWORD")}'",
-          }
-          replacements.each do |placeholder, configured|
-            raise "missing config placeholder: #{placeholder}" unless content.sub!(placeholder, configured)
-          end
-          File.write("deploy/config.yaml", content)
-          RUBY
-          sudo chown "$(id -u):10001" deploy/config.yaml
-          chmod 0640 deploy/config.yaml
-
-      - name: Validate Docker Compose
-        shell: bash
-        run: |
-          set -euo pipefail
-          docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/compose.yaml config --quiet
-
-      - name: Configure Redis host memory overcommit
-        shell: bash
-        run: |
-          set -euo pipefail
-          sudo sysctl -w vm.overcommit_memory=1
-          test "$(sysctl -n vm.overcommit_memory)" = 1
-
-      - name: Verify PostgreSQL and Redis volume persistence
-        shell: bash
-        run: |
-          set -euo pipefail
-          compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/compose.yaml)
-          "${compose[@]}" up -d --no-build --wait postgres redis
-          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
-          "${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');"
-          "${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
-            redis-cli SET cpr:ci:persistence-probe persisted
-          "${compose[@]}" up -d --no-build --wait --force-recreate postgres redis
-          test "$("${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
-            psql -At -U codex_proxy -d codex_proxy -c \
-            "SELECT value FROM cpr_ci_persistence_probe;")" = persisted
-          test "$("${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
-            redis-cli --raw GET cpr:ci:persistence-probe | tr -d '\r')" = persisted
-          "${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
-            psql -v ON_ERROR_STOP=1 -U codex_proxy -d codex_proxy -c \
-            "DROP TABLE cpr_ci_persistence_probe;"
-          "${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
-            redis-cli DEL cpr:ci:persistence-probe
-
-      - name: Start and verify application
-        shell: bash
-        run: |
-          set -euo pipefail
-          compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/compose.yaml)
-          "${compose[@]}" up -d --no-build --wait codex-proxy-rs
-          status="$(curl --silent --show-error --output /dev/null --write-out '%{http_code}' \
-            "http://127.0.0.1:8080/healthz")"
-          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
-          "${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 clean logs and graceful shutdown
-        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
-          container_id="$("${compose[@]}" ps -a -q codex-proxy-rs)"
-          test -n "$container_id"
-          test "$(docker inspect --format '{{.State.ExitCode}}' "$container_id")" = 0
-          "${compose[@]}" logs --no-color --timestamps codex-proxy-rs \
-            > "$DIAGNOSTICS_DIR/application.log"
-          "${compose[@]}" logs --no-color --timestamps postgres \
-            > "$DIAGNOSTICS_DIR/postgres.log"
-          "${compose[@]}" logs --no-color --timestamps redis \
-            > "$DIAGNOSTICS_DIR/redis.log"
-          if grep --extended-regexp --ignore-case \
-            '"level"[[:space:]]*:[[:space:]]*"(warn|error|fatal|panic)"|(^|[^[:alnum:]_])panic([^[:alnum:]_]|$)' \
-            "$DIAGNOSTICS_DIR/application.log" \
-            || grep --extended-regexp --ignore-case \
-              '(^|[[:space:]])(warning|error|fatal|panic):' \
-              "$DIAGNOSTICS_DIR/postgres.log" \
-            || grep --extended-regexp --ignore-case \
-              '[0-9]+:[A-Z][[:space:]].*[[:space:]]#[[:space:]]|(^|[|[:space:]])(warning|error|fatal|panic)(:|[[:space:]])' \
-              "$DIAGNOSTICS_DIR/redis.log"; then
-            echo "container logs contain a warning or error severity" >&2
-            exit 1
-          fi
-
-      - name: Collect container diagnostics
-        if: always()
-        shell: bash
-        run: |
-          set +e
-          mkdir -p "$DIAGNOSTICS_DIR"
-          raw_dir="$(mktemp -d)"
-          compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/compose.yaml)
-          "${compose[@]}" config > "$raw_dir/compose-config.yaml" 2>&1
-          "${compose[@]}" ps -a > "$raw_dir/compose-ps.txt" 2>&1
-          "${compose[@]}" logs --no-color --timestamps > "$raw_dir/compose.log" 2>&1
-          mapfile -t container_ids < <("${compose[@]}" ps -a -q)
-          if [ "${#container_ids[@]}" -gt 0 ]; then
-            docker inspect "${container_ids[@]}" > "$raw_dir/docker-inspect.json" 2>&1
-          fi
-          RAW_DIR="$raw_dir" OUTPUT_DIR="$DIAGNOSTICS_DIR" ruby <<'RUBY'
-          raw_dir = ENV.fetch("RAW_DIR")
-          output_dir = ENV.fetch("OUTPUT_DIR")
-          secrets = [
-            ENV.fetch("CI_ADMIN_PASSWORD"),
-            ENV.fetch("CI_POSTGRES_PASSWORD"),
-            ENV.fetch("CI_REDIS_PASSWORD"),
-          ]
-          encoded_secrets = secrets.map do |secret|
-            secret.encode("UTF-8").bytes.map do |byte|
-              character = byte.chr
-              character.match?(/[A-Za-z0-9]/) ? character : format("%%%02X", byte)
-            end.join
-          end
-
-          Dir.children(raw_dir).each do |name|
-            content = File.binread(File.join(raw_dir, name))
-            (secrets + encoded_secrets).each do |secret|
-              content = content.gsub(secret, "<redacted>")
-            end
-            File.binwrite(File.join(output_dir, name), content)
-          end
-          RUBY
-          rm -rf "$raw_dir"
-          cp trivy-results.sarif "$DIAGNOSTICS_DIR/" 2>/dev/null || true
-
-      - name: Upload container diagnostics
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: container-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}
-          path: ${{ runner.temp }}/codex-proxy-rs-diagnostics
-          if-no-files-found: warn
-          retention-days: 7
-
-      - name: Remove isolated runtime
-        if: always()
-        shell: bash
-        run: |
-          docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/compose.yaml down --remove-orphans || true
-          sudo rm -rf "$GITHUB_WORKSPACE/.runtime" "$GITHUB_WORKSPACE/deploy/config.yaml"
+          image: ${{ env.CPR_IMAGE }}
+          platform: linux/amd64
+          artifact-name: container-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}-amd64

.github/workflows/_quality.yml

@@ -12,16 +12,29 @@ on:
         required: false
         default: false
         type: boolean
+      run_backend:
+        description: Run backend quality checks
+        required: false
+        default: true
+        type: boolean
+      run_frontend:
+        description: Run frontend quality checks
+        required: false
+        default: true
+        type: boolean
 
 permissions:
   contents: read
 
 jobs:
   backend:
+    if: inputs.run_backend
     runs-on: ubuntu-latest
     timeout-minutes: 30
     env:
       CARGO_TERM_COLOR: always
+      # Rust 1.97 编译 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:
@@ -50,9 +63,44 @@ jobs:
           --health-retries 10
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ inputs.ref }}
+          # PR 场景需要 base 提交做冻结清单的 append-only 比对。
+          fetch-depth: ${{ github.event_name == 'pull_request' && 0 || 1 }}
+
+      # 已应用迁移的字节被 sqlx 启动校验钉死：改动已发布迁移会让所有
+      # 存量部署重启即失败。冻结清单保证旧文件不被改、新文件必须入册。
+      - name: Migration freeze check
+        working-directory: backend/migrations
+        shell: bash
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          set -euo pipefail
+          sha256sum --check --strict .frozen-sha256
+          for file in *.sql; do
+            if ! awk '{print $2}' .frozen-sha256 | grep -Fxq "$file"; then
+              echo "::error file=backend/migrations/$file::migration $file is not frozen; append its sha256 to backend/migrations/.frozen-sha256"
+              exit 1
+            fi
+          done
+          # 清单自证不足以防「改迁移 + 同 PR 刷新清单行」：校验对新哈希通过。
+          # 对 PR，断言 .frozen-sha256 相对 base 只增不改——base 里的每一行
+          # 必须原样保留（改哈希＝删行，删迁移＝删行，都会被挡）。
+          if [ -n "${BASE_SHA:-}" ]; then
+            base_manifest="$(git show "${BASE_SHA}:backend/migrations/.frozen-sha256" 2>/dev/null || true)"
+            if [ -n "$base_manifest" ]; then
+              while IFS= read -r line; do
+                [ -z "$line" ] && continue
+                if ! grep -Fxq "$line" .frozen-sha256; then
+                  file="$(printf '%s' "$line" | awk '{print $2}')"
+                  echo "::error file=backend/migrations/.frozen-sha256::frozen migration $file was modified or removed; released migrations are append-only — add a new numbered migration instead"
+                  exit 1
+                fi
+              done <<< "$base_manifest"
+            fi
+          fi
 
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@1a3a6d54512beeaffd394f8d516ca16f2c506a20 # 1.97
@@ -60,7 +108,7 @@ jobs:
           components: rustfmt,clippy
 
       - name: Cache Rust
-        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
         with:
           workspaces: backend -> target
 
@@ -70,30 +118,53 @@ jobs:
 
       - name: Rust clippy
         working-directory: backend
-        run: cargo clippy --all-targets --all-features --locked
+        run: cargo clippy --all-targets --all-features --locked -- -D warnings
+
+      - name: Configure PostgreSQL and Redis test authentication
+        shell: bash
+        run: |
+          set -euo pipefail
+          postgres_password="$(openssl rand -hex 24)"
+          redis_password="$(openssl rand -hex 24)"
+          echo "::add-mask::$postgres_password"
+          echo "::add-mask::$redis_password"
+          docker exec --env PGPASSWORD=codex_proxy "${{ job.services.postgres.id }}" psql \
+            --username=codex_proxy --dbname=codex_proxy \
+            --set=ON_ERROR_STOP=1 \
+            --command="ALTER USER codex_proxy WITH PASSWORD '${postgres_password}'" >/dev/null
+          docker exec --env PGPASSWORD="$postgres_password" "${{ job.services.postgres.id }}" psql \
+            --username=codex_proxy --dbname=codex_proxy \
+            --set=ON_ERROR_STOP=1 --command='SELECT 1' >/dev/null
+          docker exec "${{ job.services.redis.id }}" redis-cli CONFIG SET requirepass "$redis_password" >/dev/null
+          docker exec "${{ job.services.redis.id }}" redis-cli --no-auth-warning -a "$redis_password" ping >/dev/null
+          {
+            echo "CPR_TEST_DATABASE_URL=postgres://codex_proxy:${postgres_password}@127.0.0.1:5432/codex_proxy"
+            echo "CPR_TEST_REDIS_URL=redis://:${redis_password}@127.0.0.1:6379"
+          } >> "$GITHUB_ENV"
 
       - name: Rust tests
         working-directory: backend
         run: cargo test --test main --locked
 
   frontend:
+    if: inputs.run_frontend
     runs-on: ubuntu-latest
     timeout-minutes: 15
     env:
       CI: 'true'
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ inputs.ref }}
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
         with:
-          version: 11.7.0
+          package_json_file: frontend/package.json
 
       - name: Setup Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
           cache: pnpm
@@ -122,7 +193,7 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ inputs.ref }}
 
@@ -134,3 +205,6 @@ jobs:
           rhysd/actionlint:1.7.7@sha256:887a259a5a534f3c4f36cb02dca341673c6089431057242cdc931e9f133147e9
           -color
           .github/workflows/*.yml
+
+      - name: Check release script syntax
+        run: bash -n release/publish

.github/workflows/agents-md-guard.yml

@@ -0,0 +1,75 @@
+name: Agent Instructions Guard
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - edited
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: agents-md-guard-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  guard:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # 只查询 PR 元数据，禁止检出或执行贡献分支中的代码。
+      - name: Enforce agent instructions policy
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const pr = context.payload.pull_request;
+            const params = { owner, repo, pull_number: pr.number };
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              ...params,
+              per_page: 100,
+            });
+            const isInstructions = path => typeof path === 'string'
+              && (path === 'AGENTS.md' || path.endsWith('/AGENTS.md'));
+
+            // 同时检查重命名前后的路径，避免通过移走规则文件绕过检查。
+            if (!files.some(file => isInstructions(file.filename) || isInstructions(file.previous_filename))) {
+              core.info('No agent instruction changes detected.');
+              return;
+            }
+
+            // 旧事件不处理后续提交，也不重复处理已关闭的 PR。
+            const { data: current } = await github.rest.pulls.get(params);
+            if (current.state !== 'open' || current.head.sha !== pr.head.sha) {
+              core.info('Pull request state has changed; skipping this event.');
+              return;
+            }
+
+            const marker = '<!-- agents-md-guard -->';
+            const body = [
+              marker,
+              '此 PR 修改了 `AGENTS.md`，已按贡献规则关闭。',
+              '',
+              'PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或重命名。',
+              '请撤销相关变更后重新打开 PR；如需调整协作规则，请先提交 Issue 说明原因和建议，由维护者处理。',
+            ].join('\n');
+
+            try {
+              const comments = await github.paginate(github.rest.issues.listComments, {
+                owner, repo, issue_number: pr.number, per_page: 100,
+              });
+              const notified = comments.some(comment => comment.user?.login === 'github-actions[bot]'
+                && comment.body?.includes(marker));
+              if (!notified) {
+                await github.rest.issues.createComment({ owner, repo, issue_number: pr.number, body });
+              }
+            } catch (error) {
+              core.warning(`Unable to post policy explanation: ${error.message}`);
+            }
+
+            await github.rest.pulls.update({ ...params, state: 'closed' });
+            core.setFailed('Pull requests must not change AGENTS.md.');

.github/workflows/ci.yml

@@ -4,6 +4,9 @@ on:
   push:
     branches:
       - main
+    paths-ignore:
+      - 'release/version.yaml'
+      - 'release/notes.md'
   pull_request:
     branches:
       - main
@@ -20,35 +23,56 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     outputs:
+      backend: ${{ steps.filter.outputs.backend }}
+      frontend: ${{ steps.filter.outputs.frontend }}
       container: ${{ steps.filter.outputs.container }}
+      source: ${{ steps.filter.outputs.source }}
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
           fetch-depth: 0
 
-      - name: Detect container changes
+      - name: Detect affected checks
         id: filter
-        uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
+        uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
         with:
           filters: |
+            backend:
+              - 'backend/**'
+              - 'release/version.yaml'
+              - '.github/workflows/**'
+            frontend:
+              - 'frontend/**'
+              - '.github/workflows/**'
+            source:
+              - '.gitmodules'
+              - 'modules/ui'
+              - 'modules/plugins'
+              - 'frontend/**'
+              - 'backend/crates/gateway-plugin/sdk/**'
+              - '.github/workflows/ci.yml'
             container:
               - 'backend/**'
               - 'frontend/**'
               - 'deploy/**'
               - '.dockerignore'
               - 'release/version.yaml'
+              - '.github/actions/**'
               - '.github/workflows/_container.yml'
               - '.github/workflows/ci.yml'
 
   quality:
+    needs: changes
     uses: ./.github/workflows/_quality.yml
     with:
       ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      run_backend: ${{ needs.changes.outputs.backend == 'true' }}
+      run_frontend: ${{ needs.changes.outputs.frontend == 'true' }}
 
   container:
-    needs: [changes, quality]
+    needs: changes
     if: needs.changes.outputs.container == 'true'
     permissions:
       contents: read
@@ -56,3 +80,60 @@ jobs:
     uses: ./.github/workflows/_container.yml
     with:
       ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+  source-development:
+    needs: changes
+    if: needs.changes.outputs.source == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout with development modules
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          submodules: recursive
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+        with:
+          package_json_file: frontend/package.json
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+      - 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
+      - name: Install development dependencies
+        run: |
+          pnpm --dir modules/ui install --frozen-lockfile
+          pnpm --dir frontend install --frozen-lockfile
+          pnpm --dir modules/plugins/examples/workbench/frontend install --frozen-lockfile
+      - name: Check UI source integration
+        run: |
+          pnpm --dir frontend build:source
+          pnpm --dir modules/plugins/examples/workbench/frontend build:source
+      - name: Check local SDK integration
+        env:
+          RUST_MIN_STACK: 16777216
+          CARGO_TARGET_DIR: ${{ github.workspace }}/backend/target/plugin-development
+        run: |
+          sdk_check_dir="$RUNNER_TEMP/plugin-source"
+          mkdir -p "$sdk_check_dir/backend"
+          cp modules/plugins/examples/workbench/backend/Cargo.{toml,lock} "$sdk_check_dir/backend/"
+          cp -R modules/plugins/examples/workbench/backend/{src,tests} "$sdk_check_dir/backend/"
+          cp modules/plugins/examples/workbench/plugin.json "$sdk_check_dir/"
+          cargo test --manifest-path "$sdk_check_dir/backend/Cargo.toml" \
+            --config "patch.\"https://github.com/zyycn/codex-proxy-rs.git\".gateway-plugin-sdk.path=\"$GITHUB_WORKSPACE/backend/crates/gateway-plugin/sdk\""
+      - name: Ensure source checks preserve lockfiles
+        run: |
+          git diff --exit-code -- frontend/package.json frontend/pnpm-lock.yaml backend/Cargo.lock
+          git -C modules/plugins diff --exit-code -- examples/workbench/frontend/package.json examples/workbench/frontend/pnpm-lock.yaml examples/workbench/backend/Cargo.lock

.github/workflows/release.yml

@@ -1,9 +1,6 @@
 name: Release
 
 on:
-  push:
-    tags:
-      - 'v*'
   workflow_dispatch:
     inputs:
       tag:
@@ -15,7 +12,7 @@ permissions:
   contents: read
 
 concurrency:
-  group: release-${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
+  group: release-${{ inputs.tag }}
   cancel-in-progress: false
 
 env:
@@ -29,6 +26,7 @@ jobs:
     outputs:
       tag: ${{ steps.version.outputs.tag }}
       version: ${{ steps.version.outputs.version }}
+      docker_version: ${{ steps.version.outputs.docker_version }}
       build_time: ${{ steps.version.outputs.build_time }}
       git_sha: ${{ steps.version.outputs.git_sha }}
       platform_matrix: ${{ steps.version.outputs.platform_matrix }}
@@ -37,19 +35,20 @@ jobs:
       docker_platforms: ${{ steps.version.outputs.docker_platforms }}
       previous_tag: ${{ steps.version.outputs.previous_tag }}
       prerelease: ${{ steps.version.outputs.prerelease }}
+      build_type: ${{ steps.version.outputs.build_type }}
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
+          ref: ${{ inputs.tag }}
           fetch-depth: 0
 
       - name: Read release metadata
         id: version
         shell: bash
         env:
-          RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
+          RELEASE_TAG: ${{ inputs.tag }}
         run: |
           ruby <<'RUBY' >> "$GITHUB_OUTPUT"
           require "json"
@@ -59,7 +58,7 @@ jobs:
           require "yaml"
 
           APP_NAME = "codex-proxy-rs"
-          SEMVER = /\A(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\z/
+          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)
@@ -90,6 +89,13 @@ jobs:
           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?
 
@@ -104,7 +110,7 @@ jobs:
               require_string(platform, key, "#{platforms_path}: platforms[#{index}]")
             end
             archive = platform["archive"]
-            fail("#{platforms_path}: platforms[#{index}].archive must be tar.gz or zip") unless ["tar.gz", "zip"].include?(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
@@ -146,6 +152,8 @@ jobs:
 
           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}"
@@ -154,6 +162,7 @@ jobs:
           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
 
   quality:
@@ -165,7 +174,7 @@ jobs:
 
   build-docker-binary:
     name: build-docker-binary (${{ matrix.os }}-${{ matrix.arch }})
-    needs: [release-info, quality]
+    needs: release-info
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.release-info.outputs.docker_matrix) }}
@@ -174,7 +183,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
@@ -185,9 +194,10 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             backend/target
-          key: cargo-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock') }}
+          key: cargo-v2-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}-${{ needs.release-info.outputs.git_sha }}
           restore-keys: |
-            cargo-${{ runner.os }}-${{ matrix.target }}-
+            cargo-v2-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}
+            cargo-v2-${{ runner.os }}-${{ matrix.target }}-
 
       - name: Build binary
         shell: bash
@@ -205,7 +215,7 @@ jobs:
             -v "$HOME/.cargo:/cargo" \
             -v "$PWD/..:/workspace" \
             -w /workspace/backend \
-            rust:1.97-bookworm@sha256:7d0723df719e7f213b69dc7c8c595985c3f4b060cfbee4f7bc0e347a86fe3b6a \
+            rust:1.97-bookworm@sha256:77fac8b98f9f46062bb680b6d25d5bcaabfc400143952ebc572e924bcbedc3fa \
             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
@@ -213,7 +223,7 @@ jobs:
           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: release
+          CPR_BUILD_TYPE: ${{ needs.release-info.outputs.build_type }}
 
       - name: Upload binary artifact
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -225,7 +235,7 @@ jobs:
 
   build-binary:
     name: build-binary (${{ matrix.os }}-${{ matrix.arch }})
-    needs: [release-info, quality]
+    needs: release-info
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.release-info.outputs.non_docker_matrix) }}
@@ -234,7 +244,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
@@ -250,9 +260,10 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             backend/target
-          key: cargo-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock') }}
+          key: cargo-v2-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}-${{ needs.release-info.outputs.git_sha }}
           restore-keys: |
-            cargo-${{ runner.os }}-${{ matrix.target }}-
+            cargo-v2-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}
+            cargo-v2-${{ runner.os }}-${{ matrix.target }}-
 
       - name: Build binary
         shell: bash
@@ -265,7 +276,7 @@ jobs:
           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: release
+          CPR_BUILD_TYPE: ${{ needs.release-info.outputs.build_type }}
 
       - name: Upload binary artifact
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -286,7 +297,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
@@ -306,6 +317,8 @@ jobs:
         shell: bash
         env:
           VERSION: ${{ needs.release-info.outputs.version }}
+          DOCKER_VERSION: ${{ needs.release-info.outputs.docker_version }}
+          GIT_SHA: ${{ needs.release-info.outputs.git_sha }}
         run: |
           set -euo pipefail
           ruby <<'RUBY' > release-platforms.json
@@ -321,7 +334,6 @@ jobs:
           import pathlib
           import shutil
           import tarfile
-          import zipfile
 
           APP_NAME = "codex-proxy-rs"
 
@@ -341,7 +353,20 @@ jobs:
 
           shutil.rmtree(release_dir, ignore_errors=True)
           release_dir.mkdir(parents=True)
-          archives = []
+          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']}"
@@ -350,39 +375,61 @@ jobs:
               if not binary_src.is_file():
                   raise SystemExit(f"Missing binary artifact: {binary_src}")
 
-              shutil.rmtree(package_dir, ignore_errors=True)
-              package_root = package_dir / APP_NAME
+              package_root = package_dir / platform_name / APP_NAME
               web_dist = package_root / "web" / "dist"
               web_dist.mkdir(parents=True)
 
               binary_dest = package_root / platform["binary"]
               shutil.copy2(binary_src, binary_dest)
-              if platform["os"] != "windows":
-                  binary_dest.chmod(0o755)
+              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":
-                  with tarfile.open(archive_path, "w:gz") as archive:
-                      archive.add(package_root, arcname=APP_NAME)
-              elif platform["archive"] == "zip":
-                  with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as archive:
-                      for path in sorted(package_root.rglob("*")):
-                          if path.is_file():
-                              archive.write(path, path.relative_to(package_dir))
-              else:
+              if platform["archive"] != "tar.gz":
                   raise SystemExit(f"Unsupported archive format: {platform['archive']}")
-              archives.append(archive_path)
+              release_packages.append((platform, package_root, archive_path))
+
+          plugin_host_path = pathlib.Path("backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json")
+          plugin_host = json.loads(plugin_host_path.read_text())
+          if plugin_host.get("schema_version") != 1:
+              raise SystemExit(f"Invalid plugin host compatibility declaration: {plugin_host_path}")
+
+          plugin_manifest_path = release_dir / "plugin-release-manifest.json"
+          plugin_manifest_path.write_text(json.dumps({
+              "schema_version": 1,
+              "sealed": True,
+              "gateway_version": version,
+              "gateway_git_sha": os.environ["GIT_SHA"],
+              "plugin_host": plugin_host,
+              # 示例独立发版；当前不内置插件，仍保留更新与回滚所需的封口清单。
+              "plugins": [],
+          }, indent=2, sort_keys=True) + "\n")
+          assets.append(plugin_manifest_path)
+
+          # 保留运行时清单目录合同，宿主包不再携带教学示例。
+          for platform, package_root, archive_path in release_packages:
+              official_dir = package_root / "plugins" / "official"
+              official_dir.mkdir(parents=True)
+              bundled_manifest = official_dir / plugin_manifest_path.name
+              shutil.copy2(plugin_manifest_path, bundled_manifest)
+              bundled_manifest.chmod(0o444)
+              official_dir.chmod(0o555)
+              with tarfile.open(archive_path, "w:gz") as archive:
+                  archive.add(package_root, arcname=APP_NAME)
+              assets.append(archive_path)
 
           checksum_path = release_dir / "checksums.txt"
           with checksum_path.open("w", encoding="utf-8") as file:
-              for archive in archives:
-                  file.write(f"{sha256(archive)}  {archive.name}\n")
+              for asset in assets:
+                  file.write(f"{sha256(asset)}  {asset.name}\n")
           PY
 
       - name: Generate release asset provenance
-        uses: actions/attest@a1948c3f048ba23858d222213b7c278aabede763 # v4.1.1
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
         with:
           subject-path: dist/release/*
 
@@ -396,7 +443,7 @@ jobs:
 
   build-docker-image:
     name: build-docker-image (${{ matrix.dockerPlatform }})
-    needs: [release-info, quality, build-docker-binary]
+    needs: [release-info, quality, build-docker-binary, package-assets]
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.release-info.outputs.docker_matrix) }}
@@ -406,13 +453,14 @@ jobs:
       contents: read
       packages: write
       id-token: write
+      security-events: write
     env:
       TRIVY_QUIET: 'true'
       TRIVY_SKIP_VERSION_CHECK: 'true'
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
@@ -428,6 +476,12 @@ jobs:
           name: codex-proxy-rs-${{ matrix.os }}-${{ matrix.arch }}
           path: dist/docker-artifacts/codex-proxy-rs-${{ matrix.os }}-${{ matrix.arch }}
 
+      - name: Download sealed release assets
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-assets
+          path: dist/release-assets
+
       - name: Prepare Docker prebuilt assets
         shell: bash
         env:
@@ -437,6 +491,7 @@ jobs:
         run: |
           set -euo pipefail
           python3 - <<'PY'
+          import json
           import shutil
           import os
           import pathlib
@@ -452,13 +507,43 @@ jobs:
           binary_dest = target_dir / app_name
           shutil.copy2(binary_src, binary_dest)
           binary_dest.chmod(0o755)
+
+          release_dir = pathlib.Path("dist/release-assets")
+          manifest_path = release_dir / "plugin-release-manifest.json"
+          manifest = json.loads(manifest_path.read_text())
+          if manifest.get("schema_version") != 1 or manifest.get("sealed") is not True:
+              raise SystemExit("Invalid sealed plugin release manifest")
+          official_dir = target_dir / "plugins" / "official"
+          official_dir.mkdir(parents=True)
+          bundled_manifest = official_dir / manifest_path.name
+          shutil.copy2(manifest_path, bundled_manifest)
+          bundled_manifest.chmod(0o444)
+          selected = 0
+          for plugin in manifest.get("plugins", []):
+              artifacts = [
+                  artifact for artifact in plugin.get("artifacts", [])
+                  if artifact.get("release_os") == os.environ["MATRIX_OS"]
+                  and artifact.get("release_architecture") == os.environ["MATRIX_ARCH"]
+              ]
+              if len(artifacts) != 1:
+                  raise SystemExit(f"Official plugin platform selection is not unique: {plugin.get('id')}")
+              archive = release_dir / artifacts[0]["archive"]
+              if not archive.is_file():
+                  raise SystemExit(f"Missing official plugin archive: {archive.name}")
+              bundled_archive = official_dir / archive.name
+              shutil.copy2(archive, bundled_archive)
+              bundled_archive.chmod(0o444)
+              selected += 1
+          if selected != len(manifest.get("plugins", [])):
+              raise SystemExit("Official plugin release bundle is incomplete")
+          official_dir.chmod(0o555)
           PY
 
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
 
       - name: Login to GHCR
-        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -466,7 +551,7 @@ jobs:
 
       - name: Build and push app image
         id: build-and-push
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
         with:
           context: .
           file: deploy/Dockerfile
@@ -475,8 +560,11 @@ jobs:
           push: true
           build-args: |
             CPR_PREBUILT_DIR=dist/docker
-          cache-from: type=gha,scope=runtime-prebuilt-${{ matrix.os }}-${{ matrix.arch }}
-          cache-to: type=gha,mode=max,scope=runtime-prebuilt-${{ matrix.os }}-${{ matrix.arch }}
+          no-cache-filters: |
+            runtime-base
+            runtime-prebuilt
+          cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:buildcache-${{ matrix.os }}-${{ matrix.arch }}
+          cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:buildcache-${{ matrix.os }}-${{ matrix.arch }},mode=min
           provenance: mode=max
           sbom: true
           labels: |
@@ -486,19 +574,31 @@ jobs:
             org.opencontainers.image.source=https://github.com/zyycn/codex-proxy-rs
           tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:sha-${{ needs.release-info.outputs.git_sha }}-${{ matrix.arch }}
 
-      - name: Scan exact app image digest
-        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
-        env:
-          TRIVY_PLATFORM: ${{ matrix.dockerPlatform }}
+      - name: Verify exact app image digest
+        uses: ./.github/actions/verify-container
         with:
-          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ steps.build-and-push.outputs.digest }}
-          version: v0.72.0
-          format: table
-          severity: HIGH,CRITICAL
-          vuln-type: os,library
-          scanners: vuln
-          ignore-unfixed: true
-          exit-code: '1'
+          image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ steps.build-and-push.outputs.digest }}
+          platform: ${{ matrix.dockerPlatform }}
+          artifact-name: container-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.arch }}
+
+      - name: Record verified image digest
+        shell: bash
+        env:
+          IMAGE_DIGEST: ${{ steps.build-and-push.outputs.digest }}
+          IMAGE_ARCH: ${{ matrix.arch }}
+        run: |
+          set -euo pipefail
+          [[ "$IMAGE_DIGEST" =~ ^sha256:[a-f0-9]{64}$ ]]
+          mkdir -p dist/digests
+          printf '%s\n' "$IMAGE_DIGEST" > "dist/digests/linux-${IMAGE_ARCH}.txt"
+
+      - name: Upload verified image digest
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: image-digest-${{ matrix.os }}-${{ matrix.arch }}
+          path: dist/digests/*.txt
+          if-no-files-found: error
+          retention-days: 1
 
   publish:
     needs: [release-info, package-assets, build-docker-image]
@@ -512,7 +612,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
@@ -522,14 +622,21 @@ jobs:
           name: release-assets
           path: dist/release
 
+      - name: Download verified image digests
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: image-digest-*
+          path: dist/digests
+          merge-multiple: true
+
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
 
       - name: Install Cosign
         uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
 
       - name: Login to GHCR
-        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -539,7 +646,7 @@ jobs:
         id: manifest
         shell: bash
         env:
-          VERSION: ${{ needs.release-info.outputs.version }}
+          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 }}
@@ -553,7 +660,12 @@ jobs:
             platform="${platform//[[:space:]]/}"
             [ -n "${platform}" ] || continue
             arch="${platform##*/}"
-            sources+=("${image}:sha-${GIT_SHA}-${arch}")
+            digest="$(cat "dist/digests/linux-${arch}.txt")"
+            if [[ ! "$digest" =~ ^sha256:[a-f0-9]{64}$ ]]; then
+              echo "invalid verified image digest for ${platform}" >&2
+              exit 1
+            fi
+            sources+=("${image}@${digest}")
           done
 
           if [ "${#sources[@]}" -eq 0 ]; then
@@ -562,7 +674,7 @@ jobs:
           fi
 
           target_args=(
-            -t "${image}:${VERSION}"
+            -t "${image}:${DOCKER_VERSION}"
             -t "${image}:sha-${GIT_SHA}"
           )
           if [ "$PRERELEASE" != true ]; then
@@ -570,7 +682,7 @@ jobs:
           fi
           docker buildx imagetools create "${target_args[@]}" "${sources[@]}"
 
-          inspect_output="$(docker buildx imagetools inspect "${image}:${VERSION}")"
+          inspect_output="$(docker buildx imagetools inspect "${image}:${DOCKER_VERSION}")"
           platform_list="$(awk '$1 == "Platform:" { print $2 }' <<< "${inspect_output}")"
           for platform in "${platforms[@]}"; do
             if ! grep -Eq "^${platform}(/|$)" <<< "${platform_list}"; then
@@ -580,7 +692,7 @@ jobs:
             fi
           done
 
-          digest="$(docker buildx imagetools inspect "${image}:${VERSION}" --format '{{ .Manifest.Digest }}')"
+          digest="$(docker buildx imagetools inspect "${image}:${DOCKER_VERSION}" --format '{{ .Manifest.Digest }}')"
           if [ -z "${digest}" ]; then
             echo "missing image digest"
             exit 1
@@ -588,7 +700,7 @@ jobs:
           echo "digest=${digest}" >> "$GITHUB_OUTPUT"
 
       - name: Generate container provenance attestation
-        uses: actions/attest@a1948c3f048ba23858d222213b7c278aabede763 # v4.1.1
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
         with:
           subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           subject-digest: ${{ steps.manifest.outputs.digest }}
@@ -598,7 +710,7 @@ jobs:
         shell: bash
         env:
           DIGEST: ${{ steps.manifest.outputs.digest }}
-          VERSION: ${{ needs.release-info.outputs.version }}
+          DOCKER_VERSION: ${{ needs.release-info.outputs.docker_version }}
           GIT_SHA: ${{ needs.release-info.outputs.git_sha }}
           PRERELEASE: ${{ needs.release-info.outputs.prerelease }}
         run: |
@@ -609,7 +721,7 @@ jobs:
           fi
 
           image="${REGISTRY}/${IMAGE_NAME}"
-          tags=("${image}:${VERSION}" "${image}:sha-${GIT_SHA}")
+          tags=("${image}:${DOCKER_VERSION}" "${image}:sha-${GIT_SHA}")
           if [ "$PRERELEASE" != true ]; then
             tags+=("${image}:latest")
           fi
@@ -620,32 +732,52 @@ jobs:
 
           cosign sign --yes "${images[@]}"
 
+      - name: Prepare release notes
+        shell: bash
+        env:
+          INSTALLATION_NOTES: |
+            ## 📥 安装
+
+            **Docker 部署：**
+            ```bash
+            # 从 GitHub 容器镜像仓库拉取
+            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.release-info.outputs.docker_version }}
+            ```
+
+            请从本版本附件下载 `compose.yaml` 和 `config.example.yaml`。Compose 默认固定到本版本镜像；升级前请对比模板与已有配置。
+
+            **手动下载：**
+            请从下方附件中下载适合当前平台的归档包。
+
+            附件包含与当前宿主版本及提交绑定的 `plugin-release-manifest.json`，当前没有默认内置插件。
+            教学示例由独立的 `codex-proxy-plugins` 仓库维护和发布，不随宿主发行物分发。
+
+            发布归档提供 GitHub 构建产物证明。Docker 镜像附带软件物料清单（SBOM）、构建来源证明和 cosign 无密钥签名。
+
+            ## 📚 文档
+
+            - [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
+
+          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
-        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
+        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' }}
-          body: |
-            ## 📥 Installation
-
-            **Docker:**
-            ```bash
-            # GitHub Container Registry
-            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.release-info.outputs.version }}
-            ```
-
-            **Manual download:**
-            Download the appropriate archive for your platform from the assets below.
-
-            Release archives are covered by GitHub artifact attestations. Docker images are published with SBOM/provenance attestations and keyless cosign signatures.
-
-            ## 📚 Documentation
-
-            - [GitHub Repository](https://github.com/${{ github.repository }})
-            - [Installation Guide](https://github.com/${{ github.repository }}/blob/main/deploy/README.md)
+          body_path: ${{ runner.temp }}/release-notes.md
           fail_on_unmatched_files: true
           files: |
             dist/release/*

.github/workflows/security-scan.yml

@@ -23,7 +23,7 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
@@ -31,33 +31,33 @@ jobs:
         uses: dtolnay/rust-toolchain@1a3a6d54512beeaffd394f8d516ca16f2c506a20 # 1.97
 
       - name: Cache Rust
-        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
         with:
           workspaces: backend -> target
 
       - name: Install cargo-audit
         run: cargo install cargo-audit --version 0.22.2 --locked
 
-      - name: Run cargo audit
-        working-directory: backend
-        run: cargo audit
+      - name: Run Cargo audits
+        run: |
+          cargo audit --file backend/Cargo.lock
 
   frontend-security:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
         with:
-          version: 11.7.0
+          package_json_file: frontend/package.json
 
       - name: Setup Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
           cache: pnpm

.gitignore

@@ -1,14 +1,13 @@
 # Rust
-/backend/target/
+/backend/**/target/
 *.profraw
 *.profdata
 
 # Frontend
 /frontend/node_modules/
 /frontend/dist/
-/frontend/.vite/
-/.pnpm-store/
 /frontend/.pnpm-store/
+/frontend/.pnpm-cache/
 *.tsbuildinfo
 
 # Release artifacts
@@ -20,6 +19,9 @@
 
 # Local configuration and secrets
 /deploy/config.yaml
+.env
+.env.*
+!.env.example
 
 # Editors and operating systems
 /.idea/
@@ -33,8 +35,8 @@ Thumbs.db
 # Local tools and worktrees
 /.codegraph/
 /.codex-ws-audit/
-/.agents/
 /.reasonix/
+/.claude
 /.worktrees/
 /worktrees/
 /.cargo/

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "modules/ui"]
+	path = modules/ui
+	url = https://github.com/zyycn/codex-proxy-ui.git
+[submodule "modules/plugins"]
+	path = modules/plugins
+	url = https://github.com/zyycn/codex-proxy-plugins.git

AGENTS.md

@@ -0,0 +1,61 @@
+# 项目协作约定
+
+按用户意图和当前会话主动加载并执行仓库技能，不要求用户写出 `$技能名`：
+
+| 任务意图与常见说法 | 必用技能 |
+| --- | --- |
+| 开发、实现、修复、排查报错、审查问题或代码、修改文档 | [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 | [cpr-github-issue](.agents/skills/cpr-github-issue/SKILL.md) |
+| 写网关插件、修改插件能力、排查插件接入、打包插件 | [cpr-plugin-dev](.agents/skills/cpr-plugin-dev/SKILL.md)，同时执行 cpr-dev-guide |
+| 发版、准备版本、发布 beta／实验版、整理发布说明、打发行 tag | [cpr-release](.agents/skills/cpr-release/SKILL.md) |
+
+结合上下文识别“提交吧”“看看这个问题”等省略说法：普通 Git 提交不自动变成 PR，代码排查不自动变成 Issue；审查与发版准备不代表获准远程写入。
+任务进入新阶段时补载对应技能，不能只读取文件而跳过其中的问题核实、自审、验证与交付步骤。协作流程和审查标准见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+模块职责以 [系统架构](docs/architecture.md) 为准，界面约定以 [管理端主题](docs/theme.md) 为准；
+没有明确约定时保持与相邻实现一致，不把单次页面反馈扩展成全仓规则。
+
+<!-- CODEGRAPH_START -->
+## CodeGraph
+
+In repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:
+
+- **MCP tools** (when available): `codegraph_explore` answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them. `codegraph_node` returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search.
+- **Shell** (always works): `codegraph explore "<symbol names or question>"` and `codegraph node <symbol-or-file>` print the same output.
+
+If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is the user's decision.
+<!-- CODEGRAPH_END -->
+
+## 工作方式
+
+- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题，以官方源码为首要参考确定或评估方案。
+- 先定位变更所属模块、同类实现和上下游调用关系，再选择最小合理改动。复用已有能力，也避免为尚不存在的需求增加抽象。
+- 提交前自审最终差异，先处理本次引入的职责混淆、重复规则、冗余状态和无依据的兼容分支；后端按 [后端自审](docs/architecture.md#后端自审) 追踪状态与资源生命周期，不能把自审留给 CI 或 PR 审查者。
+- 页面变更先复用已有页面设计与组件，不因个人偏好重排页面或另建交互。文案取舍遵循 [界面文案与信息层级](docs/theme.md#界面文案与信息层级)，页面 PR 必须提供 [实际截图](CONTRIBUTING.md#界面验证)。
+- 代码注释使用中文，解释原因与边界；提交信息使用英文，沿用历史中的 Conventional Commits 格式。
+- 按变更范围执行验证，记录命令、结果和缺口。跳过的测试不算通过；界面与集成行为需要对应运行证据，构建通过不能替代实际验收。
+- 审查请求默认只读。修复、提交、推送和合并按用户当前授权执行；“本地验证通过”不等于用户已经审阅批准。
+- 不读取或输出无关凭据，不把真实密钥、代理认证、账号令牌或请求转储放入提交、截图及审查报告。
+- 使用 AI 的 PR 按 [AI 使用披露](CONTRIBUTING.md#ai-使用披露) 写明实际模型型号，不以工具名称代替模型。
+
+## Code Review Rules
+
+### 审查范围
+
+- 确认目标分支与当前变更范围，结合调用方、被调用方及已有测试审查；结论对应实际审查的提交或工作区状态。
+- 按 CONTRIBUTING.md 的维度检查设计、正确性、安全、复杂度、性能、可读性、验证、界面和文档，深度与变更风险相称。
+- 重点核对现有架构和数据合同：共享业务事实是否重复解释，异步与并发操作是否破坏状态，权限和敏感数据是否越界，协议适配是否影响兼容性。
+- 修改既有特殊分支时先查场景和历史；放宽检查、修改测试或新增例外需要业务依据，不能仅以让检查通过为理由。
+
+### 代码与界面一致性
+
+- 对重复逻辑、冗余状态和多余抽象给出具体位置及影响；建议复用时指出已有实现，不能仅凭行数或语法相似判定质量。
+- UI 变更对照原页面、项目基础组件、主题和同类页面，检查布局变化是否服务本次需求、是否堆叠重复文案，以及交互、状态、响应式与可访问性。局部问题是否应在共用组件修复，按职责判断，不一律禁止局部样式。
+- 核对页面 PR 按 [界面验证](CONTRIBUTING.md#界面验证) 提供的截图与实际交互证据；缺少必需截图时明确要求补齐，未检查的状态列为验证缺口，不推断视觉验收已经通过。
+
+### 审查输出
+
+- 用中文先回答原问题是否成立、解决方向是否合理，依据与判断标准见 [贡献与审查](CONTRIBUTING.md#审查标准)，再报告实现问题和验证缺口。
+- 实现问题聚焦本次变更新引入或加重的、可定位的问题，包含文件位置、触发场景或规范依据、影响和最小修复方向。
+- 区分必须修复的问题、可选建议和验证缺口。个人偏好标为建议，不作为必须修复项；没有问题时不要凑数。
+- 严重程度按实际影响判断，不为绕过工具的优先级过滤而升级普通规范问题。说明审查和验证的实际覆盖范围，AI 未报告问题不等于维护者批准。

CONTRIBUTING.md

@@ -0,0 +1,181 @@
+# 贡献与审查
+
+贡献应解决明确的问题，并保持或改善项目的可维护性。提交者、自动检查和审查者使用同一套标准，让重复问题在提交和初审阶段得到处理。
+
+本文定义协作流程与审查标准；模块职责以 [系统架构](docs/architecture.md) 为准，视觉规则以 [管理端主题](docs/theme.md) 为准。没有明确约定时遵循相邻实现；具体页面的布局决定不自动成为全项目限制。
+
+## 交流与反馈
+
+[讨论区](https://github.com/zyycn/codex-proxy-rs/discussions) 用于使用问答、想法讨论、实验反馈和经验分享。
+提问时按需补充版本、部署方式、已尝试的方法及脱敏信息；问题解决后，请在「使用问答」中标记有帮助的答案。
+
+明确的 Bug、具体功能需求或协作规则建议使用 Issue，无需先开讨论。
+讨论形成可执行事项后，可以新建 Issue 并互相附链接；已有 Issue 的后续信息继续补充在原帖，避免重复记录。
+围绕问题友善交流，欢迎不同使用场景和方案观点。
+
+### 提交 Issue
+
+按场景选择 [接口问题反馈](.github/ISSUE_TEMPLATE/api-bug-report.yml)、[常规问题反馈](.github/ISSUE_TEMPLATE/general-bug-report.yml) 或 [功能建议](.github/ISSUE_TEMPLATE/feature-request.yml) 表单，按对应提示提供信息。故障反馈填写实际运行版本和中转链路；接口问题区分客户端显示与网关实际响应，页面问题附相关截图或录屏。
+
+日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议说明使用场景、当前不便和期望行为；协作规则调整可直接提交普通 Issue，说明原因和建议方案。
+
+## 问题与方案依据
+
+开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题。
+
+涉及上游协议、客户端行为或兼容性时，以对应版本的官方源码为首要资料。优先读取用户提供或本机已有的官方源码，核对仓库来源、版本或提交；本地资料不足时查官方仓库的对应版本源码，再结合官方测试、文档、发布说明和运行证据。第三方资料只作线索或补充。引用具体文件、符号或行号，对外引用优先使用固定提交的源码链接；源码不可得或版本不匹配时说明证据缺口，不把最新实现当成当前部署行为。无上游依赖的内部变更，以本项目代码、合同和运行证据为依据。
+
+官方已有同一场景的处理方式时，优先沿用其协议语义、职责归属和解决路径，检查是否只需复用已有能力或正确传递官方合同。新增覆盖配置、补偿逻辑或采用第三方兼容方案，应说明官方路径为何不足；偏离官方方案需有本项目的实际约束和验证依据，不机械照搬源码，也不默认接受已有提案。
+
+反馈 Issue 时区分观察到的症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。能说明问题的反馈可以先提交，不要求报告者先找到官方源码或证明根因；引用官方行为或提出实现方案时，按上述原则注明依据与缺口。
+
+## PR 流程
+
+1. **准备变更。** 按上述依据核实问题与方案，找到所属模块、相关调用链和最接近的现有实现，在功能分支完成修改。提交前自审完整差异，清理本次引入的重复逻辑、冗余状态与职责越界；后端按 [后端自审](docs/architecture.md#后端自审) 执行。涉及架构、公开合同或较大交互变化时，先说明方案与取舍。
+2. **发起 PR。** 目标分支使用 `main`，按 [PR 模板](.github/pull_request_template.md) 说明问题依据、触发场景、最终行为、自审和实际验证结果；涉及官方行为时注明源码位置、版本和方案关系。页面变更必须按 [界面验证](#界面验证) 附实际截图，使用 AI 时按 [AI 使用披露](#ai-使用披露) 写明模型。一个 PR 围绕一个明确目标，必要重构说明关联原因。
+3. **自动检查与初审。** CI 执行适用的格式、静态分析、测试和构建检查；启用 AI 审查后，由它按本规范辅助检查语义、复用和一致性。提交者先处理明确问题，维护者重点审阅方案、风险与用户体验。
+4. **修改与合并。** 更新代码后重新执行受影响的检查，确认审查意见已处理，验证证据对应当前变更。维护者审阅批准后再合并；需要升级说明的变更同步相关文档。
+
+AI 开发和审查入口是根目录的 [AGENTS.md](AGENTS.md)。在仓库上下文中要求“审查 PR #编号”时，应按下列标准执行，无需再次列举要求。
+
+### 项目技能
+
+仓库技能位于 `.agents/skills/`，随代码共享。技能提供执行流程，协作与审查标准仍以本文和 `AGENTS.md` 为准。
+AI 开发、排查、代码审查和文档修改必须执行 `cpr-dev-guide`；准备、创建、更新及审查 PR 必须执行 `cpr-github-pr`，不以用户是否显式点名技能为条件。PR 内修复仍须经过开发流程，不能用填写 PR 正文代替实现自审与验证。
+
+| 技能 | 用途 | 调用示例 |
+| --- | --- | --- |
+| [cpr-dev-guide](.agents/skills/cpr-dev-guide/SKILL.md) | 项目开发与文档导航 | `$cpr-dev-guide 修复当前问题` |
+| [cpr-plugin-dev](.agents/skills/cpr-plugin-dev/SKILL.md) | 网关插件开发、打包与验证 | `$cpr-plugin-dev 开发一个添加响应头的插件` |
+| [cpr-github-pr](.agents/skills/cpr-github-pr/SKILL.md) | 准备、创建、更新或审查 PR | `$cpr-github-pr 创建当前分支的 PR` / `$cpr-github-pr 审查 PR #编号` |
+| [cpr-github-issue](.agents/skills/cpr-github-issue/SKILL.md) | 整理或提交 Issue | `$cpr-github-issue 提交当前问题` |
+| [cpr-release](.agents/skills/cpr-release/SKILL.md) | 准备发布说明或正式发版 | `$cpr-release 整理本次发布说明` / `$cpr-release 发布 vX.Y.Z` |
+
+审查请求默认在当前会话报告；明确要求创建 PR、提交 Issue 或正式发版时才执行对应远程操作。技能安装不等于启用 GitHub 自动审查。
+
+### AI 使用披露
+
+PR 正文说明提交者是否使用 AI。使用 AI 参与方案、代码、文档、测试或自审时，写明工具名称和实际模型型号；使用多个模型时分别列出，可简述各自参与范围。
+`Codex`、`ChatGPT`、`Claude Code` 等工具或产品名称不能代替模型型号，优先填写工具显示或调用配置中的具体模型标识。
+无法获知型号时如实标记「型号未提供，待补充」，不能猜测或伪造，也不能把待补信息称为已完成披露；补齐前保留 Draft。
+更新 PR 时同步新增的模型信息；这一披露不替代提交者自审、验证责任或已有提交署名约定。
+
+### 规则文件保护
+
+PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或重命名。调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；[规则保护工作流](.github/workflows/agents-md-guard.yml) 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查。
+
+源码变更遵守现有架构边界与迁移冻结规则，由对应 CI 检查执行；不额外设立整块业务目录的 PR 禁改清单。构建、测试和安全扫描复用现有工作流。
+
+## 审查标准
+
+按改动涉及的范围选择检查深度，无需为每个 PR 填写所有维度的报告。
+
+结论先回答原问题是否成立（成立、部分成立、不成立或证据不足），说明触发条件和依据；再判断解决方向是否合理，交代适用的官方方案、本次实现与它的关系及必要调整，最后报告实现问题与验证缺口。原问题是否成立与 PR 实现是否正确分别判断。源码推断、实际复现和检查结果分别说明，CI 通过不能代替问题与方案的论证。
+
+| 维度 | 检查重点 |
+| --- | --- |
+| 设计与架构 | 职责归属、依赖方向、公开接口是否合理；是否融入已有体系，有无绕过边界的旁路 |
+| 正确性与兼容性 | 正常、异常和边界输入；并发、取消、重试与副作用；是否改变既有 API、协议或数据合同 |
+| 安全与数据 | 权限、输入校验、敏感信息、状态隔离和持久化一致性；日志与诊断是否符合脱敏边界 |
+| 简洁性与复用 | 重复业务规则、冗余状态、无效代码和过早抽象；能否用更直接的实现解决当前问题 |
+| 性能与资源 | 实际数据规模下的查询、请求、内存与连接成本；资源释放、背压和异常时的生命周期 |
+| 可读性与风格 | 命名是否准确，控制流是否易懂，格式是否一致；注释解释约束与原因而非复述代码 |
+| 测试与验证 | 是否覆盖真实触发条件和结果，能否发现回归；证据是否对应本次变更，有无跳过或缺失项 |
+| 界面与交互 | 共用组件和主题、信息层级、状态反馈、响应式、键盘操作及可访问性；是否有实际页面证据 |
+| 文档与升级 | 行为、配置、API 和部署说明是否同步；数据迁移和兼容影响是否交代清楚 |
+
+审查意见区分三类：
+
+- **必须修复：** 有具体触发条件的缺陷、违反现有合同或明确项目规范的问题。说明位置、依据、影响和最小修复方向。
+- **建议：** 不影响合同或规范的替代实现、命名偏好和局部优化。个人偏好不能单独阻止合并，也不应强求与本次目标无关的重构。
+- **验证缺口：** 尚未检查的行为、状态或运行环境。说明缺少什么证据，由维护者评估是否需要补齐，不能把未验证当作已通过或已发现缺陷。
+
+复杂度不按行数判断，复用不只看语法相似。建议合并重复逻辑时应指出共享的业务含义；建议保留特殊分支时应能说明它服务的场景。例外应有依据，不能仅为绕过检查而放宽规则。
+
+## 项目约定
+
+- AI 进行 Rust 开发时，加载并使用 `$rust-best-practices` 技能。模块、可见性、依赖方向和测试目录按架构文档执行，使用现有 Rustfmt 与 Clippy 配置。
+- Vue 使用 TypeScript、`<script setup>` 和现有 ESLint 配置；API 请求通过已有模块及 `request` 封装，沿用逐行请求配置格式。
+- 业务数据的解析、校验和展示优先复用已有逻辑。新增抽象放在拥有该职责的模块，避免重复事实源或无实际需求的通用层。
+- 新增代码注释使用中文。提交信息使用英文 Conventional Commits，参考近期历史，按完整功能归并；确由 Codex 参与的提交保留 `Co-authored-by: Codex <noreply@openai.com>`。
+- 发布说明写入 `release/notes.md`，标题首行为目标版本的 `# vX.Y.Z`，章节标题和正文使用中文；命令、配置键、协议名等保留原文。只说明本次版本的实际变化，按影响交代升级事项。
+- PR 聚焦目标；无关格式化、重构和依赖升级单独处理。
+
+## 文档职责与更新条件
+
+常规文档说明当前有效的用法、接口合同、模块职责和维护约束，不承担变更历史。
+只有改动使对应说明失真、缺少必要信息，或改变读者需要执行的操作与判断时，才更新文档。
+内部修复、重构和界面微调不默认附带文档改动；审查时不能仅因 PR 没改文档就判定存在缺口。
+
+- 按 [开发指南的文档入口](.agents/skills/cpr-dev-guide/SKILL.md#按任务读取) 找到内容所属文档，在原有章节就地修订，
+  不按每次变更追加说明。同一事实只保留一处完整说明，其他文档按读者任务提供必要摘要和链接。
+- API 文档保留调用所需的字段、状态、语义和限制；架构文档保留职责与不变量；部署文档保留配置、操作和排障。
+  不把界面布局、内部锁或索引实现写进接口说明，也不把前端库的实现选择写进部署说明。
+- 改动原因、前后对比、排查经过和本次验证结果放在 PR / Issue 或任务报告。版本变更与升级影响按维护者的发版安排维护
+  `release/notes.md`，不为普通开发任务或 PR 自动追加发布说明。
+- 仍影响实际升级、恢复或兼容使用的限制与操作应保留，并注明适用条件；不能仅因涉及旧版就删除。
+  审查文档改动时核对必要性、所属职责与重复内容，区分当前使用说明和仅解释此次修复的内容。
+
+## 界面验证
+
+AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方案以本项目的用户任务、[管理端主题](docs/theme.md) 和已有页面为依据，优先延续原页面的布局、信息层级与交互；设计技能不构成重做页面的理由。
+
+开发前查找原页面、同类页面及 `modules/ui/src/components` 中的基础组件，明确参考实现和可复用部分，再确定最小改动。只有原设计不能满足本次操作或存在具体问题时才调整结构，并在 PR 中说明原因；不顺带换风格、重排无关区域或增加重复的模式入口。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题。
+
+列表列宽、序号、按钮、分页和弹窗尺寸由实际任务与数据规模决定，以同类页面为参照。新增或调整交互时说明用户需要完成什么操作，不把某个页面的取舍推广成全局禁令。
+
+提交者在浏览器中验证受影响路径，页面变更的 PR 必须提供实际运行截图，包括布局、文案、样式和交互状态的变化：
+
+- 修改现有页面提供变更前后截图，尽量保持相同数据、主题和窗口尺寸；新增页面提供完成态截图。截图保留必要上下文，让审查者能判断布局和信息密度，不只截取孤立控件。
+- 按影响范围补充浅色/深色、窄窗口及空/加载/错误等受影响状态；共用主题或基础组件变更按主题文档扩大验证范围。弹出层中的内容需展示展开状态，不能只截关闭后的页面。
+- 在 PR 正文嵌入或链接审查者可访问的图片，注明页面入口、状态和对应提交。录屏、预览地址和复现步骤用于补充，不能替代截图；本机绝对路径不算可供远端审阅的附件。
+- 视觉或交互继续修改后更新受影响截图，使证据对应待审实现。截图与模拟数据不得包含真实凭据，不用设计稿、生成图片或旧版截图冒充运行结果。
+- 环境不足时说明缺少的截图和交互验证，不宣称验收通过；页面 PR 在截图补齐前保留 Draft，不标为可审阅或建议合并。
+
+截图用于视觉审阅，保存、切换、错误恢复和键盘操作等行为仍需实际验证并记录覆盖范围，不能仅凭静态图片推断交互正确。
+
+涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 HTTP/HTTPS、localhost/实际部署地址与浏览器版本，记录实际覆盖的条件；本地预览正常不能替代部署环境中的交互验收。
+
+## 验证
+
+选择与变更相关的检查，纯文档修改无需重建前后端。行为修复补充能覆盖触发条件和结果的测试，不增加仅复述实现的断言。
+
+| 范围 | 现有检查 | 仍需提供的证据 |
+| --- | --- | --- |
+| Rust | Rustfmt、严格 Clippy、后端测试、架构边界检查 | 相关失败场景和集成行为 |
+| 前端 | ESLint、类型检查与构建 | 页面一致性、交互和实际数据状态 |
+| 数据库迁移 | 冻结清单校验与 PR 基线比对 | 升级行为及兼容说明 |
+| 依赖安全 | Cargo Audit、pnpm Audit | 本次变更的权限、数据与信任边界 |
+| 工作流与容器 | Actionlint、相关容器检查 | 改动涉及的运行行为 |
+
+UI 与示例源码分别在独立的 `codex-proxy-ui`、`codex-proxy-plugins` 仓库维护。前端的依赖、锁文件和 ESLint 配置均在 `frontend/` 管理，仓库根目录不维护 Node 包。UI 使用固定 GitHub 标签或提交依赖，锁文件记录实际提交、源码归档地址及完整性摘要，常规开发和 CI 不需要检出同级仓库。安装时 pnpm 按 UI 自身锁文件准备构建依赖，再执行 `prepack` 生成 JS、CSS 和类型声明。普通开发与生产构建都使用 UI 编译产物，源码联调通过 `@codex-proxy/ui/vite` 显式开启。
+
+pnpm 版本由 `frontend/package.json` 的 `packageManager` 固定，CI 和 Docker 从该字段读取。`frontend/pnpm-workspace.yaml` 的 `allowBuilds` 按仓库放行自有 UI 包的构建脚本；升级依赖时核对源码并更新锁文件，无需逐次修改构建许可，不开放全部依赖脚本。
+
+```bash
+pnpm --dir frontend install --frozen-lockfile
+```
+
+需要联合修改组件库或插件时，使用 [源码联调](docs/development.md) 中的子模块与开发入口；联调只临时替换解析路径，不改写正式依赖或锁文件。独立插件的 SDK 固定到包含所需合同的 Git 提交，不依赖浮动分支。
+
+前端从仓库根目录执行：
+
+```bash
+pnpm --dir frontend format:check
+pnpm --dir frontend build
+git diff --check
+```
+
+`build` 已包含类型检查；不维护独立前端测试代码。后端的工具链、命令与线程栈设置统一见 [修改与验收](docs/architecture.md#12-修改与验收)。
+
+依赖 PostgreSQL / Redis 的测试使用 [专用测试环境](backend/migrations/README.md#本地测试库)，未配置导致跳过时明确记录。CI 中已有对应服务和检查，见 [质量工作流](.github/workflows/_quality.yml) 与 [安全扫描](.github/workflows/security-scan.yml)。
+
+集成变更应验证实际业务路径及结果，不能只凭健康检查或探测成功认定全链路正常。协议和网络改动按需核对认证、证书、代理、流式交付及客户端结果；记录影响复现的环境条件。缺少运行条件时说明缺口，不用模拟结果代替真实集成结论。
+
+## 自动检查与合并条件
+
+[CI](.github/workflows/ci.yml) 已按变更范围调用现有质量检查。新增自动规则优先使用现有工具，要求依据明确、结果稳定、误报可控；无法可靠判定的设计与视觉问题保留审查判断，避免把具体源码写法锁成测试。
+
+AI 自动审查需要在所用工具中单独启用。其支持的检查范围和优先级过滤以工具说明为准；即使能读取 `AGENTS.md`，也不能保证所有可维护性和视觉问题都会被报告。配置参考 [Codex GitHub 审查文档](https://learn.chatgpt.com/docs/third-party/github)。
+
+要由 GitHub 强制执行合并条件，维护者需配置对应分支的必需状态检查、审阅批准和讨论解决要求，并按需要设置新提交后的重新审阅。配置前核对实际检查名称与触发范围，见 [GitHub 分支保护](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)。规则文档本身不会启用 AI 服务或更改分支设置。

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,215 +1,131 @@
+<!-- prettier-ignore -->
 <div align="center">
 
-  <img src="frontend/public/favicon.svg" alt="Codex Proxy RS" width="88" height="88" />
+<img src="frontend/public/favicon.svg" alt="Codex Proxy RS" width="80" height="80" />
 
 # Codex Proxy RS
 
-**基于 Rust 的高性能 Codex 多账号网关代理**
+面向 Codex 的自托管多账号 AI 网关
 
 [![CI](https://github.com/zyycn/codex-proxy-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/zyycn/codex-proxy-rs/actions/workflows/ci.yml)
-[![Release](https://img.shields.io/github/v/release/zyycn/codex-proxy-rs?display_name=tag&sort=semver)](https://github.com/zyycn/codex-proxy-rs/releases)
-[![Rust 1.97](https://img.shields.io/badge/Rust-1.97-000?logo=rust&logoColor=white)](https://www.rust-lang.org/)
-[![Vue 3.5](https://img.shields.io/badge/Vue-3.5-42b883?logo=vuedotjs&logoColor=white)](https://vuejs.org/)
-[![Vite 8](https://img.shields.io/badge/Vite-8-646cff?logo=vite&logoColor=white)](https://vite.dev/)
-[![GHCR](https://img.shields.io/badge/GHCR-codex--proxy--rs-2496ED?logo=docker&logoColor=white)](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
-[![MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#开源许可)
+[![Release](https://img.shields.io/github/v/release/zyycn/codex-proxy-rs?display_name=tag&sort=semver&style=flat-square)](https://github.com/zyycn/codex-proxy-rs/releases)
+[![GHCR](https://img.shields.io/badge/GHCR-codex--proxy--rs-2496ED?logo=docker&logoColor=white&style=flat-square)](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
 
-[快速开始](#快速开始) · [首次使用](#首次使用) · [客户端接入](#客户端接入) · [常见问题](#常见问题) · [部署文档](deploy/README.md)
+[快速预览](#快速预览) · [快速开始](#快速开始) · [客户端接入](#客户端接入) · [文档](#文档) · [社区](#社区) · [许可证](#许可证)
 
 </div>
 
 > [!NOTE]
-> 当前兼容 OpenAI Responses API，不提供 `/v1/chat/completions`。
+> 本项目提供 Responses API，不支持 `/v1/chat/completions`，接入前请确认客户端支持 Responses 协议
 
-## 功能
+## 快速预览
 
-- 支持 Responses HTTP、SSE 和官方 WebSocket 请求。
-- 提供智能调度、额度重置优先、轮询和粘滞四种账号策略。
-- 某个账号遇到额度、认证、模型或传输错误时，继续尝试其他账号。
-- 在网页中管理账号、客户端 Key、模型别名和运行参数。
-- 按请求、模型、账号或客户端 Key 查看 Token、费用、缓存、TTFT、延迟和错误。
-- 支持账号 OAuth、Token 导入以及 CPR、Sub2API、CLIProxyAPI JSON 导入。
-- 可直接生成 Codex CLI 配置，或通过 deeplink 导入 CCSwitch。
+无需部署，打开 [快速预览服务](https://codex-proxy-rs.ainz.cc) 即可体验管理端的系统概览、账号分组、代理管理与用量统计
+
+| 登录信息 | 默认值 |
+| --- | --- |
+| 地址 | <https://codex-proxy-rs.ainz.cc> |
+| 登录身份 | 管理员 |
+| 账号 | `admin@cpr.local` |
+| 密码 | `039c18de2aeac46d23ead7766bb07bbbe3747233c66a128e` |
+
+预览服务运行已发布版本，展示的账号、代理与使用记录均为模拟数据，每天北京时间 `00:00` 自动生成当天数据。
+这是公开共享的功能预览环境，不提供真实模型调用；请勿导入真实账号、密钥或其他敏感信息
 
 ## 快速开始
 
-Docker Compose 是最简单的启动方式。开始前请安装 Docker Engine 和 Docker Compose Plugin。
+使用 Docker Compose 部署版本固定的发布镜像，同时启动 PostgreSQL 和 Redis。
+以下命令适用于 Linux amd64/arm64，需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL。已有部署请先看
+[升级说明](deploy/README.md#镜像升级与源码构建)，不要覆盖原配置
 
-### 1. 准备配置
+### 一键安装
+
+请确保当前用户能访问 Docker，并可通过 `sudo` 或 root 设置目录权限
 
 ```bash
-git clone https://github.com/zyycn/codex-proxy-rs.git
-cd codex-proxy-rs
-
-mkdir -p .runtime/data .runtime/logs
-install -d -m 0750 .runtime/postgres .runtime/redis
-cp deploy/config.example.yaml deploy/config.yaml
-sudo chown "$(id -u):10001" deploy/config.yaml
-chmod 0640 deploy/config.yaml
+curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/install.sh -o install.sh && bash install.sh
 ```
 
-分别执行三次以下命令生成密码：
+[安装脚本](deploy/install.sh) 默认安装到当前目录下的 `codex-proxy-rs/`，下载同一正式 Release 的部署文件，
+自动生成密码、设置目录权限并启动服务。完成后会显示访问地址和管理员密码，请保存密码，再按下方步骤
+[添加账号与客户端密钥](#添加账号与客户端密钥)
+
+可在执行 `bash install.sh` 时传入环境变量：
+
+| 变量 | 用途 | 默认值 |
+| --- | --- | --- |
+| `INSTALL_DIR` | 安装目录，建议使用绝对路径 | 当前目录下的 `codex-proxy-rs/` |
+| `CPR_RELEASE_TAG` | 指定发布标签 | 最新正式版本 |
+| `ADMIN_PASSWORD` | 管理员初始密码，至少 12 位，不能包含 `$`，不能使用常见弱口令 | 随机生成 |
+
+例如，自定义安装目录：
 
 ```bash
-openssl rand -hex 24
+INSTALL_DIR="$HOME/services/codex-proxy-rs" bash install.sh
 ```
 
-把结果填入 `deploy/config.yaml` 的 `database.password`、`redis.password` 和
-`admin.default_password`。PostgreSQL 与 Redis 密码必须是 48 位十六进制字符；管理员密码
-至少 12 位且不能包含 `$`。
+重复运行时请使用同一安装目录。检测到 `deploy/config.yaml` 后，脚本保留现有配置和部署文件，
+忽略传入的管理员密码，也不执行版本升级
 
-> [!IMPORTANT]
-> 应用容器以非 root 用户 `10001:10001` 运行。Linux Bind Mount 会保留宿主机权限，因此需要允许容器用户组读取配置并写入数据和日志目录：
->
-> ```bash
-> sudo chown -R "$(id -u):10001" .runtime/data .runtime/logs
-> chmod 0770 .runtime/data .runtime/logs
-> ```
->
-> 配置文件通过 Compose `configs` 只读挂载；普通 Compose 会保留宿主机权限，因此由
-> 当前用户持有、仅向容器组开放读取权限。
-> macOS 和 Windows 的 Docker Desktop 通常也不需要调整数据目录权限。
+### 手动安装
 
-### 2. 启动服务
+自行下载部署文件、配置密码和启动服务的完整步骤见 [部署文档](deploy/README.md#手动安装)
 
-```bash
-docker compose -f deploy/compose.yaml config --quiet
-docker compose -f deploy/compose.yaml pull
-docker compose -f deploy/compose.yaml up -d --no-build
-```
+### 登录管理端
 
-启动后检查：
+部署完成后，打开 `http://127.0.0.1:8080`，使用 `admin@cpr.local` 和管理员密码登录。
+API Key 持有者可在同一登录页切换登录身份，进入 `/key-usage` 查看自己的用量、趋势、请求日志、额度与健康时间线；不能访问管理员页面。
+页面右上角的「密钥配置」支持复制 Codex 配置文件和导入 CCSwitch，导入时同时启用当前 Key 的日／周额度查询，默认刷新间隔为 30 分钟
 
-```bash
-docker compose -f deploy/compose.yaml ps
-curl -i http://127.0.0.1:8080/healthz
-```
+默认地址只能在服务器本机访问，从其他设备使用时，需要配置
+[HTTPS 反向代理](deploy/README.md#公网访问)
 
-`/healthz` 返回 `204 No Content` 即表示服务正常。管理端地址为 <http://127.0.0.1:8080>。
+### 添加账号与客户端密钥
 
-## 首次使用
-
-1. 使用 `admin@cpr.local` 和 `x-cpr.admin.default_password` 中设置的密码登录。
-2. 打开“账号”，用 OAuth、Access/Refresh Token 或 JSON 文件添加账号。
-3. 点一次连接测试，能看到模型和额度即可。
-4. 打开“API 密钥”，创建一个 `sk_...` 客户端 Key。
-5. 点击“使用密钥”复制 Codex CLI 配置，或一键导入 CCSwitch。
-
-> [!TIP]
-> `admin.default_password` 只用于首次创建管理员。已有管理员后修改该字段不会重置登录密码。
+1. 在「账号」中添加账号，完成授权或导入
+2. 按需建立账号分组，再创建客户端密钥并选择可用分组，**不选分组表示可使用全部账号**
+3. 打开密钥的「使用密钥」，复制客户端配置
 
 ## 客户端接入
 
-| 配置     | 值                                       |
-| -------- | ---------------------------------------- |
-| Base URL | `http://127.0.0.1:8080/v1`               |
-| API Key  | 管理端创建的 `sk_...` 客户端 Key         |
-| 鉴权     | `Authorization: Bearer <client-api-key>` |
+**Codex CLI / 桌面端**：在「使用密钥」中按操作系统复制配置，或通过 CCSwitch 导入。
+合并到客户端配置后重启 Codex。完整步骤、生图配置与排障见[客户端配置](deploy/README.md#客户端配置)
 
-先查询当前可用模型：
+**其他 Responses API 客户端**：填写以下信息：
+
+| 配置 | 值 |
+| --- | --- |
+| Base URL | `http://127.0.0.1:8080/v1`；远程接入使用服务器的 HTTPS 地址 |
+| API Key | 管理端创建的客户端密钥 |
+
+查询该密钥可见的模型目录：
 
 ```bash
 curl http://127.0.0.1:8080/v1/models \
   -H 'Authorization: Bearer <client-api-key>'
 ```
 
-发送一个非流式 Responses 请求：
+## 文档
 
-```bash
-curl http://127.0.0.1:8080/v1/responses \
-  -H 'Authorization: Bearer <client-api-key>' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "model": "<model-id>",
-    "input": "Reply with pong.",
-    "stream": false
-  }'
-```
+| 任务 | 文档 |
+| --- | --- |
+| 部署与使用 | [部署、备份与恢复](deploy/README.md) · [客户端接入与生图](deploy/README.md#客户端配置) |
+| 接口集成 | [API 参考](docs/api.md) · [模型定价](docs/api.md#模型定价) |
+| 使用插件 | [安装、配置与使用](docs/plugins.md) |
+| 开发插件 | [SDK 与合同](backend/crates/gateway-plugin/sdk/README.md) · [打包工具](backend/apps/plugin-cli/README.md) |
+| 开发宿主 | [贡献与验证](CONTRIBUTING.md) · [源码联调](docs/development.md) · [系统架构](docs/architecture.md) · [管理端主题](docs/theme.md) · [数据库迁移](backend/migrations/README.md) |
 
-<details>
-<summary>查看全部客户端 API 路由</summary>
+## 社区
 
-| 路由                             | 说明                            |
-| -------------------------------- | ------------------------------- |
-| `POST /v1/responses`             | Responses 非流式或 SSE 流式请求 |
-| `GET /v1/responses`              | 官方 Responses WebSocket        |
-| `POST /v1/responses/review`      | Review 请求                     |
-| `GET /v1/models`                 | OpenAI 格式的模型列表           |
-| `GET /v1/models/catalog`         | 完整模型目录                    |
-| `GET /v1/models/{model_id}`      | 模型详情                        |
-| `GET /v1/models/{model_id}/info` | 模型运行信息                    |
+欢迎到 [Discussions 讨论区](https://github.com/zyycn/codex-proxy-rs/discussions)交流：
+[使用问答](https://github.com/zyycn/codex-proxy-rs/discussions/categories/使用问答)、
+[想法讨论](https://github.com/zyycn/codex-proxy-rs/discussions/categories/想法讨论)、
+[实验反馈](https://github.com/zyycn/codex-proxy-rs/discussions/categories/实验反馈)与
+[经验分享](https://github.com/zyycn/codex-proxy-rs/discussions/categories/经验分享)
 
-所有 `/v1/*` 路由都需要客户端 API Key。
+感谢 [LINUX DO](https://linux.do) 社区提供开放、友善的技术交流平台
 
-</details>
+## 许可证
 
-## 管理端
-
-| 页面     | 内容                                                                   |
-| -------- | ---------------------------------------------------------------------- |
-| 概览     | 查看服务状态、请求趋势、Token、账号池容量、请求健康和最近调用          |
-| 账号     | 添加、导入、导出、测试、启停账号，以及刷新 Token 和额度                |
-| API 密钥 | 创建、复制、启停或删除 Key，生成 Codex CLI 配置并导入 CCSwitch         |
-| 使用统计 | 按时间、模型、账号和客户端 Key 查看用量、费用、缓存、延迟和错误        |
-| 系统设置 | 配置模型别名、调度策略、单账号并发、请求间隔、刷新参数和管理员 API Key |
-| 系统更新 | 查看版本和发布说明；Release 版本可以在线更新并重启                     |
-
-## 常用操作
-
-### 升级
-
-```bash
-docker compose -f deploy/compose.yaml pull codex-proxy-rs
-docker compose -f deploy/compose.yaml up -d --no-build
-```
-
-### 查看日志
-
-```bash
-docker compose -f deploy/compose.yaml logs -f codex-proxy-rs
-```
-
-### 从当前源码构建
-
-```bash
-docker compose -f deploy/compose.yaml build codex-proxy-rs
-docker compose -f deploy/compose.yaml up -d
-```
-
-> [!WARNING]
-> PostgreSQL、Redis、应用数据和文件日志都保存在仓库根目录 `.runtime/`。普通
-> `docker compose down` 不会删除这些绑定目录；删除 `.runtime/` 才会清除数据。升级前请备份
-> 整个目录，数据库备份中包含客户端凭据，应按敏感数据保管。
-
-## 常见问题
-
-### `/healthz` 返回 `503`
-
-检查 PostgreSQL 和 Redis 容器是否健康：
-
-```bash
-docker compose -f deploy/compose.yaml ps
-docker compose -f deploy/compose.yaml logs postgres redis
-```
-
-### 容器反复重启
-
-检查 `deploy/config.yaml` 的三个密码是否填写完整，以及 `.runtime/data`、`.runtime/logs`
-的权限是否正确。
-
-### 需要从其他设备访问
-
-Compose 默认仅绑定 `127.0.0.1`。请在服务前配置 HTTPS 反向代理，并正确转发 WebSocket 升级和真实客户端 IP 请求头。不要直接暴露 PostgreSQL 或 Redis。
-
-## 相关链接
-
-- [发布版本](https://github.com/zyycn/codex-proxy-rs/releases)
-- [容器镜像](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
-- [详细部署说明](deploy/README.md)
-- [架构说明](docs/architecture.md)
-
-Docker 镜像支持 Linux amd64/arm64。Release 压缩包另有 macOS arm64 和 Windows amd64 版本。
-
-## 开源许可
-
-Codex Proxy RS 基于 [MIT License](https://opensource.org/license/mit) 开源。
+本项目基于 [Apache License 2.0](LICENSE) 开源

backend/Cargo.toml

@@ -1,71 +1,32 @@
-[package]
-name = "codex-proxy-rs"
+[workspace]
+members = [
+    "apps/gateway",
+    "apps/plugin-cli",
+    "crates/gateway-admin",
+    "crates/gateway-api",
+    "crates/gateway-core",
+    "crates/gateway-host",
+    "crates/gateway-plugin/runtime",
+    "crates/gateway-plugin/sdk",
+    "crates/gateway-protocol",
+    "crates/gateway-store",
+    "crates/providers/openai",
+    "crates/providers/xai",
+]
+resolver = "3"
+
+[workspace.package]
+version = "0.0.0"
 edition = "2024"
-license = "MIT"
+license = "Apache-2.0"
 publish = false
 rust-version = "1.97"
 
-[dependencies]
-argon2 = "0.5.3"
-async-trait = "0.1.89"
-axum = { version = "0.8.9", default-features = false, features = ["http1", "json", "query", "tokio", "tracing"] }
-base64 = "0.22.1"
-bytes = "1.11.1"
-chrono = { version = "0.4.45", features = ["serde", "clock"] }
-config = { version = "0.15.23", default-features = false, features = ["yaml"] }
-flate2 = "1.1.9"
-futures = "0.3.32"
-hex = "0.4.3"
-hmac = "0.13.0"
-hyper = { version = "1.10.1", features = ["http1", "server"] }
-hyper-util = { version = "0.1.20", features = ["tokio"] }
-indexmap = { version = "2.0", features = ["serde"] }
-ipnet = "2.12.0"
-rand = "0.10.1"
-# Enables password_hash::rand_core::OsRng for argon2 0.5.
-rand_core = { version = "0.6.4", features = ["getrandom"] }
-redis = { version = "1.3.0", default-features = false, features = ["tokio-comp", "connection-manager", "script"] }
-# Pinned to the Codex Desktop 26.707.41301 HTTP stack; re-audit a newer Desktop before upgrading.
-reqwest = { version = "=0.12.28", default-features = false, features = ["json", "stream", "cookies", "rustls-tls-native-roots", "gzip", "brotli", "zstd", "deflate", "http2"] }
-rustls = { version = "=0.23.36", default-features = false, features = ["ring", "std", "tls12"] }
-rustls-native-certs = "0.8.4"
-rustls-pki-types = "1.14.1"
-secrecy = { version = "0.10.3", features = ["serde"] }
-semver = "1.0.27"
-serde = { version = "1.0.228", features = ["derive"] }
-serde_json = { version = "1.0.150", features = ["preserve_order"] }
-sha2 = "0.11.0"
-sqlx = { version = "0.9.0", default-features = false, features = ["runtime-tokio", "tls-rustls", "postgres", "chrono", "json"] }
-subtle = "2.6.1"
-tar = "0.4.44"
-thiserror = "2.0.18"
-tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt-multi-thread", "signal", "fs", "time", "sync", "net"] }
-tokio-util = { version = "0.7.18", features = ["rt"] }
-tokio-tungstenite = { version = "0.28.0", features = ["proxy", "rustls-tls-native-roots"] }
-tower = { version = "0.5.3", features = ["util"] }
-tower-http = { version = "0.6.11", features = ["trace", "cors", "request-id", "timeout", "fs"] }
-tracing = "0.1.44"
-tracing-appender = "0.2.5"
-tracing-subscriber = { version = "0.3.23", features = ["env-filter", "json"] }
-tungstenite = { version = "0.27.0", features = ["deflate", "proxy"] }
-url = "2.5.8"
-uuid = { version = "1.23.3", features = ["v4", "v7", "serde"] }
-
-[dev-dependencies]
-sqlx = { version = "0.9.0", default-features = false, features = ["derive"] }
-tempfile = "3.27.0"
-tokio = { version = "1.52.3", default-features = false, features = ["test-util"] }
-wiremock = "0.6.5"
-
-[patch.crates-io]
-tokio-tungstenite = { git = "https://github.com/openai-oss-forks/tokio-tungstenite", rev = "0e5b2d73aa18dd9f0a50ee9ff199d5aef7594186" }
-tungstenite = { git = "https://github.com/openai-oss-forks/tungstenite-rs", rev = "4fffad30fe373adbdcffab9545e9e9bf4f2fc19f" }
-
-[lints.rust]
+[workspace.lints.rust]
 warnings = "deny"
 unsafe_code = "forbid"
 
-[lints.clippy]
+[workspace.lints.clippy]
 all = { level = "deny", priority = 10 }
 redundant_clone = { level = "deny", priority = 9 }
 large_enum_variant = { level = "warn", priority = 8 }
@@ -80,3 +41,7 @@ strip = "symbols"
 lto = "thin"
 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" }

backend/apps/gateway/Cargo.toml

@@ -0,0 +1,35 @@
+[package]
+name = "codex-proxy-rs"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+rust-version.workspace = true
+autotests = false
+
+[[test]]
+name = "main"
+path = "tests/main.rs"
+
+[dependencies]
+gateway-admin = { path = "../../crates/gateway-admin" }
+gateway-api = { path = "../../crates/gateway-api" }
+gateway-core = { path = "../../crates/gateway-core" }
+gateway-host = { path = "../../crates/gateway-host" }
+gateway-plugin-runtime = { path = "../../crates/gateway-plugin/runtime" }
+gateway-store = { path = "../../crates/gateway-store" }
+provider-openai = { path = "../../crates/providers/openai" }
+provider-xai = { path = "../../crates/providers/xai" }
+serde = { version = "1.0.228", features = ["derive"] }
+thiserror = "2.0.18"
+tokio = { version = "1.52.3", default-features = false, features = ["rt-multi-thread"] }
+
+[dev-dependencies]
+config = { version = "0.15.23", default-features = false, features = ["yaml"] }
+serde_json = "1"
+syn = { version = "3.0.3", features = ["full", "visit"] }
+tempfile = "3.27.0"
+tokio-rustls = { version = "=0.26.4", default-features = false }
+
+[lints]
+workspace = true

backend/apps/gateway/src/bootstrap.rs

@@ -0,0 +1,414 @@
+//! 网关唯一组合根：加载包级配置并连接各 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 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 {
+                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(),
+        )
+    );
+    host.report_startup_ready("API");
+
+    let mut plan = store.take_worker_contributions();
+    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/lib.rs

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

backend/apps/gateway/src/main.rs

@@ -0,0 +1,100 @@
+use std::{
+    env,
+    error::Error,
+    io::{self, Write},
+    process::ExitCode,
+};
+
+use provider_openai::ensure_rustls_provider;
+
+fn main() -> ExitCode {
+    match run() {
+        Ok(code) => code,
+        Err(error) => {
+            eprintln!("{error}");
+            ExitCode::FAILURE
+        }
+    }
+}
+
+fn run() -> Result<ExitCode, Box<dyn Error + Send + Sync>> {
+    ensure_rustls_provider();
+    let mut arguments = env::args_os().skip(1);
+    let command = arguments
+        .next()
+        .map(|value| {
+            value
+                .into_string()
+                .map_err(|_| invalid_cli("command must be UTF-8"))
+        })
+        .transpose()?;
+    match command.as_deref() {
+        None | Some("serve") => {
+            reject_extra_arguments(arguments)?;
+            runtime()?.block_on(codex_proxy_rs::bootstrap::run())?;
+            Ok(ExitCode::SUCCESS)
+        }
+        Some("help" | "--help" | "-h") => {
+            reject_extra_arguments(arguments)?;
+            println!(
+                "Usage: codex-proxy-rs [serve]\n       codex-proxy-rs plugin <instance-id> <command> [options]\n\n  --help     Show help without loading configuration\n  --version  Show version\n  plugin --help  List enabled plugin commands without starting HTTP"
+            );
+            Ok(ExitCode::SUCCESS)
+        }
+        Some("--version" | "-V") => {
+            reject_extra_arguments(arguments)?;
+            println!(
+                "{}",
+                option_env!("CPR_VERSION").unwrap_or(env!("CARGO_PKG_VERSION"))
+            );
+            Ok(ExitCode::SUCCESS)
+        }
+        Some("plugin") => {
+            let arguments = arguments
+                .map(|value| {
+                    value
+                        .into_string()
+                        .map_err(|_| invalid_cli("plugin arguments must be UTF-8"))
+                })
+                .collect::<Result<Vec<_>, _>>()?;
+            let mut arguments = arguments.into_iter();
+            let instance_id = arguments
+                .next()
+                .filter(|value| !matches!(value.as_str(), "--help" | "-h"));
+            let name = arguments
+                .next()
+                .filter(|value| !matches!(value.as_str(), "--help" | "-h"));
+            if instance_id.is_none() && name.is_some() {
+                return Err(invalid_cli("unexpected plugin help arguments").into());
+            }
+            let output = runtime()?.block_on(codex_proxy_rs::bootstrap::plugin_command(
+                codex_proxy_rs::bootstrap::PluginCommand {
+                    instance_id,
+                    name,
+                    arguments: arguments.collect(),
+                },
+            ))?;
+            io::stdout().lock().write_all(output.stdout.as_bytes())?;
+            io::stderr().lock().write_all(output.stderr.as_bytes())?;
+            Ok(ExitCode::from(output.exit_code))
+        }
+        Some(_) => Err(invalid_cli("unknown command; expected serve, plugin, or --help").into()),
+    }
+}
+
+fn runtime() -> Result<tokio::runtime::Runtime, io::Error> {
+    tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .build()
+}
+
+fn reject_extra_arguments(mut arguments: impl Iterator) -> Result<(), io::Error> {
+    if arguments.next().is_some() {
+        return Err(invalid_cli("unexpected extra command arguments"));
+    }
+    Ok(())
+}
+
+fn invalid_cli(message: &str) -> io::Error {
+    io::Error::new(io::ErrorKind::InvalidInput, message)
+}

backend/apps/gateway/tests/architecture.rs

@@ -0,0 +1,643 @@
+//! docs/architecture.md 依赖 DAG 与生产源码纪律的 workspace 级机器校验。
+
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    fs,
+    path::{Path, PathBuf},
+};
+
+use syn::{Item, visit::Visit};
+
+/// workspace 成员冻结清单;新增 crate 必须同步扩展本文件的依赖规则。
+pub(super) const WORKSPACE_MEMBERS: &[&str] = &[
+    "apps/gateway",
+    "apps/plugin-cli",
+    "crates/gateway-admin",
+    "crates/gateway-api",
+    "crates/gateway-core",
+    "crates/gateway-host",
+    "crates/gateway-plugin/runtime",
+    "crates/gateway-plugin/sdk",
+    "crates/gateway-protocol",
+    "crates/gateway-store",
+    "crates/providers/openai",
+    "crates/providers/xai",
+];
+
+#[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();
+    assert_eq!(
+        member_count,
+        WORKSPACE_MEMBERS.len(),
+        "new workspace members must extend the dependency DAG rules"
+    );
+}
+
+#[test]
+fn gateway_core_depends_on_no_http_db_redis_or_provider_crate() {
+    assert_no_dependency(
+        "crates/gateway-core",
+        &[
+            "axum",
+            "hyper",
+            "reqwest",
+            "sqlx",
+            "redis",
+            "gateway-host",
+            "gateway-store",
+            "provider-openai",
+            "provider-xai",
+        ],
+    );
+}
+
+#[test]
+fn core_value_owners_do_not_depend_on_execution_or_routing() {
+    let root = backend_root().join("crates/gateway-core/src");
+    for relative in super::rust_files(&root) {
+        let allowed: Option<&[&str]> = match relative.to_str().expect("source path") {
+            "validation.rs" => Some(&[]),
+            "identity.rs" => Some(&["validation"]),
+            "upstream.rs" => Some(&["validation"]),
+            "event.rs" => Some(&["metering", "operation", "upstream", "validation"]),
+            "account/selection.rs" => Some(&["account", "concurrency", "identity", "validation"]),
+            "concurrency.rs" => Some(&["error"]),
+            "account/store.rs" => Some(&["account", "error", "identity", "validation"]),
+            path if path.starts_with("policy/") => Some(&["account", "policy", "validation"]),
+            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();
+        references.visit_file(&syntax);
+        for dependency in references.0 {
+            assert!(
+                allowed.contains(&dependency.as_str()),
+                "{} must not depend on crate::{dependency}",
+                relative.display()
+            );
+        }
+    }
+}
+
+#[derive(Default)]
+struct CrateReferences(BTreeSet<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());
+        }
+        syn::visit::visit_path(self, path);
+    }
+
+    fn visit_item_use(&mut self, item: &'ast syn::ItemUse) {
+        self.use_tree(&item.tree, false);
+    }
+}
+
+impl CrateReferences {
+    fn use_tree(&mut self, tree: &syn::UseTree, crate_root: bool) {
+        match tree {
+            syn::UseTree::Path(path) if crate_root => {
+                self.0.insert(path.ident.to_string());
+            }
+            syn::UseTree::Name(name) if crate_root => {
+                self.0.insert(name.ident.to_string());
+            }
+            syn::UseTree::Rename(rename) if crate_root => {
+                self.0.insert(rename.ident.to_string());
+            }
+            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);
+                }
+            }
+            syn::UseTree::Glob(_) if crate_root => {
+                self.0.insert("*".to_owned());
+            }
+            _ => {}
+        }
+    }
+}
+
+#[test]
+fn gateway_protocol_has_no_workspace_dependencies() {
+    for name in dependency_names("crates/gateway-protocol") {
+        assert!(
+            !name.starts_with("gateway-") && !name.starts_with("provider-"),
+            "gateway-protocol must not depend on workspace crate `{name}`"
+        );
+    }
+}
+
+#[test]
+fn plugin_sdk_has_no_workspace_dependencies() {
+    for name in dependency_names("crates/gateway-plugin/sdk") {
+        assert!(!name.starts_with("gateway-") && !name.starts_with("provider-"));
+    }
+}
+
+#[test]
+fn provider_crates_do_not_depend_on_each_other() {
+    assert_no_dependency("crates/providers/openai", &["provider-xai"]);
+    assert_no_dependency("crates/providers/xai", &["provider-openai"]);
+}
+
+#[test]
+fn gateway_admin_stays_free_of_infrastructure_dependencies() {
+    assert_no_dependency(
+        "crates/gateway-admin",
+        &["axum", "sqlx", "redis", "reqwest"],
+    );
+}
+
+/// workspace 包名到冻结成员路径的映射。
+const PACKAGE_TO_MEMBER: &[(&str, &str)] = &[
+    ("codex-proxy-rs", "apps/gateway"),
+    ("codex-proxy-plugin-cli", "apps/plugin-cli"),
+    ("gateway-admin", "crates/gateway-admin"),
+    ("gateway-api", "crates/gateway-api"),
+    ("gateway-core", "crates/gateway-core"),
+    ("gateway-host", "crates/gateway-host"),
+    ("gateway-plugin-runtime", "crates/gateway-plugin/runtime"),
+    ("gateway-plugin-sdk", "crates/gateway-plugin/sdk"),
+    ("gateway-protocol", "crates/gateway-protocol"),
+    ("gateway-store", "crates/gateway-store"),
+    ("provider-openai", "crates/providers/openai"),
+    ("provider-xai", "crates/providers/xai"),
+];
+
+/// SDK 与 Adapter/provider 根门面的稳定合同模块；任何增减都必须同步完成边界审计。
+const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
+    ("crates/gateway-plugin/sdk", &["call", "client"]),
+    ("crates/gateway-plugin/runtime", &[]),
+    ("crates/gateway-api", &["admin", "auth", "openai"]),
+    (
+        "crates/gateway-host",
+        &[
+            "client_distribution",
+            "config",
+            "outbound",
+            "official_plugins",
+            "pricing",
+            "plugin_distribution",
+            "process",
+            "proxy_probe",
+            "serve",
+            "system_update",
+            "workers",
+        ],
+    ),
+    ("crates/gateway-store", &["backup", "postgres", "redis"]),
+    (
+        "crates/providers/openai",
+        &["config", "credential", "transport"],
+    ),
+    ("crates/providers/xai", &["credential", "transport"]),
+];
+
+/// 不对应单一生产模块、而是校验 crate/workspace 整体契约的根级测试场景。
+const ROOT_TEST_SCENARIOS: &[(&str, &[&str])] = &[
+    ("apps/gateway", &["architecture"]),
+    ("crates/gateway-api", &["architecture"]),
+];
+
+/// 冻结的 workspace 内部运行时依赖边；新增/删除任何边都必须同步本表。
+const ALLOWED_INTERNAL_EDGES: &[(&str, &str)] = &[
+    ("codex-proxy-plugin-cli", "gateway-plugin-sdk"),
+    ("codex-proxy-rs", "gateway-admin"),
+    ("codex-proxy-rs", "gateway-api"),
+    ("codex-proxy-rs", "gateway-core"),
+    ("codex-proxy-rs", "gateway-host"),
+    ("codex-proxy-rs", "gateway-plugin-runtime"),
+    ("codex-proxy-rs", "gateway-store"),
+    ("codex-proxy-rs", "provider-openai"),
+    ("codex-proxy-rs", "provider-xai"),
+    ("gateway-admin", "gateway-core"),
+    ("gateway-api", "gateway-admin"),
+    ("gateway-api", "gateway-core"),
+    ("gateway-api", "gateway-protocol"),
+    ("gateway-host", "gateway-admin"),
+    ("gateway-host", "gateway-core"),
+    ("gateway-plugin-runtime", "gateway-host"),
+    ("gateway-plugin-runtime", "gateway-core"),
+    ("gateway-plugin-runtime", "gateway-admin"),
+    ("gateway-plugin-runtime", "gateway-plugin-sdk"),
+    ("gateway-plugin-runtime", "gateway-protocol"),
+    ("gateway-store", "gateway-admin"),
+    ("gateway-store", "gateway-core"),
+    ("provider-openai", "gateway-admin"),
+    ("provider-openai", "gateway-core"),
+    ("provider-openai", "gateway-protocol"),
+    ("provider-xai", "gateway-admin"),
+    ("provider-xai", "gateway-core"),
+    ("provider-xai", "gateway-protocol"),
+];
+
+#[test]
+fn workspace_internal_dependency_edges_match_frozen_dag() {
+    let metadata = cargo_metadata_json();
+    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()))
+        .collect();
+    expected.sort();
+
+    assert_eq!(
+        actual, expected,
+        "workspace internal dependency edges diverged from the frozen DAG"
+    );
+}
+
+#[test]
+fn runtime_dependency_edges_exclude_dev_build_and_external_dependencies() {
+    let metadata = serde_json::json!({
+        "packages": [
+            {
+                "name": "gateway-api",
+                "dependencies": [
+                    { "name": "gateway-core", "kind": null },
+                    { "name": "gateway-store", "kind": "dev" },
+                    { "name": "gateway-host", "kind": "build" },
+                    { "name": "serde", "kind": null }
+                ]
+            },
+            {
+                "name": "external-package",
+                "dependencies": [{ "name": "gateway-core", "kind": null }]
+            }
+        ]
+    });
+
+    assert_eq!(
+        workspace_runtime_dependency_edges(&metadata),
+        vec![("gateway-api".to_owned(), "gateway-core".to_owned())]
+    );
+}
+
+fn workspace_runtime_dependency_edges(metadata: &serde_json::Value) -> Vec<(String, String)> {
+    let packages = metadata["packages"]
+        .as_array()
+        .expect("cargo metadata packages");
+    let internal_names: std::collections::BTreeSet<&str> =
+        PACKAGE_TO_MEMBER.iter().map(|(name, _)| *name).collect();
+
+    let mut actual: Vec<(String, String)> = Vec::new();
+    for package in packages {
+        let name = package["name"].as_str().expect("package name");
+        if !internal_names.contains(name) {
+            continue;
+        }
+        for dependency in package["dependencies"].as_array().into_iter().flatten() {
+            let dep_name = dependency["name"].as_str().expect("dependency name");
+            if !internal_names.contains(dep_name) {
+                continue;
+            }
+            if dependency.get("kind").expect("dependency kind").is_null() {
+                actual.push((name.to_owned(), dep_name.to_owned()));
+            }
+        }
+    }
+
+    actual.sort();
+    actual
+}
+
+#[test]
+fn adapter_public_module_surfaces_match_allowlist() {
+    for (member, allowed) in ADAPTER_PUBLIC_MODULES {
+        let root = backend_root().join(member).join("src/lib.rs");
+        let source = fs::read_to_string(&root).expect("read adapter crate root");
+        let syntax = syn::parse_file(&source).expect("parse adapter crate root");
+        let actual = syntax
+            .items
+            .iter()
+            .filter_map(|item| match item {
+                Item::Mod(module) if matches!(module.vis, syn::Visibility::Public(_)) => {
+                    Some(module.ident.to_string())
+                }
+                _ => None,
+            })
+            .collect::<BTreeSet<_>>();
+        let expected = allowed
+            .iter()
+            .map(|module| (*module).to_owned())
+            .collect::<BTreeSet<_>>();
+        assert_eq!(
+            actual,
+            expected,
+            "{} public module surface diverged from its allowlist",
+            root.display()
+        );
+    }
+}
+
+#[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();
+    for member in WORKSPACE_MEMBERS {
+        let member_root = backend_root().join(member);
+        assert_module_tree(&member_root.join("src"), &["lib.rs", "main.rs"]);
+
+        let tests = member_root.join("tests");
+        if tests.is_dir() {
+            let roots = targets.get(&tests).expect("Cargo test source roots");
+            assert_module_tree(
+                &tests,
+                &roots.iter().map(String::as_str).collect::<Vec<_>>(),
+            );
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum ModuleLayout {
+    File,
+    Directory,
+}
+
+#[test]
+fn integration_tests_mirror_production_module_tree() {
+    let targets = test_source_roots();
+    for member in WORKSPACE_MEMBERS {
+        let member_root = backend_root().join(member);
+        let tests_root = member_root.join("tests");
+        if !tests_root.is_dir() {
+            continue;
+        }
+
+        let production = module_layouts(&member_root.join("src"), &["lib.rs", "main.rs"]);
+        let roots = targets.get(&tests_root).expect("Cargo test source roots");
+        let tests = module_layouts(
+            &tests_root,
+            &roots.iter().map(String::as_str).collect::<Vec<_>>(),
+        );
+        for (module, test_layout) in tests {
+            if module.starts_with("support") {
+                continue;
+            }
+
+            if let Some(production_layout) = production.get(&module) {
+                assert_eq!(
+                    test_layout,
+                    *production_layout,
+                    "{} must mirror the production module layout for {}",
+                    tests_root.join(module.with_extension("rs")).display(),
+                    member_root.join("src").join(&module).display(),
+                );
+                continue;
+            }
+
+            let has_production_owner = module
+                .parent()
+                .into_iter()
+                .flat_map(Path::ancestors)
+                .take_while(|ancestor| !ancestor.as_os_str().is_empty())
+                .any(|ancestor| production.contains_key(ancestor));
+            assert!(
+                has_production_owner || root_test_scenario_allowed(member, &module),
+                "{} has no mirrored production module owner",
+                tests_root.join(module.with_extension("rs")).display(),
+            );
+        }
+    }
+}
+
+/// Rust 子进程 fixture 是 Cargo 的独立 crate 根，不能要求它由测试模块再次声明。
+fn test_source_roots() -> BTreeMap<PathBuf, Vec<String>> {
+    let metadata = cargo_metadata_json();
+    let mut roots = BTreeMap::<PathBuf, Vec<String>>::new();
+    for package in metadata["packages"].as_array().expect("Cargo packages") {
+        let root = Path::new(package["manifest_path"].as_str().expect("package manifest"))
+            .parent()
+            .expect("package directory")
+            .join("tests");
+        for target in package["targets"].as_array().expect("Cargo targets") {
+            let source = Path::new(target["src_path"].as_str().expect("target source"));
+            if let Ok(relative) = source.strip_prefix(&root) {
+                roots
+                    .entry(root.clone())
+                    .or_default()
+                    .push(relative.to_str().expect("UTF-8 source path").to_owned());
+            }
+        }
+    }
+    roots
+}
+
+fn module_layouts(root: &Path, crate_roots: &[&str]) -> BTreeMap<PathBuf, ModuleLayout> {
+    super::rust_files(root)
+        .into_iter()
+        .filter(|relative| {
+            !crate_roots
+                .iter()
+                .any(|candidate| relative == Path::new(candidate))
+        })
+        .map(|relative| {
+            if relative.file_name().and_then(|value| value.to_str()) == Some("mod.rs") {
+                (
+                    relative.parent().expect("mod.rs parent").to_path_buf(),
+                    ModuleLayout::Directory,
+                )
+            } else {
+                (relative.with_extension(""), ModuleLayout::File)
+            }
+        })
+        .collect()
+}
+
+fn root_test_scenario_allowed(member: &str, module: &Path) -> bool {
+    let Some(module) = module.to_str() else {
+        return false;
+    };
+    ROOT_TEST_SCENARIOS
+        .iter()
+        .any(|(candidate, scenarios)| *candidate == member && scenarios.contains(&module))
+}
+
+fn assert_module_tree(root: &Path, crate_roots: &[&str]) {
+    let files = super::rust_files(root);
+    for relative in &files {
+        if crate_roots
+            .iter()
+            .any(|candidate| relative == Path::new(candidate))
+        {
+            continue;
+        }
+
+        let file_name = relative
+            .file_name()
+            .and_then(|value| value.to_str())
+            .expect("Rust source file name");
+        let parent = relative.parent().expect("Rust source parent");
+        let module_name = if file_name == "mod.rs" {
+            parent
+                .file_name()
+                .and_then(|value| value.to_str())
+                .expect("mod.rs module name")
+        } else {
+            relative
+                .file_stem()
+                .and_then(|value| value.to_str())
+                .expect("Rust source module name")
+        };
+
+        if file_name != "mod.rs" {
+            assert_ne!(
+                parent.file_name().and_then(|value| value.to_str()),
+                Some(module_name),
+                "{} repeats its parent module name",
+                root.join(relative).display()
+            );
+            let child_directory = relative.with_extension("");
+            assert!(
+                !files
+                    .iter()
+                    .any(|candidate| candidate.starts_with(&child_directory)),
+                "{} mixes a leaf module with a same-name module directory",
+                root.join(relative).display()
+            );
+        }
+
+        let declaration_parents = if parent.as_os_str().is_empty()
+            || (file_name == "mod.rs"
+                && parent
+                    .parent()
+                    .is_some_and(|ancestor| ancestor.as_os_str().is_empty()))
+        {
+            crate_roots
+                .iter()
+                .map(|candidate| root.join(candidate))
+                .collect::<Vec<_>>()
+        } else {
+            let declaration_directory = if file_name == "mod.rs" {
+                parent.parent().expect("nested mod.rs parent")
+            } else {
+                parent
+            };
+            vec![root.join(declaration_directory).join("mod.rs")]
+        };
+        let declaration_count = declaration_parents
+            .iter()
+            .map(|path| external_module_declaration_count(path, module_name))
+            .sum::<usize>();
+        assert_eq!(
+            declaration_count,
+            1,
+            "{} must be declared exactly once by its parent module",
+            root.join(relative).display()
+        );
+    }
+}
+
+fn external_module_declaration_count(path: &Path, module_name: &str) -> usize {
+    if !path.is_file() {
+        return 0;
+    }
+    let source = fs::read_to_string(path).expect("read parent module source");
+    let syntax = syn::parse_file(&source).expect("parse parent module source");
+    syntax
+        .items
+        .iter()
+        .filter(|item| {
+            matches!(
+                item,
+                Item::Mod(module)
+                    if module.content.is_none() && module.ident == module_name
+            )
+        })
+        .count()
+}
+
+pub(super) fn backend_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("../..")
+        .canonicalize()
+        .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")
+}
+
+/// 提取成员 `[dependencies]` 段内声明的依赖名;段落以下一个 `[` 表头结束。
+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
+}
+
+fn assert_no_dependency(member: &str, forbidden: &[&str]) {
+    for name in dependency_names(member) {
+        assert!(
+            !forbidden.contains(&name.as_str()),
+            "{member} must not depend on `{name}`"
+        );
+    }
+}

backend/apps/gateway/tests/bootstrap.rs

@@ -0,0 +1,582 @@
+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 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");
+}
+
+#[test]
+fn config_loader_should_resolve_paths_relative_to_config_file() {
+    let (config, _directory) = parse_config(&valid_config()).expect("resolved config");
+    let debug = format!("{config:?}");
+    assert!(debug.contains(".runtime/data"));
+    assert!(debug.contains(".runtime/logs"));
+    assert!(debug.contains("frontend/dist"));
+}
+
+#[test]
+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 路径和相对路径，避免污染并行测试。
+        for (case, web_dist) in [
+            ("binary", None),
+            ("docker", Some("/app/web/dist")),
+            ("relative", Some("../custom/dist")),
+        ] {
+            let mut child = Command::new(std::env::current_exe().expect("test executable"));
+            child
+                .args([
+                    "--exact",
+                    "bootstrap::config_loader_should_share_resolved_assets_with_system_update",
+                ])
+                .env(CHILD_ENV, case)
+                .env_remove("CPR_WEB_DIST_DIR");
+            if let Some(web_dist) = web_dist {
+                child.env("CPR_WEB_DIST_DIR", web_dist);
+            }
+            let output = child.output().expect("isolated configuration test");
+            assert!(
+                output.status.success(),
+                "{case}: {}\n{}",
+                String::from_utf8_lossy(&output.stdout),
+                String::from_utf8_lossy(&output.stderr)
+            );
+        }
+        return;
+    };
+    let mut document = valid_config_document();
+    document["api"]["asset_directory"] = serde_json::json!("../web/dist");
+    let (config, directory) = parse_config(&document.to_string()).expect("binary configuration");
+    let assets = match case.as_str() {
+        "docker" => std::path::PathBuf::from("/app/web/dist"),
+        "relative" => directory.path().join("deploy/../custom/dist"),
+        _ => directory.path().join("deploy/../web/dist"),
+    };
+    let debug = format!("{config:?}");
+    assert!(debug.contains(&format!("asset_directory: {assets:?}")));
+    assert!(debug.contains(&format!("web_dist_dir: Some({assets:?})")));
+}
+
+#[test]
+fn config_loader_should_reject_missing_runtime_data_dir() {
+    let config = valid_config().replace("  runtime_data_dir: '../.runtime/data'\n", "");
+
+    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()
+        .replace("host: '127.0.0.1'", "host: ''")
+        .replace("port: 8080", "port: 0")
+        .replace(
+            "url: 'postgres://codex_proxy@127.0.0.1:5432/codex_proxy'",
+            "url: 'invalid-postgres-url'",
+        )
+        .replace("url: 'redis://127.0.0.1:6379/'", "url: 'invalid-redis-url'")
+        .replace(POSTGRES_PASSWORD, "invalid-postgres-password")
+        .replace(REDIS_PASSWORD, "invalid-redis-password");
+    if std::env::var_os(TOPOLOGY_CHILD_ENV).is_some() {
+        parse_config(&invalid).expect("explicit package-owned environment overrides");
+        return;
+    }
+    assert!(parse_config(&invalid).is_err());
+    let status = Command::new(std::env::current_exe().expect("current test executable"))
+        .args([
+            "--exact",
+            "bootstrap::config_loader_should_apply_only_explicit_topology_overrides",
+        ])
+        .env(TOPOLOGY_CHILD_ENV, "1")
+        .env("CPR_SERVER_HOST", "127.0.0.1")
+        .env("CPR_SERVER_PORT", "8080")
+        .env(
+            "CPR_DATABASE_URL",
+            "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)
+        .status()
+        .expect("run isolated environment override test");
+    assert!(status.success());
+}
+
+#[test]
+fn bootstrap_config_debug_should_redact_all_passwords() {
+    let (config, _directory) = parse_config(&valid_config()).expect("config");
+    let debug = format!("{config:?}");
+    assert!(!debug.contains(POSTGRES_PASSWORD));
+    assert!(!debug.contains(REDIS_PASSWORD));
+    assert!(!debug.contains(ADMIN_PASSWORD));
+    assert!(debug.contains("[REDACTED]"));
+}
+
+#[test]
+fn config_loader_should_ignore_unknown_fields_in_configuration_sections() {
+    let mut document = valid_config_document();
+    document["host"]["system_update"] = serde_json::json!({});
+    document["store"]["pool"] = serde_json::json!({});
+    for path in [
+        "",
+        "/host",
+        "/host/listen",
+        "/host/logging",
+        "/host/logging/file",
+        "/host/system_update",
+        "/store",
+        "/store/database",
+        "/store/redis",
+        "/store/pool",
+        "/admin",
+        "/client",
+        "/api",
+        "/openai",
+    ] {
+        let mut extended = document.clone();
+        extended.pointer_mut(path).expect("configuration section")["unused_setting"] =
+            serde_json::json!({"nested": [true, null, "ignored"]});
+        parse_config(&extended.to_string())
+            .unwrap_or_else(|error| panic!("unknown field in {path}: {error}"));
+    }
+}
+
+#[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")] {
+        let mut document = valid_config_document();
+        document["host"]["listen"]["unused_setting"] = serde_json::json!(true);
+        document["host"]["listen"]["port"] = port;
+        assert_rejected(document.to_string());
+    }
+}
+
+#[test]
+fn config_loader_should_report_startup_configuration_diagnostics() {
+    const CHILD_ENV: &str = "CPR_TEST_CONFIG_DIAGNOSTICS_CHILD";
+    const UNUSED_SECRET: &str = "unused-value-must-not-appear-in-diagnostics";
+    if std::env::var_os(CHILD_ENV).is_some() {
+        gateway_host::load_config::<GatewayConfig>().expect("startup configuration");
+        return;
+    }
+    for case in ["normal", "unused", "missing"] {
+        let mut document = valid_config_document();
+        if case == "unused" {
+            document["openai"]["wire_profile"]["location"] = serde_json::json!(UNUSED_SECRET);
+        } else if case == "missing" {
+            document["host"]["listen"]
+                .as_object_mut()
+                .unwrap()
+                .remove("port");
+        }
+        let directory = tempfile::tempdir().unwrap();
+        fs::create_dir(directory.path().join("deploy")).unwrap();
+        fs::write(
+            directory.path().join("deploy/config.yaml"),
+            document.to_string(),
+        )
+        .unwrap();
+        let output = Command::new(std::env::current_exe().unwrap())
+            .args([
+                "--exact",
+                "bootstrap::config_loader_should_report_startup_configuration_diagnostics",
+                "--nocapture",
+            ])
+            .env(CHILD_ENV, "1")
+            .current_dir(directory.path())
+            .output()
+            .unwrap();
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        assert_eq!(
+            output.status.success(),
+            case != "missing",
+            "{case}: {stderr}"
+        );
+        match case {
+            "unused" => assert!(
+                stderr.contains("openai.wire_profile") && stderr.contains("已忽略"),
+                "{stderr}"
+            ),
+            "missing" => assert!(stderr.contains("host.listen.port"), "{stderr}"),
+            _ => assert!(!stderr.contains("警告"), "{stderr}"),
+        }
+        assert!(!stderr.contains(UNUSED_SECRET), "{stderr}");
+        assert!(!stderr.contains("services"), "{stderr}");
+    }
+}
+
+#[test]
+fn config_loader_should_reject_missing_explicit_fields() {
+    assert_rejected(valid_config().replace("  request_id_header: 'x-request-id'\n", ""));
+}
+
+#[test]
+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"));
+}
+
+#[test]
+fn config_loader_should_reject_unsupported_schema_version() {
+    assert_rejected(valid_config().replace("schema_version: 1", "schema_version: 2"));
+}
+
+#[test]
+fn config_loader_should_reject_embedded_database_password() {
+    assert_rejected(valid_config().replace(
+        "postgres://codex_proxy@127.0.0.1:5432/codex_proxy",
+        "postgres://codex_proxy:embedded@127.0.0.1:5432/codex_proxy",
+    ));
+}
+
+#[test]
+fn config_loader_should_reject_non_hex_postgres_password() {
+    assert_rejected(valid_config().replace(POSTGRES_PASSWORD, &"g".repeat(48)));
+}
+
+#[test]
+fn config_loader_should_reject_wrong_length_redis_password() {
+    assert_rejected(valid_config().replace(REDIS_PASSWORD, "1234"));
+}
+
+#[test]
+fn config_loader_should_reject_weak_admin_password() {
+    assert_rejected(valid_config().replace(ADMIN_PASSWORD, "password"));
+}
+
+#[test]
+fn config_loader_should_reject_admin_password_with_compose_interpolation() {
+    assert_rejected(valid_config().replace(ADMIN_PASSWORD, "unsafe$password"));
+}
+
+#[test]
+fn config_loader_should_reject_zero_client_session_ttl() {
+    let mut config = valid_config_document();
+    *config
+        .pointer_mut("/client/session_ttl_minutes")
+        .expect("example client session TTL") = serde_json::json!(0);
+    assert_rejected(config.to_string());
+}
+
+#[test]
+fn config_loader_should_default_missing_client_section() {
+    let mut config = valid_config_document();
+    config
+        .as_object_mut()
+        .expect("example config mapping")
+        .remove("client")
+        .expect("example client section");
+    parse_config(&config.to_string()).expect("client defaults when the section is omitted");
+}
+
+#[test]
+fn config_loader_should_reject_missing_client_session_ttl() {
+    let mut config = valid_config_document();
+    config["client"]
+        .as_object_mut()
+        .expect("example client mapping")
+        .remove("session_ttl_minutes")
+        .expect("example client session TTL");
+    assert_rejected(config.to_string());
+}
+
+#[test]
+fn config_loader_should_reject_disabled_all_log_outputs() {
+    assert_rejected(
+        valid_config()
+            .replace("stdout: true", "stdout: false")
+            .replace("enabled: true", "enabled: false"),
+    );
+}
+
+#[test]
+fn config_loader_should_reject_zero_server_port() {
+    assert_rejected(valid_config().replace("port: 8080", "port: 0"));
+}
+
+#[test]
+fn config_loader_should_validate_openai_residency() {
+    let mut document = valid_config_document();
+    document["openai"]["residency"] = serde_json::json!("invalid");
+    assert_rejected(document.to_string());
+}
+
+fn assert_rejected(config: String) {
+    assert!(parse_config(&config).is_err());
+}
+
+fn valid_config() -> String {
+    CONFIG_EXAMPLE
+        .replacen(
+            "password: &postgres_password ''",
+            &format!("password: &postgres_password '{POSTGRES_PASSWORD}'"),
+            1,
+        )
+        .replacen(
+            "password: &redis_password ''",
+            &format!("password: &redis_password '{REDIS_PASSWORD}'"),
+            1,
+        )
+        .replace(
+            "default_password: ''",
+            &format!("default_password: '{ADMIN_PASSWORD}'"),
+        )
+}
+
+fn valid_config_document() -> serde_json::Value {
+    // 按字段修改样例，避免注释或排版变化让测试输入悄悄失效；JSON 仍可由 YAML 文件入口加载。
+    config::Config::builder()
+        .add_source(config::File::from_str(
+            &valid_config(),
+            config::FileFormat::Yaml,
+        ))
+        .build()
+        .and_then(config::Config::try_deserialize)
+        .expect("example config document")
+}
+
+fn parse_config(config: &str) -> Result<(GatewayConfig, tempfile::TempDir), String> {
+    let directory = tempfile::tempdir().map_err(|error| error.to_string())?;
+    let deploy = directory.path().join("deploy");
+    fs::create_dir(&deploy).map_err(|error| error.to_string())?;
+    let path = deploy.join("config.yaml");
+    fs::write(&path, config).map_err(|error| error.to_string())?;
+    let mut config = config::Config::builder()
+        .add_source(config::File::from(path).required(true))
+        .build()
+        .and_then(config::Config::try_deserialize::<GatewayConfig>)
+        .map_err(|error| error.to_string())?;
+    config
+        .resolve_and_validate(&deploy)
+        .map_err(|error| error.to_string())?;
+    Ok((config, directory))
+}

backend/apps/gateway/tests/main.rs

@@ -0,0 +1,137 @@
+mod architecture;
+mod bootstrap;
+
+// 组合根是否混入业务策略由代码审查判断，行数和标识符/注释关键词不能证明职责越界。
+// 依赖 DAG、公开模块面和模块镜像继续由 architecture 检查，源码纪律由下方测试维护。
+
+use std::{
+    collections::BTreeSet,
+    fs,
+    path::{Path, PathBuf},
+};
+
+use syn::{Attribute, Item, Meta};
+
+#[test]
+fn app_tree_matches_frozen_terminal_manifest() {
+    let root = Path::new(env!("CARGO_MANIFEST_DIR"));
+    assert_eq!(
+        rust_files(&root.join("src")),
+        BTreeSet::from([
+            PathBuf::from("bootstrap.rs"),
+            PathBuf::from("lib.rs"),
+            PathBuf::from("main.rs"),
+        ]),
+    );
+    assert_eq!(
+        rust_files(&root.join("tests")),
+        BTreeSet::from([
+            PathBuf::from("architecture.rs"),
+            PathBuf::from("bootstrap.rs"),
+            PathBuf::from("main.rs"),
+        ]),
+    );
+}
+
+#[test]
+fn cargo_library_root_is_conventional_lib() {
+    let manifest = fs::read_to_string(Path::new(env!("CARGO_MANIFEST_DIR")).join("Cargo.toml"))
+        .expect("read app Cargo.toml");
+    assert!(!manifest.contains("[lib]"));
+    assert!(
+        Path::new(env!("CARGO_MANIFEST_DIR"))
+            .join("src/lib.rs")
+            .is_file()
+    );
+}
+
+#[test]
+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 path = root.join(relative);
+            let source = fs::read_to_string(&path).expect("read production source");
+            assert!(
+                !source.contains("include!("),
+                "{} uses include!",
+                path.display()
+            );
+            let syntax = syn::parse_file(&source).expect("parse production source");
+            for item in &syntax.items {
+                if let Item::Mod(module) = item {
+                    assert!(
+                        module.content.is_none(),
+                        "{} has an inline module",
+                        path.display()
+                    );
+                }
+                for attribute in item_attrs(item) {
+                    assert!(
+                        !is_path_or_test_cfg(attribute),
+                        "{} has a production test/path hook",
+                        path.display(),
+                    );
+                }
+            }
+        }
+    }
+}
+
+fn rust_files(root: &Path) -> BTreeSet<PathBuf> {
+    let mut result = BTreeSet::new();
+    collect_rust_files(root, root, &mut result);
+    result
+}
+
+fn collect_rust_files(root: &Path, current: &Path, result: &mut BTreeSet<PathBuf>) {
+    for entry in fs::read_dir(current).expect("read app tree") {
+        let path = entry.expect("read app tree entry").path();
+        if path.is_dir() {
+            collect_rust_files(root, &path, result);
+        } else if path.extension().is_some_and(|extension| extension == "rs") {
+            result.insert(
+                path.strip_prefix(root)
+                    .expect("relative app path")
+                    .to_path_buf(),
+            );
+        }
+    }
+}
+
+fn is_path_or_test_cfg(attribute: &Attribute) -> bool {
+    if attribute.path().is_ident("path") {
+        return true;
+    }
+    if !attribute.path().is_ident("cfg") && !attribute.path().is_ident("cfg_attr") {
+        return false;
+    }
+    let Meta::List(list) = &attribute.meta else {
+        return false;
+    };
+    list.tokens
+        .to_string()
+        .split(|character: char| !character.is_ascii_alphanumeric() && character != '_')
+        .any(|segment| segment == "test" || segment.starts_with("test_"))
+}
+
+fn item_attrs(item: &Item) -> &[Attribute] {
+    match item {
+        Item::Const(item) => &item.attrs,
+        Item::Enum(item) => &item.attrs,
+        Item::ExternCrate(item) => &item.attrs,
+        Item::Fn(item) => &item.attrs,
+        Item::ForeignMod(item) => &item.attrs,
+        Item::Impl(item) => &item.attrs,
+        Item::Macro(item) => &item.attrs,
+        Item::Mod(item) => &item.attrs,
+        Item::Static(item) => &item.attrs,
+        Item::Struct(item) => &item.attrs,
+        Item::Trait(item) => &item.attrs,
+        Item::TraitAlias(item) => &item.attrs,
+        Item::Type(item) => &item.attrs,
+        Item::Union(item) => &item.attrs,
+        Item::Use(item) => &item.attrs,
+        _ => &[],
+    }
+}

backend/apps/plugin-cli/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "codex-proxy-plugin-cli"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+rust-version.workspace = true
+
+[[bin]]
+name = "cpr-plugin"
+path = "src/main.rs"
+
+[dependencies]
+clap = { version = "4.6.7", features = ["derive"] }
+flate2 = "1.1.9"
+gateway-plugin-sdk = { path = "../../crates/gateway-plugin/sdk" }
+hex = "0.4.3"
+serde_json = "1.0.150"
+sha2 = "0.11.0"
+tar = "0.4.44"
+thiserror = "2.0.18"
+
+[dev-dependencies]
+tempfile = "3.27.0"
+
+[lints]
+workspace = true

backend/apps/plugin-cli/README.md

@@ -0,0 +1,51 @@
+# Codex Proxy Plugin CLI
+
+`cpr-plugin` 校验并规范化作者清单、收集声明的资源，生成可安装归档及 SHA-256 校验文件。
+当前输出使用 `manifestVersion: 1`、`protocolVersion: 1` 和 SDK `0.1` 合同。
+
+## 安装
+
+从仓库根目录安装到本地工具目录：
+
+```bash
+cargo install --locked --path backend/apps/plugin-cli --root /path/to/local-tools
+```
+
+将 `/path/to/local-tools/bin` 加入 `PATH`，或使用可执行文件的完整路径。
+
+## 打包
+
+先构建目标平台的插件二进制；插件提供管理页面时，还需构建页面静态资源。打包命令传入作者清单、二进制和所需的资源目录映射，通过 `cpr-plugin package --help` 查看完整参数：
+
+```bash
+cpr-plugin package \
+  --manifest /path/to/plugin/plugin.json \
+  --binary /path/to/plugin/target/x86_64-unknown-linux-gnu/release/plugin \
+  --target x86_64-unknown-linux-gnu \
+  --resource-map web=web/dist \
+  --output-dir /path/to/output
+```
+
+资源映射相对于作者清单所在目录解析。输出包括完整插件 ID、版本和目标 triple 命名的 `.tar.gz` 及 `.sha256`；归档根目录直接包含 `plugin.json`、可执行文件和已声明资源，不包含开发依赖。
+
+作者清单可省略普通贡献项的 `id`、`version` 和固定阶段；`middleware` 的 `request`／`attempt` 仍须显式选择。
+CLI 与 SDK 的 `Manifest::from_author_slice`、`PluginBuilder::from_json` 共用规范化入口；归档中的
+`plugin.json` 写入补全后的贡献项字段，不保留另一份作者声明。
+完整规则见 [SDK 清单](../../crates/gateway-plugin/sdk/docs/manifest.md)。
+
+支持 `x86_64-unknown-linux-gnu`、`aarch64-unknown-linux-gnu` 和 `aarch64-apple-darwin`。完整开发示例在同级 `codex-proxy-plugins/examples/workbench` 仓库目录；本工具不负责源码构建、上传或启用插件。
+
+### 图标资源
+
+在作者清单的 `icon` 中指定图标，并在 `resources` 中登记对应路径与 MIME 类型，配置方式见
+[SDK 插件图标](../../crates/gateway-plugin/sdk/docs/manifest.md#插件图标)。图标与其他声明资源一样参与打包和摘要计算，
+无需额外命令参数；工具保留文件原始内容，宿主安装时验证图标内容与资源限制。
+
+## 开发
+
+Rust 包名为 `codex-proxy-plugin-cli`，位于宿主的 `backend` workspace，共享工具链、锁文件和检查规则；内部仅依赖 `gateway-plugin-sdk`。
+
+```bash
+cargo run --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli -- package --help
+RUST_MIN_STACK=16777216 cargo +1.97.0 test --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked
+```

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

@@ -0,0 +1,562 @@
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    fs::{self, File, OpenOptions},
+    io::{self, Read as _, Write as _},
+    path::{Component, Path, PathBuf},
+};
+
+use clap::{Args, Parser, Subcommand};
+use flate2::{Compression, GzBuilder};
+use gateway_plugin_sdk::{
+    Manifest, ManifestError, PROTOCOL_VERSION, Package, PackageTarget, valid_package_path,
+};
+use sha2::{Digest as _, Sha256};
+use tar::{Builder, EntryType, Header, HeaderMode};
+use thiserror::Error;
+
+const MAXIMUM_COMPRESSED_BYTES: u64 = 32 * 1024 * 1024;
+const MAXIMUM_EXPANDED_BYTES: u64 = 128 * 1024 * 1024;
+const MAXIMUM_MANIFEST_BYTES: u64 = 64 * 1024;
+
+#[derive(Parser)]
+#[command(name = "cpr-plugin", version, about = "Codex Proxy 插件开发工具")]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    #[command(about = "校验清单并打包已编译的插件")]
+    Package(Options),
+}
+
+#[derive(Debug, Error)]
+enum PackagerError {
+    #[error("{0}")]
+    Invalid(String),
+    #[error("failed to {action} {path}: {source}")]
+    Io {
+        action: &'static str,
+        path: PathBuf,
+        #[source]
+        source: io::Error,
+    },
+    #[error("source or generated manifest is invalid: {0}")]
+    Manifest(#[from] ManifestError),
+    #[error("failed to encode generated manifest: {0}")]
+    EncodeManifest(#[source] serde_json::Error),
+}
+
+#[derive(Debug, Args)]
+struct Options {
+    #[arg(long, value_name = "FILE", help = "作者清单 plugin.json")]
+    manifest: PathBuf,
+    #[arg(long, value_name = "FILE", help = "已编译的目标平台插件二进制")]
+    binary: PathBuf,
+    #[arg(long, value_name = "TRIPLE", help = "目标平台 triple")]
+    target: String,
+    #[arg(long, value_name = "DIRECTORY", help = "归档与 SHA-256 文件的输出目录")]
+    output_dir: PathBuf,
+    #[arg(
+        long = "resource-map",
+        value_name = "PREFIX=DIRECTORY",
+        help = "包内资源前缀到项目内目录的映射，可重复传入"
+    )]
+    resource_maps: Vec<String>,
+}
+
+#[derive(Debug, Clone, Copy)]
+struct RuntimeTarget {
+    os: &'static str,
+    architecture: &'static str,
+}
+
+impl RuntimeTarget {
+    fn parse(triple: &str) -> Result<Self, PackagerError> {
+        match triple {
+            "x86_64-unknown-linux-gnu" => Ok(Self {
+                os: "linux",
+                architecture: "x86_64",
+            }),
+            "aarch64-unknown-linux-gnu" => Ok(Self {
+                os: "linux",
+                architecture: "aarch64",
+            }),
+            "aarch64-apple-darwin" => Ok(Self {
+                os: "macos",
+                architecture: "aarch64",
+            }),
+            _ => Err(PackagerError::Invalid(format!(
+                "unsupported plugin target {triple}"
+            ))),
+        }
+    }
+}
+
+#[derive(Debug)]
+struct PackageOutput {
+    archive: PathBuf,
+    checksum: PathBuf,
+}
+
+fn main() -> Result<(), PackagerError> {
+    match Cli::parse().command {
+        Commands::Package(options) => {
+            let output = package(&options)?;
+            println!("{}", output.archive.display());
+            println!("{}", output.checksum.display());
+            Ok(())
+        }
+    }
+}
+
+fn parse_resource_maps(values: &[String]) -> Result<BTreeMap<String, PathBuf>, PackagerError> {
+    let mut resource_maps = BTreeMap::new();
+    for value in values {
+        let (prefix, directory) = value.split_once('=').ok_or_else(|| {
+            PackagerError::Invalid(
+                "--resource-map must use package-prefix=source-directory".to_owned(),
+            )
+        })?;
+        if !valid_resource_prefix(prefix) {
+            return Err(PackagerError::Invalid(format!(
+                "invalid resource-map package prefix {prefix}"
+            )));
+        }
+        let directory = PathBuf::from(directory);
+        if !safe_relative_directory(&directory) {
+            return Err(PackagerError::Invalid(format!(
+                "resource-map source directory must be a non-empty project-relative path: {}",
+                directory.display()
+            )));
+        }
+        if resource_maps.insert(prefix.to_owned(), directory).is_some() {
+            return Err(PackagerError::Invalid(format!(
+                "duplicate resource-map package prefix {prefix}"
+            )));
+        }
+    }
+    Ok(resource_maps)
+}
+
+fn valid_resource_prefix(prefix: &str) -> bool {
+    valid_package_path(prefix) && !prefix.contains('/')
+}
+
+fn safe_relative_directory(path: &Path) -> bool {
+    !path.as_os_str().is_empty()
+        && !path.is_absolute()
+        && path
+            .components()
+            .all(|component| matches!(component, Component::Normal(_) | Component::CurDir))
+}
+
+fn package(options: &Options) -> Result<PackageOutput, PackagerError> {
+    let target = RuntimeTarget::parse(&options.target)?;
+    let resource_maps = parse_resource_maps(&options.resource_maps)?;
+    let manifest_bytes = read_regular_file(&options.manifest, MAXIMUM_MANIFEST_BYTES)?;
+    let mut manifest = Manifest::from_author_slice(&manifest_bytes)?;
+
+    let project_directory = options
+        .manifest
+        .parent()
+        .filter(|path| !path.as_os_str().is_empty())
+        .unwrap_or_else(|| Path::new("."));
+    let canonical_project = canonicalize(project_directory)?;
+    let mut sources = BTreeMap::from([(manifest.main.clone(), options.binary.clone())]);
+    let mut used_maps = BTreeSet::new();
+    for package_path in manifest.resources.keys() {
+        let source = resource_source(
+            project_directory,
+            package_path,
+            &resource_maps,
+            &mut used_maps,
+        )?;
+        let canonical_source = canonicalize(&source)?;
+        if !canonical_source.starts_with(&canonical_project) {
+            return Err(PackagerError::Invalid(format!(
+                "resource source escapes the plugin project: {}",
+                source.display()
+            )));
+        }
+        if sources.insert(package_path.clone(), source).is_some() {
+            return Err(PackagerError::Invalid(format!(
+                "plugin main and resource share package path {package_path}"
+            )));
+        }
+    }
+    if used_maps.len() != resource_maps.len() {
+        let unused = resource_maps
+            .keys()
+            .filter(|prefix| !used_maps.contains(*prefix))
+            .cloned()
+            .collect::<Vec<_>>();
+        return Err(PackagerError::Invalid(format!(
+            "unused resource-map package prefix: {}",
+            unused.join(", ")
+        )));
+    }
+    reject_case_folded_paths(sources.keys())?;
+
+    let mut files = BTreeMap::new();
+    let mut source_bytes = 0u64;
+    for (package_path, source) in sources {
+        let remaining = MAXIMUM_EXPANDED_BYTES
+            .checked_sub(source_bytes)
+            .ok_or_else(package_limit)?;
+        let bytes = read_regular_file(&source, remaining)?;
+        source_bytes = source_bytes
+            .checked_add(u64::try_from(bytes.len()).map_err(|_| package_limit())?)
+            .ok_or_else(package_limit)?;
+        files.insert(package_path, bytes);
+    }
+    let digests = files
+        .iter()
+        .map(|(path, bytes)| (path.clone(), hex::encode(Sha256::digest(bytes))))
+        .collect();
+    manifest.package = Some(Package {
+        protocol_version: PROTOCOL_VERSION,
+        target: PackageTarget {
+            os: target.os.to_owned(),
+            architecture: target.architecture.to_owned(),
+        },
+        files: digests,
+    });
+    manifest.validate()?;
+    let mut generated_manifest =
+        serde_json::to_vec_pretty(&manifest).map_err(PackagerError::EncodeManifest)?;
+    generated_manifest.push(b'\n');
+    if generated_manifest.len() as u64 > MAXIMUM_MANIFEST_BYTES {
+        return Err(package_limit());
+    }
+
+    create_directory(&options.output_dir)?;
+    let plugin_id = manifest.plugin_id()?;
+    let archive_name = format!("{plugin_id}-{}-{}.tar.gz", manifest.version, options.target);
+    let archive_path = options.output_dir.join(&archive_name);
+    let archive_temporary = options
+        .output_dir
+        .join(format!(".{archive_name}.{}.tmp", std::process::id()));
+    let mut temporary = TemporaryFile::create(archive_temporary)?;
+    write_archive(
+        temporary.file_mut(),
+        &generated_manifest,
+        &manifest.main,
+        &files,
+    )?;
+    temporary.sync_all()?;
+    let compressed_bytes = temporary.metadata_len()?;
+    if compressed_bytes > MAXIMUM_COMPRESSED_BYTES {
+        return Err(package_limit());
+    }
+    temporary.persist(&archive_path)?;
+
+    let archive_digest = sha256_file(&archive_path)?;
+    let checksum_path = options.output_dir.join(format!("{archive_name}.sha256"));
+    let checksum_temporary = options
+        .output_dir
+        .join(format!(".{archive_name}.sha256.{}.tmp", std::process::id()));
+    let mut checksum = TemporaryFile::create(checksum_temporary)?;
+    let checksum_temporary_path = checksum.path().to_owned();
+    writeln!(checksum.file_mut(), "{archive_digest}  {archive_name}").map_err(|source| {
+        PackagerError::Io {
+            action: "write",
+            path: checksum_temporary_path,
+            source,
+        }
+    })?;
+    checksum.sync_all()?;
+    checksum.persist(&checksum_path)?;
+
+    Ok(PackageOutput {
+        archive: archive_path,
+        checksum: checksum_path,
+    })
+}
+
+fn resource_source(
+    project_directory: &Path,
+    package_path: &str,
+    mappings: &BTreeMap<String, PathBuf>,
+    used_mappings: &mut BTreeSet<String>,
+) -> Result<PathBuf, PackagerError> {
+    let (prefix, remainder) = package_path
+        .split_once('/')
+        .map_or((package_path, None), |(prefix, remainder)| {
+            (prefix, Some(remainder))
+        });
+    if let Some(directory) = mappings.get(prefix) {
+        let remainder = remainder.ok_or_else(|| {
+            PackagerError::Invalid(format!(
+                "mapped resource {package_path} must have a path below prefix {prefix}"
+            ))
+        })?;
+        used_mappings.insert(prefix.to_owned());
+        Ok(project_directory.join(directory).join(remainder))
+    } else {
+        Ok(project_directory.join(package_path))
+    }
+}
+
+fn reject_case_folded_paths<'a>(
+    paths: impl IntoIterator<Item = &'a String>,
+) -> Result<(), PackagerError> {
+    let mut folded = BTreeSet::new();
+    for path in paths {
+        if !folded.insert(path.to_ascii_lowercase()) {
+            return Err(PackagerError::Invalid(format!(
+                "package path collides case-insensitively: {path}"
+            )));
+        }
+    }
+    Ok(())
+}
+
+fn write_archive(
+    output: &mut File,
+    manifest: &[u8],
+    main_path: &str,
+    files: &BTreeMap<String, Vec<u8>>,
+) -> Result<(), PackagerError> {
+    let encoder = GzBuilder::new().mtime(0).write(output, Compression::best());
+    let limited = LimitedWriter::new(encoder, MAXIMUM_EXPANDED_BYTES);
+    let mut archive = Builder::new(limited);
+    archive.mode(HeaderMode::Deterministic);
+    append_file(&mut archive, "plugin.json", manifest, 0o644)?;
+    for (path, bytes) in files {
+        let mode = if path == main_path { 0o755 } else { 0o644 };
+        append_file(&mut archive, path, bytes, mode)?;
+    }
+    archive.finish().map_err(|source| PackagerError::Io {
+        action: "finish archive",
+        path: PathBuf::from("<temporary archive>"),
+        source,
+    })?;
+    let limited = archive.into_inner().map_err(|source| PackagerError::Io {
+        action: "finish archive",
+        path: PathBuf::from("<temporary archive>"),
+        source,
+    })?;
+    limited
+        .into_inner()
+        .finish()
+        .map_err(|source| PackagerError::Io {
+            action: "finish compression",
+            path: PathBuf::from("<temporary archive>"),
+            source,
+        })?;
+    Ok(())
+}
+
+fn append_file<W: io::Write>(
+    archive: &mut Builder<W>,
+    path: &str,
+    bytes: &[u8],
+    mode: u32,
+) -> Result<(), PackagerError> {
+    let mut header = Header::new_gnu();
+    header.set_entry_type(EntryType::Regular);
+    header.set_mode(mode);
+    header.set_uid(0);
+    header.set_gid(0);
+    header.set_mtime(0);
+    header.set_size(bytes.len() as u64);
+    header.set_cksum();
+    archive
+        .append_data(&mut header, path, bytes)
+        .map_err(|source| PackagerError::Io {
+            action: "append archive entry",
+            path: PathBuf::from(path),
+            source,
+        })
+}
+
+struct LimitedWriter<W> {
+    inner: W,
+    written: u64,
+    maximum: u64,
+}
+
+impl<W> LimitedWriter<W> {
+    const fn new(inner: W, maximum: u64) -> Self {
+        Self {
+            inner,
+            written: 0,
+            maximum,
+        }
+    }
+
+    fn into_inner(self) -> W {
+        self.inner
+    }
+}
+
+impl<W> io::Write for LimitedWriter<W>
+where
+    W: io::Write,
+{
+    fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
+        let length = u64::try_from(bytes.len())
+            .map_err(|_| io::Error::other("plugin package exceeds expanded size limit"))?;
+        if length > self.maximum.saturating_sub(self.written) {
+            return Err(io::Error::other(
+                "plugin package exceeds expanded size limit",
+            ));
+        }
+        let written = self.inner.write(bytes)?;
+        self.written = self
+            .written
+            .checked_add(written as u64)
+            .ok_or_else(|| io::Error::other("plugin package size overflow"))?;
+        Ok(written)
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        self.inner.flush()
+    }
+}
+
+struct TemporaryFile {
+    path: PathBuf,
+    file: File,
+}
+
+impl TemporaryFile {
+    fn create(path: PathBuf) -> Result<Self, PackagerError> {
+        let file = OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .open(&path)
+            .map_err(|source| PackagerError::Io {
+                action: "create",
+                path: path.clone(),
+                source,
+            })?;
+        Ok(Self { path, file })
+    }
+
+    fn path(&self) -> &Path {
+        &self.path
+    }
+
+    fn file_mut(&mut self) -> &mut File {
+        &mut self.file
+    }
+
+    fn sync_all(&mut self) -> Result<(), PackagerError> {
+        let path = self.path.clone();
+        self.file_mut()
+            .sync_all()
+            .map_err(|source| PackagerError::Io {
+                action: "sync",
+                path,
+                source,
+            })
+    }
+
+    fn metadata_len(&self) -> Result<u64, PackagerError> {
+        self.file
+            .metadata()
+            .map(|metadata| metadata.len())
+            .map_err(|source| PackagerError::Io {
+                action: "inspect",
+                path: self.path.clone(),
+                source,
+            })
+    }
+
+    fn persist(mut self, destination: &Path) -> Result<(), PackagerError> {
+        fs::rename(&self.path, destination).map_err(|source| PackagerError::Io {
+            action: "publish",
+            path: destination.to_owned(),
+            source,
+        })?;
+        self.path.clear();
+        Ok(())
+    }
+}
+
+impl Drop for TemporaryFile {
+    fn drop(&mut self) {
+        if !self.path.as_os_str().is_empty() {
+            let _ = fs::remove_file(&self.path);
+        }
+    }
+}
+
+fn read_regular_file(path: &Path, maximum_bytes: u64) -> Result<Vec<u8>, PackagerError> {
+    let metadata = fs::symlink_metadata(path).map_err(|source| PackagerError::Io {
+        action: "inspect",
+        path: path.to_owned(),
+        source,
+    })?;
+    if !metadata.file_type().is_file() || metadata.file_type().is_symlink() {
+        return Err(PackagerError::Invalid(format!(
+            "package input must be a regular non-symlink file: {}",
+            path.display()
+        )));
+    }
+    if metadata.len() > maximum_bytes {
+        return Err(package_limit());
+    }
+    let file = File::open(path).map_err(|source| PackagerError::Io {
+        action: "open",
+        path: path.to_owned(),
+        source,
+    })?;
+    let mut bytes = Vec::with_capacity(usize::try_from(metadata.len()).unwrap_or_default());
+    file.take(maximum_bytes.saturating_add(1))
+        .read_to_end(&mut bytes)
+        .map_err(|source| PackagerError::Io {
+            action: "read",
+            path: path.to_owned(),
+            source,
+        })?;
+    if bytes.len() as u64 > maximum_bytes {
+        return Err(package_limit());
+    }
+    Ok(bytes)
+}
+
+fn canonicalize(path: &Path) -> Result<PathBuf, PackagerError> {
+    fs::canonicalize(path).map_err(|source| PackagerError::Io {
+        action: "canonicalize",
+        path: path.to_owned(),
+        source,
+    })
+}
+
+fn create_directory(path: &Path) -> Result<(), PackagerError> {
+    fs::create_dir_all(path).map_err(|source| PackagerError::Io {
+        action: "create directory",
+        path: path.to_owned(),
+        source,
+    })
+}
+
+fn sha256_file(path: &Path) -> Result<String, PackagerError> {
+    let mut file = File::open(path).map_err(|source| PackagerError::Io {
+        action: "open",
+        path: path.to_owned(),
+        source,
+    })?;
+    let mut digest = Sha256::new();
+    let mut buffer = [0u8; 64 * 1024];
+    loop {
+        let read = file.read(&mut buffer).map_err(|source| PackagerError::Io {
+            action: "hash",
+            path: path.to_owned(),
+            source,
+        })?;
+        if read == 0 {
+            break;
+        }
+        digest.update(&buffer[..read]);
+    }
+    Ok(hex::encode(digest.finalize()))
+}
+
+fn package_limit() -> PackagerError {
+    PackagerError::Invalid("plugin package exceeds installation size limits".to_owned())
+}

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

@@ -0,0 +1,258 @@
+use std::{
+    collections::BTreeMap,
+    fs::{self, File},
+    io::Read as _,
+    process::{Command, Output},
+};
+
+use flate2::read::MultiGzDecoder;
+use gateway_plugin_sdk::{Capability, MANIFEST_VERSION, Manifest, PROTOCOL_VERSION, Stage};
+use sha2::{Digest as _, Sha256};
+
+fn cli(arguments: &[&str]) -> Output {
+    Command::new(env!("CARGO_BIN_EXE_cpr-plugin"))
+        .args(arguments)
+        .output()
+        .unwrap()
+}
+
+fn assert_rejected(arguments: &[&str], message: &str) {
+    let output = cli(arguments);
+    assert!(
+        !output.status.success(),
+        "{arguments:?} unexpectedly succeeded"
+    );
+    assert!(
+        String::from_utf8_lossy(&output.stderr).contains(message),
+        "{arguments:?}: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+}
+
+fn package_arguments() -> Vec<&'static str> {
+    vec![
+        "package",
+        "--manifest",
+        "plugin.json",
+        "--binary",
+        "plugin-bin",
+        "--target",
+        "x86_64-unknown-linux-gnu",
+        "--output-dir",
+        "dist",
+    ]
+}
+
+#[test]
+fn root_help_lists_package_command() {
+    let output = cli(&["--help"]);
+    assert!(output.status.success());
+    let help = String::from_utf8(output.stdout).unwrap();
+    assert!(help.contains("cpr-plugin <COMMAND>"), "{help}");
+    assert!(help.contains("package"), "{help}");
+}
+
+#[test]
+fn version_uses_the_user_command_name() {
+    let output = cli(&["--version"]);
+    assert!(output.status.success());
+    assert_eq!(
+        String::from_utf8(output.stdout).unwrap(),
+        format!("cpr-plugin {}\n", env!("CARGO_PKG_VERSION"))
+    );
+}
+
+#[test]
+fn package_help_does_not_require_inputs() {
+    let output = cli(&["package", "--help"]);
+    assert!(output.status.success());
+    let help = String::from_utf8(output.stdout).unwrap();
+    assert!(help.contains("cpr-plugin package"), "{help}");
+    assert!(help.contains("--resource-map"), "{help}");
+}
+
+#[test]
+fn rejects_missing_subcommand() {
+    assert_rejected(&[], "Usage: cpr-plugin");
+}
+
+#[test]
+fn rejects_unknown_subcommand() {
+    assert_rejected(&["publish"], "unrecognized subcommand");
+}
+
+#[test]
+fn rejects_missing_package_arguments() {
+    assert_rejected(&["package"], "--manifest");
+}
+
+#[test]
+fn rejects_duplicate_single_value_options() {
+    let mut arguments = package_arguments();
+    arguments.extend(["--manifest", "other.json"]);
+    assert_rejected(&arguments, "cannot be used multiple times");
+}
+
+#[test]
+fn rejects_unknown_targets() {
+    let mut arguments = package_arguments();
+    arguments[6] = "x86_64-pc-windows-msvc";
+    assert_rejected(&arguments, "unsupported plugin target");
+}
+
+#[test]
+fn rejects_unsafe_resource_mappings_before_reading_files() {
+    for (mapping, message) in [
+        ("web=../web/dist", "project-relative path"),
+        ("web=/web/dist", "project-relative path"),
+        ("web=", "project-relative path"),
+        ("web/assets=web/dist", "invalid resource-map package prefix"),
+        ("web", "must use package-prefix=source-directory"),
+    ] {
+        let mut arguments = package_arguments();
+        arguments.extend(["--resource-map", mapping]);
+        assert_rejected(&arguments, message);
+    }
+}
+
+#[test]
+fn rejects_duplicate_resource_prefixes() {
+    let mut arguments = package_arguments();
+    arguments.extend([
+        "--resource-map",
+        "web=web/dist",
+        "--resource-map",
+        "web=other",
+    ]);
+    assert_rejected(&arguments, "duplicate resource-map package prefix");
+}
+
+#[test]
+fn packages_only_generated_resources_with_v3_metadata() {
+    assert_packaged_resources("assets/icon.png", "image/png", b"png");
+}
+
+#[test]
+fn packages_svg_icons_with_their_declared_mime_and_digest() {
+    assert_packaged_resources(
+        "assets/icon.svg",
+        "image/svg+xml",
+        br#"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M2 2h20v20H2z"/></svg>"#,
+    );
+}
+
+fn assert_packaged_resources(icon_path: &str, icon_mime: &str, icon: &[u8]) {
+    let directory = tempfile::tempdir().unwrap();
+    let project = directory.path().join("example");
+    fs::create_dir_all(project.join("web/dist")).unwrap();
+    fs::create_dir_all(project.join("assets")).unwrap();
+    let mut source: serde_json::Value = serde_json::from_slice(source_manifest()).unwrap();
+    source["icon"] = icon_path.into();
+    let resources = source["resources"].as_object_mut().unwrap();
+    resources.remove("assets/icon.png");
+    resources.insert(icon_path.into(), icon_mime.into());
+    fs::write(
+        project.join("plugin.json"),
+        serde_json::to_vec(&source).unwrap(),
+    )
+    .unwrap();
+    fs::write(project.join("LICENSE"), b"license").unwrap();
+    fs::write(project.join(icon_path), icon).unwrap();
+    fs::write(project.join("plugin-bin"), b"binary").unwrap();
+    fs::write(project.join("web/index.html"), b"source html").unwrap();
+    fs::write(project.join("web/dist/index.html"), b"built html").unwrap();
+    fs::write(project.join("web/dist/app.js"), b"built js").unwrap();
+    fs::write(project.join("web/dist/app.css"), b"built css").unwrap();
+
+    let output = Command::new(env!("CARGO_BIN_EXE_cpr-plugin"))
+        .arg("package")
+        .arg("--manifest")
+        .arg(project.join("plugin.json"))
+        .arg("--binary")
+        .arg(project.join("plugin-bin"))
+        .args(["--target", "x86_64-unknown-linux-gnu"])
+        .arg("--output-dir")
+        .arg(project.join("dist"))
+        .args(["--resource-map", "web=web/dist"])
+        .output()
+        .unwrap();
+    assert!(
+        output.status.success(),
+        "{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+
+    let archive_name = "codex-proxy.request-workbench-0.1.0-x86_64-unknown-linux-gnu.tar.gz";
+    let archive_path = project.join("dist").join(archive_name);
+    let checksum_path = project.join("dist").join(format!("{archive_name}.sha256"));
+    assert_eq!(
+        String::from_utf8(output.stdout).unwrap(),
+        format!("{}\n{}\n", archive_path.display(), checksum_path.display())
+    );
+    let archive = File::open(&archive_path).unwrap();
+    let mut package = tar::Archive::new(MultiGzDecoder::new(archive));
+    let mut entries = BTreeMap::new();
+    for entry in package.entries().unwrap() {
+        let mut entry = entry.unwrap();
+        let path = entry.path().unwrap().to_string_lossy().into_owned();
+        let mut bytes = Vec::new();
+        entry.read_to_end(&mut bytes).unwrap();
+        entries.insert(path, bytes);
+    }
+    assert_eq!(
+        entries.keys().cloned().collect::<Vec<_>>(),
+        vec![
+            "LICENSE".to_owned(),
+            icon_path.to_owned(),
+            "bin/plugin".to_owned(),
+            "plugin.json".to_owned(),
+            "web/app.css".to_owned(),
+            "web/app.js".to_owned(),
+            "web/index.html".to_owned(),
+        ]
+    );
+    assert_eq!(entries["web/index.html"], b"built html");
+    let manifest: Manifest = serde_json::from_slice(&entries["plugin.json"]).unwrap();
+    assert_eq!(manifest.manifest_version, MANIFEST_VERSION);
+    assert_eq!(
+        manifest.contributes[&Capability::Middleware].id,
+        "codex-proxy.request-workbench.middleware"
+    );
+    assert_eq!(
+        manifest.contributes[&Capability::Management].stages,
+        [Stage::Management]
+    );
+    assert_eq!(manifest.resources[icon_path], icon_mime);
+    assert_eq!(entries[icon_path], icon);
+    let package = manifest.package.unwrap();
+    assert_eq!(package.files[icon_path], hex::encode(Sha256::digest(icon)));
+    assert_eq!(package.protocol_version, PROTOCOL_VERSION);
+    assert_eq!(package.target.os, "linux");
+    assert_eq!(package.target.architecture, "x86_64");
+    assert_eq!(package.files.len(), 6);
+    let checksum = fs::read_to_string(checksum_path).unwrap();
+    let digest = hex::encode(Sha256::digest(fs::read(archive_path).unwrap()));
+    assert_eq!(checksum, format!("{digest}  {archive_name}\n"));
+}
+
+fn source_manifest() -> &'static [u8] {
+    br#"{
+      "manifestVersion":1,
+      "name":"request-workbench",
+      "displayName":"Request Workbench",
+      "publisher":"codex-proxy",
+      "version":"0.1.0",
+      "description":"test package",
+      "license":"Apache-2.0",
+      "engines":{"codex-proxy-rs":">=3.12.0, <4.0.0"},
+      "main":"bin/plugin",
+      "runtime":"trustedProcess",
+      "contributes":{
+        "middleware":{"stages":["request"],"inputFormats":["openai"],"outputFormats":["openai"]},
+        "management":{}
+      },
+      "permissions":["requests","accounts"],
+      "icon":"assets/icon.png",
+      "resources":{"LICENSE":"text/plain","assets/icon.png":"image/png","web/index.html":"text/html","web/app.js":"text/javascript","web/app.css":"text/css"}
+    }"#
+}

backend/crates/gateway-admin/Cargo.toml

@@ -0,0 +1,43 @@
+[package]
+name = "gateway-admin"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+rust-version.workspace = true
+autotests = false
+
+[[test]]
+name = "main"
+path = "tests/main.rs"
+
+[dependencies]
+argon2 = "0.6.0"
+async-trait = "0.1.89"
+base64 = "0.23.0"
+bytes = "1.11.1"
+chrono = { version = "0.4.45", features = ["serde"] }
+futures = "0.3.32"
+gateway-core = { path = "../gateway-core" }
+heck = "0.5.0"
+hex = "0.4.3"
+rand_core = { version = "0.6.4", features = ["getrandom"] }
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
+secrecy = { version = "0.10.3", features = ["serde"] }
+semver = "1.0.27"
+sha2 = "0.11"
+subtle = "2.6.1"
+thiserror = "2.0.18"
+tracing = "0.1.44"
+uuid = { version = "1.23.3", features = ["v7"] }
+cron = "0.17"
+chrono-tz = "0.10"
+tokio = { version = "1.52", features = ["rt", "time", "macros", "sync"] }
+
+[dev-dependencies]
+tempfile = "3"
+tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt", "test-util"] }
+
+[lints]
+workspace = true

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

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

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

@@ -0,0 +1,161 @@
+//! 备份纯策略：Cron 推进与保留候选。
+//!
+//! 本模块不持有任何端口或对象，是 `BackupService` 与 `BackupTask` 共用的纯函数集。
+
+use std::str::FromStr;
+
+use chrono::{DateTime, Duration, TimeZone as _, Utc};
+use chrono_tz::Tz;
+use cron::Schedule;
+
+use crate::model::backup::{BackupError, BackupRecord, BackupStatus, code};
+
+/// 向历史回溯的最大范围（分钟）。覆盖 Feb 29 + 特定星期等罕见组合的最长间隔。
+const MAX_BACKDATE_MINUTES: i64 = 40 * 366 * 24 * 60;
+
+/// 已解析并校验的备份计划。
+#[derive(Debug, Clone)]
+pub struct BackupSchedule {
+    schedule: Schedule,
+    timezone: Tz,
+}
+
+impl BackupSchedule {
+    /// 解析并校验 5 段 Cron 与 IANA 时区。
+    ///
+    /// # Errors
+    ///
+    /// Cron 非法或时区不是 IANA 名称时返回 [`BackupError`]。
+    pub fn parse(cron_expression: &str, schedule_timezone: &str) -> 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 })
+    }
+
+    /// 返回最接近 `at`（含 `at` 所在分钟）的最近一次触发时间。
+    ///
+    /// 若过去 `MAX_BACKDATE_MINUTES` 内没有任何触发（极罕见的稀疏计划或超长停机），
+    /// 返回 `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。
+        let low_instant = instant(low_min, self.timezone)?;
+        if self
+            .schedule
+            .after(&low_instant)
+            .next()
+            .is_none_or(|firing| firing.timestamp() > high_min * 60 + 59)
+        {
+            return None;
+        }
+
+        // 二分查找最小的 u（分钟）使 after(u) > high；prev = after(u - 1 分钟)。
+        let mut lo = low_min;
+        let mut hi = high_min;
+        while lo < hi {
+            let mid = lo + (hi - lo) / 2;
+            if self
+                .firing_after(mid)
+                .is_some_and(|firing| firing > high_min)
+            {
+                hi = mid;
+            } else {
+                lo = mid + 1;
+            }
+        }
+        self.firing_after(lo - 1)
+            .filter(|&firing| firing <= high_min)
+            .and_then(|firing| Utc.timestamp_opt(firing * 60, 0).single())
+    }
+
+    /// 返回第一个严格晚于 `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))
+    }
+
+    /// `after(u 分钟)` 返回的第一个触发时间（分钟索引），用于二分搜索。
+    fn firing_after(&self, minute_index: i64) -> Option<i64> {
+        let instant = instant(minute_index, self.timezone)?;
+        self.schedule
+            .after(&instant)
+            .next()
+            .map(|firing| firing.timestamp().div_euclid(60))
+    }
+}
+
+/// 构造指定分钟索引（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`。
+    Days,
+    /// 超过 `retention_count`。
+    Count,
+}
+
+/// 保留决策。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RetentionDecision {
+    pub record_id: String,
+    pub reason: RetentionReason,
+}
+
+/// 从按完成时间倒序的 completed 计划备份中决定纳入删除流程的记录。
+///
+/// 自动保留规则：
+/// - `retentionDays = 0` 时不按天数清理；`retentionCount = 0` 时不按份数清理。
+/// - 自动计划备份满足任一启用阈值即可进入删除。
+/// - 无论阈值如何，至少保留最近一个成功的计划备份（倒序下标 0）。
+/// - 手动备份不进入本规则；手工/计划记录各自的 `expires_at` 由到期扫描处理。
+#[must_use]
+pub fn decide_retention(
+    retention_days: u32,
+    retention_count: u32,
+    now: DateTime<Utc>,
+    scheduled_completed_desc: &[BackupRecord],
+) -> Vec<RetentionDecision> {
+    let mut decisions = Vec::new();
+    for (index, record) in scheduled_completed_desc.iter().enumerate() {
+        if record.status != BackupStatus::Completed {
+            continue;
+        }
+        // 最近一个成功的计划备份永远保留。
+        if index == 0 {
+            continue;
+        }
+        let expired_by_days = retention_days > 0
+            && record.completed_at.is_some_and(|completed_at| {
+                completed_at <= now - Duration::days(i64::from(retention_days))
+            });
+        let exceeded_count =
+            retention_count > 0 && index >= usize::try_from(retention_count).unwrap_or(usize::MAX);
+        if expired_by_days || exceeded_count {
+            decisions.push(RetentionDecision {
+                record_id: record.id.clone(),
+                reason: if expired_by_days {
+                    RetentionReason::Days
+                } else {
+                    RetentionReason::Count
+                },
+            });
+        }
+    }
+    decisions
+}

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

@@ -0,0 +1,648 @@
+//! Backup Worker 贡献：单个可取消 `DaemonTask` 承担调度、执行、删除收敛与保留清理。
+//!
+//! 当前部署边界是单副本，因此不需要 Redis lease、fencing token 或 heartbeat。长时间
+//! `pg_dump` 与上传由本 Daemon 自身持有；Host 只负责 panic 后重启、健康与关闭。
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use chrono::{DateTime, Utc};
+use futures::future::BoxFuture;
+use gateway_core::{
+    lifecycle::CancellationToken,
+    task::{DaemonTask, WorkerTaskError},
+};
+use tracing::{info, warn};
+
+use crate::{
+    model::backup::{
+        BackupError, BackupObjectMetadata, BackupRecord, BackupStatus, BackupStorageConfig,
+        BackupTriggerKind, build_backup_seed, code,
+    },
+    ports::backup::{
+        BackupObjectStorePort, BackupRepository, DatabaseDumpPort, DumpRequest,
+        StatusTransitionUpdate, UploadObjectRequest,
+    },
+};
+
+impl From<BackupError> for WorkerTaskError {
+    fn from(error: BackupError) -> Self {
+        WorkerTaskError::safe(error.message())
+    }
+}
+
+use super::policy::{BackupSchedule, decide_retention};
+
+/// 循环间隔：管理员修改 Cron 后该时长内生效；无工作时可取消等待。
+const BACKUP_LOOP_INTERVAL: Duration = Duration::from_secs(30);
+/// 每个循环最多执行的保留删除数量。
+const RETENTION_BATCH_SIZE: usize = 10;
+/// 保留扫描一次读取的 completed 计划备份上限。
+const RETENTION_SCAN_LIMIT: u32 = 1000;
+/// 每个循环最多完成的待删除记录数量。
+const PENDING_DELETION_BATCH: u32 = 20;
+
+/// 备份 Daemon 任务。
+pub struct BackupTask {
+    repository: Arc<dyn BackupRepository>,
+    dump: Arc<dyn DatabaseDumpPort>,
+    object_store: Arc<dyn BackupObjectStorePort>,
+}
+
+impl BackupTask {
+    /// 组合仓储、导出器与对象存储适配器。
+    #[must_use]
+    pub fn new(
+        repository: Arc<dyn BackupRepository>,
+        dump: Arc<dyn DatabaseDumpPort>,
+        object_store: Arc<dyn BackupObjectStorePort>,
+    ) -> Self {
+        Self {
+            repository,
+            dump,
+            object_store,
+        }
+    }
+}
+
+impl DaemonTask for BackupTask {
+    fn run(&self, cancellation: CancellationToken) -> BoxFuture<'_, Result<(), WorkerTaskError>> {
+        Box::pin(async move { self.run_daemon(cancellation).await })
+    }
+}
+
+impl BackupTask {
+    async fn run_daemon(&self, cancellation: CancellationToken) -> Result<(), WorkerTaskError> {
+        loop {
+            if cancellation.is_cancelled() {
+                return Ok(());
+            }
+            self.run_cycle(&cancellation).await?;
+
+            tokio::select! {
+                _ = cancellation.cancelled() => return Ok(()),
+                _ = tokio::time::sleep(BACKUP_LOOP_INTERVAL) => {}
+            }
+        }
+    }
+
+    /// 执行一个周期：推进计划、恢复中间态、删除收敛、领取执行一个任务、保留清理。
+    ///
+    /// 对外暴露以便集成测试逐周期驱动；daemon 循环内部复用。
+    ///
+    /// # Errors
+    ///
+    /// 仓储或基础设施不可用、任务执行失败时返回 [`WorkerTaskError`]。
+    pub async fn run_cycle(&self, cancellation: &CancellationToken) -> Result<(), WorkerTaskError> {
+        if cancellation.is_cancelled() {
+            return Ok(());
+        }
+        self.advance_schedule(Utc::now()).await?;
+        self.recover_intermediate(cancellation).await?;
+        self.finish_pending_deletions().await?;
+        self.process_next_task(cancellation).await?;
+        self.run_retention_batch(Utc::now()).await?;
+        Ok(())
+    }
+
+    /// 推进到期计划并幂等插入 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() {
+            return Ok(());
+        }
+        let schedule = BackupSchedule::parse(cron, timezone)
+            .map_err(|_| WorkerTaskError::safe("backup schedule is invalid"))?;
+
+        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)
+                        .await
+                        .map_err(repo_error)?;
+                }
+                return Ok(());
+            }
+        };
+        if !due {
+            return Ok(());
+        }
+
+        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)
+                        .await
+                        .map_err(repo_error)?;
+                }
+                return Ok(());
+            }
+        };
+        let prefix = settings.prefix.as_deref().unwrap_or_default();
+        let expires_at = if settings.retention_days > 0 {
+            Some(now + chrono::Duration::days(i64::from(settings.retention_days)))
+        } else {
+            None
+        };
+        let seed = build_backup_seed(
+            BackupTriggerKind::Scheduled,
+            Some(scheduled_at),
+            prefix,
+            now,
+            expires_at,
+        )
+        .map_err(infra_error)?;
+        let inserted = self
+            .repository
+            .insert_scheduled_record(seed)
+            .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)?;
+        }
+        Ok(())
+    }
+
+    /// 恢复中间状态（dumping/uploading/deleting）。
+    async fn recover_intermediate(
+        &self,
+        cancellation: &CancellationToken,
+    ) -> Result<(), WorkerTaskError> {
+        let records = self
+            .repository
+            .list_intermediate_records()
+            .await
+            .map_err(repo_error)?;
+        for record in records {
+            match record.status {
+                BackupStatus::Dumping => self.recover_dumping(&record, cancellation).await?,
+                BackupStatus::Uploading => self.recover_uploading(&record, cancellation).await?,
+                _ => {}
+            }
+        }
+        Ok(())
+    }
+
+    /// dumping：有完整暂存则继续上传，否则清理暂存并标记失败。
+    async fn recover_dumping(
+        &self,
+        record: &BackupRecord,
+        cancellation: &CancellationToken,
+    ) -> Result<(), WorkerTaskError> {
+        match self.dump.inspect_staging(&record.id).await? {
+            Some(artifact) => {
+                let now = Utc::now();
+                let update = StatusTransitionUpdate {
+                    size_bytes: Some(artifact.size_bytes),
+                    sha256: Some(artifact.sha256.clone()),
+                    ..Default::default()
+                };
+                let Some(uploading_record) = self
+                    .repository
+                    .transition_status(
+                        &record.id,
+                        BackupStatus::Dumping,
+                        BackupStatus::Uploading,
+                        update,
+                        now,
+                    )
+                    .await
+                    .map_err(repo_error)?
+                else {
+                    return Ok(());
+                };
+                self.upload_and_verify(
+                    &uploading_record,
+                    &artifact.path,
+                    artifact.size_bytes,
+                    &artifact.sha256,
+                    now,
+                    cancellation,
+                )
+                .await?;
+            }
+            None => {
+                let _ = self.dump.cleanup_staging(&record.id).await;
+                self.fail_task(record, code::PG_DUMP_FAILED, "导出进程中断，暂存归档不完整")
+                    .await?;
+            }
+        }
+        Ok(())
+    }
+
+    /// uploading：远端匹配则补记完成，有完整暂存则重试上传，否则失败。
+    async fn recover_uploading(
+        &self,
+        record: &BackupRecord,
+        cancellation: &CancellationToken,
+    ) -> Result<(), WorkerTaskError> {
+        let settings = self.repository.load_settings().await.map_err(repo_error)?;
+        let Some(config) = BackupStorageConfig::from_settings(&settings) else {
+            return Ok(());
+        };
+        if let Some(remote) = self
+            .object_store
+            .head_object(&config, &record.object_key)
+            .await?
+            && record.size_bytes == Some(remote.size_bytes)
+            && record.sha256.as_deref() == Some(remote.sha256.as_str())
+        {
+            let now = Utc::now();
+            self.repository
+                .transition_status(
+                    &record.id,
+                    BackupStatus::Uploading,
+                    BackupStatus::Completed,
+                    StatusTransitionUpdate::default(),
+                    now,
+                )
+                .await
+                .map_err(repo_error)?;
+            return Ok(());
+        }
+        match self.dump.inspect_staging(&record.id).await? {
+            Some(artifact) => {
+                self.upload_and_verify(
+                    record,
+                    &artifact.path,
+                    artifact.size_bytes,
+                    &artifact.sha256,
+                    Utc::now(),
+                    cancellation,
+                )
+                .await
+            }
+            None => {
+                self.fail_task(
+                    record,
+                    code::S3_UPLOAD_FAILED,
+                    "远端对象缺失且本地无完整暂存",
+                )
+                .await
+            }
+        }
+    }
+
+    /// 完成待删除记录（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 {
+            return Ok(());
+        };
+        let records = self
+            .repository
+            .list_pending_deletions(PENDING_DELETION_BATCH)
+            .await
+            .map_err(repo_error)?;
+        for record in records {
+            if self
+                .object_store
+                .delete_object(&config, &record.object_key)
+                .await
+                .is_ok()
+            {
+                self.repository
+                    .delete_record(&record.id)
+                    .await
+                    .map_err(repo_error)?;
+            }
+        }
+        Ok(())
+    }
+
+    /// 领取一个 queued 任务并执行导出、上传与远端校验。
+    async fn process_next_task(
+        &self,
+        cancellation: &CancellationToken,
+    ) -> Result<(), WorkerTaskError> {
+        let now = Utc::now();
+        let Some(record) = self
+            .repository
+            .claim_next_queued(now)
+            .await
+            .map_err(repo_error)?
+        else {
+            return Ok(());
+        };
+        info!(
+            backup_id = %record.id,
+            attempt = record.attempt_count,
+            "领取备份任务"
+        );
+        if let Err(error) = self.execute_task(&record, cancellation).await {
+            warn!(backup_id = %record.id, error = %error, "备份任务执行失败");
+        }
+        Ok(())
+    }
+
+    /// 执行单个任务；内部处理全部状态迁移。
+    async fn execute_task(
+        &self,
+        record: &BackupRecord,
+        cancellation: &CancellationToken,
+    ) -> Result<(), WorkerTaskError> {
+        let settings = self.repository.load_settings().await.map_err(repo_error)?;
+        if BackupStorageConfig::from_settings(&settings).is_none() {
+            return self
+                .fail_task(record, code::INVALID_CONFIG, "备份存储配置不完整")
+                .await;
+        }
+        if !settings.storage_verified() {
+            return self
+                .fail_task(record, code::INVALID_CONFIG, "备份存储配置尚未通过连接测试")
+                .await;
+        }
+
+        let now = Utc::now();
+        let artifact = match self
+            .dump
+            .dump(DumpRequest {
+                backup_id: record.id.clone(),
+                cancellation: cancellation.clone(),
+            })
+            .await
+        {
+            Ok(artifact) => artifact,
+            Err(error) => {
+                let (error_code, message) = classify_dump_error(error);
+                return self.fail_task(record, error_code, message).await;
+            }
+        };
+
+        // dumping → uploading，持久化 size/sha256。
+        let update = StatusTransitionUpdate {
+            size_bytes: Some(artifact.size_bytes),
+            sha256: Some(artifact.sha256.clone()),
+            ..Default::default()
+        };
+        let Some(uploading_record) = self
+            .repository
+            .transition_status(
+                &record.id,
+                BackupStatus::Dumping,
+                BackupStatus::Uploading,
+                update,
+                now,
+            )
+            .await
+            .map_err(repo_error)?
+        else {
+            return Ok(());
+        };
+
+        self.upload_and_verify(
+            &uploading_record,
+            &artifact.path,
+            artifact.size_bytes,
+            &artifact.sha256,
+            now,
+            cancellation,
+        )
+        .await?;
+        let _ = self.dump.cleanup_staging(&record.id).await;
+        Ok(())
+    }
+
+    /// 上传 + 远端校验，内部完成终态迁移。
+    async fn upload_and_verify(
+        &self,
+        record: &BackupRecord,
+        source: &std::path::Path,
+        size_bytes: u64,
+        sha256: &str,
+        now: DateTime<Utc>,
+        cancellation: &CancellationToken,
+    ) -> Result<(), WorkerTaskError> {
+        let settings = self.repository.load_settings().await.map_err(repo_error)?;
+        let Some(config) = BackupStorageConfig::from_settings(&settings) else {
+            return Ok(());
+        };
+        let store = self.object_store.clone();
+        let metadata =
+            BackupObjectMetadata::new(record.id.clone(), sha256.to_owned(), now, size_bytes);
+        if let Err(error) = store
+            .upload_file(
+                &config,
+                UploadObjectRequest {
+                    object_key: record.object_key.clone(),
+                    source: source.to_path_buf(),
+                    metadata,
+                    cancellation: cancellation.clone(),
+                },
+            )
+            .await
+        {
+            let _ = store.delete_object(&config, &record.object_key).await;
+            self.fail_task(
+                record,
+                error.code(),
+                format!("上传到对象存储失败：{}", error.message()),
+            )
+            .await?;
+            return Ok(());
+        }
+
+        match store.head_object(&config, &record.object_key).await {
+            Ok(Some(remote)) if remote.size_bytes == size_bytes && remote.sha256 == sha256 => {
+                if self
+                    .repository
+                    .transition_status(
+                        &record.id,
+                        BackupStatus::Uploading,
+                        BackupStatus::Completed,
+                        StatusTransitionUpdate::default(),
+                        Utc::now(),
+                    )
+                    .await
+                    .map_err(repo_error)?
+                    .is_some()
+                {
+                    info!(
+                        backup_id = %record.id,
+                        size_bytes,
+                        "备份完成"
+                    );
+                }
+            }
+            Ok(Some(remote)) => {
+                let size_matches = remote.size_bytes == size_bytes;
+                let sha256_matches = remote.sha256 == sha256;
+                warn!(
+                    backup_id = %record.id,
+                    expected_size_bytes = size_bytes,
+                    remote_size_bytes = remote.size_bytes,
+                    sha256_matches,
+                    "备份远端对象校验不一致"
+                );
+                let _ = store.delete_object(&config, &record.object_key).await;
+                self.fail_task(
+                    record,
+                    code::REMOTE_VERIFICATION_FAILED,
+                    match (size_matches, sha256_matches) {
+                        (false, true) => "远端对象大小不一致",
+                        (true, false) => "远端对象 sha256 校验值不一致",
+                        (false, false) => "远端对象大小和 sha256 校验值均不一致",
+                        (true, true) => "远端对象校验状态异常",
+                    },
+                )
+                .await?;
+            }
+            Ok(None) => {
+                warn!(backup_id = %record.id, "上传完成后未找到远端对象");
+                self.fail_task(
+                    record,
+                    code::REMOTE_VERIFICATION_FAILED,
+                    "上传完成后未找到远端对象",
+                )
+                .await?;
+            }
+            Err(error) => {
+                let _ = store.delete_object(&config, &record.object_key).await;
+                self.fail_task(
+                    record,
+                    error.code(),
+                    format!("远端对象校验失败：{}", error.message()),
+                )
+                .await?;
+            }
+        }
+        Ok(())
+    }
+
+    /// 把活跃任务写入失败终态并清理暂存。
+    async fn fail_task(
+        &self,
+        record: &BackupRecord,
+        error_code: &'static str,
+        message: impl Into<String>,
+    ) -> Result<(), WorkerTaskError> {
+        let message = message.into();
+        warn!(
+            backup_id = %record.id,
+            error_code,
+            error_message = %message,
+            "备份任务失败"
+        );
+        let now = Utc::now();
+        let update = StatusTransitionUpdate {
+            error_code: Some(error_code.to_string()),
+            error_message: Some(message),
+            completed_at: Some(now),
+            ..Default::default()
+        };
+        let _ = self
+            .repository
+            .transition_status(&record.id, record.status, BackupStatus::Failed, update, now)
+            .await
+            .map_err(repo_error)?;
+        let _ = self.dump.cleanup_staging(&record.id).await;
+        Ok(())
+    }
+
+    /// 执行一小批到期保留清理：先处理 `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 已到期的记录（手动或计划）无条件进入删除。
+        let expired = self
+            .repository
+            .list_expired_records(RETENTION_BATCH_SIZE as u32)
+            .await
+            .map_err(repo_error)?;
+        for record in expired {
+            let Some(record) = self
+                .repository
+                .transition_to_deleting(&record.id, now)
+                .await
+                .map_err(repo_error)?
+            else {
+                continue;
+            };
+            self.finalize_deletion(&record).await?;
+        }
+
+        // 2. 计划备份按 retentionDays / retentionCount 清理。
+        let records = self
+            .repository
+            .list_scheduled_completed_desc(RETENTION_SCAN_LIMIT)
+            .await
+            .map_err(repo_error)?;
+        let decisions = decide_retention(
+            settings.retention_days,
+            settings.retention_count,
+            now,
+            &records,
+        );
+        for decision in decisions.into_iter().take(RETENTION_BATCH_SIZE) {
+            let Some(record) = self
+                .repository
+                .transition_to_deleting(&decision.record_id, now)
+                .await
+                .map_err(repo_error)?
+            else {
+                continue;
+            };
+            self.finalize_deletion(&record).await?;
+        }
+        Ok(())
+    }
+
+    /// 对已进入 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 {
+            return Ok(());
+        };
+        if self
+            .object_store
+            .delete_object(&config, &record.object_key)
+            .await
+            .is_ok()
+        {
+            self.repository
+                .delete_record(&record.id)
+                .await
+                .map_err(repo_error)?;
+        }
+        Ok(())
+    }
+}
+
+fn classify_dump_error(error: BackupError) -> (&'static str, &'static str) {
+    match error.code() {
+        code::CANCELLED => (code::CANCELLED, "备份已取消"),
+        code::STAGING_SPACE_EXHAUSTED => (code::STAGING_SPACE_EXHAUSTED, "暂存磁盘空间不足"),
+        _ => (code::PG_DUMP_FAILED, "数据库导出失败"),
+    }
+}
+
+fn repo_error(error: crate::ports::store::AdminStoreError) -> WorkerTaskError {
+    WorkerTaskError::safe(format!("backup store failed: {error}"))
+}
+
+fn infra_error(error: BackupError) -> WorkerTaskError {
+    WorkerTaskError::safe(error.message())
+}

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

@@ -0,0 +1,304 @@
+//! 容量熔断冻结的恢复编排：到期探测、失败顺延与自适应并发下调。
+//!
+//! 冻结事实保存在可丢失的 Redis 冷却中，本服务只组合 Admin 端口：
+//! 观测（`AccountRuntimeStore`）、探测（`AccountsService`）与写回
+//! （原子降低并发 / 按冻结代次结束探测）。旧观测不会覆盖管理员操作。
+
+use std::collections::BTreeMap;
+use std::sync::Arc;
+use std::time::{Duration, SystemTime};
+
+use chrono::{DateTime, Utc};
+use futures::StreamExt as _;
+use gateway_core::account::{AccountConcurrencyLimit, ProviderAccountId};
+use gateway_core::routing::UpstreamModelId;
+use gateway_core::task::{ScheduledTask, WorkerCycleContext, WorkerTaskError};
+use tracing::warn;
+
+use crate::model::accounts::{
+    AccountConnectionTestEvent, AccountFreeze, AccountPageItem, AccountRuntimeSnapshot,
+};
+use crate::model::{MutationActor, MutationContext};
+use crate::ports::store::{AccountRuntimeStore, AccountStore, SettingsStore};
+use crate::use_case::accounts::AccountsService;
+
+/// 自适应并发下调保留系数：下调到观测在途峰值的 80%。
+const ADAPTIVE_CONCURRENCY_FACTOR: f64 = 0.8;
+/// 自适应并发下限：过低的并发让账号几乎不可用，宁可保持冻结。
+const ADAPTIVE_CONCURRENCY_FLOOR: u32 = 2;
+/// 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；账号并发更新审计由此溯源到自动冻结编排。
+const SYSTEM_REQUEST_ID: &str = "account-freeze-recovery";
+
+/// 冻结恢复所需的管理端口组合。
+#[derive(Clone)]
+pub struct FreezeRecoveryDeps {
+    pub accounts: Arc<dyn AccountsService>,
+    pub store: Arc<dyn AccountStore>,
+    pub runtime: Arc<dyn AccountRuntimeStore>,
+    pub settings: Arc<dyn SettingsStore>,
+}
+
+pub struct FreezeRecoveryTask {
+    deps: FreezeRecoveryDeps,
+}
+
+impl FreezeRecoveryTask {
+    pub fn new(deps: FreezeRecoveryDeps) -> Self {
+        Self { deps }
+    }
+
+    fn system_context() -> MutationContext {
+        MutationContext {
+            actor: MutationActor::System,
+            request_id: SYSTEM_REQUEST_ID.to_owned(),
+        }
+    }
+
+    /// 读取冻结策略；读取或校验失败跳过本轮，不能把未知配置当作允许解冻。
+    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,
+        )
+        .ok()
+    }
+
+    async fn active_freezes(&self) -> BTreeMap<String, AccountFreeze> {
+        self.deps.runtime.active_freezes().await.unwrap_or_default()
+    }
+
+    async fn run_cycle_inner(&self) {
+        let Some(policy) = self.freeze_policy().await else {
+            return;
+        };
+        let freezes = self.active_freezes().await;
+        if freezes.is_empty() {
+            return;
+        }
+        if policy.enabled() && policy.adaptive_concurrency() {
+            self.adapt_concurrency_limits(&freezes, &policy).await;
+        }
+        self.recover_due_freezes(&freezes, &policy).await;
+    }
+
+    /// 对冻结中的账号执行自适应并发下调：目标为观测在途峰值的 80%（下限 2），
+    /// 只降不升；未观测到峰值证据的账号保持现状。
+    async fn adapt_concurrency_limits(
+        &self,
+        freezes: &BTreeMap<String, AccountFreeze>,
+        policy: &gateway_core::provider_ports::ProviderFreezePolicy,
+    ) {
+        let account_ids = freezes.keys().cloned().collect::<Vec<_>>();
+        let Ok(peaks) = self.deps.runtime.capacity_peaks(&account_ids).await else {
+            return;
+        };
+        for (account_id, peak) in peaks {
+            let Some(target) = adaptive_target(peak) else {
+                continue;
+            };
+            let Ok(account) = ProviderAccountId::new(account_id.clone()) else {
+                continue;
+            };
+            let Some(limit) = AccountConcurrencyLimit::new(target) else {
+                continue;
+            };
+            match self
+                .deps
+                .accounts
+                .lower_concurrency_limit(&Self::system_context(), account, limit)
+                .await
+            {
+                Ok(Some(_)) => {
+                    tracing::info!(
+                        account_id,
+                        adapted_limit = target,
+                        freeze_seconds = policy.freeze_duration().as_secs(),
+                        "容量熔断：按观测在途峰值下调账号并发上限",
+                    );
+                }
+                Ok(None) => {}
+                Err(error) => {
+                    warn!(account_id, error = %error, "自适应并发下调失败");
+                }
+            }
+        }
+    }
+
+    async fn load_account(&self, account_id: &str) -> Option<Option<AccountPageItem>> {
+        let account_id = ProviderAccountId::new(account_id.to_owned()).ok()?;
+        self.deps
+            .store
+            .load_account(account_id.as_str(), AccountRuntimeSnapshot::default())
+            .await
+            .ok()
+    }
+
+    /// 到达探测时间后才恢复；关闭自动冻结或探测时，已有冻结仍等待原冷却结束。
+    async fn recover_due_freezes(
+        &self,
+        freezes: &BTreeMap<String, AccountFreeze>,
+        policy: &gateway_core::provider_ports::ProviderFreezePolicy,
+    ) {
+        for (account_id, freeze) in freezes {
+            if freeze.until > Utc::now() {
+                continue;
+            }
+            if policy.enabled() && policy.probe_enabled() && freeze.requires_probe {
+                self.probe_and_recover(account_id, freeze, policy).await;
+            } else if let Err(error) = self
+                .deps
+                .runtime
+                .finish_freeze(account_id, freeze, None)
+                .await
+            {
+                warn!(account_id, error = %error, "解除到期冻结失败");
+            }
+        }
+    }
+
+    async fn probe_and_recover(
+        &self,
+        account_id: &str,
+        freeze: &AccountFreeze,
+        policy: &gateway_core::provider_ports::ProviderFreezePolicy,
+    ) {
+        let Some(Some(item)) = self.load_account(account_id).await else {
+            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;
+        };
+        let probe_succeeded = match self
+            .deps
+            .accounts
+            .test_connection(account.clone(), model)
+            .await
+        {
+            Ok(events) => drain_probe(events).await,
+            Err(error) => {
+                tracing::debug!(account_id, error = %error, "冻结恢复探测发起失败");
+                false
+            }
+        };
+        if probe_succeeded {
+            match self
+                .deps
+                .runtime
+                .finish_freeze(account_id, freeze, None)
+                .await
+            {
+                Ok(true) => tracing::info!(account_id, "冻结恢复探测成功：账号已解冻"),
+                Ok(false) => {}
+                Err(error) => warn!(account_id, error = %error, "解除冻结失败"),
+            }
+        } else {
+            self.postpone(&account, freeze, policy).await;
+        }
+    }
+
+    /// 探测失败只顺延本次仍存在的冻结，旧探测不能重新冻结已手动恢复的账号。
+    async fn postpone(
+        &self,
+        account: &ProviderAccountId,
+        freeze: &AccountFreeze,
+        policy: &gateway_core::provider_ports::ProviderFreezePolicy,
+    ) {
+        let Some(until) = SystemTime::now().checked_add(policy.freeze_duration()) else {
+            return;
+        };
+        let until = DateTime::<Utc>::from(until);
+        match self
+            .deps
+            .runtime
+            .finish_freeze(account.as_str(), freeze, Some(until))
+            .await
+        {
+            Ok(true) => {
+                tracing::info!(
+                    account_id = account.as_str(),
+                    postpone_seconds = policy.freeze_duration().as_secs(),
+                    "冻结恢复探测失败：账号冻结顺延",
+                );
+            }
+            Ok(false) => {}
+            Err(error) => {
+                warn!(
+                    account_id = account.as_str(),
+                    error = %error,
+                    "冻结顺延失败"
+                );
+            }
+        }
+    }
+
+    async fn resolve_probe_model(
+        &self,
+        account: &ProviderAccountId,
+        policy: &gateway_core::provider_ports::ProviderFreezePolicy,
+    ) -> Option<UpstreamModelId> {
+        if let Some(model) = policy.probe_model() {
+            return UpstreamModelId::new(model.to_owned()).ok();
+        }
+        let models = self.deps.accounts.models(account, false).await.ok()?;
+        models.models.into_iter().next().map(|model| model.id)
+    }
+}
+
+impl ScheduledTask for FreezeRecoveryTask {
+    fn run_cycle(
+        &self,
+        context: WorkerCycleContext,
+    ) -> futures::future::BoxFuture<'_, Result<(), WorkerTaskError>> {
+        Box::pin(async move {
+            if context.cancellation().is_cancelled() {
+                return Ok(());
+            }
+            self.run_cycle_inner().await;
+            Ok(())
+        })
+    }
+}
+
+/// 自适应目标并发：观测峰值 × 0.8 向下取整，下限 2；无证据（峰值为 0）不调整。
+fn adaptive_target(peak_in_flight: u32) -> Option<u32> {
+    if peak_in_flight == 0 {
+        return None;
+    }
+    let scaled = (f64::from(peak_in_flight) * ADAPTIVE_CONCURRENCY_FACTOR).floor() as u32;
+    Some(scaled.max(ADAPTIVE_CONCURRENCY_FLOOR))
+}
+
+/// 消耗连接测试事件流并返回是否以 `Completed` 终止。
+async fn drain_probe(mut events: crate::model::accounts::AccountConnectionTestEventStream) -> bool {
+    let mut completed = false;
+    while let Some(event) = events.next().await {
+        match event {
+            AccountConnectionTestEvent::Completed => completed = true,
+            AccountConnectionTestEvent::Failed { .. } => return false,
+            _ => {}
+        }
+    }
+    completed
+}

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

@@ -0,0 +1,599 @@
+//! 管理控制面的语义模型、用例与外部能力端口。
+//!
+//! 本 crate 不包含 HTTP wire、数据库实现或具体 Provider 实现。
+
+use std::{fmt, path::Path, sync::Arc, time::Duration};
+
+use gateway_core::{
+    engine::execution::ClientKeyVerifier,
+    engine::probe::AccountProbe,
+    runtime::SnapshotControl,
+    task::{
+        DaemonRestartPolicy, WorkerContribution, WorkerId, WorkerKind, WorkerLeaseRequest,
+        WorkerRegistration, WorkerRunnable, WorkerSchedule,
+    },
+};
+use secrecy::{ExposeSecret as _, SecretString};
+use serde::Deserialize;
+
+pub mod backup;
+pub mod freeze_recovery;
+pub mod model;
+pub mod ports;
+mod use_case;
+pub use use_case::plugins::{PluginDistributionPorts, PluginManagementService, PluginsService};
+
+pub use use_case::key_usage::KeyUsageService;
+
+pub use use_case::{
+    account_groups::AccountGroupService,
+    accounts::AccountsService,
+    auth::AuthService,
+    backup::BackupService,
+    client_distribution::ClientDistributionService,
+    client_keys::ClientKeyService,
+    credentials::{CredentialsService, ProviderCredentials},
+    import_tasks::ImportTasksService,
+    observability::ObservabilityService,
+    proxies::ProxiesService,
+    settings::SettingsService,
+    system::SystemService,
+};
+
+use model::AdminError;
+use ports::{
+    client_distribution::ClientDistributionResolver, plugin_accounts::PluginAccountAccess,
+    plugin_client_keys::PluginClientKeyAccess, provider::ProviderAdminRegistry,
+    store::AdminStorePorts, system::SystemOperations,
+};
+use use_case::{
+    account_groups::DefaultAccountGroupService, accounts::DefaultAccountsService,
+    auth::DefaultAuthService, backup::DefaultBackupService,
+    client_distribution::DefaultClientDistributionService, client_keys::DefaultClientKeyService,
+    observability::DefaultObservabilityService, settings::DefaultSettingsService,
+    system::DefaultSystemService,
+};
+
+const MINIMUM_INITIAL_PASSWORD_BYTES: usize = 12;
+const WEAK_ADMIN_PASSWORDS: &[&str] = &[
+    "",
+    "admin",
+    "123456",
+    "password",
+    "changeme",
+    "change-me",
+    "replace-me",
+    "codex-proxy-rs",
+];
+
+const BACKUP_WORKER_OWNER: &str = "backup";
+const DEFAULT_CLIENT_SESSION_TTL_MINUTES: u64 = 24 * 60;
+
+/// 只用于首次幂等创建默认管理员的启动密码。
+#[derive(Clone, Deserialize)]
+#[serde(transparent)]
+pub struct InitialAdminPassword(SecretString);
+
+impl InitialAdminPassword {
+    #[must_use]
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(SecretString::from(value.into()))
+    }
+
+    fn expose(&self) -> &str {
+        self.0.expose_secret()
+    }
+}
+
+impl PartialEq for InitialAdminPassword {
+    fn eq(&self, other: &Self) -> bool {
+        self.expose() == other.expose()
+    }
+}
+
+impl Eq for InitialAdminPassword {}
+
+impl fmt::Debug for InitialAdminPassword {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("InitialAdminPassword([REDACTED])")
+    }
+}
+
+/// 管理控制面的启动配置。
+#[derive(Clone, Deserialize, PartialEq, Eq)]
+pub struct AdminConfig {
+    pub session_ttl_minutes: u64,
+    pub default_username: String,
+    pub default_password: InitialAdminPassword,
+}
+
+/// Client 登录域的通用启动配置。
+#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
+pub struct ClientConfig {
+    pub session_ttl_minutes: u64,
+}
+
+impl Default for ClientConfig {
+    fn default() -> Self {
+        Self {
+            session_ttl_minutes: DEFAULT_CLIENT_SESSION_TTL_MINUTES,
+        }
+    }
+}
+
+impl ClientConfig {
+    /// 校验 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"));
+        }
+        Ok(())
+    }
+}
+
+impl AdminConfig {
+    /// 校验 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)
+        {
+            return Err(AdminConfigError::InvalidField("admin.default_username"));
+        }
+        if self.session_ttl_minutes == 0 || i64::try_from(self.session_ttl_minutes).is_err() {
+            return Err(AdminConfigError::InvalidField("admin.session_ttl_minutes"));
+        }
+        let password = self.default_password.expose().trim();
+        if password.len() < MINIMUM_INITIAL_PASSWORD_BYTES
+            || password.contains('$')
+            || WEAK_ADMIN_PASSWORDS.contains(&password.to_ascii_lowercase().as_str())
+        {
+            return Err(AdminConfigError::WeakInitialPassword);
+        }
+        Ok(())
+    }
+}
+
+impl fmt::Debug for AdminConfig {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("AdminConfig")
+            .field("session_ttl_minutes", &self.session_ttl_minutes)
+            .field("default_username", &self.default_username)
+            .field("default_password", &"[REDACTED]")
+            .finish()
+    }
+}
+
+/// Admin-owned 启动配置错误；不回显任何配置值。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+pub enum AdminConfigError {
+    #[error("配置字段 `{0}` 不合法")]
+    InvalidField(&'static str),
+    #[error("admin.default_password 不符合初始密码策略")]
+    WeakInitialPassword,
+}
+
+/// API 持有的管理资源能力集合。
+///
+/// 字段全部私有；调用方经 accessor 直接调用能力，不需要命名内部 `use_case` 模块。
+#[derive(Clone)]
+pub struct AdminServices {
+    plugins: Arc<PluginsService>,
+    plugin_management: Arc<PluginManagementService>,
+    proxies: Arc<dyn ProxiesService>,
+    auth: Arc<dyn AuthService>,
+    key_usage: Arc<dyn KeyUsageService>,
+    accounts: Arc<dyn AccountsService>,
+    account_groups: Arc<dyn AccountGroupService>,
+    client_keys: Arc<dyn ClientKeyService>,
+    client_distribution: Arc<dyn ClientDistributionService>,
+    observability: Arc<dyn ObservabilityService>,
+    settings: Arc<dyn SettingsService>,
+    system: Arc<dyn SystemService>,
+    credentials: Arc<CredentialsService>,
+    plugin_accounts: Arc<dyn PluginAccountAccess>,
+    backups: Arc<dyn BackupService>,
+    import_tasks: Arc<dyn ImportTasksService>,
+}
+
+impl AdminServices {
+    #[must_use]
+    pub fn plugin_management(&self) -> &PluginManagementService {
+        &self.plugin_management
+    }
+
+    #[must_use]
+    pub fn plugins(&self) -> &PluginsService {
+        &self.plugins
+    }
+
+    #[must_use]
+    pub fn import_tasks(&self) -> &dyn ImportTasksService {
+        self.import_tasks.as_ref()
+    }
+
+    #[must_use]
+    pub fn key_usage(&self) -> &dyn KeyUsageService {
+        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()
+    }
+
+    #[must_use]
+    pub fn auth(&self) -> &dyn AuthService {
+        self.auth.as_ref()
+    }
+
+    #[must_use]
+    pub fn accounts(&self) -> &dyn AccountsService {
+        self.accounts.as_ref()
+    }
+
+    #[must_use]
+    pub fn account_groups(&self) -> &dyn AccountGroupService {
+        self.account_groups.as_ref()
+    }
+
+    #[must_use]
+    pub fn client_keys(&self) -> &dyn ClientKeyService {
+        self.client_keys.as_ref()
+    }
+
+    #[must_use]
+    pub fn client_distribution(&self) -> &dyn ClientDistributionService {
+        self.client_distribution.as_ref()
+    }
+
+    #[must_use]
+    pub fn observability(&self) -> &dyn ObservabilityService {
+        self.observability.as_ref()
+    }
+
+    #[must_use]
+    pub fn settings(&self) -> &dyn SettingsService {
+        self.settings.as_ref()
+    }
+
+    #[must_use]
+    pub fn system(&self) -> &dyn SystemService {
+        self.system.as_ref()
+    }
+
+    #[must_use]
+    pub fn credentials(&self) -> &CredentialsService {
+        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 初始化完成后的封闭能力包。
+pub struct AdminBundle {
+    services: AdminServices,
+    worker_contributions: Vec<WorkerContribution>,
+}
+
+impl AdminBundle {
+    #[must_use]
+    pub fn services(&self) -> AdminServices {
+        self.services.clone()
+    }
+
+    /// 取出 Admin Worker 贡献；只能调用一次，与其它 Bundle 的贡献一并交给 Host。
+    pub fn take_worker_contributions(&mut self) -> Vec<WorkerContribution> {
+        std::mem::take(&mut self.worker_contributions)
+    }
+}
+
+/// 组合根提供给控制面的运行能力；与配置和存储端口分别传入。
+pub struct AdminRuntimePorts {
+    pub plugin_preparation: Arc<dyn ports::plugins::PluginPreparation>,
+    pub plugin_management: Arc<dyn ports::plugin_management::PluginManagement>,
+    pub published_snapshot: gateway_core::runtime::RuntimeSnapshotHandle,
+    pub plugin_distribution: Arc<dyn ports::plugins::PluginDistribution>,
+    pub plugin_inspector: Arc<dyn ports::plugins::PluginPackageInspector>,
+    pub pricing_source: Arc<dyn ports::pricing::PricingSource>,
+    pub providers: ProviderAdminRegistry,
+    pub snapshot: Arc<dyn SnapshotControl>,
+    pub account_probe: Arc<dyn AccountProbe>,
+    pub proxy_probe: Arc<dyn ports::proxy::ProxyProbe>,
+    pub client_distribution: Arc<dyn ClientDistributionResolver>,
+    pub system: Arc<dyn SystemOperations>,
+    pub client_key_verifier: Arc<dyn ClientKeyVerifier>,
+}
+
+/// 校验配置、接入已组装的 Provider 注册表并完成默认管理员幂等初始化。
+///
+/// # Errors
+///
+/// 配置非法或默认管理员初始化失败时返回错误。
+pub async fn initialize(
+    config: AdminConfig,
+    client_config: ClientConfig,
+    store: AdminStorePorts,
+    runtime: AdminRuntimePorts,
+) -> Result<AdminBundle, AdminError> {
+    initialize_inner(config, client_config, store, runtime, None).await
+}
+
+/// 使用组合根已绑定给 Runtime 的同一账号窄端口，避免为完整 Admin 重建第二实例。
+pub async fn initialize_with_plugin_accounts(
+    config: AdminConfig,
+    client_config: ClientConfig,
+    store: AdminStorePorts,
+    runtime: AdminRuntimePorts,
+    plugin_accounts: Arc<dyn PluginAccountAccess>,
+) -> Result<AdminBundle, AdminError> {
+    initialize_inner(config, client_config, store, runtime, Some(plugin_accounts)).await
+}
+
+async fn initialize_inner(
+    mut config: AdminConfig,
+    mut client_config: ClientConfig,
+    store: AdminStorePorts,
+    runtime: AdminRuntimePorts,
+    plugin_accounts: Option<Arc<dyn PluginAccountAccess>>,
+) -> Result<AdminBundle, AdminError> {
+    let AdminRuntimePorts {
+        plugin_preparation,
+        plugin_management,
+        published_snapshot,
+        plugin_distribution,
+        plugin_inspector,
+        pricing_source,
+        providers,
+        snapshot,
+        account_probe: probe,
+        proxy_probe,
+        client_distribution,
+        system,
+        client_key_verifier,
+    } = runtime;
+    config
+        .resolve_and_validate(Path::new("."))
+        .map_err(|error| AdminError::invalid(error.to_string()))?;
+    client_config
+        .resolve_and_validate(Path::new("."))
+        .map_err(|error| AdminError::invalid(error.to_string()))?;
+    let registry = providers;
+
+    let auth = Arc::new(DefaultAuthService::new(
+        config.default_username,
+        config.session_ttl_minutes,
+        client_config.session_ttl_minutes,
+        store.auth(),
+        client_key_verifier.clone(),
+    ));
+    auth.ensure_default_admin(config.default_password.expose())
+        .await?;
+
+    let accounts = Arc::new(DefaultAccountsService::new(
+        store.accounts(),
+        store.account_runtime(),
+        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(),
+    ));
+    let backup_task = backup::task::BackupTask::new(
+        backup_ports.repository(),
+        backup_ports.dump(),
+        backup_ports.object_store(),
+    );
+    let system_preflight = Arc::new(use_case::plugin_update::PluginSystemUpdatePreflight::new(
+        store.plugins(),
+        plugin_inspector.clone(),
+    ));
+    let system = Arc::new(DefaultSystemService::new(system, system_preflight));
+    let key_usage = Arc::new(use_case::key_usage::DefaultKeyUsageService::new(
+        auth.clone(),
+        client_key_verifier,
+        store.client_keys(),
+        store.observability(),
+        system.clone(),
+    ));
+    let credentials = Arc::new(CredentialsService::new(
+        registry.clone(),
+        store.accounts(),
+        store.proxies(),
+        snapshot.clone(),
+    ));
+    let plugin_accounts = plugin_accounts.unwrap_or_else(|| {
+        initialize_plugin_accounts(registry.clone(), store.accounts(), snapshot.clone())
+    });
+    let import_tasks = use_case::import_tasks::DefaultImportTasksService::new(credentials.clone());
+    let import_task = use_case::import_tasks::ImportTaskWorker(import_tasks.clone());
+    let services = AdminServices {
+        plugin_management: Arc::new(PluginManagementService::new(
+            plugin_management,
+            store.plugins(),
+            published_snapshot.clone(),
+        )),
+        plugins: Arc::new(PluginsService::new(
+            store.plugins(),
+            plugin_inspector,
+            PluginDistributionPorts::new(plugin_distribution, store.proxies()),
+            snapshot.clone(),
+            plugin_preparation,
+            published_snapshot,
+            store.plugin_state(),
+        )),
+        key_usage,
+        proxies: Arc::new(use_case::proxies::DefaultProxiesService::new(
+            store.proxies(),
+            proxy_probe,
+            snapshot.clone(),
+            registry.clone(),
+        )),
+        auth,
+        accounts: accounts.clone(),
+        account_groups: Arc::new(DefaultAccountGroupService::new(
+            store.account_groups(),
+            store.account_runtime(),
+            snapshot.clone(),
+        )),
+        client_keys: Arc::new(DefaultClientKeyService::new(
+            store.client_keys(),
+            snapshot.clone(),
+            registry.clone(),
+        )),
+        client_distribution: Arc::new(DefaultClientDistributionService::new(client_distribution)),
+        observability: Arc::new(DefaultObservabilityService::new(
+            store.observability(),
+            store.accounts(),
+            store.settings(),
+            registry.clone(),
+        )),
+        settings: Arc::new(DefaultSettingsService::new(
+            store.settings(),
+            snapshot.clone(),
+            registry,
+            pricing_source,
+        )),
+        system,
+        credentials,
+        plugin_accounts,
+        import_tasks,
+        backups,
+    };
+    let freeze_recovery =
+        freeze_recovery::FreezeRecoveryTask::new(freeze_recovery::FreezeRecoveryDeps {
+            accounts: Arc::clone(&accounts) as Arc<dyn AccountsService>,
+            store: store.accounts(),
+            runtime: store.account_runtime(),
+            settings: store.settings(),
+        });
+    let mut worker_contributions = backup_worker_contribution(backup_task)?;
+    let id = WorkerId::try_new(WorkerKind::AccountImport, "admin")
+        .map_err(|_| AdminError::internal("导入 Worker ID 不合法"))?;
+    let restart = DaemonRestartPolicy::try_new(Duration::from_secs(1), Duration::from_secs(60))
+        .map_err(|_| AdminError::internal("导入 Worker 重启策略不合法"))?;
+    let registration = WorkerRegistration::try_new(
+        id,
+        WorkerRunnable::Daemon {
+            restart,
+            task: Box::new(import_task),
+        },
+    )
+    .map_err(|_| AdminError::internal("导入 Worker 注册信息不合法"))?;
+    worker_contributions.push(WorkerContribution::Registration(registration));
+    worker_contributions.extend(freeze_recovery_worker_contribution(freeze_recovery)?);
+    Ok(AdminBundle {
+        services,
+        worker_contributions,
+    })
+}
+
+/// CLI 只组合账号用例，不初始化管理员、管理服务或后台任务；写入仍复用同一事务与审计。
+pub fn initialize_plugin_accounts(
+    providers: ports::provider::ProviderAdminRegistry,
+    accounts: Arc<dyn ports::store::AccountStore>,
+    snapshot: Arc<dyn gateway_core::runtime::SnapshotControl>,
+) -> Arc<dyn PluginAccountAccess> {
+    Arc::new(use_case::plugin_accounts::DefaultPluginAccountAccess::new(
+        providers, accounts, snapshot,
+    ))
+}
+
+/// 为 Runtime 创建只暴露非秘密 Client Key 目录的窄端口。
+#[must_use]
+pub fn initialize_plugin_client_keys(
+    providers: ports::provider::ProviderAdminRegistry,
+    store: Arc<dyn ports::store::ClientKeyStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+) -> Arc<dyn PluginClientKeyAccess> {
+    let service: Arc<dyn ClientKeyService> =
+        Arc::new(DefaultClientKeyService::new(store, snapshot, providers));
+    Arc::new(use_case::plugin_client_keys::DefaultPluginClientKeyAccess::new(service))
+}
+
+/// 为 Runtime 组合实例自有资源写入；权限和归属在同一存储事务复核。
+#[must_use]
+pub fn initialize_plugin_resources(
+    store: Arc<dyn ports::plugin_resources::PluginResourceStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+) -> Arc<dyn ports::plugin_resources::PluginResourceAccess> {
+    Arc::new(use_case::plugin_resources::DefaultPluginResourceAccess { store, snapshot })
+}
+
+/// Backup Worker 注册：单个可取消 Daemon，owner 固定为 `backup`。
+fn backup_worker_contribution(
+    task: backup::task::BackupTask,
+) -> Result<Vec<WorkerContribution>, AdminError> {
+    let id = WorkerId::try_new(WorkerKind::Backup, BACKUP_WORKER_OWNER)
+        .map_err(|_| AdminError::internal("备份 Worker ID 不合法"))?;
+    let restart = DaemonRestartPolicy::try_new(Duration::from_secs(1), Duration::from_secs(60))
+        .map_err(|_| AdminError::internal("备份 Worker 重启策略不合法"))?;
+    let registration = WorkerRegistration::try_new(
+        id,
+        WorkerRunnable::Daemon {
+            restart,
+            task: Box::new(task),
+        },
+    )
+    .map_err(|_| AdminError::internal("备份 Worker 注册信息不合法"))?;
+    Ok(vec![WorkerContribution::Registration(registration)])
+}
+
+/// 冻结恢复 Worker 注册：按固定周期扫描活跃冻结，owner 固定。
+fn freeze_recovery_worker_contribution(
+    task: freeze_recovery::FreezeRecoveryTask,
+) -> Result<Vec<WorkerContribution>, AdminError> {
+    let id = WorkerId::try_new(
+        WorkerKind::AccountFreezeRecovery,
+        freeze_recovery::FREEZE_RECOVERY_WORKER_OWNER,
+    )
+    .map_err(|_| AdminError::internal("冻结恢复 Worker ID 不合法"))?;
+    let schedule = WorkerSchedule::try_new(
+        freeze_recovery::FREEZE_RECOVERY_INTERVAL,
+        freeze_recovery::WORKER_INITIAL_BACKOFF,
+        freeze_recovery::WORKER_MAXIMUM_BACKOFF,
+        freeze_recovery::WORKER_LEASE_TTL,
+        freeze_recovery::WORKER_LEASE_RENEWAL,
+    )
+    .map_err(|_| AdminError::internal("冻结恢复 Worker 调度配置不合法"))?;
+    let lease = WorkerLeaseRequest::try_new(id.clone(), freeze_recovery::WORKER_LEASE_TTL)
+        .map_err(|_| AdminError::internal("冻结恢复 Worker 租约配置不合法"))?;
+    let registration = WorkerRegistration::try_new(
+        id,
+        WorkerRunnable::Scheduled {
+            schedule,
+            lease: Some(lease),
+            task: Box::new(task),
+        },
+    )
+    .map_err(|_| AdminError::internal("冻结恢复 Worker 注册信息不合法"))?;
+    Ok(vec![WorkerContribution::Registration(registration)])
+}

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

@@ -0,0 +1,157 @@
+//! Provider-neutral account group commands and projections.
+
+use std::collections::BTreeMap;
+
+use chrono::{DateTime, Utc};
+use gateway_core::{account::AccountStatusFacts, routing::AccountGroupId};
+
+use super::{PageSize, Revision, observability::DecimalAmount};
+
+/// Canonical `#RRGGBBAA` color persisted with an account group.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupColor(String);
+
+impl AccountGroupColor {
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    #[must_use]
+    pub fn parse(value: &str) -> Option<Self> {
+        (value.len() == 9
+            && value.starts_with('#')
+            && value[1..].bytes().all(|byte| byte.is_ascii_hexdigit()))
+        .then(|| Self(value.to_ascii_uppercase()))
+    }
+}
+
+/// Group member availability at the current observation time.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AccountGroupAccountSummary {
+    pub available: u64,
+    pub limited: u64,
+    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` 表示可用账号中存在不限制并发的账号。
+    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 快照归属的累计成本。
+    pub retained_total_usd: DecimalAmount,
+}
+
+/// 当前页账号组 membership 对应的持久账号事实；运行态在 Admin query service 合并。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupMemberFact {
+    pub group_id: AccountGroupId,
+    pub account_id: String,
+    pub status: AccountStatusFacts,
+    pub total_slots: Option<u64>,
+}
+
+/// Lightweight group reference embedded in account and client-key views.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupRef {
+    pub id: AccountGroupId,
+    pub name: String,
+    pub color: AccountGroupColor,
+    pub enabled: bool,
+}
+
+/// Account group list query.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupListQuery {
+    pub page: u32,
+    pub page_size: PageSize,
+    pub search: Option<String>,
+    pub enabled: Option<bool>,
+}
+
+/// Complete account group summary.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupRecord {
+    pub disable_fast: bool,
+    pub id: AccountGroupId,
+    pub name: String,
+    pub description: Option<String>,
+    pub color: AccountGroupColor,
+    pub enabled: bool,
+    pub member_count: u64,
+    pub provider_counts: BTreeMap<String, u64>,
+    pub client_key_count: u64,
+    pub account_summary: AccountGroupAccountSummary,
+    pub capacity: AccountGroupCapacity,
+    pub usage: AccountGroupUsage,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// Paginated account groups.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupPage {
+    pub config_revision: Revision,
+    pub items: Vec<AccountGroupRecord>,
+    pub total: u64,
+    pub page: u32,
+    pub page_size: u16,
+}
+
+/// Create an account group.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CreateAccountGroup {
+    pub disable_fast: bool,
+    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 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 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.
+#[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,
+    pub id: AccountGroupId,
+    pub record: Option<AccountGroupRecord>,
+}

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

@@ -0,0 +1,318 @@
+//! 多 Provider 账号目录与连接测试的公共事实。
+
+use std::{collections::BTreeMap, pin::Pin};
+
+use chrono::{DateTime, Utc};
+use futures::Stream;
+
+use gateway_core::{
+    engine::probe::AccountProbeErrorSource, error::GatewayErrorKind, routing::ProviderKind,
+    upstream::UpstreamSendState,
+};
+
+use super::{PageSize, Revision, account_groups::AccountGroupRef, observability::TimeRange};
+
+pub use gateway_core::account::{
+    AccountConcurrencyLimit, AccountErrorReason, AccountStatus, AccountStatusFacts,
+    AccountStatusProjection, AccountWeight, CredentialState, QuotaAccessState, QuotaEvidence,
+    QuotaState, resolve_account_status,
+};
+
+/// 账号可用的管理操作。
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub struct ProviderAccountCapabilities {
+    pub quota: bool,
+    pub quota_refresh: bool,
+    pub profile: bool,
+    pub subscription: bool,
+    pub avatar: bool,
+    pub reset_credits: bool,
+    pub consume_reset_credit: bool,
+}
+
+/// 导入时统一应用的账号备注、调度与分组设置；缺省时保留原有导入语义。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountImportSettings {
+    pub notes: Option<String>,
+    pub enabled: bool,
+    pub concurrency_limit: Option<AccountConcurrencyLimit>,
+    pub weight: AccountWeight,
+    pub model_access: Option<gateway_core::account::AccountModelAccess>,
+    pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
+}
+
+/// 账号列表排序字段。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AccountSortField {
+    Email,
+    Status,
+    PlanType,
+    Usage,
+    LastUsedAt,
+    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,
+    pub page_size: PageSize,
+    pub provider_kind: Option<ProviderKind>,
+    pub group_filter: Option<AccountGroupFilter>,
+    pub search: Option<String>,
+    pub status: Option<AccountStatus>,
+    pub sort: Option<AccountSort>,
+}
+
+/// Admin query service 从运行态存储取得的当前账号冷却快照。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct AccountRuntimeSnapshot {
+    pub cooldown: BTreeMap<String, gateway_core::account::AccountCooldown>,
+    /// `None` 表示实时 lease 存储不可用；`Some` 中未出现的账号当前使用量为零。
+    pub in_flight: Option<BTreeMap<String, u64>>,
+}
+
+/// 恢复任务读取的冻结快照；generation 将异步结果绑定到本次冻结。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountFreeze {
+    pub credential_revision: Revision,
+    pub until: DateTime<Utc>,
+    pub generation: String,
+    pub requires_probe: bool,
+}
+
+/// Optional account membership filter.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AccountGroupFilter {
+    Group(gateway_core::routing::AccountGroupId),
+    Ungrouped,
+}
+
+/// 账号公共存储投影；Provider 专属字段不进入此结构。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountRecord {
+    pub id: String,
+    pub provider_kind: ProviderKind,
+    pub groups: Vec<AccountGroupRef>,
+    pub name: String,
+    pub notes: Option<String>,
+    pub email: Option<String>,
+    pub upstream_user_id: Option<String>,
+    pub upstream_account_id: Option<String>,
+    pub plan_type: Option<String>,
+    pub authentication_kind: String,
+    pub credential_revision: Revision,
+    pub has_refresh_token: bool,
+    pub access_token_expires_at: Option<DateTime<Utc>>,
+    pub next_refresh_at: Option<DateTime<Utc>>,
+    pub enabled: bool,
+    pub concurrency_limit: Option<AccountConcurrencyLimit>,
+    pub weight: AccountWeight,
+    pub model_access: gateway_core::account::AccountModelAccess,
+    pub outbound_proxy: Option<gateway_core::account::OutboundProxy>,
+    pub credential_state: CredentialState,
+    pub credential_observed_at: DateTime<Utc>,
+    pub quota: QuotaState,
+    pub last_error_reason: Option<AccountErrorReason>,
+    pub last_error_message: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// 单一货币的账号成本聚合。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountCost {
+    pub currency: String,
+    pub amount: super::observability::DecimalAmount,
+}
+
+/// 账号在一个模型上的历史用量。
+#[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>,
+}
+
+/// 账号在一个小时窗口内的请求数。
+#[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,
+    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: Option<DateTime<Utc>>,
+    pub request_buckets: Vec<AccountRequestBucket>,
+    pub models: Vec<AccountModelUsage>,
+}
+
+/// 某个账号在调用方指定时间窗口内的本地用量查询。
+///
+/// `key` 只用于把聚合结果关联回调用方的窗口，不承载 Provider 私有语义。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountUsageWindowQuery {
+    pub account_id: String,
+    pub key: String,
+    pub range: TimeRange,
+}
+
+/// 一个账号时间窗口用量查询的结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountUsageWindowResult {
+    pub account_id: String,
+    pub key: String,
+    pub usage: AccountUsage,
+}
+
+/// 账号列表页所需的完整存储事实。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountPage {
+    pub config_revision: Revision,
+    pub items: Vec<AccountPageItem>,
+    pub total: u64,
+    pub summary: AccountSummary,
+}
+
+/// 同一状态快照下的账号事实与唯一状态投影。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountPageItem {
+    pub account: AccountRecord,
+    pub projection: AccountStatusProjection,
+}
+
+/// 统一账号目录的全局状态计数，不受当前筛选和分页影响。
+///
+/// 计数与 [`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>,
+    pub weight: AccountWeight,
+    pub model_access: Option<gateway_core::account::AccountModelAccess>,
+    pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
+    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>,
+    pub enabled: Option<bool>,
+    pub concurrency_limit: Option<Option<AccountConcurrencyLimit>>,
+    pub weight: Option<AccountWeight>,
+    pub model_access: Option<gateway_core::account::AccountModelAccess>,
+    pub group_ids: Option<Vec<gateway_core::routing::AccountGroupId>>,
+    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 {
+        model: String,
+    },
+    Request {
+        model: String,
+        input_text: String,
+        stream: bool,
+        store: bool,
+    },
+    Content {
+        text: String,
+    },
+    Completed,
+    Failed {
+        source: AccountProbeErrorSource,
+        gateway_error_code: GatewayErrorKind,
+        send_state: Option<UpstreamSendState>,
+        message: String,
+        provider_error_code: Option<String>,
+        provider_error_type: Option<String>,
+        upstream_status: Option<u16>,
+        upstream_content_type: Option<String>,
+        upstream_body: Option<String>,
+    },
+}
+
+/// 每次连接测试独占的有限事件流。
+pub type AccountConnectionTestEventStream =
+    Pin<Box<dyn Stream<Item = AccountConnectionTestEvent> + Send + 'static>>;

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

@@ -0,0 +1,164 @@
+//! 控制面认证、统一会话和管理员安全审计事实。
+
+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,
+}
+
+/// 传给管理用例的安全请求上下文。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdminRequestContext {
+    pub principal: AdminPrincipal,
+    pub request_id: String,
+}
+
+impl AdminRequestContext {
+    #[must_use]
+    pub fn mutation_context(&self) -> MutationContext {
+        let actor = match &self.principal {
+            AdminPrincipal::Session { admin_user_id } => MutationActor::AdminSession {
+                admin_user_id: admin_user_id.clone(),
+            },
+            AdminPrincipal::ApiKey => MutationActor::AdminApiKey,
+        };
+        MutationContext {
+            actor,
+            request_id: self.request_id.clone(),
+        }
+    }
+}
+
+/// 登录方式只决定凭据验证流程，不能直接授予会话权限。
+#[derive(Clone, PartialEq, Eq)]
+pub enum LoginCommand {
+    Admin {
+        username: Option<String>,
+        password: String,
+    },
+    Key {
+        api_key: String,
+    },
+}
+
+impl std::fmt::Debug for LoginCommand {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Admin { username, .. } => formatter
+                .debug_struct("AdminLogin")
+                .field("username", username)
+                .field("password", &"[REDACTED]")
+                .finish(),
+            Self::Key { .. } => formatter
+                .debug_struct("KeyLogin")
+                .field("api_key", &"[REDACTED]")
+                .finish(),
+        }
+    }
+}
+
+/// 登录成功后返回的会话事实。
+#[derive(Clone, PartialEq, Eq)]
+pub struct LoginResult {
+    pub session_id: String,
+    pub session: AuthSession,
+}
+
+impl std::fmt::Debug for LoginResult {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("LoginResult")
+            .field("session_id", &"[REDACTED]")
+            .field("session", &self.session)
+            .finish()
+    }
+}
+
+/// 登录状态机可被 API 精确映射的失败类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+pub enum LoginError {
+    #[error("invalid login credentials")]
+    InvalidCredentials,
+    #[error("too many login attempts")]
+    TooManyAttempts { retry_after_seconds: u64 },
+    #[error("authentication is unavailable")]
+    Unavailable,
+}
+
+impl From<ClientAuthenticationError> for LoginError {
+    fn from(error: ClientAuthenticationError) -> Self {
+        match error {
+            ClientAuthenticationError::InvalidKey => Self::InvalidCredentials,
+            ClientAuthenticationError::SnapshotUnavailable
+            | ClientAuthenticationError::ProviderUnavailable => Self::Unavailable,
+        }
+    }
+}
+
+/// 服务端已验证的身份绑定，不保存密码或原始 API Key。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum SessionSubject {
+    Admin {
+        admin_user_id: String,
+        credential_fingerprint: String,
+    },
+    Key {
+        client_key_id: ClientApiKeyId,
+    },
+}
+
+/// 仅已登录管理员可以修改自己的密码。
+pub struct ChangePassword {
+    pub current_password: String,
+    pub new_password: String,
+}
+
+impl std::fmt::Debug for ChangePassword {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str("ChangePassword([REDACTED])")
+    }
+}
+
+/// 两种登录方式共用的固定有效期会话。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthSession {
+    pub subject: SessionSubject,
+    pub expires_at: DateTime<Utc>,
+}
+
+/// 安全审计事件类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AuditActorKind {
+    AdminSession,
+    AdminApiKey,
+    System,
+    Anonymous,
+}
+
+/// 管理写操作留下的最小审计事实。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdminAuditEvent {
+    pub id: String,
+    pub actor_kind: AuditActorKind,
+    pub actor_admin_user_id: Option<String>,
+    pub actor_ref: String,
+    pub request_id: Option<String>,
+    pub action: String,
+    pub entity_kind: String,
+    pub entity_ref: String,
+    pub config_revision: Option<Revision>,
+    pub changed_fields: Vec<String>,
+    pub occurred_at: DateTime<Utc>,
+}

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

@@ -0,0 +1,34 @@
+//! 备份领域的稳定错误码。
+
+/// 配置或参数非法。
+pub const INVALID_CONFIG: &str = "backup.invalid_config";
+/// Cron 表达式非法。
+pub const INVALID_CRON: &str = "backup.invalid_cron";
+/// IANA 时区非法。
+pub const INVALID_TIMEZONE: &str = "backup.invalid_timezone";
+/// 记录不存在。
+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` 非零退出或失败。
+pub const PG_DUMP_FAILED: &str = "backup.pg_dump_failed";
+/// 暂存磁盘空间不足。
+pub const STAGING_SPACE_EXHAUSTED: &str = "backup.staging_space_exhausted";
+/// S3 认证失败。
+pub const S3_AUTH_FAILED: &str = "backup.s3_auth_failed";
+/// S3 权限拒绝。
+pub const S3_PERMISSION_DENIED: &str = "backup.s3_permission_denied";
+/// 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 服务返回无效或失败响应。
+pub const UPSTREAM_FAILURE: &str = "backup.upstream_failure";

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

@@ -0,0 +1,533 @@
+//! S3 备份领域模型、状态机与稳定错误。
+//!
+//! 领域类型只携带事实，不承载基础设施细节。Secret 使用 [`secrecy::SecretString`]，
+//! 全流程不实现 `Serialize`，避免被错误地写入 wire 或日志。管理员身份等审计事实
+//! 只存在于 `admin_audit_events`，本模型不重复保存。
+
+use std::fmt;
+
+use chrono::{DateTime, Utc};
+use secrecy::SecretString;
+use uuid::Uuid;
+
+use super::PageSize;
+
+/// 备份触发来源。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BackupTriggerKind {
+    Manual,
+    Scheduled,
+}
+
+impl BackupTriggerKind {
+    /// 稳定持久化值。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Manual => "manual",
+            Self::Scheduled => "scheduled",
+        }
+    }
+
+    /// 解析持久化值。
+    #[must_use]
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "manual" => Some(Self::Manual),
+            "scheduled" => Some(Self::Scheduled),
+            _ => None,
+        }
+    }
+}
+
+impl fmt::Display for BackupTriggerKind {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(self.as_str())
+    }
+}
+
+/// 备份任务状态机（六状态）。
+///
+/// 迁移 `backup_records_lifecycle_ck` 与字段空值语义共同定义合法持久化行；
+/// [`Self::allows_transition_to`] 只约束领域内的显式状态迁移，两层都必须满足。
+/// 删除成功后记录行被硬删除，因此不存在 `deleted` 终态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum BackupStatus {
+    Queued,
+    Dumping,
+    Uploading,
+    Completed,
+    Failed,
+    Deleting,
+}
+
+impl BackupStatus {
+    /// 稳定持久化值。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Queued => "queued",
+            Self::Dumping => "dumping",
+            Self::Uploading => "uploading",
+            Self::Completed => "completed",
+            Self::Failed => "failed",
+            Self::Deleting => "deleting",
+        }
+    }
+
+    /// 解析持久化值。
+    #[must_use]
+    pub fn parse(value: &str) -> Option<Self> {
+        match value {
+            "queued" => Some(Self::Queued),
+            "dumping" => Some(Self::Dumping),
+            "uploading" => Some(Self::Uploading),
+            "completed" => Some(Self::Completed),
+            "failed" => Some(Self::Failed),
+            "deleting" => Some(Self::Deleting),
+            _ => None,
+        }
+    }
+
+    /// 该状态是否消耗全局活跃名额。
+    #[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!(
+            (self, target),
+            (Self::Queued, Self::Dumping)
+                | (Self::Queued, Self::Failed)
+                | (Self::Dumping, Self::Uploading)
+                | (Self::Dumping, Self::Failed)
+                | (Self::Uploading, Self::Completed)
+                | (Self::Uploading, Self::Failed)
+                | (Self::Completed, Self::Deleting)
+                | (Self::Failed, Self::Deleting)
+        )
+    }
+}
+
+impl fmt::Display for BackupStatus {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(self.as_str())
+    }
+}
+
+/// S3 存储配置更新命令；`secret_access_key` 为 `None` 表示保留旧值。
+#[derive(Clone)]
+pub struct UpdateBackupStorageCommand {
+    pub endpoint: String,
+    pub region: String,
+    pub bucket: String,
+    pub access_key_id: String,
+    pub secret_access_key: Option<SecretString>,
+    pub prefix: String,
+    pub force_path_style: bool,
+}
+
+impl fmt::Debug for UpdateBackupStorageCommand {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("UpdateBackupStorageCommand")
+            .field("endpoint", &self.endpoint)
+            .field("region", &self.region)
+            .field("bucket", &self.bucket)
+            .field("access_key_id", &self.access_key_id)
+            .field("secret_access_key", &self.secret_access_key.is_some())
+            .field("prefix", &self.prefix)
+            .field("force_path_style", &self.force_path_style)
+            .finish()
+    }
+}
+
+/// 调度配置更新命令。
+#[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）。
+///
+/// 只从仓储读取；不实现 `Serialize`，防止 Secret 进入 wire 或日志。
+#[derive(Clone)]
+pub struct BackupSettings {
+    pub storage_revision: u64,
+    pub endpoint: Option<String>,
+    pub region: Option<String>,
+    pub bucket: Option<String>,
+    pub access_key_id: Option<String>,
+    pub secret_access_key: Option<SecretString>,
+    pub prefix: Option<String>,
+    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,
+    pub next_run_at: Option<DateTime<Utc>>,
+    pub last_verified_at: Option<DateTime<Utc>>,
+    pub updated_at: DateTime<Utc>,
+}
+
+impl fmt::Debug for BackupSettings {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("BackupSettings")
+            .field("storage_revision", &self.storage_revision)
+            .field("endpoint", &self.endpoint)
+            .field("region", &self.region)
+            .field("bucket", &self.bucket)
+            .field("access_key_id", &self.access_key_id)
+            .field("secret_access_key", &self.secret_access_key.is_some())
+            .field("prefix", &self.prefix)
+            .field("force_path_style", &self.force_path_style)
+            .field("schedule_enabled", &self.schedule_enabled)
+            .field("cron_expression", &self.cron_expression)
+            .field("schedule_timezone", &self.schedule_timezone)
+            .field("retention_days", &self.retention_days)
+            .field("retention_count", &self.retention_count)
+            .field("next_run_at", &self.next_run_at)
+            .field("last_verified_at", &self.last_verified_at)
+            .field("updated_at", &self.updated_at)
+            .finish()
+    }
+}
+
+impl BackupSettings {
+    /// S3 存储配置是否完整（bucket/region/密钥/前缀齐全）。
+    #[must_use]
+    pub fn storage_configured(&self) -> bool {
+        self.endpoint.is_some()
+            && self.region.is_some()
+            && self.bucket.is_some()
+            && self.access_key_id.is_some()
+            && self.secret_access_key.is_some()
+            && self.prefix.is_some()
+    }
+
+    /// 探测是否已对当前 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,
+    pub endpoint: String,
+    pub region: String,
+    pub bucket: String,
+    pub access_key_id: String,
+    pub secret_access_key: SecretString,
+    pub prefix: String,
+    pub force_path_style: bool,
+}
+
+impl fmt::Debug for BackupStorageConfig {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("BackupStorageConfig")
+            .field("storage_revision", &self.storage_revision)
+            .field("endpoint", &self.endpoint)
+            .field("region", &self.region)
+            .field("bucket", &self.bucket)
+            .field("access_key_id", &self.access_key_id)
+            .field("secret_access_key", &"[REDACTED]")
+            .field("prefix", &self.prefix)
+            .field("force_path_style", &self.force_path_style)
+            .finish()
+    }
+}
+
+impl BackupStorageConfig {
+    /// 从完整设置推导对象存储配置；设置不完整时返回 `None`。
+    #[must_use]
+    pub fn from_settings(settings: &BackupSettings) -> Option<Self> {
+        Some(Self {
+            storage_revision: settings.storage_revision,
+            endpoint: settings.endpoint.clone()?,
+            region: settings.region.clone()?,
+            bucket: settings.bucket.clone()?,
+            access_key_id: settings.access_key_id.clone()?,
+            secret_access_key: settings.secret_access_key.clone()?,
+            prefix: settings.prefix.clone()?,
+            force_path_style: settings.force_path_style,
+        })
+    }
+}
+
+/// 一条备份记录。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackupRecord {
+    pub id: String,
+    pub trigger_kind: BackupTriggerKind,
+    pub status: BackupStatus,
+    pub scheduled_at: Option<DateTime<Utc>>,
+    pub object_key: String,
+    pub size_bytes: Option<u64>,
+    pub sha256: Option<String>,
+    pub attempt_count: u32,
+    pub error_code: Option<String>,
+    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,
+    pub page_size: PageSize,
+    pub status: Option<BackupStatus>,
+    pub trigger: Option<BackupTriggerKind>,
+}
+
+/// 备份记录分页结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackupRecordPage {
+    pub items: Vec<BackupRecord>,
+    pub total: u64,
+    pub page: u32,
+    pub page_size: PageSize,
+}
+
+impl BackupRecordPage {
+    /// 计算总页数；空集合视为一页。
+    #[must_use]
+    pub fn total_pages(&self) -> u32 {
+        let size = u64::from(self.page_size.get());
+        if self.total == 0 {
+            1
+        } else {
+            self.total.div_ceil(size).min(u64::from(u32::MAX)) as u32
+        }
+    }
+}
+
+/// 创建备份任务的持久化数据；id 与对象 key 由领域生成。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackupRecordSeed {
+    pub id: String,
+    pub trigger_kind: BackupTriggerKind,
+    pub scheduled_at: Option<DateTime<Utc>>,
+    pub object_key: String,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+/// 连接测试结果；只携带稳定阶段与脱敏消息。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ConnectionTestResult {
+    pub ok: bool,
+    pub stage: &'static str,
+    pub code: Option<&'static str>,
+    pub message: String,
+}
+
+/// 对象存储探测阶段。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ConnectionTestStage {
+    PutObject,
+    HeadObject,
+    GetObject,
+    DeleteObject,
+}
+
+impl ConnectionTestStage {
+    /// 稳定 wire 值。
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::PutObject => "putObject",
+            Self::HeadObject => "headObject",
+            Self::GetObject => "getObject",
+            Self::DeleteObject => "deleteObject",
+        }
+    }
+}
+
+/// 上传到对象存储并期望远端校验的归档 metadata。
+///
+/// `size_bytes` 在上传时不写入 metadata，但 `HeadObject` 会返回远端大小，
+/// 用于与本地归档校验一致。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackupObjectMetadata {
+    pub backup_id: String,
+    pub sha256: String,
+    pub created_at: DateTime<Utc>,
+    pub size_bytes: u64,
+}
+
+impl BackupObjectMetadata {
+    /// 构造上传 metadata。
+    #[must_use]
+    pub const fn new(
+        backup_id: String,
+        sha256: String,
+        created_at: DateTime<Utc>,
+        size_bytes: u64,
+    ) -> Self {
+        Self {
+            backup_id,
+            sha256,
+            created_at,
+            size_bytes,
+        }
+    }
+}
+
+/// 短时下载地址结果。
+#[derive(Clone, PartialEq, Eq)]
+pub struct DownloadUrlResult {
+    pub url: String,
+    pub file_name: String,
+    pub expires_in: std::time::Duration,
+}
+
+impl fmt::Debug for DownloadUrlResult {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("DownloadUrlResult")
+            .field("url", &"[REDACTED]")
+            .field("file_name", &self.file_name)
+            .field("expires_in", &self.expires_in)
+            .finish()
+    }
+}
+
+/// 备份基础设施错误：只携带稳定错误码与脱敏消息。
+///
+/// 该类型不构成第二套 kind 枚举；`gateway-admin` 边界统一映射为既有
+/// `AdminErrorKind`。稳定 `error_code` 同时用于任务记录、日志与 UI。
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("{message}")]
+pub struct BackupError {
+    code: &'static str,
+    message: String,
+}
+
+impl BackupError {
+    /// 构造基础设施错误。
+    #[must_use]
+    pub const fn new(code: &'static str, message: String) -> Self {
+        Self { code, message }
+    }
+
+    /// 稳定错误码，例如 `backup.s3_auth_failed`。
+    #[must_use]
+    pub const fn code(&self) -> &'static str {
+        self.code
+    }
+
+    /// 脱敏后的可操作消息。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+}
+
+/// 构造稳定错误码常量。
+pub mod code;
+
+/// 构建对象 key：`{prefix}/YYYY/MM/DD/codex-proxy-rs_{UTC seconds}_{backup id}.dump`。
+///
+/// 规范化规则：prefix 不得为空、不得以前导 `/` 开头、不得包含 `..`、反斜杠或控制字符；
+/// 输出统一使用 `/` 分隔且不含空段。
+pub fn build_object_key(
+    prefix: &str,
+    backup_id: &str,
+    at: DateTime<Utc>,
+) -> Result<String, BackupError> {
+    let prefix = normalize_prefix(prefix)?;
+    Ok(format!(
+        "{prefix}/{}/{:02}/{:02}/codex-proxy-rs_{}_{}.dump",
+        at.format("%Y"),
+        at.format("%m"),
+        at.format("%d"),
+        at.format("%Y%m%d_%H%M%S"),
+        short_backup_id(backup_id),
+    ))
+}
+
+/// 下载文件名：`codex-proxy-rs_{短 id}.dump`，与对象 key 的文件名一致。
+#[must_use]
+pub fn build_download_file_name(backup_id: &str) -> String {
+    format!("codex-proxy-rs_{}.dump", short_backup_id(backup_id))
+}
+
+/// 截取备份 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；空串、前导 `/`、`..` 段、反斜杠和控制字符均拒绝。
+pub fn normalize_prefix(prefix: &str) -> Result<String, BackupError> {
+    if prefix.is_empty() || prefix.starts_with('/') {
+        return Err(BackupError::new(
+            code::INVALID_CONFIG,
+            "存储对象前缀必须非空且不能以前导 / 开头".to_owned(),
+        ));
+    }
+    if prefix.bytes().any(|byte| byte.is_ascii_control()) || prefix.contains('\\') {
+        return Err(BackupError::new(
+            code::INVALID_CONFIG,
+            "存储对象前缀包含非法字符".to_owned(),
+        ));
+    }
+    if prefix.split('/').any(|segment| segment == "..") {
+        return Err(BackupError::new(
+            code::INVALID_CONFIG,
+            "存储对象前缀不能包含 .. 路径段".to_owned(),
+        ));
+    }
+    Ok(prefix.trim_end_matches('/').to_owned())
+}
+
+/// 生成新的备份记录 id。
+#[must_use]
+pub fn new_backup_id() -> String {
+    format!("backup_{}", Uuid::now_v7().simple())
+}
+
+/// 从触发类型与计划时间构造可持久化 seed；id 与对象 key 一次生成保持一致。
+pub fn build_backup_seed(
+    trigger_kind: BackupTriggerKind,
+    scheduled_at: Option<DateTime<Utc>>,
+    prefix: &str,
+    at: DateTime<Utc>,
+    expires_at: Option<DateTime<Utc>>,
+) -> Result<BackupRecordSeed, BackupError> {
+    let id = new_backup_id();
+    let object_key = build_object_key(prefix, &id, at)?;
+    Ok(BackupRecordSeed {
+        id,
+        trigger_kind,
+        scheduled_at,
+        object_key,
+        expires_at,
+    })
+}

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

@@ -0,0 +1,58 @@
+//! 管理设置页使用的 Codex 客户端下载信息。
+
+use chrono::{DateTime, Utc};
+
+/// Windows 安装包架构。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum ClientArchitecture {
+    X64,
+    Arm64,
+}
+
+impl ClientArchitecture {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::X64 => "x64",
+            Self::Arm64 => "arm64",
+        }
+    }
+}
+
+/// 下载地址的可信来源。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClientDownloadSource {
+    MicrosoftStore,
+    OfficialOpenAi,
+}
+
+impl ClientDownloadSource {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::MicrosoftStore => "microsoft_store",
+            Self::OfficialOpenAi => "official_openai",
+        }
+    }
+}
+
+/// 一个已经过 Host 校验、可以直接交给浏览器下载的安装包。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientDownloadPackage {
+    pub architecture: ClientArchitecture,
+    pub source: ClientDownloadSource,
+    pub version: Option<String>,
+    pub file_name: String,
+    pub size_bytes: Option<u64>,
+    pub download_url: String,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+/// Codex Desktop Windows 下载解析结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CodexDesktopWindowsDownloads {
+    pub resolved_at: DateTime<Utc>,
+    pub cached: bool,
+    pub warning: Option<String>,
+    pub packages: Vec<ClientDownloadPackage>,
+}

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

@@ -0,0 +1,250 @@
+//! Client API Key 的 Command、Result 与安全秘密类型。
+
+use std::{collections::BTreeMap, fmt, num::NonZeroU16};
+
+use chrono::{DateTime, Utc};
+
+use gateway_core::{
+    engine::budget::{ClientBudgetLimits, ClientBudgetStatus},
+    policy::{ClientApiKeyId, PlaintextClientApiKey, RateLimits},
+    routing::{AccountGroupId, ProviderKind},
+};
+
+use super::{AdminModelError, Revision, account_groups::AccountGroupRef};
+
+pub type ProviderRequestProfileOverrides =
+    BTreeMap<ProviderKind, gateway_core::account::OpaqueProviderData>;
+pub type ProviderRequestProfileOverrideUpdates =
+    BTreeMap<ProviderKind, Option<gateway_core::account::OpaqueProviderData>>;
+
+/// Client Key 列表保持旧 HTTP 合同允许的完整非零 `u16` 页大小。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct ClientKeyPageSize(NonZeroU16);
+
+impl ClientKeyPageSize {
+    /// 创建 1 至 65535 的 Client Key 页大小。
+    ///
+    /// # Errors
+    ///
+    /// `value` 为零时返回 [`AdminModelError::InvalidClientKeyPageSize`]。
+    pub fn new(value: u16) -> Result<Self, AdminModelError> {
+        NonZeroU16::new(value)
+            .map(Self)
+            .ok_or(AdminModelError::InvalidClientKeyPageSize)
+    }
+
+    #[must_use]
+    pub const fn get(self) -> u16 {
+        self.0.get()
+    }
+}
+
+/// Client Key 列表排序字段。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClientKeySortField {
+    Name,
+    Enabled,
+    CreatedAt,
+    LastUsedAt,
+}
+
+/// Client Key 列表排序方向。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SortDirection {
+    Asc,
+    Desc,
+}
+
+/// 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),
+    Enabled(bool),
+    CreatedAt(DateTime<Utc>),
+    LastUsedAt(Option<DateTime<Utc>>),
+}
+
+/// Client Key 的稳定键集游标。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientKeyCursor {
+    pub sort: ClientKeySort,
+    pub value: ClientKeyCursorValue,
+    pub id: ClientApiKeyId,
+}
+
+/// Client Key 列表查询。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientKeyListQuery {
+    pub cursor: Option<ClientKeyCursor>,
+    pub page_size: ClientKeyPageSize,
+    pub search: Option<String>,
+    pub sort: ClientKeySort,
+}
+
+/// 不含完整明文 Key 的管理投影。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientKeyRecord {
+    pub request_profile_overrides: ProviderRequestProfileOverrides,
+    pub id: ClientApiKeyId,
+    pub name: String,
+    pub label: Option<String>,
+    pub groups: Vec<AccountGroupRef>,
+    pub provider_kinds: Vec<ProviderKind>,
+    pub prefix: String,
+    pub enabled: bool,
+    pub limits: RateLimits,
+    pub budget: ClientBudgetStatus,
+    pub last_used_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// Client Key 列表页。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientKeyPage {
+    pub config_revision: Revision,
+    pub items: Vec<ClientKeyRecord>,
+    pub total: u64,
+    pub next_cursor: Option<ClientKeyCursor>,
+}
+
+/// 仅在创建或显式读取密钥配置时返回的明文 Key；Debug 隐去明文。
+#[derive(Clone, PartialEq, Eq)]
+pub struct ClientKeySecret {
+    pub record: ClientKeyRecord,
+    plaintext: String,
+}
+
+impl ClientKeySecret {
+    #[must_use]
+    pub fn new(record: ClientKeyRecord, plaintext: impl Into<String>) -> Self {
+        Self {
+            record,
+            plaintext: plaintext.into(),
+        }
+    }
+
+    #[must_use]
+    pub fn expose_for_response(&self) -> &str {
+        &self.plaintext
+    }
+}
+
+impl fmt::Debug for ClientKeySecret {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("ClientKeySecret")
+            .field("record", &self.record)
+            .field("plaintext", &"[REDACTED]")
+            .finish()
+    }
+}
+
+/// API 提交的 Client Key 创建命令。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CreateClientKey {
+    pub request_profile_overrides: ProviderRequestProfileOverrides,
+    pub custom_key: Option<PlaintextClientApiKey>,
+    pub name: String,
+    pub label: Option<String>,
+    pub group_ids: Vec<AccountGroupId>,
+    pub limits: RateLimits,
+    pub budget: ClientBudgetLimits,
+}
+
+/// 管理用例生成 ID 与明文后的持久化命令。
+#[derive(Clone, PartialEq, Eq)]
+pub struct NewClientKey {
+    pub request_profile_overrides: ProviderRequestProfileOverrides,
+    pub id: ClientApiKeyId,
+    pub name: String,
+    pub label: Option<String>,
+    pub group_ids: Vec<AccountGroupId>,
+    pub limits: RateLimits,
+    pub budget: ClientBudgetLimits,
+    pub plaintext: String,
+}
+
+impl fmt::Debug for NewClientKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("NewClientKey")
+            .field("id", &self.id)
+            .field("name", &self.name)
+            .field("group_ids", &self.group_ids)
+            .field("plaintext", &"[REDACTED]")
+            .finish_non_exhaustive()
+    }
+}
+
+/// 修改 Client Key 的公开策略字段。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UpdateClientKey {
+    pub request_profile_override_updates: ProviderRequestProfileOverrideUpdates,
+    pub id: ClientApiKeyId,
+    pub name: String,
+    pub label: Option<String>,
+    pub group_ids: Vec<AccountGroupId>,
+    pub limits: RateLimits,
+    pub daily_limit_usd: Option<gateway_core::metering::Decimal>,
+    pub weekly_limit_usd: Option<gateway_core::metering::Decimal>,
+}
+
+/// 修改 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,
+    Weekly,
+    All,
+}
+
+/// 清零所选窗口已用金额，保留限额、到期时间与历史费用。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResetClientKeyBudget {
+    pub id: ClientApiKeyId,
+    pub period: ClientKeyBudgetPeriod,
+}
+
+/// 删除 Client Key。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DeleteClientKey {
+    pub id: ClientApiKeyId,
+}
+
+/// Client Key 创建结果；完整明文仅存在于该一次性结果中。
+pub struct CreatedClientKey {
+    pub config_revision: Revision,
+    pub secret: ClientKeySecret,
+}
+
+impl fmt::Debug for CreatedClientKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("CreatedClientKey")
+            .field("config_revision", &self.config_revision)
+            .field("secret", &self.secret)
+            .finish()
+    }
+}
+
+/// Client Key 普通写操作结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientKeyMutation {
+    pub config_revision: Revision,
+    pub record: Option<ClientKeyRecord>,
+    pub id: ClientApiKeyId,
+}

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

@@ -0,0 +1,84 @@
+//! 进程内账号导入任务；只保存执行所需输入与可公开的结果。
+
+use chrono::{DateTime, Utc};
+use gateway_core::{account::ProviderAccountId, routing::ProviderKind};
+use uuid::Uuid;
+
+use super::{MutationContext, provider_credentials::ImportCredentials};
+
+pub const MAX_IMPORT_TASK_ITEMS: usize = 200;
+
+#[derive(Debug)]
+pub struct ImportTaskInput {
+    pub provider: ProviderKind,
+    pub command: ImportCredentials,
+}
+
+#[derive(Debug)]
+pub struct SubmitImportTask {
+    pub submission_id: Uuid,
+    /// API 对完整输入计算摘要；用于区分丢失响应后的重试与修改后的新提交。
+    pub fingerprint: [u8; 32],
+    pub context: MutationContext,
+    pub items: Vec<ImportTaskInput>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ImportItemStatus {
+    Pending,
+    Running,
+    Succeeded,
+    Failed,
+    Unknown,
+    Skipped,
+}
+
+impl ImportItemStatus {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Pending => "pending",
+            Self::Running => "running",
+            Self::Succeeded => "succeeded",
+            Self::Failed => "failed",
+            Self::Unknown => "unknown",
+            Self::Skipped => "skipped",
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct ImportTaskItem {
+    pub index: usize,
+    pub provider: ProviderKind,
+    pub status: ImportItemStatus,
+    pub account_ids: Vec<ProviderAccountId>,
+    pub message: Option<String>,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct ImportTaskCounts {
+    pub pending: usize,
+    pub running: usize,
+    pub succeeded: usize,
+    pub failed: usize,
+    pub unknown: usize,
+    pub skipped: usize,
+    pub imported_accounts: usize,
+}
+
+#[derive(Debug, Clone)]
+pub struct ImportTaskSummary {
+    pub task_id: Uuid,
+    pub created_at: DateTime<Utc>,
+    pub finished_at: Option<DateTime<Utc>>,
+    pub stop_requested: bool,
+    pub total: usize,
+    pub counts: ImportTaskCounts,
+}
+
+#[derive(Debug, Clone)]
+pub struct ImportTaskDetail {
+    pub summary: ImportTaskSummary,
+    pub items: Vec<ImportTaskItem>,
+}

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

@@ -0,0 +1,41 @@
+//! 单页 Key 用量的查询合同；身份范围不由调用方提供。
+
+use super::{
+    PageSize,
+    client_keys::ClientKeyRecord,
+    observability::{
+        HealthTimeline, OpsErrorPage, RequestMetricPoint, TimeRange, UsageOverview, UsagePage,
+    },
+};
+
+#[derive(Debug, Clone)]
+pub struct KeyUsageQuery {
+    pub range: TimeRange,
+    pub model: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub enum KeyUsageRecordKind {
+    Success,
+    Error,
+}
+
+#[derive(Debug, Clone)]
+pub struct KeyUsageRecordsQuery {
+    pub usage: KeyUsageQuery,
+    pub kind: KeyUsageRecordKind,
+    pub current_page: u32,
+    pub page_size: PageSize,
+}
+
+pub struct KeyUsageOverview {
+    pub key: ClientKeyRecord,
+    pub overview: UsageOverview,
+    pub trend: Vec<RequestMetricPoint>,
+    pub health_timeline: HealthTimeline,
+}
+
+pub enum KeyUsageRecords {
+    Success(UsagePage),
+    Error(OpsErrorPage),
+}

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

@@ -0,0 +1,190 @@
+//! 管理控制面使用的 Command、Result 与稳定值对象。
+
+use std::num::{NonZeroU16, NonZeroU64};
+
+pub mod account_groups;
+pub mod accounts;
+pub mod auth;
+pub mod backup;
+pub mod client_distribution;
+pub mod client_keys;
+pub mod import_tasks;
+pub mod key_usage;
+pub mod observability;
+pub mod plugin_client_keys;
+pub mod plugin_resources;
+pub mod plugins;
+pub mod pricing;
+pub mod provider_credentials;
+pub mod proxies;
+pub mod quota_forecast;
+pub mod quota_forecast_sampling;
+pub mod settings;
+pub mod system;
+
+/// 管理用例对外返回的稳定错误分类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AdminErrorKind {
+    Invalid,
+    Unauthorized,
+    Forbidden,
+    NotFound,
+    Conflict,
+    RateLimited,
+    BadGateway,
+    UpstreamResultUnknown,
+    Unavailable,
+    Internal,
+}
+
+/// 不携带基础设施细节、可安全返回给管理员的管理用例错误。
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("{message}")]
+pub struct AdminError {
+    kind: AdminErrorKind,
+    message: String,
+}
+
+impl AdminError {
+    #[must_use]
+    pub fn new(kind: AdminErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+        }
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> AdminErrorKind {
+        self.kind
+    }
+
+    /// 返回已脱敏、可公开给管理员的文案。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
+    #[must_use]
+    pub fn invalid(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::Invalid, message)
+    }
+
+    #[must_use]
+    pub fn bad_request(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::Invalid, message)
+    }
+
+    #[must_use]
+    pub fn not_found(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::NotFound, message)
+    }
+
+    #[must_use]
+    pub fn conflict(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::Conflict, message)
+    }
+
+    #[must_use]
+    pub fn bad_gateway(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::BadGateway, message)
+    }
+
+    #[must_use]
+    pub fn upstream_result_unknown(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::UpstreamResultUnknown, message)
+    }
+
+    #[must_use]
+    pub fn unavailable(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::Unavailable, message)
+    }
+
+    #[must_use]
+    pub fn internal(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::Internal, message)
+    }
+}
+
+/// PostgreSQL 中所有正整数 revision 的管理层表示。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Revision(NonZeroU64);
+
+impl Revision {
+    /// 创建正整数 revision。
+    ///
+    /// # Errors
+    ///
+    /// `value` 为零时返回 [`AdminModelError::ZeroRevision`]。
+    pub fn new(value: u64) -> Result<Self, AdminModelError> {
+        NonZeroU64::new(value)
+            .map(Self)
+            .ok_or(AdminModelError::ZeroRevision)
+    }
+
+    #[must_use]
+    pub const fn get(self) -> u64 {
+        self.0.get()
+    }
+}
+
+/// 管理列表统一使用的受限页大小。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct PageSize(NonZeroU16);
+
+impl PageSize {
+    pub const MAX: u16 = 200;
+
+    /// 创建 1 至 200 的页大小。
+    ///
+    /// # Errors
+    ///
+    /// `value` 不在有效范围时返回 [`AdminModelError::InvalidPageSize`]。
+    pub fn new(value: u16) -> Result<Self, AdminModelError> {
+        if value > Self::MAX {
+            return Err(AdminModelError::InvalidPageSize(value));
+        }
+        NonZeroU16::new(value)
+            .map(Self)
+            .ok_or(AdminModelError::InvalidPageSize(value))
+    }
+
+    #[must_use]
+    pub const fn get(self) -> u16 {
+        self.0.get()
+    }
+}
+
+/// 可审计管理写操作的发起者。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum MutationActor {
+    AdminSession { admin_user_id: String },
+    AdminApiKey,
+    System,
+}
+
+/// 管理写操作必须携带的审计上下文。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MutationContext {
+    pub actor: MutationActor,
+    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("client key page size must be inside 1..=65535")]
+    InvalidClientKeyPageSize,
+    #[error("request outcome must be 1..=256 bytes without control characters")]
+    InvalidRequestOutcome,
+    #[error("time range must be positive and no longer than 366 days")]
+    InvalidTimeRange,
+    #[error("decimal amount is not a non-negative numeric(20,10) value")]
+    InvalidDecimalAmount,
+    #[error("latency percentile must be finite and non-negative")]
+    InvalidLatencyPercentile,
+}

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

@@ -0,0 +1,31 @@
+//! 插件可见的 Client Key 非秘密资源投影。
+
+use gateway_core::policy::ClientApiKeyId;
+
+use super::PageSize;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginClientKeyCursor {
+    pub name: String,
+    pub id: ClientApiKeyId,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginClientKeyListQuery {
+    pub cursor: Option<PluginClientKeyCursor>,
+    pub limit: PageSize,
+}
+
+/// 插件只能发现调用所需的公开身份，不取得 Key 前缀、策略细节或明文。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginClientKey {
+    pub id: ClientApiKeyId,
+    pub name: String,
+    pub enabled: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginClientKeyPage {
+    pub items: Vec<PluginClientKey>,
+    pub next_cursor: Option<PluginClientKeyCursor>,
+}

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

@@ -0,0 +1,42 @@
+//! 插件资源归属由宿主调用上下文给出，不能由插件参数选择实例或代次。
+
+use super::Revision;
+
+#[derive(Debug, Clone)]
+pub struct PluginResourceOwner {
+    pub instance_id: String,
+    pub artifact_sha256: String,
+    pub revision: Revision,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ManagedResource {
+    pub id: String,
+    pub name: String,
+    pub enabled: bool,
+}
+
+pub struct ResourceMutation<T> {
+    /// 没有事实变化时不递增配置 revision，也不触发发布。
+    pub revision: Option<Revision>,
+    pub value: T,
+}
+
+pub struct GroupMembersChange {
+    pub resource_key: String,
+    pub add: Vec<String>,
+    pub remove: Vec<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct GroupMembersChanged {
+    pub added: u64,
+    pub removed: u64,
+}
+
+/// 插件 Key 的首次创建设置；分组始终从本实例资源键解析。
+pub struct ManagedKeyConfig {
+    pub name: String,
+    pub limits: gateway_core::policy::RateLimits,
+    pub budget: gateway_core::engine::budget::ClientBudgetLimits,
+}

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

@@ -0,0 +1,231 @@
+use std::{fmt, sync::Arc};
+
+use chrono::{DateTime, Utc};
+use gateway_core::account::OutboundProxy;
+use secrecy::SecretString;
+use serde::{Deserialize, Serialize};
+
+use super::{PluginArtifactMetadata, PluginSource, PluginSourceEgress};
+use crate::model::Revision;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum PluginUpdateSource {
+    Builtin,
+    Upload,
+    Url { url: String },
+    Github { repository: String },
+}
+
+/// 检查策略只决定查询目标，任何策略都不会自动安装或切换运行实例。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum PluginUpdatePolicy {
+    Manual {},
+    Stable {},
+    Pinned {
+        tag: String,
+        #[serde(default)]
+        allow_prerelease: bool,
+    },
+}
+
+impl Default for PluginUpdatePolicy {
+    fn default() -> Self {
+        Self::Manual {}
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginSourceBinding {
+    pub plugin_id: String,
+    pub source: PluginUpdateSource,
+    #[serde(default)]
+    pub policy: PluginUpdatePolicy,
+    #[serde(default)]
+    pub outbound_proxy_id: Option<String>,
+}
+
+#[derive(Clone)]
+pub struct PluginDistributionEgress {
+    pub source: PluginSourceEgress,
+    pub proxy: OutboundProxy,
+}
+
+impl PluginDistributionEgress {
+    #[must_use]
+    pub fn new(id: String, revision: Revision, proxy: OutboundProxy) -> Self {
+        Self {
+            source: PluginSourceEgress {
+                id,
+                revision: revision.get(),
+            },
+            proxy,
+        }
+    }
+
+    #[must_use]
+    pub fn cache_key(&self) -> String {
+        format!("{}:{}", self.source.id, self.source.revision)
+    }
+}
+
+impl fmt::Debug for PluginDistributionEgress {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("PluginDistributionEgress")
+            .field("source", &self.source)
+            .field("proxy", &"<redacted>")
+            .finish()
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginUpdateCheck {
+    pub binding: PluginSourceBinding,
+    /// Release 元数据不是已校验的插件包，不据此声明平台或 SDK 兼容。
+    pub release: PluginRelease,
+}
+
+impl From<&PluginSource> for PluginUpdateSource {
+    fn from(source: &PluginSource) -> Self {
+        match source {
+            PluginSource::Builtin { .. } => Self::Builtin,
+            PluginSource::Upload => Self::Upload,
+            PluginSource::Url { url, .. } => Self::Url { url: url.clone() },
+            PluginSource::Github { repository, .. } => Self::Github {
+                repository: repository.to_ascii_lowercase(),
+            },
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DownloadPurpose {
+    Metadata,
+    Artifact,
+}
+
+/// 授权目标以完整 origin 和路径段边界匹配；摘要、名称和列表均不包含 secret。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct SourceCredentialInfo {
+    pub id: String,
+    pub name: String,
+    pub origin: String,
+    pub path_prefix: String,
+    pub purposes: Vec<DownloadPurpose>,
+}
+
+#[derive(Clone, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum SourceAuthentication {
+    Github {
+        token: SecretString,
+    },
+    Bearer {
+        token: SecretString,
+    },
+    Basic {
+        username: String,
+        password: SecretString,
+    },
+    Header {
+        name: String,
+        value: SecretString,
+    },
+}
+
+#[derive(Clone)]
+pub struct SourceCredential {
+    pub info: SourceCredentialInfo,
+    pub authentication: SourceAuthentication,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct GithubReleaseQuery {
+    pub repository: String,
+    pub tag: Option<String>,
+    #[serde(default)]
+    pub allow_prerelease: bool,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ReleaseAsset {
+    pub name: String,
+    pub size: u64,
+    pub sha256: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginRelease {
+    pub repository: String,
+    pub tag: String,
+    pub name: String,
+    pub prerelease: bool,
+    pub assets: Vec<ReleaseAsset>,
+    pub queried_at: DateTime<Utc>,
+    pub expires_at: DateTime<Utc>,
+}
+
+/// 下载意图不承载凭据；引用在 Admin 中解析后只交给 Host 的本次调用。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum RemotePluginLocation {
+    Url {
+        url: String,
+        sha256: Option<String>,
+    },
+    Github {
+        repository: String,
+        tag: String,
+        asset: String,
+        #[serde(default)]
+        allow_prerelease: bool,
+        sha256: Option<String>,
+    },
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct RemotePluginVerify {
+    pub location: RemotePluginLocation,
+    #[serde(default)]
+    pub credential_ids: Vec<String>,
+    #[serde(default)]
+    pub outbound_proxy_id: Option<String>,
+    /// 更新已有插件时锁定身份；首次安装从包内清单读取。
+    pub expected_plugin_id: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct RemotePluginInstall {
+    pub plugin_id: String,
+    pub version: String,
+    pub location: RemotePluginLocation,
+    #[serde(default)]
+    pub credential_ids: Vec<String>,
+    #[serde(default)]
+    pub outbound_proxy_id: Option<String>,
+}
+
+pub struct DownloadedPlugin {
+    pub archive: Arc<[u8]>,
+    pub sha256: String,
+    pub source: PluginSource,
+}
+
+/// 只读包校验结果，不代表实例配置、授权或私有状态已完成运行时准备。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct VerifiedPluginArtifact {
+    pub metadata: PluginArtifactMetadata,
+    pub source: PluginSource,
+}

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

@@ -0,0 +1,192 @@
+use std::collections::BTreeMap;
+
+use secrecy::SecretString;
+use serde::{Deserialize, Serialize};
+
+use crate::model::Revision;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginPermissionGrant {
+    pub permission: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PluginFailurePolicy {
+    Reject,
+    Delegate,
+    Observe,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginCapabilityBinding {
+    pub contribution: String,
+    pub stage: String,
+    pub order: i32,
+    pub failure_policy: PluginFailurePolicy,
+    #[serde(default)]
+    pub client_key_ids: Vec<String>,
+    #[serde(default)]
+    pub account_group_ids: Vec<String>,
+    #[serde(default)]
+    pub provider_ids: Vec<String>,
+    #[serde(default)]
+    pub models: Vec<String>,
+    #[serde(default)]
+    pub identity_bindings: Vec<PluginFrontendIdentityBinding>,
+}
+
+/// 外部 principal 到既有 Client Key 的显式宿主映射。
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginFrontendIdentityBinding {
+    pub principal: String,
+    pub client_key_id: String,
+}
+
+impl std::fmt::Debug for PluginFrontendIdentityBinding {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("PluginFrontendIdentityBinding")
+            .field("principal", &"[REDACTED]")
+            .field("client_key_id", &self.client_key_id)
+            .finish()
+    }
+}
+
+/// 配置和 secret 分离；Debug 与 Serialize 不得无意展开实例配置。
+#[derive(Clone)]
+pub struct PluginInstance {
+    pub id: String,
+    pub name: String,
+    pub artifact_sha256: String,
+    pub enabled: bool,
+    pub trusted_process: bool,
+    pub configuration: serde_json::Value,
+    pub secrets: BTreeMap<String, SecretString>,
+    pub grants: Vec<PluginPermissionGrant>,
+    pub bindings: Vec<PluginCapabilityBinding>,
+    pub revision: Revision,
+}
+
+#[derive(Clone)]
+pub struct PluginInstanceSnapshot {
+    pub config_revision: Revision,
+    pub instances: Vec<PluginInstance>,
+}
+
+pub struct PluginInstanceMutation {
+    pub config_revision: Revision,
+    pub instance: PluginInstance,
+}
+
+/// 控制面展示的单实例运行状态；它描述当前进程观察到的事实，不替代持久启用配置。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PluginInstanceRuntimeStatus {
+    Disabled,
+    AwaitingPublication,
+    Preparing,
+    Running,
+    Blocked,
+    PreparationFailed,
+    Faulted,
+    Draining,
+}
+
+/// 已脱敏且可安全返回给管理员的运行失败摘要。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginInstanceRuntimeFailure {
+    pub code: String,
+    pub message: String,
+}
+
+/// 当前发布视图与代次索引的只读诊断。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginInstanceRuntime {
+    pub status: PluginInstanceRuntimeStatus,
+    pub actual_revision: Option<u64>,
+    pub actual_artifact_sha256: Option<String>,
+    pub failure: Option<PluginInstanceRuntimeFailure>,
+    pub draining_revisions: Vec<u64>,
+}
+
+pub struct PluginInstanceView {
+    pub instance: PluginInstance,
+    pub configuration_required: bool,
+    pub running: bool,
+    pub published_revision: Option<u64>,
+    pub runtime: PluginInstanceRuntime,
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct ConfigurePluginInstance {
+    /// 创建草稿固定一个 UUID，重试复用同一配置，不能作为编辑已有配置的入口。
+    pub creation_id: Option<String>,
+    /// 编辑时检查用户看到的配置版本，避免覆盖另一窗口已经保存的内容。
+    pub expected_revision: Option<u64>,
+    /// 管理员确认停用的同插件配置，与当前配置在同一事务中切换。
+    #[serde(default)]
+    pub replace_instances: Vec<PluginInstanceReplacement>,
+    pub name: String,
+    pub artifact_sha256: String,
+    pub enabled: bool,
+    pub configuration: serde_json::Value,
+    /// 缺省保留旧值；显式空对象清除全部 secret。
+    pub secrets: Option<BTreeMap<String, SecretString>>,
+    pub bindings: Vec<PluginCapabilityBinding>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginInstanceReplacement {
+    pub id: String,
+    pub expected_revision: u64,
+}
+
+/// 恢复已安装旧版本的配置快照，并重新通过目标版本校验。
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct RollbackPluginInstance {
+    pub artifact_sha256: String,
+    pub expected_revision: u64,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginRollbackTarget {
+    pub artifact_sha256: String,
+    pub version: String,
+    pub platforms: Vec<String>,
+}
+
+/// 静态候选不启动插件；实际回滚仍须复验配置、平台和私有状态兼容性。
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginRollbackPlan {
+    pub instance_revision: u64,
+    pub current_version: String,
+    pub targets: Vec<PluginRollbackTarget>,
+}
+
+/// 版本配置快照只用于服务端恢复，敏感值不实现 Debug 或 Serialize。
+#[derive(Clone)]
+pub struct PluginVersionConfiguration {
+    pub configuration: serde_json::Value,
+    pub secrets: BTreeMap<String, SecretString>,
+    pub bindings: Vec<PluginCapabilityBinding>,
+}
+
+/// 切换版本的只读草稿，不包含密钥值，也不会启动插件或写入配置。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginVersionPlan {
+    pub instance_revision: u64,
+    pub artifact_sha256: String,
+    pub configuration: serde_json::Value,
+    pub secret_fields: Vec<String>,
+    pub bindings: Vec<PluginCapabilityBinding>,
+    pub restored: bool,
+}

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

@@ -0,0 +1,89 @@
+use std::sync::Arc;
+
+use serde::{Deserialize, Serialize};
+
+/// 页面和业务调用绑定同一实例版本；制品摘要单独作为不可变资源身份。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginManagementTarget {
+    pub instance_id: String,
+    pub artifact_sha256: String,
+    pub revision: u64,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginManagementView {
+    pub target: PluginManagementTarget,
+    pub name: String,
+    pub configuration_schema: serde_json::Value,
+    pub pages: Vec<PluginManagementPage>,
+    pub routes: Vec<PluginManagementRoute>,
+    pub resources: Vec<PluginManagementResource>,
+    pub callbacks: Vec<PluginManagementCallback>,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginManagementCallback {
+    pub path: String,
+    pub response_content_types: Vec<String>,
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct StartPluginManagementCallback {
+    pub path: String,
+    pub ttl_seconds: u32,
+}
+
+/// state 是短期一次性秘密，只交给发起登录的管理员，不进入 Debug 或日志。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginManagementCallbackTicket {
+    pub state: String,
+    pub expires_at_ms: i64,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginManagementPage {
+    pub id: String,
+    pub title: String,
+    pub description: Option<String>,
+    pub entry: String,
+    pub icon: Option<String>,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginManagementRoute {
+    pub method: String,
+    pub path: String,
+    pub request_content_types: Vec<String>,
+    pub response_content_types: Vec<String>,
+}
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginManagementResource {
+    pub path: String,
+    pub content_type: String,
+    pub public: bool,
+}
+
+/// 原始正文可能含业务数据，不能派生内容型 Debug 或写入诊断日志。
+pub struct PluginManagementRequest {
+    pub method: String,
+    pub path: String,
+    pub query: String,
+    pub content_type: Option<String>,
+    pub body: Vec<u8>,
+    pub request_id: String,
+}
+
+pub struct PluginManagementResponse {
+    pub status: u16,
+    pub content_type: String,
+    pub body: Arc<[u8]>,
+}

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

@@ -0,0 +1,273 @@
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    sync::Arc,
+};
+
+use serde::{Deserialize, Serialize};
+
+use super::Revision;
+
+pub mod distribution;
+pub mod instances;
+pub mod management;
+pub mod official;
+pub mod state;
+
+/// 一个宿主发行版明确承诺支持的插件能力版本。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PluginHostCapability {
+    pub capability: String,
+    pub versions: Vec<u32>,
+}
+
+/// 随宿主发行物封口的插件合同；Runtime 与发布清单共用这一份声明。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PluginHostCompatibility {
+    pub schema_version: u32,
+    pub manifest_schema_versions: Vec<u32>,
+    pub protocol_versions: Vec<u32>,
+    pub capabilities: Vec<PluginHostCapability>,
+    pub permissions: Vec<String>,
+}
+
+impl PluginHostCompatibility {
+    /// 拒绝空集合、重复项和不受控标识，避免发行清单把“未知”解释为通配。
+    #[must_use]
+    pub fn is_valid(&self) -> bool {
+        if self.schema_version != 1
+            || !valid_versions(&self.manifest_schema_versions)
+            || !valid_versions(&self.protocol_versions)
+            || self.capabilities.is_empty()
+            || self.capabilities.len() > 64
+            || self.permissions.len() > 64
+        {
+            return false;
+        }
+        let mut capabilities = BTreeSet::new();
+        if self.capabilities.iter().any(|entry| {
+            !valid_identifier(&entry.capability)
+                || !valid_versions(&entry.versions)
+                || !capabilities.insert(entry.capability.as_str())
+        }) {
+            return false;
+        }
+        let mut permissions = BTreeSet::new();
+        !self.permissions.iter().any(|permission| {
+            !valid_identifier(permission) || !permissions.insert(permission.as_str())
+        })
+    }
+
+    #[must_use]
+    pub fn supports_capability(&self, capability: &str, version: u32) -> bool {
+        self.capabilities
+            .iter()
+            .any(|entry| entry.capability == capability && entry.versions.contains(&version))
+    }
+
+    #[must_use]
+    pub fn supports_permission(&self, permission: &str) -> bool {
+        self.permissions.iter().any(|entry| entry == permission)
+    }
+}
+
+fn valid_versions(versions: &[u32]) -> bool {
+    !versions.is_empty()
+        && versions.len() <= 16
+        && versions.iter().all(|version| *version > 0)
+        && versions.iter().collect::<BTreeSet<_>>().len() == versions.len()
+}
+
+fn valid_identifier(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 64
+        && value.bytes().all(|byte| {
+            byte.is_ascii_lowercase() || byte.is_ascii_digit() || matches!(byte, b'_' | b'-')
+        })
+}
+
+pub(crate) fn valid_plugin_id(value: &str) -> bool {
+    if value.len() > 64 {
+        return false;
+    }
+    let Some((publisher, name)) = value.split_once('.') else {
+        return false;
+    };
+    valid_plugin_segment(publisher) && valid_plugin_segment(name)
+}
+
+fn valid_plugin_segment(value: &str) -> bool {
+    value
+        .as_bytes()
+        .first()
+        .is_some_and(u8::is_ascii_alphanumeric)
+        && value
+            .as_bytes()
+            .last()
+            .is_some_and(u8::is_ascii_alphanumeric)
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
+}
+
+/// 已安装包对目标宿主的静态要求；不包含包体、配置或 secret。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginCompatibilityRequirements {
+    pub host_version: String,
+    pub manifest_schema_version: u32,
+    pub protocol_version: u32,
+    pub capabilities: Vec<(String, u32)>,
+    pub permissions: Vec<String>,
+}
+
+/// 一次下载使用的非敏感出站代理身份；地址与认证由受管代理记录持有。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginSourceEgress {
+    pub id: String,
+    pub revision: u64,
+}
+
+/// 安装来源只保存公开定位信息，下载凭据和出站代理通过独立记录引用。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub enum PluginSource {
+    Builtin {
+        release: String,
+    },
+    Upload,
+    Url {
+        url: String,
+        credential_ids: Vec<String>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        outbound_proxy: Option<PluginSourceEgress>,
+    },
+    Github {
+        repository: String,
+        tag: String,
+        asset: String,
+        credential_ids: Vec<String>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        outbound_proxy: Option<PluginSourceEgress>,
+    },
+}
+
+impl PluginSource {
+    #[must_use]
+    pub fn credential_ids(&self) -> &[String] {
+        match self {
+            Self::Url { credential_ids, .. } | Self::Github { credential_ids, .. } => {
+                credential_ids
+            }
+            Self::Builtin { .. } | Self::Upload => &[],
+        }
+    }
+
+    #[must_use]
+    pub const fn outbound_proxy(&self) -> Option<&PluginSourceEgress> {
+        match self {
+            Self::Url { outbound_proxy, .. } | Self::Github { outbound_proxy, .. } => {
+                outbound_proxy.as_ref()
+            }
+            Self::Builtin { .. } | Self::Upload => None,
+        }
+    }
+}
+
+/// 管理端保留的单项贡献声明；map key 是能力标识，`id` 是实例绑定引用的扩展项身份。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginContribution {
+    pub id: String,
+    pub version: u32,
+    pub stages: Vec<String>,
+    pub input_formats: Vec<String>,
+    pub output_formats: Vec<String>,
+}
+
+/// 制品清单中的展示图标；路径只用于选择已校验的包资源。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum PluginArtifactIcon {
+    Path(String),
+    Themed(PluginArtifactIconVariants),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PluginArtifactIconVariants {
+    pub light: String,
+    pub dark: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PluginIconTheme {
+    Light,
+    Dark,
+}
+
+/// 从不可变制品中读取的已校验图标字节。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginArtifactIconResource {
+    pub content_type: String,
+    pub body: Vec<u8>,
+}
+
+/// 管理端使用的静态描述，不承载 SDK 的运行时消息或宿主实现类型。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginPermissionDescription {
+    pub permission: String,
+    pub label: String,
+    pub description: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginArtifactMetadata {
+    pub plugin_id: String,
+    pub version: String,
+    pub name: String,
+    pub display_name: String,
+    pub publisher: String,
+    pub author: Option<String>,
+    pub description: String,
+    pub license: String,
+    pub sha256: String,
+    pub platforms: Vec<String>,
+    #[serde(default)]
+    pub icon: Option<PluginArtifactIcon>,
+    pub contributes: BTreeMap<String, PluginContribution>,
+    pub requested_permissions: Vec<String>,
+    pub configuration_schema: serde_json::Value,
+    pub secret_fields: Vec<String>,
+    #[serde(default)]
+    pub state_namespaces: Vec<state::PluginStateSchema>,
+}
+
+/// 由包检查端口产生的不可变制品；不派生 Debug，包内可能含敏感用户数据。
+#[derive(Clone)]
+pub struct InspectedPluginArtifact {
+    pub metadata: PluginArtifactMetadata,
+    pub archive: Arc<[u8]>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct InstalledPluginArtifact {
+    pub metadata: PluginArtifactMetadata,
+    pub source: PluginSource,
+    pub installed_at: chrono::DateTime<chrono::Utc>,
+    pub accepted_at: Option<chrono::DateTime<chrono::Utc>>,
+}
+
+pub struct PluginArtifactMutation {
+    pub config_revision: Revision,
+    pub artifact: InstalledPluginArtifact,
+}
+
+pub struct PluginInstallResult {
+    pub mutation: PluginArtifactMutation,
+    pub default_instance_id: Option<String>,
+    pub configuration_required: bool,
+}

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

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

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

@@ -0,0 +1,205 @@
+use std::{collections::BTreeMap, fmt};
+
+use serde::{Deserialize, Serialize};
+
+use crate::model::Revision;
+
+/// 已由 Runtime 校验的命名空间 schema 与配额事实。
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginStateSchema {
+    pub namespace: String,
+    pub schema_version: u32,
+    pub schema_sha256: String,
+    pub schema: serde_json::Value,
+    pub maximum_records: u32,
+    pub maximum_bytes: u64,
+    pub maximum_value_bytes: u32,
+    #[serde(default)]
+    pub migrates_from: Vec<u32>,
+}
+
+impl fmt::Debug for PluginStateSchema {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("PluginStateSchema")
+            .field("namespace", &self.namespace)
+            .field("schema_version", &self.schema_version)
+            .field("schema_sha256", &self.schema_sha256)
+            .field("schema", &"[REDACTED]")
+            .field("maximum_records", &self.maximum_records)
+            .field("maximum_bytes", &self.maximum_bytes)
+            .field("maximum_value_bytes", &self.maximum_value_bytes)
+            .field("migrates_from", &self.migrates_from)
+            .finish()
+    }
+}
+
+#[derive(Clone, Default, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PluginStateConfiguration {
+    #[serde(default)]
+    pub namespaces: Vec<PluginStateSchema>,
+}
+
+/// 与实例保存同事务提交的状态配置；transition 只引用已完成的 staging 数据。
+#[derive(Clone, Default)]
+pub struct PluginStateCommit {
+    pub configuration: PluginStateConfiguration,
+    pub transition_id: Option<String>,
+}
+
+#[derive(Clone)]
+pub struct PluginStateOwnerRequest {
+    pub instance_id: String,
+    pub artifact_sha256: String,
+    pub instance_revision: Revision,
+    pub configuration: PluginStateConfiguration,
+}
+
+/// Store 签发的实例私有状态 fence。插件协议中从不传输这些字段。
+#[derive(Clone)]
+pub struct PluginStateOwner {
+    instance_id: String,
+    artifact_sha256: String,
+    instance_revision: Revision,
+    namespaces: BTreeMap<String, PluginStateNamespaceOwner>,
+}
+
+#[derive(Clone)]
+pub struct PluginStateNamespaceOwner {
+    generation_id: String,
+    fence: String,
+    schema_version: u32,
+}
+
+impl PluginStateOwner {
+    #[must_use]
+    pub fn from_store(
+        instance_id: String,
+        artifact_sha256: String,
+        instance_revision: Revision,
+        namespaces: BTreeMap<String, PluginStateNamespaceOwner>,
+    ) -> Self {
+        Self {
+            instance_id,
+            artifact_sha256,
+            instance_revision,
+            namespaces,
+        }
+    }
+
+    #[must_use]
+    pub fn instance_id(&self) -> &str {
+        &self.instance_id
+    }
+
+    #[must_use]
+    pub fn artifact_sha256(&self) -> &str {
+        &self.artifact_sha256
+    }
+
+    #[must_use]
+    pub const fn instance_revision(&self) -> Revision {
+        self.instance_revision
+    }
+
+    #[must_use]
+    pub fn namespace(&self, namespace: &str) -> Option<&PluginStateNamespaceOwner> {
+        self.namespaces.get(namespace)
+    }
+}
+
+impl PluginStateNamespaceOwner {
+    #[must_use]
+    pub fn from_store(generation_id: String, fence: String, schema_version: u32) -> Self {
+        Self {
+            generation_id,
+            fence,
+            schema_version,
+        }
+    }
+
+    #[must_use]
+    pub fn generation_id(&self) -> &str {
+        &self.generation_id
+    }
+
+    #[must_use]
+    pub fn fence(&self) -> &str {
+        &self.fence
+    }
+
+    #[must_use]
+    pub const fn schema_version(&self) -> u32 {
+        self.schema_version
+    }
+}
+
+/// 私有值可能含插件自己的敏感状态，故意不实现 `Debug`。
+#[derive(Clone)]
+pub struct PluginStateRecord {
+    pub key: String,
+    pub value: serde_json::Value,
+    pub version: u64,
+    pub schema_version: u32,
+}
+
+pub struct PutPluginState {
+    pub namespace: String,
+    pub key: String,
+    pub value: serde_json::Value,
+    /// `None` 是 create-only；已有记录必须提交精确版本。
+    pub expected_version: Option<u64>,
+}
+
+pub struct DeletePluginState {
+    pub namespace: String,
+    pub key: String,
+    pub expected_version: u64,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PluginStateWrite {
+    pub version: u64,
+}
+
+#[derive(Clone)]
+pub struct PluginStateTransition {
+    pub id: String,
+    pub instance_id: String,
+    pub artifact_sha256: String,
+    pub namespaces: Vec<PluginStateMigrationNamespace>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginStateMigrationNamespace {
+    pub namespace: String,
+    pub from_schema_version: u32,
+    pub to_schema_version: u32,
+}
+
+pub struct PluginStateMigrationBatch {
+    pub cursor: Option<String>,
+    pub records: Vec<PluginStateRecord>,
+}
+
+pub struct ApplyPluginStateMigration {
+    pub transition_id: String,
+    pub namespace: String,
+    pub cursor: Option<String>,
+    /// Runtime 刚读取的有序源键；Store 会在写入前重新读取并逐项比对。
+    pub expected_keys: Vec<String>,
+    pub changes: Vec<PluginStateMigrationChange>,
+}
+
+pub struct PluginStateMigrationChange {
+    pub key: String,
+    pub action: PluginStateMigrationAction,
+}
+
+pub enum PluginStateMigrationAction {
+    Keep,
+    Replace(serde_json::Value),
+    Delete,
+}

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

@@ -0,0 +1,52 @@
+//! 全局模型定价的管理合同。
+
+use gateway_core::metering::{ModelPriceOverride, PricingOverrides};
+use std::collections::{BTreeMap, BTreeSet};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PricingCatalog {
+    pub defaults: PricingOverrides,
+    pub overrides: PricingOverrides,
+    pub synced: PricingOverrides,
+    pub synced_at: Option<chrono::DateTime<chrono::Utc>>,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct StoredPricing {
+    pub overrides: PricingOverrides,
+    pub synced: PricingOverrides,
+    pub synced_at: Option<chrono::DateTime<chrono::Utc>>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct PricingSyncPreview {
+    pub prices: PricingOverrides,
+    pub skipped: Vec<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct SyncPricing {
+    pub preview: PricingSyncPreview,
+    pub models: BTreeMap<String, BTreeSet<String>>,
+}
+
+pub type PricingSyncChanges = BTreeMap<String, BTreeMap<String, Option<ModelPriceOverride>>>;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PricingChange {
+    Replace(ModelPriceOverride),
+    Multiplier(u32),
+    Reset,
+    Delete,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UpdatePricing {
+    pub provider: String,
+    pub models: Vec<String>,
+    pub change: PricingChange,
+}
+
+pub type ProviderPricingCatalog = BTreeMap<String, ModelPriceOverride>;

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

@@ -0,0 +1,179 @@
+//! 可复用的账号出口配置，以及脱敏后的连通性测试结果。
+
+use chrono::{DateTime, Utc};
+use gateway_core::account::{OutboundProxy, RequestLocation};
+use serde::{Deserialize, Serialize};
+
+use super::{PageSize, Revision, account_groups::AccountGroupRef};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AccountProxySelection {
+    Direct,
+    Url(OutboundProxy),
+    Saved(String),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ImportProxyBinding {
+    pub id: String,
+    pub proxy: OutboundProxy,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyListQuery {
+    pub page: u32,
+    pub page_size: PageSize,
+    pub search: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProxyAccountRef {
+    pub id: String,
+    pub name: String,
+    pub email: Option<String>,
+    pub provider_kind: String,
+    pub authentication_kind: String,
+    pub plan_type: Option<String>,
+    pub plan_type_display: Option<String>,
+    pub groups: Vec<AccountGroupRef>,
+    pub enabled: bool,
+}
+
+/// 按代理查询关联账号，分页与搜索均在存储层执行。
+#[derive(Debug, Clone)]
+pub struct ProxyAccountListQuery {
+    pub proxy_id: String,
+    pub page: u32,
+    pub page_size: PageSize,
+    pub search: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyAccountPage {
+    pub items: Vec<ProxyAccountRef>,
+    pub total: u64,
+    pub page: u32,
+    pub page_size: u16,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProxyTestResult {
+    pub location: ProxyLocationDetection,
+    pub success: bool,
+    pub latency_ms: u64,
+    pub exit_ip: Option<std::net::IpAddr>,
+    pub exit_ipv4: Option<std::net::Ipv4Addr>,
+    pub exit_ipv6: Option<std::net::Ipv6Addr>,
+    pub message: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyRecord {
+    pub auto_location: bool,
+    pub detected_location: Option<DetectedProxyLocation>,
+    pub location: Option<gateway_core::account::RequestLocation>,
+    pub id: String,
+    pub name: String,
+    pub proxy: OutboundProxy,
+    pub revision: Revision,
+    pub account_count: u64,
+    pub last_test_at: Option<DateTime<Utc>>,
+    pub last_test: Option<ProxyTestResult>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyPage {
+    pub items: Vec<ProxyRecord>,
+    pub total: u64,
+    pub page: u32,
+    pub page_size: u16,
+}
+
+#[derive(Debug, Clone)]
+pub struct NewProxy {
+    pub auto_location: bool,
+    /// 由管理用例探测，随配置原子保存，不接受 HTTP 调用方提供结果。
+    pub test: Option<ProxyTestResult>,
+    pub location: Option<gateway_core::account::RequestLocation>,
+    pub name: String,
+    pub proxy: OutboundProxy,
+}
+
+#[derive(Debug, Clone)]
+pub struct UpdateProxy {
+    pub auto_location: Option<bool>,
+    pub test: Option<ProxyTestResult>,
+    /// 外层为空保留配置，内层为空恢复全局继承。
+    pub location: Option<Option<gateway_core::account::RequestLocation>>,
+    pub id: String,
+    pub revision: Revision,
+    pub name: String,
+    pub proxy: Option<OutboundProxy>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyMutation {
+    pub config_revision: Revision,
+    pub record: ProxyRecord,
+}
+
+/// 检测失败与连通性分开，双栈冲突不得继续应用旧位置。
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(tag = "status", rename_all = "camelCase")]
+pub enum ProxyLocationDetection {
+    #[default]
+    NotRequested,
+    Detected {
+        location: RequestLocation,
+    },
+    Failed {
+        message: String,
+    },
+    Conflict,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DetectedProxyLocation {
+    pub location: RequestLocation,
+    pub exit_ipv4: Option<std::net::Ipv4Addr>,
+    pub exit_ipv6: Option<std::net::Ipv6Addr>,
+    pub detected_at: DateTime<Utc>,
+}
+
+impl ProxyRecord {
+    #[must_use]
+    pub fn effective_location(&self) -> Option<&RequestLocation> {
+        if self.auto_location {
+            self.detected_location
+                .as_ref()
+                .map(|detected| &detected.location)
+        } else {
+            self.location.as_ref()
+        }
+    }
+
+    /// 未知出口可暂用上次成功结果，已知出口变化或时区冲突必须撤销旧覆盖。
+    #[must_use]
+    pub fn detected_location_after_test(
+        &self,
+        result: &ProxyTestResult,
+    ) -> Option<DetectedProxyLocation> {
+        match &result.location {
+            ProxyLocationDetection::Detected { location } => Some(DetectedProxyLocation {
+                location: location.clone(),
+                exit_ipv4: result.exit_ipv4,
+                exit_ipv6: result.exit_ipv6,
+                detected_at: Utc::now(),
+            }),
+            ProxyLocationDetection::Failed { .. } => self.detected_location.clone().filter(|old| {
+                !result.success
+                    || (old.exit_ipv4 == result.exit_ipv4 && old.exit_ipv6 == result.exit_ipv6)
+            }),
+            ProxyLocationDetection::Conflict => None,
+            ProxyLocationDetection::NotRequested => self.detected_location.clone(),
+        }
+    }
+}

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

@@ -0,0 +1,221 @@
+//! 账号额度的只读容量估算，不参与金额结算或账号调度。
+
+use chrono::{DateTime, Duration, Utc};
+
+use super::provider_credentials::{AccountUsagePeriod, ProviderQuota, ProviderQuotaWindow};
+use super::quota_forecast_sampling::{QuotaForecastMethod, QuotaForecastSample};
+
+const DAY_SECONDS: u64 = 86_400;
+const MIN_USED_PERCENT: f64 = 5.0;
+const LOW_SAMPLE_PERCENT: f64 = 10.0;
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct AccountQuotaForecastReport {
+    pub account_id: String,
+    pub generated_at: DateTime<Utc>,
+    pub forecasts: [AccountQuotaForecast; 2],
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct AccountQuotaForecast {
+    pub period: AccountUsagePeriod,
+    pub target_seconds: u64,
+    pub extrapolated: bool,
+    pub source: Option<QuotaForecastSource>,
+    pub unavailable_reason: Option<&'static str>,
+    pub low_sample: bool,
+    pub incomplete_cost: bool,
+    pub incomplete_tokens: bool,
+    pub estimated_tokens: Option<u64>,
+    pub estimated_usd: Option<f64>,
+    /// 剩余估算始终属于源窗口，不随目标周期折算。
+    pub remaining_tokens: Option<u64>,
+    pub remaining_usd: Option<f64>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct QuotaForecastSource {
+    pub label: String,
+    pub used_percent: Option<f64>,
+    pub observed_at: Option<DateTime<Utc>>,
+    pub reset_at: DateTime<Utc>,
+    pub tokens: Option<u64>,
+    pub usd: Option<f64>,
+}
+
+/// 为目标周期选择唯一的预测源窗口；缺少同周期窗口时复用最短的可统计窗口。
+///
+/// Admin 的历史查询与最终投影必须共用这里的顺序，避免查询不会进入响应的窗口。
+pub(crate) fn quota_forecast_source_window(
+    quota: &ProviderQuota,
+    period: AccountUsagePeriod,
+) -> Option<(&ProviderQuotaWindow, AccountUsagePeriod)> {
+    quota
+        .usage_windows()
+        .find(|(_, source_period)| *source_period == period)
+        .or_else(|| quota.usage_windows().min_by_key(|(_, period)| *period))
+}
+
+/// 优先预测真实的对应窗口；缺少对应周期时只给出明确标识的 7/30 天容量折算。
+/// 本地日志不能证明站外消耗或完整留存，因此即使样本充足也不声称官方额度。
+#[must_use]
+pub fn account_quota_forecasts(
+    quota: &ProviderQuota,
+    account_added_at: DateTime<Utc>,
+    now: DateTime<Utc>,
+    samples: &[QuotaForecastSample],
+) -> [AccountQuotaForecast; 2] {
+    [AccountUsagePeriod::Weekly, AccountUsagePeriod::Monthly].map(|period| {
+        let selected = quota_forecast_source_window(quota, period);
+        let mut forecast = AccountQuotaForecast {
+            period,
+            target_seconds: match period {
+                AccountUsagePeriod::Weekly => 7 * DAY_SECONDS,
+                AccountUsagePeriod::Monthly => 30 * DAY_SECONDS,
+            },
+            extrapolated: false,
+            source: None,
+            unavailable_reason: Some("没有可统计的周/月额度窗口，请先刷新账号额度。"),
+            low_sample: false,
+            incomplete_cost: false,
+            incomplete_tokens: false,
+            estimated_tokens: None,
+            estimated_usd: None,
+            remaining_tokens: None,
+            remaining_usd: None,
+        };
+        if let Some((window, source_period)) = selected {
+            forecast.project(
+                window,
+                source_period,
+                quota.observed_at,
+                account_added_at,
+                now,
+                samples.iter().find(|sample| sample.key == window.key),
+            );
+        }
+        forecast
+    })
+}
+
+impl AccountQuotaForecast {
+    fn project(
+        &mut self,
+        window: &ProviderQuotaWindow,
+        source_period: AccountUsagePeriod,
+        observed_at: Option<DateTime<Utc>>,
+        account_added_at: DateTime<Utc>,
+        now: DateTime<Utc>,
+        sample: Option<&QuotaForecastSample>,
+    ) {
+        let (Some(seconds), Some(reset_at)) = (window.window_seconds, window.reset_at) else {
+            return;
+        };
+        self.extrapolated = source_period != self.period;
+        if !self.extrapolated {
+            self.target_seconds = seconds;
+        }
+        let percent = window
+            .used_percent
+            .filter(|p| p.is_finite() && (0.0..=100.0).contains(p));
+        let usage = sample.map(|sample| &sample.cycle_usage);
+        let usd = usage
+            .filter(|usage| usage.known_cost_count > 0)
+            .map(|usage| usage.usd)
+            .filter(|value| value.is_finite() && *value >= 0.0);
+        let start = i64::try_from(seconds)
+            .ok()
+            .and_then(Duration::try_seconds)
+            .and_then(|duration| reset_at.checked_sub_signed(duration));
+        self.source = Some(QuotaForecastSource {
+            label: window.label.clone(),
+            used_percent: percent,
+            observed_at,
+            reset_at,
+            tokens: usage.map(|usage| usage.tokens),
+            usd,
+        });
+        self.incomplete_cost = usage.is_none_or(|usage| {
+            usage.unavailable_cost_count > 0
+                || usage.known_cost_count == 0
+                || usage.known_cost_count != usage.request_count
+        });
+        self.incomplete_tokens = usage.is_some_and(|usage| usage.missing_token_count > 0);
+        let method = sample.map_or(QuotaForecastMethod::Cumulative, |sample| sample.method);
+        let Some(start) = start.filter(|start| *start <= now && now < reset_at) else {
+            self.unavailable_reason = Some("额度窗口已过期或边界无效，请刷新账号额度后重试。");
+            return;
+        };
+        if !observed_at.is_some_and(|observed| start <= observed && observed <= now) {
+            self.unavailable_reason = Some("缺少本周期的额度快照，请先刷新账号额度。");
+            return;
+        }
+        if sample.is_some_and(|sample| sample.discontinuous) {
+            self.unavailable_reason =
+                Some("额度观测出现回落或累计记录不连续，正在重新积累配对样本。");
+            return;
+        }
+        if account_added_at > start && method == QuotaForecastMethod::Cumulative {
+            self.unavailable_reason = Some(
+                "本周期开始时的记录不完整，正在积累至少 5 个百分点的配对观测，无需等待下次重置。",
+            );
+            return;
+        }
+        let Some(percent) = percent else {
+            self.unavailable_reason = Some("已用比例未知，请刷新额度后查看预测。");
+            return;
+        };
+        let Some(usage) = usage.filter(|usage| usage.request_count > 0) else {
+            self.unavailable_reason = Some("本周期没有网关用量记录，暂时无法预测额度。");
+            return;
+        };
+        let Some(sample) = sample.filter(|sample| {
+            sample.end_at == observed_at.unwrap_or(now)
+                && start <= sample.start_at
+                && sample.start_at <= sample.end_at
+                && sample.sampled_percent.is_finite()
+                && sample.sampled_percent >= MIN_USED_PERCENT
+                && sample.sampled_percent <= percent
+        }) else {
+            self.unavailable_reason =
+                Some("有效额度进度不足 5 个百分点或采样边界无效，请继续积累用量。");
+            return;
+        };
+        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)
+            .filter(|tokens| *tokens > 0)
+            .and_then(|value| estimate(value as f64, remaining_factor));
+        self.remaining_tokens = remaining_tokens.and_then(|value| estimate_tokens(value, 1.0));
+        self.estimated_tokens = remaining_tokens
+            .and_then(|remaining| estimate_tokens(usage.tokens as f64 + remaining, factor));
+        self.remaining_usd = Some(&sample.usage)
+            .filter(|usage| usage.known_cost_count > 0 && usage.usd.is_finite() && usage.usd >= 0.0)
+            .and_then(|usage| estimate(usage.usd, remaining_factor));
+        self.estimated_usd = usd
+            .zip(self.remaining_usd)
+            .and_then(|(used, remaining)| estimate(used + remaining, factor));
+        self.unavailable_reason = if self.estimated_tokens.is_none() && self.estimated_usd.is_none()
+        {
+            Some("本周期暂无可用于估算的 Token 或费用数据，请积累用量后重试。")
+        } else {
+            None
+        };
+    }
+}
+
+fn estimate(value: f64, factor: f64) -> Option<f64> {
+    let estimate = value * factor;
+    (estimate.is_finite() && estimate >= 0.0).then_some(estimate)
+}
+
+fn estimate_tokens(value: f64, factor: f64) -> Option<u64> {
+    estimate(value, factor)
+        .filter(|value| value.round() < u64::MAX as f64)
+        .map(|value| value.round() as u64)
+}

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

@@ -0,0 +1,204 @@
+//! 预测专用的配对采样；不改变完整交付用量或费用账本的统计口径。
+
+use chrono::{DateTime, Utc};
+
+use super::provider_credentials::ProviderDocument;
+
+/// 限制带 Provider 文档的历史点数量；累计用量仍覆盖整个查询区间。
+pub const MAX_FORECAST_HISTORY_POINTS: usize = 128;
+const MIN_BLOCK_PERCENT: f64 = 5.0;
+const RECENT_BLOCKS: usize = 3;
+
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct QuotaForecastUsage {
+    pub request_count: u64,
+    pub tokens: u64,
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    pub cached_tokens: u64,
+    pub missing_token_count: u64,
+    pub known_cost_count: u64,
+    pub unavailable_cost_count: u64,
+    pub usd: f64,
+    pub excluded_request_count: u64,
+}
+
+impl QuotaForecastUsage {
+    /// 累计计数倒退表示不能配对，不用饱和减法掩盖数据断点。
+    fn difference(&self, baseline: &Self) -> Option<Self> {
+        let usd = self.usd - baseline.usd;
+        if !usd.is_finite() || usd < -1e-9 {
+            return None;
+        }
+        Some(Self {
+            request_count: self.request_count.checked_sub(baseline.request_count)?,
+            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)?,
+            missing_token_count: self
+                .missing_token_count
+                .checked_sub(baseline.missing_token_count)?,
+            known_cost_count: self
+                .known_cost_count
+                .checked_sub(baseline.known_cost_count)?,
+            unavailable_cost_count: self
+                .unavailable_cost_count
+                .checked_sub(baseline.unavailable_cost_count)?,
+            usd: usd.max(0.0),
+            excluded_request_count: self
+                .excluded_request_count
+                .checked_sub(baseline.excluded_request_count)?,
+        })
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct QuotaForecastHistoryPoint {
+    pub started_at: DateTime<Utc>,
+    pub completed_at: DateTime<Utc>,
+    pub usage: QuotaForecastUsage,
+    pub provider_observation: ProviderDocument,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct QuotaForecastHistory {
+    pub points: Vec<QuotaForecastHistoryPoint>,
+    pub usage: QuotaForecastUsage,
+    pub pending_request_count: u64,
+}
+
+/// 具体 Provider 从自己的历史文档解释出的额度事实。
+#[derive(Debug, Clone, PartialEq)]
+pub struct QuotaForecastObservation {
+    pub used_percent: f64,
+    pub reset_at: DateTime<Utc>,
+    pub plan_type: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct QuotaForecastPoint {
+    pub observed_at: DateTime<Utc>,
+    pub used_percent: f64,
+    pub usage: QuotaForecastUsage,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum QuotaForecastMethod {
+    Cumulative,
+    Incremental,
+}
+
+#[derive(Debug, Clone)]
+pub struct QuotaForecastSample {
+    pub key: String,
+    pub method: QuotaForecastMethod,
+    pub start_at: DateTime<Utc>,
+    pub end_at: DateTime<Utc>,
+    pub baseline_percent: f64,
+    pub sampled_percent: f64,
+    pub block_count: usize,
+    pub observation_count: usize,
+    pub pending_request_count: u64,
+    pub discontinuous: bool,
+    /// 本周期已记录用量；近期采样仅用于预测剩余量，不能覆盖这份累计值。
+    pub cycle_usage: QuotaForecastUsage,
+    pub usage: QuotaForecastUsage,
+}
+
+/// 对同一额度段的累计点形成至少 5 个百分点的连续块，使用最近三个完整块及尾部。
+/// 不平均逐请求比值；重复百分比不增加块数，5/10 个百分点仅是量化噪声门槛。
+#[must_use]
+pub fn select_forecast_sample(
+    key: String,
+    start_at: DateTime<Utc>,
+    current: QuotaForecastPoint,
+    mut history: Vec<QuotaForecastPoint>,
+    pending_request_count: u64,
+    interrupted: bool,
+) -> QuotaForecastSample {
+    history.retain(|point| {
+        start_at <= point.observed_at
+            && point.observed_at < current.observed_at
+            && point.used_percent.is_finite()
+            && (0.0..=100.0).contains(&point.used_percent)
+    });
+    history.sort_by_key(|point| point.observed_at);
+    let mut sample = QuotaForecastSample {
+        key,
+        method: QuotaForecastMethod::Cumulative,
+        start_at,
+        end_at: current.observed_at,
+        baseline_percent: 0.0,
+        sampled_percent: current.used_percent,
+        block_count: 0,
+        observation_count: history.len(),
+        pending_request_count,
+        discontinuous: interrupted,
+        cycle_usage: current.usage.clone(),
+        usage: current.usage.clone(),
+    };
+    history.push(current);
+    // 重置边界不在查询起点时，从首个新观测重新计数，避免把旧周期累计带入总量。
+    let mut cycle_baseline = interrupted.then(|| &history[0]);
+    let mut anchors: Vec<&QuotaForecastPoint> = Vec::new();
+    let mut high_water: Option<&QuotaForecastPoint> = None;
+    for point in &history {
+        if let Some(previous) = high_water {
+            if point.observed_at <= previous.observed_at {
+                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);
+        if anchors
+            .last()
+            .is_none_or(|anchor| point.used_percent - anchor.used_percent >= MIN_BLOCK_PERCENT)
+        {
+            anchors.push(point);
+        }
+    }
+    let Some(current) = history.last() else {
+        return sample;
+    };
+    if let Some(baseline) = cycle_baseline {
+        let Some(usage) = current.usage.difference(&baseline.usage) else {
+            sample.discontinuous = true;
+            return sample;
+        };
+        sample.cycle_usage = usage;
+    }
+    if anchors.len() < 2 {
+        return sample;
+    }
+    let baseline_index = anchors.len().saturating_sub(RECENT_BLOCKS + 1);
+    let baseline = anchors[baseline_index];
+    let progress = current.used_percent - baseline.used_percent;
+    if !progress.is_finite() || progress < MIN_BLOCK_PERCENT {
+        return sample;
+    }
+    let Some(usage) = current.usage.difference(&baseline.usage) else {
+        sample.discontinuous = true;
+        return sample;
+    };
+    if usage.request_count == 0 {
+        return sample;
+    }
+    sample.method = QuotaForecastMethod::Incremental;
+    sample.start_at = baseline.observed_at;
+    sample.baseline_percent = baseline.used_percent;
+    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/settings.rs

@@ -0,0 +1,156 @@
+//! Runtime settings 与明文管理员 API Key 的语义模型。
+
+use std::{collections::BTreeMap, fmt};
+
+use chrono::{DateTime, Utc};
+
+use gateway_core::routing::{ProviderKind, PublicModelId, UpstreamModelId};
+
+use super::Revision;
+
+/// 客户端模型到上游模型的全局精确映射。
+pub type ModelMappings = BTreeMap<PublicModelId, UpstreamModelId>;
+
+/// Provider-owned 请求画像选择；Provider ID 是唯一命名空间。
+pub type ProviderRequestProfiles =
+    BTreeMap<ProviderKind, gateway_core::account::OpaqueProviderData>;
+
+/// Provider-owned 请求画像的部分更新；`None` 只表示显式删除该 Provider 的历史选择。
+pub type ProviderRequestProfileUpdates =
+    BTreeMap<ProviderKind, Option<gateway_core::account::OpaqueProviderData>>;
+
+/// 账号调度策略；由 Core 拥有稳定值与 wire 映射。
+pub use gateway_core::account::RotationStrategy;
+
+/// 完整运行设置事实。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RuntimeSettings {
+    pub 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)]
+pub struct ReplaceRuntimeSettings {
+    /// 只覆盖提交的 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 泄漏。
+#[derive(Clone, PartialEq, Eq)]
+pub struct AdminApiKey(String);
+
+impl AdminApiKey {
+    #[must_use]
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(value.into())
+    }
+
+    #[must_use]
+    pub fn expose_for_auth(&self) -> &str {
+        &self.0
+    }
+
+    /// 仅供显式 regenerate 响应读取一次。
+    #[must_use]
+    pub fn expose_for_response(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Debug for AdminApiKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("AdminApiKey([REDACTED])")
+    }
+}
+
+/// 管理员 API Key 更新结果。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AdminApiKeyMutation {
+    pub config_revision: Revision,
+    pub exists: bool,
+}
+
+/// 新管理员 API Key 的一次性返回结果。
+pub struct RegeneratedAdminApiKey {
+    pub mutation: AdminApiKeyMutation,
+    pub key: AdminApiKey,
+}
+
+impl fmt::Debug for RegeneratedAdminApiKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("RegeneratedAdminApiKey")
+            .field("mutation", &self.mutation)
+            .field("key", &"[REDACTED]")
+            .finish()
+    }
+}
+
+impl RuntimeSettings {
+    pub fn client_profile(
+        &self,
+        provider: &str,
+    ) -> Option<&gateway_core::account::OpaqueProviderData> {
+        ProviderKind::new(provider.to_owned())
+            .ok()
+            .and_then(|provider| self.request_profiles.get(&provider))
+    }
+}

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

@@ -0,0 +1,164 @@
+//! 版本、自更新、回滚与进程重启的 UTC 语义模型。
+
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+/// 本次检查或安装选择的更新稳定性范围，具体版本准入由 Host 判定。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum SystemUpdateChannel {
+    Stable,
+    Alpha,
+    Beta,
+    Rc,
+    #[serde(rename = "exp")]
+    Experimental,
+}
+
+impl SystemUpdateChannel {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Stable => "stable",
+            Self::Alpha => "alpha",
+            Self::Beta => "beta",
+            Self::Rc => "rc",
+            Self::Experimental => "exp",
+        }
+    }
+}
+
+/// Host 返回的本次检查通道及当前构建允许选择的范围。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SystemUpdatePolicy {
+    pub channel: SystemUpdateChannel,
+    pub available_channels: Vec<SystemUpdateChannel>,
+}
+
+/// 当前运行版本及更新检查摘要。
+///
+/// `deployment_mode_label` 之类的本地化字符串由 API 根据原始枚举值生成。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SystemVersion {
+    pub version: String,
+    pub git_sha: String,
+    pub build_time: String,
+    pub deployment_mode: String,
+    pub update_channel: String,
+    pub latest_version: String,
+    pub has_update: bool,
+    pub update_cached: bool,
+    pub update_warning: Option<String>,
+}
+
+/// 发布源提供的完整更新详情。
+///
+/// 部署模式与构建类型的展示标签归 API；其余字段均为 Host 已确认的原始事实。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SystemUpdateDetail {
+    pub policy: SystemUpdatePolicy,
+    pub current_version: String,
+    pub latest_version: String,
+    pub has_update: bool,
+    pub deployment_mode: String,
+    pub build_type: String,
+    pub release_url: Option<String>,
+    pub notes: Option<String>,
+    pub cached: bool,
+    pub update_supported: bool,
+    pub unsupported_reason: Option<String>,
+    pub warning: Option<String>,
+}
+
+/// 系统操作类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SystemOperationKind {
+    Update,
+    Rollback,
+    Restart,
+}
+
+/// 系统操作状态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SystemOperationStatus {
+    Idle,
+    Running,
+    Succeeded,
+    Failed,
+}
+
+/// 持久化系统操作的完整状态。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SystemOperationState {
+    pub operation_id: Option<String>,
+    pub kind: Option<SystemOperationKind>,
+    pub status: SystemOperationStatus,
+    pub target_version: Option<String>,
+    pub message: Option<String>,
+    pub error: Option<String>,
+    pub started_at: Option<DateTime<Utc>>,
+    pub finished_at: Option<DateTime<Utc>>,
+}
+
+/// 最近一次系统操作及版本交换状态。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SystemUpdateStatus {
+    pub previous_version: Option<String>,
+    pub current_version: Option<String>,
+    pub need_restart: bool,
+    pub operation: SystemOperationState,
+}
+
+/// 自更新日志级别。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SystemUpdateEventLevel {
+    Info,
+    Warning,
+    Success,
+    Error,
+}
+
+/// 一条已脱敏的系统更新事件。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SystemUpdateEvent {
+    pub id: String,
+    pub operation_id: Option<String>,
+    pub level: SystemUpdateEventLevel,
+    pub step: Option<String>,
+    pub message: String,
+    pub terminal: bool,
+    pub progress_percent: Option<u8>,
+    pub occurred_at: DateTime<Utc>,
+}
+
+/// 已受理的异步系统操作；不同 wire shape 由枚举保持为合法状态。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum SystemOperationAccepted {
+    Update {
+        operation_id: String,
+        deployment_mode: String,
+        message: String,
+        target_version: String,
+    },
+    Rollback {
+        operation_id: String,
+        message: String,
+        need_restart: bool,
+    },
+    Restart {
+        operation_id: String,
+        message: String,
+    },
+}
+
+impl SystemOperationAccepted {
+    #[must_use]
+    pub const fn kind(&self) -> SystemOperationKind {
+        match self {
+            Self::Update { .. } => SystemOperationKind::Update,
+            Self::Rollback { .. } => SystemOperationKind::Rollback,
+            Self::Restart { .. } => SystemOperationKind::Restart,
+        }
+    }
+}

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

@@ -0,0 +1,442 @@
+//! 备份控制面所需的持久化与基础设施能力。
+//!
+//! 端口方法只接受/返回领域类型与既有错误体系：`BackupRepository` 复用
+//! `AdminStoreError`；`DatabaseDumpPort` 与 `BackupObjectStorePort` 返回只携带稳定
+//! 错误码的 [`BackupError`]。`gateway-store` 实现全部端口；`gateway-admin` 拥有
+//! 状态机、Cron、保留策略与 BackupTask 算法。
+
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+
+use crate::model::Revision;
+use crate::model::{
+    MutationContext,
+    backup::{
+        BackupError, BackupObjectMetadata, BackupRecord, BackupRecordListQuery, BackupRecordPage,
+        BackupRecordSeed, BackupSettings, BackupStatus, BackupStorageConfig, ConnectionTestResult,
+        UpdateBackupScheduleCommand, UpdateBackupStorageCommand,
+    },
+};
+use crate::ports::store::AdminStoreResult;
+
+/// Worker 状态迁移携带的字段更新；`None` 字段不写入。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct StatusTransitionUpdate {
+    pub size_bytes: Option<u64>,
+    pub sha256: Option<String>,
+    pub error_code: Option<String>,
+    pub error_message: Option<String>,
+    pub completed_at: Option<DateTime<Utc>>,
+}
+
+/// 备份配置、任务与计划游标的 PostgreSQL 仓储端口。
+#[async_trait]
+pub trait BackupRepository: Send + Sync {
+    /// 读取完整设置（含 Secret）。
+    async fn load_settings(&self) -> AdminStoreResult<BackupSettings>;
+
+    /// 同事务更新 S3 存储配置、递增 revision、清空验证状态并写审计事件。
+    ///
+    /// 已有记录时禁止切换 endpoint/region/bucket/path-style（存储身份锁定）。
+    /// 返回更新后的设置与新的全局 `config_revision`。
+    async fn update_storage_settings(
+        &self,
+        command: UpdateBackupStorageCommand,
+        context: &MutationContext,
+    ) -> AdminStoreResult<(BackupSettings, Revision)>;
+
+    /// 同事务更新调度配置、推进计划游标并写审计事件。
+    async fn update_schedule_settings(
+        &self,
+        command: UpdateBackupScheduleCommand,
+        next_run_at: Option<DateTime<Utc>>,
+        context: &MutationContext,
+    ) -> AdminStoreResult<BackupSettings>;
+
+    /// CAS 记录探针成功；`storage_revision` 与当前配置不一致时丢弃结果（返回 `false`）。
+    async fn record_verification(
+        &self,
+        storage_revision: u64,
+        at: DateTime<Utc>,
+    ) -> AdminStoreResult<bool>;
+
+    /// 插入 queued 任务；存在活跃任务时返回 `backup.active_task_conflict`。
+    async fn insert_backup_record(&self, seed: BackupRecordSeed) -> AdminStoreResult<BackupRecord>;
+
+    /// 幂等插入 scheduled 任务；同一时间点或活跃冲突时返回 `false`（调用方推进游标即可）。
+    async fn insert_scheduled_record(&self, seed: BackupRecordSeed) -> AdminStoreResult<bool>;
+
+    /// 分页查询记录。
+    async fn list_backup_records(
+        &self,
+        query: BackupRecordListQuery,
+    ) -> AdminStoreResult<BackupRecordPage>;
+
+    /// 读取单条记录。
+    async fn load_backup_record(&self, id: &str) -> AdminStoreResult<Option<BackupRecord>>;
+
+    /// 读取中间状态记录（dumping/uploading），供启动恢复。
+    async fn list_intermediate_records(&self) -> AdminStoreResult<Vec<BackupRecord>>;
+
+    /// 读取等待完成墓碑的记录（status = deleting）。
+    async fn list_pending_deletions(&self, limit: u32) -> AdminStoreResult<Vec<BackupRecord>>;
+
+    /// 读取 `expires_at` 已到期且非活跃的记录（completed/failed），供保留清理。
+    async fn list_expired_records(&self, limit: u32) -> AdminStoreResult<Vec<BackupRecord>>;
+
+    /// 原子领取最旧的 queued 任务并迁移到 dumping；无任务返回 `None`。
+    async fn claim_next_queued(&self, now: DateTime<Utc>)
+    -> AdminStoreResult<Option<BackupRecord>>;
+
+    /// 条件迁移状态：要求当前状态一致；不匹配返回 `None`。
+    async fn transition_status(
+        &self,
+        id: &str,
+        from: BackupStatus,
+        to: BackupStatus,
+        update: StatusTransitionUpdate,
+        now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>>;
+
+    /// 迁移到删除流程（completed/failed → deleting）；供管理员与保留策略调用。
+    async fn transition_to_deleting(
+        &self,
+        id: &str,
+        now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>>;
+
+    /// 远端删除成功后硬删除记录行。
+    async fn delete_record(&self, id: &str) -> AdminStoreResult<()>;
+
+    /// 条件推进计划游标；仅当计划表达式和时区仍是 `expected_*` 时才写入，返回是否推进。
+    async fn advance_schedule_cursor(
+        &self,
+        next_run_at: DateTime<Utc>,
+        expected_cron: &str,
+        expected_timezone: &str,
+    ) -> AdminStoreResult<bool>;
+
+    /// 按完成时间倒序读取 completed 计划备份，供保留策略扫描（最多 `limit` 条）。
+    async fn list_scheduled_completed_desc(
+        &self,
+        limit: u32,
+    ) -> AdminStoreResult<Vec<BackupRecord>>;
+}
+
+/// `pg_dump` 导出与本地暂存端口。
+#[async_trait]
+pub trait DatabaseDumpPort: Send + Sync {
+    /// 创建归档；完成后原子落盘。取消时终止子进程并清理部分文件。
+    async fn dump(&self, request: DumpRequest) -> Result<DumpArtifact, BackupError>;
+
+    /// 检查暂存目录是否存在完整归档。
+    async fn inspect_staging(&self, backup_id: &str)
+    -> Result<Option<StagedArtifact>, BackupError>;
+
+    /// 清理暂存目录中该备份的全部文件。
+    async fn cleanup_staging(&self, backup_id: &str) -> Result<(), BackupError>;
+}
+
+/// 一次 `pg_dump` 请求。
+#[derive(Debug, Clone)]
+pub struct DumpRequest {
+    pub backup_id: String,
+    pub cancellation: gateway_core::lifecycle::CancellationToken,
+}
+
+/// 已完成并落盘的归档事实。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DumpArtifact {
+    pub path: PathBuf,
+    pub size_bytes: u64,
+    pub sha256: String,
+}
+
+/// 暂存目录中已存在的完整归档。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct StagedArtifact {
+    pub path: PathBuf,
+    pub size_bytes: u64,
+    pub sha256: String,
+}
+
+/// S3 兼容对象存储适配器端口。
+///
+/// 方法接受已经校验的存储配置；SDK client 的构造与缓存属于 adapter 实现细节。
+#[async_trait]
+pub trait BackupObjectStorePort: Send + Sync {
+    /// 对专用探针对象执行 Put/Head/Get/Delete。
+    async fn test_connection(
+        &self,
+        config: &BackupStorageConfig,
+    ) -> Result<ConnectionTestResult, BackupError>;
+
+    /// 分片流式上传本地归档；取消时中止 multipart 并返回 `backup.cancelled`。
+    async fn upload_file(
+        &self,
+        config: &BackupStorageConfig,
+        request: UploadObjectRequest,
+    ) -> Result<(), BackupError>;
+
+    /// 读取对象大小与 metadata；对象不存在返回 `Ok(None)`。
+    async fn head_object(
+        &self,
+        config: &BackupStorageConfig,
+        object_key: &str,
+    ) -> Result<Option<BackupObjectMetadata>, BackupError>;
+
+    /// 删除对象；对象不存在视为成功。
+    async fn delete_object(
+        &self,
+        config: &BackupStorageConfig,
+        object_key: &str,
+    ) -> Result<(), BackupError>;
+
+    /// 创建短时预签名下载 URL。
+    async fn presigned_download(
+        &self,
+        config: &BackupStorageConfig,
+        object_key: &str,
+        file_name: &str,
+        ttl: Duration,
+    ) -> Result<String, BackupError>;
+}
+
+/// 一次对象上传请求。
+#[derive(Debug, Clone)]
+pub struct UploadObjectRequest {
+    pub object_key: String,
+    pub source: PathBuf,
+    pub metadata: BackupObjectMetadata,
+    pub cancellation: gateway_core::lifecycle::CancellationToken,
+}
+
+/// 备份控制面所需的全部 Store 能力集合。
+#[derive(Clone)]
+pub struct BackupStorePorts {
+    repository: Arc<dyn BackupRepository>,
+    dump: Arc<dyn DatabaseDumpPort>,
+    object_store: Arc<dyn BackupObjectStorePort>,
+}
+
+impl BackupStorePorts {
+    /// 组合备份端口。
+    #[must_use]
+    pub fn new(
+        repository: Arc<dyn BackupRepository>,
+        dump: Arc<dyn DatabaseDumpPort>,
+        object_store: Arc<dyn BackupObjectStorePort>,
+    ) -> Self {
+        Self {
+            repository,
+            dump,
+            object_store,
+        }
+    }
+
+    /// 备份任务/配置仓储。
+    #[must_use]
+    pub fn repository(&self) -> Arc<dyn BackupRepository> {
+        self.repository.clone()
+    }
+
+    /// `pg_dump` 导出与暂存。
+    #[must_use]
+    pub fn dump(&self) -> Arc<dyn DatabaseDumpPort> {
+        self.dump.clone()
+    }
+
+    /// S3/R2 对象存储适配器。
+    #[must_use]
+    pub fn object_store(&self) -> Arc<dyn BackupObjectStorePort> {
+        self.object_store.clone()
+    }
+
+    /// 测试与不可用路径使用的空实现；任何调用都返回不可用错误。
+    #[doc(hidden)]
+    #[must_use]
+    pub fn disabled() -> Self {
+        Self {
+            repository: Arc::new(UnavailableBackupRepository),
+            dump: Arc::new(UnavailableDumpPort),
+            object_store: Arc::new(UnavailableObjectStore),
+        }
+    }
+}
+
+struct UnavailableBackupRepository;
+
+#[async_trait]
+impl BackupRepository for UnavailableBackupRepository {
+    async fn load_settings(&self) -> AdminStoreResult<BackupSettings> {
+        Err(disabled_store())
+    }
+    async fn update_storage_settings(
+        &self,
+        _command: UpdateBackupStorageCommand,
+        _context: &MutationContext,
+    ) -> AdminStoreResult<(BackupSettings, Revision)> {
+        Err(disabled_store())
+    }
+    async fn update_schedule_settings(
+        &self,
+        _command: UpdateBackupScheduleCommand,
+        _next_run_at: Option<DateTime<Utc>>,
+        _context: &MutationContext,
+    ) -> AdminStoreResult<BackupSettings> {
+        Err(disabled_store())
+    }
+    async fn record_verification(
+        &self,
+        _storage_revision: u64,
+        _at: DateTime<Utc>,
+    ) -> AdminStoreResult<bool> {
+        Err(disabled_store())
+    }
+    async fn insert_backup_record(
+        &self,
+        _seed: BackupRecordSeed,
+    ) -> AdminStoreResult<BackupRecord> {
+        Err(disabled_store())
+    }
+    async fn insert_scheduled_record(&self, _seed: BackupRecordSeed) -> AdminStoreResult<bool> {
+        Err(disabled_store())
+    }
+    async fn list_backup_records(
+        &self,
+        _query: BackupRecordListQuery,
+    ) -> AdminStoreResult<BackupRecordPage> {
+        Err(disabled_store())
+    }
+    async fn load_backup_record(&self, _id: &str) -> AdminStoreResult<Option<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn list_intermediate_records(&self) -> AdminStoreResult<Vec<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn list_pending_deletions(&self, _limit: u32) -> AdminStoreResult<Vec<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn list_expired_records(&self, _limit: u32) -> AdminStoreResult<Vec<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn claim_next_queued(
+        &self,
+        _now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn transition_status(
+        &self,
+        _id: &str,
+        _from: BackupStatus,
+        _to: BackupStatus,
+        _update: StatusTransitionUpdate,
+        _now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn transition_to_deleting(
+        &self,
+        _id: &str,
+        _now: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<BackupRecord>> {
+        Err(disabled_store())
+    }
+    async fn delete_record(&self, _id: &str) -> AdminStoreResult<()> {
+        Err(disabled_store())
+    }
+    async fn advance_schedule_cursor(
+        &self,
+        _next_run_at: DateTime<Utc>,
+        _expected_cron: &str,
+        _expected_timezone: &str,
+    ) -> AdminStoreResult<bool> {
+        Err(disabled_store())
+    }
+    async fn list_scheduled_completed_desc(
+        &self,
+        _limit: u32,
+    ) -> AdminStoreResult<Vec<BackupRecord>> {
+        Err(disabled_store())
+    }
+}
+
+struct UnavailableDumpPort;
+
+#[async_trait]
+impl DatabaseDumpPort for UnavailableDumpPort {
+    async fn dump(&self, _request: DumpRequest) -> Result<DumpArtifact, BackupError> {
+        Err(disabled_infra())
+    }
+    async fn inspect_staging(
+        &self,
+        _backup_id: &str,
+    ) -> Result<Option<StagedArtifact>, BackupError> {
+        Err(disabled_infra())
+    }
+    async fn cleanup_staging(&self, _backup_id: &str) -> Result<(), BackupError> {
+        Err(disabled_infra())
+    }
+}
+
+struct UnavailableObjectStore;
+
+#[async_trait]
+impl BackupObjectStorePort for UnavailableObjectStore {
+    async fn test_connection(
+        &self,
+        _config: &BackupStorageConfig,
+    ) -> Result<ConnectionTestResult, BackupError> {
+        Err(disabled_infra())
+    }
+    async fn upload_file(
+        &self,
+        _config: &BackupStorageConfig,
+        _request: UploadObjectRequest,
+    ) -> Result<(), BackupError> {
+        Err(disabled_infra())
+    }
+    async fn head_object(
+        &self,
+        _config: &BackupStorageConfig,
+        _object_key: &str,
+    ) -> Result<Option<BackupObjectMetadata>, BackupError> {
+        Err(disabled_infra())
+    }
+    async fn delete_object(
+        &self,
+        _config: &BackupStorageConfig,
+        _object_key: &str,
+    ) -> Result<(), BackupError> {
+        Err(disabled_infra())
+    }
+    async fn presigned_download(
+        &self,
+        _config: &BackupStorageConfig,
+        _object_key: &str,
+        _file_name: &str,
+        _ttl: std::time::Duration,
+    ) -> Result<String, BackupError> {
+        Err(disabled_infra())
+    }
+}
+
+fn disabled_store() -> crate::ports::store::AdminStoreError {
+    crate::ports::store::AdminStoreError::new(
+        crate::ports::store::AdminStoreErrorKind::Unavailable,
+        "backup",
+        "backup store is disabled in this configuration",
+    )
+}
+
+fn disabled_infra() -> BackupError {
+    BackupError::new(
+        crate::model::backup::code::STORE_UNAVAILABLE,
+        "backup infrastructure is disabled in this configuration".to_owned(),
+    )
+}

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

@@ -0,0 +1,10 @@
+//! 客户端安装包解析的外部能力端口。
+
+use async_trait::async_trait;
+
+use crate::model::client_distribution::CodexDesktopWindowsDownloads;
+
+#[async_trait]
+pub trait ClientDistributionResolver: Send + Sync {
+    async fn resolve_codex_desktop_windows(&self, refresh: bool) -> CodexDesktopWindowsDownloads;
+}

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

@@ -0,0 +1,15 @@
+//! 管理用例依赖的外部能力端口。
+
+pub mod backup;
+pub mod client_distribution;
+pub mod plugin_accounts;
+pub mod plugin_client_keys;
+pub mod plugin_management;
+pub mod plugin_release;
+pub mod plugin_resources;
+pub mod plugins;
+pub mod pricing;
+pub mod provider;
+pub mod proxy;
+pub mod store;
+pub mod system;

backend/crates/gateway-admin/src/ports/plugin_accounts.rs

@@ -0,0 +1,42 @@
+//! 插件宿主访问账号权威所需的窄端口。
+
+use async_trait::async_trait;
+use gateway_core::account::ProviderAccountId;
+
+use crate::model::{
+    AdminError, MutationContext,
+    provider_credentials::{
+        PluginAccountCredential, PluginAccountListQuery, PluginAccountPage,
+        PluginAccountSaveResult, PreparedPluginAccountSave,
+    },
+};
+
+/// Runtime 只取得账号读写用例，不接触 Store、SQL 或完整管理服务集合。
+#[async_trait]
+pub trait PluginAccountAccess: Send + Sync {
+    async fn list(&self, query: PluginAccountListQuery) -> Result<PluginAccountPage, AdminError>;
+
+    async fn get_runtime(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<crate::model::accounts::AccountRecord, AdminError>;
+
+    async fn get_credential(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<PluginAccountCredential, AdminError>;
+
+    /// 只读 Provider 已有额度观测；实现不得主动刷新上游或附加用量预测。
+    async fn get_quota(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<crate::model::provider_credentials::ProviderQuota, AdminError> {
+        Err(AdminError::unavailable("插件额度事实查询暂不可用"))
+    }
+
+    async fn save(
+        &self,
+        command: PreparedPluginAccountSave,
+        context: &MutationContext,
+    ) -> Result<PluginAccountSaveResult, AdminError>;
+}

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

@@ -0,0 +1,16 @@
+//! 插件发现 Client Key 公开身份的窄端口。
+
+use async_trait::async_trait;
+
+use crate::model::{
+    AdminError,
+    plugin_client_keys::{PluginClientKeyListQuery, PluginClientKeyPage},
+};
+
+#[async_trait]
+pub trait PluginClientKeyAccess: Send + Sync {
+    async fn list(
+        &self,
+        query: PluginClientKeyListQuery,
+    ) -> Result<PluginClientKeyPage, AdminError>;
+}

backend/crates/gateway-admin/src/ports/plugin_management.rs

@@ -0,0 +1,57 @@
+use async_trait::async_trait;
+use gateway_core::runtime::extensions::ExtensionSetReference;
+
+use crate::model::{
+    AdminError,
+    plugins::management::{
+        PluginManagementRequest, PluginManagementResponse, PluginManagementTarget,
+        PluginManagementView,
+    },
+};
+
+/// 仅按 Admin 固定的发布引用分派；Runtime 不自行选择当前代次，也不拥有管理员身份。
+#[async_trait]
+pub trait PluginManagement: Send + Sync {
+    /// 复核固定发布代次中的模型访问域；调用方已校验持久实例仍为当前目标。
+    async fn authorize_models(
+        &self,
+        published: &ExtensionSetReference,
+        target: &PluginManagementTarget,
+    ) -> Result<(), AdminError>;
+
+    async fn start_callback(
+        &self,
+        published: &ExtensionSetReference,
+        target: &PluginManagementTarget,
+        command: crate::model::plugins::management::StartPluginManagementCallback,
+        context: &crate::model::auth::AdminRequestContext,
+    ) -> Result<crate::model::plugins::management::PluginManagementCallbackTicket, AdminError>;
+
+    async fn callback(
+        &self,
+        published: &ExtensionSetReference,
+        target: &PluginManagementTarget,
+        state: &str,
+        request: PluginManagementRequest,
+    ) -> Result<PluginManagementResponse, AdminError>;
+
+    async fn views(
+        &self,
+        published: &ExtensionSetReference,
+    ) -> Result<Vec<PluginManagementView>, AdminError>;
+
+    async fn resource(
+        &self,
+        published: &ExtensionSetReference,
+        target: &PluginManagementTarget,
+        path: &str,
+        public: bool,
+    ) -> Result<PluginManagementResponse, AdminError>;
+
+    async fn handle(
+        &self,
+        published: &ExtensionSetReference,
+        target: &PluginManagementTarget,
+        request: PluginManagementRequest,
+    ) -> Result<PluginManagementResponse, AdminError>;
+}

backend/crates/gateway-admin/src/ports/plugin_release.rs

@@ -0,0 +1,37 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OfficialPluginReleaseReadErrorKind {
+    Invalid,
+    NotFound,
+    Unavailable,
+}
+
+/// 文件系统错误不携带部署路径，避免把宿主布局传播到管理域和日志之外。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+#[error("official plugin release files are unavailable")]
+pub struct OfficialPluginReleaseReadError {
+    kind: OfficialPluginReleaseReadErrorKind,
+}
+
+impl OfficialPluginReleaseReadError {
+    #[must_use]
+    pub const fn new(kind: OfficialPluginReleaseReadErrorKind) -> Self {
+        Self { kind }
+    }
+
+    #[must_use]
+    pub const fn kind(self) -> OfficialPluginReleaseReadErrorKind {
+        self.kind
+    }
+}
+
+/// Host 只暴露与宿主发行物同信任边界的只读文件，不解释官方身份或插件包。
+#[async_trait]
+pub trait OfficialPluginReleaseFiles: Send + Sync {
+    async fn manifest(&self) -> Result<Option<Arc<[u8]>>, OfficialPluginReleaseReadError>;
+
+    async fn artifact(&self, file_name: &str) -> Result<Arc<[u8]>, OfficialPluginReleaseReadError>;
+}

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

@@ -0,0 +1,63 @@
+//! 插件自有资源的管理入口与原子持久化端口。
+
+use super::store::AdminStoreResult;
+use crate::model::{
+    AdminError, MutationContext,
+    account_groups::{CreateAccountGroup, NewAccountGroup},
+    client_keys::NewClientKey,
+    plugin_resources::{
+        GroupMembersChange, GroupMembersChanged, ManagedKeyConfig, ManagedResource,
+        PluginResourceOwner, ResourceMutation,
+    },
+};
+use async_trait::async_trait;
+
+#[async_trait]
+pub trait PluginResourceAccess: Send + Sync {
+    async fn ensure_group(
+        &self,
+        owner: &PluginResourceOwner,
+        resource_key: String,
+        command: CreateAccountGroup,
+        context: &MutationContext,
+    ) -> Result<ManagedResource, AdminError>;
+    async fn ensure_key(
+        &self,
+        owner: &PluginResourceOwner,
+        resource_key: String,
+        groups: Vec<String>,
+        command: ManagedKeyConfig,
+        context: &MutationContext,
+    ) -> Result<ManagedResource, AdminError>;
+    async fn change_members(
+        &self,
+        owner: &PluginResourceOwner,
+        command: GroupMembersChange,
+        context: &MutationContext,
+    ) -> Result<GroupMembersChanged, AdminError>;
+}
+
+#[async_trait]
+pub trait PluginResourceStore: Send + Sync {
+    async fn ensure_group(
+        &self,
+        owner: &PluginResourceOwner,
+        resource_key: String,
+        command: NewAccountGroup,
+        context: &MutationContext,
+    ) -> AdminStoreResult<ResourceMutation<ManagedResource>>;
+    async fn ensure_key(
+        &self,
+        owner: &PluginResourceOwner,
+        resource_key: String,
+        groups: Vec<String>,
+        command: NewClientKey,
+        context: &MutationContext,
+    ) -> AdminStoreResult<ResourceMutation<ManagedResource>>;
+    async fn change_members(
+        &self,
+        owner: &PluginResourceOwner,
+        command: GroupMembersChange,
+        context: &MutationContext,
+    ) -> AdminStoreResult<ResourceMutation<GroupMembersChanged>>;
+}

backend/crates/gateway-admin/src/ports/plugins.rs

@@ -0,0 +1,329 @@
+use std::{collections::BTreeMap, sync::Arc};
+
+use async_trait::async_trait;
+
+use super::store::AdminStoreResult;
+use crate::model::plugins::distribution::{
+    DownloadedPlugin, GithubReleaseQuery, PluginDistributionEgress, PluginRelease,
+    PluginSourceBinding, PluginUpdateSource, RemotePluginLocation, SourceCredential,
+    SourceCredentialInfo,
+};
+use crate::model::plugins::instances::{
+    PluginInstance, PluginInstanceMutation, PluginInstanceReplacement, PluginInstanceRuntime,
+    PluginInstanceSnapshot, PluginVersionConfiguration,
+};
+use crate::model::plugins::state::{
+    ApplyPluginStateMigration, DeletePluginState, PluginStateCommit, PluginStateConfiguration,
+    PluginStateMigrationBatch, PluginStateOwner, PluginStateOwnerRequest, PluginStateRecord,
+    PluginStateTransition, PluginStateWrite, PutPluginState,
+};
+use crate::model::{
+    AdminError, MutationContext, Revision,
+    plugins::{
+        InspectedPluginArtifact, InstalledPluginArtifact, PluginArtifactMutation,
+        PluginCompatibilityRequirements, PluginSource,
+    },
+};
+use gateway_core::runtime::extensions::ExtensionSetReference;
+
+/// Admin 准备完整候选并保活到提交后的发布结束；进程状态不能代替持久启用状态。
+#[async_trait]
+pub trait PluginPreparation: Send + Sync {
+    /// 静态判断业务配置是否完整，不启动进程；不完整的安装保留为待配置。
+    async fn configuration_ready(
+        &self,
+        instance: PluginInstance,
+        metadata: &crate::model::plugins::PluginArtifactMetadata,
+    ) -> Result<bool, AdminError>;
+    async fn validate(
+        &self,
+        instance: PluginInstance,
+    ) -> Result<PluginStateConfiguration, AdminError>;
+    /// 本次修改的实例 revision 必须等于候选 config_revision，准备失败时拒绝提交；历史故障可隔离。
+    async fn prepare(
+        &self,
+        snapshot: PluginInstanceSnapshot,
+    ) -> Result<ExtensionSetReference, AdminError>;
+    /// 返回当前进程的只读运行事实；缺省实现让不托管插件进程的组合保持兼容。
+    async fn runtime_diagnostics(
+        &self,
+        _snapshot: &PluginInstanceSnapshot,
+        _published_revision: Option<u64>,
+        _published: Option<&ExtensionSetReference>,
+    ) -> Option<BTreeMap<String, PluginInstanceRuntime>> {
+        None
+    }
+    async fn activate_state(
+        &self,
+        _prepared: &ExtensionSetReference,
+        _instance: &PluginInstance,
+    ) -> Result<(), AdminError> {
+        Ok(())
+    }
+    async fn quiesce_instance(
+        &self,
+        _instance_id: &str,
+        _artifact_sha256: &str,
+        _revision: Revision,
+    ) {
+    }
+    async fn migrate_state(
+        &self,
+        _prepared: &ExtensionSetReference,
+        _transition: PluginStateTransition,
+    ) -> Result<(), AdminError> {
+        Err(AdminError::unavailable("插件状态迁移运行时不可用"))
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PluginStateStoreErrorKind {
+    Invalid,
+    NotFound,
+    Conflict,
+    Quota,
+    PermissionDenied,
+    Unavailable,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("plugin state operation failed")]
+pub struct PluginStateStoreError {
+    kind: PluginStateStoreErrorKind,
+}
+
+impl PluginStateStoreError {
+    #[must_use]
+    pub const fn new(kind: PluginStateStoreErrorKind) -> Self {
+        Self { kind }
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> PluginStateStoreErrorKind {
+        self.kind
+    }
+}
+
+pub type PluginStateStoreResult<T> = Result<T, PluginStateStoreError>;
+
+/// 私有状态的窄端口；不暴露 SQL、连接或跨命名空间事务。
+#[async_trait]
+pub trait PluginStateStore: Send + Sync {
+    async fn load_owner(
+        &self,
+        request: PluginStateOwnerRequest,
+    ) -> PluginStateStoreResult<Option<PluginStateOwner>>;
+    async fn get(
+        &self,
+        owner: &PluginStateOwner,
+        namespace: &str,
+        key: &str,
+    ) -> PluginStateStoreResult<Option<PluginStateRecord>>;
+    async fn put(
+        &self,
+        owner: &PluginStateOwner,
+        command: PutPluginState,
+    ) -> PluginStateStoreResult<PluginStateWrite>;
+    async fn delete(
+        &self,
+        owner: &PluginStateOwner,
+        command: DeletePluginState,
+    ) -> PluginStateStoreResult<bool>;
+    async fn transition_required(
+        &self,
+        instance_id: &str,
+        target: &PluginStateConfiguration,
+    ) -> PluginStateStoreResult<bool>;
+    async fn begin_transition(
+        &self,
+        instance_id: &str,
+        expected_instance_revision: Revision,
+        artifact_sha256: &str,
+        target: PluginStateConfiguration,
+    ) -> PluginStateStoreResult<PluginStateTransition>;
+    async fn migration_batch(
+        &self,
+        transition_id: &str,
+        namespace: &str,
+        maximum_records: u32,
+    ) -> PluginStateStoreResult<PluginStateMigrationBatch>;
+    async fn apply_migration_batch(
+        &self,
+        command: ApplyPluginStateMigration,
+    ) -> PluginStateStoreResult<()>;
+    async fn abort_transition(&self, transition_id: &str) -> PluginStateStoreResult<()>;
+}
+
+/// Host 拥有联网、重定向、凭据作用域、限流与有界下载，不解释插件包。
+#[async_trait]
+pub trait PluginDistribution: Send + Sync {
+    fn validate_source(&self, source: &PluginUpdateSource) -> Result<(), AdminError>;
+    fn validate_credential(&self, credential: &SourceCredential) -> Result<(), AdminError>;
+    async fn query_release(
+        &self,
+        query: GithubReleaseQuery,
+        credentials: Vec<SourceCredential>,
+        egress: Option<PluginDistributionEgress>,
+    ) -> Result<PluginRelease, AdminError>;
+    async fn download(
+        &self,
+        location: RemotePluginLocation,
+        credentials: Vec<SourceCredential>,
+        egress: Option<PluginDistributionEgress>,
+    ) -> Result<DownloadedPlugin, AdminError>;
+}
+
+/// Runtime 只解释插件包格式；安装事务与来源选择归 Admin。
+#[async_trait]
+pub trait PluginPackageInspector: Send + Sync {
+    /// 当前宿主对权限标识的说明，供展示投影使用，不属于不可变制品元数据。
+    fn permission_descriptions(
+        &self,
+        permissions: &[String],
+    ) -> Vec<crate::model::plugins::PluginPermissionDescription> {
+        permissions
+            .iter()
+            .map(
+                |permission| crate::model::plugins::PluginPermissionDescription {
+                    permission: permission.clone(),
+                    label: permission.clone(),
+                    description: String::new(),
+                },
+            )
+            .collect()
+    }
+
+    async fn inspect(
+        &self,
+        archive: Arc<[u8]>,
+        expected_sha256: Option<String>,
+    ) -> Result<InspectedPluginArtifact, AdminError>;
+
+    /// 从已安装且摘要匹配的制品中读取可展示的静态图标，不启动插件实例。
+    async fn icon(
+        &self,
+        _archive: Arc<[u8]>,
+        _expected_sha256: String,
+        _theme: crate::model::plugins::PluginIconTheme,
+    ) -> Result<Option<crate::model::plugins::PluginArtifactIconResource>, AdminError> {
+        Err(AdminError::unavailable("插件图标读取不可用"))
+    }
+
+    /// 只读取已校验包的静态宿主要求；不得准备或启动插件进程。
+    async fn compatibility(
+        &self,
+        _archive: Arc<[u8]>,
+        _expected_sha256: String,
+    ) -> Result<PluginCompatibilityRequirements, AdminError> {
+        Err(AdminError::unavailable("插件兼容性检查不可用"))
+    }
+}
+
+#[async_trait]
+pub trait PluginStore: Send + Sync {
+    /// 只复核精确管理目标的启用、接受事实和版本，不读取实例配置或密钥。
+    async fn management_target_is_current(
+        &self,
+        target: &crate::model::plugins::management::PluginManagementTarget,
+    ) -> AdminStoreResult<bool>;
+    async fn load_instances(&self) -> AdminStoreResult<PluginInstanceSnapshot>;
+    /// 读取对应制品最近一次启用时提交的配置，密钥始终留在服务端。
+    async fn load_version_configuration(
+        &self,
+        _id: &str,
+        _digest: &str,
+    ) -> AdminStoreResult<Option<PluginVersionConfiguration>> {
+        Ok(None)
+    }
+    /// 只返回有可恢复配置的制品摘要，不读取敏感值。
+    async fn configuration_versions(&self, _id: &str) -> AdminStoreResult<Vec<String>> {
+        Ok(Vec::new())
+    }
+    async fn save_instance(
+        &self,
+        instance: PluginInstance,
+        expected_revision: Revision,
+        context: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation>;
+    async fn save_instance_with_state(
+        &self,
+        instance: PluginInstance,
+        expected_revision: Revision,
+        state: PluginStateCommit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        if !state.configuration.namespaces.is_empty() || state.transition_id.is_some() {
+            return Err(super::store::AdminStoreError::new(
+                super::store::AdminStoreErrorKind::Unavailable,
+                "plugin state",
+                "plugin state store is unavailable",
+            ));
+        }
+        self.save_instance(instance, expected_revision, context)
+            .await
+    }
+    /// 保存目标并停用明确确认的配置，必须共享事务和配置版本检查。
+    async fn save_instance_replacing(
+        &self,
+        instance: PluginInstance,
+        expected_revision: Revision,
+        state: PluginStateCommit,
+        replacements: &[PluginInstanceReplacement],
+        context: &MutationContext,
+    ) -> AdminStoreResult<PluginInstanceMutation> {
+        if !replacements.is_empty() {
+            return Err(super::store::AdminStoreError::new(
+                super::store::AdminStoreErrorKind::Unavailable,
+                "plugin",
+                "atomic plugin configuration switching is unavailable",
+            ));
+        }
+        self.save_instance_with_state(instance, expected_revision, state, context)
+            .await
+    }
+
+    async fn delete_instance(
+        &self,
+        id: &str,
+        expected_revision: Revision,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn list_update_sources(&self) -> AdminStoreResult<Vec<PluginSourceBinding>>;
+    async fn change_update_source(
+        &self,
+        binding: PluginSourceBinding,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn list_source_credentials(&self) -> AdminStoreResult<Vec<SourceCredentialInfo>>;
+    async fn load_source_credential(&self, id: &str) -> AdminStoreResult<SourceCredential>;
+    async fn save_source_credential(
+        &self,
+        credential: SourceCredential,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn delete_source_credential(
+        &self,
+        id: &str,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn list_artifacts(&self) -> AdminStoreResult<Vec<InstalledPluginArtifact>>;
+    async fn load_artifact(&self, digest: &str) -> AdminStoreResult<InspectedPluginArtifact>;
+    async fn install_artifact(
+        &self,
+        artifact: InspectedPluginArtifact,
+        source: PluginSource,
+        context: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation>;
+    /// 接受不可变制品声明的全部能力域；接受事实不随实例设置变化。
+    async fn accept_artifact(
+        &self,
+        digest: &str,
+        context: &MutationContext,
+    ) -> AdminStoreResult<PluginArtifactMutation>;
+    /// 删除制品及其无引用下载凭据，最后一个版本同时删除来源规则，清理与审计必须原子提交。
+    async fn delete_artifact(
+        &self,
+        digest: &str,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+}

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

@@ -0,0 +1,9 @@
+//! 手动同步的外部价目来源；网络和外部文档解析由 Host 实现。
+
+use crate::model::{AdminError, pricing::PricingSyncPreview};
+use async_trait::async_trait;
+
+#[async_trait]
+pub trait PricingSource: Send + Sync {
+    async fn fetch(&self) -> Result<PricingSyncPreview, AdminError>;
+}

backend/crates/gateway-admin/src/ports/provider.rs

@@ -0,0 +1,397 @@
+//! 原生 Provider 管理能力与启动时注册表。
+
+use std::{collections::BTreeMap, sync::Arc};
+
+use async_trait::async_trait;
+use gateway_core::{
+    account::ProviderAccountId,
+    operation::Operation,
+    routing::{ProviderKind, UpstreamModelId},
+};
+use heck::ToUpperCamelCase;
+
+use crate::model::observability::{
+    CalculatedBillingBreakdown, DashboardWireProfile, ProviderBillingInput,
+};
+use crate::model::provider_credentials::{
+    AuthorizationStarted, CompleteAuthorization, ConsumeProviderResetCredit,
+    PrepareCredentialImport, PrepareCredentialRefresh, PrepareCredentialRotation,
+    PreparedAuthorizationCommit, PreparedCredentialImport, PreparedCredentialRotation,
+    ProviderExport, ProviderExportCredentialInput, ProviderModelCatalogDocument, ProviderModels,
+    ProviderProfileAvatar, ProviderProfileStatistics, ProviderQuota, ProviderQuotaRequest,
+    ProviderResetCreditResult, ProviderResetCredits, ProviderSubscription, explicit_plan_type,
+};
+use crate::model::{
+    provider_credentials::{ProviderDocument, ProviderQuotaWindow},
+    quota_forecast_sampling::QuotaForecastObservation,
+};
+
+/// Provider 管理失败的稳定分类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProviderAdminErrorKind {
+    Invalid,
+    Unsupported,
+    NotFound,
+    Conflict,
+    /// Provider 已发起不可逆操作，但无法确认最终执行结果。
+    Ambiguous,
+    Unavailable,
+    CredentialRefreshRequired,
+    BadGateway,
+    Internal,
+}
+
+/// 不携带 OAuth 请求材料的管理错误。
+///
+/// `message` 是 Provider 局部诊断，可能包含原始上游正文；通用管理用例不得自动把它作为公开文案。
+/// 只有明确拥有原始诊断合同的调用方才能读取，`Debug` 始终只记录是否存在。
+/// `public_message` 则是明确标记为可公开的静态提示，不允许携带动态上游材料。
+#[derive(Clone, PartialEq, Eq, thiserror::Error)]
+#[error("provider admin operation failed: {kind:?}")]
+pub struct ProviderAdminError {
+    kind: ProviderAdminErrorKind,
+    message: Option<String>,
+    public_message: Option<&'static str>,
+}
+
+impl std::fmt::Debug for ProviderAdminError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("ProviderAdminError")
+            .field("kind", &self.kind)
+            .field("message", &self.message.as_ref().map(|_| "<redacted>"))
+            .field("public_message", &self.public_message)
+            .finish()
+    }
+}
+
+impl ProviderAdminError {
+    #[must_use]
+    pub const fn new(kind: ProviderAdminErrorKind) -> Self {
+        Self {
+            kind,
+            message: None,
+            public_message: None,
+        }
+    }
+
+    #[must_use]
+    pub fn with_message(mut self, message: impl Into<String>) -> Self {
+        self.message = Some(message.into());
+        self
+    }
+
+    /// Provider 明确允许公开的静态提示；不得承载上游响应或凭据材料。
+    #[must_use]
+    pub const fn with_public_message(mut self, message: &'static str) -> Self {
+        self.public_message = Some(message);
+        self
+    }
+
+    #[must_use]
+    pub const fn public_message(&self) -> Option<&'static str> {
+        self.public_message
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> ProviderAdminErrorKind {
+        self.kind
+    }
+
+    #[must_use]
+    pub fn message(&self) -> Option<&str> {
+        self.message.as_deref()
+    }
+}
+
+/// 一个具体 Provider 对管理控制面提供的解析、验证、上游交互与运行时资源回收能力。
+///
+/// 数据变更由 Provider 返回 prepared facts；config revision、审计与 PostgreSQL 事务
+/// 全部由 [`crate::ports::store::AccountStore`] 提交。运行时资源通知只在事务成功后发生。
+#[async_trait]
+pub trait ProviderAdmin: Send + Sync {
+    /// 只读内置价目；没有本地计价能力的 Provider 返回空目录。
+    fn pricing_catalog(&self) -> crate::model::pricing::ProviderPricingCatalog {
+        Default::default()
+    }
+
+    fn provider_kind(&self) -> &ProviderKind;
+
+    /// 只读取原生 Provider 能力及账号类型，不执行网络或数据库查询。
+    fn account_capabilities(
+        &self,
+        _account_id: &ProviderAccountId,
+        _authentication_kind: &str,
+    ) -> crate::model::accounts::ProviderAccountCapabilities {
+        Default::default()
+    }
+
+    /// 提供该 Provider 的可选客户端身份；通用管理层不解释内部字段。
+    fn client_profile_options(
+        &self,
+    ) -> Result<gateway_core::account::OpaqueProviderData, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 没有持久选择时使用的 Provider 默认画像；只返回已准备的本地事实。
+    fn default_client_profile(&self) -> Option<gateway_core::account::OpaqueProviderData> {
+        None
+    }
+
+    /// 校验并投影客户端身份，结果不含认证或账号材料。
+    fn preview_client_profile(
+        &self,
+        _configuration: &gateway_core::account::OpaqueProviderData,
+    ) -> Result<gateway_core::account::OpaqueProviderData, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 将原始套餐值投影为展示名称；默认保留未知 Provider 的原始名称。
+    fn plan_type_display(&self, plan_type: &str) -> String {
+        plan_type.to_owned()
+    }
+
+    /// 账号已经由控制面提交为不可调度状态，释放 Provider 持有的账号级运行时资源。
+    ///
+    /// 无账号级运行时资源的 Provider 不需要执行额外操作。该通知发生在 Store 事务
+    /// 成功之后，不参与事务成败，也不得恢复或改写已经提交的账号状态。
+    async fn account_unavailable(&self, account_id: &ProviderAccountId);
+
+    /// 账号资格事实已经由控制面提交，失效 Provider 持有的可重建派生状态。
+    ///
+    /// 该通知发生在 Store 事务成功之后、下一份 RuntimeSnapshot 编译之前；通知
+    /// 不参与已提交事务成败。没有账号派生状态的 Provider 可使用默认空实现。
+    async fn account_facts_changed(&self, _account_ids: &[ProviderAccountId]) {}
+
+    /// 生成一次连接测试所需的 Provider-owned operation；Core 负责实际执行与落账。
+    async fn connection_test_operation(
+        &self,
+        upstream_model: &UpstreamModelId,
+        input_text: &str,
+    ) -> Result<Operation, ProviderAdminError>;
+
+    /// 返回该 Provider 实际持有的 Dashboard 上游身份画像。
+    fn dashboard_wire_profile(&self) -> Option<DashboardWireProfile>;
+
+    fn configured_wire_profile(
+        &self,
+        _configuration: &gateway_core::account::OpaqueProviderData,
+    ) -> Option<DashboardWireProfile> {
+        self.dashboard_wire_profile()
+    }
+
+    /// 使用 Provider-owned 价格规则恢复持久请求的逐项费用。
+    /// 未保存的长上下文计费标记不得从当前价格反推。
+    fn calculated_billing(
+        &self,
+        input: &ProviderBillingInput,
+    ) -> Result<Option<CalculatedBillingBreakdown>, ProviderAdminError>;
+
+    async fn prepare_import(
+        &self,
+        command: PrepareCredentialImport,
+    ) -> Result<PreparedCredentialImport, ProviderAdminError>;
+
+    async fn start_authorization(
+        &self,
+        pending: crate::model::provider_credentials::PendingAuthorizationMutation,
+    ) -> Result<AuthorizationStarted, ProviderAdminError>;
+
+    async fn complete_authorization(
+        &self,
+        command: CompleteAuthorization,
+    ) -> Result<PreparedAuthorizationCommit, ProviderAdminError>;
+
+    async fn prepare_rotation(
+        &self,
+        command: PrepareCredentialRotation,
+    ) -> Result<PreparedCredentialRotation, ProviderAdminError>;
+
+    async fn prepare_refresh(
+        &self,
+        command: PrepareCredentialRefresh,
+    ) -> Result<PreparedCredentialRotation, ProviderAdminError>;
+
+    /// 可公开的账号连接设置；实现只能显式投影非敏感字段，不能返回凭据原文。
+    async fn account_configuration(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<Option<ProviderDocument>, ProviderAdminError> {
+        Ok(None)
+    }
+
+    async fn quota(
+        &self,
+        request: ProviderQuotaRequest,
+    ) -> Result<ProviderQuota, ProviderAdminError>;
+
+    /// 历史观测的协议字段仅由具体 Provider 解释；不支持时保留累计估算。
+    fn quota_forecast_observation(
+        &self,
+        _document: &ProviderDocument,
+        _window: &ProviderQuotaWindow,
+    ) -> Option<QuotaForecastObservation> {
+        None
+    }
+
+    /// 查询 Provider 官方个人资料统计；不支持该能力的 Provider 使用默认拒绝。
+    /// 只由个人信息显式查询，不在额度刷新或后台任务中预取。
+    async fn subscription(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<Option<ProviderSubscription>, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    async fn profile_statistics(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 打开 Provider 官方头像字节流；不支持该能力的 Provider 使用默认拒绝。
+    async fn profile_avatar(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileAvatar, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 查询 Provider 主动额度重置卡；不支持该能力的 Provider 使用默认拒绝。
+    async fn reset_credits(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderResetCredits, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 消费 Provider 主动额度重置卡；不支持该能力的 Provider 使用默认拒绝。
+    async fn consume_reset_credit(
+        &self,
+        _command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    async fn models(
+        &self,
+        account_id: &ProviderAccountId,
+        refresh: bool,
+    ) -> Result<ProviderModels, ProviderAdminError>;
+
+    /// 导出该账号的 Provider 原生模型目录正文；不提供原生目录的 Provider 使用默认拒绝。
+    async fn model_catalog_document(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderModelCatalogDocument, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    async fn export_credentials(
+        &self,
+        credentials: Vec<ProviderExportCredentialInput>,
+    ) -> Result<ProviderExport, ProviderAdminError>;
+}
+
+/// 启动时注册原生 Provider，按 ProviderKind 查找管理能力。
+#[derive(Clone)]
+pub struct ProviderAdminRegistry {
+    providers: Arc<BTreeMap<ProviderKind, Arc<dyn ProviderAdmin>>>,
+}
+
+impl ProviderAdminRegistry {
+    pub fn pricing_catalog(&self) -> gateway_core::metering::PricingOverrides {
+        self.providers
+            .iter()
+            .map(|(kind, provider)| (kind.as_str().to_owned(), provider.pricing_catalog()))
+            .collect()
+    }
+
+    /// 创建无重复 ProviderKind 的注册表。
+    ///
+    /// # Errors
+    ///
+    /// 重复注册同一 ProviderKind 时返回 Conflict。
+    pub fn new(
+        providers: impl IntoIterator<Item = Arc<dyn ProviderAdmin>>,
+    ) -> Result<Self, ProviderAdminError> {
+        let mut registered = BTreeMap::new();
+        for provider in providers {
+            let kind = provider.provider_kind().clone();
+            if registered.insert(kind, provider).is_some() {
+                return Err(ProviderAdminError::new(ProviderAdminErrorKind::Conflict));
+            }
+        }
+        Ok(Self {
+            providers: Arc::new(registered),
+        })
+    }
+
+    pub fn require(
+        &self,
+        provider_kind: &ProviderKind,
+    ) -> Result<Arc<dyn ProviderAdmin>, ProviderAdminError> {
+        self.providers
+            .get(provider_kind)
+            .cloned()
+            .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 账号目录与关联列表共用套餐补全和展示规则，已知账号套餐优先于额度快照。
+    pub(crate) fn resolve_account_plan(
+        &self,
+        provider_kind: &str,
+        plan_type: &mut Option<String>,
+        quota: Option<&ProviderQuota>,
+    ) -> Option<String> {
+        if let Some(quota) = quota {
+            quota.fill_missing_plan_type(plan_type);
+        }
+        self.plan_type_display(provider_kind, plan_type.as_deref())
+    }
+
+    /// 账号页和 Dashboard 共用的大驼峰套餐展示名称，不修改原始套餐值。
+    pub(crate) fn plan_type_display(
+        &self,
+        provider_kind: &str,
+        plan_type: Option<&str>,
+    ) -> Option<String> {
+        let plan_type = explicit_plan_type(plan_type)?.trim();
+        let provider = ProviderKind::new(provider_kind.to_owned())
+            .ok()
+            .and_then(|kind| self.require(&kind).ok());
+        let display = provider.map_or_else(
+            || plan_type.to_owned(),
+            |provider| provider.plan_type_display(plan_type),
+        );
+        // 所有 Provider 及未知套餐统一排版，保留 Plus 后缀的含义。
+        Some(display.replace('+', " Plus ").to_upper_camel_case())
+    }
+
+    /// 返回所有已注册 Provider 的 Dashboard 上游身份画像。
+    pub fn dashboard_wire_profiles(
+        &self,
+        configurations: &std::collections::BTreeMap<
+            ProviderKind,
+            gateway_core::account::OpaqueProviderData,
+        >,
+    ) -> Vec<DashboardWireProfile> {
+        self.providers
+            .iter()
+            .filter_map(|(kind, provider)| match configurations.get(kind) {
+                Some(configuration) => provider.configured_wire_profile(configuration),
+                None => provider.dashboard_wire_profile(),
+            })
+            .collect()
+    }
+
+    /// 按平台计算请求费用。
+    pub fn calculated_billing(
+        &self,
+        provider_kind: &ProviderKind,
+        input: &ProviderBillingInput,
+    ) -> Result<Option<CalculatedBillingBreakdown>, ProviderAdminError> {
+        self.require(provider_kind)?.calculated_billing(input)
+    }
+}

backend/crates/gateway-admin/src/ports/proxy.rs

@@ -0,0 +1,66 @@
+use async_trait::async_trait;
+use gateway_core::account::{OutboundProxy, ProviderAccountId};
+
+use super::store::AdminStoreResult;
+use crate::model::{
+    MutationContext, Revision,
+    proxies::{
+        ImportProxyBinding, NewProxy, ProxyAccountListQuery, ProxyAccountPage, ProxyListQuery,
+        ProxyMutation, ProxyPage, ProxyRecord, ProxyTestResult, UpdateProxy,
+    },
+};
+
+#[async_trait]
+pub trait ProxyStore: Send + Sync {
+    /// 在凭据交换到提交期间保护选定代理的连接配置和测试结果。
+    async fn reserve_import(&self, id: &str) -> AdminStoreResult<ProxyImportReservation>;
+    async fn list(&self, query: ProxyListQuery) -> AdminStoreResult<ProxyPage>;
+    async fn list_accounts(
+        &self,
+        query: ProxyAccountListQuery,
+    ) -> AdminStoreResult<ProxyAccountPage>;
+    async fn get(&self, id: &str) -> AdminStoreResult<ProxyRecord>;
+    /// 仅在账号仍绑定指定代理时解除关联，并清除账号保存的连接地址。
+    async fn remove_account(
+        &self,
+        proxy_id: &str,
+        account_id: &ProviderAccountId,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn create(
+        &self,
+        command: NewProxy,
+        context: &MutationContext,
+    ) -> AdminStoreResult<ProxyMutation>;
+    async fn update(
+        &self,
+        command: UpdateProxy,
+        context: &MutationContext,
+    ) -> AdminStoreResult<ProxyMutation>;
+    async fn delete(
+        &self,
+        id: &str,
+        revision: Revision,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn record_test(
+        &self,
+        id: &str,
+        revision: Revision,
+        result: ProxyTestResult,
+        context: &MutationContext,
+    ) -> AdminStoreResult<ProxyMutation>;
+}
+
+/// 离开作用域时释放保护，错误返回和请求取消也遵循相同规则。
+pub trait ProxyImportGuard: Send + Sync {}
+
+pub struct ProxyImportReservation {
+    pub binding: ImportProxyBinding,
+    pub guard: Box<dyn ProxyImportGuard>,
+}
+
+#[async_trait]
+pub trait ProxyProbe: Send + Sync {
+    async fn test(&self, proxy: &OutboundProxy, detect_location: bool) -> ProxyTestResult;
+}

backend/crates/gateway-admin/src/ports/store.rs

@@ -0,0 +1,610 @@
+//! 管理控制面所需的持久化能力。
+//!
+//! 端口按业务资源拆分，方法使用领域模型，不暴露连接池、事务或 Redis client。
+
+use std::{collections::BTreeMap, net::IpAddr, sync::Arc, time::Duration};
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use futures::stream::BoxStream;
+
+use super::backup::BackupStorePorts;
+use crate::model::{
+    MutationContext, Revision,
+    account_groups::{
+        AccountGroupListQuery, AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage,
+        DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+    },
+    accounts::{
+        AccountListQuery, AccountPage, AccountPageItem, AccountRuntimeSnapshot,
+        AccountUpdateResult, AccountUsage, AccountUsageWindowQuery, AccountUsageWindowResult,
+        AccountsUpdateResult, BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
+    },
+    auth::{AdminAuditEvent, AuthSession},
+    client_keys::{
+        ClientKeyListQuery, ClientKeyPage, ClientKeyRecord, ClientKeySecret, DeleteClientKey,
+        NewClientKey, ResetClientKeyBudget, SetClientKeyEnabled, UpdateClientKey,
+    },
+    observability::{
+        DashboardObservation, DashboardRuntimeSlots, DiagnosticDimension, DiagnosticObservation,
+        OpsErrorPage, OpsErrorQuery, RequestMetricPoint, TimeRange, UsageCalculatedBillingFact,
+        UsageDetail, UsageFilter, UsageOverview, UsagePage, UsageQuery,
+    },
+    provider_credentials::{
+        AuthorizationCommit, CredentialDetails, CredentialImportCommit, CredentialImportResult,
+        CredentialMutationResult, CredentialRotationCommit, PluginAccountListQuery,
+        PluginAccountPage, ProviderExportCredentialInput,
+    },
+    quota_forecast_sampling::QuotaForecastHistory,
+    settings::{AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RuntimeSettings},
+};
+
+/// 管理端可判定的持久化失败类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AdminStoreErrorKind {
+    Invalid,
+    NotFound,
+    StaleRevision,
+    DuplicateName,
+    Conflict,
+    Unavailable,
+}
+
+/// 隐藏数据库实现细节的持久化错误。
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("{resource} store operation failed: {message}")]
+pub struct AdminStoreError {
+    kind: AdminStoreErrorKind,
+    resource: &'static str,
+    message: String,
+}
+
+impl AdminStoreError {
+    #[must_use]
+    pub fn new(
+        kind: AdminStoreErrorKind,
+        resource: &'static str,
+        message: impl Into<String>,
+    ) -> Self {
+        Self {
+            kind,
+            resource,
+            message: message.into(),
+        }
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> AdminStoreErrorKind {
+        self.kind
+    }
+
+    #[must_use]
+    pub const fn resource(&self) -> &'static str {
+        self.resource
+    }
+}
+
+pub type AdminStoreResult<T> = Result<T, AdminStoreError>;
+
+/// 账号目录与公共账号写操作。
+#[async_trait]
+pub trait AccountStore: Send + Sync {
+    /// 插件回调按授权 Provider/账号在数据库过滤后做稳定 cursor 分页。
+    async fn list_plugin_accounts(
+        &self,
+        query: PluginAccountListQuery,
+    ) -> AdminStoreResult<PluginAccountPage>;
+
+    async fn list_accounts(
+        &self,
+        query: AccountListQuery,
+        runtime: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<AccountPage>;
+
+    async fn load_account(
+        &self,
+        account_id: &str,
+        runtime: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<Option<AccountPageItem>>;
+
+    async fn load_account_usage(
+        &self,
+        range: TimeRange,
+        account_ids: &[String],
+    ) -> AdminStoreResult<Vec<AccountUsage>>;
+
+    async fn load_account_usage_by_windows(
+        &self,
+        windows: &[AccountUsageWindowQuery],
+    ) -> AdminStoreResult<Vec<AccountUsageWindowResult>>;
+
+    /// 从同一数据库语句取得截止快照的累计用量和有界历史观测。
+    async fn load_quota_forecast_history(
+        &self,
+        window: &AccountUsageWindowQuery,
+    ) -> AdminStoreResult<QuotaForecastHistory>;
+
+    async fn credential_details(
+        &self,
+        provider_kind: &gateway_core::routing::ProviderKind,
+        account_id: &gateway_core::account::ProviderAccountId,
+    ) -> AdminStoreResult<Option<CredentialDetails>>;
+
+    /// 插件按全局账号 ID 读取时，由数据库记录提供权威 Provider 归属。
+    async fn credential_details_by_id(
+        &self,
+        account_id: &gateway_core::account::ProviderAccountId,
+    ) -> AdminStoreResult<Option<CredentialDetails>>;
+
+    async fn load_credentials_for_export(
+        &self,
+        provider_kind: &gateway_core::routing::ProviderKind,
+        account_ids: &[gateway_core::account::ProviderAccountId],
+    ) -> AdminStoreResult<Vec<ProviderExportCredentialInput>>;
+
+    /// 插件凭据读取只接收账号 ID，不接受调用方另行声明 Provider。
+    async fn load_credential_for_plugin(
+        &self,
+        account_id: &gateway_core::account::ProviderAccountId,
+    ) -> AdminStoreResult<Option<ProviderExportCredentialInput>>;
+
+    async fn commit_credential_import(
+        &self,
+        command: CredentialImportCommit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<CredentialImportResult>;
+
+    async fn commit_authorization(
+        &self,
+        command: AuthorizationCommit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<crate::model::provider_credentials::AuthorizationCommitResult>;
+
+    /// 已提交的授权结果独立于 Redis 临时状态；只有原管理员身份可读。
+    async fn authorization_receipt(
+        &self,
+        key: &crate::model::provider_credentials::AuthorizationReceiptKey,
+    ) -> AdminStoreResult<Option<crate::model::provider_credentials::CredentialMutationResult>>;
+
+    async fn commit_credential_rotation(
+        &self,
+        command: CredentialRotationCommit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<CredentialMutationResult>;
+
+    async fn commit_credential_refresh(
+        &self,
+        command: CredentialRotationCommit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<CredentialMutationResult>;
+
+    async fn update_account(
+        &self,
+        command: UpdateAccount,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountUpdateResult>;
+
+    /// 在事务内按最新启用状态、账号上限和全局默认值判断，只降低并发上限。
+    async fn lower_concurrency_limit(
+        &self,
+        account_id: &gateway_core::account::ProviderAccountId,
+        limit: gateway_core::account::AccountConcurrencyLimit,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Option<AccountUpdateResult>>;
+
+    async fn recover_account(
+        &self,
+        account_id: &gateway_core::account::ProviderAccountId,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountUpdateResult>;
+
+    async fn batch_update_accounts(
+        &self,
+        command: BatchUpdateAccounts,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountsUpdateResult>;
+
+    async fn delete_accounts(
+        &self,
+        command: DeleteAccounts,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+
+    async fn record_credential_export(
+        &self,
+        account_ids: &[gateway_core::account::ProviderAccountId],
+        context: &MutationContext,
+    ) -> AdminStoreResult<()>;
+}
+
+/// 可丢失账号运行态的管理读端口；跨存储编排由 Admin application service 拥有。
+#[async_trait]
+pub trait AccountRuntimeStore: Send + Sync {
+    async fn active_rate_limits(&self) -> AdminStoreResult<AccountRuntimeSnapshot>;
+
+    async fn account_runtime(
+        &self,
+        account_ids: &[String],
+    ) -> AdminStoreResult<AccountRuntimeSnapshot>;
+
+    /// 容量熔断自动冻结中的账号与其冻结截止时间；429 临时限流不包含在内。
+    async fn active_freezes(
+        &self,
+    ) -> AdminStoreResult<BTreeMap<String, crate::model::accounts::AccountFreeze>>;
+
+    /// 读取容量失败窗口内观测到的在途并发峰值（自适应并发下调的证据）。
+    async fn capacity_peaks(
+        &self,
+        account_ids: &[String],
+    ) -> AdminStoreResult<BTreeMap<String, u32>>;
+
+    /// 仅当冻结快照仍匹配时解除或顺延；旧探测不得覆盖手动恢复或新一轮冻结。
+    async fn finish_freeze(
+        &self,
+        account_id: &str,
+        expected: &crate::model::accounts::AccountFreeze,
+        postpone_until: Option<DateTime<Utc>>,
+    ) -> AdminStoreResult<bool>;
+}
+
+/// 控制面凭据、统一会话、登录限流与管理员安全审计。
+#[async_trait]
+pub trait AuthStore: Send + Sync {
+    async fn load_password_hash(&self, admin_user_id: &str) -> AdminStoreResult<Option<String>>;
+
+    /// 密码更新与审计必须在同一事务提交；旧哈希不匹配时不写入。
+    async fn change_password(
+        &self,
+        admin_user_id: &str,
+        expected_hash: &str,
+        password_hash: &str,
+        audit: AdminAuditEvent,
+    ) -> AdminStoreResult<bool>;
+
+    async fn create_password_hash_if_absent(
+        &self,
+        admin_user_id: &str,
+        password_hash: &str,
+    ) -> AdminStoreResult<bool>;
+
+    async fn load_admin_api_key(&self) -> AdminStoreResult<Option<AdminApiKey>>;
+
+    async fn load_session(&self, session_id: &str) -> AdminStoreResult<Option<AuthSession>>;
+
+    async fn store_session(&self, session_id: &str, session: &AuthSession) -> AdminStoreResult<()>;
+
+    async fn delete_session(&self, session_id: &str) -> AdminStoreResult<Option<AuthSession>>;
+
+    async fn client_key_enabled(
+        &self,
+        id: &gateway_core::policy::ClientApiKeyId,
+    ) -> AdminStoreResult<bool>;
+
+    /// 原子消费来源桶与全局桶的一次登录尝试；被拒绝时返回建议重试间隔。
+    async fn consume_login_attempt(
+        &self,
+        source_ip: IpAddr,
+        source_limit: u32,
+        global_limit: u32,
+        window: Duration,
+    ) -> AdminStoreResult<Option<Duration>>;
+
+    async fn append_audit_event(&self, event: AdminAuditEvent) -> AdminStoreResult<()>;
+}
+
+/// Client API Key 资料读取与管理写入。
+#[async_trait]
+pub trait ClientKeyStore: Send + Sync {
+    /// 按已验证的 ID 读取资料，不读取完整明文 Key。
+    async fn get_client_key(
+        &self,
+        id: &gateway_core::policy::ClientApiKeyId,
+    ) -> AdminStoreResult<Option<ClientKeyRecord>>;
+
+    async fn list_client_keys(&self, query: ClientKeyListQuery) -> AdminStoreResult<ClientKeyPage>;
+
+    async fn reveal_client_key(
+        &self,
+        id: &gateway_core::policy::ClientApiKeyId,
+    ) -> AdminStoreResult<Option<ClientKeySecret>>;
+
+    async fn create_client_key(
+        &self,
+        command: NewClientKey,
+        context: &MutationContext,
+    ) -> AdminStoreResult<(Revision, ClientKeyRecord)>;
+
+    async fn update_client_key(
+        &self,
+        command: UpdateClientKey,
+        context: &MutationContext,
+    ) -> AdminStoreResult<(Revision, ClientKeyRecord)>;
+
+    async fn set_client_key_enabled(
+        &self,
+        command: SetClientKeyEnabled,
+        context: &MutationContext,
+    ) -> AdminStoreResult<(Revision, ClientKeyRecord)>;
+
+    async fn delete_client_key(
+        &self,
+        command: DeleteClientKey,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+
+    /// 仅修改运行时账本并原子记录审计，不推进配置版本。
+    async fn reset_client_key_budget(
+        &self,
+        command: ResetClientKeyBudget,
+        context: &MutationContext,
+    ) -> AdminStoreResult<()>;
+}
+
+/// Provider-neutral account group management transactions.
+#[async_trait]
+pub trait AccountGroupStore: Send + Sync {
+    async fn list_account_groups(
+        &self,
+        query: AccountGroupListQuery,
+    ) -> AdminStoreResult<AccountGroupPage>;
+
+    async fn load_account_group_members(
+        &self,
+        group_ids: &[gateway_core::routing::AccountGroupId],
+    ) -> AdminStoreResult<Vec<AccountGroupMemberFact>>;
+
+    async fn create_account_group(
+        &self,
+        command: NewAccountGroup,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation>;
+
+    async fn update_account_group(
+        &self,
+        command: UpdateAccountGroup,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation>;
+
+    async fn set_account_group_enabled(
+        &self,
+        command: SetAccountGroupEnabled,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation>;
+
+    async fn delete_account_group(
+        &self,
+        command: DeleteAccountGroup,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation>;
+}
+
+/// 逐条读取的已计算费用事实；消费结束或丢弃时释放查询资源。
+pub type UsageCalculatedBillingStream<'a> =
+    BoxStream<'a, AdminStoreResult<UsageCalculatedBillingFact>>;
+
+/// 用量、趋势、诊断与运维错误的只读能力。
+#[async_trait]
+pub trait ObservabilityStore: Send + Sync {
+    /// 返回历史统计区间和指定观测时刻下的实时账号状态。
+    async fn dashboard_summary(
+        &self,
+        range: TimeRange,
+        observed_at: DateTime<Utc>,
+    ) -> AdminStoreResult<DashboardObservation>;
+
+    /// 返回 Dashboard 可选的实时槽位事实。
+    ///
+    /// 该状态来自可丢失的运行时存储；无实现或运行时存储不可用时返回 `None`，不影响
+    /// 持久观测数据的读取。
+    async fn dashboard_runtime_slots(
+        &self,
+        _observed_at: DateTime<Utc>,
+    ) -> AdminStoreResult<Option<DashboardRuntimeSlots>> {
+        Ok(None)
+    }
+
+    async fn dashboard_trend(&self, range: TimeRange) -> AdminStoreResult<Vec<RequestMetricPoint>>;
+
+    async fn usage_trend(
+        &self,
+        range: TimeRange,
+        filter: UsageFilter,
+    ) -> AdminStoreResult<Vec<RequestMetricPoint>>;
+
+    /// 流式返回可由 Provider 重新校验的已计算费用事实，不保证顺序。
+    /// 查询及解码错误由流返回；调用方应逐条聚合，避免收集整个区间。
+    fn usage_calculated_billing_facts(
+        &self,
+        range: TimeRange,
+        filter: UsageFilter,
+    ) -> UsageCalculatedBillingStream<'_>;
+
+    async fn list_usage_records(&self, query: UsageQuery) -> AdminStoreResult<UsagePage>;
+
+    async fn usage_record_detail(&self, request_id: &str) -> AdminStoreResult<UsageDetail>;
+
+    async fn usage_summary(
+        &self,
+        range: TimeRange,
+        filter: UsageFilter,
+    ) -> AdminStoreResult<UsageOverview>;
+
+    async fn usage_diagnostics(
+        &self,
+        range: TimeRange,
+        filter: UsageFilter,
+        dimension: DiagnosticDimension,
+    ) -> AdminStoreResult<Vec<DiagnosticObservation>>;
+
+    async fn list_ops_errors(&self, query: OpsErrorQuery) -> AdminStoreResult<OpsErrorPage>;
+}
+
+/// Runtime settings 与管理员 API Key 写入。
+#[async_trait]
+pub trait SettingsStore: Send + Sync {
+    async fn load_pricing(&self) -> AdminStoreResult<crate::model::pricing::StoredPricing>;
+    async fn sync_pricing(
+        &self,
+        changes: crate::model::pricing::PricingSyncChanges,
+        context: &MutationContext,
+    ) -> AdminStoreResult<crate::model::Revision>;
+    async fn update_pricing(
+        &self,
+        command: crate::model::pricing::UpdatePricing,
+        context: &MutationContext,
+    ) -> AdminStoreResult<crate::model::Revision>;
+
+    async fn load_runtime_settings(&self) -> AdminStoreResult<RuntimeSettings>;
+
+    async fn admin_api_key_exists(&self) -> AdminStoreResult<bool>;
+
+    async fn replace_runtime_settings(
+        &self,
+        command: ReplaceRuntimeSettings,
+        context: &MutationContext,
+    ) -> AdminStoreResult<RuntimeSettings>;
+
+    async fn replace_admin_api_key(
+        &self,
+        key: AdminApiKey,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AdminApiKeyMutation>;
+
+    async fn delete_admin_api_key(
+        &self,
+        context: &MutationContext,
+    ) -> AdminStoreResult<AdminApiKeyMutation>;
+}
+
+/// 账号目录、运行态与分组所需的 Store 能力集合。
+#[derive(Clone)]
+pub struct AdminAccountStorePorts {
+    accounts: Arc<dyn AccountStore>,
+    runtime: Arc<dyn AccountRuntimeStore>,
+    groups: Arc<dyn AccountGroupStore>,
+    proxies: Arc<dyn super::proxy::ProxyStore>,
+}
+
+impl AdminAccountStorePorts {
+    #[must_use]
+    pub fn new(
+        accounts: Arc<dyn AccountStore>,
+        runtime: Arc<dyn AccountRuntimeStore>,
+        groups: Arc<dyn AccountGroupStore>,
+        proxies: Arc<dyn super::proxy::ProxyStore>,
+    ) -> Self {
+        Self {
+            accounts,
+            runtime,
+            groups,
+            proxies,
+        }
+    }
+}
+
+/// 管理用例所需能力的封闭集合。
+///
+/// 字段保持私有，每个 getter 只交出一种明确能力。该类型不提供通用拆包入口。
+#[derive(Clone)]
+pub struct AdminStorePorts {
+    accounts: AdminAccountStorePorts,
+    auth: Arc<dyn AuthStore>,
+    client_keys: Arc<dyn ClientKeyStore>,
+    observability: Arc<dyn ObservabilityStore>,
+    settings: Arc<dyn SettingsStore>,
+    backup: BackupStorePorts,
+    plugins: Arc<dyn super::plugins::PluginStore>,
+    plugin_state: Arc<dyn super::plugins::PluginStateStore>,
+    plugin_resources: Arc<dyn super::plugin_resources::PluginResourceStore>,
+}
+
+impl AdminStorePorts {
+    #[must_use]
+    pub fn plugin_resources(&self) -> Arc<dyn super::plugin_resources::PluginResourceStore> {
+        self.plugin_resources.clone()
+    }
+
+    #[must_use]
+    pub fn plugins(&self) -> Arc<dyn super::plugins::PluginStore> {
+        Arc::clone(&self.plugins)
+    }
+
+    #[must_use]
+    pub fn plugin_state(&self) -> Arc<dyn super::plugins::PluginStateStore> {
+        Arc::clone(&self.plugin_state)
+    }
+
+    #[expect(
+        clippy::too_many_arguments,
+        reason = "组合根需显式注入各领域窄端口，不能用服务定位器隐藏依赖"
+    )]
+    #[must_use]
+    pub fn new(
+        accounts: AdminAccountStorePorts,
+        auth: Arc<dyn AuthStore>,
+        client_keys: Arc<dyn ClientKeyStore>,
+        observability: Arc<dyn ObservabilityStore>,
+        settings: Arc<dyn SettingsStore>,
+        backup: BackupStorePorts,
+        plugins: Arc<dyn super::plugins::PluginStore>,
+        plugin_state: Arc<dyn super::plugins::PluginStateStore>,
+        plugin_resources: Arc<dyn super::plugin_resources::PluginResourceStore>,
+    ) -> Self {
+        Self {
+            accounts,
+            auth,
+            client_keys,
+            observability,
+            settings,
+            backup,
+            plugins,
+            plugin_state,
+            plugin_resources,
+        }
+    }
+
+    #[must_use]
+    pub fn accounts(&self) -> Arc<dyn AccountStore> {
+        self.accounts.accounts.clone()
+    }
+
+    #[must_use]
+    pub fn account_runtime(&self) -> Arc<dyn AccountRuntimeStore> {
+        self.accounts.runtime.clone()
+    }
+
+    #[must_use]
+    pub fn account_groups(&self) -> Arc<dyn AccountGroupStore> {
+        self.accounts.groups.clone()
+    }
+
+    #[must_use]
+    pub fn proxies(&self) -> Arc<dyn super::proxy::ProxyStore> {
+        self.accounts.proxies.clone()
+    }
+
+    #[must_use]
+    pub fn auth(&self) -> Arc<dyn AuthStore> {
+        self.auth.clone()
+    }
+
+    #[must_use]
+    pub fn client_keys(&self) -> Arc<dyn ClientKeyStore> {
+        self.client_keys.clone()
+    }
+
+    #[must_use]
+    pub fn observability(&self) -> Arc<dyn ObservabilityStore> {
+        self.observability.clone()
+    }
+
+    #[must_use]
+    pub fn settings(&self) -> Arc<dyn SettingsStore> {
+        self.settings.clone()
+    }
+
+    #[must_use]
+    pub fn backup(&self) -> BackupStorePorts {
+        self.backup.clone()
+    }
+}

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

@@ -0,0 +1,112 @@
+//! Host 为系统管理用例提供的进程与操作系统能力。
+
+use std::{pin::Pin, sync::Arc};
+
+use async_trait::async_trait;
+use futures::Stream;
+
+use crate::model::Revision;
+use crate::model::system::{
+    SystemOperationAccepted, SystemUpdateChannel, SystemUpdateDetail, SystemUpdateEvent,
+    SystemUpdateStatus, SystemVersion,
+};
+
+/// Host 已校验并解包的同一更新候选；字节只含发行清单，不含运行配置或凭据。
+#[derive(Clone)]
+pub struct SystemUpdateCandidate {
+    pub target_version: String,
+    pub release_manifest: Arc<[u8]>,
+}
+
+impl std::fmt::Debug for SystemUpdateCandidate {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("SystemUpdateCandidate")
+            .field("target_version", &self.target_version)
+            .field("release_manifest_bytes", &self.release_manifest.len())
+            .finish()
+    }
+}
+
+/// Host 系统操作失败类型。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SystemOperationErrorKind {
+    Invalid,
+    Conflict,
+    Upstream,
+    Internal,
+}
+
+/// 不泄漏路径、命令行或发布凭据的系统操作错误。
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("system operation failed: {message}")]
+pub struct SystemOperationError {
+    kind: SystemOperationErrorKind,
+    message: String,
+}
+
+impl SystemOperationError {
+    #[must_use]
+    pub fn new(kind: SystemOperationErrorKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+        }
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> SystemOperationErrorKind {
+        self.kind
+    }
+
+    /// 返回 Host 已完成脱敏的客户端安全消息。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+}
+
+/// 每个订阅者独占的系统事件流。
+pub type SystemUpdateEventStream = Pin<Box<dyn Stream<Item = SystemUpdateEvent> + Send + 'static>>;
+
+/// Admin 对启用实例和制品作兼容决策；Host 只负责候选下载、校验与文件交换。
+#[async_trait]
+pub trait SystemUpdatePreflight: Send + Sync {
+    async fn validate(
+        &self,
+        candidate: SystemUpdateCandidate,
+    ) -> Result<Revision, SystemOperationError>;
+
+    /// 在文件交换临界点复核全局配置 CAS，不能用较早快照掩盖实例变更。
+    async fn confirm_revision(&self, expected: Revision) -> Result<(), SystemOperationError>;
+}
+
+/// 版本、自更新、回滚和重启能力；实现唯一归 gateway-host。
+#[async_trait]
+pub trait SystemOperations: Send + Sync {
+    async fn version(&self) -> Result<SystemVersion, SystemOperationError>;
+
+    async fn update_detail(
+        &self,
+        refresh: bool,
+        channel: Option<SystemUpdateChannel>,
+    ) -> Result<SystemUpdateDetail, SystemOperationError>;
+
+    fn update_events(&self) -> SystemUpdateEventStream;
+
+    async fn perform_update(
+        &self,
+        target_version: Option<String>,
+        channel: Option<SystemUpdateChannel>,
+        preflight: Arc<dyn SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError>;
+
+    async fn update_status(&self) -> Result<SystemUpdateStatus, SystemOperationError>;
+
+    async fn rollback(
+        &self,
+        preflight: Arc<dyn SystemUpdatePreflight>,
+    ) -> Result<SystemOperationAccepted, SystemOperationError>;
+
+    async fn restart(&self) -> Result<SystemOperationAccepted, SystemOperationError>;
+}

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

@@ -0,0 +1,239 @@
+//! Account group management use cases.
+
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    sync::Arc,
+    time::SystemTime,
+};
+
+use async_trait::async_trait;
+use gateway_core::{
+    account::{AccountStatus, resolve_account_status},
+    routing::AccountGroupId,
+    runtime::SnapshotControl,
+};
+use uuid::Uuid;
+
+use crate::{
+    model::{
+        AdminError, MutationContext,
+        account_groups::{
+            AccountGroupAccountSummary, AccountGroupCapacity, AccountGroupListQuery,
+            AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage, AccountGroupRecord,
+            CreateAccountGroup, DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled,
+            UpdateAccountGroup,
+        },
+    },
+    ports::store::{AccountGroupStore, AccountRuntimeStore},
+};
+
+use super::{map_store_error, publish_committed};
+
+/// API-facing account group management service.
+#[async_trait]
+pub trait AccountGroupService: Send + Sync {
+    async fn list(&self, query: AccountGroupListQuery) -> Result<AccountGroupPage, AdminError>;
+    async fn create(
+        &self,
+        context: &MutationContext,
+        command: CreateAccountGroup,
+    ) -> Result<AccountGroupMutation, AdminError>;
+    async fn update(
+        &self,
+        context: &MutationContext,
+        command: UpdateAccountGroup,
+    ) -> Result<AccountGroupMutation, AdminError>;
+    async fn set_enabled(
+        &self,
+        context: &MutationContext,
+        command: SetAccountGroupEnabled,
+    ) -> Result<AccountGroupMutation, AdminError>;
+    async fn delete(
+        &self,
+        context: &MutationContext,
+        command: DeleteAccountGroup,
+    ) -> Result<AccountGroupMutation, AdminError>;
+}
+
+pub(crate) struct DefaultAccountGroupService {
+    store: Arc<dyn AccountGroupStore>,
+    runtime: Arc<dyn AccountRuntimeStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl DefaultAccountGroupService {
+    #[must_use]
+    pub(crate) fn new(
+        store: Arc<dyn AccountGroupStore>,
+        runtime: Arc<dyn AccountRuntimeStore>,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        Self {
+            store,
+            runtime,
+            snapshot,
+        }
+    }
+
+    async fn enrich_records(&self, records: &mut [AccountGroupRecord]) -> Result<(), AdminError> {
+        if records.is_empty() {
+            return Ok(());
+        }
+        let group_ids = records
+            .iter()
+            .map(|record| record.id.clone())
+            .collect::<Vec<_>>();
+        let members = self
+            .store
+            .load_account_group_members(&group_ids)
+            .await
+            .map_err(|error| map_store_error(error, "account group members"))?;
+        let account_ids = members
+            .iter()
+            .map(|member| member.account_id.clone())
+            .collect::<BTreeSet<_>>()
+            .into_iter()
+            .collect::<Vec<_>>();
+        let runtime = match self.runtime.account_runtime(&account_ids).await {
+            Ok(runtime) => runtime,
+            Err(error) => {
+                tracing::warn!(error = %error, "account group runtime projection is unavailable");
+                Default::default()
+            }
+        };
+        project_group_runtime(records, &members, &runtime);
+        Ok(())
+    }
+
+    async fn publish(
+        &self,
+        result: Result<AccountGroupMutation, crate::ports::store::AdminStoreError>,
+    ) -> Result<AccountGroupMutation, AdminError> {
+        let mut result = result.map_err(|error| map_store_error(error, "account group"))?;
+        if let Some(record) = result.record.as_mut() {
+            self.enrich_records(std::slice::from_mut(record)).await?;
+        }
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+}
+
+#[async_trait]
+impl AccountGroupService for DefaultAccountGroupService {
+    async fn list(&self, query: AccountGroupListQuery) -> Result<AccountGroupPage, AdminError> {
+        let mut page = self
+            .store
+            .list_account_groups(query)
+            .await
+            .map_err(|error| map_store_error(error, "account group"))?;
+        self.enrich_records(&mut page.items).await?;
+        Ok(page)
+    }
+
+    async fn create(
+        &self,
+        context: &MutationContext,
+        command: CreateAccountGroup,
+    ) -> Result<AccountGroupMutation, AdminError> {
+        let id = AccountGroupId::new(format!("grp_{}", Uuid::now_v7().simple()))
+            .map_err(|_| AdminError::internal("创建账号组 ID 失败"))?;
+        self.publish(
+            self.store
+                .create_account_group(
+                    NewAccountGroup {
+                        id,
+                        name: command.name,
+                        description: command.description,
+                        disable_fast: command.disable_fast,
+                        color: command.color,
+                    },
+                    context,
+                )
+                .await,
+        )
+        .await
+    }
+
+    async fn update(
+        &self,
+        context: &MutationContext,
+        command: UpdateAccountGroup,
+    ) -> Result<AccountGroupMutation, AdminError> {
+        self.publish(self.store.update_account_group(command, context).await)
+            .await
+    }
+
+    async fn set_enabled(
+        &self,
+        context: &MutationContext,
+        command: SetAccountGroupEnabled,
+    ) -> Result<AccountGroupMutation, AdminError> {
+        self.publish(self.store.set_account_group_enabled(command, context).await)
+            .await
+    }
+
+    async fn delete(
+        &self,
+        context: &MutationContext,
+        command: DeleteAccountGroup,
+    ) -> Result<AccountGroupMutation, AdminError> {
+        self.publish(self.store.delete_account_group(command, context).await)
+            .await
+    }
+}
+
+fn project_group_runtime(
+    records: &mut [AccountGroupRecord],
+    members: &[AccountGroupMemberFact],
+    runtime: &crate::model::accounts::AccountRuntimeSnapshot,
+) {
+    let now = SystemTime::now();
+    let mut status_by_account = BTreeMap::new();
+    let mut slots_by_account = BTreeMap::new();
+    let mut accounts_by_group = BTreeMap::<&str, Vec<&str>>::new();
+    for member in members {
+        let mut status = member.status.clone();
+        status.cooldown = runtime.cooldown.get(&member.account_id).copied();
+        status_by_account
+            .entry(member.account_id.as_str())
+            .or_insert_with(|| resolve_account_status(&status, now).status);
+        slots_by_account
+            .entry(member.account_id.as_str())
+            .or_insert(member.total_slots);
+        accounts_by_group
+            .entry(member.group_id.as_str())
+            .or_default()
+            .push(member.account_id.as_str());
+    }
+    for record in records {
+        let account_ids = accounts_by_group
+            .get(record.id.as_str())
+            .map_or(&[][..], Vec::as_slice);
+        let available_ids = account_ids
+            .iter()
+            .copied()
+            .filter(|account_id| status_by_account.get(account_id) == Some(&AccountStatus::Normal))
+            .collect::<Vec<_>>();
+        let total = u64::try_from(account_ids.len()).unwrap_or(u64::MAX);
+        let available = u64::try_from(available_ids.len()).unwrap_or(u64::MAX);
+        record.account_summary = AccountGroupAccountSummary {
+            available,
+            limited: total.saturating_sub(available),
+            total,
+        };
+        record.capacity = AccountGroupCapacity {
+            used_slots: if available_ids.is_empty() {
+                Some(0)
+            } else {
+                runtime.in_flight.as_ref().map(|in_flight| {
+                    available_ids.iter().fold(0_u64, |sum, account_id| {
+                        sum.saturating_add(in_flight.get(*account_id).copied().unwrap_or(0))
+                    })
+                })
+            },
+            total_slots: available_ids.iter().try_fold(0_u64, |sum, account_id| {
+                Some(sum.saturating_add(slots_by_account.get(*account_id).copied().flatten()?))
+            }),
+        };
+    }
+}

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

@@ -0,0 +1,431 @@
+//! 控制面登录、会话恢复与身份校验的唯一 owner。
+
+use std::{net::IpAddr, sync::Arc, time::Duration as StdDuration};
+
+use argon2::{Argon2, PasswordHash, PasswordHasher, PasswordVerifier};
+use async_trait::async_trait;
+use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
+use chrono::{Duration, Utc};
+use gateway_core::engine::execution::ClientKeyVerifier;
+use rand_core::{OsRng, RngCore as _};
+use sha2::{Digest, Sha256};
+use subtle::ConstantTimeEq as _;
+use uuid::Uuid;
+
+use crate::{
+    model::{
+        AdminError, AdminErrorKind,
+        auth::{
+            AdminAuditEvent, AuditActorKind, AuthSession, ChangePassword, LoginCommand, LoginError,
+            LoginResult, SessionSubject,
+        },
+    },
+    ports::store::AuthStore,
+};
+
+use super::map_store_error;
+
+/// 所有控制面接口消费同一个会话服务，权限由服务端身份决定。
+#[async_trait]
+pub trait AuthService: Send + Sync {
+    async fn change_password(
+        &self,
+        session_id: Option<&str>,
+        command: ChangePassword,
+        source_ip: IpAddr,
+    ) -> Result<(), AdminError>;
+    async fn ensure_default_admin(&self, password: &str) -> Result<bool, AdminError>;
+    async fn session(&self, session_id: Option<&str>) -> Result<Option<AuthSession>, AdminError>;
+    async fn resolve_admin_user_id(
+        &self,
+        session_id: Option<&str>,
+    ) -> Result<Option<String>, AdminError>;
+    async fn verify_admin_api_key(&self, key: &str) -> Result<bool, AdminError>;
+    async fn login(
+        &self,
+        command: LoginCommand,
+        source_ip: IpAddr,
+        previous_session_id: Option<&str>,
+    ) -> Result<LoginResult, LoginError>;
+    async fn logout(&self, session_id: &str) -> Result<(), AdminError>;
+}
+
+const MAX_SESSION_TTL_MINUTES: i64 = 366 * 24 * 60;
+const LOGIN_WINDOW: StdDuration = StdDuration::from_secs(60);
+const LOGIN_ATTEMPTS_PER_SOURCE: u32 = 10;
+const LOGIN_ATTEMPTS_GLOBAL: u32 = 200;
+
+pub(crate) struct DefaultAuthService {
+    default_admin_user_id: String,
+    admin_session_ttl: Duration,
+    key_session_ttl: Duration,
+    store: Arc<dyn AuthStore>,
+    verifier: Arc<dyn ClientKeyVerifier>,
+}
+
+impl DefaultAuthService {
+    #[must_use]
+    pub(crate) fn new(
+        default_admin_user_id: impl Into<String>,
+        admin_session_ttl_minutes: u64,
+        key_session_ttl_minutes: u64,
+        store: Arc<dyn AuthStore>,
+        verifier: Arc<dyn ClientKeyVerifier>,
+    ) -> Self {
+        Self {
+            default_admin_user_id: default_admin_user_id.into(),
+            admin_session_ttl: session_ttl(admin_session_ttl_minutes),
+            key_session_ttl: session_ttl(key_session_ttl_minutes),
+            store,
+            verifier,
+        }
+    }
+
+    fn auth_audit(&self, action: &str, admin_user_id: &str) -> AdminAuditEvent {
+        AdminAuditEvent {
+            id: format!("audit_{}", Uuid::now_v7().simple()),
+            actor_kind: AuditActorKind::AdminSession,
+            actor_admin_user_id: Some(admin_user_id.to_owned()),
+            actor_ref: crate::model::auth::admin_session_actor_ref(admin_user_id),
+            request_id: None,
+            action: action.to_owned(),
+            entity_kind: "admin_session".to_owned(),
+            entity_ref: admin_user_id.to_owned(),
+            config_revision: None,
+            changed_fields: Vec::new(),
+            occurred_at: Utc::now(),
+        }
+    }
+
+    async fn authenticate(&self, command: LoginCommand) -> Result<SessionSubject, LoginError> {
+        match command {
+            LoginCommand::Admin { username, password } => {
+                if username.as_deref().unwrap_or(&self.default_admin_user_id)
+                    != self.default_admin_user_id
+                {
+                    return Err(LoginError::InvalidCredentials);
+                }
+                let password_hash = self
+                    .store
+                    .load_password_hash(&self.default_admin_user_id)
+                    .await
+                    .map_err(|_| LoginError::Unavailable)?
+                    .ok_or(LoginError::InvalidCredentials)?;
+                if password.len() > 4096
+                    || !verify_admin_password(&password, &password_hash)
+                        .map_err(|_| LoginError::Unavailable)?
+                {
+                    return Err(LoginError::InvalidCredentials);
+                }
+                Ok(SessionSubject::Admin {
+                    admin_user_id: self.default_admin_user_id.clone(),
+                    credential_fingerprint: password_fingerprint(&password_hash),
+                })
+            }
+            LoginCommand::Key { api_key } => {
+                if api_key.is_empty() || api_key.len() > 4096 {
+                    return Err(LoginError::InvalidCredentials);
+                }
+                let client_key_id = self.verifier.verify_client_key(&api_key)?;
+                if !self
+                    .store
+                    .client_key_enabled(&client_key_id)
+                    .await
+                    .map_err(|_| LoginError::Unavailable)?
+                {
+                    return Err(LoginError::InvalidCredentials);
+                }
+                Ok(SessionSubject::Key { client_key_id })
+            }
+        }
+    }
+}
+
+#[async_trait]
+impl AuthService for DefaultAuthService {
+    async fn change_password(
+        &self,
+        session_id: Option<&str>,
+        command: ChangePassword,
+        source_ip: IpAddr,
+    ) -> Result<(), AdminError> {
+        let session = self
+            .session(session_id)
+            .await?
+            .ok_or_else(|| AdminError::new(AdminErrorKind::Unauthorized, "请先登录"))?;
+        let SessionSubject::Admin {
+            admin_user_id,
+            credential_fingerprint,
+        } = session.subject
+        else {
+            return Err(AdminError::new(
+                AdminErrorKind::Forbidden,
+                "仅管理员可以修改密码",
+            ));
+        };
+        if self
+            .store
+            .consume_login_attempt(
+                source_ip,
+                LOGIN_ATTEMPTS_PER_SOURCE,
+                LOGIN_ATTEMPTS_GLOBAL,
+                LOGIN_WINDOW,
+            )
+            .await
+            .map_err(|error| map_store_error(error, "password change limit"))?
+            .is_some()
+        {
+            return Err(AdminError::new(
+                AdminErrorKind::RateLimited,
+                "尝试过于频繁，请稍后再试",
+            ));
+        }
+        validate_new_password(&command.new_password)?;
+        let password_hash = self
+            .store
+            .load_password_hash(&admin_user_id)
+            .await
+            .map_err(|error| map_store_error(error, "administrator"))?
+            .filter(|hash| password_fingerprint(hash) == credential_fingerprint)
+            .ok_or_else(|| AdminError::conflict("密码已变更，请重新登录"))?;
+        if command.current_password.len() > 4096
+            || !verify_admin_password(&command.current_password, &password_hash)?
+        {
+            return Err(AdminError::invalid("当前密码不正确"));
+        }
+        if command.new_password == command.current_password {
+            return Err(AdminError::invalid("新密码不能与当前密码相同"));
+        }
+        let hash = hash_admin_password(&command.new_password)?;
+        let mut audit = self.auth_audit("admin.password_changed", &admin_user_id);
+        audit.entity_kind = "admin_user".to_owned();
+        audit.changed_fields = vec!["password".to_owned()];
+        if !self
+            .store
+            .change_password(&admin_user_id, &password_hash, &hash, audit)
+            .await
+            .map_err(|error| map_store_error(error, "administrator password"))?
+        {
+            return Err(AdminError::conflict("密码已变更，请重新登录"));
+        }
+        // 密码事务提交后旧指纹不再匹配，会话撤销不依赖 Redis 删除成功。
+        Ok(())
+    }
+
+    async fn ensure_default_admin(&self, password: &str) -> Result<bool, AdminError> {
+        let hash = hash_admin_password(password)?;
+        self.store
+            .create_password_hash_if_absent(&self.default_admin_user_id, &hash)
+            .await
+            .map_err(|error| map_store_error(error, "administrator"))
+    }
+
+    async fn session(&self, session_id: Option<&str>) -> Result<Option<AuthSession>, AdminError> {
+        let Some(session_id) = session_id.filter(|value| !value.is_empty()) else {
+            return Ok(None);
+        };
+        let Some(session) = self
+            .store
+            .load_session(session_id)
+            .await
+            .map_err(|error| map_store_error(error, "authentication session"))?
+        else {
+            return Ok(None);
+        };
+        if session.expires_at <= Utc::now() {
+            let _ = self.store.delete_session(session_id).await;
+            return Ok(None);
+        }
+        if let SessionSubject::Admin {
+            admin_user_id,
+            credential_fingerprint,
+        } = &session.subject
+        {
+            let password_hash = self
+                .store
+                .load_password_hash(admin_user_id)
+                .await
+                .map_err(|error| map_store_error(error, "administrator session"))?;
+            if password_hash
+                .is_none_or(|hash| password_fingerprint(&hash) != *credential_fingerprint)
+            {
+                let _ = self.store.delete_session(session_id).await;
+                return Ok(None);
+            }
+        }
+        if let SessionSubject::Key { client_key_id } = &session.subject
+            && !self
+                .store
+                .client_key_enabled(client_key_id)
+                .await
+                .map_err(|error| map_store_error(error, "session key"))?
+        {
+            let _ = self.store.delete_session(session_id).await;
+            return Ok(None);
+        }
+        Ok(Some(session))
+    }
+
+    async fn resolve_admin_user_id(
+        &self,
+        session_id: Option<&str>,
+    ) -> Result<Option<String>, AdminError> {
+        match self
+            .session(session_id)
+            .await?
+            .map(|session| session.subject)
+        {
+            Some(SessionSubject::Admin { admin_user_id, .. }) => Ok(Some(admin_user_id)),
+            Some(SessionSubject::Key { .. }) => Err(AdminError::new(
+                AdminErrorKind::Forbidden,
+                "当前身份无权访问管理接口",
+            )),
+            None => Ok(None),
+        }
+    }
+
+    async fn verify_admin_api_key(&self, key: &str) -> Result<bool, AdminError> {
+        if !valid_admin_api_key_shape(key) {
+            return Ok(false);
+        }
+        let stored = self
+            .store
+            .load_admin_api_key()
+            .await
+            .map_err(|error| map_store_error(error, "administrator API key"))?;
+        Ok(stored.as_ref().is_some_and(|stored| {
+            let stored = stored.expose_for_auth();
+            key.len() == stored.len() && bool::from(key.as_bytes().ct_eq(stored.as_bytes()))
+        }))
+    }
+
+    async fn login(
+        &self,
+        command: LoginCommand,
+        source_ip: IpAddr,
+        previous_session_id: Option<&str>,
+    ) -> Result<LoginResult, LoginError> {
+        if let Some(retry_after) = self
+            .store
+            .consume_login_attempt(
+                source_ip,
+                LOGIN_ATTEMPTS_PER_SOURCE,
+                LOGIN_ATTEMPTS_GLOBAL,
+                LOGIN_WINDOW,
+            )
+            .await
+            .map_err(|_| LoginError::Unavailable)?
+        {
+            return Err(LoginError::TooManyAttempts {
+                retry_after_seconds: retry_after.as_secs().max(1),
+            });
+        }
+        let subject = self.authenticate(command).await?;
+        let ttl = match subject {
+            SessionSubject::Admin { .. } => self.admin_session_ttl,
+            SessionSubject::Key { .. } => self.key_session_ttl,
+        };
+        let session = AuthSession {
+            subject,
+            expires_at: Utc::now() + ttl,
+        };
+        let session_id = random_session_token();
+        self.store
+            .store_session(&session_id, &session)
+            .await
+            .map_err(|_| LoginError::Unavailable)?;
+        if let SessionSubject::Admin { admin_user_id, .. } = &session.subject
+            && self
+                .store
+                .append_audit_event(self.auth_audit("admin.login", admin_user_id))
+                .await
+                .is_err()
+        {
+            let _ = self.store.delete_session(&session_id).await;
+            return Err(LoginError::Unavailable);
+        }
+        // 新身份验证成功后才撤销旧会话；撤销失败时不向浏览器提交新会话。
+        if let Some(previous) = previous_session_id.filter(|value| !value.is_empty())
+            && self.logout(previous).await.is_err()
+        {
+            let _ = self.store.delete_session(&session_id).await;
+            return Err(LoginError::Unavailable);
+        }
+        Ok(LoginResult {
+            session_id,
+            session,
+        })
+    }
+
+    async fn logout(&self, session_id: &str) -> Result<(), AdminError> {
+        let session = self
+            .store
+            .delete_session(session_id)
+            .await
+            .map_err(|error| map_store_error(error, "authentication session"))?;
+        if let Some(AuthSession {
+            subject: SessionSubject::Admin { admin_user_id, .. },
+            ..
+        }) = session
+        {
+            self.store
+                .append_audit_event(self.auth_audit("admin.logout", &admin_user_id))
+                .await
+                .map_err(|error| map_store_error(error, "administrator audit"))?;
+        }
+        Ok(())
+    }
+}
+
+fn session_ttl(minutes: u64) -> Duration {
+    Duration::minutes(
+        i64::try_from(minutes)
+            .unwrap_or(MAX_SESSION_TTL_MINUTES)
+            .clamp(1, MAX_SESSION_TTL_MINUTES),
+    )
+}
+
+fn validate_new_password(password: &str) -> Result<(), AdminError> {
+    if password.trim().chars().count() < 12
+        || password.len() > 1024
+        || password.chars().any(char::is_control)
+        || crate::WEAK_ADMIN_PASSWORDS.contains(&password.trim().to_ascii_lowercase().as_str())
+    {
+        return Err(AdminError::invalid(
+            "新密码至少需要 12 个字符，最多 1024 字节，不能使用常见弱口令或控制字符",
+        ));
+    }
+    Ok(())
+}
+
+fn hash_admin_password(password: &str) -> Result<String, AdminError> {
+    Argon2::default()
+        .hash_password(password.as_bytes())
+        .map(|hash| hash.to_string())
+        .map_err(|_| AdminError::internal("管理员密码哈希失败"))
+}
+
+fn verify_admin_password(password: &str, encoded: &str) -> Result<bool, AdminError> {
+    let hash = PasswordHash::new(encoded)
+        .map_err(|_| AdminError::internal("已保存的管理员密码哈希不合法"))?;
+    Ok(Argon2::default()
+        .verify_password(password.as_bytes(), &hash)
+        .is_ok())
+}
+
+fn random_session_token() -> String {
+    let mut bytes = [0_u8; 32];
+    OsRng.fill_bytes(&mut bytes);
+    format!("session_{}", URL_SAFE_NO_PAD.encode(bytes))
+}
+
+fn valid_admin_api_key_shape(value: &str) -> bool {
+    value.len() == 70
+        && value.starts_with("admin-")
+        && value[6..].bytes().all(|byte| byte.is_ascii_hexdigit())
+}
+
+// 指纹只绑定已加盐的密码哈希，不把密码或原始哈希复制到 Redis 会话。
+fn password_fingerprint(password_hash: &str) -> String {
+    URL_SAFE_NO_PAD.encode(Sha256::digest(password_hash.as_bytes()))
+}

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

@@ -0,0 +1,437 @@
+//! 备份配置、手动创建、下载与删除用例。
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use gateway_core::runtime::SnapshotControl;
+use secrecy::ExposeSecret as _;
+use uuid::Uuid;
+
+use crate::model::{
+    AdminError, AdminErrorKind, MutationContext,
+    auth::{AdminAuditEvent, AuditActorKind},
+    backup::{
+        BackupError, BackupRecord, BackupRecordListQuery, BackupRecordPage, BackupSettings,
+        BackupStatus, BackupStorageConfig, BackupTriggerKind, ConnectionTestResult,
+        DownloadUrlResult, UpdateBackupScheduleCommand, UpdateBackupStorageCommand,
+        build_backup_seed, code,
+    },
+};
+use crate::ports::{
+    backup::{BackupObjectStorePort, BackupRepository},
+    store::AuthStore,
+};
+
+use super::map_store_error;
+
+/// 默认下载地址有效期。
+const DOWNLOAD_TTL: Duration = Duration::from_secs(5 * 60);
+
+/// API 消费的备份管理服务。
+#[async_trait]
+pub trait BackupService: Send + Sync {
+    async fn load_settings(&self) -> Result<BackupSettings, AdminError>;
+
+    async fn update_storage(
+        &self,
+        context: &MutationContext,
+        command: UpdateBackupStorageCommand,
+    ) -> Result<BackupSettings, AdminError>;
+
+    async fn update_schedule(
+        &self,
+        context: &MutationContext,
+        command: UpdateBackupScheduleCommand,
+    ) -> Result<BackupSettings, AdminError>;
+
+    async fn test_connection(
+        &self,
+        context: &MutationContext,
+    ) -> Result<ConnectionTestResult, AdminError>;
+
+    async fn create_backup(
+        &self,
+        context: &MutationContext,
+        expires_at: Option<DateTime<Utc>>,
+    ) -> Result<BackupRecord, AdminError>;
+
+    async fn list_records(
+        &self,
+        query: BackupRecordListQuery,
+    ) -> Result<BackupRecordPage, AdminError>;
+
+    async fn download_url(
+        &self,
+        context: &MutationContext,
+        backup_id: &str,
+    ) -> Result<DownloadUrlResult, AdminError>;
+
+    async fn delete_backup(
+        &self,
+        context: &MutationContext,
+        backup_id: &str,
+    ) -> Result<BackupRecord, AdminError>;
+}
+
+pub(crate) struct DefaultBackupService {
+    repository: Arc<dyn BackupRepository>,
+    object_store: Arc<dyn BackupObjectStorePort>,
+    auth: Arc<dyn AuthStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl DefaultBackupService {
+    #[must_use]
+    pub(crate) fn new(
+        repository: Arc<dyn BackupRepository>,
+        object_store: Arc<dyn BackupObjectStorePort>,
+        auth: Arc<dyn AuthStore>,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        Self {
+            repository,
+            object_store,
+            auth,
+            snapshot,
+        }
+    }
+}
+
+#[async_trait]
+impl BackupService for DefaultBackupService {
+    async fn load_settings(&self) -> Result<BackupSettings, AdminError> {
+        self.repository
+            .load_settings()
+            .await
+            .map_err(|error| map_store_error(error, "backup settings"))
+    }
+
+    async fn update_storage(
+        &self,
+        context: &MutationContext,
+        command: UpdateBackupStorageCommand,
+    ) -> Result<BackupSettings, AdminError> {
+        validate_storage(&command)?;
+        let (settings, revision) = self
+            .repository
+            .update_storage_settings(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "backup storage"))?;
+        super::publish_committed(self.snapshot.as_ref(), revision).await?;
+        Ok(settings)
+    }
+
+    async fn update_schedule(
+        &self,
+        context: &MutationContext,
+        command: UpdateBackupScheduleCommand,
+    ) -> Result<BackupSettings, AdminError> {
+        validate_schedule(&command)?;
+        let next_run_at = if command.schedule_enabled {
+            Some(
+                crate::backup::policy::BackupSchedule::parse(
+                    &command.cron_expression,
+                    &command.schedule_timezone,
+                )
+                .map_err(map_backup_error)?
+                .next_after(Utc::now())
+                .ok_or_else(|| AdminError::bad_request("无法从计划推导下次执行时间"))?,
+            )
+        } else {
+            None
+        };
+        self.repository
+            .update_schedule_settings(command, next_run_at, context)
+            .await
+            .map_err(|error| map_store_error(error, "backup schedule"))
+    }
+
+    async fn test_connection(
+        &self,
+        context: &MutationContext,
+    ) -> Result<ConnectionTestResult, AdminError> {
+        let settings = self
+            .repository
+            .load_settings()
+            .await
+            .map_err(|error| map_store_error(error, "backup settings"))?;
+        let Some(config) = BackupStorageConfig::from_settings(&settings) else {
+            return Ok(ConnectionTestResult {
+                ok: false,
+                stage: "putObject",
+                code: Some(code::INVALID_CONFIG),
+                message: "备份存储配置不完整，无法执行连接测试".to_owned(),
+            });
+        };
+        let result = self
+            .object_store
+            .test_connection(&config)
+            .await
+            .map_err(map_backup_error)?;
+        if result.ok {
+            let _ = self
+                .repository
+                .record_verification(config.storage_revision, Utc::now())
+                .await
+                .map_err(|error| map_store_error(error, "backup settings"))?;
+        }
+        self.append_audit(
+            context,
+            "backup.s3_connection_tested",
+            "backup_settings",
+            vec![],
+        )
+        .await?;
+        Ok(result)
+    }
+
+    async fn create_backup(
+        &self,
+        context: &MutationContext,
+        expires_at: Option<DateTime<Utc>>,
+    ) -> Result<BackupRecord, AdminError> {
+        let settings = self
+            .repository
+            .load_settings()
+            .await
+            .map_err(|error| map_store_error(error, "backup settings"))?;
+        if !settings.storage_configured() {
+            return Err(AdminError::bad_request(
+                "备份存储配置不完整，请先保存存储配置",
+            ));
+        }
+        if !settings.storage_verified() {
+            return Err(AdminError::bad_request(
+                "备份存储尚未通过连接测试，请先测试存储配置",
+            ));
+        }
+        let prefix = settings.prefix.as_deref().unwrap_or_default();
+        let seed = build_backup_seed(
+            BackupTriggerKind::Manual,
+            None,
+            prefix,
+            Utc::now(),
+            expires_at,
+        )
+        .map_err(map_backup_error)?;
+        let record = self
+            .repository
+            .insert_backup_record(seed)
+            .await
+            .map_err(|error| map_store_error(error, "backup record"))?;
+        self.append_audit(context, "backup.created", "backup", vec![record.id.clone()])
+            .await?;
+        Ok(record)
+    }
+
+    async fn list_records(
+        &self,
+        query: BackupRecordListQuery,
+    ) -> Result<BackupRecordPage, AdminError> {
+        self.repository
+            .list_backup_records(query)
+            .await
+            .map_err(|error| map_store_error(error, "backup records"))
+    }
+
+    async fn download_url(
+        &self,
+        context: &MutationContext,
+        backup_id: &str,
+    ) -> Result<DownloadUrlResult, AdminError> {
+        let record = self.require_record(backup_id).await?;
+        if record.status != BackupStatus::Completed {
+            return Err(AdminError::conflict(
+                "只有 completed 的备份才能创建下载地址",
+            ));
+        }
+        let settings = self
+            .repository
+            .load_settings()
+            .await
+            .map_err(|error| map_store_error(error, "backup settings"))?;
+        let Some(config) = BackupStorageConfig::from_settings(&settings) else {
+            return Err(AdminError::bad_request("备份存储配置不完整"));
+        };
+        let file_name = crate::model::backup::build_download_file_name(backup_id);
+        let url = self
+            .object_store
+            .presigned_download(&config, &record.object_key, &file_name, DOWNLOAD_TTL)
+            .await
+            .map_err(map_backup_error)?;
+        self.append_audit(
+            context,
+            "backup.download_url_created",
+            "backup",
+            vec![backup_id.to_owned()],
+        )
+        .await?;
+        Ok(DownloadUrlResult {
+            url,
+            file_name,
+            expires_in: DOWNLOAD_TTL,
+        })
+    }
+
+    async fn delete_backup(
+        &self,
+        context: &MutationContext,
+        backup_id: &str,
+    ) -> Result<BackupRecord, AdminError> {
+        let record = self.require_record(backup_id).await?;
+        if !record.status.can_be_deleted() {
+            return Err(AdminError::conflict(
+                "只有 completed 或 failed 的备份才能删除",
+            ));
+        }
+        let now = Utc::now();
+        let deleting = self
+            .repository
+            .transition_to_deleting(backup_id, now)
+            .await
+            .map_err(|error| map_store_error(error, "backup record"))?
+            .ok_or_else(|| AdminError::conflict("备份记录已进入删除流程"))?;
+        self.append_audit(
+            context,
+            "backup.delete_requested",
+            "backup",
+            vec![backup_id.to_owned()],
+        )
+        .await?;
+        Ok(deleting)
+    }
+}
+
+impl DefaultBackupService {
+    async fn require_record(&self, backup_id: &str) -> Result<BackupRecord, AdminError> {
+        self.repository
+            .load_backup_record(backup_id)
+            .await
+            .map_err(|error| map_store_error(error, "backup record"))?
+            .ok_or_else(|| AdminError::not_found("备份记录不存在"))
+    }
+
+    async fn append_audit(
+        &self,
+        context: &MutationContext,
+        action: &str,
+        entity_ref: &str,
+        changed_fields: Vec<String>,
+    ) -> Result<(), AdminError> {
+        let actor_kind = match context.actor {
+            crate::model::MutationActor::AdminSession { .. } => AuditActorKind::AdminSession,
+            crate::model::MutationActor::AdminApiKey => AuditActorKind::AdminApiKey,
+            crate::model::MutationActor::System => AuditActorKind::System,
+        };
+        let actor_ref = match &context.actor {
+            crate::model::MutationActor::AdminSession { admin_user_id } => {
+                crate::model::auth::admin_session_actor_ref(admin_user_id)
+            }
+            crate::model::MutationActor::AdminApiKey => "admin_api_key".to_owned(),
+            crate::model::MutationActor::System => "system".to_owned(),
+        };
+        let actor_admin_user_id = match &context.actor {
+            crate::model::MutationActor::AdminSession { admin_user_id } => {
+                Some(admin_user_id.clone())
+            }
+            _ => None,
+        };
+        let event = AdminAuditEvent {
+            id: format!("audit_{}", Uuid::now_v7().simple()),
+            actor_kind,
+            actor_admin_user_id,
+            actor_ref,
+            request_id: Some(context.request_id.clone()),
+            action: action.to_owned(),
+            entity_kind: "backup".to_owned(),
+            entity_ref: entity_ref.to_owned(),
+            config_revision: None,
+            changed_fields,
+            occurred_at: Utc::now(),
+        };
+        self.auth
+            .append_audit_event(event)
+            .await
+            .map_err(|error| map_store_error(error, "backup audit"))
+    }
+}
+
+/// 校验存储配置；空串视为非法，Secret 缺省表示保留旧值。
+fn validate_storage(command: &UpdateBackupStorageCommand) -> Result<(), AdminError> {
+    validate_endpoint(&command.endpoint)?;
+    validate_nonempty("region", &command.region)?;
+    validate_nonempty("bucket", &command.bucket)?;
+    validate_nonempty("accessKeyId", &command.access_key_id)?;
+    if let Some(secret) = command.secret_access_key.as_ref() {
+        let value = secret.expose_secret();
+        if value.is_empty() {
+            return Err(AdminError::bad_request(
+                "secretAccessKey 不能为空字符串；缺省表示保留旧值",
+            ));
+        }
+        validate_length("secretAccessKey", value, 512)?;
+    }
+    crate::model::backup::normalize_prefix(&command.prefix).map_err(map_backup_error)?;
+    Ok(())
+}
+
+fn validate_endpoint(value: &str) -> Result<(), AdminError> {
+    if value.is_empty() {
+        return Err(AdminError::bad_request("endpoint 不能为空"));
+    }
+    if !value.starts_with("https://") {
+        return Err(AdminError::bad_request(
+            "endpoint 必须使用 HTTPS；仅测试或显式开发配置允许 HTTP",
+        ));
+    }
+    if value.contains('@') || value.bytes().any(|byte| byte.is_ascii_control()) {
+        return Err(AdminError::bad_request("endpoint 格式非法"));
+    }
+    validate_length("endpoint", value, 2048)
+}
+
+fn validate_nonempty(field: &str, value: &str) -> Result<(), AdminError> {
+    if value.is_empty() {
+        return Err(AdminError::bad_request(format!("{field} 不能为空")));
+    }
+    validate_length(field, value, 255)
+}
+
+fn validate_length(field: &str, value: &str, max: usize) -> Result<(), AdminError> {
+    if value.len() > max || value.bytes().any(|byte| byte.is_ascii_control()) {
+        return Err(AdminError::bad_request(format!(
+            "{field} 超出长度或包含非法字符"
+        )));
+    }
+    Ok(())
+}
+
+/// 校验调度配置并解析 Cron 与时区。
+fn validate_schedule(command: &UpdateBackupScheduleCommand) -> Result<(), AdminError> {
+    if command.cron_expression.trim().is_empty() {
+        return Err(AdminError::bad_request("cronExpression 不能为空"));
+    }
+    crate::backup::policy::BackupSchedule::parse(
+        &command.cron_expression,
+        &command.schedule_timezone,
+    )
+    .map_err(map_backup_error)?;
+    Ok(())
+}
+
+/// 备份基础设施错误到既有 `AdminErrorKind` 的唯一边界映射。
+fn map_backup_error(error: BackupError) -> AdminError {
+    match error.code() {
+        code::INVALID_CONFIG | code::INVALID_CRON | code::INVALID_TIMEZONE => {
+            AdminError::bad_request(error.message().to_owned())
+        }
+        code::RECORD_NOT_FOUND => AdminError::not_found(error.message().to_owned()),
+        code::ACTIVE_TASK_CONFLICT | code::STATE_CONFLICT | code::STORAGE_IDENTITY_LOCKED => {
+            AdminError::conflict(error.message().to_owned())
+        }
+        code::STORE_UNAVAILABLE => AdminError::new(AdminErrorKind::Unavailable, "备份服务暂不可用"),
+        _ => AdminError::bad_gateway("备份服务请求失败"),
+    }
+}

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

@@ -0,0 +1,33 @@
+//! Codex 客户端下载信息用例。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+
+use crate::{
+    model::client_distribution::CodexDesktopWindowsDownloads,
+    ports::client_distribution::ClientDistributionResolver,
+};
+
+#[async_trait]
+pub trait ClientDistributionService: Send + Sync {
+    async fn codex_desktop_windows(&self, refresh: bool) -> CodexDesktopWindowsDownloads;
+}
+
+pub(crate) struct DefaultClientDistributionService {
+    resolver: Arc<dyn ClientDistributionResolver>,
+}
+
+impl DefaultClientDistributionService {
+    #[must_use]
+    pub(crate) const fn new(resolver: Arc<dyn ClientDistributionResolver>) -> Self {
+        Self { resolver }
+    }
+}
+
+#[async_trait]
+impl ClientDistributionService for DefaultClientDistributionService {
+    async fn codex_desktop_windows(&self, refresh: bool) -> CodexDesktopWindowsDownloads {
+        self.resolver.resolve_codex_desktop_windows(refresh).await
+    }
+}

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

@@ -0,0 +1,264 @@
+//! Client API Key 管理用例。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
+use gateway_core::policy::ClientApiKeyId;
+use gateway_core::runtime::SnapshotControl;
+use rand_core::{OsRng, RngCore as _};
+use uuid::Uuid;
+
+use crate::{
+    model::{
+        AdminError, MutationContext,
+        client_keys::{
+            ClientKeyCursorValue, ClientKeyListQuery, ClientKeyMutation, ClientKeyPage,
+            ClientKeySecret, ClientKeySortField, CreateClientKey, CreatedClientKey,
+            DeleteClientKey, NewClientKey, ResetClientKeyBudget, SetClientKeyEnabled,
+            UpdateClientKey,
+        },
+    },
+    ports::store::{AdminStoreError, AdminStoreErrorKind, ClientKeyStore},
+};
+
+use super::{map_store_error, publish_committed};
+
+/// API 消费的 Client Key 管理服务。
+#[async_trait]
+pub trait ClientKeyService: Send + Sync {
+    async fn list(&self, query: ClientKeyListQuery) -> Result<ClientKeyPage, AdminError>;
+    async fn reveal(&self, id: &ClientApiKeyId) -> Result<ClientKeySecret, AdminError>;
+    async fn create(
+        &self,
+        context: &MutationContext,
+        command: CreateClientKey,
+    ) -> Result<CreatedClientKey, AdminError>;
+    async fn update(
+        &self,
+        context: &MutationContext,
+        command: UpdateClientKey,
+    ) -> Result<ClientKeyMutation, AdminError>;
+    async fn set_enabled(
+        &self,
+        context: &MutationContext,
+        command: SetClientKeyEnabled,
+    ) -> Result<ClientKeyMutation, AdminError>;
+    async fn delete(
+        &self,
+        context: &MutationContext,
+        command: DeleteClientKey,
+    ) -> Result<ClientKeyMutation, AdminError>;
+    async fn reset_budget(
+        &self,
+        context: &MutationContext,
+        command: ResetClientKeyBudget,
+    ) -> Result<ClientApiKeyId, AdminError>;
+}
+
+pub(crate) struct DefaultClientKeyService {
+    providers: crate::ports::provider::ProviderAdminRegistry,
+    store: Arc<dyn ClientKeyStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl DefaultClientKeyService {
+    #[must_use]
+    pub(crate) fn new(
+        store: Arc<dyn ClientKeyStore>,
+        snapshot: Arc<dyn SnapshotControl>,
+        providers: crate::ports::provider::ProviderAdminRegistry,
+    ) -> Self {
+        Self {
+            store,
+            snapshot,
+            providers,
+        }
+    }
+}
+
+#[async_trait]
+impl ClientKeyService for DefaultClientKeyService {
+    async fn reset_budget(
+        &self,
+        context: &MutationContext,
+        command: ResetClientKeyBudget,
+    ) -> Result<ClientApiKeyId, AdminError> {
+        let id = command.id.clone();
+        self.store
+            .reset_client_key_budget(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "client API key"))?;
+        Ok(id)
+    }
+
+    async fn list(&self, query: ClientKeyListQuery) -> Result<ClientKeyPage, AdminError> {
+        validate_cursor(&query)?;
+        self.store
+            .list_client_keys(query)
+            .await
+            .map_err(|error| map_store_error(error, "client API key"))
+    }
+
+    async fn reveal(&self, id: &ClientApiKeyId) -> Result<ClientKeySecret, AdminError> {
+        self.store
+            .reveal_client_key(id)
+            .await
+            .map_err(|error| map_store_error(error, "client API key"))?
+            .ok_or_else(|| AdminError::not_found("Client API Key 不存在"))
+    }
+
+    async fn create(
+        &self,
+        context: &MutationContext,
+        command: CreateClientKey,
+    ) -> Result<CreatedClientKey, AdminError> {
+        for (provider, profile) in &command.request_profile_overrides {
+            self.providers
+                .require(provider)
+                .and_then(|provider| provider.preview_client_profile(profile))
+                .map_err(|error| super::map_provider_error(error, "client profile"))?;
+        }
+        let id = ClientApiKeyId::new(format!("key_{}", Uuid::now_v7().simple()))
+            .map_err(|_| AdminError::internal("创建 Client API Key ID 失败"))?;
+        let plaintext = if let Some(key) = command.custom_key {
+            key.expose_for_auth().to_owned()
+        } else {
+            generate_key()
+        };
+        let (config_revision, record) = self
+            .store
+            .create_client_key(
+                NewClientKey {
+                    request_profile_overrides: command.request_profile_overrides,
+                    id,
+                    name: command.name,
+                    label: command.label,
+                    group_ids: command.group_ids,
+                    limits: command.limits,
+                    budget: command.budget,
+                    plaintext: plaintext.clone(),
+                },
+                context,
+            )
+            .await
+            .map_err(map_client_key_write_error)?;
+        publish_committed(self.snapshot.as_ref(), config_revision).await?;
+        Ok(CreatedClientKey {
+            config_revision,
+            secret: ClientKeySecret::new(record, plaintext),
+        })
+    }
+
+    async fn update(
+        &self,
+        context: &MutationContext,
+        command: UpdateClientKey,
+    ) -> Result<ClientKeyMutation, AdminError> {
+        for (provider, profile) in &command.request_profile_override_updates {
+            if let Some(profile) = profile {
+                self.providers
+                    .require(provider)
+                    .and_then(|provider| provider.preview_client_profile(profile))
+                    .map_err(|error| super::map_provider_error(error, "client profile"))?;
+            }
+        }
+        let id = command.id.clone();
+        let (config_revision, record) = self
+            .store
+            .update_client_key(command, context)
+            .await
+            .map_err(map_client_key_write_error)?;
+        publish_committed(self.snapshot.as_ref(), config_revision).await?;
+        Ok(ClientKeyMutation {
+            config_revision,
+            record: Some(record),
+            id,
+        })
+    }
+
+    async fn set_enabled(
+        &self,
+        context: &MutationContext,
+        command: SetClientKeyEnabled,
+    ) -> Result<ClientKeyMutation, AdminError> {
+        let id = command.id.clone();
+        let (config_revision, record) =
+            self.store
+                .set_client_key_enabled(command, context)
+                .await
+                .map_err(|error| map_store_error(error, "client API key"))?;
+        publish_committed(self.snapshot.as_ref(), config_revision).await?;
+        Ok(ClientKeyMutation {
+            config_revision,
+            record: Some(record),
+            id,
+        })
+    }
+
+    async fn delete(
+        &self,
+        context: &MutationContext,
+        command: DeleteClientKey,
+    ) -> Result<ClientKeyMutation, AdminError> {
+        let id = command.id.clone();
+        let config_revision = self
+            .store
+            .delete_client_key(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "client API key"))?;
+        publish_committed(self.snapshot.as_ref(), config_revision).await?;
+        Ok(ClientKeyMutation {
+            config_revision,
+            record: None,
+            id,
+        })
+    }
+}
+
+fn map_client_key_write_error(error: AdminStoreError) -> AdminError {
+    match error.kind() {
+        AdminStoreErrorKind::DuplicateName => AdminError::conflict("名称已存在"),
+        AdminStoreErrorKind::Conflict => AdminError::conflict("API Key 已存在，请使用其他密钥"),
+        _ => map_store_error(error, "client API key"),
+    }
+}
+
+fn validate_cursor(query: &ClientKeyListQuery) -> Result<(), AdminError> {
+    let Some(cursor) = &query.cursor else {
+        return Ok(());
+    };
+    if cursor.sort != query.sort {
+        return Err(AdminError::invalid(
+            "Client API Key 游标排序与查询条件不一致",
+        ));
+    }
+    let matches = matches!(
+        (cursor.sort.field, &cursor.value),
+        (ClientKeySortField::Name, ClientKeyCursorValue::Name(value)) if !value.trim().is_empty()
+    ) || matches!(
+        (cursor.sort.field, &cursor.value),
+        (
+            ClientKeySortField::Enabled,
+            ClientKeyCursorValue::Enabled(_)
+        ) | (
+            ClientKeySortField::CreatedAt,
+            ClientKeyCursorValue::CreatedAt(_)
+        ) | (
+            ClientKeySortField::LastUsedAt,
+            ClientKeyCursorValue::LastUsedAt(_)
+        )
+    );
+    if matches {
+        Ok(())
+    } else {
+        Err(AdminError::invalid("Client API Key 游标不合法"))
+    }
+}
+
+// 原生与插件创建共用相同的密钥生成规则。
+pub(super) fn generate_key() -> String {
+    let mut bytes = [0_u8; 32];
+    OsRng.fill_bytes(&mut bytes);
+    format!("sk_{}", URL_SAFE_NO_PAD.encode(bytes))
+}

backend/crates/gateway-admin/src/use_case/credentials/flow.rs

@@ -0,0 +1,251 @@
+//! 已冻结 Provider 的凭据工作流；Admin 保持事务、审计与发布的唯一所有权。
+
+use std::sync::Arc;
+
+use gateway_core::runtime::SnapshotControl;
+
+use crate::{
+    model::{
+        AdminError,
+        provider_credentials::{
+            AuthorizationCommitResult, AuthorizationReceiptKey, AuthorizationStarted,
+            CompleteAuthorization, CredentialDeletion, CredentialDeletionResult,
+            CredentialImportCommit, CredentialImportResult, CredentialMutationResult,
+            ImportCredentials, PrepareCredentialImport, PrepareCredentialRotation,
+            RotateCredential, StartAuthorization,
+        },
+    },
+    ports::{provider::ProviderAdmin, store::AccountStore},
+};
+
+use super::super::{
+    commit_authorization, commit_credential_rotation, delete_credentials, map_provider_error,
+    map_store_error, pending_authorization, publish_committed,
+    publish_credentials_and_observe_quota, required_credential, validate_authorization_commit,
+    validate_prepared_import, validate_prepared_rotation,
+};
+
+pub struct ProviderCredentials {
+    provider: Arc<dyn ProviderAdmin>,
+    accounts: Arc<dyn AccountStore>,
+    proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+}
+
+impl ProviderCredentials {
+    #[must_use]
+    pub(crate) fn new(
+        provider: Arc<dyn ProviderAdmin>,
+        accounts: Arc<dyn AccountStore>,
+        proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        Self {
+            provider,
+            accounts,
+            proxies,
+            snapshot,
+        }
+    }
+    pub async fn import_document(
+        &self,
+        command: ImportCredentials,
+    ) -> Result<CredentialImportResult, AdminError> {
+        let context = command.context;
+        let proxy_reservation = super::super::import_proxy_binding(
+            self.proxies.as_ref(),
+            command.outbound_proxy_id.as_deref(),
+        )
+        .await?;
+        let outbound_proxy = proxy_reservation
+            .as_ref()
+            .map(|reservation| reservation.binding.clone());
+        let prepared = self
+            .provider
+            .prepare_import(PrepareCredentialImport {
+                default_outbound_proxy: outbound_proxy
+                    .as_ref()
+                    .map(|binding| binding.proxy.clone()),
+                document: command.document,
+            })
+            .await
+            .map_err(|error| map_provider_error(error, "provider credential import"))?;
+        validate_prepared_import(
+            self.provider.provider_kind(),
+            &prepared,
+            "provider credential import",
+        )?;
+        let result = self
+            .accounts
+            .commit_credential_import(
+                CredentialImportCommit {
+                    outbound_proxy,
+                    prepared,
+                    settings: command.settings,
+                },
+                &context,
+            )
+            .await
+            .map_err(|error| map_store_error(error, "provider credential import"))?;
+        drop(proxy_reservation);
+        publish_credentials_and_observe_quota(
+            &self.provider,
+            self.snapshot.as_ref(),
+            result.config_revision,
+            &result.credential_ids,
+            &context.request_id,
+        )
+        .await?;
+        Ok(result)
+    }
+
+    pub async fn start_authorization(
+        &self,
+        command: StartAuthorization,
+    ) -> Result<AuthorizationStarted, AdminError> {
+        let pending = pending_authorization(
+            self.accounts.as_ref(),
+            self.proxies.as_ref(),
+            self.provider.provider_kind(),
+            &command,
+            "provider credential",
+        )
+        .await?;
+        self.provider
+            .start_authorization(pending)
+            .await
+            .map_err(|error| map_provider_error(error, "provider authorization"))
+    }
+
+    pub async fn rotate(
+        &self,
+        command: RotateCredential,
+    ) -> Result<CredentialMutationResult, AdminError> {
+        let context = command.mutation.context;
+        let account_id = command.mutation.account_id;
+        if command
+            .settings
+            .as_ref()
+            .is_some_and(|settings| settings.account_id != account_id.as_str())
+        {
+            return Err(AdminError::invalid("凭据和账号设置的目标不一致"));
+        }
+        let disable_account = command
+            .settings
+            .as_ref()
+            .is_some_and(|settings| !settings.enabled);
+        let details = required_credential(
+            self.accounts.as_ref(),
+            self.provider.provider_kind(),
+            &account_id,
+            "provider credential rotation",
+        )
+        .await?;
+        let account = details.credential;
+        let prepared = self
+            .provider
+            .prepare_rotation(PrepareCredentialRotation {
+                account: account.clone(),
+                provider_material: command.provider_material,
+            })
+            .await
+            .map_err(|error| map_provider_error(error, "provider credential rotation"))?;
+        validate_prepared_rotation(&account, &prepared, "provider credential rotation")?;
+        let result = commit_credential_rotation(
+            self.accounts.as_ref(),
+            prepared,
+            command.settings,
+            &context,
+            "provider credential rotation",
+        )
+        .await?;
+        if disable_account {
+            self.provider.account_unavailable(&account_id).await;
+        }
+        self.provider
+            .account_facts_changed(std::slice::from_ref(&result.account_id))
+            .await;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+
+    pub async fn delete(
+        &self,
+        command: CredentialDeletion,
+    ) -> Result<CredentialDeletionResult, AdminError> {
+        let result = delete_credentials(
+            self.accounts.as_ref(),
+            self.provider.as_ref(),
+            command,
+            "provider credential",
+        )
+        .await?;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+}
+
+impl super::CredentialsService {
+    pub async fn complete_authorization(
+        &self,
+        kind: &gateway_core::routing::ProviderKind,
+        mut command: CompleteAuthorization,
+    ) -> Result<CredentialMutationResult, AdminError> {
+        let context = command.context.clone();
+        let key = AuthorizationReceiptKey::new(kind.clone(), &command.flow_id, &context)?;
+        if let Some(result) = self
+            .accounts
+            .authorization_receipt(&key)
+            .await
+            .map_err(|error| map_store_error(error, "authorization receipt"))?
+        {
+            publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+            return Ok(result);
+        }
+        let scope = self.for_provider(kind)?;
+        let provider = &scope.provider;
+        let settings = command.settings.take();
+        let prepared = provider
+            .complete_authorization(command)
+            .await
+            .map_err(|error| map_provider_error(error, "provider authorization"))?;
+        let prepared =
+            validate_authorization_commit(kind, &context, prepared, "provider authorization")
+                .await?;
+        let result = commit_authorization(
+            self.accounts.as_ref(),
+            prepared,
+            key,
+            settings,
+            &context,
+            "provider authorization",
+        )
+        .await?;
+        let result = self
+            .publish_authorization(provider, result, &context.request_id)
+            .await?;
+        Ok(result)
+    }
+
+    async fn publish_authorization(
+        &self,
+        provider: &Arc<dyn ProviderAdmin>,
+        outcome: AuthorizationCommitResult,
+        request_id: &str,
+    ) -> Result<CredentialMutationResult, AdminError> {
+        let result = outcome.result;
+        if outcome.newly_committed {
+            publish_credentials_and_observe_quota(
+                provider,
+                self.snapshot.as_ref(),
+                result.config_revision,
+                std::slice::from_ref(&result.account_id),
+                request_id,
+            )
+            .await?;
+        } else {
+            publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        }
+        Ok(result)
+    }
+}